Плагины (расширения)

Быстрый старт (новичок в плагинах?)

Плагин — это просто небольшой модуль кода, который расширяет OpenClaw дополнительными функциями (команды, инструменты и Gateway RPC).

В большинстве случаев вы будете использовать плагины, когда хотите функцию, которой еще нет в ядре OpenClaw (или хотите держать дополнительные функции вне основной установки).

Быстрый путь:

  1. Посмотрите, что уже загружено:
openclaw plugins list
  1. Установите официальный плагин (пример: Voice Call):
openclaw plugins install @openclaw/voice-call
  1. Перезапустите Gateway, затем настройте под plugins.entries.<id>.config.

См. Voice Call для конкретного примера плагина.

Доступные плагины (официальные)

  • Microsoft Teams является только плагином с версии 2026.1.15; установите @openclaw/msteams, если используете Teams.
  • Memory (Core) — встроенный плагин поиска в памяти (включен по умолчанию через plugins.slots.memory)
  • Memory (LanceDB) — встроенный плагин долговременной памяти (автоматический отзыв/захват; установите plugins.slots.memory = "memory-lancedb")
  • Voice Call — @openclaw/voice-call
  • Zalo Personal — @openclaw/zalouser
  • Matrix — @openclaw/matrix
  • Nostr — @openclaw/nostr
  • Zalo — @openclaw/zalo
  • Microsoft Teams — @openclaw/msteams
  • Google Antigravity OAuth (авторизация провайдера) — встроен как google-antigravity-auth (по умолчанию отключен)
  • Gemini CLI OAuth (авторизация провайдера) — встроен как google-gemini-cli-auth (по умолчанию отключен)
  • Qwen OAuth (авторизация провайдера) — встроен как qwen-portal-auth (по умолчанию отключен)
  • Copilot Proxy (авторизация провайдера) — локальный мост VS Code Copilot Proxy; отличается от встроенного github-copilot device login (встроен, по умолчанию отключен)

Плагины OpenClaw — это TypeScript модули, загружаемые во время выполнения через jiti. Валидация конфигурации не выполняет код плагина; она использует манифест плагина и JSON Schema. См. Манифест плагина.

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

  • Gateway RPC методы
  • Gateway HTTP обработчики
  • Инструменты агента
  • CLI команды
  • Фоновые сервисы
  • Дополнительную валидацию конфигурации
  • Навыки (указывая директории skills в манифесте плагина)
  • Автоматические команды-ответы (выполняются без вызова ИИ-агента)

Плагины работают в процессе с Gateway, поэтому обращайтесь с ними как с доверенным кодом. Руководство по созданию инструментов: Инструменты агента плагинов.

Вспомогательные функции времени выполнения

Плагины могут получать доступ к выбранным вспомогательным функциям ядра через api.runtime. Для телефонии TTS:

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Привет от OpenClaw",
  cfg: api.config,
});

Примечания:

  • Использует конфигурацию ядра messages.tts (OpenAI или ElevenLabs).
  • Возвращает PCM аудио буфер + частоту дискретизации. Плагины должны пересэмплировать/кодировать для провайдеров.
  • Edge TTS не поддерживается для телефонии.

Обнаружение и приоритет

OpenClaw сканирует в порядке:

  1. Пути конфигурации
  • plugins.load.paths (файл или директория)
  1. Расширения рабочего пространства
  • <workspace>/.openclaw/extensions/*.ts
  • <workspace>/.openclaw/extensions/*/index.ts
  1. Глобальные расширения
  • ~/.openclaw/extensions/*.ts
  • ~/.openclaw/extensions/*/index.ts
  1. Встроенные расширения (поставляются с OpenClaw, по умолчанию отключены)
  • <openclaw>/extensions/*

Встроенные плагины должны быть явно включены через plugins.entries.<id>.enabled или openclaw plugins enable <id>. Установленные плагины включены по умолчанию, но могут быть отключены таким же образом.

Каждый плагин должен включать файл openclaw.plugin.json в своем корне. Если путь указывает на файл, корнем плагина является директория файла, и она должна содержать манифест.

Если несколько плагинов разрешаются в один и тот же id, побеждает первое совпадение в порядке выше, а копии с более низким приоритетом игнорируются.

Пакеты пакетов

Директория плагина может включать package.json с openclaw.extensions:

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

Каждая запись становится плагином. Если пакет перечисляет несколько расширений, id плагина становится name/<fileBase>.

Если ваш плагин импортирует npm зависимости, установите их в этой директории, чтобы был доступен node_modules (npm install / pnpm install).

Метаданные каталога каналов

Плагины каналов могут рекламировать метаданные настройки через openclaw.channel и подсказки по установке через openclaw.install. Это сохраняет данные каталога ядра без данных.

Пример:

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (самостоятельный хостинг)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Самостоятельный чат через Nextcloud Talk webhook боты.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

OpenClaw также может объединять внешние каталоги каналов (например, экспорт реестра MPM). Поместите JSON файл в один из:

  • ~/.openclaw/mpm/plugins.json
  • ~/.openclaw/mpm/catalog.json
  • ~/.openclaw/plugins/catalog.json

Или укажите OPENCLAW_PLUGIN_CATALOG_PATHS (или OPENCLAW_MPM_CATALOG_PATHS) на один или несколько JSON файлов (разделитель запятая/точка с запятой/PATH). Каждый файл должен содержать \{ "entries": [ \{ "name": "@scope/pkg", "openclaw": \{ "channel": \{...\}, "install": \{...\} \} \} ] \}.

ID плагинов

ID плагинов по умолчанию:

  • Пакеты пакетов: name из package.json
  • Отдельный файл: базовое имя файла (~/.../voice-call.ts → voice-call)

Если плагин экспортирует id, OpenClaw использует его, но предупреждает, когда он не соответствует настроенному id.

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

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } }
    }
  }
}

Поля:

  • enabled: главный переключатель (по умолчанию: true)
  • allow: белый список (опционально)
  • deny: черный список (опционально; deny побеждает)
  • load.paths: дополнительные файлы/директории плагинов
  • entries.<id>: переключатели и конфигурация для каждого плагина

Изменения конфигурации требуют перезапуска gateway.

Правила валидации (строгие):

  • Неизвестные ID плагинов в entries, allow, deny или slots являются ошибками.
  • Неизвестные ключи channels.<id> являются ошибками, если манифест плагина не объявляет id канала.
  • Конфигурация плагина валидируется с использованием JSON Schema, встроенной в openclaw.plugin.json (configSchema).
  • Если плагин отключен, его конфигурация сохраняется и выдается предупреждение.

Слоты плагинов (эксклюзивные категории)

Некоторые категории плагинов эксклюзивны (только один активен за раз). Используйте plugins.slots для выбора, какой плагин владеет слотом:

{
  plugins: {
    slots: {
      memory: "memory-core" // или "none" для отключения плагинов памяти
    }
  }
}

Если несколько плагинов объявляют kind: "memory", загружается только выбранный. Другие отключаются с диагностикой.

Control UI (схема + метки)

Control UI использует config.schema (JSON Schema + uiHints) для отрисовки лучших форм.

OpenClaw дополняет uiHints во время выполнения на основе обнаруженных плагинов:

  • Добавляет метки для каждого плагина для plugins.entries.<id> / .enabled / .config
  • Объединяет опциональные подсказки полей конфигурации, предоставленные плагином, под: plugins.entries.<id>.config.<field>

Если вы хотите, чтобы поля конфигурации вашего плагина показывали хорошие метки/заполнители (и помечали секреты как чувствительные), предоставьте uiHints вместе с вашей JSON Schema в манифесте плагина.

Пример:

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API ключ", "sensitive": true },
    "region": { "label": "Регион", "placeholder": "us-east-1" }
  }
}

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # копирование локального файла/директории в ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # относительный путь ок
openclaw plugins install ./plugin.tgz           # установка из локального tarball
openclaw plugins install ./plugin.zip           # установка из локального zip
openclaw plugins install -l ./extensions/voice-call # ссылка (без копирования) для разработки
openclaw plugins install @openclaw/voice-call # установка из npm
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

plugins update работает только для npm установок, отслеживаемых в plugins.installs.

Плагины также могут регистрировать свои собственные команды верхнего уровня (пример: openclaw voicecall).

API плагина (обзор)

Плагины экспортируют либо:

  • Функцию: (api) => \{ ... \}
  • Объект: \{ id, name, configSchema, register(api) \{ ... \} \}

Хуки плагинов

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

Пример

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

Примечания:

  • Директории хуков следуют обычной структуре хуков (HOOK.md + handler.ts).
  • Правила применимости хуков все еще применяются (требования OS/bins/env/config).
  • Хуки, управляемые плагинами, отображаются в openclaw hooks list с plugin:<id>.
  • Вы не можете включить/отключить хуки, управляемые плагинами, через openclaw hooks; вместо этого включите/отключите плагин.

Плагины провайдеров (авторизация моделей)

Плагины могут регистрировать авторизацию провайдера модели, чтобы пользователи могли запускать OAuth или настройку API-ключа внутри OpenClaw (не нужны внешние скрипты).

Зарегистрируйте провайдера через api.registerProvider(...). Каждый провайдер предоставляет один или несколько методов авторизации (OAuth, API-ключ, код устройства и т.д.). Эти методы питают:

  • openclaw models auth login --provider <id> [--method <id>]

Пример:

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Запуск OAuth потока и возврат профилей авторизации.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

Примечания:

  • run получает ProviderAuthContext с prompter, runtime, openUrl и oauth.createVpsAwareHandlers помощниками.
  • Возвращайте configPatch, когда вам нужно добавить модели по умолчанию или конфигурацию провайдера.
  • Возвращайте defaultModel, чтобы --set-default мог обновлять настройки агента по умолчанию.

Регистрация канала обмена сообщениями

Плагины могут регистрировать плагины каналов, которые ведут себя как встроенные каналы (WhatsApp, Telegram и т.д.). Конфигурация канала находится под channels.<id> и валидируется кодом вашего плагина канала.

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "демо-плагин канала.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      (cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? { accountId }),
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

Примечания:

  • Размещайте конфигурацию под channels.<id> (не plugins.entries).
  • meta.label используется для меток в списках CLI/UI.
  • meta.aliases добавляет альтернативные id для нормализации и входов CLI.
  • meta.preferOver перечисляет id каналов, которые нужно пропустить при автоматическом включении, когда настроены оба.
  • meta.detailLabel и meta.systemImage позволяют UI показывать более богатые метки/иконки каналов.

(продолжение опущено для краткости - полный файл с остальными разделами)

← Назад к документации