---
read_when:
    - Вы создаёте плагин OpenClaw
    - Вам нужно выпустить схему конфигурации плагина или отладить ошибки проверки плагина
summary: Требования к манифесту плагина и схеме JSON (строгая проверка конфигурации)
title: Манифест плагина
x-i18n:
    generated_at: "2026-07-13T18:29:43Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: cd4ab5b10108585abb9a83a416b129e6f6351023016064b5d64b66aeabd04b2f
    source_path: plugins/manifest.md
    workflow: 16
---

На этой странице описан **нативный манифест плагина OpenClaw**, `openclaw.plugin.json`. Совместимые структуры пакетов (Codex, Claude, Cursor) см. в разделе [Пакеты плагинов](/ru/plugins/bundles).

Совместимые форматы пакетов используют вместо него собственные файлы манифестов:

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

OpenClaw автоматически обнаруживает эти структуры, но не проверяет их по приведённой ниже схеме `openclaw.plugin.json`. Если структура совместимого пакета соответствует требованиям среды выполнения OpenClaw, система считывает метаданные пакета, объявленные корневые каталоги навыков, корневые каталоги команд Claude, значения `settings.json` по умолчанию для Claude, настройки LSP по умолчанию для Claude и поддерживаемые наборы хуков.

Каждый нативный плагин OpenClaw **обязан** содержать `openclaw.plugin.json` в **корневом каталоге плагина**. OpenClaw считывает его для проверки конфигурации **без выполнения кода плагина**. Отсутствующий или недопустимый манифест блокирует проверку конфигурации и считается ошибкой плагина.

Полное руководство по системе плагинов см. в разделе [Плагины](/ru/tools/plugin), а описание нативной модели возможностей и текущие рекомендации по внешней совместимости — в разделе [Модель возможностей](/ru/plugins/architecture#public-capability-model).

## Назначение этого файла

`openclaw.plugin.json` — это метаданные, которые OpenClaw считывает **до загрузки кода вашего плагина**. Проверка всех содержащихся в нём данных должна выполняться без ресурсоёмкого запуска среды выполнения плагина.

**Используйте его для:**

- идентификации плагина, проверки конфигурации и подсказок интерфейса конфигурации
- метаданных аутентификации, первоначальной настройки и установки (псевдоним, автоматическое включение, переменные среды провайдера, варианты аутентификации)
- подсказок по активации для поверхностей плоскости управления
- сокращённого указания принадлежности семейств моделей
- статических снимков принадлежности возможностей (`contracts`)
- метаданных средства запуска контроля качества, доступных общему хосту `openclaw qa`
- метаданных конфигурации отдельных каналов, объединяемых с каталогом и поверхностями проверки

**Не используйте его для:** регистрации поведения среды выполнения, объявления точек входа кода или метаданных установки npm. Они должны находиться в коде вашего плагина и `package.json`.

## Минимальный пример

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

## Расширенный пример

```json
{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Плагин провайдера OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["OPENROUTER_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "API-ключ OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "API-ключ OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API-ключ",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}
```

## Справочник полей верхнего уровня

| Поле                                | Обязательно | Тип                         | Что означает                                                                                                                                                                                                                                                              |
| ------------------------------------ | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                 | Да      | `string`                     | Канонический идентификатор плагина. Этот идентификатор используется в `plugins.entries.<id>`.                                                                                                                                                                                                        |
| `configSchema`                       | Да      | `object`                     | Встроенная JSON Schema для конфигурации этого плагина.                                                                                                                                                                                                                               |
| `requiresPlugins`                    | Нет       | `string[]`                   | Идентификаторы плагинов, которые также должны быть установлены, чтобы этот плагин действовал. При обнаружении плагин остаётся доступным для загрузки, но выводится предупреждение, если отсутствует любой из обязательных плагинов.                                                                                                               |
| `enabledByDefault`                   | Нет       | `true`                       | Помечает встроенный плагин как включённый по умолчанию. Не указывайте это поле или задайте любое значение, кроме `true`, чтобы плагин по умолчанию оставался отключённым.                                                                                                                                               |
| `enabledByDefaultOnPlatforms`        | Нет       | `string[]`                   | Помечает встроенный плагин как включённый по умолчанию только на перечисленных платформах Node.js, например `["darwin"]`. Явная конфигурация по-прежнему имеет приоритет.                                                                                                                                   |
| `legacyPluginIds`                    | Нет       | `string[]`                   | Устаревшие идентификаторы, которые нормализуются в этот канонический идентификатор плагина.                                                                                                                                                                                                                     |
| `autoEnableWhenConfiguredProviders`  | Нет       | `string[]`                   | Идентификаторы провайдеров, при упоминании которых в данных аутентификации, конфигурации или ссылках на модели этот плагин должен включаться автоматически.                                                                                                                                                                            |
| `kind`                               | Нет       | `PluginKind \| PluginKind[]` | Объявляет один или несколько взаимоисключающих типов плагинов (`"memory"`, `"context-engine"`), используемых `plugins.slots.*`. Плагин, которому принадлежат оба слота, объявляет оба типа в одном массиве.                                                                                                    |
| `channels`                           | Нет       | `string[]`                   | Идентификаторы каналов, принадлежащих этому плагину. Используются для обнаружения и проверки конфигурации.                                                                                                                                                                                                |
| `providers`                          | Нет       | `string[]`                   | Идентификаторы провайдеров, принадлежащих этому плагину.                                                                                                                                                                                                                                         |
| `providerCatalogEntry`               | Нет       | `string`                     | Путь к облегчённому модулю каталога провайдеров относительно корня плагина для метаданных каталога провайдеров в области манифеста, которые можно загрузить без активации полной среды выполнения плагина.                                                                                        |
| `modelSupport`                       | Нет       | `object`                     | Принадлежащие манифесту сокращённые метаданные семейств моделей, используемые для автоматической загрузки плагина до запуска среды выполнения.                                                                                                                                                                                |
| `modelCatalog`                       | Нет       | `object`                     | Декларативные метаданные каталога моделей для провайдеров, принадлежащих этому плагину. Это контракт управляющего уровня для будущего списка только для чтения, первоначальной настройки, средств выбора моделей, псевдонимов и скрытия без загрузки среды выполнения плагина.                                                |
| `modelPricing`                       | Нет       | `object`                     | Принадлежащая провайдеру политика внешнего поиска цен. Используйте её, чтобы исключить локальных провайдеров и провайдеров с самостоятельным размещением из удалённых каталогов цен или сопоставить ссылки на провайдеров с идентификаторами каталогов OpenRouter/LiteLLM без жёсткого кодирования идентификаторов провайдеров в ядре.                                                    |
| `modelIdNormalization`               | Нет       | `object`                     | Принадлежащая провайдеру очистка псевдонимов и префиксов идентификаторов моделей, которая должна выполняться до загрузки среды выполнения провайдера.                                                                                                                                                                                  |
| `providerEndpoints`                  | Нет       | `object[]`                   | Принадлежащие манифесту метаданные хоста конечной точки и baseUrl для маршрутов провайдера, которые ядро должно классифицировать до загрузки среды выполнения провайдера.                                                                                                                                                   |
| `providerRequest`                    | Нет       | `object`                     | Легковесные метаданные семейства провайдеров и совместимости запросов, используемые общей политикой запросов до загрузки среды выполнения провайдера.                                                                                                                                                     |
| `secretProviderIntegrations`         | Нет       | `Record<string, object>`     | Декларативные предустановки exec-провайдеров SecretRef, которые интерфейсы настройки или установки могут предлагать без жёсткого кодирования специфичных для провайдера интеграций в ядре.                                                                                                                            |
| `cliBackends`                        | Нет       | `string[]`                   | Идентификаторы серверных компонентов инференса CLI, принадлежащих этому плагину. Используются для автоматической активации при запуске по явным ссылкам в конфигурации.                                                                                                                                                                |
| `syntheticAuthRefs`                  | Нет       | `string[]`                   | Ссылки на провайдеры или серверные компоненты CLI, для которых принадлежащий плагину хук синтетической аутентификации должен проверяться при холодном обнаружении моделей до загрузки среды выполнения.                                                                                                                                     |
| `nonSecretAuthMarkers`               | Нет       | `string[]`                   | Принадлежащие встроенному плагину значения-заполнители ключей API, представляющие несекретное локальное состояние, состояние OAuth или состояние учётных данных из окружения.                                                                                                                                                       |
| `commandAliases`                     | Нет       | `object[]`                   | Имена команд, принадлежащих этому плагину, для которых до загрузки среды выполнения должна формироваться диагностика конфигурации и CLI с учётом плагина.                                                                                                                                                       |
| `providerAuthEnvVars`                | Нет       | `Record<string, string[]>`   | Устаревшие метаданные переменных окружения для совместимости при поиске данных аутентификации и состояния провайдера. Для новых плагинов предпочитайте `setup.providers[].envVars`; OpenClaw продолжает читать эти данные в течение периода устаревания.                                                                                        |
| `providerUsageAuthEnvVars`           | Нет       | `Record<string, string[]>`   | Учётные данные провайдера только для данных об использовании и выставлении счетов. OpenClaw использует эти имена для обнаружения данных об использовании и удаления секретов, но никогда не использует их для аутентификации инференса.                                                                                                                                  |
| `providerAuthAliases`                | Нет       | `Record<string, string>`     | Идентификаторы провайдеров, которые должны использовать идентификатор другого провайдера для поиска данных аутентификации, например провайдер для программирования, использующий общий с базовым провайдером ключ API и профили аутентификации.                                                                                                                 |
| `channelEnvVars`                     | Нет       | `Record<string, string[]>`   | Легковесные метаданные переменных окружения канала, которые OpenClaw может проверять без загрузки кода плагина. Используйте их для управляемой переменными окружения настройки канала или интерфейсов аутентификации, которые должны быть доступны общим вспомогательным средствам запуска и конфигурации.                                                                                   |
| `providerAuthChoices`                | Нет       | `object[]`                   | Легковесные метаданные вариантов аутентификации для средств выбора при первоначальной настройке, определения предпочтительного провайдера и простого подключения флагов CLI.                                                                                                                                                              |
| `activation`                         | Нет       | `object`                     | Легковесные метаданные планировщика активации для загрузки, запускаемой при старте, обращении к провайдеру, команде, каналу, маршруту или возможности. Это только метаданные; фактическое поведение по-прежнему принадлежит среде выполнения плагина.                                                                                              |
| `setup`                              | Нет       | `object`                     | Легковесные дескрипторы настройки и первоначальной настройки, которые механизмы обнаружения и интерфейсы настройки могут проверять без загрузки среды выполнения плагина.                                                                                                                                                           |
| `qaRunners`                          | Нет       | `object[]`                   | Легковесные дескрипторы средства запуска QA, используемые общим хостом `openclaw qa` до загрузки среды выполнения плагина.                                                                                                                                                                             |
| `contracts`                          | Нет       | `object`                     | Статический снимок принадлежности возможностей для внешних хуков аутентификации, эмбеддингов, речи, транскрибирования в реальном времени, голосовой связи в реальном времени, понимания медиаконтента, генерации изображений, видео и музыки, веб-загрузки, веб-поиска, провайдеров рабочих процессов, извлечения содержимого документов и веб-страниц, а также принадлежности инструментов. |
| `configContracts`                    | Нет       | `object`                     | Определяемое манифестом поведение конфигурации, используемое универсальными вспомогательными средствами ядра: обнаружение опасных флагов, целевые параметры миграции SecretRef и сужение устаревших путей конфигурации. См. [справочник по configContracts](#configcontracts-reference).                                                     |
| `mediaUnderstandingProviderMetadata` | Нет       | `Record<string, object>`     | Легковесные значения по умолчанию для анализа медиаданных для идентификаторов провайдеров, объявленных в `contracts.mediaUnderstandingProviders`.                                                                                                                                                                   |
| `imageGenerationProviderMetadata`    | Нет       | `Record<string, object>`     | Легковесные метаданные аутентификации для генерации изображений для идентификаторов провайдеров, объявленных в `contracts.imageGenerationProviders`, включая принадлежащие провайдеру псевдонимы аутентификации и проверки базового URL.                                                                                                         |
| `videoGenerationProviderMetadata`    | Нет       | `Record<string, object>`     | Легковесные метаданные аутентификации для генерации видео для идентификаторов провайдеров, объявленных в `contracts.videoGenerationProviders`, включая принадлежащие провайдеру псевдонимы аутентификации и проверки базового URL.                                                                                                         |
| `musicGenerationProviderMetadata`    | Нет       | `Record<string, object>`     | Легковесные метаданные аутентификации для генерации музыки для идентификаторов провайдеров, объявленных в `contracts.musicGenerationProviders`, включая принадлежащие провайдеру псевдонимы аутентификации и проверки базового URL.                                                                                                         |
| `toolMetadata`                       | Нет       | `Record<string, object>`     | Легковесные метаданные доступности для принадлежащих плагину инструментов, объявленных в `contracts.tools`. Используйте их, если инструмент не должен загружать среду выполнения без наличия данных конфигурации, переменных окружения или аутентификации.                                                                                                  |
| `channelConfigs`                     | Нет       | `Record<string, object>`     | Принадлежащие манифесту метаданные конфигурации канала, объединяемые с поверхностями обнаружения и проверки до загрузки среды выполнения.                                                                                                                                                                 |
| `skills`                             | Нет       | `string[]`                   | Загружаемые каталоги Skills относительно корня плагина.                                                                                                                                                                                                                    |
| `name`                               | Нет       | `string`                     | Удобочитаемое имя плагина.                                                                                                                                                                                                                                                |
| `description`                        | Нет       | `string`                     | Краткое описание, отображаемое в интерфейсах плагинов.                                                                                                                                                                                                                                    |
| `catalog`                            | Нет       | `object`                     | Необязательные подсказки по представлению для интерфейсов каталога плагинов. Эти метаданные не устанавливают и не включают плагин, а также не предоставляют ему доверие.                                                                                                                                               |
| `icon`                               | Нет       | `string`                     | URL изображения по HTTPS для карточек магазина или каталога. ClawHub принимает любой допустимый URL `https://` и использует стандартный значок плагина, если значение не указано или недопустимо.                                                                                                         |
| `version`                            | Нет       | `string`                     | Информационная версия плагина.                                                                                                                                                                                                                                              |
| `uiHints`                            | Нет       | `Record<string, object>`     | Метки интерфейса, заполнители и указания на конфиденциальность полей конфигурации.                                                                                                                                                                                                          |

## Справочник по catalog

`catalog` предоставляет необязательные подсказки по отображению для каталогов плагинов. Хосты могут игнорировать эти подсказки. Они никогда не устанавливают и не включают плагин, а также не изменяют его поведение во время выполнения или уровень доверия.

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

| Поле      | Тип      | Значение                                                              |
| ---------- | --------- | -------------------------------------------------------------------------- |
| `featured` | `boolean` | Следует ли выделять этот плагин в интерфейсах каталога.                       |
| `order`    | `number`  | Подсказка по порядку отображения среди отобранных плагинов по возрастанию; меньшие значения отображаются раньше. |

## Справочник по метаданным провайдера генерации

Поля метаданных провайдера генерации описывают статические сигналы аутентификации для провайдеров, объявленных в соответствующем списке `contracts.*GenerationProviders`. OpenClaw считывает эти поля до загрузки среды выполнения провайдера, чтобы основные инструменты могли определить доступность провайдера генерации без импорта каждого плагина провайдера.

Используйте эти поля только для простых декларативных фактов. Транспорт, преобразования запросов, обновление токенов, проверка учётных данных и фактическое поведение генерации остаются в среде выполнения плагина.

```json
{
  "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`.                     |
| `referenceAudioInputs` | Нет       | `boolean`  | Только для генерации видео. Установите значение `true`, если провайдер принимает эталонные аудиоресурсы; в противном случае `video_generate` скрывает параметры эталонного аудио. |

Каждая запись `configSignals` поддерживает следующие поля:

| Поле            | Обязательно | Тип       | Значение                                                                                                                                                                             |
| ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rootPath`       | Да      | `string`   | Путь с точечной нотацией к принадлежащему плагину объекту конфигурации, который следует проверить, например `plugins.entries.example.config`.                                                                                      |
| `overlayPath`    | Нет       | `string`   | Путь с точечной нотацией внутри корневой конфигурации к объекту, который следует наложить на корневой объект перед оценкой сигнала. Используйте это для конфигурации конкретной возможности, например `image`, `video` или `music`.   |
| `overlayMapPath` | Нет       | `string`   | Путь с точечной нотацией внутри корневой конфигурации к объекту, каждое значение которого следует наложить на корневой объект. Используйте это для карт именованных учётных записей, таких как `accounts`, где достаточно любой настроенной учётной записи. |
| `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 мог не импортировать среду выполнения плагина лишь для того, чтобы фабрика инструмента вернула `null`.

```json
{
  "setup": {
    "providers": [
      {
        "id": "example",
        "envVars": ["EXAMPLE_API_KEY"]
      }
    ]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}
```

Записи `toolMetadata` также принимают `optional` (обозначает инструмент как необязательный для активации плагина) и `replaySafe` (обозначает выполнение инструмента как безопасное для повторения после незавершённого хода модели) в дополнение к общим полям `configSignals`/`authSignals`, описанным выше.

Если у инструмента нет `toolMetadata`, OpenClaw сохраняет существующее поведение и загружает владеющий им плагин, когда контракт инструмента соответствует политике. Для инструментов горячего пути, фабрика которых зависит от аутентификации или конфигурации, авторам плагинов следует объявлять `toolMetadata` вместо того, чтобы заставлять ядро импортировать среду выполнения для проверки.

## Справочник по 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`                                                              | Краткий поясняющий текст для группы.                                                                          |
| `onboardingFeatured`  | Нет       | `boolean`                                                             | Показывает эту группу на уровне рекомендуемых вариантов интерактивного списка первоначальной настройки перед пунктом "More...". |
| `optionKey`           | Нет       | `string`                                                              | Внутренний ключ параметра для простых процессов аутентификации с одним флагом.                                                       |
| `cliFlag`             | Нет       | `string`                                                              | Имя флага CLI, например `--openrouter-api-key`.                                                            |
| `cliOption`           | Нет       | `string`                                                              | Полная форма параметра CLI, например `--openrouter-api-key <key>`.                                              |
| `cliDescription`      | Нет       | `string`                                                              | Описание, используемое в справке CLI.                                                                             |
| `onboardingScopes`    | Нет       | `Array<"text-inference" \| "image-generation" \| "music-generation">` | В каких интерфейсах первоначальной настройки должен отображаться этот вариант. Если значение не указано, по умолчанию используется `["text-inference"]`.  |

## Справочник commandAliases

Используйте `commandAliases`, когда плагину принадлежит имя команды среды выполнения, которое пользователи могут по ошибке указать в `plugins.allow` или попытаться выполнить как корневую команду CLI. OpenClaw использует эти метаданные для диагностики, не импортируя код среды выполнения плагина.

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

| Поле        | Обязательно | Тип              | Значение                                                           |
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
| `name`       | Да      | `string`          | Имя команды, принадлежащей этому плагину.                               |
| `kind`       | Нет       | `"runtime-slash"` | Указывает, что псевдоним является слеш-командой чата, а не корневой командой CLI. |
| `cliCommand` | Нет       | `string`          | Связанная корневая команда CLI, которую следует предложить для операций CLI, если такая существует.  |

## Справочник activation

Используйте `activation`, если плагин может без существенных затрат объявить, при каких событиях плоскости управления его следует включать в план активации или загрузки.

Этот блок содержит метаданные планировщика, а не API жизненного цикла. Он не регистрирует поведение среды выполнения, не заменяет `register(...)` и не гарантирует, что код плагина уже был выполнен. Планировщик активации использует эти поля, чтобы сузить набор плагинов-кандидатов, прежде чем переходить к существующим метаданным владения из манифеста, таким как `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` и хуки.

Предпочитайте наиболее узкие метаданные, которые уже описывают владение. Используйте `providers`, `channels`, `commandAliases`, дескрипторы настройки или `contracts`, когда эти поля выражают соответствующую связь. Используйте `activation` для дополнительных подсказок планировщику, которые нельзя представить этими полями владения. Используйте `cliBackends` верхнего уровня для псевдонимов среды выполнения CLI, таких как `claude-cli`, `my-cli` или `google-gemini-cli`; `activation.onAgentHarnesses` предназначен только для идентификаторов встроенной среды агента, для которых ещё нет поля владения.

Каждый плагин должен задавать `activation.onStartup` явно. Устанавливайте значение `true` только тогда, когда плагин должен выполняться при запуске Gateway. Устанавливайте значение `false`, если плагин неактивен при запуске и должен загружаться только по более узким триггерам. Если `onStartup` не указан, плагин больше не загружается неявно при запуске; используйте явные метаданные активации для запуска, канала, конфигурации, среды агента, памяти или других более узких триггеров активации.

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

| Поле              | Обязательно | Тип                                                 | Значение                                                                                                                                                                               |
| ------------------ | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onStartup`        | Нет       | `boolean`                                            | Явная активация при запуске Gateway. Каждый плагин должен задавать это поле. `true` импортирует плагин при запуске; `false` сохраняет отложенную загрузку при запуске, если только другой совпавший триггер не потребует загрузки. |
| `onProviders`      | Нет       | `string[]`                                           | Идентификаторы провайдеров, при которых этот плагин следует включать в планы активации или загрузки.                                                                                                                      |
| `onAgentHarnesses` | Нет       | `string[]`                                           | Идентификаторы сред выполнения встроенных агентов, при которых этот плагин следует включать в планы активации или загрузки. Для псевдонимов бэкенда CLI используйте `cliBackends` верхнего уровня.                                           |
| `onCommands`       | Нет       | `string[]`                                           | Идентификаторы команд, при которых этот плагин следует включать в планы активации или загрузки.                                                                                                                       |
| `onChannels`       | Нет       | `string[]`                                           | Идентификаторы каналов, при которых этот плагин следует включать в планы активации или загрузки.                                                                                                                       |
| `onRoutes`         | Нет       | `string[]`                                           | Типы маршрутов, при которых этот плагин следует включать в планы активации или загрузки.                                                                                                                       |
| `onConfigPaths`    | Нет       | `string[]`                                           | Пути конфигурации относительно корня, при наличии которых и отсутствии явного отключения этот плагин следует включать в планы запуска или загрузки.                                                      |
| `onCapabilities`   | Нет       | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Общие подсказки о возможностях, используемые при планировании активации плоскостью управления. По возможности предпочитайте более узкие поля.                                                                                     |

Текущие активные потребители:

- Планирование запуска Gateway использует `activation.onStartup` для явного импорта при запуске.
- Планирование CLI, запускаемое командой, при необходимости возвращается к устаревшим `commandAliases[].cliCommand` или `commandAliases[].name`.
- Планирование запуска среды выполнения агента использует `activation.onAgentHarnesses` для встроенных сред и `cliBackends[]` верхнего уровня для псевдонимов среды выполнения CLI.
- Планирование настройки или канала, запускаемое каналом, при отсутствии явных метаданных активации канала возвращается к устаревшим метаданным владения `channels[]`.
- Планирование плагинов при запуске использует `activation.onConfigPaths` для корневых поверхностей конфигурации, не относящихся к каналам, например блока `browser` встроенного браузерного плагина.
- Планирование настройки или среды выполнения, запускаемое провайдером, при отсутствии явных метаданных активации провайдера возвращается к устаревшим метаданным владения `providers[]` и `cliBackends[]` верхнего уровня.

Диагностика планировщика может различать явные подсказки активации и резервное использование владения из манифеста. Например, `activation-command-hint` означает, что совпало `activation.onCommands`, а `manifest-command-alias` означает, что вместо этого планировщик использовал владение `commandAliases`. Эти метки причин предназначены для диагностики хоста и тестов; авторам плагинов следует продолжать объявлять метаданные, наиболее точно описывающие владение.

## Справочник qaRunners

Используйте `qaRunners`, когда плагин предоставляет один или несколько транспортных исполнителей в рамках
общего корня `openclaw qa`. Эти метаданные должны оставаться простыми и статическими; среда выполнения
плагина по-прежнему отвечает за фактическую регистрацию CLI через облегчённую
поверхность `runtime-api.ts`, экспортирующую соответствующие `qaRunnerCliRegistrations`. Необязательный
`adapterFactory` делает транспорт доступным для общих сценариев контроля качества, не
изменяя исполнитель зарегистрированной команды.

```json
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Запустить выполняемый в Docker сценарий интерактивного контроля качества Matrix с одноразовым домашним сервером"
    }
  ]
}
```

| Поле         | Обязательно | Тип     | Значение                                                      |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| `commandName` | Да      | `string` | Подкоманда, подключённая под `openclaw qa`, например `matrix`.    |
| `description` | Нет       | `string` | Резервный текст справки, используемый, когда общему хосту нужна команда-заглушка. |

Идентификатор `adapterFactory` должен соответствовать `commandName`. Не экспортируйте регистрации
для команд, отсутствующих в манифесте.

## Справочник setup

Используйте `setup`, когда интерфейсам настройки и первоначальной конфигурации нужны легковесные метаданные плагина до загрузки среды выполнения.

```json
{
  "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"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
```

Верхнеуровневое поле `cliBackends` остаётся допустимым и продолжает описывать серверные части логического вывода CLI. `setup.cliBackends` — это специальная для настройки поверхность дескрипторов для потоков плоскости управления и настройки, которая должна содержать только метаданные.

Если присутствуют `setup.providers` и `setup.cliBackends`, они являются предпочтительной поверхностью поиска на основе дескрипторов для обнаружения при настройке. Если дескриптор лишь сужает выбор плагина-кандидата, а для настройки всё ещё требуются более функциональные перехватчики среды выполнения, действующие во время настройки, задайте `requiresRuntime: true` и сохраните `setup-api` как резервный путь выполнения.

OpenClaw также включает `setup.providers[].envVars` в общие операции поиска аутентификации провайдера и переменных окружения. `providerAuthEnvVars` продолжает поддерживаться через адаптер совместимости в течение периода устаревания, однако несвязанные плагины, которые всё ещё его используют, получают диагностическое сообщение манифеста. Новые плагины должны размещать метаданные переменных окружения для настройки и состояния в `setup.providers[].envVars`.

Используйте `providerUsageAuthEnvVars`, когда учётные данные уровня биллинга или организации должны активировать `resolveUsageAuth`, не становясь учётными данными для логического вывода. Эти имена включаются в блокировку dotenv рабочей области, удаление из дочерних процессов ACP, фильтрацию секретов песочницы и общую очистку секретов. Среда выполнения провайдера по-прежнему считывает и классифицирует значение внутри `resolveUsageAuth`.

OpenClaw также может формировать простые варианты настройки на основе `setup.providers[].authMethods`, если запись настройки отсутствует или если `setup.requiresRuntime: false` объявляет среду выполнения настройки ненужной. Явные записи `providerAuthChoices` остаются предпочтительными для пользовательских меток, флагов CLI, области первоначальной конфигурации и метаданных ассистента.

Задавайте `requiresRuntime: false` только тогда, когда этих дескрипторов достаточно для интерфейса настройки. OpenClaw рассматривает явное значение `false` как контракт только на дескрипторы и не будет выполнять `setup-api` или `openclaw.setupEntry` для поиска при настройке. Если плагин, работающий только с дескрипторами, всё же поставляет одну из этих записей среды выполнения настройки, OpenClaw сообщает дополнительное диагностическое сообщение и продолжает её игнорировать. Если `requiresRuntime` не задано, сохраняется прежнее резервное поведение, чтобы не нарушить работу существующих плагинов, добавивших дескрипторы без этого флага.

Поскольку поиск при настройке может выполнять принадлежащий плагину код `setup-api`, нормализованные значения `setup.providers[].id` и `setup.cliBackends[]` должны оставаться уникальными среди обнаруженных плагинов. При неоднозначном владении операция завершается отказом, а не выбирает победителя на основе порядка обнаружения.

Когда среда выполнения настройки всё же запускается, диагностика реестра настройки сообщает о расхождении дескрипторов, если `setup-api` регистрирует провайдера или серверную часть CLI, не объявленную дескрипторами манифеста, либо если дескриптор не имеет соответствующей регистрации в среде выполнения. Эти диагностические сообщения являются дополнительными и не приводят к отклонению устаревших плагинов.

### Справочник setup.providers

| Поле          | Обязательно | Тип       | Значение                                                                                    |
| -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `id`           | Да      | `string`   | Идентификатор провайдера, предоставляемый при настройке или первоначальной конфигурации. Обеспечьте глобальную уникальность нормализованных идентификаторов.             |
| `authMethods`  | Нет       | `string[]` | Идентификаторы методов настройки и аутентификации, поддерживаемых этим провайдером без загрузки полной среды выполнения.                       |
| `envVars`      | Нет       | `string[]` | Переменные окружения, которые общие интерфейсы настройки и состояния могут проверять до загрузки среды выполнения плагина.               |
| `authEvidence` | Нет       | `object[]` | Легковесные локальные проверки признаков аутентификации для провайдеров, способных выполнять аутентификацию через несекретные маркеры. |

`authEvidence` предназначено для принадлежащих провайдеру локальных маркеров учётных данных, которые можно проверить без загрузки кода среды выполнения. Эти проверки должны оставаться легковесными и локальными: без сетевых вызовов, чтения связки ключей или менеджера секретов, команд оболочки и запросов к 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[]` | Идентификаторы миграций конфигурации, принадлежащие интерфейсу настройки этого плагина.                                          |
| `requiresRuntime`  | Нет       | `boolean`  | Требуется ли для настройки выполнение `setup-api` после поиска по дескриптору.                            |

## Справочник uiHints

`uiHints` — это сопоставление имён полей конфигурации с небольшими подсказками по отображению. В ключах можно использовать точки для вложенных полей конфигурации, но ни один сегмент пути не может быть `__proto__`, `constructor` или `prototype`; настройка отклоняет такие имена.

```json
{
  "uiHints": {
    "apiKey": {
      "label": "Ключ API",
      "help": "Используется для запросов OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
```

Каждая подсказка для поля может включать:

| Поле         | Тип       | Значение                           |
| ------------- | ---------- | --------------------------------------- |
| `label`       | `string`   | Отображаемая пользователю метка поля.                |
| `help`        | `string`   | Краткий вспомогательный текст.                      |
| `tags`        | `string[]` | Необязательные теги пользовательского интерфейса.                       |
| `advanced`    | `boolean`  | Помечает поле как расширенное.            |
| `sensitive`   | `boolean`  | Помечает поле как секретное или конфиденциальное. |
| `placeholder` | `string`   | Текст-заполнитель для полей ввода формы.       |

## Справочник contracts

Используйте `contracts` только для статических метаданных владения возможностями, которые OpenClaw может прочитать без импорта среды выполнения плагина.

```json
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "musicGenerationProviders": ["stability-audio"],
    "documentExtractors": ["example-docs"],
    "webContentExtractors": ["firecrawl"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "workerProviders": ["example-worker"],
    "usageProviders": ["acme-ai"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
```

Каждый список необязателен:

| Поле                            | Тип       | Что означает                                                                                                                        |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `embeddedExtensionFactories`     | `string[]` | Идентификаторы фабрик расширений сервера приложений Codex, в настоящее время `codex-app-server`.                                                                |
| `agentToolResultMiddleware`      | `string[]` | Идентификаторы сред выполнения, для которых этот плагин может регистрировать промежуточное ПО для результатов инструментов.                                                                     |
| `trustedToolPolicies`            | `string[]` | Локальные для плагина идентификаторы доверенных политик, применяемых перед вызовом инструмента, которые может регистрировать установленный плагин. Встроенные плагины могут регистрировать политики без этого поля. |
| `externalAuthProviders`          | `string[]` | Идентификаторы провайдеров, внешняя функция профиля аутентификации которых принадлежит этому плагину.                                                                      |
| `embeddingProviders`             | `string[]` | Идентификаторы провайдеров векторных представлений общего назначения, принадлежащих этому плагину и предназначенных для многократного использования векторных представлений, включая память.                                 |
| `speechProviders`                | `string[]` | Идентификаторы провайдеров речи, принадлежащих этому плагину.                                                                                                |
| `realtimeTranscriptionProviders` | `string[]` | Идентификаторы провайдеров транскрибирования в реальном времени, принадлежащих этому плагину.                                                                                |
| `realtimeVoiceProviders`         | `string[]` | Идентификаторы провайдеров голосовой связи в реальном времени, принадлежащих этому плагину.                                                                                        |
| `memoryEmbeddingProviders`       | `string[]` | Устаревшие идентификаторы провайдеров векторных представлений специально для памяти, принадлежащих этому плагину.                                                                  |
| `mediaUnderstandingProviders`    | `string[]` | Идентификаторы провайдеров анализа медиаданных, принадлежащих этому плагину.                                                                                   |
| `transcriptSourceProviders`      | `string[]` | Идентификаторы провайдеров источников расшифровок, принадлежащих этому плагину.                                                                                     |
| `documentExtractors`             | `string[]` | Идентификаторы провайдеров извлечения данных из документов (например, PDF), принадлежащих этому плагину.                                                                  |
| `imageGenerationProviders`       | `string[]` | Идентификаторы провайдеров генерации изображений, принадлежащих этому плагину.                                                                                      |
| `videoGenerationProviders`       | `string[]` | Идентификаторы провайдеров генерации видео, принадлежащих этому плагину.                                                                                      |
| `musicGenerationProviders`       | `string[]` | Идентификаторы провайдеров генерации музыки, принадлежащих этому плагину.                                                                                      |
| `webContentExtractors`           | `string[]` | Идентификаторы провайдеров извлечения содержимого веб-страниц, принадлежащих этому плагину.                                                                           |
| `webFetchProviders`              | `string[]` | Идентификаторы провайдеров загрузки веб-ресурсов, принадлежащих этому плагину.                                                                                             |
| `webSearchProviders`             | `string[]` | Идентификаторы провайдеров веб-поиска, принадлежащих этому плагину.                                                                                            |
| `workerProviders`                | `string[]` | Идентификаторы провайдеров облачных рабочих узлов, принадлежащих этому плагину и предназначенных для подготовки ресурсов и управления жизненным циклом аренды на основе профиля.                                      |
| `usageProviders`                 | `string[]` | Идентификаторы провайдеров, функции аутентификации использования и снимков использования которых принадлежат этому плагину.                                                             |
| `migrationProviders`             | `string[]` | Идентификаторы провайдеров импорта, принадлежащих этому плагину для `openclaw migrate`.                                                                         |
| `gatewayMethodDispatch`          | `string[]` | Зарезервированное разрешение для аутентифицированных HTTP-маршрутов плагина, которые диспетчеризуют методы Gateway внутри процесса.                                  |
| `tools`                          | `string[]` | Имена инструментов агента, принадлежащих этому плагину.                                                                                                   |

`contracts.embeddedExtensionFactories` сохраняется для встроенных фабрик расширений, работающих только с сервером приложений Codex. Встроенные преобразования результатов инструментов должны вместо этого объявлять `contracts.agentToolResultMiddleware` и регистрироваться с помощью `api.registerAgentToolResultMiddleware(...)`. Установленные плагины могут использовать тот же механизм промежуточного ПО только при явном включении и только для сред выполнения, объявленных ими в `contracts.agentToolResultMiddleware`.

Установленные плагины, которым требуется доверенный хостом уровень политики перед вызовом инструмента, должны объявить каждый регистрируемый локальный идентификатор в `contracts.trustedToolPolicies` и быть явно включены. Встроенные плагины сохраняют существующий путь доверенных политик, но установленные плагины с необъявленными идентификаторами политик отклоняются до регистрации. Идентификаторы политик ограничены областью регистрирующего плагина, поэтому два плагина могут объявить и зарегистрировать `workflow-budget`; один плагин не может дважды зарегистрировать один и тот же локальный идентификатор.

Регистрации `api.registerTool(...)` среды выполнения должны соответствовать `contracts.tools`. Обнаружение инструментов использует этот список, чтобы загружать только те среды выполнения плагинов, которым могут принадлежать запрошенные инструменты.

Плагины провайдеров, реализующие `resolveExternalAuthProfiles`, должны объявлять `contracts.externalAuthProviders`; необъявленные функции внешней аутентификации игнорируются.

Плагины провайдеров, реализующие одновременно `resolveUsageAuth` и `fetchUsageSnapshot`, должны объявить каждый автоматически обнаруживаемый идентификатор провайдера в `contracts.usageProviders`. Механизм обнаружения использования читает этот контракт до загрузки кода среды выполнения, а затем проверяет обе функции после загрузки только объявленных владельцев.

Провайдеры векторных представлений общего назначения должны объявлять `contracts.embeddingProviders` для каждого адаптера, зарегистрированного с помощью `api.registerEmbeddingProvider(...)`. Используйте общий контракт для многократно используемой генерации векторов, включая провайдеров, используемых поиском по памяти. `contracts.memoryEmbeddingProviders` — устаревший механизм совместимости, относящийся только к памяти; он сохраняется лишь на время миграции существующих провайдеров на общий механизм провайдеров векторных представлений.

Провайдеры рабочих узлов должны объявить каждый идентификатор `api.registerWorkerProvider(...)` в `contracts.workerProviders`. Ядро сохраняет устойчивое намерение перед вызовом `provision`; провайдеры проверяют свои настройки до внешнего выделения ресурсов, а повторные вызовы с тем же идентификатором операции должны принимать ту же аренду. Ядро также сохраняет снимок этих проверенных настроек и передаёт его с `leaseId` в `inspect({ leaseId, profile })` и `destroy({ leaseId, profile })`, в том числе после изменения или удаления именованного профиля. Уничтожение идемпотентно, проверка возвращает закрытое объединение состояний `active` / `destroyed` / `unknown`, а материал закрытого ключа SSH указывается только через `SecretRef`. Подготовленные конечные точки SSH также должны включать открытый `hostKey` из доверенного результата подготовки ресурсов точно в виде `algorithm base64`, без имени хоста или комментария, чтобы ядро могло закрепить хост перед подключением. Провайдеры, создающие динамические ссылки на удостоверения, могут реализовать авторитетный `resolveSshIdentity({ leaseId, profile, keyRef })`; для провайдеров без него используется универсальный механизм разрешения секретов ядра. Авторитетный `unknown` делает активную локальную запись потерянной; после сохранённого запроса на уничтожение он подтверждает завершение удаления ресурсов.

`contracts.gatewayMethodDispatch` в настоящее время принимает `"authenticated-request"`. Это механизм контроля чистоты API для нативных HTTP-маршрутов плагинов, которые намеренно диспетчеризуют методы плоскости управления Gateway внутри процесса, а не песочница для защиты от вредоносных нативных плагинов. Используйте его только для тщательно проверенных встроенных или операторских поверхностей, которые уже требуют HTTP-аутентификацию Gateway. Маршрут с таким разрешением остаётся доступным при закрытом допуске корневых работ Gateway, только если он также объявляет `auth: "gateway"` и специфичный для маршрута `gatewayRuntimeScopeSurface: "trusted-operator"`; обычные соседние маршруты того же плагина остаются за границей допуска. Это позволяет сохранять доступ к состоянию приостановки и возобновлению, не предоставляя всему плагину обход допуска. Ограничивайте синтаксический разбор и формирование ответа вне диспетчеризации; существенная работа или работа с изменением состояния должна выполняться через диспетчеризацию методов Gateway, которая отвечает за допуск и соблюдение областей действия.

## Справочник configContracts

Используйте `configContracts` для поведения конфигурации, принадлежащего манифесту и необходимого универсальным вспомогательным средствам ядра без импорта среды выполнения плагина: обнаружения опасных флагов, целей миграции SecretRef и сужения устаревших путей конфигурации.

```json
{
  "configContracts": {
    "compatibilityMigrationPaths": ["legacyProvider"],
    "compatibilityRuntimePaths": ["legacyProvider.webhook"],
    "dangerousFlags": [
      {
        "path": "accounts.*.allowUnverifiedSenders",
        "equals": true
      }
    ],
    "secretInputs": {
      "bundledDefaultEnabled": false,
      "paths": [
        {
          "path": "apiKey",
          "expected": "string"
        }
      ]
    }
  }
}
```

| Поле                         | Обязательно | Тип       | Что означает                                                                                                                                                                                                                          |
| ----------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compatibilityMigrationPaths` | Нет       | `string[]` | Пути конфигурации относительно корня, указывающие, что могут применяться миграции совместимости этого плагина на этапе настройки. Позволяет универсальному чтению конфигурации среды выполнения пропускать все поверхности настройки плагина, если конфигурация никогда не ссылается на этот плагин.                 |
| `compatibilityRuntimePaths`   | Нет       | `string[]` | Пути совместимости относительно корня, которые этот плагин может обслуживать во время выполнения до полной активации кода плагина. Используйте их для устаревших поверхностей, чтобы сузить наборы встроенных кандидатов без импорта каждой совместимой среды выполнения плагина. |
| `dangerousFlags`              | Нет       | `object[]` | Литералы конфигурации, которые `openclaw doctor` должен помечать как небезопасные или опасные при включении. См. ниже.                                                                                                                                   |
| `secretInputs`                | Нет       | `object`   | Пути конфигурации в `plugins.entries.<id>.config`, которые реестр целей миграции и аудита SecretRef должен рассматривать как строки в формате секрета. См. ниже.                                                                                  |

Каждая запись `dangerousFlags` поддерживает:

| Поле    | Обязательно | Тип                                  | Что означает                                                                                                       |
| -------- | -------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `path`   | Да      | `string`                              | Путь конфигурации с разделением точками относительно `plugins.entries.<id>.config`. Поддерживает подстановочные знаки `*` для сегментов отображений и массивов. |
| `equals` | Да      | `string \| number \| boolean \| null` | Точный литерал, отмечающий это значение конфигурации как опасное.                                                            |

`secretInputs` поддерживает:

| Поле                   | Обязательно | Тип       | Что означает                                                                                                                                                                                                   |
| ----------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bundledDefaultEnabled` | Нет       | `boolean`  | Переопределяет включение по умолчанию для встроенного плагина при определении активности этой поверхности SecretRef. Используйте это, если плагин встроен, но поверхность должна оставаться неактивной до явного включения в конфигурации. |
| `paths`                 | Да      | `object[]` | Пути конфигурации, содержащие секреты; каждый включает `path` (разделённый точками, относительно `plugins.entries.<id>.config`, поддерживает подстановочные знаки `*`) и необязательный `expected` (в настоящее время только `"string"`).                            |

## Справочник mediaUnderstandingProviderMetadata

Используйте `mediaUnderstandingProviderMetadata`, если у провайдера анализа медиаданных есть модели по умолчанию, приоритет резервного автоматического выбора на основе аутентификации или встроенная поддержка документов, необходимые универсальным вспомогательным средствам ядра до загрузки среды выполнения. Ключи также должны быть объявлены в `contracts.mediaUnderstandingProviders`.

```json
{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}
```

Каждая запись провайдера может включать:

| Поле                  | Тип                                                             | Что означает                                                                                                   |
| ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `capabilities`         | `("image" \| "audio" \| "video")[]`                              | Возможности обработки медиаданных, предоставляемые этим провайдером.                                                                    |
| `defaultModels`        | `Record<string, string>`                                         | Модели по умолчанию для каждой возможности, используемые, когда модель не указана в конфигурации.                                         |
| `autoPriority`         | `Record<string, number>`                                         | Меньшие числа располагаются раньше при автоматическом резервном выборе провайдера на основе учётных данных.                                    |
| `nativeDocumentInputs` | `"pdf"[]`                                                        | Входные форматы документов, изначально поддерживаемые провайдером.                                                               |
| `documentModels`       | `{ pdf?: { textExtraction?: string; image?: string \| false } }` | Переопределения моделей для каждого типа документа. Установите `image: false`, чтобы отключить извлечение на основе изображений для этого типа документа. |

## Справочник channelConfigs

Используйте `channelConfigs`, когда плагину канала нужны легковесные метаданные конфигурации до загрузки среды выполнения. Обнаружение настроек и состояния канала только для чтения может напрямую использовать эти метаданные для настроенных внешних каналов, когда запись настройки отсутствует или когда `setup.requiresRuntime: false` указывает, что среда выполнения настройки не требуется.

`channelConfigs` — это метаданные манифеста плагина, а не новый раздел верхнего уровня пользовательской конфигурации. Пользователи по-прежнему настраивают экземпляры каналов в `channels.<channel-id>`. OpenClaw читает метаданные манифеста, чтобы определить, какой плагин владеет настроенным каналом, до выполнения кода среды выполнения плагина.

Для плагина канала `configSchema` и `channelConfigs` описывают разные пути:

- `configSchema` проверяет `plugins.entries.<plugin-id>.config`
- `channelConfigs.<channel-id>.schema` проверяет `channels.<channel-id>`

Невстроенные плагины, объявляющие `channels[]`, также должны объявлять соответствующие записи `channelConfigs`. Без них OpenClaw всё равно может загрузить плагин, но схема конфигурации холодного пути, настройка и поверхности Control UI не смогут определить структуру параметров, принадлежащих каналу, до выполнения среды выполнения плагина.

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

```json
{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "URL домашнего сервера",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Подключение к домашнему серверу Matrix",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}
```

Каждая запись канала может включать:

| Поле         | Тип                     | Что означает                                                                             |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema`      | `object`                 | JSON Schema для `channels.<id>`. Обязательна для каждой объявленной записи конфигурации канала.         |
| `uiHints`     | `Record<string, object>` | Необязательные подписи интерфейса, заполнители и указания на конфиденциальность для этого раздела конфигурации канала.          |
| `label`       | `string`                 | Подпись канала, объединяемая с данными в поверхностях выбора и просмотра, когда метаданные среды выполнения ещё не готовы. |
| `description` | `string`                 | Краткое описание канала для поверхностей просмотра и каталога.                               |
| `commands`    | `object`                 | Статические значения автоматического включения по умолчанию для встроенных команд и Skills при проверках конфигурации до запуска среды выполнения.       |
| `preferOver`  | `string[]`               | Идентификаторы устаревших или менее приоритетных плагинов, которые этот канал должен опережать на поверхностях выбора.    |

### Замена другого плагина канала

Используйте `preferOver`, когда ваш плагин является предпочтительным владельцем идентификатора канала, который также может предоставлять другой плагин. Типичные случаи: переименованный идентификатор плагина, отдельный плагин, заменяющий встроенный, или поддерживаемый форк, сохраняющий тот же идентификатор канала для совместимости конфигурации.

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

Когда настроен `channels.chat`, OpenClaw учитывает как идентификатор канала, так и идентификатор предпочтительного плагина. Если плагин с меньшим приоритетом был выбран только потому, что он встроен или включён по умолчанию, OpenClaw отключает его в эффективной конфигурации среды выполнения, чтобы каналом и его инструментами владел один плагин. Явный выбор пользователя по-прежнему имеет приоритет: если пользователь явно включает оба плагина (через `plugins.allow` или существенную конфигурацию `plugins.entries`), OpenClaw сохраняет этот выбор и сообщает диагностические сведения о дублирующихся каналах и инструментах вместо скрытого изменения запрошенного набора плагинов.

Ограничивайте `preferOver` только идентификаторами плагинов, которые действительно могут предоставлять тот же канал. Это не общее поле приоритета, и оно не переименовывает ключи пользовательской конфигурации.

## Справочник modelSupport

Используйте `modelSupport`, когда OpenClaw должен определить ваш плагин провайдера по сокращённым идентификаторам моделей, таким как `gpt-5.6-sol` или `claude-sonnet-4.6`, до загрузки среды выполнения плагина.

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

OpenClaw применяет следующий порядок приоритетов:

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

Поля:

| Поле           | Тип       | Что означает                                                                   |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | Префиксы, сопоставляемые с сокращёнными идентификаторами моделей с помощью `startsWith`.                 |
| `modelPatterns` | `string[]` | Исходные регулярные выражения, сопоставляемые с сокращёнными идентификаторами моделей после удаления суффикса профиля. |

Записи `modelPatterns` компилируются через `compileSafeRegex`, который отклоняет шаблоны с вложенными повторениями (например, `(a+)+$`). Шаблоны, не прошедшие проверку безопасности, молча пропускаются, как и синтаксически некорректные регулярные выражения. Используйте простые шаблоны и избегайте вложенных квантификаторов.

## Справочник modelCatalog

Используйте `modelCatalog`, когда OpenClaw должен знать метаданные моделей провайдера до загрузки среды выполнения плагина. Это принадлежащий манифесту источник фиксированных строк каталога, псевдонимов провайдеров, правил исключения и режима обнаружения. Обновление во время выполнения по-прежнему относится к коду среды выполнения провайдера, но манифест сообщает ядру, когда среда выполнения необходима.

```json
{
  "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": "недоступно в Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}
```

Поля верхнего уровня:

| Поле             | Тип                                                      | Что означает                                                                                                               |
| ---------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `providers`      | `Record<string, object>`                                 | Строки каталога для идентификаторов провайдеров, принадлежащих этому плагину. Ключи также должны присутствовать в верхнеуровневом `providers`. |
| `aliases`        | `Record<string, object>`                                 | Псевдонимы провайдеров, которые при планировании каталога или подавления должны разрешаться в принадлежащего плагину провайдера. |
| `suppressions`   | `object[]`                                               | Строки моделей из другого источника, которые этот плагин подавляет по причине, относящейся к конкретному провайдеру.        |
| `discovery`      | `Record<string, "static" \| "refreshable" \| "runtime">` | Можно ли прочитать каталог провайдера из метаданных манифеста, обновить его в кэше или для него требуется среда выполнения. |
| `runtimeAugment` | `boolean`                                                | Устанавливайте значение `true` только тогда, когда среда выполнения провайдера должна добавить строки каталога после планирования манифеста и конфигурации. |

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

`suppressions` заменяет прежний обработчик среды выполнения провайдера `suppressBuiltInModel`. Записи подавления учитываются, только если провайдер принадлежит плагину или объявлен как ключ `modelCatalog.aliases`, указывающий на принадлежащего плагину провайдера. Обработчики подавления среды выполнения больше не вызываются при разрешении модели.

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

| Поле                  | Тип                      | Что означает                                                                                                                                                                                                                                   |
| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`             | `string`                 | Необязательный базовый URL по умолчанию для моделей в каталоге этого провайдера.                                                                                                                                                               |
| `api`                 | `ModelApi`               | Необязательный адаптер API по умолчанию для моделей в каталоге этого провайдера.                                                                                                                                                               |
| `headers`             | `Record<string, string>` | Необязательные статические заголовки, применяемые к каталогу этого провайдера.                                                                                                                                                                 |
| `defaultUtilityModel` | `string`                 | Необязательный рекомендуемый провайдером идентификатор небольшой модели для коротких внутренних служебных задач (заголовки, описание хода выполнения). Используется, когда `agents.defaults.utilityModel` не задан и этот провайдер обслуживает основную модель агента. |
| `models`              | `object[]`               | Обязательные строки моделей. Строки без `id` игнорируются.                                                                                                                                                                       |

Поля модели:

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

Поля подавления:

| Поле                       | Тип        | Что означает                                                                                                                       |
| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`   | Идентификатор провайдера для подавляемой вышестоящей строки. Должен принадлежать этому плагину или быть объявлен как принадлежащий ему псевдоним. |
| `model`                    | `string`   | Локальный для провайдера идентификатор подавляемой модели.                                                                          |
| `reason`                   | `string`   | Необязательное сообщение, отображаемое при прямом запросе подавленной строки.                                                       |
| `when.baseUrlHosts`        | `string[]` | Необязательный список хостов эффективных базовых URL провайдера, наличие которых требуется для применения подавления.               |
| `when.providerConfigApiIn` | `string[]` | Необязательный список точных значений `api` конфигурации провайдера, наличие которых требуется для применения подавления. |

Не помещайте данные, доступные только в среде выполнения, в `modelCatalog`. Используйте `static`, только если строки манифеста достаточно полны, чтобы списки с фильтрацией по провайдеру и интерфейсы выбора могли пропустить обнаружение реестра и среды выполнения. Используйте `refreshable`, когда строки манифеста полезны как доступные для перечисления начальные или дополнительные данные, но обновление или кэш может позднее добавить другие строки; обновляемые строки сами по себе не являются авторитетными. Используйте `runtime`, когда OpenClaw должен загрузить среду выполнения провайдера, чтобы получить список.

## Справочник modelIdNormalization

Используйте `modelIdNormalization` для недорогой очистки принадлежащих провайдеру идентификаторов моделей, которая должна выполняться до загрузки среды выполнения провайдера. Благодаря этому псевдонимы, например короткие имена моделей, прежние локальные идентификаторы провайдера и правила префиксов прокси, остаются в манифесте плагина-владельца, а не в основных таблицах выбора моделей.

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

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

| Поле                                 | Тип                     | Что означает                                                                                  |
| ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------- |
| `aliases`                            | `Record<string,string>` | Точные псевдонимы идентификаторов моделей без учета регистра. Значения возвращаются в исходном виде. |
| `stripPrefixes`                      | `string[]`              | Префиксы, удаляемые перед поиском псевдонима; полезны при прежнем дублировании провайдера и модели. |
| `prefixWhenBare`                     | `string`                | Префикс, добавляемый, если нормализованный идентификатор модели еще не содержит `/`. |
| `prefixWhenBareAfterAliasStartsWith` | `object[]`              | Условные правила добавления префикса к идентификатору без префикса после поиска псевдонима, сгруппированные по `modelPrefix` и `prefix`. |

## Справочник providerEndpoints

Используйте `providerEndpoints` для классификации конечных точек, которую общая политика запросов должна знать до загрузки среды выполнения провайдера. Основная система по-прежнему определяет значение каждого `endpointClass`; манифесты плагинов определяют метаданные хоста и базового URL.

Официально вынесенные во внешние пакеты плагины провайдеров исключены из основного дистрибутива, поэтому
их манифесты недоступны до установки. Их `providerEndpoints` также должны
дублироваться в `scripts/lib/official-external-provider-catalog.json`, чтобы
классификация конечных точек продолжала работать без плагина; соответствие копии
обеспечивается контрактным тестом.

Поля конечной точки:

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

## Справочник providerRequest

Используйте `providerRequest` для недорогих метаданных совместимости запросов, которые нужны общей политике запросов без загрузки среды выполнения провайдера. Перезапись полезной нагрузки, зависящую от поведения, оставляйте обработчикам среды выполнения провайдера или общим вспомогательным функциям семейства провайдеров.

```json
{
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}
```

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

| Поле                  | Тип          | Что означает                                                                           |
| --------------------- | ------------ | -------------------------------------------------------------------------------------- |
| `family`              | `string`     | Метка семейства провайдеров, используемая общими решениями о совместимости запросов и диагностикой. |
| `compatibilityFamily` | `"moonshot"` | Необязательная категория совместимости семейства провайдеров для общих вспомогательных функций запросов. |
| `openAICompletions`   | `object`     | Флаги запросов завершения, совместимых с OpenAI; в настоящее время `supportsStreamingUsage`.       |

## Справочник secretProviderIntegrations

Используйте `secretProviderIntegrations`, когда плагин может опубликовать многократно используемую предустановку exec-провайдера SecretRef. OpenClaw считывает эти метаданные до загрузки среды выполнения плагина, сохраняет принадлежность плагину в `secrets.providers.<alias>.pluginIntegration` и оставляет фактическое разрешение секретов среде выполнения SecretRef. Предустановки доступны только для встроенных плагинов и установленных плагинов, обнаруженных в управляемых корневых каталогах установки плагинов, например при установке через git и ClawHub.

```json
{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}
```

Ключ карты — идентификатор интеграции. Если `providerAlias` опущен, OpenClaw использует идентификатор интеграции как псевдоним провайдера SecretRef. Псевдонимы провайдеров должны соответствовать обычному шаблону псевдонима провайдера SecretRef, например `team-secrets` или `onepassword-work`.

Когда оператор выбирает предустановку, OpenClaw записывает ссылку на провайдера следующего вида:

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

При запуске или перезагрузке OpenClaw разрешает этот провайдер, загружая текущие метаданные манифеста плагина, проверяя, что плагин-владелец установлен и активен, и формируя команду exec из манифеста. Отключение или удаление плагина отзывает провайдер для активных SecretRef. Операторы, которым нужна автономная конфигурация exec, по-прежнему могут напрямую задавать вручную провайдеры `command`/`args`.

В настоящее время поддерживаются только предустановки `source: "exec"`. `command` должен иметь значение `${node}`, а `args[0]` должен быть скриптом разрешения `./` с путём относительно корневого каталога плагина. При запуске или перезагрузке OpenClaw преобразует его в текущий исполняемый файл Node и абсолютный путь к скрипту внутри плагина. Параметры Node, такие как `--require`, `--import`, `--loader`, `--env-file`, `--eval` и `--print`, не входят в контракт предустановки манифеста. Операторы, которым нужны команды не на Node, могут напрямую настроить автономные ручные exec-провайдеры.

OpenClaw формирует `trustedDirs` для предустановок манифеста из корневого каталога плагина, а для предустановок `${node}` — также из каталога текущего исполняемого файла Node. Заданные в манифесте `trustedDirs` игнорируются. Другие параметры exec-провайдера, такие как `timeoutMs`, `noOutputTimeoutMs`, `maxOutputBytes`, `jsonOnly`, `env`, `passEnv` и `allowInsecurePath`, передаются в обычную конфигурацию exec-провайдера SecretRef.

## Справочник modelPricing

Используйте `modelPricing`, когда провайдеру требуется управление ценообразованием на уровне управляющей плоскости до загрузки среды выполнения. Кэш цен Gateway считывает эти метаданные без импорта кода среды выполнения провайдера.

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

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

| Поле         | Тип               | Что означает                                                                                       |
| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- |
| `external`   | `boolean`         | Установите `false` для локальных или самостоятельно размещённых провайдеров, которые никогда не должны получать цены OpenRouter или LiteLLM. |
| `openRouter` | `false \| object` | Сопоставление для поиска цен OpenRouter. `false` отключает поиск OpenRouter для этого провайдера. |
| `liteLLM`    | `false \| object` | Сопоставление для поиска цен LiteLLM. `false` отключает поиск LiteLLM для этого провайдера. |

Поля источника:

| Поле                       | Тип                | Что означает                                                                                                         |
| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `provider`                 | `string`           | Идентификатор провайдера во внешнем каталоге, если он отличается от идентификатора провайдера OpenClaw, например `z-ai` для провайдера `zai`. |
| `passthroughProviderModel` | `boolean`          | Интерпретировать идентификаторы моделей с косой чертой как вложенные ссылки провайдер/модель; полезно для прокси-провайдеров, таких как OpenRouter. |
| `modelIdTransforms`        | `"version-dots"[]` | Дополнительные варианты идентификатора модели во внешнем каталоге. `version-dots` проверяет идентификаторы версий с точками, например `claude-opus-4.6`. |

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

Индекс провайдеров OpenClaw — это принадлежащие OpenClaw метаданные предварительного просмотра для провайдеров, плагины которых могут быть ещё не установлены. Он не является частью манифеста плагина. Манифесты плагинов остаются авторитетным источником сведений об установленных плагинах. Индекс провайдеров — это внутренний резервный контракт, который будущие интерфейсы устанавливаемых провайдеров и выбора моделей перед установкой будут использовать, когда плагин провайдера не установлен.

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

1. Пользовательская конфигурация.
2. Манифест установленного плагина `modelCatalog`.
3. Кэш каталога моделей после явного обновления.
4. Строки предварительного просмотра из индекса провайдеров OpenClaw.

Индекс провайдеров не должен содержать секреты, состояние включения, обработчики среды выполнения или актуальные данные моделей, зависящие от конкретной учётной записи. Его каталоги предварительного просмотра используют ту же структуру строки провайдера `modelCatalog`, что и манифесты плагинов, но должны ограничиваться стабильными отображаемыми метаданными, если только поля адаптера среды выполнения, такие как `api`, `baseUrl`, цены или флаги совместимости, намеренно не синхронизируются с манифестом установленного плагина. Провайдеры с динамическим обнаружением `/models` должны записывать обновлённые строки через явный путь кэша каталога моделей, а не вызывать API провайдера при обычном выводе списка или первоначальной настройке.

Записи индекса провайдеров также могут содержать метаданные устанавливаемого плагина для провайдеров, чей плагин был вынесен из ядра или по иной причине ещё не установлен. Эти метаданные соответствуют шаблону каталога каналов: имени пакета, спецификации установки npm, ожидаемой целостности и простых меток вариантов аутентификации достаточно для отображения устанавливаемого варианта настройки. После установки плагина приоритет получает его манифест, а запись индекса провайдеров для этого провайдера игнорируется.

`openclaw doctor --fix` переносит небольшой закрытый набор устаревших ключей возможностей верхнего уровня манифеста в `contracts.*`: `speechProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders` и `tools`. Ни один из них, как и любой другой список возможностей, больше не считывается как поле верхнего уровня манифеста; обычная загрузка манифеста распознаёт их только в `contracts`.

## Манифест и package.json

Эти два файла выполняют разные задачи:

| Файл                   | Для чего используется                                                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Обнаружение, проверка конфигурации, метаданные вариантов аутентификации и подсказки интерфейса, которые должны быть доступны до запуска кода плагина |
| `package.json`         | Метаданные npm, установка зависимостей и блок `openclaw`, используемый для точек входа, условий установки, настройки или метаданных каталога |

Если вы не уверены, где должны находиться определённые метаданные, используйте следующее правило:

- если OpenClaw должен знать их до загрузки кода плагина, поместите их в `openclaw.plugin.json`
- если они относятся к упаковке, входным файлам или поведению установки npm, поместите их в `package.json`

### Поля package.json, влияющие на обнаружение

Некоторые метаданные плагина, необходимые до запуска среды выполнения, намеренно хранятся в `package.json` в блоке `openclaw`, а не в `openclaw.plugin.json`. `openclaw.bundle` и `openclaw.bundle.json` не являются контрактами плагинов OpenClaw; нативные плагины должны использовать `openclaw.plugin.json` вместе с поддерживаемыми полями `package.json#openclaw`, перечисленными ниже.

Важные примеры:

| Поле                                                                                      | Что означает                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions`                                                                      | Объявляет нативные точки входа плагина. Они должны находиться внутри каталога пакета плагина.                                                                                                   |
| `openclaw.runtimeExtensions`                                                               | Объявляет точки входа собранной среды выполнения JavaScript для установленных пакетов. Они должны находиться внутри каталога пакета плагина.                                                                 |
| `openclaw.setupEntry`                                                                      | Облегчённая точка входа только для настройки, используемая при первоначальной настройке, отложенном запуске канала и доступном только для чтения обнаружении статуса канала и SecretRef. Она должна находиться внутри каталога пакета плагина. |
| `openclaw.runtimeSetupEntry`                                                               | Объявляет точку входа собранной настройки JavaScript для установленных пакетов. Требует `setupEntry`, должна существовать и находиться внутри каталога пакета плагина.                         |
| `openclaw.channel`                                                                         | Легковесные метаданные каталога каналов, например метки, пути к документации, псевдонимы и текст вариантов выбора.                                                                                                 |
| `openclaw.channel.commands`                                                                | Статические метаданные нативных команд и автоматически применяемых значений по умолчанию для нативных Skills, используемые в конфигурации, аудите и списках команд до загрузки среды выполнения канала.                                          |
| `openclaw.channel.configuredState`                                                         | Легковесные метаданные средства проверки настроенного состояния, позволяющие ответить на вопрос «существует ли уже настройка только через переменные среды?» без загрузки полной среды выполнения канала.                                         |
| `openclaw.channel.persistedAuthState`                                                      | Легковесные метаданные средства проверки сохранённой аутентификации, позволяющие ответить на вопрос «выполнен ли уже где-либо вход?» без загрузки полной среды выполнения канала.                                               |
| `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | Подсказки по установке и обновлению для встроенных и внешне опубликованных плагинов.                                                                                                                   |
| `openclaw.install.defaultChoice`                                                           | Предпочтительный способ установки при наличии нескольких источников установки.                                                                                                                  |
| `openclaw.install.minHostVersion`                                                          | Минимальная поддерживаемая версия хоста OpenClaw с нижней границей semver, например `>=2026.3.22` или `>=2026.5.1-beta.1`.                                                                             |
| `openclaw.compat.pluginApi`                                                                | Минимальный диапазон API плагинов OpenClaw, необходимый этому пакету, с нижней границей semver, например `>=2026.5.27`.                                                                                 |
| `openclaw.install.expectedIntegrity`                                                       | Ожидаемая строка целостности npm dist, например `sha512-...`; процессы установки и обновления сверяют с ней полученный артефакт.                                                            |
| `openclaw.install.allowInvalidConfigRecovery`                                              | Разрешает узкий сценарий восстановления путём переустановки встроенного плагина при недопустимой конфигурации.                                                                                                       |
| `openclaw.install.requiredPlatformPackages`                                                | Псевдонимы пакетов npm, которые должны быть установлены, когда их платформенные ограничения в lock-файле соответствуют текущему хосту.                                                                           |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`                          | Позволяет загружать поверхности настройки среды выполнения канала до начала прослушивания, а затем откладывает загрузку полного настроенного плагина канала до активации после начала прослушивания.                                                 |

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

`openclaw.install.minHostVersion` проверяется во время установки и загрузки реестра манифестов для источников невстроенных плагинов. Недопустимые значения отклоняются; более новые, но допустимые значения приводят к пропуску внешних плагинов на старых хостах. Предполагается, что версии встроенных исходных плагинов согласованы с версией рабочей копии хоста.

`openclaw.install.requiredPlatformPackages` предназначен для пакетов npm, предоставляющих необходимые нативные двоичные файлы через необязательные платформенные псевдонимы. Укажите базовое имя пакета npm для каждого поддерживаемого платформенного псевдонима. Во время установки npm OpenClaw проверяет только объявленный псевдоним, ограничения которого в lock-файле соответствуют текущему хосту. Если npm сообщает об успешной установке, но пропускает этот псевдоним, OpenClaw повторяет попытку один раз с новым кэшем и откатывает установку, если псевдоним по-прежнему отсутствует.

`openclaw.compat.pluginApi` проверяется во время установки пакета для источников невстроенных плагинов. Используйте его для указания нижней границы API SDK/среды выполнения плагинов OpenClaw, под которую был собран пакет. Она может быть строже, чем `minHostVersion`, когда пакету плагина нужен более новый API, но для других процессов он сохраняет более низкую подсказку по установке. Официальная синхронизация выпусков OpenClaw по умолчанию повышает существующие нижние границы API официальных плагинов до версии выпуска OpenClaw, однако выпуски только плагинов могут сохранять более низкую границу, если пакет намеренно поддерживает старые хосты. Не используйте только версию пакета в качестве контракта совместимости. `peerDependencies.openclaw` остаётся метаданными пакета npm; OpenClaw использует контракт `openclaw.compat.pluginApi` для принятия решений о совместимости при установке.

В официальных метаданных установки по требованию следует использовать `clawhubSpec`, если плагин опубликован в ClawHub; процесс первоначальной настройки рассматривает его как предпочтительный удалённый источник и после установки записывает сведения об артефакте ClawHub. `npmSpec` остаётся резервным вариантом совместимости для пакетов, которые ещё не перенесены в ClawHub.

Точная фиксация версии npm уже задаётся в `npmSpec`, например `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. В официальных записях внешнего каталога точные спецификации следует сочетать с `expectedIntegrity`, чтобы процессы обновления завершались с ошибкой, если полученный артефакт npm больше не соответствует зафиксированному выпуску. Для совместимости интерактивная первоначальная настройка по-прежнему предлагает доверенные спецификации npm из реестра, включая базовые имена пакетов и dist-теги. Диагностика каталога позволяет различать точные, плавающие, закреплённые по целостности источники, источники без данных о целостности, с несовпадением имени пакета, а также недопустимые источники выбора по умолчанию. Она также предупреждает, когда присутствует `expectedIntegrity`, но нет допустимого источника npm, к которому его можно привязать. Если присутствует `expectedIntegrity`, процессы установки и обновления обеспечивают его соблюдение; если он отсутствует, результат разрешения через реестр записывается без фиксации целостности.

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

Поля точек входа среды выполнения не отменяют проверки границ пакета для полей исходных точек входа. Например, `openclaw.runtimeExtensions` не может сделать доступным для загрузки путь `openclaw.extensions`, выходящий за границы пакета.

`openclaw.install.allowInvalidConfigRecovery` намеренно имеет узкую область действия. Он не позволяет устанавливать произвольные пакеты при неисправной конфигурации. Сейчас он лишь позволяет процессам установки восстанавливаться после конкретных сбоев обновления устаревших встроенных плагинов, например при отсутствии пути встроенного плагина или наличии устаревшей записи `channels.<id>` для того же встроенного плагина. Несвязанные ошибки конфигурации по-прежнему блокируют установку и направляют операторов к `openclaw doctor --fix`.

`openclaw.channel.persistedAuthState` — это метаданные пакета для небольшого модуля проверки:

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

Используйте их, когда процессам настройки, doctor, проверки статуса или доступной только для чтения проверки наличия требуется недорогая проверка аутентификации с ответом «да» или «нет» до загрузки полного плагина канала. Сохранённое состояние аутентификации не является настроенным состоянием канала: не используйте эти метаданные для автоматического включения плагинов, восстановления зависимостей среды выполнения или принятия решения о том, должна ли загружаться среда выполнения канала. Целевой экспорт должен быть небольшой функцией, которая только считывает сохранённое состояние; не направляйте его через основной модуль экспорта полной среды выполнения канала.

`openclaw.channel.configuredState` использует такую же структуру для недорогих проверок настроенного состояния только по переменным среды:

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

Используйте их, когда канал может определить настроенное состояние по переменным среды или другим небольшим входным данным, не требующим среды выполнения. Если для проверки требуется полное разрешение конфигурации или реальная среда выполнения канала, оставьте эту логику в обработчике `config.hasConfiguredState` плагина.

## Приоритет обнаружения (повторяющиеся идентификаторы плагинов)

OpenClaw обнаруживает плагины в трёх корневых каталогах, проверяемых в следующем порядке: встроенные плагины, поставляемые с OpenClaw, глобальный корневой каталог установки (`~/.openclaw/extensions`) и корневой каталог текущего рабочего пространства (`<workspace>/.openclaw/extensions`), а также все явно заданные записи `plugins.load.paths`.

Если у двух обнаруженных элементов совпадает `id`, сохраняется только манифест с **наивысшим приоритетом**; дубликаты с более низким приоритетом отбрасываются, а не загружаются вместе с ним. Приоритет от наивысшего к низшему:

1. **Выбранный конфигурацией** — путь, явно закреплённый в `plugins.entries.<id>`
2. **Глобальная установка, соответствующая отслеживаемой записи установки** — плагин, установленный через `openclaw plugin install`/`openclaw plugin update`, который система отслеживания установок OpenClaw распознаёт для того же идентификатора, даже если этот идентификатор также принадлежит встроенному плагину
3. **Встроенный** — плагины, поставляемые с OpenClaw
4. **Рабочее пространство** — плагины, обнаруженные относительно текущего рабочего пространства
5. Любой другой обнаруженный кандидат

Следствия:

- Ответвлённая или устаревшая копия встроенного плагина, находящаяся без отслеживания в рабочем пространстве или глобальном корневом каталоге, не заменит встроенную сборку.
- Чтобы переопределить встроенный плагин, выполните `openclaw plugin install` для этого идентификатора, чтобы отслеживаемая глобальная установка получила приоритет над встроенной копией, либо закрепите конкретный путь через `plugins.entries.<id>`, чтобы он получил приоритет как выбранный конфигурацией.
- Отбрасывание дубликатов записывается в журнал, чтобы Doctor и диагностика запуска могли указать на отброшенную копию.
- В диагностике выбранные конфигурацией переопределения дубликатов описываются как явные переопределения, но предупреждения всё равно выводятся, чтобы устаревшие ответвления и случайные подмены оставались заметными.

## Требования JSON Schema

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

Пример расширения схемы:

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

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

- Неизвестные ключи `channels.*` считаются **ошибками**, если только идентификатор канала не объявлен в манифесте плагина. Если тот же идентификатор также присутствует в `plugins.allow`, `plugins.entries` или `plugins.installs` (плагин, на который есть ссылка, но который сейчас недоступен для обнаружения), OpenClaw вместо этого понижает уровень проблемы до **предупреждения**.
- Ссылки на неизвестные идентификаторы плагинов в `plugins.entries.<id>`, `plugins.allow` и `plugins.deny` считаются **предупреждениями** («устаревшая запись конфигурации проигнорирована»), а не ошибками, поэтому обновления и удалённые или переименованные плагины не блокируют запуск Gateway.
- Ссылка на неизвестный идентификатор плагина в `plugins.slots.memory` считается **ошибкой**, кроме известного официального внешнего плагина `memory-lancedb`, для которого вместо этого выводится предупреждение.
- Если плагин установлен, но его манифест или схема повреждены либо отсутствуют, проверка завершается с ошибкой, а Doctor сообщает об ошибке плагина.
- Если конфигурация плагина существует, но плагин **отключён**, конфигурация сохраняется, а в Doctor и журналах отображается **предупреждение**.

Полную схему `plugins.*` см. в [справочнике по конфигурации](/ru/gateway/configuration).

## Примечания

- Манифест **обязателен для нативных плагинов OpenClaw**, включая загрузку из локальной файловой системы. Среда выполнения по-прежнему загружает модуль плагина отдельно; манифест используется только для обнаружения и проверки.
- Нативные манифесты разбираются как JSON5, поэтому допускаются комментарии, завершающие запятые и ключи без кавычек, если итоговое значение по-прежнему является объектом.
- Загрузчик манифеста считывает только документированные поля манифеста. Избегайте пользовательских ключей верхнего уровня.
- `channels`, `providers`, `cliBackends` и `skills` можно не указывать, если они не нужны плагину.
- `providerCatalogEntry` должен оставаться легковесным и не должен импортировать обширный код среды выполнения; используйте его для статических метаданных каталога провайдера или узкоспециализированных дескрипторов обнаружения, а не для выполнения во время обработки запросов.
- Взаимоисключающие виды плагинов выбираются через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory` (по умолчанию `memory-core`), `kind: "context-engine"` через `plugins.slots.contextEngine` (по умолчанию `legacy`).
- Объявляйте взаимоисключающий вид плагина в этом манифесте. `OpenClawPluginDefinition.kind` в точке входа среды выполнения устарел и сохраняется только как резервный механизм совместимости для старых плагинов.
- Метаданные переменных среды (`setup.providers[].envVars`, устаревший `providerAuthEnvVars` и `channelEnvVars`) носят исключительно декларативный характер. Статус, аудит, проверка доставки Cron и другие поверхности только для чтения по-прежнему применяют политику доверия к плагину и его фактической активации, прежде чем считать переменную среды настроенной.
- Метаданные мастера среды выполнения, для которых требуется код провайдера, описаны в разделе [Перехватчики среды выполнения провайдера](/ru/plugins/architecture-internals#provider-runtime-hooks).
- Если ваш плагин зависит от нативных модулей, задокументируйте этапы сборки и все требования к списку разрешений менеджера пакетов (например, pnpm `allow-build-scripts` + `pnpm rebuild <package>`).

## Связанные материалы

<CardGroup cols={3}>
  <Card title="Разработка плагинов" href="/ru/plugins/building-plugins" icon="rocket">
    Начало работы с плагинами.
  </Card>
  <Card title="Архитектура плагинов" href="/ru/plugins/architecture" icon="diagram-project">
    Внутренняя архитектура и модель возможностей.
  </Card>
  <Card title="Обзор SDK" href="/ru/plugins/sdk-overview" icon="book">
    Справочник по SDK плагинов и импорту подпутей.
  </Card>
</CardGroup>