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> # alias for 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:validateЗа замовчуванням plugins 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" # search ClawHub pluginsopenclaw plugins install <package> # source auto-detectionopenclaw plugins install clawhub:<package> # ClawHub onlyopenclaw plugins install npm:<package> # npm onlyopenclaw plugins install npm-pack:<path.tgz> # local npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo> # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path> # local path or archiveopenclaw plugins install -l <path> # link instead of copyopenclaw plugins install <plugin>@<marketplace> # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)openclaw plugins install <package> --force # overwrite existing installopenclaw plugins install <package> --pin # pin resolved npm versionopenclaw 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 або артефакту npm. Для звичайних оновлень уже відстежуваного плагіна npm віддавайте перевагу openclaw plugins update <id-or-npm-spec>.
Якщо запустити plugins install для вже встановленого ідентифікатора плагіна, OpenClaw зупинить операцію та запропонує plugins update <id-or-npm-spec> для звичайного оновлення або plugins install <package> --force, якщо ви справді хочете перезаписати поточне встановлення з іншого джерела. --force не підтримується разом із --link.
Область дії --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, коли потрібна специфічна для хоста політика встановлення. Хуки плагіна 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 відхиляються. Для безпеки залежності встановлюються з --ignore-scripts в одному керованому проєкті npm для кожного Plugin, навіть якщо у вашій оболонці налаштовано глобальні параметри встановлення npm. Керовані проєкти npm для Plugin успадковують npm overrides рівня пакета OpenClaw, тому закріплені на рівні хоста версії для усунення вразливостей також застосовуються до піднятих залежностей Plugin.
Використовуйте npm:<package>, щоб явно вказати розв’язання через npm. Під час перехідного етапу запуску специфікації пакетів без префікса також установлюються безпосередньо з npm, якщо вони не відповідають ідентифікатору офіційного Plugin.
Необроблені специфікації @openclaw/*, що відповідають вбудованим Plugin, спочатку розв’язуються до вбудованої копії, яка належить образу, і лише потім використовується резервне розв’язання через npm. Наприклад, openclaw plugins install @openclaw/discord@2026.5.20 --pin використовує вбудований Plugin 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 Plugin OpenClaw або вищої мінімальної версії хоста, OpenClaw перевіряє старіші стабільні версії та встановлює найновіший сумісний випуск. Точні версії та явно вказані dist-tag залишаються суворими: вибір несумісної версії завершується помилкою з пропозицією оновити OpenClaw або вибрати сумісну версію.
Якщо специфікація встановлення без префікса відповідає ідентифікатору офіційного Plugin (наприклад, diffs), OpenClaw установлює безпосередньо запис із каталогу. Щоб установити однойменний пакет npm, використовуйте явну специфікацію з областю видимості (наприклад, @scope/diffs).
Репозиторії Git
Використовуйте git:<repo> для встановлення безпосередньо з репозиторію Git. Підтримувані форми: git:github.com/owner/repo, git:owner/repo, повні URL-адреси https://, ssh://, git://, file:// і URL-адреси клонування git@host:owner/repo.git. Додайте @<ref> або #<ref>, щоб перед установленням перейти на гілку, тег або коміт.
Під час установлення з Git репозиторій клонується до тимчасового каталогу, за наявності виконується перехід на вказане посилання, а потім використовується звичайний інсталятор каталогу Plugin. Тому перевірка маніфесту, політика встановлення оператора, встановлення через менеджер пакетів і записи про встановлення працюють так само, як для встановлень із npm. Записані встановлення з Git містять URL-адресу та посилання джерела, а також розв’язаний коміт, щоб openclaw plugins update міг згодом повторно розв’язати джерело.
Після встановлення з Git скористайтеся openclaw plugins inspect <id> --runtime --json, щоб перевірити реєстрації середовища виконання, як-от методи 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>, якщо файл є tar-архівом npm-pack і вам потрібен
той самий шлях керованого проєкту npm для кожного Plugin, який використовується під час установлення з реєстру,
зокрема перевірка package-lock.json, сканування піднятих залежностей
і записи про встановлення npm. Звичайні шляхи до архівів і надалі встановлюються як локальні
архіви в корені розширень Plugin.
Також підтримується встановлення з маркетплейсу Claude.
Для встановлення з ClawHub використовується явний локатор clawhub:<package>:
openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3Під час перехідного етапу запуску безпечні для npm специфікації Plugin без префікса типово встановлюються з npm, якщо вони не відповідають ідентифікатору офіційного Plugin:
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 Plugin і мінімальною версією Gateway. Якщо вибрана версія ClawHub публікує артефакт ClawPack, OpenClaw завантажує версійний .tgz npm-pack, перевіряє заголовок дайджесту 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, записи Plugin повинні залишатися в межах клонованого репозиторію маркетплейсу. OpenClaw приймає джерела з відносними шляхами в цьому репозиторії та відхиляє HTTP(S), абсолютні шляхи, Git, GitHub та інші джерела Plugin, що не є шляхами, у віддалених маніфестах.
Для локальних шляхів і архівів OpenClaw автоматично виявляє:
- нативні Plugin OpenClaw (
openclaw.plugin.json) - пакети, сумісні з Codex (
.codex-plugin/plugin.json) - пакети, сумісні з Claude (
.claude-plugin/plugin.json, або типовий макет компонентів Claude, якщо файл маніфесту відсутній) - пакети, сумісні з Cursor (
.cursor-plugin/plugin.json)
Керовані локальні встановлення мають бути каталогами або архівами Plugin. Окремі файли Plugin .js,
.mjs, .cjs і .ts не копіюються до керованого кореня Plugin командою
plugins install і не завантажуються, якщо розмістити їх безпосередньо в
~/.openclaw/extensions або <workspace>/.openclaw/extensions; ці
автоматично виявлені корені завантажують каталоги пакетів або комплектів Plugin і пропускають
файли сценаріїв верхнього рівня як локальні допоміжні файли. Натомість явно вкажіть окремі файли в
plugins.load.paths.
Використовуйте -l/--link, щоб указати локальний каталог Plugin без його копіювання (додає
до plugins.load.paths):
openclaw plugins install -l ./my-plugin--link не підтримується разом із --force (пов’язані Plugin указують безпосередньо на шлях
до джерела, тому перезаписувати на місці нічого), --marketplace або
встановленнями git:; також потрібен уже наявний локальний шлях.
Список
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json--enabledbooleanПоказувати лише ввімкнені Plugin.
--verbosebooleanПеремкнутися з табличного подання на рядки докладної інформації для кожного Plugin з метаданими формату, джерела, походження, версії та активації.
--jsonbooleanМашиночитаний перелік разом із діагностикою реєстру та станом установлення залежностей пакета.
Якщо під час запуску в журналі з’являється plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,
виконайте openclaw plugins list --enabled --verbose або
openclaw plugins inspect <id> з ідентифікатором Plugin зі списку, щоб підтвердити
ідентифікатори Plugin і скопіювати довірені ідентифікатори до plugins.allow у openclaw.json. Якщо
в попередженні можна перелічити всі виявлені Plugin, воно виводить готовий до вставлення
фрагмент plugins.allow, який уже містить ці ідентифікатори. Якщо Plugin завантажується
без даних про походження встановлення або шлях завантаження, перевірте цей ідентифікатор Plugin, а потім або закріпіть
довірений ідентифікатор у plugins.allow, або повторно встановіть Plugin із довіреного джерела,
щоб OpenClaw записав походження встановлення.
Для роботи з вбудованим Plugin усередині упакованого образу Docker підключіть каталог
із вихідним кодом Plugin поверх відповідного упакованого шляху до вихідного коду, наприклад
/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 показує попередній перегляд того, що буде видалено, а потім перед внесенням змін запитує Видалити плагін "<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 openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-installОновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і відстежуваних встановлень пакетів хуків у hooks.internal.installs.
Визначення ідентифікатора плагіна й специфікації npm
Коли ви передаєте ідентифікатор плагіна, OpenClaw повторно використовує записану специфікацію встановлення цього плагіна. Це означає, що раніше збережені dist-теги, як-от @beta, і точно закріплені версії продовжують використовуватися під час наступних запусків update <id>.
Під час update <id> --dry-run точно закріплені встановлення npm залишаються закріпленими. Якщо OpenClaw також може визначити стандартну гілку пакета в реєстрі й вона новіша за встановлену закріплену версію, пробний запуск повідомляє про закріплення та показує явну команду оновлення пакета до @latest, щоб перейти на стандартну гілку реєстру.
Це правило цільового оновлення відрізняється від шляху масового обслуговування openclaw plugins update --all. Масові оновлення й надалі дотримуються звичайних відстежуваних специфікацій установлення, але записи довірених офіційних плагінів OpenClaw можуть синхронізуватися з поточною цільовою версією офіційного каталогу замість збереження застарілого точно вказаного офіційного пакета. Використовуйте цільове update <id>, коли навмисно хочете залишити точну або позначену тегом офіційну специфікацію без змін.
Для встановлень npm також можна передати явну специфікацію пакета npm із dist-тегом або точною версією. OpenClaw зіставляє назву цього пакета з відстежуваним записом плагіна, оновлює встановлений плагін і записує нову специфікацію npm для майбутніх оновлень за ідентифікатором.
Передавання назви пакета npm без версії або тегу також зіставляє її з відстежуваним записом плагіна. Скористайтеся цим, коли плагін було закріплено на точній версії, а ви хочете повернути його до стандартної гілки випусків реєстру.
Оновлення бета-каналу
Цільова команда openclaw plugins update <id-or-npm-spec> повторно використовує відстежувану специфікацію плагіна, якщо ви не передали нову. Масова команда openclaw plugins update --all використовує налаштований update.channel, коли синхронізує записи довірених офіційних плагінів із цільовою версією офіційного каталогу, тому встановлення з бета-каналу можуть залишатися на гілці бета-випусків замість неявної нормалізації до стабільної/найновішої версії.
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 повідомляє про помилки завантаження плагінів, діагностику маніфестів/виявлення, повідомлення про сумісність і застарілі посилання на плагіни в конфігурації, як-от відсутні слоти плагінів. Коли дерево встановлення та конфігурація плагінів не мають проблем, команда виводить Проблем із плагінами не виявлено. Якщо застаріла конфігурація залишається, але дерево встановлення в іншому справне, у зведенні це зазначається без твердження про повну справність плагінів.
Якщо налаштований плагін наявний на диску, але заблокований перевірками безпечності шляхів завантажувача, перевірка конфігурації зберігає запис плагіна й повідомляє про стан наявний, але заблокований. Виправте попереднє діагностичне повідомлення про заблокований плагін, наприклад щодо власника шляху або дозволів на запис для всіх користувачів, замість видалення 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 не може зберегти перевірений знімок.
