---
read_when:
    - Зміна поведінки оновлення OpenClaw, doctor, перевірки прийнятності пакетів або встановлення плагінів
    - Підготовка або схвалення кандидата на випуск
    - Налагодження оновлення пакета, очищення залежностей Plugin або регресій встановлення Plugin
sidebarTitle: Update and plugin tests
summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення та оновлення плагінів
title: 'Тестування: оновлення та плагіни'
x-i18n:
    generated_at: "2026-07-12T13:21:38Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 4e930960b5819d2144467476cb473e62f236eca63e1d9941a6bc793b484e731c
    source_path: help/testing-updates-plugins.md
    workflow: 16
---

Контрольний список для перевірки оновлень і Plugin: доведіть, що пакет, який можна встановити, здатний
оновлювати реальний стан користувача, виправляти застарілий стан через `doctor` і надалі
встановлювати, завантажувати, оновлювати та видаляти плагіни з кожного підтримуваного джерела.

Загальну схему засобів запуску тестів див. у розділі [Тестування](/uk/help/testing). Відомості про ключі
активних провайдерів і набори тестів, що звертаються до мережі, див. у розділі [Тестування наживо](/uk/help/testing-live).

## Що ми захищаємо

- Архів пакета є повним, містить коректний `dist/postinstall-inventory.json`
  і не залежить від нерозпакованих файлів репозиторію.
- Користувач може перейти зі старішого опублікованого пакета на пакет-кандидат
  без втрати конфігурації, агентів, сеансів, робочих просторів, списків дозволених плагінів або
  конфігурації каналів.
- `openclaw doctor --fix --non-interactive` відповідає за очищення та виправлення
  застарілих станів. Під час запуску не повинні з’являтися приховані міграції сумісності для застарілого
  стану плагінів.
- Установлення плагінів працює з локальних каталогів, git-репозиторіїв, пакетів npm і через
  реєстр ClawHub.
- Залежності npm плагіна встановлюються в одному керованому проєкті npm для кожного плагіна,
  перевіряються до надання довіри та видаляються через `npm uninstall` під час
  видалення плагіна, щоб підняті залежності не залишалися.
- Оновлення плагіна не виконує жодних дій, якщо нічого не змінилося: записи про встановлення, визначене
  джерело, структура встановлених залежностей і стан увімкнення залишаються незмінними.

## Локальна перевірка під час розробки

Починайте з вузького набору:

```bash
pnpm changed:lanes --json
pnpm check:changed
pnpm test:changed
```

Для змін у встановленні чи видаленні плагінів, залежностях або інвентаризації пакета також
запускайте цільові тести, що охоплюють змінену межу:

```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
```

Перш ніж будь-який пакетний Docker-напрям використає архів, перевірте артефакт пакета:

```bash
pnpm release:check
```

`release:check` запускає перевірки розбіжностей конфігурації, документації та API (схему конфігурації, базову версію
документації конфігурації, базову версію API й експортів SDK плагінів, версії та інвентаризацію плагінів),
записує інвентаризацію дистрибутива пакета, запускає `npm pack --dry-run`, відхиляє заборонені
запаковані файли, встановлює архів у тимчасовий префікс, запускає postinstall і
виконує базову перевірку точок входу вбудованих каналів.

## Docker-напрями

Docker-напрями забезпечують перевірку на рівні продукту. Вони встановлюють або оновлюють справжній
пакет у контейнерах Linux і перевіряють поведінку за допомогою команд CLI,
запуску Gateway, HTTP-запитів, стану RPC і стану файлової системи.

Під час ітерацій використовуйте цільові напрями:

```bash
pnpm test:docker:plugins
pnpm test:docker:plugin-lifecycle-matrix
pnpm test:docker:plugin-update
pnpm test:docker:upgrade-survivor
pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-restart-auth
pnpm test:docker:update-migration
```

Важливі напрями:

- `test:docker:plugins` охоплює базову перевірку встановлення плагінів, установлення з локальних папок,
  поведінку пропуску оновлень локальних папок, локальні папки з попередньо встановленими
  залежностями, установлення пакетів `file:`, установлення з git із виконанням CLI, оновлення
  рухомих посилань git, установлення з реєстру npm із піднятими транзитивними
  залежностями, відсутність дій під час оновлення npm, відхилення некоректних метаданих пакетів npm,
  установлення з локальної тестової фікстури ClawHub і відсутність дій під час оновлення, поведінку оновлення каталогу,
  а також увімкнення й перевірку пакета Claude. Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб
  блок ClawHub залишався герметичним і автономним.
- `test:docker:plugin-lifecycle-matrix` встановлює пакет-кандидат у порожньому
  контейнері та проводить плагін npm через установлення, перевірку, вимкнення, увімкнення,
  явне оновлення, явне повернення до старішої версії та видалення після видалення коду
  плагіна. Для кожної фази він записує показники RSS і CPU.
- `test:docker:plugin-update` перевіряє, що незмінений установлений плагін не
  перевстановлюється й не втрачає метадані встановлення під час `openclaw plugins update`.
- `test:docker:upgrade-survivor` встановлює архів-кандидат поверх тестової фікстури зі
  забрудненим станом старого користувача, запускає оновлення пакета та неінтерактивний doctor, а потім запускає
  Gateway через local loopback і перевіряє збереження стану.
- `test:docker:published-upgrade-survivor` спочатку встановлює опубліковану базову версію,
  налаштовує її за допомогою вбудованого сценарію `openclaw config set`, оновлює її до
  архіву-кандидата, запускає doctor, перевіряє очищення застарілого стану, запускає Gateway і
  перевіряє `/healthz`, `/readyz` та стан RPC.
- `test:docker:update-restart-auth` встановлює пакет-кандидат, запускає
  керований Gateway з автентифікацією за токеном, скасовує змінну середовища автентифікації Gateway виклику для
  `openclaw update --yes --json` і вимагає, щоб команда оновлення кандидата
  перезапустила Gateway до виконання звичайних перевірок.
- `test:docker:update-migration` — це напрям оновлення опублікованої версії з інтенсивним очищенням. Він
  починає з налаштованого стану користувача в стилі Discord/Telegram, запускає doctor
  базової версії, щоб залежності налаштованих плагінів могли матеріалізуватися, створює
  застаріле сміття залежностей плагіна для налаштованого пакетного плагіна, оновлює до
  архіву-кандидата й вимагає, щоб doctor після оновлення видалив застарілі
  корені залежностей.

Корисні варіанти перевірки оновлення опублікованої версії:

```bash
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \
pnpm test:docker:published-upgrade-survivor

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \
OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \
pnpm test:docker:published-upgrade-survivor
```

Доступні сценарії: `base`, `acpx-openclaw-tools-bridge`, `feishu-channel`,
`bootstrap-persona`, `channel-post-core-restore`, `plugin-deps-cleanup`,
`configured-plugin-installs`, `stale-source-plugin-shadow`, `tilde-log-path`
і `versioned-runtime-deps`. У сукупних запусках `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`
(псевдонім `far-reaching`) розгортається в усі сценарії, включно з
міграцією встановлення налаштованих плагінів.

Повну міграцію оновлень навмисно відокремлено від повного CI випуску. Використовуйте
ручний робочий процес `Update Migration`, коли питання випуску звучить так: «Чи може кожен
опублікований стабільний випуск, починаючи з 2026.4.23, оновитися до цього кандидата й
очистити сміття залежностей плагінів?»:

```bash
gh workflow run update-migration.yml \
  --ref main \
  -f workflow_ref=main \
  -f package_ref=main \
  -f baselines=all-since-2026.4.23 \
  -f scenarios=plugin-deps-cleanup
```

## Приймання пакета

Приймання пакета — це вбудований у GitHub шлюз перевірки пакета. Він перетворює один пакет-кандидат
на архів `package-under-test`, записує версію та SHA-256, а потім
запускає повторно використовувані наскрізні Docker-напрями для цього конкретного архіву. Посилання на обв’язку робочого процесу
відокремлене від посилання на джерело пакета, тому поточна логіка тестування може перевіряти
старіші довірені випуски.

Джерела кандидатів:

- `source=npm`: перевіряє `openclaw@extended-stable`, `openclaw@beta`,
  `openclaw@latest` або точну опубліковану версію.
- `source=ref`: пакує довірену гілку, тег або коміт за допомогою вибраної поточної
  обв’язки.
- `source=url`: перевіряє загальнодоступний HTTPS-архів з обов’язковим `package_sha256`.
  Цей шлях відхиляє облікові дані в URL, нестандартні порти HTTPS, приватні або внутрішні
  імена хостів чи результати DNS/IP, IP-простір спеціального призначення та небезпечні перенаправлення.
- `source=trusted-url`: перевіряє HTTPS-архів з обов’язковими
  `package_sha256` і `trusted_source_id` за політикою, якою володіють супроводжувачі,
  у `.github/package-trusted-sources.json`. Використовуйте це для корпоративних або приватних
  дзеркал замість послаблення `source=url` перемикачем дозволу приватних джерел на рівні вхідних даних.
  Автентифікація Bearer, якщо її налаштовано політикою, використовує фіксований
  секрет `OPENCLAW_TRUSTED_PACKAGE_TOKEN`.
- `source=artifact`: повторно використовує архів, завантажений іншим запуском Actions.

Повна перевірка випуску за замовчуванням використовує `source=artifact`, зібраний із
визначеного SHA випуску. Для перевірки після публікації передайте
`package_acceptance_package_spec=openclaw@YYYY.M.PATCH`, щоб та сама матриця оновлень
перевіряла вже опублікований пакет npm.

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

```text
doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape
```

Коли ввімкнено тривалу перевірку випуску (примусово для `release_profile=stable` і
`full`), вони також передають:

```text
published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15
published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
```

Так міграція пакета, перемикання каналу оновлень, стійкість до пошкоджених керованих плагінів,
очищення застарілих залежностей плагінів, автономне покриття плагінів, поведінка
оновлення плагінів і перевірка якості пакета Telegram виконуються для одного й того самого визначеного артефакту без
необхідності перевіряти кожен опублікований випуск у стандартному шлюзі пакета випуску.

`last-stable-4` визначає чотири останні стабільні випуски OpenClaw,
опубліковані в npm. Приймання пакета випуску фіксує `2026.4.23` як першу межу
сумісності оновлення плагінів, `2026.5.2` як межу значних змін архітектури плагінів і
`2026.4.15` як старішу базову версію опублікованого оновлення з серії 2026.4.1x; засіб визначення
усуває дублікати фіксованих версій, які вже входять до останніх чотирьох. Для вичерпного покриття
міграції опублікованих оновлень використовуйте `all-since-2026.4.23` в окремому робочому процесі
міграції оновлень замість повного CI випуску. `release-history` залишається
доступним для ручної ширшої вибірки, коли також потрібна застаріла опорна версія
до цієї дати.

Коли вибрано кілька базових версій для перевірки оновлення опублікованих випусків, повторно використовуваний
робочий процес Docker розподіляє кожну базову версію в окреме цільове завдання виконавця. Кожна
частина базової версії й надалі запускає вибраний набір сценаріїв, але журнали й артефакти залишаються
окремими для кожної базової версії, а загальний час обмежується найповільнішою частиною замість одного великого
послідовного завдання.

Запускайте профіль пакета вручну під час перевірки кандидата перед випуском:

```bash
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=package \
  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \
  -f published_upgrade_survivor_scenarios=reported-issues \
  -f telegram_mode=mock-openai
```

Для опублікованого канаркового випуску з розширеною стабільністю встановіть
`package_spec=openclaw@extended-stable`. Приймання пакета перетворює цей
селектор на точний архів до запуску Docker-напрямів.

Використовуйте `suite_profile=product`, коли питання випуску охоплює канали MCP,
очищення cron/підагентів, вебпошук OpenAI або OpenWebUI. Використовуйте `suite_profile=full`
лише тоді, коли потрібне повне Docker-покриття шляхів випуску.

## Типовий процес випуску

Для кандидатів на випуск типовий набір перевірок такий:

1. `pnpm check:changed` і `pnpm test:changed` для регресій на рівні вихідного коду.
2. `pnpm release:check` для перевірки цілісності артефакту пакета.
3. Профіль `package` приймання пакета або спеціальні пакетні
   напрями перевірки випуску для контрактів установлення, оновлення, перезапуску та плагінів.
4. Міжплатформні перевірки випуску для специфічної для ОС поведінки інсталятора, початкового налаштування та платформи.
5. Набори тестів наживо лише тоді, коли змінена поверхня стосується поведінки провайдера або розміщеної
   служби.

На машинах супроводжувачів широкі шлюзи та перевірки продукту Docker/пакета мають виконуватися
в Testbox, якщо локальну перевірку не обрано явно.

## Сумісність із застарілими версіями

Послаблення вимог сумісності є вузьким і обмеженим у часі:

- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть допускати
  вже опубліковані прогалини в метаданих пакета під час приймання пакета.
- Опублікований пакет `2026.4.26` може попереджати про вже опубліковані локальні файли
  позначок метаданих збірки.
- Пізніші пакети мають відповідати сучасним контрактам. Ті самі прогалини призводять до
  помилки, а не до попередження чи пропуску.

Не додавайте нових міграцій під час запуску для цих старих форм. Додайте або розширте виправлення
doctor, а потім перевірте його за допомогою `upgrade-survivor`, `published-upgrade-survivor` або
`update-restart-auth`, якщо команда оновлення відповідає за перезапуск.

## Додавання покриття

Змінюючи поведінку оновлень або плагінів, додавайте покриття на найнижчому рівні, де
помилка може виникнути з правильної причини:

- Чиста логіка шляхів або метаданих: модульний тест поруч із вихідним кодом.
- Інвентаризація пакета або поведінка запакованих файлів: `package-dist-inventory` чи тест перевірки tarball.
- Поведінка встановлення/оновлення через CLI: перевірка в Docker-каналі або фікстура.
- Поведінка міграції опублікованого випуску: сценарій `published-upgrade-survivor`.
- Поведінка перезапуску, керованого оновленням: `update-restart-auth`.
- Поведінка джерела реєстру/пакета: фікстура `test:docker:plugins` або сервер фікстур ClawHub.
- Поведінка структури залежностей або очищення: перевіряйте як виконання під час роботи, так і межі файлової системи. Залежності npm можуть бути підняті всередині керованого npm-проєкту плагіна, тому тести мають доводити, що цей проєкт сканується/очищається, замість припущення, що існує лише локальне для пакета плагіна дерево `node_modules`.

За замовчуванням забезпечуйте герметичність нових Docker-фікстур. Використовуйте локальні реєстри фікстур і фіктивні пакети, якщо метою тесту не є поведінка реального реєстру.

## Аналіз причин збоїв

Починайте з ідентифікації артефакту:

- Зведення `resolve_package` для приймального тестування пакета: джерело, версія, SHA-256 і назва артефакту.
- Артефакти Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали каналів і команди повторного запуску.
- Зведення перевірки збереження працездатності після оновлення: `.artifacts/upgrade-survivor/summary.json`, включно з базовою версією, версією-кандидатом, сценарієм, тривалістю фаз і покриттям рецептів конфігурації.

Надавайте перевагу повторному запуску саме невдалого каналу з тим самим артефактом пакета, а не повторному запуску всього комплексу перевірок випуску.
