Розв’язання залежностей Plugin

OpenClaw обробляє залежності Plugin лише під час установлення або оновлення. Під час завантаження в середовищі виконання менеджер пакетів ніколи не запускається, дерево залежностей не відновлюється, а каталог пакета OpenClaw не змінюється.

Розподіл відповідальності

Пакети Plugin відповідають за власний граф залежностей:

• Залежності середовища виконання містяться в dependencies або optionalDependencies пакета Plugin.
• Імпорти SDK/ядра є peer-залежностями або імпортами, які надає OpenClaw.
• Плагіни для локальної розробки постачаються з уже встановленими залежностями.
• Плагіни npm і git установлюються в кореневі каталоги пакетів, якими керує OpenClaw.

OpenClaw відповідає лише за життєвий цикл Plugin:

• Виявлення джерела Plugin.
• Установлення або оновлення пакета за явним запитом.
• Запис метаданих установлення.
• Завантаження точки входу Plugin.
• Завершення з дієвою помилкою, якщо залежності відсутні.

Кореневі каталоги встановлення

OpenClaw використовує стабільні кореневі каталоги для кожного джерела:

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

Установлення npm виконується в кореневому каталозі відповідного проєкту Plugin:

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 для кожного Plugin із локальним tar-архівом npm-pack: OpenClaw читає метадані npm з tar-архіву, додає його до керованого проєкту як скопійовану залежність file:, виконує звичайне встановлення npm, наведене вище, а потім перевіряє метадані встановленого lock-файлу, перш ніж довіряти Plugin. Цей шлях призначений для перевірки прийнятності пакета та кандидата на випуск, коли локальний артефакт пакета має поводитися так само, як імітований ним артефакт реєстру.

Використовуйте npm-pack: під час тестування офіційних або зовнішніх пакетів Plugin перед публікацією. Установлення з необробленого архіву або шляху корисне для локального налагодження, але воно не перевіряє той самий шлях залежностей, що й установлений пакет npm або ClawHub. npm-pack: перевіряє структуру керованого встановлення пакета; саме по собі це не доводить, що Plugin є офіційним вмістом, пов’язаним із каталогом.

Якщо поведінка залежить від статусу вбудованого або довіреного офіційного Plugin, доповніть локальну перевірку пакета офіційним установленням із каталогу або шляхом опублікованого пакета, який фіксує офіційну довіру. Доступ до привілейованих допоміжних засобів і обробку області довіреного офіційного Plugin слід перевіряти через цей довірений шлях установлення, а не виводити з установлення локального tar-архіву.

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

npm може піднімати транзитивні залежності до каталогу node_modules проєкту відповідного Plugin поруч із пакетом Plugin. OpenClaw перевіряє кореневий каталог керованого проєкту, перш ніж довіряти встановленню, і видаляє цей проєкт під час видалення Plugin, тому підняті залежності середовища виконання залишаються в межах очищення цього Plugin.

Опубліковані пакети Plugin npm можуть містити npm-shrinkwrap.json; npm використовує цей придатний до публікації lock-файл під час установлення, а кореневий каталог керованого проєкту npm OpenClaw підтримує його через звичайний шлях установлення. Придатні до публікації пакети Plugin, якими володіє OpenClaw, мають містити локальний для пакета shrinkwrap, створений із графа опублікованих залежностей цього пакета:

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

Генератор видаляє devDependencies Plugin, застосовує політику перевизначень робочої області та записує extensions/<id>/npm-shrinkwrap.json для кожного Plugin із openclaw.release.publishToNpm: true. Сторонні пакети Plugin також можуть постачати 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"

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

Плагіни, які імпортують openclaw/plugin-sdk/*, оголошують openclaw як peer-залежність. OpenClaw не дозволяє npm установлювати окрему копію пакета хоста з реєстру в керований проєкт, оскільки застарілий пакет хоста може вплинути на розв’язання peer-залежностей npm усередині цього Plugin. Керовані встановлення npm пропускають розв’язання та матеріалізацію peer-залежностей npm, а після встановлення або оновлення OpenClaw повторно забезпечує локальні для Plugin посилання node_modules/openclaw для встановлених пакетів, що оголошують peer-залежність від хоста.

Під час установлення з git репозиторій клонується або оновлюється, після чого виконується:

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

Після цього встановлений Plugin завантажується з каталогу свого пакета, тому розв’язання локальних для пакета та батьківських каталогів node_modules працює так само, як для звичайного пакета Node.

Локальні плагіни

Локальні плагіни — це каталоги, якими керує розробник. OpenClaw ніколи не виконує для них npm install, pnpm install або відновлення залежностей; якщо локальний Plugin має залежності, установіть їх у цьому Plugin перед завантаженням.

Сторонні локальні плагіни TypeScript завантажуються через Jiti як аварійний шлях. Запаковані плагіни JavaScript і вбудовані внутрішні плагіни натомість завантажуються через нативні import/require.

Запуск і перезавантаження

Запуск Gateway і перезавантаження конфігурації ніколи не встановлюють залежності Plugin. Вони читають записи про встановлення Plugin, обчислюють точку входу та завантажують її.

Відсутня залежність під час виконання спричиняє помилку завантаження Plugin, яка вказує оператору явний спосіб виправлення:

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

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

Вбудовані плагіни

Легкі та критично важливі для ядра вбудовані плагіни постачаються як частина OpenClaw. Вони не повинні мати важкого дерева залежностей середовища виконання; інакше їх слід винести в завантажуваний пакет на ClawHub/npm.

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

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

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

Очищення застарілого стану

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

Старіші встановлення npm також використовували спільний кореневий каталог ~/.openclaw/npm/node_modules. Поточні процеси встановлення, оновлення, видалення та doctor усе ще розпізнають цей застарілий плаский кореневий каталог лише для відновлення й очищення. Нові встановлення npm натомість створюють окремі кореневі каталоги проєктів для кожного Plugin.