Перейти к основному содержанию
Эта страница предназначена только для нативного манифеста Plugin OpenClaw. Совместимые макеты пакетов см. в разделе Пакеты Plugin. Совместимые форматы пакетов используют другие файлы манифестов:
  • Пакет Codex: .codex-plugin/plugin.json
  • Пакет Claude: .claude-plugin/plugin.json или стандартный макет компонентов Claude без манифеста
  • Пакет Cursor: .cursor-plugin/plugin.json
OpenClaw также автоматически обнаруживает эти макеты пакетов, но они не проходят проверку по схеме openclaw.plugin.json, описанной здесь. Для совместимых пакетов OpenClaw сейчас считывает метаданные пакета, объявленные корни Skills, корни команд Claude, стандартные значения settings.json пакета Claude, стандартные значения LSP пакета Claude и поддерживаемые наборы хуков, когда макет соответствует ожиданиям среды выполнения OpenClaw. Каждый нативный Plugin OpenClaw должен поставляться с файлом openclaw.plugin.json в корне Plugin. OpenClaw использует этот манифест для проверки конфигурации без выполнения кода Plugin. Отсутствующие или недействительные манифесты считаются ошибками Plugin и блокируют проверку конфигурации. См. полное руководство по системе Plugin: Plugin. Нативная модель возможностей и текущие рекомендации по внешней совместимости: Модель возможностей.

Что делает этот файл

openclaw.plugin.json — это метаданные, которые OpenClaw считывает до загрузки вашего кода Plugin. Все ниже должно быть достаточно легковесным для проверки без запуска среды выполнения Plugin. Используйте его для:
  • идентификации Plugin, проверки конфигурации и подсказок для пользовательского интерфейса конфигурации
  • метаданных аутентификации, адаптации и настройки (псевдоним, автовключение, переменные окружения провайдера, варианты аутентификации)
  • подсказок активации для поверхностей плоскости управления
  • краткой записи владения семействами моделей
  • статических снимков владения возможностями (contracts)
  • метаданных QA-запускателя, которые может проверять общий хост openclaw qa
  • метаданных конфигурации для конкретных каналов, объединяемых с каталогом и поверхностями проверки
Не используйте его для: регистрации поведения среды выполнения, объявления точек входа кода или метаданных установки npm. Они должны находиться в коде вашего Plugin и package.json.

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

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

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

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "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": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

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

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

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

Поля метаданных провайдера генерации описывают статические сигналы аутентификации для провайдеров, объявленных в соответствующем списке contracts.*GenerationProviders. OpenClaw читает эти поля до загрузки среды выполнения провайдера, чтобы инструменты ядра могли решить, доступен ли провайдер генерации, без импорта каждого Plugin провайдера. Используйте эти поля только для дешевых декларативных фактов. Транспорт, преобразования запросов, обновление токенов, проверка учетных данных и фактическое поведение генерации остаются в среде выполнения Plugin.
{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}
Каждая запись метаданных поддерживает:
ПолеОбязательноТипЧто это означает
aliasesНетstring[]Дополнительные идентификаторы провайдеров, которые должны считаться статическими псевдонимами аутентификации для провайдера генерации.
authProvidersНетstring[]Идентификаторы провайдеров, настроенные профили аутентификации которых должны считаться аутентификацией для этого провайдера генерации.
configSignalsНетobject[]Дешевые сигналы доступности только по конфигурации для локальных или самостоятельно размещенных провайдеров, которые можно настроить без профилей аутентификации или переменных окружения.
authSignalsНетobject[]Явные сигналы аутентификации. Если они присутствуют, они заменяют набор сигналов по умолчанию из идентификатора провайдера, aliases и authProviders.
referenceAudioInputsНетbooleanТолько для генерации видео. Установите true, когда провайдер принимает эталонные аудиоактивы; иначе video_generate скрывает параметры аудиореференсов.
Каждая запись configSignals поддерживает:
ПолеОбязательноТипЧто это означает
rootPathДаstringТочечный путь к объекту конфигурации, принадлежащему Plugin, который нужно проверить, например 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 мог избежать импорта среды выполнения Plugin только для того, чтобы фабрика инструмента вернула null.
{
  "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, OpenClaw сохраняет существующее поведение и загружает владеющий Plugin, когда контракт инструмента соответствует политике. Для инструментов на горячем пути, фабрика которых зависит от аутентификации или конфигурации, авторам Plugin следует объявлять 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Короткий вспомогательный текст для группы.
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, когда Plugin владеет именем команды среды выполнения, которое пользователи могут ошибочно добавить в plugins.allow или попытаться запустить как корневую команду CLI. OpenClaw использует эти метаданные для диагностики без импорта кода среды выполнения Plugin.
{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}
ПолеОбязательноТипЧто означает
nameДаstringИмя команды, принадлежащее этому Plugin.
kindНет"runtime-slash"Помечает псевдоним как slash-команду чата, а не как корневую команду CLI.
cliCommandНетstringСвязанная корневая команда CLI, которую можно предложить для операций CLI, если она существует.

Справочник activation

Используйте activation, когда Plugin может недорого объявить, какие события плоскости управления должны включать его в план активации/загрузки. Этот блок является метаданными планировщика, а не API жизненного цикла. Он не регистрирует поведение среды выполнения, не заменяет register(...) и не гарантирует, что код Plugin уже был выполнен. Планировщик активации использует эти поля, чтобы сузить список кандидатов Plugin перед откатом к существующим метаданным владения манифеста, таким как providers, channels, commandAliases, setup.providers, contracts.tools и hooks. Предпочитайте самые узкие метаданные, которые уже описывают владение. Используйте providers, channels, commandAliases, дескрипторы setup или contracts, когда эти поля выражают связь. Используйте activation для дополнительных подсказок планировщика, которые нельзя представить этими полями владения. Используйте верхнеуровневый cliBackends для псевдонимов среды выполнения CLI, таких как claude-cli, my-cli или google-gemini-cli; activation.onAgentHarnesses предназначен только для идентификаторов встроенных агентских harness, у которых еще нет поля владения. Этот блок содержит только метаданные. Он не регистрирует поведение среды выполнения и не заменяет register(...), setupEntry или другие точки входа среды выполнения/Plugin. Текущие потребители используют его как сужающую подсказку перед более широкой загрузкой Plugin, поэтому отсутствие метаданных активации не для запуска обычно влияет только на производительность; оно не должно менять корректность, пока по-прежнему существуют откаты к владению из манифеста. Каждый Plugin должен задавать activation.onStartup намеренно. Установите true только тогда, когда Plugin должен запускаться во время старта Gateway. Установите false, когда Plugin инертен при запуске и должен загружаться только по более узким триггерам. Если onStartup опущен, Plugin больше не загружается при запуске неявно; используйте явные метаданные активации для запуска, канала, конфигурации, agent-harness, памяти или других более узких триггеров активации.
{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}
ПолеОбязательноТипЧто означает
onStartupНетbooleanЯвная активация при запуске Gateway. Каждый Plugin должен задавать это поле. true импортирует Plugin во время запуска; false оставляет его ленивым при запуске, если загрузка не требуется другим совпавшим триггером.
onProvidersНетstring[]Идентификаторы поставщиков, которые должны включать этот Plugin в планы активации/загрузки.
onAgentHarnessesНетstring[]Идентификаторы среды выполнения встроенных агентских harness, которые должны включать этот Plugin в планы активации/загрузки. Используйте верхнеуровневый cliBackends для псевдонимов backend CLI.
onCommandsНетstring[]Идентификаторы команд, которые должны включать этот Plugin в планы активации/загрузки.
onChannelsНетstring[]Идентификаторы каналов, которые должны включать этот Plugin в планы активации/загрузки.
onRoutesНетstring[]Типы маршрутов, которые должны включать этот Plugin в планы активации/загрузки.
onConfigPathsНетstring[]Пути конфигурации относительно корня, которые должны включать этот Plugin в планы запуска/загрузки, когда путь присутствует и не отключен явно.
onCapabilitiesНетArray<"provider" | "channel" | "tool" | "hook">Широкие подсказки возможностей, используемые планированием активации плоскости управления. По возможности предпочитайте более узкие поля.
Текущие активные потребители:
  • Планирование запуска Gateway использует activation.onStartup для явного импорта при запуске
  • Планирование CLI, запускаемое командой, откатывается к устаревшим commandAliases[].cliCommand или commandAliases[].name
  • Планирование запуска среды выполнения агента использует activation.onAgentHarnesses для встроенных harness и верхнеуровневый cliBackends[] для псевдонимов среды выполнения CLI
  • Планирование setup/канала, запускаемое каналом, откатывается к устаревшему владению channels[], когда явные метаданные активации канала отсутствуют
  • Планирование Plugin при запуске использует activation.onConfigPaths для некональных корневых поверхностей конфигурации, таких как блок browser встроенного browser Plugin
  • Планирование setup/среды выполнения, запускаемое поставщиком, откатывается к устаревшему владению providers[] и верхнеуровневому cliBackends[], когда явные метаданные активации поставщика отсутствуют
Диагностика планировщика может отличать явные подсказки активации от отката к владению из манифеста. Например, activation-command-hint означает, что совпал activation.onCommands, а manifest-command-alias означает, что планировщик вместо этого использовал владение commandAliases. Эти метки причин предназначены для диагностики хоста и тестов; авторам Plugin следует продолжать объявлять метаданные, которые лучше всего описывают владение.

Справочник qaRunners

Используйте qaRunners, когда Plugin добавляет один или несколько транспортных runner под общим корнем openclaw qa. Держите эти метаданные легковесными и статическими; среда выполнения Plugin по-прежнему владеет фактической регистрацией CLI через легковесную поверхность runtime-api.ts, которая экспортирует qaRunnerCliRegistrations.
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}
ПолеОбязательноТипЧто означает
commandNameДаstringПодкоманда, смонтированная под openclaw qa, например matrix.
descriptionНетstringРезервный текст справки, используемый, когда общему хосту нужна команда-заглушка.

Справочник setup

Используйте setup, когда поверхностям настройки и онбординга нужны дешевые метаданные, принадлежащие plugin, до загрузки runtime.
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
Верхнеуровневое cliBackends остается допустимым и продолжает описывать backend-ы вывода CLI. setup.cliBackends — это специфичная для настройки поверхность дескрипторов для потоков control-plane/setup, которые должны оставаться только метаданными. Если они присутствуют, setup.providers и setup.cliBackends являются предпочтительной поверхностью поиска по принципу descriptor-first для обнаружения настройки. Если дескриптор только сужает plugin-кандидат, а настройке все еще нужны более богатые runtime-хуки времени настройки, задайте requiresRuntime: true и оставьте setup-api на месте как резервный путь выполнения. OpenClaw также включает setup.providers[].envVars в общие проверки аутентификации provider и поиски env-переменных. providerAuthEnvVars остается поддерживаемым через адаптер совместимости в течение окна устаревания, но не входящие в комплект plugins, которые все еще используют его, получают диагностическое сообщение manifest. Новые plugins должны помещать env-метаданные настройки/статуса в setup.providers[].envVars. OpenClaw также может выводить простые варианты настройки из setup.providers[].authMethods, когда запись setup недоступна или когда setup.requiresRuntime: false объявляет, что setup runtime не нужен. Явные записи providerAuthChoices остаются предпочтительными для пользовательских меток, флагов CLI, области онбординга и метаданных assistant. Задавайте requiresRuntime: false только когда этих дескрипторов достаточно для поверхности setup. OpenClaw трактует явное false как контракт только на дескрипторах и не будет выполнять setup-api или openclaw.setupEntry для поиска setup. Если plugin, работающий только по дескрипторам, все еще поставляет одну из этих runtime-записей setup, OpenClaw сообщает добавочную диагностику и продолжает игнорировать ее. Отсутствующее requiresRuntime сохраняет legacy-поведение fallback, чтобы существующие plugins, которые добавили дескрипторы без этого флага, не ломались. Поскольку поиск setup может выполнять код setup-api, принадлежащий plugin, нормализованные значения setup.providers[].id и setup.cliBackends[] должны оставаться уникальными среди обнаруженных plugins. Неоднозначное владение завершается закрытым отказом вместо выбора победителя по порядку обнаружения. Когда setup runtime действительно выполняется, диагностика реестра setup сообщает о расхождении дескрипторов, если setup-api регистрирует provider или backend CLI, который дескрипторы manifest не объявляют, или если у дескриптора нет соответствующей runtime-регистрации. Эта диагностика является добавочной и не отклоняет legacy plugins.

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

ПолеОбязательноТипЧто означает
idДаstringId provider, раскрываемый во время настройки или онбординга. Сохраняйте нормализованные id глобально уникальными.
authMethodsНетstring[]Id методов setup/auth, которые этот provider поддерживает без загрузки полного runtime.
envVarsНетstring[]Env vars, которые общие поверхности setup/status могут проверять до загрузки runtime plugin.
authEvidenceНетobject[]Дешевые локальные проверки доказательств auth для providers, которые могут аутентифицироваться через несекретные маркеры.
authEvidence предназначен для принадлежащих provider локальных маркеров учетных данных, которые можно проверять без загрузки runtime-кода. Эти проверки должны оставаться дешевыми и локальными: без сетевых вызовов, без чтения keychain или secret-manager, без shell-команд и без проб provider API. Поддерживаемые записи доказательств:
ПолеОбязательноТипЧто означает
typeДаstringСейчас local-file-with-env.
fileEnvVarНетstringEnv var, содержащая явный путь к файлу учетных данных.
fallbackPathsНетstring[]Локальные пути к файлам учетных данных, проверяемые, когда fileEnvVar отсутствует или пуст. Поддерживает ${HOME} и ${APPDATA}.
requiresAnyEnvНетstring[]Как минимум одна указанная env var должна быть непустой, прежде чем доказательство будет действительно.
requiresAllEnvНетstring[]Каждая указанная env var должна быть непустой, прежде чем доказательство будет действительно.
credentialMarkerДаstringНесекретный маркер, возвращаемый, когда доказательство присутствует.
sourceНетstringПользовательская метка источника для вывода auth/status.

Поля setup

ПолеОбязательноТипЧто означает
providersНетobject[]Дескрипторы настройки provider, раскрываемые во время настройки и онбординга.
cliBackendsНетstring[]Id backend-ов времени настройки, используемые для поиска setup по принципу descriptor-first. Сохраняйте нормализованные id глобально уникальными.
configMigrationsНетstring[]Id миграций config, принадлежащие поверхности setup этого plugin.
requiresRuntimeНетbooleanНуждается ли setup все еще в выполнении setup-api после поиска дескрипторов.

Справочник uiHints

uiHints — это отображение имен полей config в небольшие подсказки рендеринга.
{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
Подсказка каждого поля может включать:
ПолеТипЧто означает
labelstringПользовательская метка поля.
helpstringКороткий вспомогательный текст.
tagsstring[]Необязательные UI-теги.
advancedbooleanПомечает поле как расширенное.
sensitivebooleanПомечает поле как секретное или чувствительное.
placeholderstringТекст placeholder для полей формы.

Справочник contracts

Используйте contracts только для статических метаданных владения capability, которые OpenClaw может читать без импорта runtime plugin.
{
  "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"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
Каждый список необязателен:
ПолеТипЧто означает
embeddedExtensionFactoriesstring[]Идентификаторы фабрик расширений app-server Codex, сейчас codex-app-server.
agentToolResultMiddlewarestring[]Идентификаторы runtime, для которых этот плагин может регистрировать middleware результатов инструментов.
trustedToolPoliciesstring[]Локальные для плагина идентификаторы доверенных pre-tool policy, которые установленный плагин может регистрировать. Встроенные плагины могут регистрировать политики без этого поля.
externalAuthProvidersstring[]Идентификаторы провайдеров, чей hook внешнего профиля аутентификации принадлежит этому плагину.
embeddingProvidersstring[]Идентификаторы общих embedding-провайдеров, которыми владеет этот плагин для переиспользуемого создания векторных embedding, включая память.
speechProvidersstring[]Идентификаторы провайдеров речи, которыми владеет этот плагин.
realtimeTranscriptionProvidersstring[]Идентификаторы провайдеров транскрипции в реальном времени, которыми владеет этот плагин.
realtimeVoiceProvidersstring[]Идентификаторы голосовых провайдеров реального времени, которыми владеет этот плагин.
memoryEmbeddingProvidersstring[]Устаревшие идентификаторы embedding-провайдеров, специфичных для памяти, которыми владеет этот плагин.
mediaUnderstandingProvidersstring[]Идентификаторы провайдеров понимания медиа, которыми владеет этот плагин.
transcriptSourceProvidersstring[]Идентификаторы провайдеров источников транскриптов, которыми владеет этот плагин.
imageGenerationProvidersstring[]Идентификаторы провайдеров генерации изображений, которыми владеет этот плагин.
videoGenerationProvidersstring[]Идентификаторы провайдеров генерации видео, которыми владеет этот плагин.
webFetchProvidersstring[]Идентификаторы провайдеров web-fetch, которыми владеет этот плагин.
webSearchProvidersstring[]Идентификаторы провайдеров web-search, которыми владеет этот плагин.
migrationProvidersstring[]Идентификаторы провайдеров импорта, которыми владеет этот плагин для openclaw migrate.
gatewayMethodDispatchstring[]Зарезервированное право для аутентифицированных HTTP-маршрутов плагина, которые dispatch-ят методы Gateway внутри процесса.
toolsstring[]Имена инструментов агента, которыми владеет этот плагин.
contracts.embeddedExtensionFactories сохраняется для встроенных фабрик расширений Codex, предназначенных только для app-server. Встроенные преобразования результатов инструментов должны объявлять contracts.agentToolResultMiddleware и вместо этого регистрироваться через api.registerAgentToolResultMiddleware(...). Установленные плагины могут использовать тот же стык middleware только при явном включении и только для runtime, которые они объявляют в contracts.agentToolResultMiddleware. Установленные плагины, которым нужен host-trusted уровень pre-tool policy, должны объявить каждый зарегистрированный локальный идентификатор в contracts.trustedToolPolicies и быть явно включены. Встроенные плагины сохраняют существующий путь доверенных политик, но установленные плагины с необъявленными идентификаторами политик отклоняются до регистрации. Идентификаторы политик ограничены регистрирующим плагином, поэтому два плагина могут оба объявить и зарегистрировать workflow-budget; один плагин не может зарегистрировать один и тот же локальный идентификатор дважды. Регистрации runtime api.registerTool(...) должны соответствовать contracts.tools. Обнаружение инструментов использует этот список, чтобы загружать только runtime плагинов, которые могут владеть запрошенными инструментами. Плагины провайдеров, реализующие resolveExternalAuthProfiles, должны объявлять contracts.externalAuthProviders; необъявленные hooks внешней аутентификации игнорируются. Общие embedding-провайдеры должны объявлять contracts.embeddingProviders для каждого адаптера, зарегистрированного через api.registerEmbeddingProvider(...). Используйте общий контракт для переиспользуемой генерации векторов, включая провайдеров, используемых поиском по памяти. contracts.memoryEmbeddingProviders является устаревшей совместимостью, специфичной для памяти, и остается только на время миграции существующих провайдеров на общий стык embedding-провайдера. contracts.gatewayMethodDispatch сейчас принимает "authenticated-request". Это гейт гигиены API для нативных HTTP-маршрутов плагина, которые намеренно dispatch-ят методы control-plane Gateway внутри процесса, а не sandbox против вредоносных нативных плагинов. Используйте его только для тщательно проверенных встроенных/operator поверхностей, которые уже требуют HTTP-аутентификацию Gateway.

Справочник mediaUnderstandingProviderMetadata

Используйте mediaUnderstandingProviderMetadata, когда у провайдера понимания медиа есть модели по умолчанию, приоритет fallback для auto-auth или нативная поддержка документов, которые нужны общим core helpers до загрузки runtime. Ключи также должны быть объявлены в contracts.mediaUnderstandingProviders.
{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}
Каждая запись провайдера может включать:
ПолеТипЧто означает
capabilities("image" | "audio" | "video")[]Возможности медиа, предоставляемые этим провайдером.
defaultModelsRecord<string, string>Значения по умолчанию для соответствия возможности модели, используемые, когда config не задает модель.
autoPriorityRecord<string, number>Меньшие числа сортируются раньше для автоматического fallback провайдера на основе учетных данных.
nativeDocumentInputs"pdf"[]Нативные входные документы, поддерживаемые провайдером.

Справочник channelConfigs

Используйте channelConfigs, когда плагину канала нужны дешевые метаданные config до загрузки runtime. Обнаружение настройки/статуса канала только для чтения может использовать эти метаданные напрямую для настроенных внешних каналов, когда запись настройки недоступна или когда setup.requiresRuntime: false объявляет runtime настройки ненужным. channelConfigs — это метаданные манифеста плагина, а не новый пользовательский раздел config верхнего уровня. Пользователи по-прежнему настраивают экземпляры каналов в channels.<channel-id>. OpenClaw читает метаданные манифеста, чтобы решить, какому плагину принадлежит этот настроенный канал, до выполнения runtime-кода плагина. Для плагина канала configSchema и channelConfigs описывают разные пути:
  • configSchema проверяет plugins.entries.<plugin-id>.config
  • channelConfigs.<channel-id>.schema проверяет channels.<channel-id>
Невстроенные плагины, которые объявляют channels[], также должны объявлять соответствующие записи channelConfigs. Без них OpenClaw все равно может загрузить плагин, но cold-path схема config, настройка и поверхности Control UI не смогут узнать форму опций, принадлежащих каналу, пока не выполнится runtime плагина. channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled и nativeSkillsAutoEnabled могут объявлять статические значения по умолчанию auto для проверок config команд, которые выполняются до загрузки runtime канала. Встроенные каналы также могут публиковать те же значения по умолчанию через package.json#openclaw.channel.commands вместе с другими метаданными каталога каналов, принадлежащими их пакету.
{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}
Каждая запись канала может включать:
ПолеТипЧто означает
schemaobjectJSON Schema для channels.<id>. Обязательна для каждой объявленной записи config канала.
uiHintsRecord<string, object>Необязательные UI labels/placeholders/sensitive hints для этого раздела config канала.
labelstringМетка канала, объединяемая в picker и inspect surfaces, когда runtime-метаданные еще не готовы.
descriptionstringКраткое описание канала для inspect и catalog surfaces.
commandsobjectСтатические auto-defaults нативных команд и нативных Skills для pre-runtime проверок config.
preferOverstring[]Идентификаторы устаревших или менее приоритетных плагинов, которые этот канал должен опережать в поверхностях выбора.

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

Используйте preferOver, когда ваш плагин является предпочтительным владельцем для идентификатора канала, который также может предоставлять другой плагин. Типичные случаи — переименованный идентификатор плагина, автономный плагин, который заменяет встроенный плагин, или поддерживаемый форк, сохраняющий тот же идентификатор канала для совместимости config.
{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}
Когда channels.chat настроен, OpenClaw учитывает и идентификатор канала, и предпочтительный идентификатор плагина. Если менее приоритетный плагин был выбран только потому, что он встроен или включен по умолчанию, OpenClaw отключает его в эффективном runtime config, чтобы каналом и его инструментами владел один плагин. Явный выбор пользователя все равно имеет приоритет: если пользователь явно включает оба плагина, OpenClaw сохраняет этот выбор и сообщает диагностику дублирования канала/инструмента вместо молчаливого изменения запрошенного набора плагинов. Ограничивайте preferOver идентификаторами плагинов, которые действительно могут предоставлять тот же канал. Это не общее поле приоритета, и оно не переименовывает пользовательские ключи config.

Справочник modelSupport

Используйте modelSupport, когда OpenClaw должен определить ваш Plugin поставщика по сокращенным id моделей, таким как gpt-5.5 или claude-sonnet-4.6, до загрузки среды выполнения Plugin.
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
OpenClaw применяет такой приоритет:
  • явные ссылки provider/model используют принадлежащие им метаданные манифеста providers
  • modelPatterns имеют приоритет над modelPrefixes
  • если совпадают один невстроенный Plugin и один встроенный Plugin, побеждает невстроенный Plugin
  • оставшаяся неоднозначность игнорируется, пока пользователь или конфигурация не задаст поставщика
Поля:
ПолеТипЧто это означает
modelPrefixesstring[]Префиксы, сопоставляемые через startsWith с сокращенными id моделей.
modelPatternsstring[]Источники Regex, сопоставляемые с сокращенными id моделей после удаления суффикса профиля.
Записи modelPatterns компилируются через compileSafeRegex, который отклоняет шаблоны с вложенным повторением (например, (a+)+$). Шаблоны, не прошедшие проверку безопасности, молча пропускаются, как и синтаксически недопустимые Regex. Держите шаблоны простыми и избегайте вложенных квантификаторов.

Справочник modelCatalog

Используйте modelCatalog, когда OpenClaw должен знать метаданные моделей поставщика до загрузки среды выполнения Plugin. Это источник, принадлежащий манифесту, для фиксированных строк каталога, псевдонимов поставщиков, правил подавления и режима обнаружения. Обновление во время выполнения по-прежнему принадлежит коду среды выполнения поставщика, но манифест сообщает ядру, когда требуется среда выполнения.
{
  "providers": ["openai"],
  "modelCatalog": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4",
            "input": ["text", "image"],
            "reasoning": true,
            "contextWindow": 256000,
            "maxTokens": 128000,
            "cost": {
              "input": 1.25,
              "output": 10,
              "cacheRead": 0.125
            },
            "status": "available",
            "tags": ["default"]
          }
        ]
      }
    },
    "aliases": {
      "azure-openai-responses": {
        "provider": "openai",
        "api": "azure-openai-responses"
      }
    },
    "suppressions": [
      {
        "provider": "azure-openai-responses",
        "model": "gpt-5.3-codex-spark",
        "reason": "not available on Azure OpenAI Responses"
      }
    ],
    "discovery": {
      "openai": "static"
    }
  }
}
Поля верхнего уровня:
ПолеТипЧто это означает
providersRecord<string, object>Строки каталога для id поставщиков, принадлежащих этому Plugin. Ключи также должны присутствовать в providers верхнего уровня.
aliasesRecord<string, object>Псевдонимы поставщиков, которые должны разрешаться в принадлежащего поставщика для планирования каталога или подавления.
suppressionsobject[]Строки моделей из другого источника, которые этот Plugin подавляет по причине, специфичной для поставщика.
discoveryRecord<string, "static" | "refreshable" | "runtime">Можно ли читать каталог поставщика из метаданных манифеста, обновлять в кэш или требуется среда выполнения.
runtimeAugmentbooleanУстанавливайте true только когда среда выполнения поставщика должна добавлять строки каталога после планирования манифеста/конфигурации.
aliases участвует в поиске владельца поставщика для планирования каталога моделей. Цели псевдонимов должны быть поставщиками верхнего уровня, принадлежащими тому же Plugin. Когда список, отфильтрованный по поставщику, использует псевдоним, OpenClaw может прочитать манифест владельца и применить переопределения API/базового URL псевдонима без загрузки среды выполнения поставщика. Псевдонимы не расширяют нефильтрованные списки каталога; широкие списки выводят только строки принадлежащего канонического поставщика. suppressions заменяет старый хук среды выполнения поставщика suppressBuiltInModel. Записи подавления учитываются только когда поставщик принадлежит Plugin или объявлен как ключ modelCatalog.aliases, указывающий на принадлежащего поставщика. Хуки подавления среды выполнения больше не вызываются во время разрешения моделей. Поля поставщика:
ПолеТипЧто это означает
baseUrlstringНеобязательный базовый URL по умолчанию для моделей в этом каталоге поставщика.
apiModelApiНеобязательный API-адаптер по умолчанию для моделей в этом каталоге поставщика.
headersRecord<string, string>Необязательные статические заголовки, применяемые к этому каталогу поставщика.
modelsobject[]Обязательные строки моделей. Строки без id игнорируются.
Поля модели:
ПолеТипЧто это означает
idstringЛокальный для поставщика id модели, без префикса provider/.
namestringНеобязательное отображаемое имя.
apiModelApiНеобязательное переопределение API для модели.
baseUrlstringНеобязательное переопределение базового URL для модели.
headersRecord<string, string>Необязательные статические заголовки для модели.
inputArray<"text" | "image" | "document" | "audio" | "video">Модальности, которые принимает модель.
reasoningbooleanПредоставляет ли модель поведение рассуждения.
contextWindownumberНативное контекстное окно поставщика.
contextTokensnumberНеобязательный эффективный лимит контекста во время выполнения, если отличается от contextWindow.
maxTokensnumberМаксимальное число выходных токенов, когда известно.
costobjectНеобязательная цена в USD за миллион токенов, включая необязательное tieredPricing.
compatobjectНеобязательные флаги совместимости, соответствующие совместимости конфигурации моделей OpenClaw.
status"available" | "preview" | "deprecated" | "disabled"Статус в списке. Подавляйте только когда строка вообще не должна появляться.
statusReasonstringНеобязательная причина, показываемая при статусе, отличном от доступного.
replacesstring[]Старые локальные для поставщика id моделей, которые эта модель заменяет.
replacedBystringЛокальный для поставщика id модели-замены для устаревших строк.
tagsstring[]Стабильные теги, используемые средствами выбора и фильтрами.
Поля подавления:
ПолеТипЧто это означает
providerstringId поставщика для вышестоящей строки, которую нужно подавить. Должен принадлежать этому Plugin или быть объявлен как принадлежащий псевдоним.
modelstringЛокальный для поставщика id модели, которую нужно подавить.
reasonstringНеобязательное сообщение, показываемое при прямом запросе подавленной строки.
when.baseUrlHostsstring[]Необязательный список хостов эффективного базового URL поставщика, необходимых перед применением подавления.
when.providerConfigApiInstring[]Необязательный список точных значений api конфигурации поставщика, необходимых перед применением подавления.
Не помещайте данные, существующие только во время выполнения, в modelCatalog. Используйте static только когда строки манифеста достаточно полны, чтобы поверхности списков и выбора, отфильтрованные по поставщику, могли пропустить обнаружение через реестр/среду выполнения. Используйте refreshable, когда строки манифеста полезны как отображаемые начальные записи или дополнения, но обновление/кэш может позже добавить больше строк; обновляемые строки сами по себе не являются авторитетными. Используйте runtime, когда OpenClaw должен загрузить среду выполнения поставщика, чтобы узнать список.

Справочник modelIdNormalization

Используйте modelIdNormalization для дешевой очистки id моделей, принадлежащей поставщику, которая должна выполняться до загрузки среды выполнения поставщика. Это держит псевдонимы, такие как короткие имена моделей, локальные для поставщика устаревшие id и правила префиксов прокси, в манифесте Plugin владельца вместо таблиц выбора моделей в ядре.
{
  "providers": ["anthropic", "openrouter"],
  "modelIdNormalization": {
    "providers": {
      "anthropic": {
        "aliases": {
          "sonnet-4.6": "claude-sonnet-4-6"
        }
      },
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  }
}
Поля поставщика:
ПолеТипЧто это означает
aliasesRecord<string,string>Точные псевдонимы id моделей без учета регистра. Значения возвращаются как записаны.
stripPrefixesstring[]Префиксы, удаляемые перед поиском псевдонима, полезны для устаревшего дублирования provider/model.
prefixWhenBarestringПрефикс, добавляемый, когда нормализованный id модели еще не содержит /.
prefixWhenBareAfterAliasStartsWithobject[]Условные правила префикса для голого id после поиска псевдонима, задаваемые modelPrefix и prefix.

Справочник providerEndpoints

Используйте providerEndpoints для классификации конечных точек, которую общая политика запросов должна знать до загрузки среды выполнения поставщика. Ядро по-прежнему владеет смыслом каждого endpointClass; манифесты Plugin владеют метаданными хоста и базового URL. Поля конечной точки:
ПолеТипЧто означает
endpointClassstringИзвестный класс конечной точки ядра, например openrouter, moonshot-native или google-vertex.
hostsstring[]Точные имена хостов, которые сопоставляются с классом конечной точки.
hostSuffixesstring[]Суффиксы хостов, которые сопоставляются с классом конечной точки. Добавьте префикс . для сопоставления только по суффиксу домена.
baseUrlsstring[]Точные нормализованные базовые URL HTTP(S), которые сопоставляются с классом конечной точки.
googleVertexRegionstringСтатический регион Google Vertex для точных глобальных хостов.
googleVertexRegionHostSuffixstringСуффикс, удаляемый из совпавших хостов, чтобы получить префикс региона Google Vertex.

Справочник providerRequest

Используйте providerRequest для недорогих метаданных совместимости запросов, которые нужны общей политике запросов без загрузки среды выполнения провайдера. Переписывание полезной нагрузки, зависящее от поведения, оставляйте в хуках среды выполнения провайдера или общих помощниках семейства провайдеров.
{
  "providers": ["vllm"],
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}
Поля провайдера:
ПолеТипЧто означает
familystringМетка семейства провайдера, используемая общими решениями совместимости запросов и диагностикой.
compatibilityFamily"moonshot"Необязательная корзина совместимости семейства провайдера для общих помощников запросов.
openAICompletionsobjectФлаги запросов completions, совместимых с OpenAI; сейчас это supportsStreamingUsage.

Справочник secretProviderIntegrations

Используйте secretProviderIntegrations, когда plugin может публиковать переиспользуемый пресет exec-провайдера SecretRef. OpenClaw читает эти метаданные до загрузки среды выполнения plugin, сохраняет принадлежность plugin в secrets.providers.<alias>.pluginIntegration и оставляет фактическое разрешение секретов среде выполнения SecretRef. Пресеты доступны только для встроенных plugins и установленных plugins, обнаруженных из управляемых корней установки plugins, например установок из git и ClawHub.
{
  "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 записывает ссылку на провайдера, например:
{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}
При запуске или перезагрузке OpenClaw разрешает этого провайдера, загружая текущие метаданные манифеста plugin, проверяя, что владеющий plugin установлен и активен, и материализуя exec-команду из манифеста. Отключение или удаление plugin отзывает провайдера для активных SecretRefs. Операторы, которым нужна автономная exec-конфигурация, по-прежнему могут напрямую записывать ручных провайдеров command/args. Сейчас поддерживаются только пресеты source: "exec". command должен быть ${node}, а args[0] должен быть скриптом-резолвером, относительным к корню plugin и начинающимся с ./. OpenClaw материализует его при запуске или перезагрузке в текущий исполняемый файл Node и абсолютный путь к скрипту внутри plugin. Параметры Node, такие как --require, --import, --loader, --env-file, --eval и --print, не входят в контракт пресета манифеста. Операторы, которым нужны команды не на Node, могут напрямую настроить автономных ручных exec-провайдеров. OpenClaw выводит trustedDirs для пресетов манифеста из корня plugin и, для пресетов ${node}, из каталога текущего исполняемого файла Node. Указанные в манифесте trustedDirs игнорируются. Другие параметры exec-провайдера, такие как timeoutMs, maxOutputBytes, jsonOnly, env, passEnv и allowInsecurePath, передаются в обычную конфигурацию exec-провайдера SecretRef.

Справочник modelPricing

Используйте modelPricing, когда провайдеру нужно поведение ценообразования control plane до загрузки среды выполнения. Кэш цен Gateway читает эти метаданные без импорта кода среды выполнения провайдера.
{
  "providers": ["ollama", "openrouter"],
  "modelPricing": {
    "providers": {
      "ollama": {
        "external": false
      },
      "openrouter": {
        "openRouter": {
          "passthroughProviderModel": true
        },
        "liteLLM": false
      }
    }
  }
}
Поля провайдера:
ПолеТипЧто означает
externalbooleanУстановите false для локальных или самостоятельно размещенных провайдеров, которые никогда не должны получать цены OpenRouter или LiteLLM.
openRouterfalse | objectСопоставление поиска цен OpenRouter. false отключает поиск OpenRouter для этого провайдера.
liteLLMfalse | objectСопоставление поиска цен LiteLLM. false отключает поиск LiteLLM для этого провайдера.
Поля источника:
ПолеТипЧто означает
providerstringИдентификатор провайдера во внешнем каталоге, если он отличается от идентификатора провайдера OpenClaw, например z-ai для провайдера zai.
passthroughProviderModelbooleanРассматривать идентификаторы моделей со слешем как вложенные ссылки provider/model; полезно для прокси-провайдеров, таких как OpenRouter.
modelIdTransforms"version-dots"[]Дополнительные варианты идентификаторов моделей во внешнем каталоге. version-dots пробует идентификаторы версий с точками, например claude-opus-4.6.

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

Индекс провайдеров OpenClaw — это принадлежащие OpenClaw предварительные метаданные для провайдеров, чьи plugins могут еще не быть установлены. Он не является частью манифеста plugin. Манифесты plugins остаются источником истины для установленных plugins. Индекс провайдеров — это внутренний резервный контракт, который будущие поверхности установки провайдеров и выбора модели до установки будут использовать, когда plugin провайдера не установлен. Порядок источников истины каталога:
  1. Конфигурация пользователя.
  2. Манифест установленного plugin modelCatalog.
  3. Кэш каталога моделей из явного обновления.
  4. Предварительные строки Индекса провайдеров OpenClaw.
Индекс провайдеров не должен содержать секреты, включенное состояние, хуки среды выполнения или живые данные моделей, специфичные для аккаунта. Его предварительные каталоги используют ту же форму строки провайдера modelCatalog, что и манифесты plugins, но должны оставаться ограниченными стабильными отображаемыми метаданными, если только поля адаптера среды выполнения, такие как api, baseUrl, цены или флаги совместимости, намеренно не поддерживаются согласованными с манифестом установленного plugin. Провайдеры с живым обнаружением /models должны записывать обновленные строки через явный путь кэша каталога моделей, а не вызывать API провайдеров при обычном листинге или онбординге. Записи Индекса провайдеров также могут содержать метаданные устанавливаемого plugin для провайдеров, чей plugin был вынесен из ядра или иначе еще не установлен. Эти метаданные повторяют шаблон каталога каналов: имени пакета, npm-спецификации установки, ожидаемой целостности и недорогих меток выбора аутентификации достаточно, чтобы показать вариант устанавливаемой настройки. После установки plugin его манифест получает приоритет, а запись Индекса провайдеров для этого провайдера игнорируется. Устаревшие ключи возможностей верхнего уровня считаются deprecated. Используйте openclaw doctor --fix, чтобы переместить speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders и webSearchProviders в contracts; обычная загрузка манифеста больше не рассматривает эти поля верхнего уровня как владение возможностями.

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

Эти два файла выполняют разные задачи:
ФайлДля чего используется
openclaw.plugin.jsonОбнаружение, проверка конфигурации, метаданные выбора аутентификации и подсказки UI, которые должны существовать до запуска кода plugin
package.jsonМетаданные npm, установка зависимостей и блок openclaw, используемый для точек входа, блокировки установки, настройки или метаданных каталога
Если вы не уверены, где должны находиться конкретные метаданные, используйте это правило:
  • если OpenClaw должен знать это до загрузки кода plugin, поместите это в openclaw.plugin.json
  • если это относится к упаковке, файлам входа или поведению установки npm, поместите это в package.json

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

Некоторые метаданные plugin до запуска среды выполнения намеренно находятся в package.json в блоке openclaw, а не в openclaw.plugin.json. openclaw.bundle и openclaw.bundle.json не являются контрактами plugin OpenClaw; нативные plugins должны использовать openclaw.plugin.json плюс поддерживаемые поля package.json#openclaw ниже. Важные примеры:
ПолеЧто оно означает
openclaw.extensionsОбъявляет нативные точки входа Plugin. Должно оставаться внутри каталога пакета Plugin.
openclaw.runtimeExtensionsОбъявляет собранные точки входа среды выполнения JavaScript для установленных пакетов. Должно оставаться внутри каталога пакета Plugin.
openclaw.setupEntryЛегковесная точка входа только для настройки, используемая при онбординге, отложенном запуске канала и обнаружении статуса канала/SecretRef в режиме только чтения. Должна оставаться внутри каталога пакета Plugin.
openclaw.runtimeSetupEntryОбъявляет собранную точку входа настройки JavaScript для установленных пакетов. Требует setupEntry, должна существовать и должна оставаться внутри каталога пакета Plugin.
openclaw.channelДешевые метаданные каталога каналов, такие как метки, пути документации, псевдонимы и текст выбора.
openclaw.channel.commandsСтатические метаданные нативных команд и автоматических нативных skill по умолчанию, используемые конфигурацией, аудитом и поверхностями списка команд до загрузки среды выполнения канала.
openclaw.channel.configuredStateЛегковесные метаданные проверки настроенного состояния, которые могут ответить на вопрос «существует ли уже настройка только через env?» без загрузки полной среды выполнения канала.
openclaw.channel.persistedAuthStateЛегковесные метаданные проверки сохраненного состояния аутентификации, которые могут ответить на вопрос «есть ли уже выполненный вход?» без загрузки полной среды выполнения канала.
openclaw.install.clawhubSpec / openclaw.install.npmSpec / openclaw.install.localPathПодсказки установки/обновления для встроенных и внешне опубликованных plugins.
openclaw.install.defaultChoiceПредпочтительный путь установки, когда доступно несколько источников установки.
openclaw.install.minHostVersionМинимальная поддерживаемая версия хоста OpenClaw с нижней границей semver, например >=2026.3.22 или >=2026.5.1-beta.1.
openclaw.compat.pluginApiМинимальный диапазон API Plugin OpenClaw, требуемый этим пакетом, с нижней границей semver, например >=2026.5.27.
openclaw.install.expectedIntegrityОжидаемая строка целостности npm dist, например sha512-...; потоки установки и обновления проверяют полученный артефакт по ней.
openclaw.install.allowInvalidConfigRecoveryРазрешает узкий путь восстановления переустановки встроенного Plugin, когда конфигурация недействительна.
openclaw.install.requiredPlatformPackagesПсевдонимы пакетов npm, которые должны материализоваться, когда их платформенные ограничения lockfile соответствуют текущему хосту.
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListenПозволяет поверхностям канала среды выполнения настройки загрузиться до listen, а затем откладывает полный настроенный Plugin канала до активации после listen.
Метаданные манифеста определяют, какие варианты провайдера/канала/настройки появляются в онбординге до загрузки среды выполнения. package.json#openclaw.install сообщает онбордингу, как получить или включить этот Plugin, когда пользователь выбирает один из этих вариантов. Не переносите подсказки установки в openclaw.plugin.json. openclaw.install.minHostVersion применяется во время установки и загрузки реестра манифестов для невстроенных источников Plugin. Недействительные значения отклоняются; более новые, но допустимые значения пропускают внешние plugins на более старых хостах. Встроенные исходные plugins считаются совместно версионированными с checkout хоста. openclaw.install.requiredPlatformPackages предназначен для пакетов npm, которые предоставляют требуемые нативные бинарные файлы через необязательные, платформенно-специфичные псевдонимы. Укажите простое имя пакета npm для каждого поддерживаемого платформенного псевдонима. Во время установки npm OpenClaw проверяет только объявленный псевдоним, ограничения lockfile которого соответствуют текущему хосту. Если npm сообщает об успехе, но опускает этот псевдоним, OpenClaw один раз повторяет попытку со свежим кешем и откатывает установку, если псевдоним все еще отсутствует. openclaw.compat.pluginApi применяется во время установки пакета для невстроенных источников Plugin. Используйте его для нижней границы API SDK/среды выполнения Plugin OpenClaw, против которой был собран пакет. Она может быть строже, чем minHostVersion, когда пакету Plugin нужен более новый API, но он все еще сохраняет более низкую подсказку установки для других потоков. Официальная синхронизация релиза OpenClaw по умолчанию повышает существующие нижние границы API официальных plugins до версии релиза OpenClaw, но релизы только Plugin могут сохранять более низкую границу, когда пакет намеренно поддерживает более старые хосты. Не используйте только версию пакета как контракт совместимости. peerDependencies.openclaw остается метаданными пакета npm; OpenClaw использует контракт openclaw.compat.pluginApi для решений о совместимости установки. Официальные метаданные установки по требованию должны использовать clawhubSpec, когда Plugin опубликован в ClawHub; онбординг рассматривает это как предпочтительный удаленный источник и записывает факты артефакта ClawHub после установки. npmSpec остается совместимым резервным вариантом для пакетов, которые еще не перешли в ClawHub. Точная фиксация версии npm уже находится в npmSpec, например "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Официальные записи внешнего каталога должны сочетать точные спецификации с expectedIntegrity, чтобы потоки обновления завершались закрыто, если полученный артефакт npm больше не соответствует зафиксированному релизу. Интерактивный онбординг по-прежнему предлагает доверенные спецификации npm из registry, включая простые имена пакетов и dist-tags, для совместимости. Диагностика каталога может различать точные, плавающие, закрепленные по целостности, без целостности, с несовпадением имени пакета и недействительные источники выбора по умолчанию. Она также предупреждает, когда expectedIntegrity присутствует, но нет допустимого источника npm, который он может закрепить. Когда expectedIntegrity присутствует, потоки установки/обновления принудительно применяют его; когда он опущен, разрешение registry записывается без закрепления целостности. Plugins каналов должны предоставлять openclaw.setupEntry, когда статус, список каналов или сканирования SecretRef должны определить настроенные аккаунты без загрузки полной среды выполнения. Точка входа настройки должна предоставлять метаданные канала, а также безопасные для настройки адаптеры конфигурации, статуса и секретов; держите сетевые клиенты, слушатели Gateway и транспортные среды выполнения в основной точке входа расширения. Поля точек входа среды выполнения не переопределяют проверки границ пакета для исходных полей точек входа. Например, openclaw.runtimeExtensions не может сделать выходящий за пределы путь openclaw.extensions загружаемым. openclaw.install.allowInvalidConfigRecovery намеренно узок. Он не делает произвольные сломанные конфигурации устанавливаемыми. Сегодня он только позволяет потокам установки восстанавливаться после конкретных устаревших сбоев обновления встроенного Plugin, таких как отсутствующий путь встроенного Plugin или устаревшая запись channels.<id> для того же встроенного Plugin. Несвязанные ошибки конфигурации по-прежнему блокируют установку и направляют операторов к openclaw doctor --fix. openclaw.channel.persistedAuthState — это метаданные пакета для крошечного модуля проверки:
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
Используйте их, когда настройке, doctor, статусу или потокам присутствия только для чтения нужна дешевая проверка аутентификации да/нет до загрузки полного Plugin канала. Сохраненное состояние аутентификации не является настроенным состоянием канала: не используйте эти метаданные для автоматического включения plugins, исправления зависимостей среды выполнения или решения о том, должна ли загружаться среда выполнения канала. Целевой export должен быть небольшой функцией, которая читает только сохраненное состояние; не проводите ее через полный barrel среды выполнения канала. openclaw.channel.configuredState следует той же форме для дешевых проверок настроенности только через env:
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
Используйте это, когда канал может ответить о настроенном состоянии из env или других маленьких не-runtime входов. Если проверке нужно полное разрешение конфигурации или настоящая среда выполнения канала, оставьте эту логику в хуке Plugin config.hasConfiguredState.

Приоритет обнаружения (повторяющиеся id plugins)

OpenClaw обнаруживает plugins из нескольких корней. Порядок сырого сканирования файловой системы см. в разделе Порядок сканирования Plugin. Если два обнаружения имеют один и тот же id, сохраняется только манифест с наивысшим приоритетом; дубликаты с более низким приоритетом отбрасываются вместо загрузки рядом с ним. Приоритет, от высшего к низшему:
  1. Выбранный конфигурацией — путь, явно закрепленный в plugins.entries.<id>
  2. Встроенный — plugins, поставляемые с OpenClaw
  3. Глобальная установка — plugins, установленные в глобальный корень plugins OpenClaw
  4. Workspace — plugins, обнаруженные относительно текущего workspace
Следствия:
  • Ответвленная или устаревшая копия встроенного Plugin, находящаяся в workspace, не затмит встроенную сборку.
  • Чтобы действительно переопределить встроенный Plugin локальным, закрепите его через plugins.entries.<id>, чтобы он победил по приоритету, а не полагайтесь на обнаружение workspace.
  • Отбрасывания дубликатов логируются, чтобы Doctor и диагностика запуска могли указать на отброшенную копию.
  • Переопределения дубликатов, выбранные конфигурацией, формулируются в диагностике как явные переопределения, но все равно предупреждают, чтобы устаревшие форки и случайные затенения оставались видимыми.

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

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

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

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

Примечания

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

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

Создание plugin

Начало работы с plugin.

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

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

Обзор SDK

Справочник Plugin SDK и импорты подпутей.