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: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" # поиск плагинов 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, когда требуется политика установки, специфичная для хоста. Хуки 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-тег). Спецификации Git/URL/файлов и диапазоны semver отклоняются. Для безопасности зависимости устанавливаются в отдельном управляемом проекте npm для каждого плагина с --ignore-scripts, даже если в вашей оболочке настроены глобальные параметры установки npm. Управляемые проекты npm плагинов наследуют overrides уровня пакета npm из 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-теги обрабатываются строго: при выборе несовместимой версии операция завершается ошибкой с предложением обновить 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-монтирование поверх соответствующего пути к упакованным исходникам, например
/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. Если бета-версия плагина отсутствует, они возвращаются к сохранённой спецификации default/latest; плагины 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 |
инструменты/команды/службы, но без возможностей |
Дополнительные сведения о модели возможностей см. в разделе Формы плагинов.
Doctor
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 не может сохранить проверенный снимок.
