Manifest Pluginu

Ta strona dotyczy wyłącznie natywnego manifestu Plugin OpenClaw.

Zgodne układy pakietów opisuje strona Pakiety Plugin.

Zgodne formaty pakietów używają innych plików manifestu:

• Pakiet Codex: .codex-plugin/plugin.json
• Pakiet Claude: .claude-plugin/plugin.json albo domyślny układ komponentu Claude bez manifestu
• Pakiet Cursor: .cursor-plugin/plugin.json

OpenClaw automatycznie wykrywa także te układy pakietów, ale nie są one walidowane względem schematu openclaw.plugin.json opisanego tutaj.

W przypadku zgodnych pakietów OpenClaw obecnie odczytuje metadane pakietu oraz zadeklarowane korzenie Skills, korzenie poleceń Claude, domyślne ustawienia settings.json pakietu Claude, domyślne ustawienia LSP pakietu Claude i obsługiwane pakiety hooków, gdy układ odpowiada oczekiwaniom środowiska uruchomieniowego OpenClaw.

Każdy natywny Plugin OpenClaw musi dostarczać plik openclaw.plugin.json w katalogu głównym Plugin. OpenClaw używa tego manifestu do walidacji konfiguracji bez wykonywania kodu Plugin. Brakujące albo nieprawidłowe manifesty są traktowane jako błędy Plugin i blokują walidację konfiguracji.

Zobacz pełny przewodnik po systemie Plugin: Plugin. Informacje o natywnym modelu możliwości i aktualne wskazówki dotyczące zgodności zewnętrznej: Model możliwości.

Co robi ten plik

openclaw.plugin.json to metadane, które OpenClaw odczytuje zanim załaduje kod Plugin. Wszystko poniżej musi dać się sprawdzić wystarczająco tanio bez uruchamiania środowiska uruchomieniowego Plugin.

Używaj go do:

• tożsamości Plugin, walidacji konfiguracji i wskazówek dla interfejsu konfiguracji
• metadanych uwierzytelniania, onboardingu i konfiguracji początkowej (alias, automatyczne włączenie, zmienne środowiskowe dostawcy, wybory uwierzytelniania)
• wskazówek aktywacji dla powierzchni płaszczyzny sterowania
• skróconej własności rodzin modeli
• statycznych migawek własności możliwości (contracts)
• metadanych runnera QA, które współdzielony host openclaw qa może sprawdzić
• metadanych konfiguracji specyficznych dla kanału, scalanych z katalogiem i powierzchniami walidacji

Nie używaj go do: rejestrowania zachowania środowiska uruchomieniowego, deklarowania punktów wejścia kodu ani metadanych instalacji npm. Te należą do kodu Plugin i 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"],  "providerAuthEnvVars": {    "openrouter": ["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"      }    }  }}

Odniesienie do pól najwyższego poziomu

Odniesienie do metadanych dostawcy generowania

Pola metadanych dostawcy generowania opisują statyczne sygnały uwierzytelniania dla dostawców zadeklarowanych w pasującej liście contracts.*GenerationProviders. OpenClaw odczytuje te pola przed załadowaniem runtime dostawcy, aby narzędzia core mogły ustalić, czy dostawca generowania jest dostępny, bez importowania każdego pluginu dostawcy.

Używaj tych pól wyłącznie do tanich, deklaratywnych faktów. Transport, przekształcenia żądań, odświeżanie tokenów, walidacja poświadczeń i faktyczne zachowanie generowania pozostają w runtime 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żda kontrola mode obsługuje:

Każdy wpis authSignals obsługuje:

Każda kontrola providerBaseUrl obsługuje:

Odniesienie do metadanych narzędzi

toolMetadata używa tych samych kształtów configSignals i authSignals co metadane dostawcy generowania, indeksowanych nazwą narzędzia. contracts.tools deklaruje własność. toolMetadata deklaruje tanie dowody dostępności, aby OpenClaw mógł uniknąć importowania runtime pluginu tylko po to, by fabryka jego narzędzia zwróciła null.

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

Jeśli narzędzie nie ma toolMetadata, OpenClaw zachowuje istniejące zachowanie i ładuje plugin właściciela, gdy kontrakt narzędzia pasuje do polityki. Dla narzędzi na gorącej ścieżce, których fabryka zależy od uwierzytelniania/konfiguracji, autorzy pluginów powinni deklarować toolMetadata zamiast powodować, że core importuje runtime, aby zapytać.

Odniesienie do providerAuthChoices

Każdy wpis providerAuthChoices opisuje jedną opcję onboardingu lub uwierzytelniania. OpenClaw odczytuje to przed załadowaniem runtime dostawcy. Listy konfiguracji dostawcy używają tych wyborów z manifestu, wyborów konfiguracji wyprowadzonych z deskryptora oraz metadanych katalogu instalacyjnego bez ładowania runtime dostawcy.

Odniesienie do commandAliases

Użyj commandAliases, gdy plugin jest właścicielem nazwy polecenia runtime, którą użytkownicy mogą błędnie umieścić w plugins.allow lub spróbować uruchomić jako główne polecenie CLI. OpenClaw używa tych metadanych do diagnostyki bez importowania kodu runtime pluginu.

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

Dokumentacja activation

Użyj activation, gdy plugin może tanio zadeklarować, które zdarzenia płaszczyzny sterowania powinny uwzględniać go w planie aktywacji/ładowania.

Ten blok to metadane planisty, a nie API cyklu życia. Nie rejestruje zachowania runtime, nie zastępuje register(...) i nie obiecuje, że kod pluginu został już wykonany. Planista aktywacji używa tych pól do zawężenia kandydatów na pluginy przed powrotem do istniejących metadanych własności w manifeście, takich jak providers, channels, commandAliases, setup.providers, contracts.tools i hooki.

Preferuj najwęższe metadane, które już opisują własność. Używaj providers, channels, commandAliases, deskryptorów setupu lub contracts, gdy te pola wyrażają relację. Używaj activation dla dodatkowych wskazówek planisty, których nie da się reprezentować przez te pola własności. Używaj najwyższego poziomu cliBackends dla aliasów runtime CLI, takich jak claude-cli, codex-cli lub google-gemini-cli; activation.onAgentHarnesses służy tylko do osadzonych identyfikatorów uprzęży agentów, które nie mają już pola własności.

Ten blok zawiera wyłącznie metadane. Nie rejestruje zachowania runtime i nie zastępuje register(...), setupEntry ani innych punktów wejścia runtime/pluginu. Obecni konsumenci używają go jako wskazówki zawężającej przed szerszym ładowaniem pluginów, więc brak metadanych aktywacji poza startem zwykle kosztuje tylko wydajność; nie powinien zmieniać poprawności, dopóki nadal istnieją fallbacki własności manifestu.

Każdy plugin powinien celowo ustawić activation.onStartup. Ustaw go na true tylko wtedy, gdy plugin musi działać podczas startu Gateway. Ustaw go na false, gdy plugin jest bezczynny przy starcie i powinien ładować się tylko z węższych wyzwalaczy. Pominięcie onStartup nie powoduje już niejawnego ładowania pluginu przy starcie; używaj jawnych metadanych aktywacji dla startu, kanału, konfiguracji, uprzęży agenta, pamięci lub innych węższych wyzwalaczy aktywacji.

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

Obecni konsumenci na żywo:

• planowanie startu Gateway używa activation.onStartup do jawnego importu przy starcie
• planowanie CLI wyzwalane poleceniem wraca do starszych commandAliases[].cliCommand lub commandAliases[].name
• planowanie startu runtime agenta używa activation.onAgentHarnesses dla osadzonych uprzęży oraz najwyższego poziomu cliBackends[] dla aliasów runtime CLI
• planowanie setupu/kanału wyzwalane kanałem wraca do starszej własności channels[], gdy brakuje jawnych metadanych aktywacji kanału
• planowanie pluginów przy starcie używa activation.onConfigPaths dla głównych powierzchni konfiguracji niebędących kanałami, takich jak blok browser dołączonego pluginu przeglądarki
• planowanie setupu/runtime wyzwalane dostawcą wraca do starszej własności providers[] i najwyższego poziomu cliBackends[], gdy brakuje jawnych metadanych aktywacji dostawcy

Diagnostyka planisty może odróżniać jawne wskazówki aktywacji od fallbacku własności manifestu. Na przykład activation-command-hint oznacza, że dopasowano activation.onCommands, a manifest-command-alias oznacza, że planista użył zamiast tego własności commandAliases. Te etykiety powodów są przeznaczone dla diagnostyki hosta i testów; autorzy pluginów powinni nadal deklarować metadane, które najlepiej opisują własność.

Dokumentacja qaRunners

Użyj qaRunners, gdy plugin wnosi jeden lub więcej runnerów transportu pod wspólnym katalogiem głównym openclaw qa. Utrzymuj te metadane tanie i statyczne; runtime pluginu nadal jest właścicielem rzeczywistej rejestracji CLI przez lekką powierzchnię runtime-api.ts, która eksportuje qaRunnerCliRegistrations.

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

Dokumentacja setup

Użyj setup, gdy powierzchnie konfiguracji i onboardingu potrzebują tanich metadanych należących do pluginu, zanim runtime zostanie załadowany.

{  "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  }}

Najwyższy poziom cliBackends pozostaje prawidłowy i nadal opisuje backendy wnioskowania CLI. setup.cliBackends to specyficzna dla setupu powierzchnia deskryptora dla przepływów płaszczyzny sterowania/setupu, które powinny pozostać wyłącznie metadanymi.

Gdy są obecne, setup.providers i setup.cliBackends są preferowaną powierzchnią wyszukiwania z deskryptorem na pierwszym miejscu dla odkrywania setupu. Jeśli deskryptor tylko zawęża kandydujący plugin, a setup nadal potrzebuje bogatszych hooków runtime podczas setupu, ustaw requiresRuntime: true i zachowaj setup-api jako zapasową ścieżkę wykonania.

OpenClaw uwzględnia też setup.providers[].envVars w ogólnych wyszukiwaniach uwierzytelniania dostawcy i zmiennych środowiskowych. providerAuthEnvVars pozostaje obsługiwane przez adapter zgodności w oknie wycofywania, ale niedołączone pluginy, które nadal go używają, otrzymują diagnostykę manifestu. Nowe pluginy powinny umieszczać metadane środowiska setupu/statusu w setup.providers[].envVars.

OpenClaw może też wyprowadzać proste wybory setupu z setup.providers[].authMethods, gdy wpis setupu nie jest dostępny albo gdy setup.requiresRuntime: false deklaruje, że runtime setupu jest zbędny. Jawne wpisy providerAuthChoices pozostają preferowane dla niestandardowych etykiet, flag CLI, zakresu onboardingu i metadanych asystenta.

Ustaw requiresRuntime: false tylko wtedy, gdy te deskryptory wystarczają dla powierzchni setupu. OpenClaw traktuje jawne false jako kontrakt wyłącznie deskryptorowy i nie wykona setup-api ani openclaw.setupEntry na potrzeby wyszukiwania setupu. Jeśli plugin wyłącznie deskryptorowy nadal dostarcza jeden z tych wpisów runtime setupu, OpenClaw zgłasza addytywną diagnostykę i nadal go ignoruje. Pominięte requiresRuntime zachowuje starsze zachowanie fallbacku, aby istniejące pluginy, które dodały deskryptory bez tej flagi, nie przestały działać.

Ponieważ wyszukiwanie setupu może wykonywać należący do pluginu kod setup-api, znormalizowane wartości setup.providers[].id i setup.cliBackends[] muszą pozostać unikalne we wszystkich odkrytych pluginach. Niejednoznaczna własność kończy się bezpiecznym niepowodzeniem zamiast wybierania zwycięzcy według kolejności odkrywania.

Gdy runtime setupu faktycznie się wykonuje, diagnostyka rejestru setupu zgłasza rozjazd deskryptora, jeśli setup-api rejestruje dostawcę lub backend CLI, którego deskryptory manifestu nie deklarują, albo jeśli deskryptor nie ma pasującej rejestracji runtime. Te diagnostyki są addytywne i nie odrzucają starszych pluginów.

Dokumentacja setup.providers

authEvidence służy do należących do dostawcy lokalnych znaczników poświadczeń, które można zweryfikować bez ładowania kodu runtime. Te sprawdzenia muszą pozostać tanie i lokalne: bez wywołań sieciowych, bez odczytów z pęku kluczy ani menedżera sekretów, bez poleceń powłoki i bez sond API dostawcy.

Obsługiwane wpisy dowodów:

pola setup

Dokumentacja referencyjna uiHints

uiHints to mapa nazw pól konfiguracji na małe wskazówki renderowania.

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

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

Dokumentacja referencyjna contracts

Używaj contracts tylko do statycznych metadanych własności capability, które OpenClaw może odczytać bez importowania runtime pluginu.

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Każda lista jest opcjonalna:

contracts.embeddedExtensionFactories jest zachowane dla dołączonych fabryk rozszerzeń tylko dla serwera aplikacji Codex. Dołączone transformacje wyników narzędzi powinny deklarować contracts.agentToolResultMiddleware i zamiast tego rejestrować się przez api.registerAgentToolResultMiddleware(...). Zewnętrzne pluginy nie mogą rejestrować middleware wyników narzędzi, ponieważ seam może przepisać dane wyjściowe narzędzi o wysokim zaufaniu, zanim zobaczy je model.

Rejestracje runtime api.registerTool(...) muszą odpowiadać contracts.tools. Wykrywanie narzędzi używa tej listy, aby ładować tylko runtime tych pluginów, które mogą być właścicielami żądanych narzędzi.

Pluginy dostawców, które implementują resolveExternalAuthProfiles, powinny deklarować contracts.externalAuthProviders. Pluginy bez tej deklaracji nadal przechodzą przez przestarzały fallback zgodności, ale ten fallback jest wolniejszy i zostanie usunięty po oknie migracji.

Dołączeni dostawcy embeddingów pamięci powinni deklarować contracts.memoryEmbeddingProviders dla każdego udostępnianego identyfikatora adaptera, w tym wbudowanych adapterów, takich jak local. Samodzielne ścieżki CLI używają tego kontraktu manifestu, aby załadować tylko plugin właścicielski, zanim pełny runtime Gateway zarejestruje dostawców.

Dokumentacja referencyjna mediaUnderstandingProviderMetadata

Używaj mediaUnderstandingProviderMetadata, gdy dostawca rozumienia mediów ma domyślne modele, priorytet fallbacku automatycznego uwierzytelniania lub natywną obsługę dokumentów, których ogólne helpery core potrzebują przed załadowaniem runtime. Klucze muszą być też 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"]    }  }}

Każdy wpis dostawcy może zawierać:

Dokumentacja referencyjna channelConfigs

Używaj channelConfigs, gdy plugin kanału potrzebuje tanich metadanych konfiguracji przed załadowaniem runtime. Wykrywanie konfiguracji/statusu kanału tylko do odczytu może używać tych metadanych bezpośrednio dla skonfigurowanych kanałów zewnętrznych, gdy nie ma dostępnego wpisu setup, albo gdy setup.requiresRuntime: false deklaruje, że runtime konfiguracji jest zbędny.

channelConfigs to metadane manifestu pluginu, a nie nowa sekcja konfiguracji użytkownika najwyższego poziomu. Użytkownicy nadal konfigurują instancje kanałów pod channels.<channel-id>. OpenClaw odczytuje metadane manifestu, aby zdecydować, który plugin jest właścicielem danego skonfigurowanego kanału, zanim wykona się kod runtime pluginu.

Dla 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 też 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ą znać kształtu opcji należących do kanału, dopóki runtime pluginu się nie wykona.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled i nativeSkillsAutoEnabled mogą deklarować statyczne domyślne wartości auto dla sprawdzeń konfiguracji poleceń, które uruchamiają się przed załadowaniem runtime kanału. Dołączone kanały mogą też publikować te same wartości domyślne przez package.json#openclaw.channel.commands obok innych metadanych katalogu kanałów należących do ich 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 Plugin kanału

Użyj preferOver, gdy Twój Plugin jest preferowanym właścicielem identyfikatora kanału, który może również dostarczać inny Plugin. Typowe przypadki to zmieniony identyfikator Plugin, samodzielny Plugin zastępujący dołączony Plugin albo utrzymywany fork, który zachowuje ten sam identyfikator kanału dla zgodności konfiguracji.

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

Gdy skonfigurowane jest channels.chat, OpenClaw uwzględnia zarówno identyfikator kanału, jak i identyfikator preferowanego Plugin. 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 runtime, aby jeden Plugin był właścicielem kanału i jego narzędzi. Jawny wybór użytkownika nadal wygrywa: jeśli użytkownik jawnie włączy oba Plugin, OpenClaw zachowuje ten wybór i zgłasza diagnostykę zduplikowanych kanałów/narzędzi zamiast po cichu zmieniać żądany zestaw Plugin.

Ogranicz preferOver do identyfikatorów Plugin, które naprawdę mogą dostarczać 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ć Twój Plugin dostawcy na podstawie skróconych identyfikatorów modeli, takich jak gpt-5.5 lub claude-sonnet-4.6, zanim załaduje się runtime Plugin.

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

OpenClaw stosuje tę kolejność pierwszeństwa:

• jawne referencje provider/model używają metadanych manifestu providers właściciela
• modelPatterns mają pierwszeństwo przed modelPrefixes
• jeśli pasują zarówno jeden niedołączony Plugin, jak i jeden dołączony Plugin, wygrywa niedołączony Plugin
• pozostała niejednoznaczność jest ignorowana, dopóki użytkownik lub konfiguracja nie określi dostawcy

Pola:

Dokumentacja modelCatalog

Użyj modelCatalog, gdy OpenClaw powinien znać metadane modeli dostawcy przed załadowaniem runtime Plugin. To źródło należące do manifestu dla stałych wierszy katalogu, aliasów dostawców, reguł wyciszania i trybu wykrywania. Odświeżanie runtime nadal należy do kodu runtime dostawcy, ale manifest informuje rdzeń, kiedy runtime jest wymagany.

{  "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łasności dostawcy na potrzeby planowania katalogu modeli. Cele aliasów muszą być dostawcami najwyższego poziomu należącymi do tego samego Plugin. Gdy lista filtrowana według dostawcy używa aliasu, OpenClaw może odczytać manifest właściciela i zastosować nadpisania API/bazowego URL aliasu bez ładowania runtime dostawcy. Aliasy nie rozszerzają niefiltrowanych list katalogu; szerokie listy emitują tylko wiersze kanonicznego dostawcy właściciela.

suppressions zastępuje stary hak runtime dostawcy suppressBuiltInModel. Wpisy wyciszeń są honorowane tylko wtedy, gdy dostawca należy do Plugin albo jest zadeklarowany jako klucz modelCatalog.aliases, który wskazuje posiadanego dostawcę. Haki wyciszania runtime nie są już wywoływane podczas rozwiązywania modelu.

Pola dostawcy:

Pola modelu:

Pola wyciszenia:

Nie umieszczaj danych dostępnych wyłącznie w czasie wykonywania w modelCatalog. Używaj static tylko wtedy, gdy wiersze manifestu są na tyle kompletne, że powierzchnie listy filtrowanej według dostawcy i selektora mogą pominąć odkrywanie rejestru/czasu wykonywania. Używaj refreshable, gdy wiersze manifestu są przydatnymi nasionami lub uzupełnieniami możliwymi do wylistowania, ale odświeżenie/pamięć podręczna może później dodać więcej wierszy; wiersze odświeżalne same w sobie nie są autorytatywne. Używaj runtime, gdy OpenClaw musi załadować runtime dostawcy, aby poznać listę.

Informacje referencyjne modelIdNormalization

Używaj modelIdNormalization do taniego, kontrolowanego przez dostawcę czyszczenia identyfikatorów modeli, które musi nastąpić przed załadowaniem runtime dostawcy. Dzięki temu aliasy, takie jak krótkie nazwy modeli, lokalne dla dostawcy starsze identyfikatory oraz reguły prefiksów proxy, pozostają w manifeście właścicielskiego pluginu 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:

Informacje referencyjne providerEndpoints

Używaj providerEndpoints do klasyfikacji punktów końcowych, którą ogólna polityka żądań musi znać przed załadowaniem runtime dostawcy. Core nadal jest właścicielem znaczenia każdej endpointClass; manifesty pluginów są właścicielami metadanych hosta i bazowego URL.

Pola punktu końcowego:

Informacje referencyjne providerRequest

Używaj providerRequest do tanich metadanych zgodności żądań, których ogólna polityka żądań potrzebuje bez ładowania runtime dostawcy. Przepisywanie ładunku specyficzne dla zachowania trzymaj w hookach runtime dostawcy albo we współdzielonych helperach rodziny dostawców.

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

Pola dostawcy:

Informacje referencyjne modelPricing

Używaj modelPricing, gdy dostawca potrzebuje zachowania wyceny w płaszczyźnie kontroli przed załadowaniem runtime. Pamięć podręczna wyceny Gateway odczytuje te metadane bez importowania kodu runtime dostawcy.

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

Pola dostawcy:

Pola źródłowe:

Indeks dostawców OpenClaw

Indeks dostawców OpenClaw to należące do OpenClaw metadane podglądu dla dostawców, których pluginy mogą nie być jeszcze zainstalowane. Nie jest częścią manifestu pluginu. Manifesty pluginów pozostają autorytetem zainstalowanego pluginu. Indeks dostawców jest wewnętrznym kontraktem awaryjnym, z którego będą korzystać przyszłe powierzchnie instalowalnych dostawców i selektora modeli przed instalacją, gdy plugin dostawcy nie jest zainstalowany.

Kolejność autorytetu katalogu:

1. Konfiguracja użytkownika.
2. modelCatalog manifestu zainstalowanego pluginu.
3. Pamięć podręczna katalogu modeli z jawnego odświeżenia.
4. Wiersze podglądu Indeksu dostawców OpenClaw.

Indeks dostawców nie może zawierać sekretów, stanu włączenia, hooków runtime ani aktywnych danych modeli specyficznych dla konta. Jego katalogi podglądu używają tego samego kształtu wiersza dostawcy modelCatalog co manifesty pluginów, ale powinny pozostawać ograniczone do stabilnych metadanych wyświetlania, chyba że pola adaptera runtime, takie jak api, baseUrl, wycena lub flagi zgodności, są celowo utrzymywane w zgodności z manifestem zainstalowanego pluginu. Dostawcy z aktywnym odkrywaniem /models powinni zapisywać odświeżone wiersze przez jawną ścieżkę pamięci podręcznej katalogu modeli zamiast sprawiać, że zwykłe listowanie lub onboarding wywołują API dostawców.

Wpisy Indeksu dostawców mogą też zawierać metadane instalowalnych pluginów dla dostawców, których plugin został przeniesiony poza core albo w inny sposób nie jest jeszcze zainstalowany. Te metadane odzwierciedlają wzorzec katalogu kanałów: nazwa pakietu, spec instalacji npm, oczekiwana integralność oraz tanie etykiety wyboru uwierzytelniania wystarczą, aby pokazać instalowalną opcję konfiguracji. Po zainstalowaniu pluginu jego manifest wygrywa, a wpis Indeksu dostawców jest ignorowany dla tego dostawcy.

Starsze klucze możliwości najwyższego poziomu są przestarzałe. Użyj openclaw doctor --fix, aby przenieść speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders i webSearchProviders pod contracts; zwykłe ładowanie manifestu nie traktuje już tych pól najwyższego poziomu jako własności możliwości.

Manifest kontra package.json

Te dwa pliki pełnią różne funkcje:

Jeśli nie masz pewności, gdzie powinien znaleźć się element metadanych, użyj tej reguły:

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

Pola package.json wpływające na odkrywanie

Niektóre metadane pluginu sprzed uruchomienia celowo znajdują się w package.json pod blokiem openclaw zamiast w openclaw.plugin.json. openclaw.bundle i openclaw.bundle.json nie są kontraktami pluginu OpenClaw; natywne pluginy muszą używać openclaw.plugin.json oraz obsługiwanych pól package.json#openclaw poniżej.

Ważne przykłady:

Metadane manifestu decydują, które wybory dostawcy/kanału/konfiguracji pojawiają się we wdrażaniu przed załadowaniem środowiska uruchomieniowego. package.json#openclaw.install mówi wdrażaniu, jak pobrać lub włączyć ten plugin, gdy użytkownik wybierze jedną z tych opcji. Nie przenoś wskazówek instalacji do openclaw.plugin.json.

openclaw.install.minHostVersion jest egzekwowane podczas instalacji i ładowania rejestru manifestów dla źródeł pluginów niedołączonych. Nieprawidłowe wartości są odrzucane; nowsze, ale prawidłowe wartości pomijają zewnętrzne pluginy na starszych hostach. Dołączone pluginy źródłowe są uznawane za współwersjonowane z checkoutem hosta.

Oficjalne metadane instalacji na żądanie powinny używać clawhubSpec, gdy plugin jest opublikowany w ClawHub; wdrażanie traktuje to jako preferowane zdalne źródło i zapisuje fakty artefaktu ClawHub po instalacji. npmSpec pozostaje zgodnościową opcją awaryjną dla pakietów, które jeszcze nie przeniosły się do ClawHub.

Dokładne przypięcie wersji npm już znajduje się w npmSpec, na przykład "npmSpec": "@wecom/[email protected]". Oficjalne wpisy katalogu zewnętrznego powinny łączyć dokładne specyfikacje z expectedIntegrity, aby przepływy aktualizacji kończyły się zamknięciem w razie niezgodności, jeśli pobrany artefakt npm nie pasuje już do przypiętego wydania. Interaktywne wdrażanie nadal oferuje zaufane specyfikacje npm z rejestru, w tym same nazwy pakietów i dist-tagi, dla zgodności. Diagnostyka katalogu potrafi rozróżniać źródła dokładne, płynne, przypięte integralnością, bez integralności, z niezgodnością nazwy pakietu i z nieprawidłowym wyborem domyślnym. Ostrzega też, gdy expectedIntegrity jest obecne, ale nie ma prawidłowego źródła npm, które może przypiąć. Gdy expectedIntegrity jest obecne, przepływy instalacji/aktualizacji je egzekwują; gdy jest pominięte, rozwiązanie z rejestru jest zapisywane bez przypięcia integralności.

Pluginy kanałów powinny udostępniać openclaw.setupEntry, gdy skany stanu, listy kanałów lub SecretRef muszą identyfikować skonfigurowane konta bez ładowania pełnego środowiska uruchomieniowego. Punkt wejścia konfiguracji powinien ujawniać metadane kanału oraz bezpieczne dla konfiguracji adaptery config, stanu i sekretów; klientów sieciowych, nasłuchiwacze Gateway i transportowe środowiska uruchomieniowe trzymaj 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 sprawić, że uciekająca ścieżka openclaw.extensions stanie się ładowalna.

openclaw.install.allowInvalidConfigRecovery jest celowo wąskie. Nie sprawia, że dowolnie uszkodzone konfiguracje stają się instalowalne. Obecnie pozwala tylko przepływom instalacji odzyskać się po konkretnych przestarzałych awariach aktualizacji dołączonego pluginu, takich jak brakująca ścieżka dołączonego pluginu lub przestarzały wpis channels.<id> dla 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 kontrolera:

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

Używaj ich, gdy przepływy konfiguracji, doctor, stanu lub obecności tylko do odczytu potrzebują taniego sondowania uwierzytelnienia typu tak/nie przed załadowaniem pełnego pluginu kanału. Utrwalony stan uwierzytelnienia nie jest skonfigurowanym stanem kanału: nie używaj tych metadanych do automatycznego włączania pluginów, naprawiania zależności środowiska uruchomieniowego ani decydowania, czy środowisko uruchomieniowe kanału powinno się załadować. Eksport docelowy powinien być małą funkcją, która czyta wyłącznie utrwalony stan; nie kieruj jej przez pełny barrel środowiska uruchomieniowego kanału.

openclaw.channel.configuredState ma ten sam kształt dla tanich kontroli skonfigurowania tylko przez env:

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

Używaj ich, gdy kanał może odpowiedzieć na stan skonfigurowania na podstawie env lub innych niewielkich danych wejściowych poza środowiskiem uruchomieniowym. Jeśli kontrola wymaga pełnego rozwiązywania konfiguracji lub rzeczywistego środowiska uruchomieniowego kanału, zachowaj tę logikę zamiast tego w hooku pluginu config.hasConfiguredState.

Pierwszeństwo wykrywania (zduplikowane identyfikatory pluginów)

OpenClaw wykrywa pluginy z kilku źródeł głównych (dołączone, globalna instalacja, workspace, jawne ścieżki wybrane w konfiguracji). Jeśli dwa odkrycia współdzielą ten sam id, zachowywany jest tylko 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 w konfiguracji — ścieżka jawnie przypięta w plugins.entries.<id>
2. Dołączony — pluginy dostarczane z OpenClaw
3. Globalna instalacja — pluginy zainstalowane w globalnym katalogu pluginów OpenClaw
4. Workspace — pluginy wykryte względem bieżącego workspace

Konsekwencje:

• Sforkowana lub przestarzała kopia dołączonego pluginu znajdująca się w workspace nie przesłoni dołączonej kompilacji.
• Aby faktycznie zastąpić dołączony plugin lokalnym, przypnij go przez plugins.entries.<id>, aby wygrał priorytetem zamiast polegać na wykrywaniu w workspace.
• Odrzucenia duplikatów są logowane, aby diagnostyka Doctor i uruchamiania mogła wskazać odrzuconą kopię.
• Nadpisania duplikatów wybranych w konfiguracji są w diagnostyce opisywane jako jawne nadpisania, ale nadal ostrzegają, aby przestarzałe forki i przypadkowe przesłonięcia pozostawały widoczne.

Wymagania JSON Schema

• Każdy plugin musi dostarczać JSON Schema, nawet jeśli nie akceptuje konfiguracji.
• Pusty schemat jest dopuszczalny (na przykład { "type": "object", "additionalProperties": false }).
• Schematy są walidowane podczas odczytu/zapisu konfiguracji, nie w czasie działania.
• Podczas rozszerzania lub forkowania dołączonego pluginu o nowe klucze konfiguracji zaktualizuj jednocześnie configSchema tego pluginu w openclaw.plugin.json. 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 przez manifest pluginu.
• plugins.entries.<id>, plugins.allow, plugins.deny i plugins.slots.* muszą odwoływać się do wykrywalnych identyfikatorów pluginów. Nieznane identyfikatory są błędami.
• Jeśli plugin jest zainstalowany, ale ma uszkodzony lub brakujący manifest albo schemat, walidacja kończy się niepowodzeniem, a Doctor zgłasza błąd pluginu.
• Jeśli konfiguracja pluginu istnieje, ale plugin jest wyłączony, konfiguracja jest zachowywana, a ostrzeżenie pojawia się w Doctor i logach.

Zobacz Dokumentację konfiguracji, aby poznać pełny schemat plugins.*.

Uwagi

• Manifest jest wymagany dla natywnych pluginów OpenClaw, w tym ładowanych z lokalnego systemu plików. Runtime nadal ładuje moduł pluginu osobno; manifest służy tylko do wykrywania i walidacji.
• Natywne manifesty są parsowane za pomocą JSON5, więc komentarze, końcowe przecinki i klucze bez cudzysłowów są akceptowane, o ile końcowa wartość nadal jest obiektem.
• Loader manifestów odczytuje tylko udokumentowane pola manifestu. Unikaj własnych kluczy najwyższego poziomu.
• channels, providers, cliBackends i skills można pominąć, gdy plugin ich nie potrzebuje.
• providerCatalogEntry musi pozostać lekkie i nie powinno importować rozległego kodu runtime; używaj go do statycznych metadanych katalogu providerów lub wąskich deskryptorów wykrywania, a nie do wykonywania w czasie obsługi żądania. providerDiscoveryEntry to starsza pisownia i nadal działa dla istniejących pluginów.
• Wyłączne rodzaje pluginów są wybierane przez plugins.slots.*: kind: "memory" przez plugins.slots.memory, kind: "context-engine" przez plugins.slots.contextEngine (domyślnie legacy).
• Zadeklaruj wyłączny rodzaj pluginu w tym manifeście. OpenClawPluginDefinition.kind w punkcie wejścia runtime jest przestarzałe i pozostaje tylko jako awaryjna warstwa zgodności dla starszych pluginów.
• Metadane zmiennych środowiskowych (setup.providers[].envVars, przestarzałe providerAuthEnvVars i channelEnvVars) mają wyłącznie charakter deklaratywny. Status, audyt, walidacja dostarczania Cron i inne powierzchnie tylko do odczytu nadal stosują zaufanie do pluginu oraz obowiązującą politykę aktywacji, zanim potraktują zmienną środowiskową jako skonfigurowaną.
• Metadane kreatora runtime wymagające kodu providera opisano w hookach runtime providera.
• Jeśli Twój plugin zależy od modułów natywnych, udokumentuj kroki budowania oraz wszelkie wymagania allowlist menedżera pakietów (na przykład pnpm allow-build-scripts + pnpm rebuild <package>).

Powiązane