Плагины инструментов

defineToolPlugin создаёт плагин, который добавляет только инструменты, вызываемые агентом: без канала, поставщика моделей, обработчика, службы или серверной части настройки. Он создаёт метаданные манифеста, необходимые OpenClaw для обнаружения инструментов без загрузки кода среды выполнения плагина. Для плагинов поставщиков, каналов, обработчиков, служб или плагинов со смешанными возможностями начните с Создание плагинов, Плагины каналов или Плагины поставщиков.

Требования

Node 22.22.3+, Node 24.15+ или Node 25.9+.
Выходной пакет TypeScript ESM.
typebox в dependencies (не только в devDependencies — созданный плагин импортирует его во время выполнения).
openclaw >=2026.5.17 — первая версия, экспортирующая openclaw/plugin-sdk/tool-plugin.
Корень пакета, содержащий dist/, openclaw.plugin.json и package.json.

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

openclaw plugins init stock-quotes --name "Котировки акций"
cd stock-quotes
npm install
npm run plugin:build
npm run plugin:validate
npm test

plugins init создаёт:

Файл	Назначение
`src/index.ts`	Точка входа `defineToolPlugin` с одним инструментом `echo`
`src/index.test.ts`	Тест метаданных, проверяющий список инструментов
`tsconfig.json`	Выходные данные NodeNext TypeScript в `dist/`
`vitest.config.ts`	Конфигурация Vitest для `src/*/.test.ts`
`package.json`	Скрипты, зависимости среды выполнения, `openclaw.extensions: ["./dist/index.js"]`
`openclaw.plugin.json`	Созданные метаданные манифеста для исходного инструмента

npm run plugin:build запускает npm run build (tsc), а затем openclaw plugins build --entry ./dist/index.js. npm run plugin:validate повторно выполняет сборку и запускает openclaw plugins validate --entry ./dist/index.js. При успешной проверке выводится:

Плагин stock-quotes действителен.

Параметры openclaw plugins init <id>:

Флаг	Значение по умолчанию	Действие
`--directory <path>`	`<id>`	Каталог вывода
`--name <name>`	`<id>` в заглавном регистре	Отображаемое имя
`--type <type>`	`tool`	Тип шаблона: `tool` или `provider`
`--force`	выключено	Перезаписать существующий каталог вывода

Написание инструмента

defineToolPlugin принимает идентификационные данные плагина, необязательную схему конфигурации и статический список инструментов. Типы параметров и конфигурации выводятся из схем TypeBox.

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Котировки акций",
  description: "Получение снимков котировок акций.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "Ключ API котировок." })),
    baseUrl: Type.Optional(Type.String({ description: "Базовый URL API котировок." })),
  }),
  tools: (tool) => [
    tool({
      name: "stock_quote",
      label: "Котировка акции",
      description: "Получение снимка котировки акции.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Биржевой символ, например OPEN." }),
      }),
      async execute({ symbol }, config, context) {
        context.signal?.throwIfAborted();
        return {
          symbol: symbol.toUpperCase(),
          configured: Boolean(config.apiKey),
          baseUrl: config.baseUrl ?? "https://api.example.com",
        };
      },
    }),
  ],
});

Имена инструментов являются стабильным API. Выбирайте уникальные имена в нижнем регистре, достаточно конкретные, чтобы избежать конфликтов с основными инструментами или другими плагинами.

Необязательные инструменты и фабрики инструментов

Задайте optional: true, если пользователи должны явно добавить инструмент в список разрешённых, прежде чем он будет отправлен модели. openclaw plugins build записывает соответствующую запись манифеста toolMetadata.<tool>.optional, поэтому OpenClaw может определить, что инструмент является необязательным, без загрузки кода среды выполнения плагина.

tool({
  name: "workflow_run",
  description: "Запуск внешнего рабочего процесса.",
  parameters: Type.Object({ goal: Type.String() }),
  optional: true,
  execute: ({ goal }) => ({ queued: true, goal }),
});

Используйте factory, когда для создания инструмента требуется контекст инструмента среды выполнения — чтобы отказаться от него для конкретного запуска, проверить состояние песочницы или привязать вспомогательные функции среды выполнения. Метаданные остаются статическими, хотя конкретный инструмент создаётся во время выполнения.

tool({
  name: "local_workflow",
  description: "Запуск локального рабочего процесса вне изолированных сеансов.",
  parameters: Type.Object({ goal: Type.String() }),
  optional: true,
  factory({ api, toolContext }) {
    if (toolContext.sandboxed) {
      return null;
    }
    return createLocalWorkflowTool(api);
  },
});

Фабрики по-прежнему заранее объявляют фиксированное имя инструмента. Используйте definePluginEntry напрямую, когда плагин динамически вычисляет имена инструментов или объединяет инструменты с обработчиками, службами, поставщиками или командами.

Возвращаемые значения

defineToolPlugin оборачивает обычные возвращаемые значения в формат результата инструмента OpenClaw:

Возвращайте строку, если модель должна увидеть именно этот текст.
Возвращайте JSON-совместимое значение, если модель должна увидеть форматированный JSON, а OpenClaw — сохранить исходное значение в details.

tool({
  name: "echo_text",
  description: "Повторение входного текста.",
  parameters: Type.Object({
    input: Type.String(),
  }),
  execute: ({ input }) => input,
});

tool({
  name: "echo_json",
  description: "Повторение входных данных в виде структурированного JSON.",
  parameters: Type.Object({
    input: Type.String(),
  }),
  execute: ({ input }) => ({ input, length: input.length }),
});

Используйте фабрику инструментов, когда требуется пользовательский AgentToolResult или необходимо повторно использовать существующую реализацию api.registerTool.

Конфигурация

configSchema является необязательной. Если её опустить, OpenClaw применит строгую схему пустого объекта; созданный манифест всё равно будет содержать configSchema.

export default defineToolPlugin({
  id: "no-config-tools",
  name: "Инструменты без конфигурации",
  description: "Добавляет инструменты, которым не требуется конфигурация.",
  tools: () => [],
});

При наличии configSchema тип второго аргумента execute выводится из неё:

const configSchema = Type.Object({
  apiKey: Type.String(),
});

export default defineToolPlugin({
  id: "configured-tools",
  name: "Настроенные инструменты",
  description: "Добавляет настроенные инструменты.",
  configSchema,
  tools: (tool) => [
    tool({
      name: "configured_ping",
      description: "Проверка доступности конфигурации.",
      parameters: Type.Object({}),
      execute: (_params, config) => ({ hasKey: config.apiKey.length > 0 }),
    }),
  ],
});

OpenClaw считывает конфигурацию плагина из записи плагина в конфигурации Gateway. Не указывайте секреты непосредственно в исходном коде или примерах документации; используйте конфигурацию, переменные окружения или SecretRefs в соответствии с моделью безопасности плагина.

Созданные метаданные

OpenClaw должен прочитать манифест плагина до импорта кода среды выполнения плагина. defineToolPlugin предоставляет для этого статические метаданные, а openclaw plugins build записывает их в пакет. Повторно запускайте генератор после изменения идентификатора, имени, описания, схемы конфигурации, активации или имён инструментов плагина:

npm run build
openclaw plugins build --entry ./dist/index.js

Созданный манифест для плагина с одним инструментом:

{
  "id": "stock-quotes",
  "name": "Котировки акций",
  "description": "Получение снимков котировок акций.",
  "version": "0.1.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "activation": {
    "onStartup": true
  },
  "contracts": {
    "tools": ["stock_quote"]
  }
}

contracts.tools — важный контракт обнаружения: он сообщает OpenClaw, какому плагину принадлежит каждый инструмент, без загрузки среды выполнения каждого установленного плагина. Из-за устаревшего манифеста инструмент может отсутствовать при обнаружении либо ошибка регистрации может быть ошибочно приписана другому плагину.

Метаданные пакета

openclaw plugins build также согласует package.json с выбранной точкой входа среды выполнения:

{
  "type": "module",
  "files": ["dist", "openclaw.plugin.json", "README.md"],
  "dependencies": {
    "typebox": "^1.1.38"
  },
  "peerDependencies": {
    "openclaw": ">=2026.5.17"
  },
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

Публикуйте собранный JavaScript (./dist/index.js), а не точку входа исходного кода TypeScript. Точки входа исходного кода работают только при локальной разработке в рабочей области.

Проверка в CI

plugins build --check завершается с ошибкой без перезаписи файлов, если созданные метаданные устарели:

npm run build
openclaw plugins build --entry ./dist/index.js --check
openclaw plugins validate --entry ./dist/index.js
npm test

plugins validate проверяет следующее:

openclaw.plugin.json существует и проходит обычную загрузку манифеста.
Текущая точка входа экспортирует метаданные defineToolPlugin.
Поля созданного манифеста соответствуют метаданным точки входа.
contracts.tools соответствует объявленным именам инструментов.
package.json направляет openclaw.extensions на выбранную точку входа среды выполнения.

Локальная установка и проверка

Из отдельной копии OpenClaw или установленного CLI установите пакет по его пути:

openclaw plugins install ./stock-quotes
openclaw plugins inspect stock-quotes --runtime

Для проверки упакованной версии сначала создайте пакет и установите tar-архив:

npm pack
openclaw plugins install npm-pack:./openclaw-plugin-stock-quotes-0.1.0.tgz
openclaw plugins inspect stock-quotes --runtime --json

После установки перезапустите или перезагрузите Gateway и попросите агента использовать инструмент. Если инструмент не отображается, проверьте среду выполнения плагина и действующий каталог инструментов, прежде чем изменять код (см. Устранение неполадок).

Публикация

Когда пакет будет готов, опубликуйте его через ClawHub. clawhub package publish принимает источник: локальную папку, репозиторий GitHub (owner/repo[@ref]) или URL tar-архива.

clawhub package publish ./stock-quotes --dry-run
clawhub package publish ./stock-quotes

Установите с явным указателем ClawHub:

openclaw plugins install clawhub:your-org/stock-quotes

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

Устранение неполадок

`plugin entry not found: ./dist/index.js`

Выбранный файл точки входа не существует. Запустите npm run build, затем повторно запустите openclaw plugins build --entry ./dist/index.js или openclaw plugins validate --entry ./dist/index.js.

`plugin entry does not expose defineToolPlugin metadata`

Точка входа не экспортировала значение, созданное defineToolPlugin. Убедитесь, что экспорт модуля по умолчанию является результатом defineToolPlugin(...), либо передайте правильную точку входа с помощью --entry.

`openclaw.plugin.json generated metadata is stale`

Манифест больше не соответствует метаданным точки входа. Выполните:

npm run build
openclaw plugins build --entry ./dist/index.js

Зафиксируйте изменения как openclaw.plugin.json, так и package.json.

`package.json openclaw.extensions must include ./dist/index.js`

Метаданные пакета указывают на другую точку входа среды выполнения. Запустите openclaw plugins build --entry ./dist/index.js, чтобы генератор согласовал метаданные пакета с точкой входа, которую вы намерены опубликовать.

`Cannot find package 'typebox'`

Собранный плагин импортирует typebox во время выполнения. Оставьте его в dependencies, повторно установите зависимости, выполните сборку и снова запустите проверку.

Инструмент не отображается после установки

Проверьте следующее по порядку:

openclaw plugins inspect <plugin-id> --runtime
openclaw plugins validate --root <plugin-root> --entry ./dist/index.js
openclaw.plugin.json содержит contracts.tools с ожидаемыми именами инструментов.
package.json содержит openclaw.extensions: ["./dist/index.js"].
Gateway был перезапущен или перезагружен после установки плагина.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Плагины инструментов

Требования

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

Написание инструмента

Необязательные инструменты и фабрики инструментов

Возвращаемые значения

Конфигурация

Созданные метаданные

Метаданные пакета

Проверка в CI

Локальная установка и проверка

Публикация

Устранение неполадок

`plugin entry not found: ./dist/index.js`

`plugin entry does not expose defineToolPlugin metadata`

`openclaw.plugin.json generated metadata is stale`

`package.json openclaw.extensions must include ./dist/index.js`

`Cannot find package 'typebox'`

Инструмент не отображается после установки

См. также

​Требования

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

​Написание инструмента

​Необязательные инструменты и фабрики инструментов

​Возвращаемые значения

​Конфигурация

​Созданные метаданные

​Метаданные пакета

​Проверка в CI

​Локальная установка и проверка

​Публикация

​Устранение неполадок

​plugin entry not found: ./dist/index.js

​plugin entry does not expose defineToolPlugin metadata

​openclaw.plugin.json generated metadata is stale

​package.json openclaw.extensions must include ./dist/index.js

​Cannot find package 'typebox'

​Инструмент не отображается после установки

​См. также

Требования

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

Написание инструмента

Необязательные инструменты и фабрики инструментов

Возвращаемые значения

Конфигурация

Созданные метаданные

Метаданные пакета

Проверка в CI

Локальная установка и проверка

Публикация

Устранение неполадок

`plugin entry not found: ./dist/index.js`

`plugin entry does not expose defineToolPlugin metadata`

`openclaw.plugin.json generated metadata is stale`

`package.json openclaw.extensions must include ./dist/index.js`

`Cannot find package 'typebox'`

Инструмент не отображается после установки

См. также