Разрешение зависимостей плагина

OpenClaw обрабатывает зависимости плагинов только во время установки или обновления. Во время выполнения загрузка никогда не запускает менеджер пакетов, не восстанавливает дерево зависимостей и не изменяет каталог пакета OpenClaw.

Разделение ответственности

Пакеты плагинов отвечают за собственный граф зависимостей:

• Зависимости среды выполнения указываются в dependencies или optionalDependencies пакета плагина.
• Импорты SDK и ядра являются одноранговыми зависимостями или предоставляемыми импортами OpenClaw.
• Локальные плагины для разработки предоставляют собственные уже установленные зависимости.
• Плагины npm и git устанавливаются в корневые каталоги пакетов, которыми управляет OpenClaw.

OpenClaw отвечает только за жизненный цикл плагина:

• Обнаружение источника плагина.
• Установка или обновление пакета по явному запросу.
• Запись метаданных установки.
• Загрузка точки входа плагина.
• Завершение с ошибкой, содержащей конкретные инструкции, если зависимости отсутствуют.

Корневые каталоги установки

OpenClaw использует стабильные корневые каталоги для каждого источника:

• Пакеты npm устанавливаются в отдельные проекты для каждого плагина в ~/.openclaw/npm/projects/<encoded-package>.
• Репозитории пакетов git клонируются в ~/.openclaw/git.
• Локальные установки, установки из пути или архива копируются либо подключаются по ссылке без восстановления зависимостей.

Установка npm выполняется в этом корневом каталоге отдельного проекта плагина с помощью:

cd ~/.openclaw/npm/projects/<encoded-package>npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

openclaw plugins install npm-pack:<path.tgz> использует тот же корневой каталог проекта npm для отдельного плагина с локальным tar-архивом npm-pack: OpenClaw считывает метаданные npm из tar-архива, добавляет его в управляемый проект как скопированную зависимость file:, выполняет указанную выше обычную установку npm, а затем проверяет метаданные установленного файла блокировки, прежде чем считать плагин доверенным. Этот путь предназначен для проверки приёмки пакета и релиз-кандидата, когда локальный упакованный артефакт должен вести себя так же, как имитируемый им артефакт из реестра.

Используйте npm-pack: при тестировании официальных или внешних пакетов плагинов перед публикацией. Установка непосредственно из архива или пути полезна для локальной отладки, но она не подтверждает тот же путь зависимостей, что и установленный пакет npm или ClawHub. npm-pack: подтверждает форму установки управляемого пакета; само по себе это не доказывает, что плагин является официальным содержимым, связанным с каталогом.

Если поведение зависит от статуса встроенного или доверенного официального плагина, дополняйте проверку локального пакета официальной установкой на основе каталога либо путём опубликованного пакета, который фиксирует официальный статус доверия. Доступ к привилегированным вспомогательным средствам и обработку области доверенных официальных плагинов следует проверять через этот доверенный путь установки, а не выводить из установки локального tar-архива.

Если во время выполнения плагин завершается с ошибкой из-за отсутствующего импорта, исправьте манифест пакета, а не восстанавливайте управляемый проект вручную. Импорты среды выполнения должны находиться в dependencies или optionalDependencies пакета плагина; devDependencies не устанавливаются для управляемых проектов среды выполнения. Локальный npm install внутри ~/.openclaw/npm/projects/<encoded-package> может временно разблокировать диагностику, но не служит доказательством приёмки пакета, поскольку при следующей установке или обновлении проект будет заново создан из метаданных пакета.

npm может поднять транзитивные зависимости в node_modules проекта отдельного плагина рядом с пакетом плагина. OpenClaw сканирует корневой каталог управляемого проекта, прежде чем считать установку доверенной, и удаляет этот проект при удалении плагина, поэтому поднятые зависимости среды выполнения остаются в пределах области очистки этого плагина.

Опубликованные пакеты плагинов npm могут включать npm-shrinkwrap.json; npm использует этот публикуемый файл блокировки во время установки, а управляемый OpenClaw корневой каталог проекта npm поддерживает его через обычный путь установки. Принадлежащие OpenClaw публикуемые пакеты плагинов должны содержать локальный для пакета shrinkwrap, созданный из опубликованного графа зависимостей этого пакета:

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

Генератор удаляет devDependencies плагина, применяет политику переопределений рабочей области и записывает extensions/<id>/npm-shrinkwrap.json для каждого плагина с openclaw.release.publishToNpm: true. Пакеты сторонних плагинов также могут включать shrinkwrap; OpenClaw не требует его для пакетов сообщества, но npm учитывает его при наличии.

Прежде чем считать локальный пакет доказательством готовности релиз-кандидата, проверьте tar-архив, который будет установлен:

npm pack --pack-destination /tmptar -xOf /tmp/<plugin-package>.tgz package/package.jsontar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

При изменениях зависимостей также убедитесь, что производственная установка может разрешить пакеты среды выполнения без зависимостей разработки:

tmpdir=$(mktemp -d)(  cd "$tmpdir"  npm init -y >/dev/null  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz)rm -rf "$tmpdir"

Принадлежащие OpenClaw пакеты плагинов npm также могут публиковаться с явным bundledDependencies. Путь публикации npm накладывает список имён зависимостей среды выполнения, удаляет из публикуемого манифеста метаданные рабочей области, предназначенные только для разработки, выполняет установку npm без скриптов для локальных зависимостей среды выполнения пакета, а затем упаковывает или публикует tar-архив плагина с включёнными файлами этих зависимостей. Пакеты с большим количеством нативных компонентов (Codex, ACPX, Copilot, llama.cpp, memory-lancedb, Tlon) отключают это с помощью openclaw.release.bundleRuntimeDependencies: false; они по-прежнему включают shrinkwrap, но npm разрешает зависимости среды выполнения во время установки вместо встраивания всех платформенных двоичных файлов в tar-архив плагина. Корневой пакет openclaw не включает полное дерево своих зависимостей.

Плагины, импортирующие openclaw/plugin-sdk/*, объявляют openclaw одноранговой зависимостью. OpenClaw не позволяет npm устанавливать отдельную копию пакета хоста из реестра в управляемый проект, поскольку устаревший пакет хоста может повлиять на разрешение одноранговых зависимостей npm внутри этого плагина. При управляемых установках npm разрешение и материализация одноранговых зависимостей npm пропускаются, а OpenClaw повторно устанавливает локальные для плагина ссылки node_modules/openclaw для установленных пакетов, объявляющих одноранговую зависимость от хоста, после установки или обновления.

При установке из git репозиторий клонируется или обновляется, после чего выполняется:

npm install --omit=dev --ignore-scripts --no-audit --no-fund

Затем установленный плагин загружается из каталога этого пакета, поэтому разрешение локального и родительского node_modules работает так же, как для обычного пакета Node.

Локальные плагины

Локальные плагины — это каталоги, которыми управляет разработчик. OpenClaw никогда не выполняет для них npm install, pnpm install или восстановление зависимостей; если у локального плагина есть зависимости, установите их в этом плагине перед загрузкой.

Локальные сторонние плагины TypeScript загружаются через Jiti как резервный аварийный путь. Упакованные плагины JavaScript и встроенные внутренние плагины загружаются через нативный import/require.

Запуск и перезагрузка

Запуск Gateway и перезагрузка конфигурации никогда не устанавливают зависимости плагинов. Они считывают записи об установке плагинов, вычисляют точку входа и загружают её.

Отсутствующая зависимость во время выполнения приводит к ошибке загрузки плагина, которая указывает оператору явный способ исправления:

openclaw plugins update <id>openclaw plugins install <source>openclaw doctor --fix

doctor --fix очищает устаревшее состояние зависимостей, созданное OpenClaw, и может восстановить загружаемые плагины, отсутствующие в локальных записях об установке, если конфигурация по-прежнему ссылается на них. Doctor не восстанавливает зависимости уже установленного локального плагина.

Встроенные плагины

Легковесные и критически важные для ядра встроенные плагины поставляются как часть OpenClaw. Они либо не должны иметь тяжёлого дерева зависимостей среды выполнения, либо должны быть вынесены в загружаемый пакет в ClawHub/npm.

Актуальный сгенерированный список плагинов, которые поставляются в составе пакета ядра, устанавливаются извне или остаются доступными только в исходном коде, см. в разделе Перечень плагинов.

Манифесты встроенных плагинов не должны запрашивать подготовку зависимостей. Крупную или необязательную функциональность плагина следует оформлять как обычный плагин и устанавливать тем же путём npm/git/ClawHub, что и сторонние плагины.

В рабочих копиях исходного кода OpenClaw обрабатывает репозиторий как монорепозиторий pnpm. После pnpm install встроенные плагины загружаются из extensions/<id>, поэтому локальные зависимости пакетов рабочей области доступны, а изменения подхватываются непосредственно. Разработка в рабочей копии исходного кода поддерживает только pnpm; обычный npm install в корне репозитория не подготавливает зависимости встроенных плагинов.

Очистка устаревших данных

Предыдущие версии OpenClaw создавали корневые каталоги зависимостей встроенных плагинов при запуске или во время восстановления с помощью doctor. Текущая очистка doctor удаляет эти устаревшие каталоги и символические ссылки с помощью --fix, включая старые корневые каталоги plugin-runtime-deps, символические ссылки пакетов из глобального префикса Node, указывающие на удалённые цели plugin-runtime-deps, манифесты .openclaw-runtime-deps*, созданные node_modules плагинов, промежуточные каталоги установки и локальные для пакета хранилища pnpm. Процесс postinstall упакованной версии также удаляет эти глобальные символические ссылки перед очисткой устаревших корневых каталогов назначения, чтобы после обновления не оставались неработающие импорты пакетов ESM.

В предыдущих установках npm также использовался общий корневой каталог ~/.openclaw/npm/node_modules. Текущие процессы установки, обновления, удаления и doctor по-прежнему распознают этот устаревший плоский корневой каталог только для восстановления и очистки. Новые установки npm создают отдельные корневые каталоги проектов для каждого плагина.