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

Плагины OpenClaw могут регистрировать инструменты агента (функции JSON-schema), которые предоставляются LLM во время работы агента. Инструменты могут быть обязательными (всегда доступны) или опциональными (opt-in).

Инструменты агента настраиваются под tools в основной конфигурации или для каждого агента под agents.list[].tools. Политика белого/черного списка контролирует, какие инструменты может вызывать агент.

Базовый инструмент

import { Type } from "@sinclair/typebox";

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Сделать что-то",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

Опциональный инструмент (opt-in)

Опциональные инструменты никогда не включаются автоматически. Пользователи должны добавить их в белый список агента.

export default function (api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Запустить локальный рабочий процесс",
      parameters: {
        type: "object",
        properties: {
          pipeline: { type: "string" },
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Включите опциональные инструменты в agents.list[].tools.allow (или глобально tools.allow):

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool",  // конкретное имя инструмента
            "workflow",       // id плагина (включает все инструменты из этого плагина)
            "group:plugins"   // все инструменты плагинов
          ]
        }
      }
    ]
  }
}

Другие параметры конфигурации, влияющие на доступность инструментов:

  • Белые списки, которые называют только инструменты плагинов, рассматриваются как opt-ins плагинов; инструменты ядра остаются включенными, если вы также не включите инструменты ядра или группы в белый список.
  • tools.profile / agents.list[].tools.profile (базовый белый список)
  • tools.byProvider / agents.list[].tools.byProvider (allow/deny для конкретного провайдера)
  • tools.sandbox.tools.* (политика инструментов sandbox при работе в песочнице)

Правила + советы

  • Имена инструментов не должны конфликтовать с именами инструментов ядра; конфликтующие инструменты пропускаются.
  • ID плагинов, используемые в белых списках, не должны конфликтовать с именами инструментов ядра.
  • Предпочитайте optional: true для инструментов, которые вызывают побочные эффекты или требуют дополнительных бинарных файлов/учетных данных.
← Назад к документации