Building Plugins

Плагіни розширюють OpenClaw новими можливостями: канали, провайдери моделей, мовлення, транскрибування в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання вебданих, вебпошук, інструменти агента або будь-яка комбінація. Вам не потрібно додавати свій плагін до репозиторію OpenClaw. Опублікуйте його в ClawHub або npm, а користувачі встановлять його за допомогою openclaw plugins install <package-name>. OpenClaw спочатку намагається використати ClawHub, а потім автоматично переходить до npm.

Передумови

Node >= 22 і менеджер пакетів (npm або pnpm)
Знайомство з TypeScript (ESM)
Для плагінів у репозиторії: клонований репозиторій і виконаний pnpm install

Який тип плагіна?

Плагін каналу

Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)

Плагін провайдера

Додайте провайдера моделей (LLM, проксі або власну кінцеву точку)

Плагін інструмента / хука

Зареєструйте інструменти агента, хуки подій або сервіси — продовження нижче

Якщо плагін каналу є необов’язковим і може бути не встановлений під час запуску онбордингу/налаштування, використовуйте createOptionalChannelSetupSurface(...) з openclaw/plugin-sdk/channel-setup. Він створює пару адаптер + майстер налаштування, яка повідомляє про вимогу встановлення та безпечно блокує реальні записи конфігурації, доки плагін не буде встановлено.

Швидкий старт: плагін інструмента

У цьому прикладі створюється мінімальний плагін, який реєструє інструмент агента. Для каналів і плагінів провайдерів є окремі посібники, посилання на які наведено вище.

Створіть пакет і маніфест

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

Кожному плагіну потрібен маніфест, навіть без конфігурації. Повну схему див. у Manifest. Канонічні фрагменти публікації в ClawHub розміщені в docs/snippets/plugin-publish/.

Напишіть точку входу

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry призначено для плагінів, які не є каналами. Для каналів використовуйте defineChannelPluginEntry — див. Channel Plugins. Повний список параметрів точки входу див. у Entry Points.

Протестуйте й опублікуйте

Зовнішні плагіни: перевірте та опублікуйте через ClawHub, а потім установіть:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів, таких як @myorg/openclaw-my-plugin.Плагіни в репозиторії: розміщуйте у дереві workspace bundled plugin — вони виявляються автоматично.

pnpm test -- <bundled-plugin-root>/my-plugin/

Можливості плагінів

Один плагін може реєструвати будь-яку кількість можливостей через об’єкт api:

Можливість	Метод реєстрації	Докладний посібник
Текстова інференція (LLM)	`api.registerProvider(...)`	Provider Plugins
Канал / обмін повідомленнями	`api.registerChannel(...)`	Channel Plugins
Мовлення (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Транскрибування в реальному часі	`api.registerRealtimeTranscriptionProvider(...)`	Provider Plugins
Голос у реальному часі	`api.registerRealtimeVoiceProvider(...)`	Provider Plugins
Розуміння медіа	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Генерація зображень	`api.registerImageGenerationProvider(...)`	Provider Plugins
Генерація відео	`api.registerVideoGenerationProvider(...)`	Provider Plugins
Отримання вебданих	`api.registerWebFetchProvider(...)`	Provider Plugins
Вебпошук	`api.registerWebSearchProvider(...)`	Provider Plugins
Інструменти агента	`api.registerTool(...)`	Нижче
Власні команди	`api.registerCommand(...)`	Entry Points
Хуки подій	`api.registerHook(...)`	Entry Points
HTTP-маршрути	`api.registerHttpRoute(...)`	Internals
Підкоманди CLI	`api.registerCli(...)`	Entry Points

Повний API реєстрації див. у SDK Overview. Якщо ваш плагін реєструє власні методи gateway RPC, використовуйте для них префікс, специфічний для плагіна. Простори імен адміністрування ядра (config.*, exec.approvals.*, wizard.*, update.*) залишаються зарезервованими й завжди відповідають operator.admin, навіть якщо плагін просить вужчу область дії. Семантика захисних рішень для хуків, про яку варто пам’ятати:

before_tool_call: { block: true } є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
before_tool_call: { block: false } вважається відсутністю рішення.
before_tool_call: { requireApproval: true } призупиняє виконання агента й запитує схвалення користувача через накладку підтвердження виконання, кнопки Telegram, інтеракції Discord або команду /approve у будь-якому каналі.
before_install: { block: true } є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
before_install: { block: false } вважається відсутністю рішення.
message_sending: { cancel: true } є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
message_sending: { cancel: false } вважається відсутністю рішення.

Команда /approve обробляє як підтвердження виконання, так і підтвердження плагінів із обмеженим резервним сценарієм: якщо ідентифікатор підтвердження виконання не знайдено, OpenClaw повторно пробує той самий ідентифікатор через підтвердження плагінів. Переспрямування підтверджень плагінів можна налаштовувати окремо через approvals.plugin у конфігурації. Якщо для власної логіки підтвердження потрібно виявляти той самий випадок обмеженого резервного сценарію, використовуйте isApprovalNotFoundError з openclaw/plugin-sdk/error-runtime замість ручного зіставлення рядків про завершення строку підтвердження. Подробиці див. у SDK Overview hook decision semantics.

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

Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди доступними) або необов’язковими (користувач вмикає їх сам):

register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  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 },
  );
}

Користувачі вмикають необов’язкові інструменти в конфігурації:

{
  tools: { allow: ["workflow_tool"] },
}

Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються)
Використовуйте optional: true для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів
Користувачі можуть увімкнути всі інструменти з плагіна, додавши ідентифікатор плагіна до tools.allow

Угоди щодо імпорту

Завжди імпортуйте з цільових шляхів openclaw/plugin-sdk/<subpath>:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Повний довідник щодо підшляхів див. у SDK Overview. Усередині свого плагіна використовуйте локальні barrel-файли (api.ts, runtime-api.ts) для внутрішніх імпортів — ніколи не імпортуйте власний плагін через його шлях SDK. Для плагінів провайдерів зберігайте специфічні для провайдера допоміжні функції в цих barrel-файлах у корені пакета, якщо лише цей інтерфейс справді не є універсальним. Поточні bundled-приклади:

Anthropic: обгортки потоків Claude і допоміжні засоби service_tier / beta
OpenAI: конструктори провайдерів, допоміжні засоби моделей за замовчуванням, провайдери realtime
OpenRouter: конструктор провайдера та допоміжні засоби онбордингу/конфігурації

Якщо допоміжна функція корисна лише в межах одного bundled-пакета провайдера, залишайте її на цьому інтерфейсі в корені пакета замість того, щоб переносити її до openclaw/plugin-sdk/*. Деякі згенеровані інтерфейси допоміжних засобів openclaw/plugin-sdk/<bundled-id> все ще існують для підтримки bundled-плагінів і сумісності, наприклад plugin-sdk/feishu-setup або plugin-sdk/zalo-setup. Розглядайте їх як зарезервовані поверхні, а не як типовий шаблон для нових сторонніх плагінів.

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

package.json має правильні метадані openclaw

Маніфест openclaw.plugin.json наявний і коректний

У точці входу використовується defineChannelPluginEntry або definePluginEntry

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

Внутрішні імпорти використовують локальні модулі, а не самоімпорти через SDK

Тести проходять (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check проходить (для плагінів у репозиторії)

Тестування бета-релізів

Стежте за тегами релізів GitHub у openclaw/openclaw і підпишіться через Watch > Releases. Бета-теги мають вигляд v2026.3.N-beta.1. Також можна ввімкнути сповіщення для офіційного акаунта OpenClaw у X @openclaw для оголошень про релізи.
Протестуйте свій плагін із бета-тегом щойно він з’явиться. Вікно до стабільного релізу зазвичай триває лише кілька годин.
Після тестування напишіть у гілці свого плагіна в Discord-каналі plugin-forum або all good, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
Якщо щось зламалося, відкрийте або оновіть issue з назвою Beta blocker: <plugin-name> - <summary> і додайте мітку beta-blocker. Додайте посилання на issue у свою гілку.
Відкрийте PR до main із назвою fix(<plugin-id>): beta blocker - <summary> і додайте посилання на issue як у PR, так і у свою гілку Discord. Учасники не можуть ставити мітки PR, тому заголовок є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити до релізу. Мейнтейнери стежать за цими гілками під час бета-тестування.
Відсутність повідомлень означає, що все гаразд. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить до наступного циклу.

Наступні кроки

Channel Plugins

Створіть плагін каналу обміну повідомленнями

Provider Plugins

Створіть плагін провайдера моделей

SDK Overview

Довідник карти імпортів і API реєстрації

Runtime Helpers

TTS, пошук, субагент через api.runtime

Testing

Утиліти та шаблони тестування

Plugin Manifest

Повний довідник зі схеми маніфесту

Пов’язане

Plugin Architecture — глибокий огляд внутрішньої архітектури
SDK Overview — довідник Plugin SDK
Manifest — формат маніфесту плагіна
Channel Plugins — створення плагінів каналів
Provider Plugins — створення плагінів провайдерів

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Building Plugins

Building Plugins

Передумови

Який тип плагіна?

Плагін каналу

Плагін провайдера

Плагін інструмента / хука

Швидкий старт: плагін інструмента

Можливості плагінів

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

Угоди щодо імпорту

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

Тестування бета-релізів

Наступні кроки

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

Пов’язане

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Building Plugins

​Передумови

​Який тип плагіна?

Плагін каналу

Плагін провайдера

Плагін інструмента / хука

​Швидкий старт: плагін інструмента

​Можливості плагінів

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

​Угоди щодо імпорту

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

​Тестування бета-релізів

​Наступні кроки

Channel Plugins

Provider Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​Пов’язане

Building Plugins

Передумови

Який тип плагіна?

Швидкий старт: плагін інструмента

Можливості плагінів

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

Угоди щодо імпорту

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

Тестування бета-релізів

Наступні кроки

Пов’язане