Плагіни - OpenClaw

Plugins розширюють OpenClaw каналами, постачальниками моделей, обв’язками агентів, інструментами, Skills, мовленням, транскрибуванням у реальному часі, голосом, розумінням медіа, генерацією, отриманням даних з вебу, вебпошуком та іншими можливостями середовища виконання. Використовуйте цю сторінку, коли потрібно встановити Plugin, перезапустити Gateway, перевірити, що середовище виконання його завантажило, і розібрати типові збої налаштування. Приклади лише з командами див. у Керування plugins. Повний згенерований перелік вбудованих, офіційних зовнішніх і доступних лише з вихідного коду plugins див. у Інвентар Plugin.

Вимоги

Перед встановленням Plugin переконайтеся, що у вас є:

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

Швидкий старт

Find the plugin

Шукайте публічні пакети plugins у ClawHub:

openclaw plugins search "calendar"

ClawHub є основною поверхнею виявлення для спільнотних plugins. Під час переходу запуску звичайні специфікації пакетів без префікса все ще встановлюються з npm, якщо вони не збігаються з офіційним id Plugin. Сирі специфікації пакетів @openclaw/*, які збігаються з вбудованими plugins, використовують вбудовану копію з поточного білда OpenClaw. Використовуйте явний префікс, коли вам потрібне конкретне джерело.

Install the plugin

# From ClawHub.
openclaw plugins install clawhub:<package>

# From npm.
openclaw plugins install npm:<package>

# From git.
openclaw plugins install git:github.com/<owner>/<repo>@<ref>

# From a local development checkout.
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin

Ставтеся до встановлення plugins як до запуску коду. Надавайте перевагу зафіксованим версіям, коли потрібні відтворювані production-інсталяції.

Configure and enable it

Налаштуйте специфічні для Plugin параметри в plugins.entries.<id>.config. Увімкніть Plugin, якщо він ще не ввімкнений:

openclaw plugins enable <plugin-id>

Якщо ваша конфігурація використовує обмежувальний список plugins.allow, id встановленого Plugin має бути присутній там, перш ніж Plugin зможе завантажитися. openclaw plugins install додає встановлений id до наявного списку plugins.allow і видаляє той самий id з plugins.deny, щоб явна інсталяція могла завантажитися після перезапуску.

Let the Gateway reload

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

openclaw gateway restart

Операції ввімкнення та вимкнення оновлюють конфігурацію й оновлюють холодний реєстр. Інспекція середовища виконання все ще є найзрозумілішим шляхом перевірки для активних поверхонь середовища виконання.

Verify runtime registration

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

Використовуйте --runtime, коли потрібно довести зареєстровані інструменти, hooks, сервіси, методи Gateway або CLI-команди, що належать Plugin. Звичайний inspect є холодною перевіркою маніфесту й реєстру.

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

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

Джерело	Коли використовувати	Приклад
ClawHub	Потрібні нативне для OpenClaw виявлення, сканування, метадані версій і підказки встановлення	`openclaw plugins install clawhub:<package>`
npm	Потрібні прямий реєстр npm або робочі процеси dist-tag	`openclaw plugins install npm:<package>`
git	Потрібні гілка, тег або commit з репозиторію	`openclaw plugins install git:github.com/<owner>/<repo>@<ref>`
локальний шлях	Ви розробляєте або тестуєте Plugin на тій самій машині	`openclaw plugins install --link ./my-plugin`
marketplace	Ви встановлюєте сумісний із Claude Plugin marketplace	`openclaw plugins install <plugin> --marketplace <source>`

Специфікації пакетів без префікса мають спеціальну поведінку сумісності. Якщо просте ім’я збігається з id вбудованого Plugin, OpenClaw використовує це вбудоване джерело. Якщо воно збігається з id офіційного зовнішнього Plugin, OpenClaw використовує офіційний каталог пакетів. Інші звичайні специфікації пакетів без префікса встановлюються через npm під час переходу запуску. Сирі специфікації пакетів @openclaw/*, які збігаються з вбудованими plugins, також розв’язуються у вбудовану копію перед fallback до npm. Використовуйте npm:@openclaw/<plugin>@<version>, коли навмисно хочете зовнішній пакет npm замість вбудованої копії, що належить образу. Використовуйте clawhub:, npm:, git: або npm-pack:, коли потрібен детермінований вибір джерела. Повний контракт команди див. у openclaw plugins. Для інсталяцій npm специфікації пакетів без фіксації версії та @latest вибирають найновіший стабільний пакет, який заявляє сумісність із цим білдом OpenClaw. Якщо поточний latest-реліз npm оголошує новіший openclaw.compat.pluginApi або openclaw.install.minHostVersion, OpenClaw сканує старіші стабільні версії пакетів і встановлює найновішу придатну. Точні версії та явні теги каналів, наприклад @beta, залишаються прив’язаними до вибраного пакета й завершуються помилкою, якщо несумісні.

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

Налаштуйте security.installPolicy, щоб запускати довірену локальну команду політики перед тим, як продовжиться встановлення або оновлення Plugin. Політика отримує метадані разом із проміжним шляхом джерела і може дозволити або заблокувати встановлення. Вона охоплює шляхи встановлення/оновлення Plugin через CLI і через Gateway. Hooks Plugin before_install виконуються пізніше лише в процесах OpenClaw, де завантажені hooks Plugin, тому використовуйте security.installPolicy для рішень щодо встановлення, які належать оператору. Застарілий прапорець --dangerously-force-unsafe-install приймається для сумісності, але не обходить політику встановлення або вбудований denylist залежностей Plugin в OpenClaw. Спільну exec-схему security.installPolicy, яку використовують і skills, і plugins, див. у Конфігурація Skills.

Налаштуйте політику Plugin

Спільна форма конфігурації Plugin:

{
  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 вимикає всі plugins і пропускає роботу з виявлення/завантаження Plugin. Застарілі посилання на plugins інертні, поки це активне; повторно ввімкніть plugins перед запуском очищення doctor, якщо хочете видалити застарілі ids.
plugins.deny має пріоритет над allow і ввімкненням окремого Plugin.
plugins.allow є ексклюзивним allowlist. Інструменти, що належать Plugin, поза allowlist залишаються недоступними, навіть коли tools.allow містить "*".
plugins.entries.<id>.enabled: false вимикає один Plugin, зберігаючи його конфігурацію.
plugins.load.paths додає явні локальні файли або каталоги Plugin. Керовані локальні шляхи plugins install мають бути каталогами або архівами Plugin; використовуйте plugins.load.paths для автономних файлів Plugin.
Plugins з походженням із workspace вимкнені за замовчуванням; явно ввімкніть їх або додайте до allowlist перед використанням локального коду workspace.
Вбудовані plugins дотримуються своїх вбудованих метаданих default-on/default-off, якщо конфігурація явно їх не перевизначає.
plugins.slots.<slot> вибирає один Plugin для ексклюзивних категорій, таких як memory та рушії context. Вибір slot примусово вмикає вибраний Plugin для цього slot, зараховуючись як явна активація; він може завантажитися, навіть коли інакше був би opt-in. plugins.deny і plugins.entries.<id>.enabled: false все одно блокують його.
Вбудовані opt-in plugins можуть auto-activate, коли конфігурація називає одну з їхніх власних поверхонь, наприклад provider/model ref, конфігурацію channel, CLI backend або runtime обв’язки agent.
Маршрутизація Codex сімейства OpenAI тримає межі provider і runtime Plugin окремими: legacy refs моделей Codex є legacy-конфігурацією, яку виправляє doctor, тоді як вбудований Plugin codex володіє runtime app-server Codex для канонічних refs agent openai/*, явного agentRuntime.id: "codex" і legacy refs codex/*.

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

Зрозумійте формати Plugin

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

Формат	Як завантажується	Коли використовувати
Нативний Plugin OpenClaw	`openclaw.plugin.json` плюс runtime-модуль, завантажений у процесі	Ви встановлюєте або створюєте runtime-можливості, специфічні для OpenClaw
Сумісний bundle	Макет Plugin Codex, Claude або Cursor, зіставлений з інвентарем Plugin OpenClaw	Ви повторно використовуєте сумісні skills, commands, hooks або метадані bundle

Обидва формати відображаються в openclaw plugins list, openclaw plugins inspect, openclaw plugins enable і openclaw plugins disable. Межу сумісності bundle див. у Bundles Plugin, а нативне авторство Plugin див. у Створення plugins.

Hooks Plugin

Plugins можуть реєструвати hooks під час виконання, але є два різні API з різними завданнями.

Використовуйте типізовані hooks через api.on(...) для hooks життєвого циклу runtime. Це бажана поверхня для middleware, policy, переписування повідомлень, формування prompt і керування tools.
Використовуйте api.registerHook(...) лише тоді, коли хочете брати участь у внутрішній системі hooks, описаній у Hooks. Це переважно для грубих побічних ефектів command/lifecycle і сумісності з наявною автоматизацією в стилі HOOK.

Швидке правило:

Якщо handler потребує пріоритету, семантики merge або поведінки block/cancel, використовуйте типізовані hooks Plugin.
Якщо handler просто реагує на command:new, command:reset, message:sent або подібні грубі події, api.registerHook(...) підходить.

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

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

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

openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart

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

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

Ознака	Перевірка	Виправлення
Plugin відображається в `plugins list`, але runtime-хуки не виконуються	Використайте `openclaw plugins inspect <id> --runtime --json` і підтвердьте активний Gateway через `gateway status --deep --require-rpc`	Перезапустіть живий Gateway після встановлення, оновлення, зміни конфігурації або вихідного коду
З’являються діагностичні повідомлення про дублювання власника каналу або інструмента	Запустіть `openclaw plugins list --enabled --verbose`, перевірте кожен підозрюваний Plugin із `--runtime --json` і порівняйте власників каналів/інструментів	Вимкніть одного власника, видаліть застарілі встановлення або використайте `preferOver` у маніфесті для навмисної заміни
Конфігурація повідомляє, що Plugin відсутній	Перевірте інвентар Plugin, щоб з’ясувати, чи він вбудований, офіційний зовнішній або доступний лише з вихідного коду	Установіть зовнішній пакет, увімкніть вбудований Plugin або видаліть застарілу конфігурацію
Конфігурація недійсна під час встановлення	Прочитайте повідомлення валідації та запустіть `openclaw doctor --fix`, коли воно вказує на застарілий стан Plugin	Doctor може помістити недійсну конфігурацію Plugin у карантин, вимкнувши запис і видаливши недійсне корисне навантаження
Шлях Plugin заблоковано через підозріле володіння або дозволи	Перегляньте діагностику перед помилкою конфігурації	Виправте володіння/дозволи файлової системи, потім запустіть `openclaw plugins registry --refresh`
`OPENCLAW_NIX_MODE=1` блокує команди життєвого циклу	Підтвердьте, що встановлення керується Nix	Змініть вибір Plugin у джерелі Nix замість використання команд зміни Plugin
Імпорт залежності не вдається під час виконання	Перевірте, чи Plugin було встановлено через npm/git/ClawHub, чи завантажено з локального шляху	Запустіть `openclaw plugins update <id>`, перевстановіть джерело або самостійно встановіть залежності локального Plugin

Коли застаріла конфігурація Plugin усе ще вказує на Plugin каналу, який більше не виявляється, запуск Gateway пропускає цей канал, підтримуваний Plugin, замість блокування всіх інших каналів. Запустіть openclaw doctor --fix, щоб видалити застарілі записи Plugin і каналів. Невідомі ключі каналів без доказів застарілого Plugin усе одно не проходять валідацію, щоб друкарські помилки залишалися помітними. Для навмисної заміни каналу бажаний Plugin має оголосити channelConfigs.<channel-id>.preferOver із застарілим або нижчепріоритетним ідентифікатором Plugin. Якщо обидва Plugin явно ввімкнені, OpenClaw зберігає цей запит і повідомляє діагностику дублювання каналів або інструментів замість мовчазного вибору одного власника. Якщо встановлений пакет повідомляє, що він requires compiled runtime output for TypeScript entry ..., пакет було опубліковано без JavaScript-файлів, потрібних OpenClaw під час виконання. Оновіть або перевстановіть після того, як видавець випустить скомпільований JavaScript, або вимкніть/видаліть Plugin до того часу.

Заблоковане володіння шляхом Plugin

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

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

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

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

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

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

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

openclaw config set logging.level trace
openclaw logs --follow

Шукайте:

[trace:plugin-tools] factory timings ...

Зведення перелічує загальний час фабрик і найповільніші фабрики інструментів Plugin, зокрема ідентифікатор Plugin, оголошені назви інструментів, форму результату та чи є інструмент необов’язковим. Повільні рядки підвищуються до попереджень, коли одна фабрика триває щонайменше 1 с або загальна підготовка фабрик інструментів Plugin триває щонайменше 5 с. OpenClaw кешує успішні результати фабрик інструментів Plugin для повторних розв’язань із тим самим ефективним контекстом запиту. Ключ кешу включає ефективну runtime-конфігурацію, робочий простір, ідентифікатори агента/сеансу, політику sandbox, налаштування браузера, контекст доставки, ідентичність запитувача та стан володіння, тому фабрики, що залежать від цих довірених полів, запускаються повторно, коли контекст змінюється. Якщо часи залишаються високими, Plugin може виконувати дорогу роботу до повернення визначень інструментів. Якщо один Plugin домінує за часом, перевірте його runtime-реєстрації:

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

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

Пов’язане

Керування Plugin - приклади команд для list, install, update, uninstall і publish
openclaw plugins - повний довідник CLI
Інвентар Plugin - згенерований список вбудованих і зовнішніх Plugin
Довідник Plugin - згенеровані довідкові сторінки для кожного Plugin
Спільнотні Plugin - виявлення ClawHub і політика PR для документації
Розв’язання залежностей Plugin - корені встановлення, записи реєстру та межі runtime
Створення Plugin - посібник з авторства нативних Plugin
Огляд Plugin SDK - runtime-реєстрація, хуки та поля API
Маніфест Plugin - метадані маніфесту та пакета

​Вимоги

​Швидкий старт

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

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

​Політика інсталяції оператора

​Налаштуйте політику Plugin

​Зрозумійте формати Plugin

​Hooks Plugin

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

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

​Заблоковане володіння шляхом Plugin

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

​Пов’язане