--- read_when: - Ви налагоджуєте встановлення пакетів плагінів - Ви змінюєте поведінку запуску плагіна, doctor або встановлення через менеджер пакетів - Ви супроводжуєте пакетні інсталяції OpenClaw або маніфести вбудованих плагінів sidebarTitle: Dependencies summary: Як OpenClaw встановлює пакети плагінів і розв’язує залежності плагінів title: Розв’язання залежностей Plugin x-i18n: generated_at: "2026-07-12T13:31:28Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: ae24a82568e275399cb7b68729d2805956792852612f84d6918850305f0eb243 source_path: plugins/dependency-resolution.md workflow: 16 --- OpenClaw обробляє залежності Plugin лише під час установлення або оновлення. Під час завантаження в середовищі виконання менеджер пакетів ніколи не запускається, дерево залежностей не відновлюється, а каталог пакета OpenClaw не змінюється. ## Розподіл відповідальності Пакети Plugin відповідають за власний граф залежностей: - Залежності середовища виконання містяться в `dependencies` або `optionalDependencies` пакета Plugin. - Імпорти SDK/ядра є peer-залежностями або імпортами, які надає OpenClaw. - Плагіни для локальної розробки постачаються з уже встановленими залежностями. - Плагіни npm і git установлюються в кореневі каталоги пакетів, якими керує OpenClaw. OpenClaw відповідає лише за життєвий цикл Plugin: - Виявлення джерела Plugin. - Установлення або оновлення пакета за явним запитом. - Запис метаданих установлення. - Завантаження точки входу Plugin. - Завершення з дієвою помилкою, якщо залежності відсутні. ## Кореневі каталоги встановлення OpenClaw використовує стабільні кореневі каталоги для кожного джерела: - Пакети npm установлюються в окремі проєкти для кожного Plugin у `~/.openclaw/npm/projects/`. - Пакети git клонуються в `~/.openclaw/git`. - Локальні встановлення, а також установлення зі шляху чи архіву копіюються або підключаються без відновлення залежностей. Установлення npm виконується в кореневому каталозі відповідного проєкту Plugin: ```bash cd ~/.openclaw/npm/projects/ npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund ``` `openclaw plugins install npm-pack:` використовує той самий кореневий каталог проєкту 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/` може тимчасово розблокувати діагностику, але не є доказом прийнятності пакета, оскільки наступне встановлення або оновлення повторно створить проєкт із метаданих пакета. npm може піднімати транзитивні залежності до каталогу `node_modules` проєкту відповідного Plugin поруч із пакетом Plugin. OpenClaw перевіряє кореневий каталог керованого проєкту, перш ніж довіряти встановленню, і видаляє цей проєкт під час видалення Plugin, тому підняті залежності середовища виконання залишаються в межах очищення цього Plugin. Опубліковані пакети Plugin npm можуть містити `npm-shrinkwrap.json`; npm використовує цей придатний до публікації lock-файл під час установлення, а кореневий каталог керованого проєкту npm OpenClaw підтримує його через звичайний шлях установлення. Придатні до публікації пакети Plugin, якими володіє OpenClaw, мають містити локальний для пакета shrinkwrap, створений із графа опублікованих залежностей цього пакета: ```bash pnpm deps:shrinkwrap:generate pnpm deps:shrinkwrap:check ``` Генератор видаляє `devDependencies` Plugin, застосовує політику перевизначень робочої області та записує `extensions//npm-shrinkwrap.json` для кожного Plugin із `openclaw.release.publishToNpm: true`. Сторонні пакети Plugin також можуть постачати shrinkwrap; OpenClaw не вимагає його для пакетів спільноти, але npm враховує його за наявності. Перш ніж вважати локальний пакет доказом готовності кандидата на випуск, перевірте tar-архів, який буде встановлено: ```bash npm pack --pack-destination /tmp tar -xOf /tmp/.tgz package/package.json tar -tf /tmp/.tgz | grep '^package/dist/' ``` У разі змін залежностей також переконайтеся, що виробниче встановлення може розв’язати пакети середовища виконання без залежностей розробки: ```bash 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/.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 репозиторій клонується або оновлюється, після чого виконується: ```bash 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, яка вказує оператору явний спосіб виправлення: ```bash openclaw plugins update openclaw plugins install openclaw doctor --fix ``` `doctor --fix` очищує застарілий стан залежностей, створений OpenClaw, і може відновлювати завантажувані плагіни, відсутні в локальних записах установлення, якщо конфігурація досі посилається на них. Doctor не відновлює залежності вже встановленого локального Plugin. ## Вбудовані плагіни Легкі та критично важливі для ядра вбудовані плагіни постачаються як частина OpenClaw. Вони не повинні мати важкого дерева залежностей середовища виконання; інакше їх слід винести в завантажуваний пакет на ClawHub/npm. Поточний згенерований список плагінів, які постачаються в пакеті ядра, встановлюються зовнішньо або залишаються доступними лише як вихідний код, див. у розділі [Перелік Plugin](/uk/plugins/plugin-inventory). Маніфести вбудованих Plugin не повинні запитувати підготовку залежностей. Велику або необов’язкову функціональність Plugin слід пакувати як звичайний Plugin і встановлювати через той самий шлях npm/git/ClawHub, що й сторонні плагіни. У робочих копіях вихідного коду OpenClaw розглядає репозиторій як монорепозиторій pnpm. Після `pnpm install` вбудовані плагіни завантажуються з `extensions/`, тому локальні для пакетів залежності робочої області доступні, а зміни підхоплюються безпосередньо. Розробка в робочій копії вихідного коду підтримує лише pnpm; звичайна команда `npm install` у корені репозиторію не готує залежності вбудованих Plugin. | Структура встановлення | Розташування вбудованого Plugin | Власник залежностей | | --------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------- | | `npm install -g openclaw` | Побудоване дерево виконання всередині пакета | Пакет OpenClaw і явні процеси встановлення, оновлення та doctor для Plugin | | Робоча копія Git плюс `pnpm install` | Пакети робочої області `extensions/` | Робоча область pnpm, включно з власними залежностями кожного пакета Plugin | | `openclaw plugins install ...` | Керований проєкт npm або корінь git/ClawHub | Процес установлення та оновлення 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.