Skip to main content
Контрольный список для проверки обновления и плагинов: докажите, что устанавливаемый пакет может обновлять реальное состояние пользователя, исправлять устаревшее состояние прежних версий с помощью doctor и при этом устанавливать, загружать, обновлять и удалять плагины из всех поддерживаемых источников. Общую карту средств запуска тестов см. в разделе Тестирование. Сведения о ключах рабочих провайдеров и наборах тестов, использующих сеть, см. в разделе Тестирование в рабочей среде.

​
Что мы защищаем

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

​
Локальная проверка во время разработки

Начинайте с узкой области:
При изменениях установки, удаления, зависимостей или инвентаризации пакетов плагинов также запускайте целевые тесты, покрывающие изменённый стык:
Прежде чем какой-либо Docker-контур пакета начнёт использовать архив, проверьте артефакт пакета:
release:check выполняет проверки расхождений конфигурации, документации и API (схема конфигурации, базовый уровень документации конфигурации, базовый уровень API и экспорта SDK плагинов, версии и инвентаризация плагинов), записывает инвентаризацию дистрибутива пакета, запускает npm pack --dry-run, отклоняет запрещённые упакованные файлы, устанавливает архив во временный префикс, выполняет postinstall и проверяет точки входа встроенных каналов.

​
Docker-контуры

Docker-контуры обеспечивают проверку на уровне продукта. Они устанавливают или обновляют реальный пакет внутри контейнеров Linux и проверяют поведение с помощью команд CLI, запуска Gateway, HTTP-запросов, состояния RPC и состояния файловой системы. Во время итераций используйте целевые контуры:
Важные контуры:
  • 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 устанавливает архив-кандидат поверх загрязнённого тестового состояния старого пользователя, выполняет обновление пакета и неинтерактивную диагностику, затем запускает Gateway с обратной петлёй и проверяет сохранность состояния.
  • test:docker:published-upgrade-survivor сначала устанавливает опубликованную базовую версию, настраивает её с помощью встроенного рецепта openclaw config set, обновляет до архива-кандидата, запускает диагностику, проверяет очистку устаревшего состояния, запускает Gateway и проверяет /healthz, /readyz и состояние RPC.
  • test:docker:update-restart-auth устанавливает пакет-кандидат, запускает управляемый Gateway с аутентификацией по токену, удаляет переменные среды аутентификации Gateway вызывающей стороны для openclaw update --yes --json и требует, чтобы команда обновления пакета-кандидата перезапустила Gateway перед обычными проверками.
  • test:docker:update-migration — контур обновления опубликованной версии с упором на очистку. Он начинает с настроенного пользовательского состояния в стиле Discord/Telegram, запускает диагностику базовой версии, чтобы зависимости настроенных плагинов могли материализоваться, добавляет устаревшие остатки зависимостей плагина для настроенного упакованного плагина, обновляется до архива-кандидата и требует, чтобы диагностика после обновления удалила устаревшие корневые каталоги зависимостей.
Полезные варианты проверки сохранности при обновлении опубликованной версии:
Доступные сценарии: 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 обновиться до этого кандидата и очистить остатки зависимостей плагинов?»:

​
Приёмка пакета

Приёмка пакета — это встроенный в GitHub шлюз проверки пакета. Он преобразует один пакет-кандидат в архив package-under-test, записывает версию и SHA-256, а затем запускает повторно используемые Docker-контуры E2E для этого конкретного архива. Ссылка на среду процесса отделена от ссылки на источник пакета, поэтому текущая логика тестирования может проверять старые доверенные выпуски. Источники кандидатов:
  • 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. Проверки выпуска вызывают приёмку пакета с набором тестов пакета, обновления, перезапуска и плагинов:
Когда включена длительная проверка выпуска (принудительно для release_profile=stable и full), также передаются:
Это позволяет проверять миграцию пакета, переключение канала обновлений, устойчивость к повреждённым управляемым плагинам, очистку устаревших зависимостей плагинов, автономную проверку плагинов, поведение обновления плагинов и контроль качества пакета 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-процесс распределяет каждую базовую версию в отдельное целевое задание средства запуска. Каждый сегмент базовой версии по-прежнему выполняет выбранный набор сценариев, но журналы и артефакты остаются разделёнными по базовым версиям, а общее время ограничивается самым медленным сегментом вместо одного большого последовательного задания. При проверке кандидата перед выпуском запустите профиль пакета вручную:
Для опубликованной канареечной версии с расширенной стабильностью задайте 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 может выдавать предупреждения для уже выпущенных файлов меток метаданных локальной сборки.
  • Более поздние пакеты должны соответствовать современным контрактам. Те же пробелы приводят к ошибке, а не к предупреждению или пропуску.
Не добавляйте новые миграции при запуске для этих старых форматов. Добавьте или расширьте исправление в диагностике, а затем проверьте его с помощью 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-фикстуры герметичными. Используйте локальные реестры фикстур и фиктивные пакеты, если только целью теста не является проверка поведения реального реестра.

​
Разбор сбоев

Начните с идентификации артефакта:
  • Сводка Package Acceptance resolve_package: источник, версия, SHA-256 и имя артефакта.
  • Артефакты Docker: .artifacts/docker-tests/**/summary.json, failures.json, журналы сценария и команды повторного запуска.
  • Сводка сохранности после обновления: .artifacts/upgrade-survivor/summary.json, включая исходную версию, версию-кандидат, сценарий, длительность этапов и покрытие рецептов конфигурации.
Предпочитайте повторный запуск конкретного завершившегося сбоем сценария с тем же артефактом пакета повторному запуску всего набора проверок выпуска.