Перейти до основного вмісту
Довідник із пакування Plugin (package.json метадані), маніфестів (openclaw.plugin.json), записів налаштування та схем конфігурації.
Шукаєте покроковий посібник? Практичні посібники пояснюють пакування в контексті: Plugin каналів і Plugin провайдерів.

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

Ваш 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 — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження середовища виконання.
ПолеТипЩо це означає
idstringКанонічний ідентифікатор каналу.
labelstringОсновна мітка каналу.
selectionLabelstringМітка вибору/налаштування, коли вона має відрізнятися від label.
detailLabelstringВторинна детальна мітка для розширених каталогів каналів і поверхонь статусу.
docsPathstringШлях документації для посилань налаштування та вибору.
docsLabelstringПеревизначена мітка для посилань документації, коли вона має відрізнятися від ідентифікатора каналу.
blurbstringКороткий опис для онбордингу/каталогу.
ordernumberПорядок сортування в каталогах каналів.
aliasesstring[]Додаткові псевдоніми пошуку для вибору каналу.
preferOverstring[]Ідентифікатори Plugin/каналів нижчого пріоритету, які цей канал має випереджати.
systemImagestringНеобов’язкова назва піктограми/системного зображення для 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 dist, зазвичай sha512-..., для закріплених встановлень.
allowInvalidConfigRecoverybooleanДозволяє потокам перевстановлення вбудованого Plugin відновлюватися після конкретних збоїв застарілої конфігурації.
requiredPlatformPackagesstring[]Обов’язкові платформозалежні псевдоніми npm, які перевіряються під час встановлення npm.
Інтерактивний онбординг також використовує openclaw.install для поверхонь встановлення на вимогу. Якщо ваш Plugin показує варіанти автентифікації провайдера або метадані налаштування/каталогу каналу до завантаження середовища виконання, онбординг може показати цей варіант, запропонувати 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.*) залишаються у власності core і завжди розв’язуються в 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": {}
  }
}
Навіть плагіни без конфігурації мають постачатися зі схемою. Порожня схема є валідною:
{
  "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. Пакети Plugin завжди мають використовувати 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);
Це дає змогу не завантажувати важкий runtime-код (криптографічні бібліотеки, реєстрації CLI, фонові служби) під час потоків налаштування. Вбудовані канали робочого простору, які тримають безпечні для налаштування експорти в допоміжних модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей вбудований контракт також підтримує необов’язковий експорт runtime, щоб wiring runtime під час налаштування залишався легким і явним.
  • Канал вимкнений, але потребує поверхонь налаштування/початкового налаштування.
  • Канал увімкнений, але не налаштований.
  • Відкладене завантаження увімкнено (deferConfiguredChannelFullLoadUntilAfterListen).
  • Об’єкт Plugin каналу (через defineSetupPluginEntry).
  • Будь-які HTTP-маршрути, потрібні до прослуховування gateway.
  • Будь-які методи gateway, потрібні під час запуску.
Ці методи gateway запуску все одно мають уникати зарезервованих просторів імен адміністрування core, як-от config.* або update.*.
  • Реєстрації CLI.
  • Фонові служби.
  • Важкі імпорти runtime (криптографія, SDK).
  • Методи Gateway, потрібні лише після запуску.

Вузькі імпорти помічників налаштування

Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам помічників налаштування над ширшою парасолькою plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:
Шлях імпортуДля чого використовуватиКлючові експорти
plugin-sdk/setup-runtimeruntime-помічники часу налаштування, які залишаються доступними в 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 текст налаштування в коді, яким володіє Plugin, і використовуйте спільні ключі каталогу лише для поширених міток налаштування, тексту статусу та офіційного тексту налаштування вбудованих Plugin. Адаптери виправлень налаштування залишаються безпечними для гарячого шляху під час імпорту. Їхній вбудований lookup поверхні контракту просування одного облікового запису є лінивим, тому імпорт plugin-sdk/setup-runtime не завантажує завчасно discovery вбудованої поверхні контракту до фактичного використання адаптера.

Просування одного облікового запису, яким володіє канал

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

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

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

Побудова схем конфігурації каналів

Використовуйте buildChannelConfigSchema, щоб перетворити схему Zod на обгортку ChannelConfigSchema, яку використовують артефакти конфігурації, якими володіє Plugin:
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-to-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> без завантаження runtime-коду.

Майстри налаштування

Плагіни каналів можуть надавати інтерактивні майстри налаштування для 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 тощо. Повні приклади див. у пакетах вбудованих Plugin (наприклад, Plugin Discord src/channel.setup.ts).
Для запитів allowlist DM, яким потрібен лише стандартний потік note -> prompt -> parse -> merge -> patch, віддавайте перевагу спільним помічникам налаштування з openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) і createNestedChannelParsedAllowFromPrompt(...).
Для блоків статусу налаштування каналу, які відрізняються лише мітками, оцінками та необов’язковими додатковими рядками, віддавайте перевагу createStandardChannelSetupStatus(...) з openclaw/plugin-sdk/setup замість ручного створення того самого об’єкта status у кожному Plugin.
Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте 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 також надає нижчорівневі builders createOptionalChannelSetupAdapter(...) і createOptionalChannelSetupWizard(...), коли вам потрібна лише одна половина цієї поверхні необов’язкового встановлення.Згенерований необов’язковий адаптер/майстер відмовляє закрито під час реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в validateInput, applyAccountConfig і finalize та додають посилання на документацію, коли встановлено docsPath.
Для UI налаштування на основі бінарних файлів віддавайте перевагу спільним делегованим помічникам замість копіювання того самого glue для бінарного файлу/статусу в кожен канал:
  • createDetectedBinaryStatus(...) для блоків стану, що відрізняються лише мітками, підказками, оцінками та виявленням бінарного файла
  • createCliPathTextInput(...) для текстових полів вводу на основі шляху
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) і createDelegatedResolveConfigured(...), коли setupEntry потрібно відкладено переспрямувати до важчого повного майстра
  • createDelegatedTextInputShouldPrompt(...), коли setupEntry потрібно лише делегувати рішення textInputs[*].shouldPrompt

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

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

Пов’язане