Создание plugins

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

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

openclaw plugins install clawhub:<package-name>

Спецификации пакетов без префикса во время перехода при запуске по-прежнему устанавливаются из npm. Используйте префикс clawhub:, когда нужно разрешение через ClawHub.

Требования

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

Выберите форму Plugin

Быстрый старт

Создайте минимальный tool 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 включен. Необязательные инструменты требуют явного согласия пользователя.

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"] }, // or ["my-plugin"] for all tools from one plugin}

Необязательные инструменты управляют тем, будет ли инструмент открыт для модели. Используйте запросы разрешений Plugin, когда инструмент или hook должен запросить одобрение после того, как модель его выбрала, и до запуска действия.

Используйте необязательные инструменты для побочных эффектов, необычных бинарных файлов или возможностей, которые не должны открываться по умолчанию. Имена инструментов не должны конфликтовать с инструментами ядра; конфликты пропускаются и отображаются в диагностике Plugin. Некорректные регистрации, включая дескрипторы инструментов без parameters, пропускаются и отображаются таким же образом. Зарегистрированные инструменты являются типизированными функциями, которые модель может вызывать после прохождения проверок политики и allowlist.

Фабрики инструментов получают объект контекста, предоставленный runtime. Используйте ctx.activeModel, когда инструменту нужно логировать, отображать или адаптироваться к активной модели текущего turn. Объект может включать provider, modelId и modelRef. Рассматривайте его как информационные runtime-метаданные, а не как границу безопасности против локального оператора, установленного кода Plugin или измененного runtime OpenClaw. Чувствительные локальные инструменты по-прежнему должны требовать явного согласия Plugin или оператора и завершаться закрыто, если метаданные активной модели отсутствуют или не подходят.

Манифест объявляет владение и обнаружение; выполнение по-прежнему вызывает живую зарегистрированную реализацию инструмента. Держите toolMetadata.<tool>.optional: true согласованным с api.registerTool(..., { optional: true }), чтобы OpenClaw мог не загружать runtime этого Plugin до тех пор, пока инструмент не будет явно добавлен в allowlist.

Соглашения об импортах

Импортируйте из сфокусированных подпутей SDK:

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

Внутри пакета вашего Plugin используйте локальные barrel-файлы, такие как api.ts и runtime-api.ts, для внутренних импортов. Не импортируйте собственный Plugin через путь SDK. Помощники, специфичные для поставщика, должны оставаться в пакете поставщика, если граница не является действительно общей.

Пользовательские методы Gateway RPC являются продвинутой точкой входа. Держите их на префиксе, специфичном для Plugin; пространства имен администрирования ядра, такие как config.*, exec.approvals.*, operator.admin.*, wizard.* и update.*, остаются зарезервированными и разрешаются в operator.admin. Мост openclaw/plugin-sdk/gateway-method-runtime зарезервирован для HTTP-маршрутов Plugin, которые объявляют contracts.gatewayMethodDispatch: ["authenticated-request"].

Полную карту импортов см. в обзоре Plugin SDK.

Контрольный список перед отправкой

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: