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

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

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

openclaw plugins install clawhub:<package-name>

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

Вимоги

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

Виберіть форму плагіна

Швидкий старт

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

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

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

Інструменти можуть бути обов’язковими або необов’язковими. Обов’язкові інструменти завжди доступні, коли плагін увімкнено. Необов’язкові інструменти потребують явного вибору користувача.

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(...), також має бути оголошений у маніфесті плагіна:

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

Користувачі вмикають їх через tools.allow:

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

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

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

Фабрики інструментів отримують runtime-контекстний об’єкт. Використовуйте ctx.activeModel, коли інструменту потрібно журналювати, показувати або адаптуватися до активної моделі для поточного ходу. Об’єкт може містити provider, modelId і modelRef. Сприймайте його як інформаційні runtime-метадані, а не як межу безпеки проти локального оператора, встановленого коду плагіна або зміненого runtime OpenClaw. Чутливі локальні інструменти все одно мають вимагати явного opt-in плагіна або оператора й завершуватися із закритою відмовою, коли метадані активної моделі відсутні або непридатні.

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

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

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

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

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

Користувацькі RPC-методи Gateway є розширеною точкою входу. Тримайте їх на префіксі, специфічному для плагіна; простори імен адміністрування ядра, як-от config.*, exec.approvals.*, operator.admin.*, wizard.* і update.*, залишаються зарезервованими та розв’язуються в operator.admin. Міст openclaw/plugin-sdk/gateway-method-runtime зарезервований для HTTP-маршрутів плагінів, які оголошують 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: