Створення Plugin-ів

Plugins розширюють OpenClaw новими можливостями: каналами, провайдерами моделей, мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, генерацією відео, web fetch, web search, інструментами агентів або будь-якою комбінацією.

Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в ClawHub, і користувачі встановлять його за допомогою openclaw plugins install clawhub:<package-name>. Специфікації bare-пакетів усе ще встановлюються з npm під час перехідного запуску.

# Передумови

• Node >= 22 і менеджер пакетів (npm або pnpm)
• Знання TypeScript (ESM)
• Для Plugins у репозиторії: репозиторій клоновано, а pnpm install виконано. Розробка Plugin із checkout вихідного коду підтримує лише pnpm, тому що OpenClaw завантажує bundled Plugins з workspace-пакетів extensions/*.

# Який тип Plugin?

Для Channel Plugin, який не гарантовано буде встановлено під час onboarding/setup, використовуйте createOptionalChannelSetupSurface(...) з openclaw/plugin-sdk/channel-setup. Він створює пару setup adapter + wizard, яка повідомляє про вимогу встановлення й закрито відмовляє в реальних записах конфігурації, доки Plugin не буде встановлено.

# Швидкий старт: tool Plugin

Цей покроковий посібник створює мінімальний Plugin, який реєструє інструмент агента. Для Channel і Provider Plugins є окремі посібники, посилання на які наведено вище.

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

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

// 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}` }] };
      },
    });
  },
});

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

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

# Можливості Plugin

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

Повний registration API дивіться в SDK Overview.

Bundled Plugins можуть використовувати api.registerAgentToolResultMiddleware(...), коли їм потрібне асинхронне переписування результатів інструментів до того, як модель побачить output. Оголосіть цільові runtimes у contracts.agentToolResultMiddleware, наприклад ["pi", "codex"]. Це довірена межа bundled Plugin; зовнішнім Plugins варто віддавати перевагу звичайним hooks OpenClaw Plugin, доки OpenClaw не отримає явну політику довіри для цієї можливості.

Якщо ваш Plugin реєструє власні Gateway RPC methods, тримайте їх на префіксі, специфічному для Plugin. Core admin namespaces (config.*, exec.approvals.*, wizard.*, update.*) залишаються зарезервованими й завжди резолвляться в operator.admin, навіть якщо Plugin запитує вужчу scope.

Семантика hook guard, яку варто пам'ятати:

• before_tool_call: { block: true } є термінальною і зупиняє handlers з нижчим пріоритетом.
• before_tool_call: { block: false } трактується як відсутність рішення.
• before_tool_call: { requireApproval: true } призупиняє виконання агента й запитує схвалення користувача через exec approval overlay, кнопки Telegram, взаємодії Discord або команду /approve у будь-якому каналі.
• before_install: { block: true } є термінальною і зупиняє handlers з нижчим пріоритетом.
• before_install: { block: false } трактується як відсутність рішення.
• message_sending: { cancel: true } є термінальною і зупиняє handlers з нижчим пріоритетом.
• message_sending: { cancel: false } трактується як відсутність рішення.
• message_received: віддавайте перевагу типізованому полю threadId, коли потрібна маршрутизація inbound thread/topic. Залишайте metadata для специфічних для каналу додаткових даних.
• message_sending: віддавайте перевагу типізованим полям маршрутизації replyToId / threadId замість специфічних для каналу ключів metadata.

Команда /approve обробляє як exec approvals, так і Plugin approvals з обмеженим fallback: коли exec approval id не знайдено, OpenClaw повторює той самий id через Plugin approvals. Пересилання Plugin approval можна налаштувати незалежно через approvals.plugin у конфігурації.

Якщо власна approval plumbing має виявляти той самий обмежений fallback-випадок, віддавайте перевагу isApprovalNotFoundError з openclaw/plugin-sdk/error-runtime замість ручного зіставлення рядків про expiration approval.

Приклади й довідник hooks дивіться в Plugin hooks.

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

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

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 },
  );
}

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

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

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

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

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

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

# Реєстрація команд CLI

Плагіни можуть додавати кореневі групи команд openclaw за допомогою api.registerCli. Надайте descriptors для кожного кореня команди верхнього рівня, щоб OpenClaw міг показувати та маршрутизувати команду без завчасного завантаження runtime кожного плагіна.

register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}

Після встановлення перевірте реєстрацію runtime і виконайте команду:

openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping

# Умовні правила імпорту

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

// Wrong: monolithic root (deprecated, will be removed)

Повний довідник підшляхів див. у Огляді SDK.

У своєму плагіні використовуйте локальні barrel-файли (api.ts, runtime-api.ts) для внутрішніх імпортів - ніколи не імпортуйте власний плагін через його шлях SDK.

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

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

Якщо допоміжна функція корисна лише всередині одного вбудованого пакета провайдера, тримайте її на цій межі кореня пакета замість просування до openclaw/plugin-sdk/*.

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

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

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: