Створення Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Передумови

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

​

Який тип plugin?

​

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

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

// 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

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

​

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

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

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

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

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

​

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

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

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

​

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

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

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

​

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

​

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

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

​

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

​

Пов’язане

• Архітектура Plugin - глибокий огляд внутрішньої архітектури
• Огляд SDK - довідник Plugin SDK
• Маніфест - формат маніфесту plugin
• Channel Plugins - створення channel plugins
• Provider Plugins - створення provider plugins