Плагіни

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

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

Вимоги

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

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

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

openclaw plugins search "calendar"

# 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-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

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

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

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

Специфікації пакетів без префікса мають спеціальну поведінку сумісності. Якщо просте ім'я збігається з 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:

Обидва формати відображаються в 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-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

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

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

Коли застаріла конфігурація 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 traceopenclaw 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 - метадані маніфесту та пакета