Skip to main content

​
Настройки агента по умолчанию

В сеансах агента один или несколько целевых тестов и недорогие статические проверки выполняются локально только для доверенного исходного кода и при наличии готовых установленных зависимостей. Никогда не выполняйте локально инструменты из недоверенного репозитория. Более крупные наборы тестов, изменённые проверки с параллельным выполнением проверки типов и линтинга, сборки, Docker, проверки пакетов, E2E, проверка в реальной среде и кроссплатформенная проверка выполняются удалённо через Crabbox. Для ресурсоёмкой проверки доверенного кода сопровождающими по умолчанию используется Blacksmith Testbox. Настроенный рабочий процесс Testbox загружает учётные данные, поэтому для недоверенного кода участника или форка необходимо вместо него использовать CI форка без секретов или санитизированный прямой AWS Crabbox. Не выполняйте предварительный прогрев для предполагаемой работы. Получайте серверную среду по требованию, когда будет готова первая ресурсоёмкая команда, повторно используйте возвращённый идентификатор tbx_... для последующих ресурсоёмких команд, синхронизируйте текущую рабочую копию при каждом запуске и останавливайте среду перед передачей работы. После первого успешного повторного использования обёртка записывает базовый коммит аренды, отпечатки зависимостей и рабочего процесса Testbox в .crabbox/testbox-leases/. При изменениях только исходного кода прогретая среда продолжает использоваться повторно. Изменение базы слияния, файла блокировки, входных данных менеджера пакетов, обёртки или рабочего процесса Testbox приводит к безопасному отказу и требует новой аренды. При каждом запуске текущая рабочая копия по-прежнему синхронизируется. OPENCLAW_TESTBOX_ALLOW_STALE=1 предназначен только для целевой диагностики, а не для проверки релиза. Приведённые ниже команды локального тестирования предназначены для рабочих процессов, выполняемых людьми, и ограниченной проверки агентом. О недоступности удалённого провайдера необходимо сообщить; она не является разрешением незаметно выполнить локально комплексную проверку. Для ресурсоёмкой проверки недоверенного кода выполняйте прогрев по требованию с помощью --provider aws. При каждом запуске необходимо задавать CRABBOX_ENV_ALLOW=CI, передавать --provider aws --no-hydrate и использовать новый временный удалённый HOME перед установкой зависимостей или запуском тестов. Используйте новую прогретую аренду, выделенную для этого недоверенного исходного кода; никогда не используйте повторно доверенную или ранее загруженную учётными данными аренду. Запускайте установленный доверенный исполняемый файл Crabbox из чистой доверенной рабочей копии main и получайте только удалённый PR с помощью --fresh-pr; никогда не выполняйте локально обёртку или конфигурацию из недоверенной рабочей копии. Отмените установку CRABBOX_AWS_INSTANCE_PROFILE и выполняйте безопасный отказ, если разрешённое значение aws.instanceProfile не пусто. Перед любой установкой или тестированием используйте доверенные инструменты с абсолютными путями, чтобы потребовать токен IMDSv2, подтвердить, что конечная точка учётных данных IAM возвращает 404, и проверить, что удалённое значение git rev-parse HEAD равно полному проверенному SHA головного коммита PR. Привяжите аренду к этому SHA и останавливайте или прогревайте её заново при изменении головного коммита. Загрузите доверенный scripts/crabbox-untrusted-bootstrap.sh из чистого main вместе с --fresh-pr; он устанавливает закреплённые версии Node и pnpm, проверяет SHA и закреплённую версию менеджера пакетов, изолирует HOME, устанавливает зависимости, а затем выполняет запрошенный тест. Если брокер не может подтвердить отсутствие роли или удалённого PR, используйте CI форка без секретов. Не используйте hydrate-github, --no-sync или рабочий процесс Testbox с загруженными учётными данными. Отмените все переопределения CRABBOX_TAILSCALE*, принудительно задайте --network public --tailscale=false, сбросьте флаги выходного узла/LAN и потребуйте, чтобы crabbox inspect сообщал об использовании общедоступной сети без состояния Tailscale перед загрузкой любого скрипта.

​
Обычный порядок локального выполнения

  1. pnpm test:changed для проверки Vitest в области изменений.
  2. pnpm test <path-or-filter> для одного файла, каталога или явно указанной цели.
  3. pnpm test только когда намеренно требуется полный локальный набор тестов Vitest.
В рабочем дереве Codex или связанном/разреженном рабочем дереве агенты избегают прямого локального запуска pnpm test* / pnpm check* / pnpm crabbox:run:
  • Ограниченная целевая проверка при наличии готовых зависимостей: node scripts/run-vitest.mjs <path-or-filter>.
  • Проверка изменений с предварительной классификацией: node scripts/check-changed.mjs; планы только с документацией, без изменений и с небольшими изменениями метаданных выполняются локально при наличии готовых зависимостей, а ресурсоёмкие планы или планы с отсутствующими зависимостями делегируются Testbox.
  • Явно заданная широкая проверка с сохранением аренды: node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed, чтобы pnpm выполнялся внутри Testbox.
  • Итоговые exitCode оболочки и JSON с временными показателями являются результатом команды. Делегированный запуск Blacksmith GitHub Actions может показывать cancelled после успешного выполнения команды SSH, поскольку Testbox останавливается извне действия поддержания активности; прежде чем считать это сбоем, проверьте сводку оболочки и вывод команды.
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: сохраняет сериализацию ресурсоёмких проверок внутри текущего рабочего дерева, а не в общем каталоге Git, для таких команд, как pnpm check:changed и целевая pnpm test .... Используйте это только на высокопроизводительных локальных хостах при намеренном параллельном запуске независимых проверок в связанных рабочих деревьях.

​
Основные команды

Запуски оболочки тестов завершаются краткой сводкой [test] passed|failed|skipped ... in ...; собственная строка Vitest с длительностью остаётся детализацией по сегментам.

​
Общее состояние тестов и вспомогательные средства для процессов

  • src/test-utils/openclaw-test-state.ts: используйте из Vitest, когда тесту требуется изолированный HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, тестовая конфигурация, рабочее пространство, каталог агента или хранилище профилей аутентификации.
  • pnpm test:env-mutations:report: неблокирующий отчёт о тестах и тестовой инфраструктуре, которые напрямую изменяют HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR или связанные переменные среды. Используйте его для поиска кандидатов на миграцию к общему вспомогательному средству состояния тестов.
  • test/helpers/openclaw-test-instance.ts: для тестов E2E на уровне процессов, которым в одном месте требуются работающий Gateway, среда CLI, сбор журналов и очистка.
  • Потоки E2E для Docker/Bash, подключающие scripts/lib/docker-e2e-image.sh, могут передавать docker_e2e_test_state_shell_b64 <label> <scenario> в контейнер и декодировать его с помощью scripts/lib/openclaw-e2e-instance.sh; сценарии с несколькими домашними каталогами могут передавать docker_e2e_test_state_function_b64 и вызывать openclaw_test_state_create <label> <scenario> в каждом потоке. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json записывает файл переменных среды хоста, пригодный для подключения (конструкция -- перед create не позволяет более новым средам выполнения Node интерпретировать --env-file как флаг Node). Потоки, запускающие Gateway, могут подключать scripts/lib/openclaw-e2e-instance.sh для разрешения точки входа, запуска имитации OpenAI, запуска в основном/фоновом режиме, проверок готовности, экспорта переменных среды состояния, выгрузки журналов и очистки процессов.

​
Потоки Control UI, TUI и расширений

  • E2E с имитацией Control UI: pnpm test:ui:e2e запускает связку Vitest + Playwright, которая поднимает Control UI в Vite и управляет реальной страницей Chromium, подключённой к имитируемому WebSocket Gateway. Тесты находятся в ui/src/**/*.e2e.test.ts; общие имитации и элементы управления — в ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e включает эту связку. Запуски агентом по умолчанию выполняются в Testbox/Crabbox, включая целевую проверку; используйте node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts только как явно выбранный локальный резервный вариант.
  • PTY-тесты TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts запускает быструю PTY-связку с имитируемым бэкендом. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 или pnpm tui:pty:test:watch --mode local запускает более медленную дымовую проверку tui --local, которая имитирует только внешнюю конечную точку модели. Проверяйте стабильный видимый текст или вызовы фикстур, а не необработанные снимки ANSI.
  • pnpm test:extensions и pnpm test extensions запускают все шарды расширений/плагинов. Ресурсоёмкие плагины каналов, браузерный плагин и OpenAI запускаются как отдельные шарды; остальные группы плагинов остаются объединёнными. pnpm test extensions/<id> запускает одну связку встроенного плагина.
  • Исходные файлы с соседними тестами сначала сопоставляются с этим соседним тестом, и только затем используются более широкие шаблоны каталогов. При изменении вспомогательных файлов в src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers и src/plugins/contracts локальный граф импортов позволяет запускать импортирующие их тесты вместо широкого запуска всех шардов, когда путь зависимости определён точно.
  • Целевые каталоги контрактов распределяются по соответствующим связкам контрактов: pnpm test src/channels/plugins/contracts запускает четыре конфигурации контрактов каналов, а pnpm test src/plugins/contracts — конфигурацию контрактов плагинов, поскольку универсальные проекты channels/plugins исключают contracts/**.
  • auto-reply разделяется на три отдельные конфигурации (core, top-level, reply), чтобы инфраструктура ответов не преобладала над более лёгкими высокоуровневыми тестами состояния, токенов и вспомогательных средств.
  • Выбранные тестовые файлы plugin-sdk и commands направляются через отдельные облегчённые связки, в которых остаётся только test/setup.ts, а ресурсоёмкие сценарии среды выполнения продолжают выполняться в существующих связках.
  • Базовая конфигурация Vitest по умолчанию использует pool: "threads" и isolate: false, а общий неизолированный исполнитель включён во всех конфигурациях репозитория.
  • pnpm test:channels запускает vitest.channels.config.ts.

​
Gateway и E2E

  • Интеграция Gateway включается явно: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test или pnpm test:gateway.
  • pnpm test:e2e: совокупный E2E репозитория = pnpm test:e2e:gateway && pnpm test:ui:e2e.
  • pnpm test:e2e:gateway: сквозные дымовые тесты Gateway (сопряжение нескольких экземпляров по WS/HTTP/Node). По умолчанию используются threads + isolate: false с адаптивным числом исполнителей в vitest.e2e.config.ts; настройка выполняется через OPENCLAW_E2E_WORKERS=<n>, подробное журналирование — через OPENCLAW_E2E_VERBOSE=1.
  • pnpm test:live: тесты провайдеров в реальной среде (Claude/Minimax/DeepSeek/z.ai и т. д., управляются *.live.test.ts). Чтобы они не пропускались, требуются ключи API и LIVE=1 (или OPENCLAW_LIVE_TEST=1); подробный вывод включается через OPENCLAW_LIVE_TEST_QUIET=0.

​
Полный набор Docker (pnpm test:docker:all)

Создаёт общий образ для тестов в реальной среде, один раз упаковывает OpenClaw в tar-архив npm, создаёт или повторно использует минимальный образ исполнителя с Node/Git и функциональный образ, устанавливающий этот tar-архив в /app, а затем запускает связки дымовых проверок Docker через взвешенный планировщик. scripts/package-openclaw-for-docker.mjs — единый локальный/CI-упаковщик пакета, который проверяет tar-архив и dist/postinstall-inventory.json до их использования Docker.
  • Минимальный образ (OPENCLAW_DOCKER_E2E_BARE_IMAGE): связки установки, обновления и зависимостей плагинов; монтирует предварительно собранный tar-архив вместо скопированных исходных файлов репозитория.
  • Функциональный образ (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): связки проверки обычной функциональности собранного приложения.
  • Определения связок: scripts/lib/docker-e2e-scenarios.mjs. Планировщик: scripts/lib/docker-e2e-plan.mjs. Исполнитель: scripts/test-docker-all.mjs.
  • node scripts/test-docker-all.mjs --plan-json формирует принадлежащий планировщику план CI (связки, виды образов, потребности в пакете/образе для реальной среды, сценарии состояния, проверки учётных данных), не собирая и не запуская Docker.
Параметры планирования (переменные среды, значения по умолчанию в скобках): Шаблон переменной среды для ограничений ресурсов: OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (имя ресурса в верхнем регистре, последовательности символов, не являющихся буквами или цифрами, заменяются на _). Другое поведение: раннер по умолчанию выполняет предварительную проверку Docker, удаляет устаревшие E2E-контейнеры OpenClaw, совместно использует кеши CLI-инструментов провайдеров между совместимыми линиями и прекращает планировать новые линии из пула после первого сбоя, если не задана переменная OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Если одна линия превышает эффективный лимит веса/ресурсов на хосте с низким уровнем параллелизма, она всё равно может запуститься из пустого пула и выполняться одна, пока не освободит ресурсы. Журналы отдельных линий, summary.json, failures.json и данные о времени выполнения фаз записываются в .artifacts/docker-tests/<run-id>/; используйте pnpm test:docker:timings <summary.json> для анализа медленных линий и pnpm test:docker:rerun <run-id|summary.json|failures.json> для вывода недорогих команд целевого повторного запуска.

​
Примечательные линии Docker

​
Локальный шлюз PR

Для локальных проверок перед слиянием PR и прохождением шлюза выполните:
  • pnpm check:changed
  • pnpm check
  • pnpm check:test-types
  • pnpm build
  • pnpm test
  • pnpm check:docs
Если pnpm test нестабилен на загруженном хосте, повторите запуск один раз, прежде чем считать это регрессией, а затем изолируйте проблему с помощью pnpm test <path/to/test>. Для хостов с ограниченным объёмом памяти:
  • OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
  • OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

​
Инструменты анализа производительности тестов

  • pnpm test:perf:imports: включает отчёты Vitest о длительности импорта и детализации импорта, продолжая использовать маршрутизацию по ограниченным областям линий для явно указанных файлов и каталогов. pnpm test:perf:imports:changed ограничивает такое же профилирование файлами, изменёнными после origin/main.
  • pnpm test:perf:changed:bench -- --ref <git-ref> сопоставляет производительность маршрутизируемого режима изменений с нативным запуском корневого проекта для одной и той же зафиксированной разницы git; pnpm test:perf:changed:bench -- --worktree измеряет производительность текущего набора изменений рабочего дерева без предварительной фиксации.
  • pnpm test:perf:profile:main записывает профиль CPU для основного потока Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner записывает профили CPU и кучи для раннера модульных тестов (.artifacts/vitest-runner-profile).
  • pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: последовательно запускает каждую конечную конфигурацию Vitest полного набора и записывает сгруппированные данные о длительности, а также JSON-артефакты и журналы для каждой конфигурации. По умолчанию отчёты полного набора изолируют файлы, чтобы сохранённые графы модулей и паузы сборки мусора из предыдущих файлов не учитывались в последующих проверках; передавайте -- --no-isolate только при намеренном профилировании накопления в общем воркере. Агент производительности тестов использует это как базовый уровень перед попытками ускорить медленные тесты. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json сравнивает сгруппированные отчёты после изменения, направленного на повышение производительности.
  • Запуски шардов полного набора, расширений и шаблонов включения обновляют локальные данные о времени в .artifacts/vitest-shard-timings.json; последующие запуски всей конфигурации используют эти данные, чтобы сбалансировать медленные и быстрые шарды. Шарды CI с шаблонами включения добавляют имя шарда к ключу времени, благодаря чему данные о времени отфильтрованных шардов остаются видимыми, не заменяя данные о времени всей конфигурации. Задайте OPENCLAW_TEST_PROJECTS_TIMINGS=0, чтобы игнорировать локальный артефакт данных о времени.

​
Тесты производительности

Необязательные переменные окружения: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY. Запрос по умолчанию: «Ответьте одним словом: ok. Без знаков препинания и дополнительного текста».
Предустановки:
  • startup: --version, --help, health, health --json, status --json, status
  • real: health, status, status --json, sessions, sessions --json, tasks --json, tasks list --json, tasks audit --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
  • all: обе предустановки вместе
Вывод содержит sampleCount, среднее значение, p50, p95, минимум/максимум, распределение кодов завершения/сигналов и максимальный RSS для каждой команды. --cpu-prof-dir / --heap-prof-dir записывают профили V8 для каждого запуска.Сохранённый вывод: pnpm test:startup:bench:smoke записывает .artifacts/cli-startup-bench-smoke.json; pnpm test:startup:bench:save записывает .artifacts/cli-startup-bench-all.json (runs=5 warmup=1). Зафиксированная в репозитории фикстура: test/fixtures/cli-startup-bench.json, обновляется с помощью pnpm test:startup:bench:update и сравнивается с помощью pnpm test:startup:bench:check.
По умолчанию используется собранная точка входа CLI в dist/entry.js; сначала выполните pnpm build. Передайте --entry scripts/run-node.mjs, чтобы вместо неё измерить средство запуска исходного кода, и храните эти результаты отдельно от базовых показателей собранной точки входа.
Идентификаторы сценариев: default, skipChannels (запуск каналов пропущен), oneInternalHook, allInternalHooks, fiftyPlugins (50 плагинов с манифестами), fiftyStartupLazyPlugins (50 плагинов с манифестами и отложенным запуском).Вывод содержит первые выходные данные процесса, /healthz, /readyz, время записи в журнал о начале прослушивания HTTP, время записи в журнал о готовности Gateway, процессорное время, коэффициент использования ядер процессора, максимальный RSS, кучу, метрики трассировки запуска, задержку цикла событий и подробные метрики таблицы поиска плагинов. Скрипт задаёт OPENCLAW_GATEWAY_STARTUP_TRACE=1 в окружении дочернего процесса Gateway./healthz обозначает работоспособность (HTTP-сервер может отвечать). /readyz обозначает фактическую готовность к использованию (завершилась подготовка вспомогательных процессов плагинов запуска, каналов и критически важной для готовности работы после подключения). Обработчики запуска выполняются асинхронно и не входят в гарантию готовности. Время записи в журнал о готовности — это внутренняя временная метка Gateway, полезная для атрибуции на стороне процесса, но не заменяющая внешнюю проверку /readyz.При сравнении изменений используйте вывод JSON или --output. Используйте --cpu-prof-dir только после того, как данные трассировки укажут на импорт, компиляцию или процессорно-зависимую работу, которую невозможно объяснить одними временными показателями фаз.
Только для macOS и Linux (использует SIGUSR1 для перезапусков внутри процесса; в Windows немедленно завершается с ошибкой). По умолчанию используется та же собранная точка входа и то же переопределение --entry scripts/run-node.mjs, что и при запуске Gateway выше.
Идентификаторы сценариев: skipChannels, skipChannelsAcpxProbe (проверка запуска ACPX включена), skipChannelsNoAcpxProbe (проверка отключена), default, fiftyPlugins.Вывод содержит следующие /healthz, следующие /readyz, время простоя, время готовности после перезапуска, показатели процессора, RSS, метрики трассировки запуска замещающего процесса и метрики трассировки перезапуска для обработки сигналов, ожидания завершения активной работы, фаз закрытия, следующего запуска, времени готовности и снимков памяти. Скрипт задаёт OPENCLAW_GATEWAY_STARTUP_TRACE=1 и OPENCLAW_GATEWAY_RESTART_TRACE=1.Используйте этот тест производительности, когда изменение затрагивает сигнализацию перезапуска, обработчики закрытия, запуск после перезапуска, завершение вспомогательных процессов, передачу управления службой или готовность после перезапуска. Начните с skipChannels, чтобы изолировать механику Gateway от запуска каналов; используйте default или сценарии с большим количеством плагинов только после того, как узкий сценарий прояснит путь перезапуска. Метрики трассировки — это подсказки для атрибуции, а не окончательные выводы: оценивайте изменение перезапуска по нескольким выборкам, соответствующему диапазону владельца, поведению /healthz//readyz и пользовательскому контракту перезапуска.

​
Сквозное тестирование первоначальной настройки (Docker)

Необязательно; требуется только для дымовых тестов первоначальной настройки в контейнере. Полный процесс холодного запуска в чистом контейнере Linux:
Управляет интерактивным мастером через псевдотерминал, проверяет файлы конфигурации, рабочей области и сеанса, затем запускает Gateway и выполняет openclaw health.

​
Дымовой тест импорта QR-кода (Docker)

Проверяет, что поддерживаемый вспомогательный модуль среды выполнения QR загружается в поддерживаемых средах выполнения Docker Node (Node 24 по умолчанию, совместимость с Node 22):

​
Связанные материалы