Плагіни

Plugins розширюють OpenClaw, додаючи канали, постачальників моделей, середовища виконання агентів, інструменти, навички, мовлення, транскрибування в реальному часі, голосові функції, розуміння медіа, генерування, отримання даних із вебу, вебпошук та інші можливості середовища виконання.

Скористайтеся цією сторінкою, щоб установити Plugin, перезапустити Gateway, перевірити, чи середовище виконання завантажило його, і усунути поширені помилки налаштування. Приклади лише з командами див. у розділі Керування плагінами. Згенерований перелік вбудованих, офіційних зовнішніх і доступних лише у вихідному коді плагінів див. у розділі Перелік плагінів.

Вимоги

• робоча копія або інсталяція OpenClaw із доступним CLI openclaw
• доступ до мережі для вибраного джерела (ClawHub, npm або git-хост)
• усі облікові дані, ключі конфігурації або інструменти ОС, потрібні конкретному плагіну й зазначені в документації з його налаштування
• дозвіл для Gateway, який обслуговує ваші канали, на перезавантаження або перезапуск

Швидкий початок

openclaw plugins search "calendar"

# Із ClawHub.openclaw plugins install clawhub:<package> # Із npm.openclaw plugins install npm:<package> # Із git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # Із локальної робочої копії для розробки.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

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

Виберіть джерело встановлення

Специфікації пакетів без уточнень мають особливу поведінку сумісності: ім’я без уточнень, яке збігається з ідентифікатором вбудованого плагіна, використовує це вбудоване джерело; ім’я без уточнень, яке збігається з ідентифікатором офіційного зовнішнього плагіна, використовує офіційний каталог пакетів; будь-яка інша специфікація без уточнень під час переходу на запуск установлюється через npm. Необроблені специфікації @openclaw/*, які збігаються з вбудованими плагінами, також перед резервним переходом до npm зіставляються з вбудованою копією. Використовуйте npm:@openclaw/<plugin>@<version>, щоб навмисно встановити зовнішній пакет npm замість вбудованої копії. Використовуйте clawhub:, npm:, git: або npm-pack: для детермінованого вибору джерела. Повний контракт команди див. у розділі openclaw plugins.

Для встановлень із npm незакріплені специфікації та @latest вибирають найновіший стабільний пакет, який заявляє сумісність із цією збіркою OpenClaw. Якщо поточний найновіший випуск npm оголошує новіший openclaw.compat.pluginApi або openclaw.install.minHostVersion, ніж підтримує ця збірка, OpenClaw сканує старіші стабільні версії та встановлює найновішу відповідну. Точні версії та явні теги каналів, як-от @beta, залишаються закріпленими за вибраним пакетом і завершуються помилкою в разі несумісності.

Політика встановлення оператора

Налаштуйте security.installPolicy, щоб перед продовженням встановлення або оновлення плагіна запускалася довірена локальна команда політики. Політика отримує метадані разом зі шляхом до підготовленого джерела й може дозволити або заблокувати встановлення. Вона охоплює як CLI, так і шляхи встановлення та оновлення через Gateway. Хуки плагіна before_install запускаються пізніше й лише в процесах OpenClaw, де завантажено хуки плагінів, тому для рішень щодо встановлення, якими керує оператор, натомість використовуйте security.installPolicy. Застарілий прапорець --dangerously-force-unsafe-install приймається для сумісності, але нічого не робить: він не обходить політику встановлення чи вбудований у OpenClaw список заборонених залежностей плагінів.

Спільну схему виконання security.installPolicy, яку використовують і Skills, і плагіни, див. у розділі Налаштування Skills.

Налаштуйте політику плагінів

Загальна структура конфігурації плагінів:

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

Основні правила політики:

• plugins.enabled: false вимикає всі плагіни та пропускає роботу з виявлення й завантаження. Застарілі посилання на плагіни залишаються неактивними, доки цей параметр діє; знову ввімкніть плагіни перед очищенням за допомогою doctor, якщо потрібно видалити застарілі ідентифікатори.
• plugins.deny має пріоритет над списком дозволів і ввімкненням окремого плагіна.
• plugins.allow — це винятковий список дозволів. Інструменти, що належать плагінам поза списком дозволів, залишаються недоступними, навіть коли tools.allow містить "*".
• plugins.entries.<id>.enabled: false вимикає один плагін, зберігаючи його конфігурацію.
• plugins.load.paths додає явні локальні файли або каталоги плагінів. Керовані локальні шляхи plugins install мають бути каталогами або архівами плагінів; для окремих файлів плагінів використовуйте plugins.load.paths.
• Плагіни з робочого простору за замовчуванням вимкнені; явно ввімкніть або додайте їх до списку дозволів перед використанням локального коду робочого простору.
• Вбудовані плагіни дотримуються вбудованих метаданих про ввімкнення або вимкнення за замовчуванням, якщо конфігурація явно не перевизначає їх.
• plugins.slots.<slot> (memory або contextEngine) вибирає один плагін для виняткової категорії. Вибір слота вважається явною активацією та примусово вмикає вибраний плагін для цього слота, навіть якщо інакше він потребував би явного ввімкнення. plugins.deny і plugins.entries.<id>.enabled: false усе одно блокують його.
• Вбудовані плагіни з явним ввімкненням можуть активуватися автоматично, коли конфігурація називає одну з належних їм поверхонь, як-от посилання на постачальника або модель, конфігурацію каналу, серверну частину CLI чи середовище виконання каркаса агента.
• Маршрутизація Codex родини OpenAI зберігає межі плагінів постачальника й середовища виконання окремими: застарілі посилання на моделі Codex є застарілою конфігурацією, яку виправляє doctor, тоді як вбудований плагін codex керує середовищем виконання сервера застосунку Codex для канонічних посилань агентів openai/*, явного agentRuntime.id: "codex" і застарілих посилань codex/*.

Коли plugins.allow не задано, а невбудовані плагіни автоматично виявляються в робочому просторі або глобальних кореневих каталогах плагінів, під час запуску журналюється plugins.allow is empty; discovered non-bundled plugins may auto-load: ... з ідентифікаторами виявлених плагінів і, для коротких списків, мінімальним фрагментом plugins.allow. Запустіть openclaw plugins list --enabled --verbose або openclaw plugins inspect <id> для вказаного ідентифікатора плагіна, перш ніж копіювати довірені плагіни до openclaw.json. Таке саме закріплення довіри застосовується, коли діагностика повідомляє, що плагін завантажено without install/load-path provenance: перевірте цей ідентифікатор плагіна, а потім закріпіть його в plugins.allow або повторно встановіть із довіреного джерела, щоб OpenClaw записав походження встановлення.

Запустіть openclaw doctor або openclaw doctor --fix, коли перевірка конфігурації повідомляє про застарілі ідентифікатори плагінів, невідповідності списку дозволів та інструментів або застарілі шляхи вбудованих плагінів.

Формати плагінів

OpenClaw розпізнає два формати плагінів:

Обидва формати відображаються в openclaw plugins list, openclaw plugins inspect, openclaw plugins enable і openclaw plugins disable. Межі сумісності пакетів див. у розділі Пакети плагінів, а створення нативних плагінів — у розділі Створення плагінів.

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

Плагіни можуть реєструвати хуки під час виконання через два різні API:

• api.on(...) — типізовані хуки для подій життєвого циклу середовища виконання. Це рекомендована поверхня для проміжного ПЗ, політик, переписування повідомлень, формування запитів та керування інструментами.
• api.registerHook(...) — для внутрішньої системи хуків, описаної в розділі Хуки. Вона призначена переважно для грубих побічних ефектів команд і життєвого циклу та сумісності з наявною автоматизацією у стилі HOOK.

Коротке правило: якщо обробнику потрібні пріоритет, семантика об’єднання або поведінка блокування чи скасування, використовуйте типізовані хуки. Якщо він лише реагує на command:new, command:reset, message:sent або подібні грубі події, api.registerHook цілком підходить.

Внутрішні хуки, якими керують плагіни, відображаються в openclaw hooks list з plugin:<id>. Їх неможливо ввімкнути або вимкнути через openclaw hooks; натомість увімкніть або вимкніть плагін.

Перевірте активний Gateway

openclaw plugins list і звичайна команда openclaw plugins inspect зчитують холодний стан конфігурації, маніфесту та реєстру. Вони не підтверджують, що вже запущений Gateway імпортував той самий код плагіна.

Якщо плагін видається встановленим, але трафік активних чатів його не використовує:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Керовані Gateway автоматично перезапускаються після встановлення, оновлення та видалення плагінів, якщо ці зміни модифікують вихідний код плагіна. Для встановлень на VPS або в контейнері переконайтеся, що будь-який ручний перезапуск спрямовано на фактичний дочірній процес openclaw gateway run, який обслуговує ваші канали, а не лише на оболонку чи супервізор.

Усунення несправностей

Якщо застаріла конфігурація плагіна все ще містить назву плагіна каналу, який більше неможливо виявити, перевірка конфігурації понижує помилку цього ключа каналу до попередження замість критичної помилки, тому під час запуску Gateway може й надалі обслуговувати всі інші канали. Запустіть openclaw doctor --fix, щоб видалити застарілі записи плагінів і каналів. Невідомі ключі каналів без ознак застарілого плагіна все одно не проходять перевірку, щоб друкарські помилки залишалися помітними.

Для навмисної заміни каналу бажаний плагін має оголосити channelConfigs.<channel-id>.preferOver з ідентифікатором застарілого плагіна або плагіна з нижчим пріоритетом. Якщо обидва плагіни явно ввімкнено, OpenClaw зберігає цей запит і повідомляє про дублювання власників каналів або інструментів, а не вибирає одного власника без попередження.

Якщо встановлений пакет повідомляє, що він requires compiled runtime output for TypeScript entry ..., пакет опубліковано без файлів JavaScript, необхідних OpenClaw під час виконання. Оновіть або повторно встановіть його після того, як видавець надасть скомпільований JavaScript, або до того часу вимкніть чи видаліть плагін.

Заблокований власник шляху до плагіна

Якщо діагностика повідомляє blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root), а потім перевірка видає plugin present but blocked, OpenClaw знайшов файли плагіна, що належать іншому користувачеві Unix, а не процесу, який їх завантажує. Залиште конфігурацію плагіна без змін; виправте власника файлової системи або запускайте OpenClaw від імені того самого користувача, якому належить каталог стану.

Для встановлень Docker офіційний образ працює від імені node (uid 1000), тому примонтовані з хоста каталоги конфігурації та робочого простору OpenClaw зазвичай мають належати uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Якщо ви навмисно запускаєте OpenClaw від імені root, натомість змініть власника кореневого каталогу керованих плагінів на root:

sudo chown -R root:root /path/to/openclaw-config/npm

Після виправлення власника повторно запустіть openclaw doctor --fix або openclaw plugins registry --refresh, щоб збережений реєстр плагінів відповідав виправленим файлам.

Повільне налаштування інструментів плагіна

Якщо під час підготовки інструментів виконання агента ніби призупиняється, увімкніть журналювання трасування та перевірте рядки тривалості роботи фабрик інструментів плагінів:

openclaw config set logging.level traceopenclaw logs --follow

Знайдіть:

[trace:plugin-tools] тривалість роботи фабрик ...

У зведенні наведено загальний час роботи фабрик і найповільніші фабрики інструментів плагінів, зокрема ідентифікатор плагіна, оголошені назви інструментів, форму результату й те, чи є інструмент необов’язковим. Повільні рядки підвищуються до рівня попереджень, якщо одна фабрика працює принаймні 1s або загальна підготовка фабрик інструментів плагінів триває принаймні 5s.

OpenClaw кешує успішні результати фабрик інструментів плагінів для повторних визначень з однаковим фактичним контекстом запиту. Ключ кешу містить фактичну конфігурацію середовища виконання, робочий простір та ідентифікатор агента, політику пісочниці, налаштування браузера, контекст доставки, ідентичність запитувача й стан власності, тому фабрики, що залежать від цих довірених полів, запускаються повторно, коли контекст змінюється. Якщо тривалість залишається високою, плагін може виконувати витратну роботу до повернення визначень своїх інструментів.

Якщо один плагін займає більшу частину часу, перевірте його реєстрації в середовищі виконання:

openclaw plugins inspect <plugin-id> --runtime --json

Потім оновіть, повторно встановіть або вимкніть цей плагін. Автори плагінів мають перенести витратне завантаження залежностей у шлях виконання інструмента, а не виконувати його всередині фабрики інструментів.

Докладніше про кореневі каталоги залежностей, перевірку метаданих пакетів, записи реєстру, поведінку перезавантаження під час запуску й очищення застарілих даних див. у розділі Визначення залежностей плагінів.

Пов’язані матеріали

• Керування плагінами - приклади команд для перегляду списку, встановлення, оновлення, видалення й публікації
• openclaw plugins - повний довідник CLI
• Перелік плагінів - згенерований список вбудованих і зовнішніх плагінів
• Довідник плагінів - згенеровані довідкові сторінки для кожного плагіна
• Плагіни спільноти - правила пошуку в ClawHub і PR для документації
• Визначення залежностей плагінів - кореневі каталоги встановлення, записи реєстру та межі середовища виконання
• Створення плагінів - посібник зі створення нативних плагінів
• Огляд SDK плагінів - реєстрація в середовищі виконання, обробники та поля API
• Маніфест плагіна - маніфест і метадані пакета