Плагіни

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

Скористайтеся цією сторінкою, щоб установити плагін, перезапустити 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] factory timings ...

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

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

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

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

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

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

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

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