Налаштування та конфігурація Plugin

Довідник із пакування плагінів (метадані package.json), маніфестів (openclaw.plugin.json), записів налаштування та схем конфігурації.

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

Вашому package.json потрібне поле openclaw, яке повідомляє системі плагінів, що надає ваш плагін:

{  "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."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Поля openclaw

openclaw.channel

openclaw.channel — це легкі метадані пакета для виявлення каналів і поверхонь налаштування до завантаження runtime.

Приклад:

{  "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: позначати канал як публічний у поверхнях документації/навігації

openclaw.install

openclaw.install — це метадані пакета, а не метадані маніфесту.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Відкладене повне завантаження

Плагіни каналів можуть увімкнути відкладене завантаження за допомогою:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Коли це ввімкнено, OpenClaw завантажує лише setupEntry під час фази запуску до прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того, як gateway починає прослуховування.

Якщо ваш запис налаштування/повний запис реєструє RPC-методи gateway, тримайте їх на префіксі, специфічному для плагіна. Зарезервовані простори імен адміністрування core (config.*, exec.approvals.*, wizard.*, update.*) залишаються у власності core і завжди зіставляються з operator.admin.

Маніфест плагіна

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

{  "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"      }    }  }}

Для плагінів каналів додайте kind і channels:

{  "id": "my-channel",  "kind": "channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Навіть плагіни без конфігурації мають постачати схему. Порожня схема є дійсною:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Див. Маніфест плагіна для повного довідника схеми.

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

Для пакетів плагінів використовуйте команду ClawHub, специфічну для пакета:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Запис налаштування

Файл setup-entry.ts — це легка альтернатива index.ts, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, виправлення конфігурації, перевірка вимкненого каналу).

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Це дає змогу не завантажувати важкий runtime-код (криптографічні бібліотеки, реєстрації CLI, фонові сервіси) під час потоків налаштування.

Пакетні канали робочого простору, які тримають setup-safe експорти в sidecar-модулях, можуть використовувати defineBundledChannelSetupEntry(...) з openclaw/plugin-sdk/channel-entry-contract замість defineSetupPluginEntry(...). Цей пакетний контракт також підтримує необов’язковий експорт runtime, щоб runtime-зв’язування під час налаштування залишалося легким і явним.

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

Для гарячих setup-only шляхів віддавайте перевагу вузьким швам помічників налаштування замість ширшого umbrella plugin-sdk/setup, коли вам потрібна лише частина поверхні налаштування:

Використовуйте ширший шов plugin-sdk/setup, коли потрібен повний спільний toolbox налаштування, включно з config-patch помічниками, як-от moveSingleAccountChannelSectionToDefaultAccount(...).

Setup patch adapters залишаються безпечними для hot-path під час імпорту. Їхній пакетний single-account promotion contract-surface lookup є лінивим, тому імпорт plugin-sdk/setup-runtime не завантажує заздалегідь bundled contract-surface discovery до фактичного використання адаптера.

Channel-owned single-account promotion

Коли канал оновлюється з single-account top-level config до channels.<id>.accounts.*, стандартна спільна поведінка переносить promoted account-scoped values до accounts.default.

Пакетні канали можуть звузити або перевизначити це promotion через свою setup contract surface:

• singleAccountKeysToMove: додаткові top-level keys, які мають перейти до promoted account
• namedAccountPromotionKeys: коли named accounts уже існують, лише ці keys переходять до promoted account; shared policy/delivery keys залишаються в корені каналу
• resolveSingleAccountPromotionTarget(...): вибрати, який наявний account отримає promoted values

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

Конфігурація Plugin перевіряється за JSON Schema у вашому manifest. Користувачі налаштовують plugins через:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Ваш Plugin отримує цю конфігурацію як api.pluginConfig під час реєстрації.

Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Створення схем конфігурації каналів

Використовуйте buildChannelConfigSchema, щоб перетворити Zod schema на wrapper ChannelConfigSchema, який використовується plugin-owned config artifacts:

  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, використовуйте direct helper, щоб OpenClaw міг пропустити перетворення Zod-to-JSON-Schema на metadata paths:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Для third-party plugins cold-path contract усе ще є plugin manifest: віддзеркальте згенеровану JSON Schema в openclaw.plugin.json#channelConfigs, щоб schema конфігурації, налаштування та поверхні UI могли перевіряти channels.<id> без завантаження runtime-коду.

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

Channel plugins можуть надавати інтерактивні майстри налаштування для openclaw onboard. Майстер — це об’єкт ChannelSetupWizard у ChannelPlugin:

 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 та інше. Повні приклади дивіться в пакетах bundled plugin (наприклад, у Discord Plugin src/channel.setup.ts).

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 }

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

Зовнішні plugins: опублікуйте в ClawHub, потім встановіть:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Плагіни в репозиторії: розмістіть їх у дереві робочої області вбудованих плагінів, і вони автоматично виявлятимуться під час збірки.

Користувачі можуть установити:

openclaw plugins install <package-name>

Метадані вбудованого пакета є явними, а не виводяться зі зібраного JavaScript під час запуску Gateway. Runtime-залежності належать пакету плагіна, який ними володіє; запуск упакованого OpenClaw ніколи не відновлює й не дзеркалює залежності плагінів.

Пов’язане

• Створення плагінів — покроковий посібник для початку роботи
• Маніфест Plugin — повний довідник схеми маніфесту
• Точки входу SDK — definePluginEntry і defineChannelPluginEntry