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

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

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

Вашому 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."
    }
  }
}

{
  "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/[email protected]",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}

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

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

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

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

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

# Маніфест Plugin

Кожен native 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"
      }
    }
  }
}

Для channel plugins додайте kind і channels:

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

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

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

Див. Маніфест Plugin, щоб отримати повну довідку зі схеми.

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

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

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

# Точка входу для налаштування

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

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

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

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

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

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

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

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

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

Коли канал оновлюється з top-level конфігурації одного облікового запису до channels.<id>.accounts.*, стандартна спільна поведінка переміщує promoted значення, scoped до облікового запису, в accounts.default.

Пакетні канали можуть звузити або перевизначити це просування через свою поверхню контракту налаштування:

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

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

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

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

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

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

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

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

Використовуйте buildChannelConfigSchema, щоб перетворити схему Zod на wrapper ChannelConfigSchema, який використовується артефактами конфігурації, що належать Plugin:

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 на шляхах метаданих:

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

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

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

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-залежності мають бути в пакеті Plugin, якому вони належать; запуск упакованого OpenClaw ніколи не виправляє й не дзеркалює залежності плагінів.

# Пов’язане

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