CLI commands
Плагіни
Керуйте плагінами Gateway, пакетами хуків і сумісними комплектами.
Посібник для кінцевих користувачів зі встановлення, увімкнення та усунення несправностей плагінів.
Короткі приклади встановлення, перегляду списку, оновлення, видалення та публікації.
Модель сумісності комплектів.
Поля маніфесту та схема конфігурації.
Посилення безпеки встановлення плагінів.
Команди
openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id> # псевдонім для inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]Щоб дослідити повільне встановлення, перевірку, видалення або оновлення реєстру, запустіть
команду з OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. Трасування записує тривалість етапів
у stderr і зберігає JSON-вивід придатним для синтаксичного аналізу. Див. Налагодження.
Розробка
openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validateplugins init за замовчуванням створює мінімальний плагін інструмента на TypeScript. Перший
аргумент — ідентифікатор плагіна; --name задає відображувану назву. OpenClaw використовує
ідентифікатор для стандартного каталогу виводу та іменування пакета. Заготовки інструментів використовують
defineToolPlugin і створюють сценарії package.json plugin:build та
plugin:validate, які спочатку виконують збирання, а потім викликають openclaw plugins build/validate.
plugins build імпортує зібрану точку входу, зчитує її статичні метадані інструмента, записує
openclaw.plugin.json і підтримує openclaw.extensions у package.json узгодженим.
plugins validate перевіряє, що згенерований маніфест, метадані пакета та
поточний експорт точки входу досі узгоджуються. Повний процес розробки див. у розділі
Плагіни інструментів.
Заготовка записує вихідний код TypeScript, але генерує метадані із зібраної
точки входу ./dist/index.js, тому цей процес також працює з опублікованим CLI. Використовуйте
--entry <path>, якщо точка входу не є стандартною точкою входу пакета. Використовуйте
plugins build --check у CI, щоб завершувати роботу з помилкою, якщо згенеровані метадані застаріли, не
перезаписуючи файли.
Заготовка постачальника
openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validateЗаготовки постачальників створюють універсальний плагін постачальника моделей, сумісний з OpenAI,
з інфраструктурою автентифікації за ключем API, сценарієм npm run validate, що запускає
clawhub package validate, метаданими пакета ClawHub і робочим процесом GitHub Actions,
який запускається вручну, для майбутньої довіреної публікації через GitHub
OIDC. Заготовки постачальників не створюють Skills і не використовують
openclaw plugins build/validate; ці команди призначені для шляху згенерованих
метаданих заготовки інструмента.
Перед публікацією замініть заповнювачі базової URL-адреси API, каталогу моделей, маршруту документації, тексту облікових даних і вмісту README справжніми відомостями про постачальника. Використовуйте згенерований README для першої публікації в ClawHub і налаштування довіреного видавця.
Встановлення
openclaw plugins search "calendar" # пошук плагінів ClawHubopenclaw plugins install @openclaw/<package> # довірений офіційний каталогopenclaw plugins install <package> # довільний пакет npmopenclaw plugins install clawhub:<package> # лише ClawHubopenclaw plugins install npm:<package> # лише npmopenclaw plugins install npm-pack:<path.tgz> # локальний tar-архів npm-packopenclaw plugins install git:github.com/<owner>/<repo> # репозиторій gitopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path> # локальний шлях або архівopenclaw plugins install -l <path> # створити посилання замість копіюванняopenclaw plugins install <plugin>@<marketplace> # скорочений запис маркетплейсуopenclaw plugins install <plugin> --marketplace <name> # маркетплейс (явно)openclaw plugins install <package> --force # підтвердити джерело / перезаписати наявнеopenclaw plugins install <package> --pin # зафіксувати визначену версію npmopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-installСупроводжувачі, які тестують встановлення під час налаштування, можуть перевизначити автоматичні джерела встановлення плагінів за допомогою захищених змінних середовища. Див. Перевизначення встановлення плагінів.
plugins search запитує в ClawHub доступні для встановлення пакети code-plugin і
bundle-plugin (не Skills; для них використовуйте openclaw skills search).
Стандартне значення --limit — 20, максимальне — 100. Команда лише зчитує віддалений каталог: без
перевірки локального стану, зміни конфігурації, встановлення пакетів або завантаження середовища виконання
плагіна. Результати містять назву пакета ClawHub, сімейство, канал, версію,
короткий опис і підказку зі встановлення, як-от openclaw plugins install clawhub:<package>.
Включення конфігурації та виправлення недійсної конфігурації
Якщо ваш розділ plugins базується на однофайловому $include, plugins install/update/enable/disable/uninstall записує безпосередньо до цього включеного файлу й не змінює openclaw.json. Кореневі включення, масиви включень і включення із сусідніми перевизначеннями безпечно завершуються з помилкою замість згладжування. Підтримувані форми див. у розділі Включення конфігурації.
Якщо під час встановлення конфігурація недійсна, plugins install зазвичай безпечно завершується з помилкою та пропонує спочатку запустити openclaw doctor --fix. Під час запуску Gateway і гарячого перезавантаження недійсна конфігурація плагіна безпечно завершується з помилкою, як і будь-яка інша недійсна конфігурація; openclaw doctor --fix може помістити недійсний запис плагіна в карантин. Єдиний документований виняток під час встановлення — вузький шлях відновлення вбудованих плагінів для плагінів, які явно погоджуються на openclaw.install.allowInvalidConfigRecovery.
Підтвердження --force і повторне встановлення порівняно з оновленням
--force підтверджує джерело, відмінне від ClawHub, без запиту. Він не обходить security.installPolicy або решту перевірок безпеки встановлення. Якщо плагін або пакет хуків уже встановлено, він також повторно використовує наявну ціль і перезаписує її на місці. Використовуйте його після перевірки довільного джерела npm, локального джерела, архіву, git або маркетплейсу чи коли навмисно повторно встановлюєте той самий ідентифікатор. Для звичайних оновлень уже відстежуваного плагіна npm віддавайте перевагу openclaw plugins update <id-or-npm-spec>.
Якщо запустити plugins install для ідентифікатора плагіна, який уже встановлено, OpenClaw зупиниться та вкаже на plugins update <id-or-npm-spec> для звичайного оновлення або на plugins install <package> --force, коли справді потрібно перезаписати поточне встановлення з іншого джерела. Довільні джерела все одно показують інтерактивне попередження про походження; для неінтерактивного встановлення після перевірки потрібно передати --force. Для довірених джерел ClawHub і каталогу OpenClaw він не потрібен. З --link параметр --force підтверджує джерело, але не змінює режим установлення через пов'язаний шлях.
Область дії --pin
--pin застосовується лише до встановлень npm і записує визначений точний <name>@<version>. Він не підтримується зі встановленнями git: (натомість зафіксуйте посилання у специфікації, наприклад git:github.com/acme/plugin@v1.2.3) або з --marketplace (встановлення з маркетплейсу зберігають метадані джерела маркетплейсу замість специфікації npm).
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install застарів і тепер нічого не робить. OpenClaw більше не виконує вбудоване блокування небезпечного коду під час встановлення плагінів.
Використовуйте керовану оператором поверхню security.installPolicy, коли потрібна специфічна для хоста політика встановлення. Хуки Plugin before_install — це хуки життєвого циклу середовища виконання плагіна, а не основна межа політики для встановлень через CLI.
Якщо опублікований вами в ClawHub плагін приховано або заблоковано перевіркою реєстру, виконайте кроки для видавця в розділі Публікація в ClawHub. --dangerously-force-unsafe-install не надсилає ClawHub запит на повторну перевірку плагіна й не робить заблокований випуск загальнодоступним.
--acknowledge-clawhub-risk
Перед завантаженням установлення зі спільноти ClawHub перевіряють запис довіри вибраного випуску. Якщо ClawHub вимикає завантаження випуску, повідомляє про виявлені перевіркою шкідливі елементи або переводить випуск у блокувальний стан модерації (карантин, відкликання), OpenClaw безумовно відмовляється від нього незалежно від цього прапорця. Для неблокувальних ризикованих статусів перевірки або станів модерації OpenClaw показує відомості про довіру й запитує підтвердження перед продовженням.
Використовуйте --acknowledge-clawhub-risk лише після перегляду попередження ClawHub і ухвалення рішення продовжити без інтерактивного запиту. Результати перевірки зі статусом очікування або застарілі (ще не підтверджені як безпечні) спричиняють попередження, але не потребують підтвердження. Офіційні пакети ClawHub і вбудовані джерела плагінів OpenClaw повністю оминають цю перевірку довіри до випуску.
Пакети хуків і специфікації npm
plugins install також є поверхнею встановлення для пакетів хуків, які надають openclaw.hooks у package.json. Використовуйте openclaw hooks для фільтрованої видимості хуків і ввімкнення окремих хуків, а не для встановлення пакета.
Специфікації npm підтримують лише реєстр (назва пакета з необов’язковою точною версією або dist-tag). Специфікації Git/URL/файлів і діапазони semver відхиляються. Для безпеки залежності встановлюються в одному керованому проєкті npm на плагін із --ignore-scripts, навіть якщо оболонка має глобальні налаштування встановлення npm. Керовані проєкти npm плагінів успадковують пакетний npm overrides OpenClaw, тому налаштування безпеки хоста також застосовуються до піднятих залежностей плагінів.
Використовуйте npm:<package>, щоб явно задати розв’язання через npm. Під час переходу на запуск специфікації пакетів без префікса також установлюються безпосередньо з npm, якщо вони не відповідають ідентифікатору офіційного плагіна.
Необроблені специфікації @openclaw/*, що відповідають вбудованим плагінам, розв’язуються до вбудованої копії, яка належить образу, перш ніж застосовується резервне розв’язання через npm. Наприклад, openclaw plugins install @openclaw/discord@2026.5.20 --pin використовує вбудований плагін Discord із поточної збірки OpenClaw замість створення керованого перевизначення npm. Щоб примусово використати зовнішній пакет npm, застосуйте openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin.
Специфікації без префікса та @latest залишаються на стабільному каналі. Версії виправлень OpenClaw із датою, як-от 2026.5.3-1, вважаються стабільними для цієї перевірки. Якщо npm розв’язує будь-яку із цих форм до попередньої версії, OpenClaw зупиняється й просить явно погодитися за допомогою тегу попередньої версії (@beta/@rc) або точної попередньої версії (@1.2.3-beta.4).
Для встановлень npm без точної версії (npm:<package> або npm:<package>@latest) OpenClaw перед установленням перевіряє метадані розв’язаного пакета. Якщо останній стабільний пакет потребує новішого API плагінів OpenClaw або вищої мінімальної версії хоста, OpenClaw перевіряє старіші стабільні версії та натомість установлює найновіший сумісний випуск. Точні версії та явні dist-tag залишаються суворими: несумісний вибір завершується помилкою з пропозицією оновити OpenClaw або вибрати сумісну версію.
Якщо специфікація встановлення без префікса відповідає ідентифікатору офіційного плагіна (наприклад, diffs), OpenClaw безпосередньо встановлює запис каталогу. Щоб установити пакет npm із такою самою назвою, використовуйте явну специфікацію з областю видимості (наприклад, @scope/diffs).
Репозиторії Git
Використовуйте git:<repo> для встановлення безпосередньо з репозиторію git. Підтримувані форми: git:github.com/owner/repo, git:owner/repo, повні https://, ssh://, git://, file:// і URL-адреси клонування git@host:owner/repo.git. Додайте @<ref> або #<ref>, щоб перед установленням отримати гілку, тег або коміт.
Під час установлення з Git репозиторій клонується в тимчасовий каталог, за наявності виконується перехід на запитане посилання, а потім використовується звичайний інсталятор плагінів із каталогу, тому перевірка маніфесту, політика встановлення оператора, робота пакетного менеджера та записи встановлення поводяться так само, як під час установлення з npm. Записані встановлення з git містять URL-адресу/посилання джерела та розв’язаний коміт, щоб openclaw plugins update міг повторно розв’язати джерело пізніше.
Після встановлення з git використовуйте openclaw plugins inspect <id> --runtime --json, щоб перевірити реєстрації середовища виконання, як-от методи Gateway і команди CLI. Якщо плагін зареєстрував кореневу команду CLI за допомогою api.registerCli, запускайте цю команду безпосередньо через кореневий CLI OpenClaw, наприклад openclaw demo-plugin ping.
Архіви
Підтримувані архіви: .zip, .tgz, .tar.gz, .tar. Власні архіви плагінів OpenClaw мають містити дійсний openclaw.plugin.json у корені розпакованого плагіна; архіви, які містять лише package.json, відхиляються до того, як OpenClaw запише дані про встановлення.
Використовуйте npm-pack:<path.tgz>, якщо файл є tar-архівом npm-pack і потрібно
застосувати той самий шлях керованого проєкту npm для кожного плагіна, що й під час установлення з реєстру,
зокрема перевірку package-lock.json, сканування піднятих залежностей
і записи встановлення npm. Звичайні шляхи до архівів і надалі встановлюються як локальні
архіви в корені розширень плагінів.
Установлення з маркетплейсу Claude також підтримуються.
Для встановлень із ClawHub використовується явний локатор clawhub:<package>:
openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3Під час переходу на запуск безпечні для npm специфікації плагінів без префікса за замовчуванням установлюються з npm, якщо вони не відповідають ідентифікатору офіційного плагіна:
openclaw plugins install openclaw-codex-app-serverВикористовуйте npm:, щоб явно задати розв’язання лише через npm:
openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1Перед установленням OpenClaw перевіряє заявлену сумісність API плагіна / мінімальної версії Gateway. Коли вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версіонований npm-pack .tgz, перевіряє заголовок дайджесту ClawHub і дайджест артефакту, а потім установлює його через звичайний шлях архіву. Старіші версії ClawHub без метаданих ClawPack і надалі встановлюються через застарілий шлях перевірки архіву пакета. Записані встановлення зберігають метадані джерела ClawHub, тип артефакту, цілісність npm, контрольну суму npm, назву tar-архіву й дані дайджесту ClawPack для подальших оновлень.
Записана специфікація встановлень ClawHub без версії також залишається без версії, щоб openclaw plugins update міг переходити на новіші випуски ClawHub; явні селектори версії або тегу, як-от clawhub:pkg@1.2.3 і clawhub:pkg@beta, залишаються закріпленими за цим селектором.
Скорочений запис маркетплейсу
Використовуйте скорочений запис plugin@marketplace, коли назва маркетплейсу існує в локальному кеші реєстру Claude за адресою ~/.claude/plugins/known_marketplaces.json:
openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>Використовуйте --marketplace, щоб явно передати джерело маркетплейсу:
openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplaceДжерела маркетплейсу
- назва відомого маркетплейсу Claude з
~/.claude/plugins/known_marketplaces.json - корінь локального маркетплейсу або шлях
marketplace.json - скорочений запис репозиторію GitHub, як-от
owner/repo - URL-адреса репозиторію GitHub, як-от
https://github.com/owner/repo - URL-адреса git
Правила віддаленого маркетплейсу
Для віддалених маркетплейсів, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію маркетплейсу. OpenClaw приймає джерела з відносними шляхами з цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші джерела плагінів, що не є шляхами, із віддалених маніфестів.
Для локальних шляхів і архівів OpenClaw автоматично визначає:
- власні плагіни OpenClaw (
openclaw.plugin.json) - сумісні з Codex пакети (
.codex-plugin/plugin.json) - сумісні з Claude пакети (
.claude-plugin/plugin.jsonабо стандартне компонування компонентів Claude, коли файл цього маніфесту відсутній) - сумісні з Cursor пакети (
.cursor-plugin/plugin.json)
Керовані локальні встановлення мають бути каталогами або архівами плагінів. Окремі файли плагінів .js,
.mjs, .cjs і .ts не копіюються в керований корінь
плагінів командою plugins install і не завантажуються, якщо розмістити їх безпосередньо в
~/.openclaw/extensions або <workspace>/.openclaw/extensions; ці
автоматично виявлені корені завантажують каталоги пакетів або комплектів плагінів і пропускають
файли сценаріїв верхнього рівня як локальні допоміжні файли. Натомість явно перелічіть окремі файли в
plugins.load.paths.
Використовуйте -l/--link, щоб указати локальний каталог плагіна без його копіювання (додає
до plugins.load.paths):
openclaw plugins install -l ./my-plugin--link не підтримується для встановлень --marketplace або git: і
потребує локального шляху, який уже існує. Для неінтерактивного локального посилання
передайте --force після перевірки джерела; це підтверджує походження, але не
копіює й не перезаписує каталог, на який указує посилання.
Перелік
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json--enabledbooleanПоказати лише ввімкнені плагіни.
--verbosebooleanПерейти від табличного подання до рядків із докладними відомостями про кожен плагін, включно з метаданими формату/джерела/походження/версії/активації.
--jsonbooleanМашиночитаний перелік разом із діагностикою реєстру та станом установлення залежностей пакета.
Якщо під час запуску в журналах з'являється plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,
виконайте openclaw plugins list --enabled --verbose або
openclaw plugins inspect <id> із зазначеним ідентифікатором плагіна, щоб підтвердити
ідентифікатори плагінів, і скопіюйте довірені ідентифікатори до plugins.allow у openclaw.json. Коли
в попередженні можна перелічити всі виявлені плагіни, воно виводить готовий для вставлення
фрагмент plugins.allow, який уже містить ці ідентифікатори. Якщо плагін завантажується
без даних про походження встановлення або шляху завантаження, перевірте цей ідентифікатор плагіна, а потім або закріпіть
довірений ідентифікатор у plugins.allow, або перевстановіть плагін із довіреного джерела,
щоб OpenClaw записав походження встановлення.
Під час роботи з вбудованим плагіном у запакованому образі Docker під'єднайте каталог
вихідного коду плагіна як bind mount поверх відповідного шляху запакованого вихідного коду, наприклад
/app/extensions/synology-chat. OpenClaw виявляє це змонтоване накладання вихідного коду
перед /app/dist/extensions/synology-chat; просто скопійований каталог вихідного коду
залишається неактивним, тому звичайні запаковані встановлення й надалі використовують скомпільований dist.
Для налагодження хуків середовища виконання:
openclaw plugins inspect <id> --runtime --jsonпоказує зареєстровані хуки й діагностику, отримані під час перевірки із завантаженням модуля. Перевірка середовища виконання ніколи не встановлює залежності; використовуйтеopenclaw doctor --fix, щоб очистити застарілий стан залежностей або відновити відсутні завантажувані плагіни, на які посилається конфігурація.openclaw gateway status --deep --require-rpcпідтверджує доступну URL-адресу або профіль 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.
Індекс плагінів
Метадані встановлення плагінів — це стан, яким керує система, а не користувацька конфігурація. Під час встановлень і оновлень ці дані записуються до спільної бази даних стану SQLite в активному каталозі стану OpenClaw. Рядок installed_plugin_index зберігає сталі метадані installRecords, зокрема записи про пошкоджені або відсутні маніфести плагінів, а також похідний від маніфестів кеш холодного реєстру, який використовують openclaw plugins update, видалення, діагностика та холодний реєстр плагінів.
Коли OpenClaw виявляє в конфігурації випущені застарілі записи plugins.installs, середовище виконання читає їх як вхідні дані сумісності, не перезаписуючи openclaw.json. Явні операції запису плагінів і openclaw doctor --fix переміщують ці записи до індексу плагінів і видаляють ключ конфігурації, якщо запис конфігурації дозволено; якщо будь-яка з операцій запису завершується невдало, записи конфігурації зберігаються, щоб не втратити метадані встановлення.
Видалення
openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --forceuninstall видаляє записи плагіна з plugins.entries, збереженого індексу плагінів, списків дозволених і заборонених плагінів, а також пов'язані записи plugins.load.paths, коли це застосовно. Якщо не задано --keep-files, під час видалення також вилучається відстежуваний керований каталог встановлення, але лише якщо його дозволений шлях розташований у кореневому каталозі розширень плагінів OpenClaw. Якщо плагін наразі займає слот memory або contextEngine, цей слот скидається до типового значення (memory-core для пам'яті, legacy для рушія контексту).
uninstall виводить попередній перегляд того, що буде видалено, а потім перед внесенням змін показує запит Uninstall plugin "<id>"?. Передайте --force, щоб пропустити запит підтвердження (це корисно для сценаріїв і неінтерактивних запусків); без нього видалення потребує інтерактивного TTY. --dry-run виводить такий самий попередній перегляд і завершує роботу без запиту чи будь-яких змін.
Оновлення
openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update @acme/demoopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-installОновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і відстежуваних встановлень пакетів хуків у hooks.internal.installs. Вони повторно використовують джерело, яке користувач уже вибрав під час встановлення плагіна, тому повторне підтвердження джерела не потрібне.
Визначення ідентифікатора плагіна порівняно зі специфікацією npm
Коли передається ідентифікатор плагіна, OpenClaw повторно використовує записану специфікацію встановлення цього плагіна. Це означає, що раніше збережені теги дистрибутива, як-от @beta, і точно закріплені версії продовжують використовуватися під час наступних запусків update <id>.
Під час update <id> --dry-run точно закріплені встановлення npm залишаються закріпленими. Якщо OpenClaw також може визначити типову гілку реєстру пакета й вона новіша за встановлену закріплену версію, пробний запуск повідомляє про закріплення та виводить явну команду оновлення пакета @latest для переходу на типову гілку реєстру.
Це правило цільового оновлення відрізняється від шляху масового обслуговування openclaw plugins update --all. Масові оновлення й надалі враховують звичайні відстежувані специфікації встановлення, але записи довірених офіційних плагінів OpenClaw можуть синхронізуватися з поточною цільовою версією офіційного каталогу, а не залишатися на застарілому точному офіційному пакеті. Використовуйте цільовий update <id>, якщо навмисно потрібно залишити точну або позначену тегом офіційну специфікацію без змін.
Для встановлень npm також можна передати явну специфікацію пакета npm із тегом дистрибутива або точною версією. OpenClaw зіставляє цю назву пакета з відстежуваним записом плагіна, оновлює встановлений плагін і записує нову специфікацію npm для майбутніх оновлень за ідентифікатором.
Передавання назви пакета npm без версії або тегу також зіставляє її з відстежуваним записом плагіна. Використовуйте це, коли плагін було закріплено до точної версії й потрібно повернути його до типової гілки випусків реєстру.
Оновлення бета-каналу
Цільовий openclaw plugins update <id-or-npm-spec> повторно використовує відстежувану специфікацію плагіна, якщо не передано нову специфікацію. Масовий openclaw plugins update --all використовує налаштований update.channel під час синхронізації записів довірених офіційних плагінів із цільовою версією офіційного каталогу, тому встановлення з бета-каналу можуть залишатися на бета-гілці випусків, а не непомітно нормалізуватися до stable/latest.
openclaw update також розпізнає активний канал оновлень OpenClaw: у бета-каналі записи плагінів npm і ClawHub із типовою гілкою спочатку пробують @beta. Якщо бета-випуску плагіна немає, вони повертаються до записаної типової або найновішої специфікації; плагіни npm також використовують резервний варіант, коли бета-пакет існує, але не проходить перевірку встановлення. Про використання резервного варіанта повідомляється попередженням, і воно не спричиняє збою оновлення ядра. Точні версії та явні теги під час цільових оновлень залишаються закріпленими за цим селектором.
Перевірки версій і розбіжність цілісності
Перед безпосереднім оновленням npm OpenClaw звіряє версію встановленого пакета з метаданими реєстру npm. Якщо встановлена версія та записана ідентичність артефакту вже відповідають визначеній цільовій версії, оновлення пропускається без завантаження, перевстановлення або перезапису openclaw.json.
Якщо існує збережений хеш цілісності, а хеш отриманого артефакту змінився, OpenClaw вважає це розбіжністю артефакту npm. Інтерактивна команда openclaw plugins update виводить очікуваний і фактичний хеші та запитує підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення завершуються з відмовою, якщо викликач не надасть явну політику продовження.
--dangerously-force-unsafe-install під час оновлення
--dangerously-force-unsafe-install також приймається в plugins update для сумісності, але є застарілим і більше не змінює поведінку оновлення плагінів. Оператор security.installPolicy усе ще може блокувати оновлення; хуки плагіна before_install застосовуються лише в процесах, де завантажено хуки плагінів.
--acknowledge-clawhub-risk під час оновлення
Оновлення плагінів спільноти на основі ClawHub перед завантаженням пакета заміни проходять таку саму перевірку довіри до конкретного випуску, що й під час встановлення. Використовуйте --acknowledge-clawhub-risk для перевіреної автоматизації, яка має продовжувати роботу, коли вибраний випуск ClawHub має ризиковане попередження щодо довіри. Офіційні пакети ClawHub і джерела вбудованих плагінів OpenClaw оминають цей запит про довіру до випуску.
Перевірка
openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allЗа замовчуванням перевірка показує ідентичність, стан завантаження, джерело, можливості маніфесту, прапорці політик, діагностику, метадані встановлення, можливості пакета й усю виявлену підтримку серверів MCP або LSP, не імпортуючи середовище виконання плагіна. Виведення JSON містить контракти маніфесту плагіна, як-от contracts.agentToolResultMiddleware і contracts.trustedToolPolicies, щоб оператори могли перевірити оголошення довірених поверхонь перед увімкненням або перезапуском плагіна. Додайте --runtime, щоб завантажити модуль плагіна й включити зареєстровані хуки, інструменти, команди, служби, методи Gateway і маршрути HTTP. Перевірка середовища виконання безпосередньо повідомляє про відсутні залежності плагіна; встановлення та відновлення виконуються через openclaw plugins install, openclaw plugins update і openclaw doctor --fix.
Команди CLI, якими володіють плагіни, зазвичай установлюються як кореневі групи команд openclaw, але плагіни також можуть реєструвати вкладені команди під батьківською командою ядра, як-от openclaw nodes. Після того як inspect --runtime покаже команду в cliCommands, виконайте її за вказаним шляхом; наприклад, плагін, який реєструє demo-git, можна перевірити за допомогою openclaw demo-git ping.
Кожен плагін класифікується за тим, що він фактично реєструє під час виконання:
| Форма | Значення |
|---|---|
plain-capability |
рівно один тип можливості (наприклад, плагін лише для провайдера) |
hybrid-capability |
понад один тип можливостей (наприклад, текст + мовлення + зображення) |
hook-only |
лише хуки, без можливостей, інструментів, команд, служб або маршрутів |
non-capability |
інструменти, команди або служби, але без можливостей |
Докладніше про модель можливостей див. у розділі Форми плагінів.
Діагностика
openclaw plugins doctordoctor повідомляє про помилки завантаження плагінів, діагностичні дані маніфесту й виявлення, сповіщення про сумісність і посилання на застарілу конфігурацію плагінів, як-от відсутні слоти плагінів. Коли дерево встановлення та конфігурація плагінів не містять проблем, команда виводить No plugin issues detected. Якщо застаріла конфігурація залишається, але дерево встановлення в іншому справне, це зазначається у зведенні без створення хибного враження про повну справність плагінів.
Якщо налаштований плагін наявний на диску, але заблокований перевірками безпечності шляхів завантажувача, перевірка конфігурації зберігає запис плагіна й повідомляє про нього як про present but blocked. Виправте вказану перед цим причину блокування плагіна, як-от власника шляху або дозволи на запис для всіх користувачів, замість видалення конфігурації plugins.entries.<id> чи plugins.allow.
У разі помилок структури модуля, як-от відсутність експортованих елементів register/activate, повторіть запуск із OPENCLAW_PLUGIN_LOAD_DEBUG=1, щоб додати до діагностичного виводу стислий опис структури експортованих елементів.
Реєстр
openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --jsonЛокальний реєстр плагінів — це збережена модель холодного читання OpenClaw для ідентичності встановлених плагінів, стану їх увімкнення, метаданих джерел і належності внесків. Звичайний запуск, пошук власника постачальника, класифікація налаштування каналів та інвентаризація плагінів можуть читати її без імпорту модулів середовища виконання плагінів.
Скористайтеся plugins registry, щоб перевірити, чи існує збережений реєстр і чи є він актуальним або застарілим. Скористайтеся --refresh, щоб перебудувати його зі збереженого індексу плагінів, політики конфігурації та метаданих маніфесту або пакета. Це шлях відновлення, а не шлях активації середовища виконання.
openclaw doctor --fix також виправляє пов’язані з реєстром розбіжності керованих пакетів npm: якщо осиротілий або відновлений пакет @openclaw/* у керованому npm-проєкті плагіна чи застарілому плоскому корені керованих пакетів npm перекриває вбудований плагін, doctor видаляє цей застарілий пакет і перебудовує реєстр, щоб під час запуску перевірка виконувалася за вбудованим маніфестом. Doctor також повторно створює посилання на пакет хоста openclaw у керованих npm-плагінах, які оголошують peerDependencies.openclaw, щоб локальні для пакета імпорти середовища виконання, як-от openclaw/plugin-sdk/*, коректно розв’язувалися після оновлень або відновлення npm.
Маркетплейс
openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --jsonplugins marketplace entries перелічує записи з налаштованого каналу маркетплейсу OpenClaw. Типово команда намагається використати розміщений канал, а в разі невдачі переходить до останнього прийнятого знімка або вбудованих даних. Скористайтеся --feed-profile <name>, щоб прочитати певний налаштований профіль, --feed-url <url> — щоб прочитати явно вказану URL-адресу розміщеного каналу, а --offline — щоб прочитати останній прийнятий знімок без отримання каналу.
plugins marketplace refresh оновлює знімок налаштованого розміщеного каналу й повідомляє, чи прийняв OpenClaw розміщені дані, знімок розміщеного каналу або вбудовані резервні дані. Використовуйте --expected-sha256, коли команда має завершитися помилкою, якщо свіжі розміщені дані не відповідають закріпленій контрольній сумі.
Команда маркетплейсу list приймає локальний шлях до маркетплейсу, шлях marketplace.json, скорочений запис GitHub на кшталт owner/repo, URL-адресу репозиторію GitHub або URL-адресу git. --json виводить мітку визначеного джерела, а також розібраний маніфест маркетплейсу й записи плагінів.
Оновлення маркетплейсу завантажує розміщений канал маркетплейсу OpenClaw і зберігає
перевірену відповідь як локальний знімок розміщеного каналу. Без параметрів
використовується налаштований стандартний профіль каналу. Скористайтеся --feed-profile <name>, щоб оновити
певний налаштований профіль, --feed-url <url> — щоб оновити явно вказану URL-адресу
розміщеного каналу, --expected-sha256 <sha256> — щоб вимагати відповідності контрольної суми даних
(sha256:<hex> або лише 64-символьний шістнадцятковий дайджест), а --json — для
машинозчитуваного виводу. Явно вказані URL-адреси розміщених каналів не повинні містити
облікових даних, рядків запиту чи фрагментів. Незакріплені оновлення можуть повідомляти про
результат із використанням знімка розміщеного каналу або вбудованих резервних даних, не завершуючи команду помилкою. Закріплені
оновлення завершуються помилкою, якщо не прийнято свіжі розміщені дані, а успішні розміщені
оновлення завершуються помилкою, якщо OpenClaw не може зберегти перевірений знімок.
