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 "Котировки акций"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" --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 <package> # автоматическое определение источникаopenclaw plugins install clawhub:<package> # только ClawHubopenclaw plugins install npm:<package> # только npmopenclaw plugins install npm-pack:<path.tgz> # локальный tarball 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 или артефакта 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 отклоняются. Для безопасности зависимости устанавливаются в отдельном управляемом проекте 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 не поддерживается с --force (связанные плагины указывают непосредственно на исходный
путь, поэтому перезаписывать на месте нечего), при установках --marketplace или
git:, а также требует уже существующий локальный путь.
Список
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 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. Если бета-выпуск плагина отсутствует, используется записанная стандартная спецификация или 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 не может сохранить проверенный снимок.
