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

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

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

openclaw plugins install clawhub:<package-name>

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

Вимоги

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

Вибір структури Plugin

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

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

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

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

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

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

pnpm test extensions/my-plugin/pnpm check

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

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

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

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

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

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

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:

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

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

{  tools: { allow: ["workflow_tool"] }, // або ["my-plugin"] для всіх інструментів одного 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:

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

У пакунку Plugin використовуйте локальні barrel-файли, як-от 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: