Маніфест 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, коли макет відповідає очікуванням runtime OpenClaw. Кожен нативний Plugin OpenClaw обов’язково має постачати файл openclaw.plugin.json у корені Plugin. OpenClaw використовує цей маніфест, щоб перевіряти конфігурацію без виконання коду Plugin. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують перевірку конфігурації. Див. повний посібник із системи Plugin: Plugins. Про нативну модель можливостей і поточні настанови щодо зовнішньої сумісності: Модель можливостей.

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

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

ідентичності Plugin, перевірки конфігурації та підказок UI конфігурації
метаданих auth, onboarding і setup (alias, auto-enable, provider env vars, auth choices)
підказок активації для поверхонь control-plane
скороченого володіння сімействами моделей
статичних знімків володіння можливостями (contracts)
метаданих QA runner, які може перевіряти спільний хост openclaw qa
метаданих конфігурації для конкретних каналів, об’єднаних у catalog і поверхні validation

Не використовуйте його для: реєстрації поведінки runtime, оголошення code entrypoints або метаданих npm install. Вони належать до вашого коду 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`	Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.<id>`.
`configSchema`	Так	`object`	Вбудована JSON Schema для конфігурації цього Plugin.
`enabledByDefault`	Ні	`true`	Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням.
`enabledByDefaultOnPlatforms`	Ні	`string[]`	Позначає вбудований Plugin як увімкнений за замовчуванням лише на перелічених платформах Node.js, наприклад `["darwin"]`. Явна конфігурація все одно має пріоритет.
`legacyPluginIds`	Ні	`string[]`	Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора Plugin.
`autoEnableWhenConfiguredProviders`	Ні	`string[]`	Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх.
`kind`	Ні	`"memory"` \| `"context-engine"`	Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`.
`channels`	Ні	`string[]`	Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та перевірки конфігурації.
`providers`	Ні	`string[]`	Ідентифікатори провайдерів, якими володіє цей Plugin.
`providerCatalogEntry`	Ні	`string`	Шлях до легкого модуля каталогу провайдера відносно кореня Plugin для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного runtime Plugin.
`modelSupport`	Ні	`object`	Скорочені метадані сімейств моделей, що належать маніфесту й використовуються для автоматичного завантаження Plugin перед runtime.
`modelCatalog`	Ні	`object`	Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт площини керування для майбутнього спискування лише для читання, онбордингу, вибору моделей, псевдонімів і пригнічення без завантаження runtime Plugin.
`modelPricing`	Ні	`object`	Політика зовнішнього пошуку цін, що належить провайдеру. Використовуйте її, щоб виключити локальних або self-hosted провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у core.
`modelIdNormalization`	Ні	`object`	Очищення псевдонімів і префіксів ідентифікаторів моделей, що належить провайдеру та має виконуватися до завантаження runtime провайдера.
`providerEndpoints`	Ні	`object[]`	Метадані хоста/baseUrl кінцевої точки, що належать маніфесту, для маршрутів провайдера, які core має класифікувати до завантаження runtime провайдера.
`providerRequest`	Ні	`object`	Дешеві метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження runtime провайдера.
`cliBackends`	Ні	`string[]`	Ідентифікатори backend-ів CLI inference, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації.
`syntheticAuthRefs`	Ні	`string[]`	Посилання на провайдера або backend CLI, для яких синтетичний хук автентифікації, що належить Plugin, слід перевіряти під час холодного виявлення моделей до завантаження runtime.
`nonSecretAuthMarkers`	Ні	`string[]`	Значення-заповнювачі API-ключів, що належать вбудованому Plugin і представляють несекретний локальний, OAuth або навколишній стан облікових даних.
`commandAliases`	Ні	`object[]`	Назви команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime.
`providerAuthEnvVars`	Ні	`Record<string, string[]>`	Застарілі сумісні метадані env для пошуку автентифікації/стану провайдера. Для нових Plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це поле протягом періоду deprecation.
`providerAuthAliases`	Ні	`Record<string, string>`	Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, що спільно використовує API-ключ і профілі автентифікації базового провайдера.
`channelEnvVars`	Ні	`Record<string, string[]>`	Дешеві env-метадані каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу на основі env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації.
`providerAuthChoices`	Ні	`object[]`	Дешеві метадані вибору автентифікації для засобів вибору під час онбордингу, визначення бажаного провайдера та простого підключення прапорців CLI.
`activation`	Ні	`object`	Дешеві метадані планувальника активації для завантаження, спричиненого запуском, провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; runtime Plugin усе одно володіє фактичною поведінкою.
`setup`	Ні	`object`	Дешеві дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin.
`qaRunners`	Ні	`object[]`	Дешеві дескриптори QA runner, що використовуються спільним хостом `openclaw qa` до завантаження runtime Plugin.
`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>`	Дешеві метадані доступності для інструментів, що належать Plugin і оголошені в `contracts.tools`. Використовуйте це, коли інструмент не повинен завантажувати runtime, якщо немає доказів конфігурації, env або автентифікації.
`channelConfigs`	Ні	`Record<string, object>`	Метадані конфігурації каналу, що належать маніфесту й об’єднуються з поверхнями виявлення та перевірки до завантаження runtime.
`skills`	Ні	`string[]`	Каталоги Skills для завантаження, відносно кореня Plugin.
`name`	Ні	`string`	Зрозуміла для людини назва Plugin.
`description`	Ні	`string`	Короткий опис, що показується в поверхнях Plugin.
`version`	Ні	`string`	Інформаційна версія Plugin.
`uiHints`	Ні	`Record<string, object>`	Мітки інтерфейсу, заповнювачі та підказки щодо чутливості для полів конфігурації.

Довідник метаданих провайдера генерації

Поля метаданих провайдера генерації описують статичні сигнали автентифікації для провайдерів, оголошених у відповідному списку contracts.*GenerationProviders. OpenClaw читає ці поля до завантаження середовища виконання провайдера, щоб основні інструменти могли визначити, чи доступний провайдер генерації, без імпорту кожного Plugin провайдера. Використовуйте ці поля лише для дешевих декларативних фактів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації залишаються в середовищі виконання 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 міг уникати імпорту середовища виконання 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, а не змушувати core імпортувати середовище виконання, щоб запитати.

Довідник providerAuthChoices

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

Поле	Обов’язкове	Тип	Що це означає
`provider`	Так	`string`	Ідентифікатор провайдера, якому належить цей варіант.
`method`	Так	`string`	Ідентифікатор методу автентифікації, до якого потрібно передати виконання.
`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 може дешево оголосити, які події площини керування мають включати його до плану активації/завантаження. Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє runtime-поведінку, не замінює register(...) і не гарантує, що код Plugin уже виконано. Планувальник активації використовує ці поля, щоб звузити список кандидатів Plugin перед поверненням до наявних метаданих володіння в маніфесті, таких як providers, channels, commandAliases, setup.providers, contracts.tools і хуки. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте 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, тому відсутні метадані активації не для запуску зазвичай лише впливають на продуктивність; це не має змінювати коректність, доки fallback-и володіння з маніфесту все ще існують. Кожен Plugin має задавати activation.onStartup навмисно. Установіть його в true лише тоді, коли Plugin має запускатися під час старту Gateway. Установіть його в false, коли Plugin інертний під час старту й має завантажуватися лише за вужчими тригерами. Пропуск onStartup більше не завантажує Plugin під час старту неявно; використовуйте явні метадані активації для старту, каналу, конфігурації, agent-harness, пам’яті або інших вужчих тригерів активації.

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

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

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

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

Діагностика планувальника може відрізняти явні підказки активації від fallback володіння з маніфесту. Наприклад, activation-command-hint означає, що збігся activation.onCommands, тоді як manifest-command-alias означає, що планувальник використав володіння commandAliases натомість. Ці reason-мітки призначені для діагностики хоста й тестів; автори 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`	Fallback-текст довідки, який використовується, коли спільному хосту потрібна команда-заглушка.

довідник 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 залишається чинним і надалі описує backend-и CLI inference. setup.cliBackends є специфічною для setup поверхнею дескрипторів для потоків площини керування/setup, які мають залишатися лише метаданими. Коли setup.providers і setup.cliBackends присутні, вони є пріоритетною поверхнею lookup за принципом descriptor-first для виявлення setup. Якщо дескриптор лише звужує кандидатний Plugin, а setup все ще потребує багатших runtime-хуків під час setup, установіть requiresRuntime: true і залиште setup-api як fallback-шлях виконання. OpenClaw також включає setup.providers[].envVars до загальних lookup для auth provider і env-var. providerAuthEnvVars лишається підтримуваним через адаптер сумісності під час періоду вилучення, але невбудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin мають розміщувати env-метадані setup/status у setup.providers[].envVars. OpenClaw також може виводити прості варіанти setup з setup.providers[].authMethods, коли немає доступного setup entry або коли setup.requiresRuntime: false оголошує, що runtime setup не потрібен. Явні записи providerAuthChoices залишаються пріоритетними для користувацьких міток, CLI-прапорів, області onboarding і метаданих assistant. Установлюйте requiresRuntime: false лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw розглядає явне false як descriptor-only контракт і не виконуватиме setup-api або openclaw.setupEntry для lookup setup. Якщо descriptor-only Plugin усе ще постачає один із цих runtime entry для setup, OpenClaw повідомляє additive-діагностику й продовжує ігнорувати його. Пропущений requiresRuntime зберігає застарілу fallback-поведінку, щоб наявні Plugin, які додали дескриптори без прапора, не ламалися. Оскільки lookup setup може виконувати код setup-api, яким володіє Plugin, нормалізовані значення setup.providers[].id і setup.cliBackends[] мають залишатися унікальними серед виявлених Plugin. Неоднозначне володіння завершується закрито замість вибору переможця за порядком виявлення. Коли runtime setup виконується, діагностика registry setup повідомляє про drift дескрипторів, якщо setup-api реєструє provider або CLI backend, які дескриптори маніфесту не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. Ці діагностики additive й не відхиляють застарілі Plugin.

довідник setup.providers

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

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

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

поля setup

Поле	Обов’язкове	Тип	Що це означає
`providers`	Ні	`object[]`	Дескриптори налаштування провайдера, доступні під час налаштування та онбордингу.
`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`	Текст-заповнювач для полів форми.

довідник 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 може реєструвати проміжне ПЗ результатів інструментів.
`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 не можуть реєструвати проміжне ПЗ результатів інструментів, оскільки ця точка інтеграції може переписувати високодовірений вивід інструмента до того, як модель його побачить. Реєстрації середовища виконання api.registerTool(...) мають відповідати contracts.tools. Виявлення інструментів використовує цей список, щоб завантажувати лише ті середовища виконання Plugin, які можуть володіти запитаними інструментами. Plugins провайдерів, які реалізують resolveExternalAuthProfiles, мають оголошувати contracts.externalAuthProviders. Plugins без цього оголошення все ще проходять через застарілий резервний шлях сумісності, але цей шлях повільніший і буде видалений після вікна міграції. Вбудовані провайдери embedding пам’яті мають оголошувати contracts.memoryEmbeddingProviders для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як local. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажити лише Plugin-власник до того, як повне середовище виконання Gateway зареєструє провайдерів.

довідник mediaUnderstandingProviderMetadata

Використовуйте mediaUnderstandingProviderMetadata, коли провайдер розуміння медіа має моделі за замовчуванням, пріоритет резервного auto-auth або нативну підтримку документів, які загальним допоміжним засобам ядра потрібні до завантаження середовища виконання. Ключі також мають бути оголошені в 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>`	Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних.
`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, але схема конфігурації холодного шляху, налаштування та поверхні Control UI не можуть знати форму параметрів, що належать каналу, доки середовище виконання Plugin не виконається. channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled і nativeSkillsAutoEnabled можуть оголошувати статичні типові значення auto для перевірок конфігурації команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі типові значення через package.json#openclaw.channel.commands разом з іншими метаданими каталогу каналів, що належать їхньому пакету.

{
  "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`	Статична нативна команда та автоматичні стандартні значення нативної навички для перевірок до runtime.
`preferOver`	`string[]`	Ідентифікатори застарілих або нижчопріоритетних plugin, які цей канал має випереджати в поверхнях вибору.

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

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

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

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

Довідник modelSupport

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

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

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

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

Поля:

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

Довідник modelCatalog

Використовуйте modelCatalog, коли OpenClaw має знати метадані моделей provider до завантаження plugin runtime. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, псевдонімів provider, правил придушення та режиму виявлення. Runtime-оновлення все ще належить коду runtime provider, але маніфест повідомляє 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>`	Рядки каталогу для ідентифікаторів provider, що належать цьому plugin. Ключі також мають бути в `providers` верхнього рівня.
`aliases`	`Record<string, object>`	Псевдоніми provider, які мають розв’язуватися в належний provider для планування каталогу або придушення.
`suppressions`	`object[]`	Рядки моделей з іншого джерела, які цей plugin придушує з причини, специфічної для provider.
`discovery`	`Record<string, "static" \| "refreshable" \| "runtime">`	Чи можна прочитати каталог provider з метаданих маніфесту, оновити в кеш або чи він потребує runtime.

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

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

Поля моделі:

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

Поля придушення:

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

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

Довідник modelIdNormalization

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

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

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

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

Довідник providerEndpoints

Використовуйте providerEndpoints для класифікації endpoint, яку generic request policy має знати до завантаження provider runtime. Core усе ще володіє значенням кожного endpointClass; маніфести plugin володіють metadata host і base URL. Поля endpoint:

Поле	Тип	Що це означає
`endpointClass`	`string`	Відомий core endpoint class, як-от `openrouter`, `moonshot-native` або `google-vertex`.
`hosts`	`string[]`	Точні hostnames, які відповідають endpoint class.
`hostSuffixes`	`string[]`	Host suffixes, які відповідають endpoint class. Додавайте `.` на початку для збігу лише за domain suffix.
`baseUrls`	`string[]`	Точні нормалізовані HTTP(S) base URLs, які відповідають endpoint class.
`googleVertexRegion`	`string`	Статичний регіон Google Vertex для точних global hosts.
`googleVertexRegionHostSuffix`	`string`	Suffix, який потрібно відкинути з matching hosts, щоб показати prefix регіону Google Vertex.

Довідник providerRequest

Використовуйте providerRequest для дешевої metadata сумісності запитів, потрібної generic request policy без завантаження provider runtime. Тримайте переписування payload, специфічне для поведінки, у runtime hooks провайдера або спільних provider-family helpers.

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

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

Поле	Тип	Що це означає
`family`	`string`	Мітка provider family, яку використовують generic request compatibility decisions і diagnostics.
`compatibilityFamily`	`"moonshot"`	Необов’язковий provider-family compatibility bucket для спільних request helpers.
`openAICompletions`	`object`	OpenAI-compatible completions request flags, наразі `supportsStreamingUsage`.

Довідник modelPricing

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

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

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

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

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

Поле	Тип	Що це означає
`provider`	`string`	External catalog provider id, коли він відрізняється від provider id OpenClaw, наприклад `z-ai` для провайдера `zai`.
`passthroughProviderModel`	`boolean`	Обробляйте model ids зі slash як вкладені refs provider/model; корисно для proxy providers, таких як OpenRouter.
`modelIdTransforms`	`"version-dots"[]`	Додаткові external catalog model-id variants. `version-dots` пробує dotted version ids, як-от `claude-opus-4.6`.

OpenClaw Provider Index

OpenClaw Provider Index — це preview metadata, що належить OpenClaw, для провайдерів, plugins яких можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для встановлених plugins. Provider Index — це внутрішній fallback contract, який майбутні поверхні installable-provider і pre-install model picker використовуватимуть, коли provider plugin не встановлено. Порядок авторитетності каталогу:

Конфігурація користувача.
modelCatalog маніфесту встановленого plugin.
Model catalog cache з explicit refresh.
Preview rows OpenClaw Provider Index.

Provider Index не має містити secrets, enabled state, runtime hooks або live account-specific model data. Його preview catalogs використовують таку саму форму provider row modelCatalog, що й маніфести plugin, але мають залишатися обмеженими stable display metadata, якщо runtime adapter fields, як-от api, baseUrl, pricing або compatibility flags, не підтримуються навмисно узгодженими з маніфестом встановленого plugin. Провайдери з live /models discovery мають записувати refreshed rows через explicit model catalog cache path замість того, щоб нормальний listing або onboarding викликав provider APIs. Записи Provider Index також можуть містити metadata installable-plugin для провайдерів, plugin яких переміщено з core або ще не встановлено з іншої причини. Ця metadata віддзеркалює channel catalog pattern: package name, npm install spec, expected integrity і дешеві auth-choice labels достатні, щоб показати installable setup option. Після встановлення plugin його маніфест має пріоритет, а запис Provider Index для цього провайдера ігнорується. Legacy top-level capability keys застаріли. Використовуйте openclaw doctor --fix, щоб перемістити speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders і webSearchProviders під contracts; normal manifest loading більше не розглядає ці top-level fields як capability ownership.

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

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

Файл	Для чого використовувати
`openclaw.plugin.json`	Discovery, config validation, auth-choice metadata та UI hints, які мають існувати до запуску коду plugin
`package.json`	npm metadata, dependency installation і блок `openclaw`, який використовується для entrypoints, install gating, setup або catalog metadata

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

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

Поля package.json, які впливають на discovery

Частина pre-runtime plugin metadata навмисно живе в package.json у блоці openclaw, а не в openclaw.plugin.json. openclaw.bundle і openclaw.bundle.json не є plugin contracts OpenClaw; native plugins мають використовувати openclaw.plugin.json плюс підтримувані поля package.json#openclaw нижче. Важливі приклади:

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

Метадані manifest визначають, які варіанти provider/channel/setup з’являються в onboarding до завантаження runtime. package.json#openclaw.install повідомляє onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в openclaw.plugin.json. openclaw.install.minHostVersion застосовується під час встановлення та завантаження реєстру manifest для невбудованих джерел Plugin. Недійсні значення відхиляються; новіші, але дійсні значення пропускають зовнішні plugins на старіших хостах. Вбудовані вихідні plugins вважаються співверсійними з checkout хоста. Офіційні метадані встановлення на вимогу мають використовувати clawhubSpec, коли Plugin опубліковано на ClawHub; onboarding трактує це як бажане віддалене джерело та записує факти артефакта ClawHub після встановлення. npmSpec залишається сумісним fallback для пакетів, які ще не перейшли на ClawHub. Точне закріплення версії npm уже міститься в npmSpec, наприклад "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Офіційні зовнішні записи каталогу мають поєднувати точні specs з expectedIntegrity, щоб потоки оновлення завершувалися закрито, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний onboarding і далі пропонує довірені specs npm registry, включно з голими назвами пакетів і dist-tags, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, integrity-pinned, missing-integrity, package-name mismatch і недійсні джерела default-choice. Вона також попереджає, коли expectedIntegrity наявний, але немає дійсного джерела npm, яке він може закріпити. Коли expectedIntegrity наявний, потоки встановлення/оновлення застосовують його; коли його опущено, розв’язання registry записується без закріплення цілісності. Plugins каналів мають надавати openclaw.setupEntry, коли status, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного runtime. Точка входу налаштування має відкривати метадані каналу плюс setup-safe config, status і secrets adapters; тримайте мережеві clients, gateway listeners і transport runtimes в основній точці входу extension. Поля точки входу runtime не перевизначають перевірки меж пакета для полів вихідної точки входу. Наприклад, openclaw.runtimeExtensions не може зробити шлях openclaw.extensions, що виходить за межі, придатним до завантаження. openclaw.install.allowInvalidConfigRecovery навмисно вузький. Він не робить довільні зламані configs придатними для встановлення. Сьогодні він лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого Plugin, як-от відсутній шлях вбудованого Plugin або застарілий запис channels.<id> для того самого вбудованого Plugin. Непов’язані помилки config усе ще блокують встановлення та спрямовують операторів до openclaw doctor --fix. openclaw.channel.persistedAuthState — це метадані пакета для крихітного модуля перевірки:

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

Використовуйте його, коли setup, doctor, status або потоки read-only presence потребують дешевої перевірки автентифікації yes/no до завантаження повного Plugin каналу. Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці метадані для автоматичного ввімкнення plugins, відновлення runtime dependencies або вирішення, чи має завантажуватися runtime каналу. Цільовий export має бути маленькою функцією, яка читає лише збережений стан; не спрямовуйте його через повний barrel runtime каналу. openclaw.channel.configuredState має таку саму форму для дешевих перевірок налаштованого стану лише через env:

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

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

Пріоритет виявлення (дублікати id Plugin)

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

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

Наслідки:

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

Вимоги JSON Schema

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

Приклад розширення schema:

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

Поведінка валідації

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

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

Примітки

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

Пов’язане

Створення plugins

Початок роботи з plugins.

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

Внутрішня архітектура та модель capability.

Огляд SDK

Довідник SDK для plugin та імпорти subpath.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Release and CI

Documentation Index

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

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

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

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

​Довідник метаданих провайдера генерації

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

​Довідник providerAuthChoices

​Довідник commandAliases

​довідник activation

​довідник qaRunners

​довідник setup

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

​поля setup

​довідник uiHints

​довідник contracts

​довідник mediaUnderstandingProviderMetadata

​довідник channelConfigs

​Заміна іншого plugin каналу

​Довідник modelSupport

​Довідник modelCatalog

​Довідник modelIdNormalization

​Довідник providerEndpoints

​Довідник providerRequest

​Довідник modelPricing

​OpenClaw Provider Index

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

​Поля package.json, які впливають на discovery

​Пріоритет виявлення (дублікати id Plugin)

​Вимоги JSON Schema

​Поведінка валідації

​Примітки

​Пов’язане

Створення plugins

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

Огляд SDK

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

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

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

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

Довідник метаданих провайдера генерації

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

Довідник providerAuthChoices

Довідник commandAliases

довідник activation

довідник qaRunners

довідник setup

довідник setup.providers

поля setup

довідник uiHints

довідник contracts

довідник mediaUnderstandingProviderMetadata

довідник channelConfigs

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

Довідник modelSupport

Довідник modelCatalog

Довідник modelIdNormalization

Довідник providerEndpoints

Довідник providerRequest

Довідник modelPricing

OpenClaw Provider Index

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

Поля package.json, які впливають на discovery

Пріоритет виявлення (дублікати id Plugin)

Вимоги JSON Schema

Поведінка валідації

Примітки

Пов’язане