OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Створення плагінів

Plugins розширюють OpenClaw без зміни ядра. Plugin може додати канал обміну повідомленнями, постачальника моделей, локальний бекенд CLI, інструмент агента, хук, постачальника медіа або іншу можливість, що належить Plugin.

Вам не потрібно додавати зовнішній Plugin до репозиторію OpenClaw. Опублікуйте пакет у ClawHub, після чого користувачі зможуть установити його так:

bash
openclaw plugins install clawhub:<package-name>

Специфікації пакетів без префікса під час перехідного періоду запуску все ще встановлюються з npm. Використовуйте префікс clawhub:, коли потрібне розв’язання через ClawHub.

Вимоги

  • Node 22.19+, Node 23.11+ або Node 24+, а також npm чи pnpm.
  • Модулі TypeScript ESM.
  • Для роботи над вбудованим Plugin у репозиторії клонуйте репозиторій і виконайте pnpm install. Розроблення Plugin із вихідного коду можливе лише з pnpm, оскільки OpenClaw виявляє вбудовані Plugins серед пакетів робочого простору extensions/*.

Виберіть тип Plugin

Plugin каналу

Підключіть OpenClaw до платформи обміну повідомленнями.
Plugin постачальника

Додайте постачальника моделей, медіа, пошуку, отримання даних, мовлення або взаємодії в реальному часі.
Plugin бекенду CLI

Запускайте локальний CLI ШІ через резервний вибір моделі OpenClaw.
Plugin інструментів

Зареєструйте інструменти агента.

Швидкий початок

Створіть мінімальний Plugin інструментів, зареєструвавши один обов’язковий інструмент агента. Це найкоротший корисний тип Plugin, який охоплює пакет, маніфест, точку входу та локальну перевірку.

  • Створіть метадані пакета

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    Опубліковані зовнішні Plugins мають спрямовувати записи середовища виконання на зібрані файли JavaScript. Повний контракт точки входу наведено в розділі Точки входу SDK.

    Кожному Plugin потрібен маніфест, навіть за відсутності конфігурації. Інструменти середовища виконання мають бути вказані в contracts.tools, щоб OpenClaw міг визначати їхнього власника без завчасного завантаження середовища виконання кожного Plugin. Задавайте activation.onStartup свідомо; у цьому прикладі Plugin завантажується під час запуску Gateway.

    Довірені хостом поверхні Plugin також обмежуються маніфестом і потребують явного оголошення для встановлених Plugins: для api.registerAgentToolResultMiddleware(...) кожне цільове середовище виконання має бути зазначене в contracts.agentToolResultMiddleware, а для api.registerTrustedToolPolicy(...) кожен ідентифікатор політики має бути вказаний у contracts.trustedToolPolicies. Ці оголошення узгоджують перевірку під час установлення з реєстрацією в середовищі виконання.

    Опис усіх полів маніфесту дивіться в розділі Маніфест Plugin.

  • Зареєструйте інструмент

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Використовуйте definePluginEntry для Plugins, що не є каналами. Натомість Plugins каналів використовують defineChannelPluginEntry з openclaw/plugin-sdk/core.

  • Перевірте середовище виконання

    Для встановленого або зовнішнього Plugin перевірте завантажене середовище виконання:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Якщо Plugin реєструє команду CLI, також запустіть цю команду та перевірте результат, наприклад openclaw demo-plugin ping.

    Для вбудованого Plugin у цьому репозиторії OpenClaw виявляє пакети Plugin із вихідного коду в робочому просторі extensions/*. Запустіть найближчий цільовий тест:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Перевірте встановлення пакета

    Перед публікацією готового до пакування Plugin перевірте той самий спосіб установлення, який отримають користувачі. Спершу додайте крок збирання, спрямуйте записи середовища виконання, як-от openclaw.extensions, на зібраний JavaScript, наприклад ./dist/index.js, і переконайтеся, що npm pack включає цей вивід dist/. Точки входу у вихідному коді TypeScript призначені лише для робочих копій вихідного коду та шляхів локального розроблення.

    Потім запакуйте Plugin і встановіть tar-архів за допомогою npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: використовує керований OpenClaw окремий npm-проєкт для кожного Plugin, тому виявляє помилки залежностей середовища виконання, які може приховати тестування робочої копії вихідного коду. Це підтверджує структуру пакета й залежностей, але не офіційний рівень довіри, пов’язаний із каталогом. Імпортовані в середовищі виконання пакети мають бути в dependencies або optionalDependencies; залежності, залишені лише в devDependencies, не буде встановлено для керованого проєкту середовища виконання.

    Не використовуйте встановлення з необробленого архіву або шляху як остаточне підтвердження офіційної чи привілейованої поведінки Plugin. Необроблені вихідні файли корисні для локального налагодження, але вони не підтверджують той самий шлях залежностей, що й установлення через npm або ClawHub. Якщо ваш Plugin покладається на довірений статус офіційного Plugin, додайте другу перевірку через офіційне встановлення з каталогу або шлях опублікованого пакета, який фіксує офіційний рівень довіри. Докладні відомості про корінь установлення та володіння залежностями дивіться в розділі Розв’язання залежностей Plugin.

  • Опублікуйте

    Перевірте пакет перед публікацією:

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

    Канонічні фрагменти пакетів ClawHub містяться в docs/snippets/plugin-publish/.

  • Установіть

    Установіть опублікований пакет через ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Реєстрація інструментів

    Інструменти можуть бути обов’язковими або необов’язковими. Обов’язкові інструменти завжди доступні, коли Plugin увімкнено. Для необов’язкових інструментів потрібна явна згода користувача, перш ніж OpenClaw завантажить середовище виконання Plugin-власника.

    Фабрики інструментів отримують довірений контекст середовища виконання, зокрема deliveryContext, nativeChannelId для активної розмови на платформі, коли він доступний, і requesterSenderId.

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    Кожен інструмент, зареєстрований за допомогою api.registerTool(...), також має бути оголошений у маніфесті Plugin:

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Користувачі надають згоду через tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    Необов’язкові інструменти визначають, чи буде інструмент доступний моделі. Використовуйте запити дозволів Plugin, коли інструмент або хук має запитати схвалення після того, як модель вибере його, але до виконання дії.

    Використовуйте необов’язкові інструменти для побічних ефектів, нетипових бінарних файлів або можливостей, які не слід надавати за замовчуванням. Назви інструментів не повинні конфліктувати з назвами основних інструментів; конфлікти пропускаються та відображаються в діагностиці Plugin. Некоректні реєстрації пропускаються та відображаються так само: відсутній непорожній name, значення execute, що не є функцією, або дескриптор інструмента без об’єкта parameters.

    Фабрики інструментів отримують наданий середовищем виконання об’єкт контексту. Використовуйте ctx.activeModel, коли інструменту потрібно журналювати, відображати активну модель поточного кроку або адаптуватися до неї; він може містити provider, modelId і modelRef. Розглядайте його як інформаційні метадані середовища виконання, а не межу безпеки проти локального оператора, коду встановленого Plugin або зміненого середовища виконання OpenClaw. Для чутливих локальних інструментів усе одно слід вимагати явної згоди на рівні Plugin або оператора й безпечно відмовляти, якщо метадані активної моделі відсутні або непридатні.

    Маніфест оголошує володіння та виявлення; виконання й надалі викликає активну зареєстровану реалізацію інструмента. Узгоджуйте toolMetadata.<tool>.optional: true з api.registerTool(..., { optional: true }), щоб OpenClaw міг не завантажувати середовище виконання цього Plugin, доки інструмент не буде явно додано до списку дозволених.

    Правила імпорту

    Імпортуйте з цільових підшляхів SDK:

    typescript

    Не імпортуйте із застарілого кореневого модуля-агрегатора:

    typescript

    У пакеті свого Plugin використовуйте локальні файли-агрегатори, як-от api.ts і runtime-api.ts, для внутрішніх імпортів. Не імпортуйте власний Plugin через шлях SDK. Допоміжні засоби, специфічні для постачальника, мають залишатися в пакеті постачальника, якщо межа взаємодії не є справді універсальною.

    Власні методи RPC Gateway — це розширена точка входу. Використовуйте для них префікс, специфічний для Plugin; основні адміністративні простори імен, як-от config.*, exec.approvals.*, operator.admin.*, wizard.* і update.*, залишаються зарезервованими та зіставляються з operator.admin. Міст openclaw/plugin-sdk/gateway-method-runtime зарезервовано для HTTP-маршрутів Plugin, які оголошують contracts.gatewayMethodDispatch: ["authenticated-request"].

    Повну карту імпортів дивіться в розділі Огляд SDK Plugin.

    Контрольний список перед надсиланням

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json містить правильні метадані openclaw OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Маніфест openclaw.plugin.json наявний і коректний OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Точка входу використовує defineChannelPluginEntry або definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Усі імпорти використовують цільові шляхи plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page