Перейти к основному содержанию
Справочник по упаковке plugin (метаданные package.json), манифестам (openclaw.plugin.json), записям настройки и схемам конфигурации.
Ищете пошаговое руководство? Практические руководства рассматривают упаковку в контексте: Channel plugins и Provider plugins.

Метаданные пакета

Вашему package.json нужно поле openclaw, которое сообщает системе plugin, что предоставляет ваш plugin:
{
  "name": "@myorg/openclaw-my-channel",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "Short description of the channel."
    }
  }
}
Если вы публикуете plugin внешне в ClawHub, эти поля compat и build обязательны. Канонические фрагменты для публикации находятся в docs/snippets/plugin-publish/.

Поля openclaw

extensions
string[]
Файлы точек входа (относительно корня пакета).
setupEntry
string
Легковесная точка входа только для настройки (необязательно).
channel
object
Метаданные каталога канала для поверхностей настройки, выбора, быстрого старта и статуса.
providers
string[]
Идентификаторы провайдеров, зарегистрированные этим plugin.
install
object
Подсказки установки: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.
startup
object
Флаги поведения при запуске.

openclaw.channel

openclaw.channel — это недорогие метаданные пакета для обнаружения каналов и поверхностей настройки до загрузки runtime.
ПолеТипЧто это означает
idstringКанонический идентификатор канала.
labelstringОсновная метка канала.
selectionLabelstringМетка в выборе/настройке, когда она должна отличаться от label.
detailLabelstringВторичная детальная метка для более содержательных каталогов каналов и поверхностей статуса.
docsPathstringПуть к документации для ссылок настройки и выбора.
docsLabelstringПереопределяющая метка для ссылок на документацию, когда она должна отличаться от идентификатора канала.
blurbstringКраткое описание для онбординга/каталога.
ordernumberПорядок сортировки в каталогах каналов.
aliasesstring[]Дополнительные псевдонимы поиска для выбора канала.
preferOverstring[]Идентификаторы plugin/каналов с более низким приоритетом, которые этот канал должен опережать.
systemImagestringНеобязательное имя значка/system-image для UI-каталогов каналов.
selectionDocsPrefixstringПрефиксный текст перед ссылками на документацию в поверхностях выбора.
selectionDocsOmitLabelbooleanПоказывать путь к документации напрямую вместо подписанной ссылки на документацию в тексте выбора.
selectionExtrasstring[]Дополнительные короткие строки, добавляемые в текст выбора.
markdownCapablebooleanПомечает канал как поддерживающий Markdown для решений о форматировании исходящих сообщений.
exposureobjectЭлементы управления видимостью канала для настройки, списков настроенных каналов и поверхностей документации.
quickstartAllowFrombooleanПодключить этот канал к стандартному потоку настройки быстрого старта allowFrom.
forceAccountBindingbooleanТребовать явной привязки учетной записи, даже когда существует только одна учетная запись.
preferSessionLookupForAnnounceTargetbooleanПредпочитать поиск сеанса при разрешении целей объявлений для этого канала.
Пример:
{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (self-hosted)",
      "detailLabel": "My Channel Bot",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "Webhook-based self-hosted chat integration.",
      "order": 80,
      "aliases": ["mc"],
      "preferOver": ["my-channel-legacy"],
      "selectionDocsPrefix": "Guide:",
      "selectionExtras": ["Markdown"],
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}
exposure поддерживает:
  • configured: включать канал в поверхности списков настроенных каналов/статуса
  • setup: включать канал в интерактивные средства выбора настройки/конфигурации
  • docs: помечать канал как публичный в поверхностях документации/навигации
showConfigured и showInSetup по-прежнему поддерживаются как устаревшие псевдонимы. Предпочитайте exposure.

openclaw.install

openclaw.install — это метаданные пакета, а не метаданные манифеста.
ПолеТипЧто это означает
clawhubSpecstringКаноническая спецификация ClawHub для установки/обновления и онбординг-потоков установки по требованию.
npmSpecstringКаноническая спецификация npm для резервных потоков установки/обновления.
localPathstringЛокальный путь разработки или встроенной установки.
defaultChoice"clawhub" | "npm" | "local"Предпочитаемый источник установки, когда доступно несколько источников.
minHostVersionstringМинимальная поддерживаемая версия OpenClaw в форме >=x.y.z или >=x.y.z-prerelease.
expectedIntegritystringОжидаемая строка целостности npm-дистрибутива, обычно sha512-..., для закрепленных установок.
allowInvalidConfigRecoverybooleanПозволяет потокам переустановки встроенного plugin восстанавливаться после конкретных сбоев устаревшей конфигурации.
requiredPlatformPackagesstring[]Обязательные платформозависимые псевдонимы npm, проверяемые во время установки npm.
Интерактивный онбординг также использует openclaw.install для поверхностей установки по требованию. Если ваш plugin предоставляет варианты авторизации провайдера или метаданные настройки/каталога канала до загрузки runtime, онбординг может показать этот вариант, предложить установку через ClawHub, npm или локально, установить или включить plugin, а затем продолжить выбранный поток. Варианты онбординга ClawHub используют clawhubSpec и предпочтительны, когда они присутствуют; варианты npm требуют доверенных метаданных каталога со спецификацией реестра npmSpec; точные версии и expectedIntegrity являются необязательными закреплениями npm. Если expectedIntegrity присутствует, потоки установки/обновления принудительно проверяют его для npm. Держите метаданные «что показывать» в openclaw.plugin.json, а метаданные «как это установить» — в package.json.
Если minHostVersion задан, и установка, и загрузка реестра манифестов для невстроенных plugin принудительно его проверяют. Старые хосты пропускают внешние plugin; недопустимые строки версий отклоняются. Встроенные исходные plugin считаются совместно версионированными с checkout хоста.
Для закрепленных установок npm держите точную версию в npmSpec и добавьте ожидаемую целостность артефакта:
{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery не является общим обходом для сломанных конфигураций. Он предназначен только для узкого восстановления встроенных plugin, чтобы переустановка/настройка могла исправлять известные остатки после обновления, например отсутствующий путь встроенного plugin или устаревшую запись channels.<id> для того же plugin. Если конфигурация сломана по несвязанным причинам, установка по-прежнему завершается закрыто и сообщает оператору запустить openclaw doctor --fix.

Отложенная полная загрузка

Plugin каналов могут включить отложенную загрузку с помощью:
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Когда это включено, OpenClaw загружает только setupEntry на этапе запуска до начала прослушивания, даже для уже настроенных каналов. Полная точка входа загружается после того, как Gateway начинает прослушивание.
Включайте отложенную загрузку только когда ваш setupEntry регистрирует все, что нужно Gateway до начала прослушивания (регистрация канала, HTTP-маршруты, методы Gateway). Если полной точке входа принадлежат обязательные возможности запуска, оставьте поведение по умолчанию.
Если ваша настроечная/полная точка входа регистрирует RPC-методы Gateway, держите их на префиксе, специфичном для plugin. Зарезервированные пространства имен администрирования ядра (config.*, exec.approvals.*, wizard.*, update.*) остаются во владении ядра и всегда разрешаются в operator.admin.

Манифест Plugin

Каждый нативный plugin должен поставлять openclaw.plugin.json в корне пакета. OpenClaw использует его для проверки конфигурации без выполнения кода plugin.
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}
Для plugin каналов добавьте kind и channels:
{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
Даже plugin без конфигурации должны поставлять схему. Пустая схема допустима:
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
См. манифест Plugin для полного справочника схемы.

Публикация в ClawHub

Для пакетов плагинов используйте команду ClawHub, предназначенную для пакетов:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
Устаревший псевдоним публикации только Skills предназначен для Skills. Пакеты плагинов всегда должны использовать clawhub package publish.

Точка входа настройки

Файл setup-entry.ts — это облегченная альтернатива index.ts, которую OpenClaw загружает, когда ему нужны только поверхности настройки (первичная настройка, исправление конфигурации, проверка отключенного канала).
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);
Это позволяет не загружать тяжелый код времени выполнения (криптографические библиотеки, регистрации CLI, фоновые службы) во время потоков настройки. Встроенные каналы рабочей области, которые хранят безопасные для настройки экспорты в боковых модулях, могут использовать defineBundledChannelSetupEntry(...) из openclaw/plugin-sdk/channel-entry-contract вместо defineSetupPluginEntry(...). Этот встроенный контракт также поддерживает необязательный экспорт runtime, чтобы связывание времени выполнения на этапе настройки оставалось легким и явным.
  • Канал отключен, но ему нужны поверхности настройки/первичной настройки.
  • Канал включен, но не настроен.
  • Включена отложенная загрузка (deferConfiguredChannelFullLoadUntilAfterListen).
  • Объект Plugin канала (через defineSetupPluginEntry).
  • Любые HTTP-маршруты, необходимые до запуска прослушивания Gateway.
  • Любые методы Gateway, необходимые во время запуска.
Эти методы Gateway для запуска все равно должны избегать зарезервированных административных пространств имен ядра, таких как config.* или update.*.
  • Регистрации CLI.
  • Фоновые службы.
  • Тяжелые импорты времени выполнения (криптография, SDK).
  • Методы Gateway, необходимые только после запуска.

Узкие импорты помощников настройки

Для горячих путей, предназначенных только для настройки, предпочитайте узкие швы помощников настройки более широкому зонтичному модулю plugin-sdk/setup, когда вам нужна только часть поверхности настройки:
Путь импортаДля чего использоватьКлючевые экспорты
plugin-sdk/setup-runtimeпомощники времени выполнения настройки, остающиеся доступными в setupEntry / отложенном запуске каналаcreateSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeустаревший псевдоним совместимости; используйте plugin-sdk/setup-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsпомощники CLI/архивов/документации для настройки/установкиformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
Используйте более широкий шов plugin-sdk/setup, когда вам нужен полный общий набор инструментов настройки, включая помощники исправления конфигурации, такие как moveSingleAccountChannelSectionToDefaultAccount(...). Используйте createSetupTranslator(...) для фиксированного текста мастера настройки. Он следует локали мастера CLI (OPENCLAW_LOCALE, затем системные переменные локали) и откатывается на английский. Храните текст настройки, специфичный для плагина, в коде, принадлежащем плагину, и используйте общие ключи каталога только для общих меток настройки, текста состояния и официального текста настройки встроенных плагинов. Адаптеры исправления настройки остаются безопасными для горячего пути при импорте. Их поиск поверхности контракта встроенного повышения однопользовательской учетной записи ленивый, поэтому импорт plugin-sdk/setup-runtime не загружает нетерпеливо обнаружение поверхности контракта встроенных компонентов до фактического использования адаптера.

Повышение однопользовательской учетной записи, принадлежащее каналу

Когда канал обновляется с конфигурации верхнего уровня для одной учетной записи до channels.<id>.accounts.*, стандартное общее поведение перемещает повышенные значения области учетной записи в accounts.default. Встроенные каналы могут сузить или переопределить это повышение через свою поверхность контракта настройки:
  • singleAccountKeysToMove: дополнительные ключи верхнего уровня, которые должны перейти в повышенную учетную запись
  • namedAccountPromotionKeys: когда именованные учетные записи уже существуют, только эти ключи переходят в повышенную учетную запись; общие ключи политики/доставки остаются в корне канала
  • resolveSingleAccountPromotionTarget(...): выбор существующей учетной записи, которая получает повышенные значения
Matrix — текущий встроенный пример. Если уже существует ровно одна именованная учетная запись Matrix или если defaultAccount указывает на существующий неканонический ключ, такой как Ops, повышение сохраняет эту учетную запись вместо создания новой записи accounts.default.

Схема конфигурации

Конфигурация Plugin проверяется по JSON Schema в вашем манифесте. Пользователи настраивают плагины через:
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}
Ваш плагин получает эту конфигурацию как api.pluginConfig во время регистрации. Для конфигурации, специфичной для канала, используйте вместо этого раздел конфигурации канала:
{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

Создание схем конфигурации канала

Используйте buildChannelConfigSchema, чтобы преобразовать схему Zod в обертку ChannelConfigSchema, используемую артефактами конфигурации, принадлежащими плагину:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

const accountSchema = z.object({
  token: z.string().optional(),
  allowFrom: z.array(z.string()).optional(),
  accounts: z.object({}).catchall(z.any()).optional(),
  defaultAccount: z.string().optional(),
});

const configSchema = buildChannelConfigSchema(accountSchema);
Если вы уже описываете контракт как JSON Schema или TypeBox, используйте прямой помощник, чтобы OpenClaw мог пропустить преобразование Zod в JSON Schema на путях метаданных:
import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

const configSchema = buildJsonChannelConfigSchema(
  Type.Object({
    token: Type.Optional(Type.String()),
    allowFrom: Type.Optional(Type.Array(Type.String())),
  }),
);
Для сторонних плагинов контракт холодного пути по-прежнему находится в манифесте Plugin: отразите сгенерированную JSON Schema в openclaw.plugin.json#channelConfigs, чтобы схема конфигурации, настройка и поверхности UI могли проверять channels.<id> без загрузки кода времени выполнения.

Мастера настройки

Плагины каналов могут предоставлять интерактивные мастера настройки для openclaw onboard. Мастер — это объект ChannelSetupWizard в ChannelPlugin:
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};
Тип ChannelSetupWizard поддерживает credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize и многое другое. Полные примеры см. в пакетах встроенных плагинов (например, в плагине Discord src/channel.setup.ts).
Для запросов списка разрешенных DM, которым нужен только стандартный поток note -> prompt -> parse -> merge -> patch, предпочитайте общие помощники настройки из openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) и createNestedChannelParsedAllowFromPrompt(...).
Для блоков состояния настройки канала, которые отличаются только метками, оценками и необязательными дополнительными строками, предпочитайте createStandardChannelSetupStatus(...) из openclaw/plugin-sdk/setup вместо ручного создания одного и того же объекта status в каждом плагине.
Для необязательных поверхностей настройки, которые должны появляться только в определенных контекстах, используйте createOptionalChannelSetupSurface из openclaw/plugin-sdk/channel-setup:
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";

const setupSurface = createOptionalChannelSetupSurface({
  channel: "my-channel",
  label: "My Channel",
  npmSpec: "@myorg/openclaw-my-channel",
  docsPath: "/channels/my-channel",
});
// Returns { setupAdapter, setupWizard }
plugin-sdk/channel-setup также предоставляет более низкоуровневые сборщики createOptionalChannelSetupAdapter(...) и createOptionalChannelSetupWizard(...), когда вам нужна только одна половина этой поверхности необязательной установки.Сгенерированные необязательные адаптер/мастер закрываются при реальных записях конфигурации. Они повторно используют одно сообщение о необходимости установки в validateInput, applyAccountConfig и finalize, а также добавляют ссылку на документацию, когда задан docsPath.
Для UI настройки на основе бинарных файлов предпочитайте общие делегированные помощники вместо копирования одной и той же связки бинарного файла/состояния в каждый канал:
  • createDetectedBinaryStatus(...) для блоков состояния, которые отличаются только метками, подсказками, оценками и обнаружением бинарного файла
  • createCliPathTextInput(...) для текстовых вводов на основе пути
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) и createDelegatedResolveConfigured(...), когда setupEntry должен лениво перенаправлять к более тяжелому полному мастеру
  • createDelegatedTextInputShouldPrompt(...), когда setupEntry должен делегировать только решение textInputs[*].shouldPrompt

Публикация и установка

Внешние plugins: опубликуйте в ClawHub, затем установите:
openclaw plugins install @myorg/openclaw-my-plugin
Спецификации пакетов без префикса устанавливаются из npm во время перехода при запуске.
Plugins в репозитории: разместите их в дереве рабочей области встроенных plugins, и они будут автоматически обнаружены во время сборки. Пользователи могут установить:
openclaw plugins install <package-name>
Для установок из npm openclaw plugins install устанавливает пакет в отдельный для plugin проект в ~/.openclaw/npm/projects с отключенными lifecycle-скриптами. Держите деревья зависимостей plugin чистыми JS/TS и избегайте пакетов, требующих сборок postinstall.
Запуск Gateway не устанавливает зависимости plugin. Потоки установки npm/git/ClawHub отвечают за согласование зависимостей; у локальных plugins их зависимости уже должны быть установлены.
Метаданные встроенного пакета задаются явно, а не выводятся из собранного JavaScript при запуске gateway. Runtime-зависимости должны находиться в пакете plugin, который ими владеет; запуск упакованного OpenClaw никогда не исправляет и не зеркалирует зависимости plugin.

См. также