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

OpenClaw тримає роботу із залежностями plugin на етапі встановлення/оновлення. Завантаження під час виконання не запускає менеджери пакетів, не відновлює дерева залежностей і не змінює каталог пакетів OpenClaw.

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

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

• залежності часу виконання містяться в dependencies або optionalDependencies пакета plugin
• імпорти SDK/core є peer-залежностями або імпортами, наданими OpenClaw
• локальні plugin для розробки постачають власні вже встановлені залежності
• npm- і git-plugin встановлюються в корені пакетів, якими керує OpenClaw

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

• виявити джерело plugin
• встановити або оновити пакет за явним запитом
• записати метадані встановлення
• завантажити точку входу plugin
• завершитися з придатною до дії помилкою, коли залежностей бракує

# Корені встановлення

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

• npm-пакети встановлюються в ~/.openclaw/npm
• git-пакети клонуються в ~/.openclaw/git
• локальні/path/archive встановлення копіюються або посилаються без відновлення залежностей

npm-встановлення виконуються в npm-корені з:

npm install --prefix ~/.openclaw/npm <spec> --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

openclaw plugins install npm-pack:<path.tgz> використовує той самий керований npm-корінь для локального tarball npm-pack. OpenClaw читає npm-метадані tarball, додає його до керованого кореня як скопійовану залежність file:, запускає звичайне npm-встановлення, а потім перевіряє метадані встановленого lockfile, перш ніж довіряти plugin. Це призначено для підтвердження приймання пакета та release-candidate, коли локальний pack-артефакт має поводитися як артефакт реєстру, який він імітує.

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

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

git-встановлення клонують або оновлюють репозиторій, а потім запускають:

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

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

# Локальні plugin

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

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

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

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

Якщо залежність відсутня під час виконання, plugin не завантажується, а помилка має вказати оператору явне виправлення:

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

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

# Вбудовані plugin

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

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

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

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

Форма встановлення	Розташування вбудованого plugin	Власник залежностей
npm install -g openclaw	Зібране дерево runtime всередині пакета	Пакет OpenClaw і явні потоки встановлення/оновлення/doctor для plugin
Git checkout плюс pnpm install	Workspace-пакети extensions/<id>	pnpm workspace, включно з власними залежностями кожного пакета plugin
openclaw plugins install ...	Керований корінь plugin npm/git/ClawHub	Потік встановлення/оновлення plugin

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

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

Ці шляхи є лише застарілими залишками. Нові встановлення не повинні їх створювати.