Керуйте Plugin для Gateway, пакетами хуків і сумісними бандлами.Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Система Plugin
Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей Plugin.
Керування Plugin
Короткі приклади для встановлення, перегляду списку, оновлення, видалення та публікації.
Бандли Plugin
Модель сумісності бандлів.
Маніфест Plugin
Поля маніфесту та схема конфігурації.
Безпека
Посилення безпеки для встановлень Plugin.
Команди
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. Трасування записує таймінги фаз
у stderr і зберігає JSON-вивід придатним для парсингу. Див. Налагодження.
У режимі Nix (
OPENCLAW_NIX_MODE=1) мутуючі операції життєвого циклу Plugin вимкнено. Використовуйте джерело Nix для цього встановлення замість plugins install, plugins update, plugins uninstall, plugins enable або plugins disable; для nix-openclaw використовуйте agent-first Швидкий старт.Вбудовані Plugin постачаються з OpenClaw. Деякі увімкнено за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний Plugin); інші потребують
plugins enable.Нативні Plugin OpenClaw мають постачати openclaw.plugin.json з вбудованою JSON Schema (configSchema, навіть якщо вона порожня). Сумісні бандли натомість використовують власні маніфести бандлів.plugins list показує Format: openclaw або Format: bundle. Докладний вивід списку/інформації також показує підтип бандла (codex, claude або cursor) і виявлені можливості бандла.Установлення
plugins search запитує ClawHub щодо доступних для встановлення пакетів Plugin і виводить
готові до встановлення назви пакетів. Пошук охоплює пакети code-plugin і bundle-plugin,
а не skills. Використовуйте openclaw skills search для ClawHub skills.
ClawHub є основною поверхнею розповсюдження та виявлення для більшості Plugin. Npm
залишається підтримуваним резервним варіантом і шляхом прямого встановлення. Пакети Plugin,
що належать OpenClaw і мають формат
@openclaw/*, знову публікуються в npm; див. поточний список
на npmjs.com/org/openclaw або
інвентар Plugin. Стабільні встановлення використовують latest.
Встановлення та оновлення з бета-каналу надають перевагу npm dist-tag beta, коли цей тег
доступний, а потім повертаються до latest.Config includes і відновлення недійсної конфігурації
Config includes і відновлення недійсної конфігурації
Якщо ваш розділ
plugins підтримується однофайловим $include, plugins install/update/enable/disable/uninstall записують зміни в цей включений файл і залишають openclaw.json без змін. Кореневі includes, масиви include та includes із сусідніми перевизначеннями завершуються закрито замість розгортання. Див. Config includes щодо підтримуваних форм.Якщо під час встановлення конфігурація недійсна, plugins install зазвичай завершується закрито й повідомляє, що спершу потрібно запустити openclaw doctor --fix. Під час запуску Gateway і гарячого перезавантаження недійсна конфігурація Plugin завершується закрито, як і будь-яка інша недійсна конфігурація; openclaw doctor --fix може помістити недійсний запис Plugin у карантин. Єдиний задокументований виняток під час встановлення — вузький шлях відновлення вбудованого Plugin для Plugin, які явно вмикають openclaw.install.allowInvalidConfigRecovery.--force і перевстановлення проти оновлення
--force і перевстановлення проти оновлення
--force повторно використовує наявну ціль встановлення та перезаписує вже встановлений Plugin або пакет хуків на місці. Використовуйте його, коли ви навмисно перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm Plugin віддавайте перевагу openclaw plugins update <id-or-npm-spec>.Якщо ви запускаєте plugins install для id Plugin, який уже встановлено, OpenClaw зупиняється й спрямовує вас до plugins update <id-or-npm-spec> для звичайного оновлення або до plugins install <package> --force, коли ви справді хочете перезаписати поточне встановлення з іншого джерела.Область дії --pin
Область дії --pin
--pin застосовується лише до встановлень npm. Він не підтримується з встановленнями git:; використовуйте явне посилання git, наприклад git:github.com/acme/plugin@v1.2.3, коли потрібне зафіксоване джерело. Він не підтримується з --marketplace, оскільки встановлення marketplace зберігають метадані джерела marketplace замість npm spec.--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install — це аварійна опція для хибнопозитивних спрацювань у вбудованому сканері небезпечного коду. Вона дозволяє продовжити встановлення, навіть коли вбудований сканер повідомляє про знахідки critical, але не обходить блокування політики хуків Plugin before_install і не обходить помилки сканування.Цей прапорець CLI застосовується до потоків встановлення/оновлення Plugin. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту dangerouslyForceUnsafeInstall, тоді як openclaw skills install залишається окремим потоком завантаження/встановлення Skills із ClawHub.Якщо Plugin, який ви опублікували в ClawHub, заблоковано скануванням реєстру, скористайтеся кроками видавця в ClawHub.Пакети хуків і npm specs
Пакети хуків і npm specs
plugins install також є поверхнею встановлення для пакетів хуків, які експонують openclaw.hooks у package.json. Використовуйте openclaw hooks для відфільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакетів.Npm specs є лише реєстровими (назва пакета + необов’язкова точна версія або dist-tag). Git/URL/file specs і діапазони semver відхиляються. Встановлення залежностей виконується локально для проєкту з --ignore-scripts для безпеки, навіть якщо ваша оболонка має глобальні налаштування npm install. Керовані npm-корені Plugin успадковують npm overrides рівня пакета OpenClaw, тому захисні фіксації хоста застосовуються і до піднятих залежностей Plugin.Використовуйте npm:<package>, коли хочете зробити npm-резолюцію явною. Голі package specs також встановлюються напряму з npm під час перехідного запуску.Голі specs і @latest залишаються на стабільній гілці. Версії виправлень OpenClaw із датою, як-от 2026.5.3-1, є стабільними випусками для цієї перевірки. Якщо npm резолвить будь-яку з них у prerelease, OpenClaw зупиняється й просить вас явно погодитися за допомогою prerelease-тега, як-от @beta/@rc, або точної prerelease-версії, як-от @1.2.3-beta.4.Якщо голий install spec збігається з офіційним id Plugin (наприклад, diffs), OpenClaw встановлює запис каталогу напряму. Щоб встановити npm-пакет із такою самою назвою, використовуйте явний scoped spec (наприклад, @scope/diffs).Git-репозиторії
Git-репозиторії
Використовуйте
git:<repo> для встановлення безпосередньо з git-репозиторію. Підтримувані форми включають URL-адреси клонування git:github.com/owner/repo, git:owner/repo, повні https://, ssh://, git://, file:// і git@host:owner/repo.git. Додайте @<ref> або #<ref>, щоб перед встановленням перейти на гілку, тег або коміт.Встановлення Git клонують у тимчасовий каталог, переходять на запитаний ref, якщо він наявний, а потім використовують звичайний інсталятор каталогу Plugin. Це означає, що перевірка маніфесту, сканування небезпечного коду, робота встановлення пакетним менеджером і записи встановлення поводяться як під час встановлень npm. Записані встановлення git містять URL/ref джерела плюс розв’язаний коміт, щоб openclaw plugins update міг пізніше повторно розв’язати джерело.Після встановлення з git використовуйте openclaw plugins inspect <id> --runtime --json, щоб перевірити реєстрації runtime, як-от методи gateway і команди CLI. Якщо Plugin зареєстрував корінь CLI через api.registerCli, виконайте цю команду напряму через кореневий CLI OpenClaw, наприклад openclaw demo-plugin ping.Архіви
Архіви
Підтримувані архіви:
.zip, .tgz, .tar.gz, .tar. Архіви нативних Plugin OpenClaw мають містити дійсний openclaw.plugin.json у корені розпакованого Plugin; архіви, що містять лише package.json, відхиляються до того, як OpenClaw запише записи встановлення.Використовуйте npm-pack:<path.tgz>, коли файл є tarball npm-pack і ви хочете
протестувати той самий керований шлях встановлення npm-root, який використовують реєстрові встановлення,
включно з перевіркою package-lock.json, скануванням піднятих залежностей і
записами встановлення npm. Звичайні шляхи архівів усе ще встановлюються як локальні архіви
під коренем plugin extensions.Встановлення з Claude marketplace також підтримуються.clawhub:<package>:
npm:, щоб зробити npm-only резолюцію явною:
.tgz, перевіряє заголовок дайджесту ClawHub і дайджест артефакту, а потім інсталює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack досі інсталюються через застарілий шлях перевірки архіву пакета. Записані інсталяції зберігають свої вихідні метадані ClawHub, тип артефакту, npm integrity, npm shasum, назву tarball і факти дайджесту ClawPack для подальших оновлень.
Неверсіоновані інсталяції ClawHub зберігають неверсіоновану записану специфікацію, щоб openclaw plugins update міг відстежувати новіші релізи ClawHub; явні селектори версії або тегу, як-от clawhub:pkg@1.2.3 і clawhub:pkg@beta, залишаються закріпленими за цим селектором.
Скорочення маркетплейсу
Використовуйте скороченняplugin@marketplace, коли назва маркетплейсу існує в локальному кеші реєстру Claude за адресою ~/.claude/plugins/known_marketplaces.json:
--marketplace, коли потрібно явно передати джерело маркетплейсу:
- Джерела маркетплейсу
- Правила віддаленого маркетплейсу
- назва відомого маркетплейсу Claude з
~/.claude/plugins/known_marketplaces.json - локальний корінь маркетплейсу або шлях до
marketplace.json - скорочення репозиторію GitHub, як-от
owner/repo - URL репозиторію GitHub, як-от
https://github.com/owner/repo - URL git
- нативні Plugin OpenClaw (
openclaw.plugin.json) - пакети, сумісні з Codex (
.codex-plugin/plugin.json) - пакети, сумісні з Claude (
.claude-plugin/plugin.jsonабо стандартний макет компонентів Claude) - пакети, сумісні з Cursor (
.cursor-plugin/plugin.json)
Сумісні пакети інсталюються у звичайний корінь Plugin і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються Skills пакета, командні Skills Claude, стандартні значення Claude
settings.json, стандартні значення Claude .lsp.json / оголошених у маніфесті lspServers, командні Skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в діагностиці/info, але ще не під’єднані до виконання під час роботи.Список
Показати лише ввімкнені Plugin.
Перемкнутися з табличного подання на рядки деталей для кожного Plugin з метаданими source/origin/version/activation.
Машиночитаний інвентар разом із діагностикою реєстру та станом інсталяції залежностей пакета.
plugins list спершу читає збережений локальний реєстр Plugin, із запасним варіантом, виведеним лише з маніфестів, коли реєстр відсутній або недійсний. Це корисно для перевірки, чи Plugin інстальовано, увімкнено та видно для планування холодного запуску, але це не live-зонд часу виконання вже запущеного процесу Gateway. Після зміни коду Plugin, стану ввімкнення, політики хуків або plugins.load.paths перезапустіть Gateway, що обслуговує канал, перш ніж очікувати виконання нового коду register(api) або хуків. Для віддалених/container-розгортань перевірте, що ви перезапускаєте фактичний дочірній процес openclaw gateway run, а не лише процес-обгортку.plugins list --json включає dependencyStatus кожного Plugin з package.json
dependencies і optionalDependencies. OpenClaw перевіряє, чи ці назви пакетів
наявні вздовж звичайного шляху пошуку Node node_modules для Plugin; він
не імпортує runtime-код Plugin, не запускає менеджер пакетів і не виправляє
відсутні залежності.plugins search — це віддалений пошук у каталозі ClawHub. Він не перевіряє локальний
стан, не змінює конфігурацію, не інсталює пакети й не завантажує runtime-код Plugin. Результати пошуку
містять назву пакета ClawHub, сімейство, канал, версію, підсумок і
підказку для інсталяції, як-от openclaw plugins install clawhub:<package>.
Для роботи з вбудованим Plugin усередині запакованого Docker-образу змонтуйте каталог
джерела Plugin поверх відповідного запакованого шляху джерела, наприклад
/app/extensions/synology-chat. OpenClaw виявить це змонтоване джерельне
накладання перед /app/dist/extensions/synology-chat; звичайний скопійований джерельний
каталог залишається неактивним, тож звичайні запаковані інсталяції все одно використовують скомпільований dist.
Для налагодження runtime-хуків:
openclaw plugins inspect <id> --runtime --jsonпоказує зареєстровані хуки та діагностику з проходу інспекції із завантаженим модулем. Runtime-інспекція ніколи не інсталює залежності; використовуйтеopenclaw doctor --fix, щоб очистити застарілий стан залежностей або відновити відсутні завантажувані Plugin, на які посилається конфігурація.openclaw gateway status --deep --require-rpcпідтверджує доступний Gateway, підказки щодо служби/процесу, шлях конфігурації та стан RPC.- Невбудовані хуки розмови (
llm_input,llm_output,before_model_resolve,before_agent_reply,before_agent_run,before_agent_finalize,agent_end) потребуютьplugins.entries.<id>.hooks.allowConversationAccess=true.
--link, щоб не копіювати локальний каталог (додає до plugins.load.paths):
--force не підтримується з --link, оскільки зв’язані інсталяції повторно використовують шлях джерела замість копіювання поверх керованої цілі інсталяції.Використовуйте --pin для npm-інсталяцій, щоб зберегти вирішену точну специфікацію (name@version) у керованому індексі Plugin, зберігаючи стандартну поведінку незакріпленою.Індекс Plugin
Метадані інсталяції Plugin — це стан, керований машиною, а не користувацька конфігурація. Інсталяції та оновлення записують його доplugins/installs.json в активному каталозі стану OpenClaw. Його мапа верхнього рівня installRecords є довговічним джерелом метаданих інсталяції, зокрема записів для зламаних або відсутніх маніфестів Plugin. Масив plugins — це кеш холодного реєстру, виведений із маніфестів. Файл містить попередження не редагувати його та використовується openclaw plugins update, деінсталяцією, діагностикою й холодним реєстром Plugin.
Коли OpenClaw бачить поставлені застарілі записи plugins.installs у конфігурації, runtime-читання трактують їх як вхід сумісності без перезапису openclaw.json. Явні записи Plugin і openclaw doctor --fix переміщують ці записи в індекс Plugin і видаляють ключ конфігурації, коли записи конфігурації дозволені; якщо будь-який із записів не вдається, записи конфігурації зберігаються, щоб метадані інсталяції не були втрачені.
Деінсталяція
uninstall видаляє записи Plugin з plugins.entries, збереженого індексу Plugin, записів allow/deny-списків Plugin і зв’язаних записів plugins.load.paths, коли це застосовно. Якщо --keep-files не задано, деінсталяція також видаляє відстежуваний керований каталог інсталяції, коли він розташований усередині кореня розширень Plugin OpenClaw. Для Plugin активної пам’яті слот пам’яті скидається до memory-core.
--keep-config підтримується як застарілий псевдонім для --keep-files.Оновлення
hooks.internal.installs.
Вирішення id Plugin проти npm-специфікації
Вирішення id Plugin проти npm-специфікації
Коли ви передаєте id Plugin, OpenClaw повторно використовує записану специфікацію інсталяції для цього Plugin. Це означає, що раніше збережені dist-tags, як-от
@beta, і точні закріплені версії продовжують використовуватися під час пізніших запусків update <id>.Для npm-інсталяцій ви також можете передати явну npm-специфікацію пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета назад із відстежуваним записом Plugin, оновлює цей інстальований Plugin і записує нову npm-специфікацію для майбутніх оновлень за id.Передання назви npm-пакета без версії або тегу також зіставляється назад із відстежуваним записом Plugin. Використовуйте це, коли Plugin було закріплено за точною версією і ви хочете повернути його до стандартної лінії релізів реєстру.Оновлення beta-каналу
Оновлення beta-каналу
openclaw plugins update повторно використовує відстежувану специфікацію Plugin, якщо ви не передасте нову специфікацію. openclaw update додатково знає активний канал оновлень OpenClaw: на beta-каналі записи npm і Plugin ClawHub стандартної лінії спершу пробують @beta, а потім повертаються до записаної default/latest-специфікації, якщо beta-релізу Plugin не існує. Про такий fallback повідомляється як про попередження, і він не призводить до збою оновлення ядра. Точні версії та явні теги залишаються закріпленими за цим селектором.Перевірки версій і дрейф цілісності
Перевірки версій і дрейф цілісності
Перед live npm-оновленням OpenClaw перевіряє інстальовану версію пакета щодо метаданих npm-реєстру. Якщо інстальована версія та записана ідентичність артефакту вже відповідають вирішеній цілі, оновлення пропускається без завантаження, повторної інсталяції або перезапису
openclaw.json.Коли існує збережений integrity-хеш і хеш отриманого артефакту змінюється, OpenClaw трактує це як дрейф npm-артефакту. Інтерактивна команда openclaw plugins update виводить очікуваний і фактичний хеші та запитує підтвердження перед продовженням. Неінтерактивні помічники оновлення завершуються із закритою відмовою, якщо викликач не надає явну політику продовження.--dangerously-force-unsafe-install під час оновлення
--dangerously-force-unsafe-install під час оновлення
--dangerously-force-unsafe-install також доступний у plugins update як аварійне перевизначення для хибнопозитивних спрацювань вбудованого сканування небезпечного коду під час оновлень Plugin. Він досі не обходить блокування політики Plugin before_install або блокування через збій сканування, і застосовується лише до оновлень Plugin, а не до оновлень hook-pack.Інспекція
--runtime, щоб завантажити модуль Plugin і включити зареєстровані хуки, інструменти, команди, служби, методи gateway та HTTP-маршрути. Runtime-інспекція повідомляє про відсутні залежності Plugin безпосередньо; інсталяції та ремонти залишаються в openclaw plugins install, openclaw plugins update і openclaw doctor --fix.
CLI-команди, якими володіє Plugin, зазвичай інсталюються як кореневі групи команд openclaw, але Plugin також можуть реєструвати вкладені команди під основним батьківським елементом, як-от openclaw nodes. Після того як inspect --runtime покаже команду в cliCommands, запустіть її за вказаним шляхом; наприклад, Plugin, який реєструє demo-git, можна перевірити за допомогою openclaw demo-git ping.
Кожен Plugin класифікується за тим, що він фактично реєструє під час роботи:
- проста capability — один тип capability (наприклад, plugin лише для провайдера)
- гібридна capability — кілька типів capability (наприклад, текст + мовлення + зображення)
- лише hook — лише hooks, без capabilities або surfaces
- без capability — інструменти/команди/служби, але без capabilities
Прапорець
--json виводить машинно-читний звіт, придатний для скриптів і аудиту. inspect --all відображає таблицю для всього парку з формою, видами capability, повідомленнями про сумісність, capabilities бандла та стовпцями з підсумком hooks. info є псевдонімом для inspect.Doctor
doctor повідомляє про помилки завантаження plugin, діагностику маніфесту/виявлення та повідомлення про сумісність. Коли все чисто, він друкує No plugin issues detected.
Якщо налаштований plugin є на диску, але заблокований перевірками безпеки шляхів у завантажувачі, перевірка конфігурації зберігає запис plugin і повідомляє про нього як present but blocked. Виправте попередню діагностику заблокованого plugin, наприклад права власності на шлях або дозволи на запис для всіх, замість видалення конфігурації plugins.entries.<id> або plugins.allow.
Для збоїв форми модуля, як-от відсутні експорти register/activate, запустіть повторно з OPENCLAW_PLUGIN_LOAD_DEBUG=1, щоб додати до діагностичного виводу стислий підсумок форми експорту.
Registry
plugins registry, щоб перевірити, чи збережений реєстр наявний, актуальний або застарілий. Використовуйте --refresh, щоб перебудувати його зі збереженого індексу plugin, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях runtime-активації.
openclaw doctor --fix також виправляє керований npm-дрейф поруч із реєстром: якщо осиротілий або відновлений пакет @openclaw/* під керованим npm-коренем plugin затіняє вбудований plugin, doctor видаляє цей застарілий пакет і перебудовує реєстр, щоб запуск перевірявся за вбудованим маніфестом. Doctor також повторно зв’язує пакет хоста openclaw у керовані npm plugins, які оголошують peerDependencies.openclaw, щоб локальні для пакета runtime-імпорти, як-от openclaw/plugin-sdk/*, розв’язувалися після оновлень або npm-відновлень.
Marketplace
marketplace.json, скорочення GitHub на кшталт owner/repo, URL репозиторію GitHub або git URL. --json друкує розпізнану мітку джерела, а також розібраний маніфест marketplace і записи plugin.