---
read_when:
    - Ви створюєте Plugin для OpenClaw
    - Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin
summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації)
title: Маніфест Plugin
x-i18n:
    generated_at: "2026-04-14T20:31:17Z"
    model: gpt-5.4
    provider: openai
    source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730
    source_path: plugins/manifest.md
    workflow: 15
---

# Маніфест Plugin (`openclaw.plugin.json`)

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

Щоб дізнатися про сумісні макети bundle, див. [Пакети Plugin](/uk/plugins/bundles).

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

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

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

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

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

Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin).
Для власної моделі capability і поточних рекомендацій щодо зовнішньої сумісності:
[Модель capability](/uk/plugins/architecture#public-capability-model).

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

`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду
вашого plugin.

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

- ідентифікації plugin
- валідації конфігурації
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску
  середовища виконання plugin
- легких підказок активації, які поверхні площини керування можуть перевіряти до
  завантаження середовища виконання
- легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до
  завантаження середовища виконання
- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання plugin
- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати
  plugin до завантаження середовища виконання
- статичних знімків належності capability, що використовуються для bundled wiring сумісності та
  покриття контрактів
- легких метаданих виконувача QA, які спільний хост `openclaw qa` може перевіряти
  до завантаження середовища виконання plugin
- метаданих конфігурації, специфічних для channel, які мають об’єднуватися з поверхнями каталогу та валідації
  без завантаження середовища виконання
- підказок UI для конфігурації

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

- реєстрації поведінки середовища виконання
- оголошення точок входу коду
- метаданих встановлення npm

Це належить вашому коду plugin і `package.json`.

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

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

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

```json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["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 для конфігурації цього plugin.                                                                                                                                                          |
| `enabledByDefault`                  | Ні          | `true`                           | Позначає bundled plugin як увімкнений типово. Не вказуйте його або задайте будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим типово.                                                 |
| `legacyPluginIds`                   | Ні          | `string[]`                       | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin.                                                                                                                    |
| `autoEnableWhenConfiguredProviders` | Ні          | `string[]`                       | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на модель згадують їх.                                                                  |
| `kind`                              | Ні          | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`.                                                                                                                                   |
| `channels`                          | Ні          | `string[]`                       | Ідентифікатори channel, що належать цьому plugin. Використовуються для виявлення та валідації конфігурації.                                                                                                |
| `providers`                         | Ні          | `string[]`                       | Ідентифікатори provider, що належать цьому plugin.                                                                                                                                                           |
| `modelSupport`                      | Ні          | `object`                         | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автозавантаження plugin до середовища виконання.                                                                       |
| `cliBackends`                       | Ні          | `string[]`                       | Ідентифікатори backend CLI, що належать цьому plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації.                                                                  |
| `commandAliases`                    | Ні          | `object[]`                       | Імена команд, що належать цьому plugin і мають формувати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання.                                                        |
| `providerAuthEnvVars`               | Ні          | `Record<string, string[]>`       | Легкі метадані змінних середовища для автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin.                                                                                  |
| `providerAuthAliases`               | Ні          | `Record<string, string>`         | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку автентифікації, наприклад provider для кодування, що спільно використовує API key та профілі автентифікації базового provider. |
| `channelEnvVars`                    | Ні          | `Record<string, string[]>`       | Легкі метадані змінних середовища для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для поверхонь налаштування або автентифікації channel на основі змінних середовища, які мають бачити загальні допоміжні засоби запуску/конфігурації. |
| `providerAuthChoices`               | Ні          | `object[]`                       | Легкі метадані варіантів автентифікації для засобів вибору в онбордингу, визначення бажаного provider та простого зв’язування прапорців CLI.                                                                |
| `activation`                        | Ні          | `object`                         | Легкі підказки активації для завантаження, яке запускається provider, командою, channel, маршрутом і capability. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання plugin.   |
| `setup`                             | Ні          | `object`                         | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin.                                                           |
| `qaRunners`                         | Ні          | `object[]`                       | Легкі дескриптори виконувачів QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin.                                                                          |
| `contracts`                         | Ні          | `object`                         | Статичний bundled-знімок capability для speech, транскрибування в реальному часі, голосу в реальному часі, media-understanding, генерації зображень, генерації музики, генерації відео, web-fetch, web search і належності tools. |
| `channelConfigs`                    | Ні          | `Record<string, object>`         | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання.                                                              |
| `skills`                            | Ні          | `string[]`                       | Каталоги Skills для завантаження, відносно кореня plugin.                                                                                                                                                    |
| `name`                              | Ні          | `string`                         | Зрозуміла людині назва plugin.                                                                                                                                                                               |
| `description`                       | Ні          | `string`                         | Короткий опис, що показується на поверхнях plugin.                                                                                                                                                           |
| `version`                           | Ні          | `string`                         | Інформаційна версія plugin.                                                                                                                                                                                  |
| `uiHints`                           | Ні          | `Record<string, object>`         | Підписи UI, заповнювачі та підказки щодо чутливості для полів конфігурації.                                                                                                                                  |

## Довідник `providerAuthChoices`

Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
OpenClaw читає це до завантаження середовища виконання provider.

| Поле                 | Обов’язкове | Тип                                             | Що це означає                                                                                             |
| -------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `provider`           | Так         | `string`                                        | Ідентифікатор provider, якому належить цей варіант.                                                       |
| `method`             | Так         | `string`                                        | Ідентифікатор методу автентифікації, до якого слід спрямувати.                                            |
| `choiceId`           | Так         | `string`                                        | Стабільний ідентифікатор варіанта автентифікації, який використовується онбордингом і потоками CLI.      |
| `choiceLabel`        | Ні          | `string`                                        | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`.                                |
| `choiceHint`         | Ні          | `string`                                        | Короткий допоміжний текст для засобу вибору.                                                              |
| `assistantPriority`  | Ні          | `number`                                        | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих assistant.                    |
| `assistantVisibility`| Ні          | `"visible"` \| `"manual-only"`                  | Приховує варіант із засобів вибору assistant, але все ще дозволяє ручний вибір через 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 володіє назвою команди середовища виконання, яку користувачі можуть
помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
використовує ці метадані для діагностики без імпорту коду середовища виконання plugin.

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

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

## Довідник `activation`

Використовуйте `activation`, коли plugin може недорого оголосити, які події площини керування
мають активувати його пізніше.

## Довідник `qaRunners`

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

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

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

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

```json
{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}
```

| Поле             | Обов’язкове | Тип                                                  | Що це означає                                                       |
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `onProviders`    | Ні          | `string[]`                                           | Ідентифікатори provider, які мають активувати цей plugin за запитом. |
| `onCommands`     | Ні          | `string[]`                                           | Ідентифікатори команд, які мають активувати цей plugin.             |
| `onChannels`     | Ні          | `string[]`                                           | Ідентифікатори channel, які мають активувати цей plugin.            |
| `onRoutes`       | Ні          | `string[]`                                           | Типи маршрутів, які мають активувати цей plugin.                    |
| `onCapabilities` | Ні          | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються для планування активації площини керування. |

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

- планування CLI, що запускається командою, використовує застарілий резервний механізм
  `commandAliases[].cliCommand` або `commandAliases[].name`
- планування налаштування/channel, що запускається channel, використовує застарілий резервний механізм належності
  `channels[]`, коли явні метадані активації channel відсутні
- планування налаштування/середовища виконання, що запускається provider, використовує застарілий резервний механізм
  `providers[]` і належності верхньорівневих `cliBackends[]`, коли явні метадані
  активації provider відсутні

## Довідник `setup`

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

```json
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

Верхньорівневе `cliBackends` залишається валідним і, як і раніше, описує backend-и
інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup,
для потоків площини керування/setup, яка має залишатися лише метаданими.

За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку
для виявлення setup на основі дескрипторів. Якщо дескриптор лише звужує коло
потенційних plugin, а setup все ще потребує багатших hook середовища виконання під час setup,
установіть `requiresRuntime: true` і залиште `setup-api` як
резервний шлях виконання.

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

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

| Поле          | Обов’язкове | Тип        | Що це означає                                                                         |
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- |
| `id`          | Так         | `string`   | Ідентифікатор provider, який надається під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. |
| `authMethods` | Ні          | `string[]` | Ідентифікатори методів setup/автентифікації, які цей provider підтримує без завантаження повного середовища виконання. |
| `envVars`     | Ні          | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження середовища виконання plugin. |

### Поля `setup`

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

## Довідник `uiHints`

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

```json
{
  "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` лише для статичних метаданих належності capability, які OpenClaw може
читати без імпорту середовища виконання plugin.

```json
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

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

| Поле                             | Тип        | Що це означає                                               |
| -------------------------------- | ---------- | ----------------------------------------------------------- |
| `speechProviders`                | `string[]` | Ідентифікатори speech provider, якими володіє цей plugin.   |
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрибування в реальному часі, якими володіє цей plugin. |
| `realtimeVoiceProviders`         | `string[]` | Ідентифікатори provider голосу в реальному часі, якими володіє цей plugin. |
| `mediaUnderstandingProviders`    | `string[]` | Ідентифікатори provider media-understanding, якими володіє цей plugin. |
| `imageGenerationProviders`       | `string[]` | Ідентифікатори provider генерації зображень, якими володіє цей plugin. |
| `videoGenerationProviders`       | `string[]` | Ідентифікатори provider генерації відео, якими володіє цей plugin. |
| `webFetchProviders`              | `string[]` | Ідентифікатори provider web-fetch, якими володіє цей plugin. |
| `webSearchProviders`             | `string[]` | Ідентифікатори provider web search, якими володіє цей plugin. |
| `tools`                          | `string[]` | Назви tool агента, якими володіє цей plugin, для bundled-перевірок контрактів. |

## Довідник `channelConfigs`

Використовуйте `channelConfigs`, коли channel plugin потребує недорогих метаданих конфігурації
до завантаження середовища виконання.

```json
{
  "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",
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

Кожен запис channel може містити:

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

## Довідник `modelSupport`

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

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

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

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

Поля:

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

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

## Маніфест і `package.json`

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

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

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

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

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

Деякі метадані plugin до середовища виконання навмисно розміщуються в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.

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

| Поле                                                              | Що це означає                                                                                                                                 |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions`                                             | Оголошує власні точки входу plugin.                                                                                                          |
| `openclaw.setupEntry`                                             | Легка точка входу лише для setup, що використовується під час онбордингу та відкладеного запуску channel.                                   |
| `openclaw.channel`                                                | Легкі метадані каталогу channel, як-от підписи, шляхи до документації, псевдоніми та текст для вибору.                                      |
| `openclaw.channel.configuredState`                                | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. |
| `openclaw.channel.persistedAuthState`                             | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є хоч один вхід у систему?» без завантаження повного середовища виконання channel. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath`         | Підказки для встановлення/оновлення bundled plugin і plugin, опублікованих зовнішньо.                                                         |
| `openclaw.install.defaultChoice`                                  | Бажаний шлях установлення, коли доступно кілька джерел установлення.                                                                         |
| `openclaw.install.minHostVersion`                                 | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`.                                |
| `openclaw.install.allowInvalidConfigRecovery`                     | Дозволяє вузький шлях відновлення через перевстановлення bundled plugin, коли конфігурація невалідна.                                        |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного channel plugin під час запуску.                                         |

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

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

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

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

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

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

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

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

## Вимоги до схеми JSON

- **Кожен plugin повинен постачатися зі схемою JSON**, навіть якщо він не приймає жодної конфігурації.
- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання.

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

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

Див. [Довідник із конфігурації](/uk/gateway/configuration), щоб переглянути повну схему `plugins.*`.

## Примітки

- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для завантаження з локальної файлової системи.
- Середовище виконання все одно завантажує модуль plugin окремо; маніфест призначений лише для
  виявлення та валідації.
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, коми в кінці списку та
  ключі без лапок допускаються, якщо кінцеве значення все одно залишається об’єктом.
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
  власних ключів верхнього рівня сюди.
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації
  маркерів env і подібних поверхонь автентифікації provider, які не повинні запускати
  середовище виконання plugin лише для перевірки назв env.
- `providerAuthAliases` дає змогу варіантам provider повторно використовувати змінні середовища автентифікації,
  профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу
  з API key іншого provider без жорсткого кодування цього зв’язку в core.
- `channelEnvVars` — це недорогий шлях метаданих для резервного використання env оболонки, підказок
  setup і подібних поверхонь channel, які не повинні запускати середовище виконання plugin
  лише для перевірки назв env.
- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації,
  розв’язання `--auth-choice`, зіставлення бажаного provider і простої реєстрації
  прапорців CLI для онбордингу до завантаження середовища виконання provider. Для метаданих
  майстра середовища виконання, що потребують коду provider, див.
  [Hook середовища виконання provider](/uk/plugins/architecture#provider-runtime-hooks).
- Ексклюзивні типи plugin вибираються через `plugins.slots.*`.
  - `kind: "memory"` вибирається через `plugins.slots.memory`.
  - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
    (типово: вбудований `legacy`).
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо
  plugin їх не потребує.
- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та будь-які
  вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
  - `pnpm rebuild <package>`).

## Пов’язане

- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник із SDK Plugin
