Plugins

Маніфест Plugin

Ця сторінка стосується лише нативного маніфесту Plugin OpenClaw.

Сумісні структури комплектів див. у комплектах Plugin.

Сумісні формати комплектів використовують інші файли маніфестів:

Комплект Codex: .codex-plugin/plugin.json
Комплект Claude: .claude-plugin/plugin.json або типова структура компонентів Claude без маніфесту
Комплект Cursor: .cursor-plugin/plugin.json

OpenClaw також автоматично виявляє ці структури комплектів, але вони не перевіряються за схемою openclaw.plugin.json, описаною тут.

Для сумісних комплектів OpenClaw наразі зчитує метадані комплекту, а також оголошені корені skill, корені команд Claude, типові значення settings.json комплекту Claude, типові значення LSP комплекту Claude і підтримувані набори hook, коли структура відповідає очікуванням середовища виконання OpenClaw.

Кожен нативний Plugin OpenClaw має постачати файл openclaw.plugin.json у корені Plugin. OpenClaw використовує цей маніфест для перевірки конфігурації без виконання коду Plugin. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують перевірку конфігурації.

Див. повний посібник із системи Plugin: Plugins. Про нативну модель можливостей і поточні настанови щодо зовнішньої сумісності: Модель можливостей.

Що робить цей файл

openclaw.plugin.json — це метадані, які OpenClaw читає до завантаження вашого коду Plugin. Усе нижче має бути достатньо дешевим для перевірки без запуску середовища виконання Plugin.

Використовуйте його для:

ідентичності Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації
метаданих автентифікації, онбордингу та налаштування (псевдонім, автоматичне ввімкнення, env vars провайдера, варіанти автентифікації)
підказок активації для поверхонь control-plane
скороченого володіння сімейством моделей
статичних знімків володіння можливостями (contracts)
метаданих запуску QA, які спільний хост openclaw qa може перевіряти
метаданих конфігурації для окремих каналів, об’єднаних у поверхні каталогу та перевірки

Не використовуйте його для: реєстрації поведінки середовища виконання, оголошення точок входу коду або метаданих встановлення npm. Їхнє місце — у вашому коді Plugin і package.json.

Мінімальний приклад

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

Розширений приклад

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

Довідник полів верхнього рівня

Поле	Обов’язкове	Тип	Що означає
`id`	Так	`string`	Канонічний ідентифікатор плагіна. Це ідентифікатор, що використовується в `plugins.entries.<id>`.
`configSchema`	Так	`object`	Вбудована JSON Schema для конфігурації цього плагіна.
`enabledByDefault`	Ні	`true`	Позначає вбудований плагін як увімкнений за замовчуванням. Пропустіть його або встановіть будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим за замовчуванням.
`enabledByDefaultOnPlatforms`	Ні	`string[]`	Позначає вбудований плагін як увімкнений за замовчуванням лише на перелічених платформах Node.js, наприклад `["darwin"]`. Явна конфігурація усе одно має пріоритет.
`legacyPluginIds`	Ні	`string[]`	Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора плагіна.
`autoEnableWhenConfiguredProviders`	Ні	`string[]`	Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли авторизація, конфігурація або посилання на моделі згадують їх.
`kind`	Ні	`"memory"` \| `"context-engine"`	Оголошує ексклюзивний тип плагіна, що використовується `plugins.slots.*`.
`channels`	Ні	`string[]`	Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та перевірки конфігурації.
`providers`	Ні	`string[]`	Ідентифікатори провайдерів, якими володіє цей плагін.
`providerDiscoveryEntry`	Ні	`string`	Шлях до легкого модуля виявлення провайдера, відносно кореня плагіна, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного середовища виконання плагіна.
`modelSupport`	Ні	`object`	Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження плагіна перед середовищем виконання.
`modelCatalog`	Ні	`object`	Декларативні метадані каталогу моделей для провайдерів, якими володіє цей плагін. Це контракт площини керування для майбутніх списків лише для читання, онбордингу, вибирачів моделей, псевдонімів і приглушення без завантаження середовища виконання плагіна.
`modelPricing`	Ні	`object`	Політика зовнішнього пошуку цін, якою володіє провайдер. Використовуйте її, щоб виключити локальних/самостійно розміщених провайдерів із віддалених каталогів цін або зіставити посилання провайдера з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі.
`modelIdNormalization`	Ні	`object`	Очищення псевдонімів/префіксів ідентифікаторів моделей, яким володіє провайдер, що має виконуватися до завантаження середовища виконання провайдера.
`providerEndpoints`	Ні	`object[]`	Метадані хоста/baseUrl кінцевої точки, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера.
`providerRequest`	Ні	`object`	Легкі метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження середовища виконання провайдера.
`cliBackends`	Ні	`string[]`	Ідентифікатори бекендів інференсу CLI, якими володіє цей плагін. Використовується для автоматичної активації під час запуску з явних посилань конфігурації.
`syntheticAuthRefs`	Ні	`string[]`	Посилання на провайдера або бекенд CLI, для яких під час холодного виявлення моделей до завантаження середовища виконання має перевірятися синтетичний хук авторизації, яким володіє плагін.
`nonSecretAuthMarkers`	Ні	`string[]`	Значення-заповнювачі API-ключів, якими володіє вбудований плагін, що представляють несекретний локальний, OAuth або навколишній стан облікових даних.
`commandAliases`	Ні	`object[]`	Назви команд, якими володіє цей плагін, що мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження середовища виконання.
`providerAuthEnvVars`	Ні	`Record<string, string[]>`	Застарілі сумісні env-метадані для пошуку авторизації/стану провайдера. Для нових плагінів віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час періоду виведення з ужитку.
`providerAuthAliases`	Ні	`Record<string, string>`	Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку авторизації, наприклад провайдер кодування, що спільно використовує API-ключ і профілі авторизації базового провайдера.
`channelEnvVars`	Ні	`Record<string, string[]>`	Легкі env-метадані каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу або поверхонь авторизації, керованих env, які мають бачити загальні помічники запуску/конфігурації.
`providerAuthChoices`	Ні	`object[]`	Легкі метадані вибору авторизації для вибирачів онбордингу, визначення бажаного провайдера та простого підключення прапорів CLI.
`activation`	Ні	`object`	Легкі метадані планувальника активації для запуску, провайдера, команди, каналу, маршруту та завантаження, спричиненого можливостями. Лише метадані; середовище виконання плагіна все одно володіє фактичною поведінкою.
`setup`	Ні	`object`	Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання плагіна.
`qaRunners`	Ні	`object[]`	Легкі дескриптори QA-запускачів, що використовуються спільним хостом `openclaw qa` до завантаження середовища виконання плагіна.
`contracts`	Ні	`object`	Статичний знімок володіння можливостями для зовнішніх хуків авторизації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами.
`mediaUnderstandingProviderMetadata`	Ні	`Record<string, object>`	Легкі типові значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`.
`imageGenerationProviderMetadata`	Ні	`Record<string, object>`	Легкі метадані авторизації генерації зображень для ідентифікаторів провайдерів, оголошених у `contracts.imageGenerationProviders`, зокрема псевдоніми авторизації та запобіжники base-url, якими володіє провайдер.
`videoGenerationProviderMetadata`	Ні	`Record<string, object>`	Легкі метадані авторизації генерації відео для ідентифікаторів провайдерів, оголошених у `contracts.videoGenerationProviders`, зокрема псевдоніми авторизації та запобіжники base-url, якими володіє провайдер.
`musicGenerationProviderMetadata`	Ні	`Record<string, object>`	Легкі метадані авторизації генерації музики для ідентифікаторів провайдерів, оголошених у `contracts.musicGenerationProviders`, зокрема псевдоніми авторизації та запобіжники base-url, якими володіє провайдер.
`toolMetadata`	Ні	`Record<string, object>`	Легкі метадані доступності для інструментів, якими володіє плагін і які оголошені в `contracts.tools`. Використовуйте це, коли інструмент не має завантажувати середовище виконання, якщо немає доказів конфігурації, env або авторизації.
`channelConfigs`	Ні	`Record<string, object>`	Метадані конфігурації каналу, якими володіє маніфест, що об’єднуються з поверхнями виявлення та перевірки до завантаження середовища виконання.
`skills`	Ні	`string[]`	Каталоги Skills для завантаження, відносно кореня плагіна.
`name`	Ні	`string`	Людсько-зрозуміла назва Plugin.
`description`	Ні	`string`	Короткий підсумок, що показується в поверхнях Plugin.
`version`	Ні	`string`	Інформаційна версія Plugin.
`uiHints`	Ні	`Record<string, object>`	Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації.

Довідник метаданих постачальників генерації

Поля метаданих постачальника генерації описують статичні сигнали автентифікації для постачальників, оголошених у відповідному списку contracts.*GenerationProviders. OpenClaw читає ці поля до завантаження runtime постачальника, щоб основні інструменти могли визначити, чи доступний постачальник генерації, без імпорту кожного Plugin постачальника.

Використовуйте ці поля лише для простих декларативних фактів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації залишаються в runtime Plugin.

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

Кожен запис метаданих підтримує:

Поле	Обов’язкове	Тип	Що це означає
`aliases`	Ні	`string[]`	Додаткові ідентифікатори постачальника, які мають вважатися статичними псевдонімами автентифікації для постачальника генерації.
`authProviders`	Ні	`string[]`	Ідентифікатори постачальників, чиї налаштовані профілі автентифікації мають вважатися автентифікацією для цього постачальника генерації.
`configSignals`	Ні	`object[]`	Прості сигнали доступності лише з конфігурації для локальних або самостійно розгорнутих постачальників, які можна налаштувати без профілів автентифікації чи змінних середовища.
`authSignals`	Ні	`object[]`	Явні сигнали автентифікації. Якщо присутні, вони замінюють стандартний набір сигналів з ідентифікатора постачальника, `aliases` і `authProviders`.

Кожен запис configSignals підтримує:

Поле	Обов’язкове	Тип	Що це означає
`rootPath`	Так	`string`	Шлях через крапку до об’єкта конфігурації, що належить Plugin, який потрібно перевірити, наприклад `plugins.entries.example.config`.
`overlayPath`	Ні	`string`	Шлях через крапку всередині кореневої конфігурації, чий об’єкт має накладатися на кореневий об’єкт перед оцінюванням сигналу. Використовуйте це для конфігурації певної можливості, як-от `image`, `video` або `music`.
`required`	Ні	`string[]`	Шляхи через крапку всередині ефективної конфігурації, які повинні мати налаштовані значення. Рядки мають бути непорожніми; об’єкти й масиви не мають бути порожніми.
`requiredAny`	Ні	`string[]`	Шляхи через крапку всередині ефективної конфігурації, де принаймні один має мати налаштоване значення.
`mode`	Ні	`object`	Необов’язкова перевірка рядкового режиму всередині ефективної конфігурації. Використовуйте це, коли доступність лише з конфігурації застосовується тільки до одного режиму.

Кожна перевірка mode підтримує:

Поле	Обов’язкове	Тип	Що це означає
`path`	Ні	`string`	Шлях через крапку всередині ефективної конфігурації. За замовчуванням `mode`.
`default`	Ні	`string`	Значення режиму, яке слід використовувати, коли конфігурація не містить шлях.
`allowed`	Ні	`string[]`	Якщо присутнє, сигнал проходить лише тоді, коли ефективний режим є одним із цих значень.
`disallowed`	Ні	`string[]`	Якщо присутнє, сигнал не проходить, коли ефективний режим є одним із цих значень.

Кожен запис authSignals підтримує:

Поле	Обов’язкове	Тип	Що це означає
`provider`	Так	`string`	Ідентифікатор постачальника для перевірки в налаштованих профілях автентифікації.
`providerBaseUrl`	Ні	`object`	Необов’язкова перевірка, завдяки якій сигнал враховується лише тоді, коли вказаний налаштований постачальник використовує дозволену базову URL-адресу. Використовуйте це, коли псевдонім автентифікації чинний лише для певних API.

Кожна перевірка providerBaseUrl підтримує:

Поле	Обов’язкове	Тип	Що це означає
`provider`	Так	`string`	Ідентифікатор конфігурації постачальника, чий `baseUrl` потрібно перевірити.
`defaultBaseUrl`	Ні	`string`	Базова URL-адреса, яку слід припускати, коли конфігурація постачальника не містить `baseUrl`.
`allowedBaseUrls`	Так	`string[]`	Дозволені базові URL-адреси для цього сигналу автентифікації. Сигнал ігнорується, коли налаштована або стандартна базова URL-адреса не збігається з одним із цих нормалізованих значень.

Довідник метаданих інструментів

toolMetadata використовує ті самі форми configSignals і authSignals, що й метадані постачальника генерації, з ключами за назвою інструмента. contracts.tools оголошує належність. toolMetadata оголошує прості докази доступності, щоб OpenClaw міг уникати імпорту runtime Plugin лише для того, щоб фабрика інструмента повернула 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"]
        }
      ]
    }
  }
}

Якщо інструмент не має toolMetadata, OpenClaw зберігає наявну поведінку й завантажує Plugin-власника, коли контракт інструмента відповідає політиці. Для інструментів гарячого шляху, чия фабрика залежить від автентифікації/конфігурації, автори Plugin мають оголошувати toolMetadata замість того, щоб змушувати ядро імпортувати runtime для запиту.

Довідник providerAuthChoices

Кожен запис providerAuthChoices описує один варіант онбордингу або автентифікації. OpenClaw читає це до завантаження runtime постачальника. Списки налаштування постачальника використовують ці варіанти з маніфесту, варіанти налаштування, отримані з дескриптора, і метадані каталогу встановлення без завантаження runtime постачальника.

Поле	Обов’язкове	Тип	Що це означає
`provider`	Так	`string`	Ідентифікатор постачальника, якому належить цей варіант.
`method`	Так	`string`	Ідентифікатор методу автентифікації для dispatch.
`choiceId`	Так	`string`	Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та потоках CLI.
`choiceLabel`	Ні	`string`	Мітка для користувача. Якщо пропущено, OpenClaw повертається до `choiceId`.
`choiceHint`	Ні	`string`	Короткий допоміжний текст для вибору.
`assistantPriority`	Ні	`number`	Нижчі значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом.
`assistantVisibility`	Ні	`"visible"` \| `"manual-only"`	Приховує варіант із засобів вибору асистента, водночас дозволяючи ручний вибір у CLI.
`deprecatedChoiceIds`	Ні	`string[]`	Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта заміни.
`groupId`	Ні	`string`	Необов’язковий ідентифікатор групи для групування пов’язаних варіантів.
`groupLabel`	Ні	`string`	Мітка для користувача для цієї групи.
`groupHint`	Ні	`string`	Короткий допоміжний текст для групи.
`optionKey`	Ні	`string`	Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем.
`cliFlag`	Ні	`string`	Назва прапорця CLI, наприклад `--openrouter-api-key`.
`cliOption`	Ні	`string`	Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`.
`cliDescription`	Ні	`string`	Опис, що використовується в довідці CLI.
`onboardingScopes`	Ні	`Array<"text-inference" \| "image-generation">`	Поверхні онбордингу, на яких має з’являтися цей варіант. Якщо пропущено, стандартно використовується `["text-inference"]`.

Довідник commandAliases

Використовуйте commandAliases, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати в plugins.allow або спробувати запустити як кореневу CLI-команду. OpenClaw використовує ці метадані для діагностики без імпорту runtime-коду Plugin.

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

Поле	Обов’язкове	Тип	Що це означає
`name`	Так	`string`	Назва команди, що належить цьому Plugin.
`kind`	Ні	`"runtime-slash"`	Позначає псевдонім як slash-команду чату, а не кореневу CLI-команду.
`cliCommand`	Ні	`string`	Пов’язана коренева CLI-команда, яку варто запропонувати для CLI-операцій, якщо така існує.

довідник activation

Використовуйте activation, коли Plugin може з малими витратами оголосити, які події control plane мають включати його до плану активації/завантаження.

Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє runtime-поведінку, не замінює register(...) і не обіцяє, що код Plugin уже виконано. Планувальник активації використовує ці поля, щоб звузити список кандидатів Plugin перед fallback до наявних метаданих володіння маніфесту, таких як providers, channels, commandAliases, setup.providers, contracts.tools і hooks.

Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте providers, channels, commandAliases, setup-дескриптори або contracts, коли ці поля виражають зв’язок. Використовуйте activation для додаткових підказок планувальнику, які не можна представити цими полями володіння. Використовуйте верхньорівневі cliBackends для runtime-псевдонімів CLI, таких як claude-cli, codex-cli або google-gemini-cli; activation.onAgentHarnesses призначено лише для ідентифікаторів вбудованих agent harness, які ще не мають поля володіння.

Цей блок містить лише метадані. Він не реєструє runtime-поведінку і не замінює register(...), setupEntry чи інші точки входу runtime/Plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тож відсутність не-startup метаданих активації зазвичай впливає лише на продуктивність; вона не має змінювати коректність, доки fallback-и володіння маніфесту все ще існують.

Кожен Plugin має свідомо встановлювати activation.onStartup. Встановлюйте true лише тоді, коли Plugin має запускатися під час старту Gateway. Встановлюйте false, коли Plugin інертний під час startup і має завантажуватися лише за вужчими тригерами. Відсутність onStartup більше не спричиняє неявне startup-завантаження Plugin; використовуйте явні метадані активації для startup, каналу, конфігурації, agent-harness, пам’яті або інших вужчих тригерів активації.

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

Поле	Обов’язкове	Тип	Що це означає
`onStartup`	Ні	`boolean`	Явна startup-активація Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час startup; `false` залишає його startup-lazy, якщо інший відповідний тригер не потребує завантаження.
`onProviders`	Ні	`string[]`	Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження.
`onAgentHarnesses`	Ні	`string[]`	Runtime-ідентифікатори вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте верхньорівневі `cliBackends` для псевдонімів CLI backend.
`onCommands`	Ні	`string[]`	Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження.
`onChannels`	Ні	`string[]`	Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження.
`onRoutes`	Ні	`string[]`	Види маршрутів, які мають включати цей Plugin до планів активації/завантаження.
`onConfigPaths`	Ні	`string[]`	Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів startup/завантаження, коли шлях присутній і не вимкнений явно.
`onCapabilities`	Ні	`Array<"provider" \| "channel" \| "tool" \| "hook">`	Широкі підказки про можливості, які використовуються плануванням активації control plane. За можливості віддавайте перевагу вужчим полям.

Поточні live-споживачі:

Планування startup Gateway використовує activation.onStartup для явного startup імпорту
планування CLI, ініційоване командою, fallback-иться до legacy commandAliases[].cliCommand або commandAliases[].name
планування startup agent-runtime використовує activation.onAgentHarnesses для вбудованих harness і верхньорівневі cliBackends[] для runtime-псевдонімів CLI
планування setup/каналу, ініційоване каналом, fallback-иться до legacy-володіння channels[], коли явні метадані активації каналу відсутні
планування startup Plugin використовує activation.onConfigPaths для неканальних кореневих поверхонь конфігурації, таких як блок browser у вбудованому browser Plugin
планування setup/runtime, ініційоване провайдером, fallback-иться до legacy-володіння providers[] і верхньорівневих cliBackends[], коли явні метадані активації провайдера відсутні

Діагностика планувальника може відрізняти явні підказки активації від fallback володіння маніфесту. Наприклад, activation-command-hint означає, що activation.onCommands збігся, тоді як manifest-command-alias означає, що планувальник натомість використав володіння commandAliases. Ці мітки причин призначені для діагностики хоста й тестів; автори Plugin мають і далі оголошувати метадані, які найкраще описують володіння.

довідник qaRunners

Використовуйте qaRunners, коли Plugin додає один або кілька transport runner під спільним коренем openclaw qa. Тримайте ці метадані дешевими й статичними; runtime Plugin і далі володіє фактичною реєстрацією CLI через легку поверхню runtime-api.ts, яка експортує qaRunnerCliRegistrations.

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

Поле	Обов’язкове	Тип	Що це означає
`commandName`	Так	`string`	Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`.
`description`	Ні	`string`	Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда.

довідник setup

Використовуйте setup, коли поверхням setup і onboarding потрібні дешеві метадані, що належать Plugin, до завантаження runtime.

{
  "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 залишається чинним і продовжує описувати бекенди інференсу CLI. setup.cliBackends — це setup-специфічна поверхня дескрипторів для потоків control-plane/setup, які мають залишатися лише метаданими.

Коли setup.providers і setup.cliBackends присутні, вони є пріоритетною поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише звужує кандидатний Plugin, а setup все ще потребує багатших runtime hooks під час setup, встановіть requiresRuntime: true і залиште setup-api як резервний шлях виконання.

OpenClaw також включає setup.providers[].envVars у загальні пошуки автентифікації провайдера та env-var. providerAuthEnvVars залишається підтримуваним через compatibility адаптер протягом вікна deprecation, але невбудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin мають розміщувати setup/status env metadata у setup.providers[].envVars.

OpenClaw також може виводити прості варіанти setup з setup.providers[].authMethods, коли setup entry недоступний або коли setup.requiresRuntime: false оголошує, що setup runtime непотрібний. Явні записи providerAuthChoices залишаються пріоритетними для власних міток, CLI-прапорців, onboarding scope і метаданих assistant.

Встановлюйте requiresRuntime: false лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне false як descriptor-only contract і не виконуватиме setup-api або openclaw.setupEntry для пошуку setup. Якщо descriptor-only Plugin все ще постачає один із цих runtime entry для setup, OpenClaw повідомляє additive diagnostic і продовжує його ігнорувати. Пропущений requiresRuntime зберігає legacy fallback behavior, щоб наявні Plugin, які додали дескриптори без прапорця, не ламалися.

Оскільки пошук setup може виконувати код setup-api, що належить Plugin, нормалізовані значення setup.providers[].id і setup.cliBackends[] мають залишатися унікальними серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору переможця за порядком виявлення.

Коли setup runtime виконується, діагностика setup registry повідомляє про descriptor drift, якщо setup-api реєструє провайдера або CLI backend, який дескриптори маніфесту не оголошують, або якщо дескриптор не має відповідної runtime реєстрації. Ці діагностики additive і не відхиляють legacy Plugin.

довідник setup.providers

Поле	Обов’язкове	Тип	Що це означає
`id`	Так	`string`	Ідентифікатор провайдера, доступний під час setup або onboarding. Тримайте нормалізовані ідентифікатори глобально унікальними.
`authMethods`	Ні	`string[]`	Ідентифікатори методів setup/auth, які цей провайдер підтримує без завантаження повного runtime.
`envVars`	Ні	`string[]`	Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin.
`authEvidence`	Ні	`object[]`	Дешеві локальні перевірки доказів автентифікації для провайдерів, які можуть автентифікуватися через не-secret маркери.

authEvidence призначено для локальних маркерів облікових даних, якими володіє провайдер і які можна перевірити без завантаження коду середовища виконання. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання з keychain або менеджера секретів, без команд оболонки та без перевірок API провайдера.

Підтримувані записи доказів:

Поле	Обов’язкове	Тип	Що це означає
`type`	Так	`string`	Наразі `local-file-with-env`.
`fileEnvVar`	Ні	`string`	Змінна середовища, що містить явний шлях до файлу облікових даних.
`fallbackPaths`	Ні	`string[]`	Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`.
`requiresAnyEnv`	Ні	`string[]`	Принаймні одна зі вказаних змінних середовища має бути непорожньою, перш ніж доказ стане чинним.
`requiresAllEnv`	Ні	`string[]`	Кожна зі вказаних змінних середовища має бути непорожньою, перш ніж доказ стане чинним.
`credentialMarker`	Так	`string`	Несекретний маркер, що повертається, коли доказ наявний.
`source`	Ні	`string`	Видима для користувача мітка джерела для виводу автентифікації/статусу.

поля налаштування

Поле	Обов’язкове	Тип	Що це означає
`providers`	Ні	`object[]`	Дескриптори налаштування провайдера, що показуються під час налаштування й onboarding.
`cliBackends`	Ні	`string[]`	Ідентифікатори бекендів часу налаштування, що використовуються для пошуку налаштування спершу за дескриптором. Тримайте нормалізовані ідентифікатори глобально унікальними.
`configMigrations`	Ні	`string[]`	Ідентифікатори міграцій конфігурації, якими володіє поверхня налаштування цього plugin.
`requiresRuntime`	Ні	`boolean`	Чи налаштуванню все ще потрібне виконання `setup-api` після пошуку дескриптора.

довідник uiHints

uiHints — це мапа від назв полів конфігурації до невеликих підказок рендерингу.

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

Кожна підказка поля може містити:

Поле	Тип	Що це означає
`label`	`string`	Видима для користувача мітка поля.
`help`	`string`	Короткий допоміжний текст.
`tags`	`string[]`	Необов’язкові UI-теги.
`advanced`	`boolean`	Позначає поле як розширене.
`sensitive`	`boolean`	Позначає поле як секретне або чутливе.
`placeholder`	`string`	Текст placeholder для полів форми.

довідник contracts

Використовуйте contracts лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту середовища виконання plugin.

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

Кожен список необов’язковий:

Поле	Тип	Що це означає
`embeddedExtensionFactories`	`string[]`	Ідентифікатори фабрик розширень сервера застосунку Codex, наразі `codex-app-server`.
`agentToolResultMiddleware`	`string[]`	Ідентифікатори середовища виконання, для яких вбудований plugin може реєструвати middleware результатів інструментів.
`externalAuthProviders`	`string[]`	Ідентифікатори провайдерів, чиїм hook зовнішнього профілю автентифікації володіє цей plugin.
`speechProviders`	`string[]`	Ідентифікатори провайдерів мовлення, якими володіє цей plugin.
`realtimeTranscriptionProviders`	`string[]`	Ідентифікатори провайдерів транскрипції в реальному часі, якими володіє цей plugin.
`realtimeVoiceProviders`	`string[]`	Ідентифікатори голосових провайдерів у реальному часі, якими володіє цей plugin.
`memoryEmbeddingProviders`	`string[]`	Ідентифікатори провайдерів embedding пам’яті, якими володіє цей plugin.
`mediaUnderstandingProviders`	`string[]`	Ідентифікатори провайдерів розуміння медіа, якими володіє цей plugin.
`imageGenerationProviders`	`string[]`	Ідентифікатори провайдерів генерації зображень, якими володіє цей plugin.
`videoGenerationProviders`	`string[]`	Ідентифікатори провайдерів генерації відео, якими володіє цей plugin.
`webFetchProviders`	`string[]`	Ідентифікатори провайдерів web-fetch, якими володіє цей plugin.
`webSearchProviders`	`string[]`	Ідентифікатори провайдерів web-search, якими володіє цей plugin.
`migrationProviders`	`string[]`	Ідентифікатори провайдерів імпорту, якими цей plugin володіє для `openclaw migrate`.
`tools`	`string[]`	Назви інструментів агента, якими володіє цей plugin.

contracts.embeddedExtensionFactories збережено для вбудованих фабрик розширень Codex, призначених лише для сервера застосунку. Вбудовані перетворення результатів інструментів мають оголошувати contracts.agentToolResultMiddleware і реєструватися через api.registerAgentToolResultMiddleware(...) натомість. Зовнішні plugins не можуть реєструвати middleware результатів інструментів, оскільки цей seam може переписувати високодовірений вивід інструментів до того, як модель його побачить.

Реєстрації середовища виконання api.registerTool(...) мають відповідати contracts.tools. Виявлення інструментів використовує цей список, щоб завантажувати лише середовища виконання plugins, які можуть володіти запитаними інструментами.

Plugins провайдерів, які реалізують resolveExternalAuthProfiles, мають оголошувати contracts.externalAuthProviders. Plugins без такого оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде вилучений після міграційного вікна.

Вбудовані провайдери embedding пам’яті мають оголошувати contracts.memoryEmbeddingProviders для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як local. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажити лише plugin-власника до того, як повне середовище виконання Gateway зареєструє провайдерів.

довідник mediaUnderstandingProviderMetadata

Використовуйте mediaUnderstandingProviderMetadata, коли провайдер розуміння медіа має моделі за замовчуванням, пріоритет fallback для auto-auth або нативну підтримку документів, які потрібні загальним core-помічникам до завантаження середовища виконання. Ключі також мають бути оголошені в contracts.mediaUnderstandingProviders.

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

Кожен запис провайдера може містити:

Поле	Тип	Що це означає
`capabilities`	`("image" \| "audio" \| "video")[]`	Можливості медіа, які надає цей провайдер.
`defaultModels`	`Record<string, string>`	Значення за замовчуванням «можливість-модель», що використовуються, коли конфігурація не вказує модель.
`autoPriority`	`Record<string, number>`	Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних.
`nativeDocumentInputs`	`"pdf"[]`	Нативні вхідні документи, які підтримує провайдер.

довідник channelConfigs

Використовуйте channelConfigs, коли plugin каналу потребує дешевих метаданих конфігурації до завантаження середовища виконання. Виявлення налаштування/статусу каналу тільки для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний, або коли setup.requiresRuntime: false оголошує, що середовище виконання налаштування непотрібне.

channelConfigs — це метадані маніфесту plugin, а не новий розділ верхнього рівня користувацької конфігурації. Користувачі все ще налаштовують екземпляри каналів у channels.<channel-id>. OpenClaw читає метадані маніфесту, щоб вирішити, який plugin володіє цим налаштованим каналом до виконання коду середовища виконання plugin.

Для plugin каналу configSchema і channelConfigs описують різні шляхи:

configSchema перевіряє plugins.entries.<plugin-id>.config
channelConfigs.<channel-id>.schema перевіряє channels.<channel-id>

Невбудовані plugins, які оголошують channels[], також мають оголошувати відповідні записи channelConfigs. Без них OpenClaw усе ще може завантажити plugin, але схема конфігурації cold-path, налаштування та поверхні Control UI не можуть знати форму опцій, якою володіє канал, доки не виконається середовище виконання plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled і nativeSkillsAutoEnabled можуть оголошувати статичні значення auto за замовчуванням для перевірок конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі значення за замовчуванням через package.json#openclaw.channel.commands разом з іншими метаданими каталогу каналів, якими володіє package.

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

Кожен запис каналу може містити:

Поле	Тип	Що означає
`schema`	`object`	JSON Schema для `channels.<id>`. Обов’язкова для кожного оголошеного запису конфігурації каналу.
`uiHints`	`Record<string, object>`	Необов’язкові UI-мітки/заповнювачі/підказки щодо чутливих даних для цього розділу конфігурації каналу.
`label`	`string`	Мітка каналу, що об’єднується з поверхнями вибору та інспекції, коли метадані runtime ще не готові.
`description`	`string`	Короткий опис каналу для поверхонь інспекції та каталогу.
`commands`	`object`	Статична нативна команда й автоматичні стандартні значення нативного skill для перевірок конфігурації до runtime.
`preferOver`	`string[]`	Ідентифікатори застарілих або нижчопріоритетних плагінів, які цей канал має випереджати в поверхнях вибору.

Заміна іншого плагіна каналу

Використовуйте preferOver, коли ваш плагін є пріоритетним власником для ідентифікатора каналу, який також може надавати інший плагін. Типові випадки: перейменований ідентифікатор плагіна, окремий плагін, що замінює вбудований плагін, або підтримуваний форк, який зберігає той самий ідентифікатор каналу для сумісності конфігурації.

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

Коли channels.chat налаштовано, OpenClaw враховує і ідентифікатор каналу, і ідентифікатор пріоритетного плагіна. Якщо нижчопріоритетний плагін було вибрано лише тому, що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній конфігурації runtime, щоб один плагін володів каналом і його інструментами. Явний вибір користувача все ще має перевагу: якщо користувач явно вмикає обидва плагіни, OpenClaw зберігає цей вибір і повідомляє діагностику дублювання каналу/інструментів замість тихої зміни запитаного набору плагінів.

Обмежуйте preferOver ідентифікаторами плагінів, які справді можуть надавати той самий канал. Це не загальне поле пріоритету, і воно не перейменовує ключі конфігурації користувача.

Довідник modelSupport

Використовуйте modelSupport, коли OpenClaw має виводити ваш плагін провайдера з коротких ідентифікаторів моделей на кшталт gpt-5.5 або claude-sonnet-4.6 до завантаження runtime плагіна.

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

OpenClaw застосовує такий порядок пріоритету:

явні посилання provider/model використовують метадані маніфесту providers власника
modelPatterns мають перевагу над modelPrefixes
якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований плагін
решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера

Поля:

Поле	Тип	Що означає
`modelPrefixes`	`string[]`	Префікси, що зіставляються через `startsWith` із короткими ідентифікаторами моделей.
`modelPatterns`	`string[]`	Джерела regex, що зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю.

Довідник modelCatalog

Використовуйте modelCatalog, коли OpenClaw має знати метадані моделей провайдера до завантаження runtime плагіна. Це джерело, яким володіє маніфест, для фіксованих рядків каталогу, псевдонімів провайдера, правил приховування та режиму виявлення. Оновлення runtime все ще належить до коду runtime провайдера, але маніфест повідомляє core, коли runtime потрібен.

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

Поля верхнього рівня:

Поле	Тип	Що означає
`providers`	`Record<string, object>`	Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей плагін. Ключі також мають бути в `providers` верхнього рівня.
`aliases`	`Record<string, object>`	Псевдоніми провайдерів, які мають розв’язуватися до власного провайдера для планування каталогу або приховування.
`suppressions`	`object[]`	Рядки моделей з іншого джерела, які цей плагін приховує з причини, специфічної для провайдера.
`discovery`	`Record<string, "static" \| "refreshable" \| "runtime">`	Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або чи він потребує runtime.

aliases бере участь у пошуку власника провайдера для планування каталогу моделей. Цілі псевдонімів мають бути провайдерами верхнього рівня, якими володіє той самий плагін. Коли список, відфільтрований за провайдером, використовує псевдонім, OpenClaw може прочитати маніфест власника та застосувати перевизначення API/base URL псевдоніма без завантаження runtime провайдера. Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки канонічного провайдера-власника.

suppressions замінює старий runtime hook провайдера suppressBuiltInModel. Записи приховування враховуються лише тоді, коли провайдером володіє плагін або його оголошено як ключ modelCatalog.aliases, що вказує на власного провайдера. Runtime hooks приховування більше не викликаються під час розв’язання моделей.

Поля провайдера:

Поле	Тип	Що означає
`baseUrl`	`string`	Необов’язкова стандартна base URL для моделей у цьому каталозі провайдера.
`api`	`ModelApi`	Необов’язковий стандартний API-адаптер для моделей у цьому каталозі провайдера.
`headers`	`Record<string, string>`	Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера.
`models`	`object[]`	Обов’язкові рядки моделей. Рядки без `id` ігноруються.

Поля моделі:

Поле	Тип	Що означає
`id`	`string`	Локальний для провайдера ідентифікатор моделі без префікса `provider/`.
`name`	`string`	Необов’язкова відображувана назва.
`api`	`ModelApi`	Необов’язкове перевизначення API для окремої моделі.
`baseUrl`	`string`	Необов’язкове перевизначення base URL для окремої моделі.
`headers`	`Record<string, string>`	Необов’язкові статичні заголовки для окремої моделі.
`input`	`Array<"text" \| "image" \| "document" \| "audio" \| "video">`	Модальності, які приймає модель.
`reasoning`	`boolean`	Чи надає модель поведінку reasoning.
`contextWindow`	`number`	Нативне вікно контексту провайдера.
`contextTokens`	`number`	Необов’язкове ефективне обмеження контексту runtime, коли воно відрізняється від `contextWindow`.
`maxTokens`	`number`	Максимальна кількість вихідних токенів, якщо відома.
`cost`	`object`	Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`.
`compat`	`object`	Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw.
`status`	`"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"`	Статус у списку. Приховуйте лише тоді, коли рядок узагалі не має з’являтися.
`statusReason`	`string`	Необов’язкова причина, що показується зі статусом, відмінним від available.
`replaces`	`string[]`	Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює.
`replacedBy`	`string`	Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків.
`tags`	`string[]`	Стабільні теги, які використовують засоби вибору та фільтри.

Поля приховування:

Поле	Тип	Що означає
`provider`	`string`	Ідентифікатор провайдера для upstream-рядка, який потрібно приховати. Має належати цьому плагіну або бути оголошеним як власний псевдонім.
`model`	`string`	Локальний для провайдера ідентифікатор моделі, яку потрібно приховати.
`reason`	`string`	Необов’язкове повідомлення, що показується, коли прихований рядок запитують напряму.
`when.baseUrlHosts`	`string[]`	Необов’язковий список ефективних хостів base URL провайдера, потрібних до застосування приховування.
`when.providerConfigApiIn`	`string[]`	Необов’язковий список точних значень `api` конфігурації провайдера, потрібних до застосування приховування.

Не розміщуйте дані лише для runtime в modelCatalog. Використовуйте static лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку та вибору з фільтрацією за провайдером могли пропускати виявлення через реєстр/runtime. Використовуйте refreshable, коли рядки маніфесту корисні як доступні для списку початкові дані або доповнення, але refresh/cache може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте runtime, коли OpenClaw має завантажити runtime провайдера, щоб дізнатися список.

Довідник modelIdNormalization

Використовуйте modelIdNormalization для дешевого очищення model-id, що належить провайдеру й має відбутися до завантаження runtime провайдера. Це залишає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі id та правила префіксів проксі, у маніфесті належного плагіна, а не в таблицях вибору моделей ядра.

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

Поля провайдера:

Поле	Тип	Що це означає
`aliases`	`Record<string,string>`	Точні псевдоніми model-id без урахування регістру. Значення повертаються так, як записані.
`stripPrefixes`	`string[]`	Префікси для видалення перед пошуком псевдоніма, корисні для застарілого дублювання provider/model.
`prefixWhenBare`	`string`	Префікс, який додається, коли нормалізований id моделі ще не містить `/`.
`prefixWhenBareAfterAliasStartsWith`	`object[]`	Умовні правила префікса bare-id після пошуку псевдоніма, ключовані за `modelPrefix` і `prefix`.

Довідник providerEndpoints

Використовуйте providerEndpoints для класифікації endpoint, яку загальна політика запитів має знати до завантаження runtime провайдера. Ядро й надалі визначає значення кожного endpointClass; маніфести плагінів визначають метадані хоста та базової URL-адреси.

Поля endpoint:

Поле	Тип	Що це означає
`endpointClass`	`string`	Відомий ядру клас endpoint, як-от `openrouter`, `moonshot-native` або `google-vertex`.
`hosts`	`string[]`	Точні імена хостів, що зіставляються з класом endpoint.
`hostSuffixes`	`string[]`	Суфікси хостів, що зіставляються з класом endpoint. Додайте `.` для зіставлення лише за суфіксом домену.
`baseUrls`	`string[]`	Точні нормалізовані базові HTTP(S) URL-адреси, що зіставляються з класом endpoint.
`googleVertexRegion`	`string`	Статичний регіон Google Vertex для точних глобальних хостів.
`googleVertexRegionHostSuffix`	`string`	Суфікс, який потрібно вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex.

Довідник providerRequest

Використовуйте providerRequest для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження runtime провайдера. Переписування payload, специфічне для поведінки, залишайте в runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів.

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

Поля провайдера:

Поле	Тип	Що це означає
`family`	`string`	Мітка сімейства провайдера, яку використовують загальні рішення сумісності запитів і діагностика.
`compatibilityFamily`	`"moonshot"`	Необов’язковий кошик сумісності сімейства провайдера для спільних допоміжних засобів запитів.
`openAICompletions`	`object`	Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`.

Довідник modelPricing

Використовуйте modelPricing, коли провайдеру потрібна поведінка ціноутворення control-plane до завантаження runtime. Кеш ціноутворення Gateway читає ці метадані без імпорту коду runtime провайдера.

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

Поля провайдера:

Поле	Тип	Що це означає
`external`	`boolean`	Установіть `false` для локальних/self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM.
`openRouter`	`false \| object`	Зіставлення пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера.
`liteLLM`	`false \| object`	Зіставлення пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера.

Поля джерела:

Поле	Тип	Що це означає
`provider`	`string`	Id провайдера зовнішнього каталогу, коли він відрізняється від id провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`.
`passthroughProviderModel`	`boolean`	Обробляти id моделей зі скісною рискою як вкладені посилання provider/model, корисно для проксі-провайдерів, як-от OpenRouter.
`modelIdTransforms`	`"version-dots"[]`	Додаткові варіанти model-id зовнішнього каталогу. `version-dots` пробує id версій із крапками, як-от `claude-opus-4.6`.

Індекс провайдерів OpenClaw

Індекс провайдерів OpenClaw — це preview-метадані, що належать OpenClaw, для провайдерів, плагіни яких ще можуть бути не встановлені. Він не є частиною маніфесту плагіна. Маніфести плагінів залишаються авторитетним джерелом для встановлених плагінів. Індекс провайдерів — це внутрішній fallback-контракт, який майбутні поверхні встановлюваних провайдерів і вибору моделей до встановлення використовуватимуть, коли плагін провайдера не встановлено.

Порядок авторитетності каталогу:

Конфігурація користувача.
modelCatalog маніфесту встановленого плагіна.
Кеш каталогу моделей з явного refresh.
Preview-рядки Індексу провайдерів OpenClaw.

Індекс провайдерів не має містити секрети, стан увімкнення, runtime-хуки або живі дані моделей, специфічні для акаунта. Його preview-каталоги використовують ту саму форму рядка провайдера modelCatalog, що й маніфести плагінів, але мають бути обмежені стабільними display-метаданими, якщо runtime-поля адаптера, як-от api, baseUrl, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого плагіна. Провайдери з живим виявленням /models мають записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати звичайний listing або onboarding викликати API провайдера.

Записи Індексу провайдерів також можуть містити метадані встановлюваного плагіна для провайдерів, чий плагін винесено з ядра або ще не встановлено з іншої причини. Ці метадані віддзеркалюють шаблон каталогу каналів: імені пакета, npm install spec, очікуваної цілісності та дешевих міток вибору auth достатньо, щоб показати варіант встановлюваного налаштування. Щойно плагін установлено, його маніфест має перевагу, а запис Індексу провайдерів для цього провайдера ігнорується.

Застарілі ключі можливостей верхнього рівня вважаються deprecated. Використовуйте openclaw doctor --fix, щоб перемістити speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders і webSearchProviders під contracts; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як належність можливостей.

Маніфест проти package.json

Ці два файли виконують різні завдання:

Файл	Для чого використовується
`openclaw.plugin.json`	Виявлення, валідація конфігурації, метадані вибору auth і підказки UI, які мають існувати до запуску коду плагіна
`package.json`	Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, install gating, setup або метаданих каталогу

Якщо ви не впевнені, де має бути певна частина метаданих, скористайтеся цим правилом:

якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в openclaw.plugin.json
якщо це стосується пакування, entry-файлів або поведінки npm install, помістіть це в package.json

Поля package.json, що впливають на виявлення

Деякі pre-runtime метадані плагіна навмисно зберігаються в package.json під блоком openclaw, а не в openclaw.plugin.json. openclaw.bundle і openclaw.bundle.json не є контрактами плагінів OpenClaw; native-плагіни мають використовувати openclaw.plugin.json плюс підтримувані поля package.json#openclaw нижче.

Важливі приклади:

Поле	Що воно означає
`openclaw.extensions`	Оголошує нативні точки входу плагіна. Має залишатися всередині каталогу пакета плагіна.
`openclaw.runtimeExtensions`	Оголошує зібрані JavaScript-точки входу середовища виконання для встановлених пакетів. Має залишатися всередині каталогу пакета плагіна.
`openclaw.setupEntry`	Легка точка входу лише для налаштування, яка використовується під час початкового налаштування, відкладеного запуску каналу та виявлення стану каналу/SecretRef у режимі лише читання. Має залишатися всередині каталогу пакета плагіна.
`openclaw.runtimeSetupEntry`	Оголошує зібрану JavaScript-точку входу налаштування для встановлених пакетів. Потребує `setupEntry`, має існувати та має залишатися всередині каталогу пакета плагіна.
`openclaw.channel`	Дешева метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст вибору.
`openclaw.channel.commands`	Статичні метадані нативних команд і нативних автоматичних типових Skills, які використовують поверхні конфігурації, аудиту та списку команд до завантаження середовища виконання каналу.
`openclaw.channel.configuredState`	Легкі метадані перевірки налаштованого стану, які можуть відповісти «чи вже існує налаштування лише через середовище?» без завантаження повного середовища виконання каналу.
`openclaw.channel.persistedAuthState`	Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти «чи вже хтось увійшов?» без завантаження повного середовища виконання каналу.
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих плагінів.
`openclaw.install.defaultChoice`	Бажаний шлях встановлення, коли доступно кілька джерел встановлення.
`openclaw.install.minHostVersion`	Мінімальна підтримувана версія хоста OpenClaw, з використанням нижньої межі semver на кшталт `>=2026.3.22` або `>=2026.5.1-beta.1`.
`openclaw.install.expectedIntegrity`	Очікуваний рядок цілісності npm-дистрибутива, наприклад `sha512-...`; потоки встановлення та оновлення перевіряють отриманий артефакт за ним.
`openclaw.install.allowInvalidConfigRecovery`	Дозволяє вузький шлях відновлення перевстановлення вбудованого плагіна, коли конфігурація недійсна.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	Дозволяє завантажувати поверхні каналу лише для налаштування перед повним плагіном каналу під час запуску.

Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в початковому налаштуванні до завантаження середовища виконання. package.json#openclaw.install повідомляє початковому налаштуванню, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в openclaw.plugin.json.

openclaw.install.minHostVersion застосовується під час встановлення та завантаження реєстру маніфестів для джерел невбудованих плагінів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають зовнішні плагіни на старіших хостах. Вважається, що вбудовані вихідні плагіни мають ту саму версію, що й checkout хоста.

Офіційні метадані встановлення на вимогу мають використовувати clawhubSpec, коли плагін опубліковано на ClawHub; початкове налаштування розглядає це як бажане віддалене джерело та записує факти артефакта ClawHub після встановлення. npmSpec залишається сумісним резервним варіантом для пакетів, які ще не перейшли на ClawHub.

Точне закріплення версії npm уже міститься в npmSpec, наприклад "npmSpec": "@wecom/[email protected]". Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з expectedIntegrity, щоб потоки оновлення завершувалися закрито, якщо отриманий npm-артефакт більше не відповідає закріпленому випуску. Інтерактивне початкове налаштування все ще пропонує довірені npm-специфікації реєстру, зокрема прості назви пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та недійсні джерела типового вибору. Вона також попереджає, коли expectedIntegrity присутній, але немає дійсного npm-джерела, яке він може закріпити. Коли expectedIntegrity присутній, потоки встановлення/оновлення застосовують його; коли його немає, розв’язання реєстру записується без закріплення цілісності.

Плагіни каналів мають надавати openclaw.setupEntry, коли стан, список каналів або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має відкривати метадані каналу плюс безпечні для налаштування адаптери конфігурації, стану та секретів; мережеві клієнти, слухачі Gateway та транспортні середовища виконання тримайте в основній точці входу розширення.

Поля точки входу середовища виконання не перевизначають перевірки меж пакета для вихідних полів точки входу. Наприклад, openclaw.runtimeExtensions не може зробити шлях openclaw.extensions, що виходить за межі, завантажуваним.

openclaw.install.allowInvalidConfigRecovery навмисно вузький. Він не робить довільні зламані конфігурації придатними для встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого плагіна, як-от відсутній шлях вбудованого плагіна або застарілий запис channels.<id> для того самого вбудованого плагіна. Непов’язані помилки конфігурації все ще блокують встановлення та спрямовують операторів до openclaw doctor --fix.

openclaw.channel.persistedAuthState — це метадані пакета для крихітного модуля перевірки:

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

Використовуйте це, коли потоки налаштування, doctor, стану або присутності лише для читання потребують дешевого так/ні-зонду автентифікації до завантаження повного плагіна каналу. Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці метадані, щоб автоматично вмикати плагіни, ремонтувати залежності середовища виконання або вирішувати, чи має завантажуватися середовище виконання каналу. Цільовий експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel середовища виконання каналу.

openclaw.channel.configuredState має таку саму форму для дешевих перевірок налаштованості лише через середовище:

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

Використовуйте це, коли канал може відповісти про налаштований стан із середовища або інших крихітних не-runtime-вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або справжнього середовища виконання каналу, залиште цю логіку в хуку плагіна config.hasConfiguredState.

Пріоритет виявлення (дублікати ідентифікаторів плагінів)

OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, workspace, явні шляхи, вибрані конфігурацією). Якщо два виявлені елементи мають той самий id, зберігається лише маніфест із найвищим пріоритетом; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.

Пріоритет, від найвищого до найнижчого:

Вибраний конфігурацією — шлях, явно закріплений у plugins.entries.<id>
Вбудований — плагіни, що постачаються з OpenClaw
Глобальне встановлення — плагіни, встановлені в глобальний корінь плагінів OpenClaw
Workspace — плагіни, виявлені відносно поточного workspace

Наслідки:

Форкована або застаріла копія вбудованого плагіна, що лежить у workspace, не затінить вбудовану збірку.
Щоб справді перевизначити вбудований плагін локальним, закріпіть його через plugins.entries.<id>, щоб він переміг за пріоритетом, а не покладайтеся на виявлення workspace.
Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
Перевизначення дублікатів, вибраних конфігурацією, у діагностиці формулюються як явні перевизначення, але все одно попереджають, щоб застарілі форки та випадкові затінення залишалися видимими.

Вимоги JSON Schema

Кожен плагін має постачатися з JSON Schema, навіть якщо він не приймає конфігурацію.
Порожня схема прийнятна (наприклад, { "type": "object", "additionalProperties": false }).
Схеми перевіряються під час читання/запису конфігурації, а не під час виконання.
Коли розширюєте або форкаєте вбудований плагін із новими ключами конфігурації, одночасно оновіть configSchema цього плагіна в openclaw.plugin.json. Схеми вбудованих плагінів суворі, тому додавання plugins.entries.<id>.config.myNewKey у конфігурацію користувача без додавання myNewKey до configSchema.properties буде відхилено до завантаження середовища виконання плагіна.

Приклад розширення схеми:

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

Поведінка перевірки

Невідомі ключі channels.* є помилками, якщо ідентифікатор каналу не оголошено маніфестом плагіна.
plugins.entries.<id>, plugins.allow, plugins.deny і plugins.slots.* мають посилатися на виявлювані ідентифікатори плагінів. Невідомі ідентифікатори є помилками.
Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, перевірка завершується невдачею, а Doctor повідомляє про помилку плагіна.
Якщо конфігурація плагіна існує, але плагін вимкнено, конфігурація зберігається, а попередження показується в Doctor і журналах.

Див. довідник конфігурації для повної схеми plugins.*.

Примітки

Маніфест є обов’язковим для нативних плагінів OpenClaw, зокрема для завантажень із локальної файлової системи. Середовище виконання й надалі завантажує модуль плагіна окремо; маніфест потрібен лише для виявлення + валідації.
Нативні маніфести розбираються за допомогою JSON5, тому коментарі, завершальні коми та ключі без лапок приймаються, якщо підсумкове значення все одно є об’єктом.
Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня.
channels, providers, cliBackends і skills можна не вказувати, якщо вони не потрібні плагіну.
providerDiscoveryEntry має залишатися легковагим і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту.
Ексклюзивні типи плагінів вибираються через plugins.slots.*: kind: "memory" через plugins.slots.memory, kind: "context-engine" через plugins.slots.contextEngine (типово legacy).
Оголошуйте ексклюзивний тип плагіна в цьому маніфесті. OpenClawPluginDefinition.kind у точці входу середовища виконання застарів і залишається лише як резервна сумісність для старіших плагінів.
Метадані змінних середовища (setup.providers[].envVars, застарілі providerAuthEnvVars і channelEnvVars) є лише декларативними. Статус, аудит, валідація доставки cron та інші поверхні лише для читання все ще застосовують довіру до плагіна й політику ефективної активації, перш ніж вважати змінну середовища налаштованою.
Для метаданих майстра середовища виконання, яким потрібен код провайдера, див. хуки середовища виконання провайдера.
Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до списку дозволів менеджера пакетів (наприклад, pnpm allow-build-scripts + pnpm rebuild <package>).

Пов’язане

Створення плагінів

Початок роботи з плагінами.

Архітектура Plugin

Внутрішня архітектура та модель можливостей.

Огляд SDK

Довідник SDK Plugin та імпорти підшляхів.

# Що робить цей файл

# Мінімальний приклад

# Розширений приклад

# Довідник полів верхнього рівня

# Довідник метаданих постачальників генерації

# Довідник метаданих інструментів

# Довідник providerAuthChoices

# Довідник commandAliases

# довідник activation

# довідник qaRunners

# довідник setup

# довідник setup.providers

# поля налаштування

# довідник uiHints

# довідник contracts

# довідник mediaUnderstandingProviderMetadata

# довідник channelConfigs

# Заміна іншого плагіна каналу

# Довідник modelSupport

# Довідник modelCatalog

# Довідник modelIdNormalization

# Довідник providerEndpoints

# Довідник providerRequest

# Довідник modelPricing

# Індекс провайдерів OpenClaw

# Маніфест проти package.json

# Поля package.json, що впливають на виявлення

# Пріоритет виявлення (дублікати ідентифікаторів плагінів)

# Вимоги JSON Schema

# Поведінка перевірки

# Примітки

# Пов’язане

Що робить цей файл

Мінімальний приклад

Розширений приклад

Довідник полів верхнього рівня

Довідник метаданих постачальників генерації

Довідник метаданих інструментів

Довідник providerAuthChoices

Довідник commandAliases

довідник activation

довідник qaRunners

довідник setup

довідник setup.providers

поля налаштування

довідник uiHints

довідник contracts

довідник mediaUnderstandingProviderMetadata

довідник channelConfigs

Заміна іншого плагіна каналу

Довідник modelSupport

Довідник modelCatalog

Довідник modelIdNormalization

Довідник providerEndpoints

Довідник providerRequest

Довідник modelPricing

Індекс провайдерів OpenClaw

Маніфест проти package.json

Поля package.json, що впливають на виявлення

Пріоритет виявлення (дублікати ідентифікаторів плагінів)

Вимоги JSON Schema

Поведінка перевірки

Примітки

Пов’язане