Тестирование

OpenClaw имеет три набора Vitest (unit/integration, e2e, live) и небольшой набор Docker-раннеров.

Этот документ — руководство "как мы тестируем":

Что охватывает каждый набор (и что он намеренно не охватывает)
Какие команды запускать для обычных рабочих процессов (локальных, перед отправкой, отладки)
Как live-тесты обнаруживают учетные данные и выбирают модели/провайдеров
Как добавлять регрессии для реальных проблем модели/провайдера

Быстрый старт

Большинство дней:

Полная проверка (ожидается перед отправкой): pnpm lint && pnpm build && pnpm test

Когда вы касаетесь тестов или хотите дополнительной уверенности:

Проверка покрытия: pnpm test:coverage
Набор E2E: pnpm test:e2e

При отладке реальных провайдеров/моделей (требуются реальные учетные данные):

Набор Live (модели + инструменты/изображения шлюза): pnpm test:live

Совет: когда вам нужен только один неудачный случай, предпочтите сужение live-тестов через переменные окружения allowlist, описанные ниже.

Наборы тестов (что где выполняется)

Думайте о наборах как о "возрастающем реализме" (и возрастающей нестабильности/стоимости):

Unit / integration (по умолчанию)

Команда: pnpm test
Конфигурация: vitest.config.ts
Файлы: src/**/*.test.ts
Область:
- Чистые unit-тесты
- Интеграционные тесты в процессе (аутентификация шлюза, маршрутизация, инструментарий, парсинг, конфигурация)
- Детерминированные регрессии для известных ошибок
Ожидания:
- Выполняется в CI
- Не требуются реальные ключи
- Должны быть быстрыми и стабильными

E2E (smoke-тест шлюза)

Команда: pnpm test:e2e
Конфигурация: vitest.e2e.config.ts
Файлы: src/**/*.e2e.test.ts
Область:
- Сквозное поведение многоинстансового шлюза
- Поверхности WebSocket/HTTP, сопряжение узлов и более тяжелая работа с сетью
Ожидания:
- Выполняется в CI (когда включено в конвейере)
- Не требуются реальные ключи
- Больше движущихся частей, чем в unit-тестах (может быть медленнее)

Live (реальные провайдеры + реальные модели)

Команда: pnpm test:live
Конфигурация: vitest.live.config.ts
Файлы: src/**/*.live.test.ts
По умолчанию: включено через pnpm test:live (устанавливает OPENCLAW_LIVE_TEST=1)
Область:
- "Работает ли этот провайдер/модель сегодня с реальными учетными данными?"
- Отлавливает изменения формата провайдера, особенности вызова инструментов, проблемы аутентификации и поведение лимитов скорости
Ожидания:
- Не стабильно для CI по дизайну (реальные сети, реальные политики провайдеров, квоты, сбои)
- Стоит денег / использует лимиты скорости
- Предпочитайте запускать суженные подмножества вместо "всего"
- Live-запуски будут использовать ~/.profile для получения отсутствующих API-ключей
- Ротация ключей Anthropic: установите OPENCLAW_LIVE_ANTHROPIC_KEYS="sk-...,sk-..." (или OPENCLAW_LIVE_ANTHROPIC_KEY=sk-...) или несколько переменных ANTHROPIC_API_KEY*; тесты будут повторять попытки при лимитах скорости

Какой набор мне следует запустить?

Используйте эту таблицу решений:

Редактирование логики/тестов: запустите pnpm test (и pnpm test:coverage, если вы много изменили)
Касание сети шлюза / протокола WS / сопряжения: добавьте pnpm test:e2e
Отладка "мой бот не работает" / сбои, специфичные для провайдера / вызов инструментов: запустите суженный pnpm test:live

Live: smoke-тест модели (ключи профиля)

Live-тесты разделены на два уровня, чтобы мы могли изолировать сбои:

"Прямая модель" сообщает нам, может ли провайдер/модель вообще ответить с данным ключом.
"Smoke-тест шлюза" сообщает нам, работает ли полный конвейер шлюз+агент для этой модели (сеансы, история, инструменты, политика песочницы и т.д.).

Уровень 1: Прямое завершение модели (без шлюза)

Тест: src/agents/models.profiles.live.test.ts
Цель:
- Перечислить обнаруженные модели
- Использовать getApiKeyForModel для выбора моделей, для которых у вас есть учетные данные
- Выполнить небольшое завершение для каждой модели (и целевые регрессии там, где необходимо)
Как включить:
- pnpm test:live (или OPENCLAW_LIVE_TEST=1, если вызываете Vitest напрямую)
Установите OPENCLAW_LIVE_MODELS=modern (или all, псевдоним для modern), чтобы фактически запустить этот набор; в противном случае он пропускается, чтобы pnpm test:live фокусировался на smoke-тесте шлюза
Как выбрать модели:
- OPENCLAW_LIVE_MODELS=modern для запуска современного списка разрешений (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
- OPENCLAW_LIVE_MODELS=all — это псевдоним для современного списка разрешений
- или OPENCLAW_LIVE_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,..." (список через запятую)
Как выбрать провайдеров:
- OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (список через запятую)
Откуда берутся ключи:
- По умолчанию: хранилище профилей и резервные варианты окружения
- Установите OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, чтобы принудительно использовать только хранилище профилей
Зачем это существует:
- Отделяет "API провайдера сломан / ключ недействителен" от "конвейер агента шлюза сломан"
- Содержит небольшие изолированные регрессии (пример: воспроизведение рассуждений OpenAI Responses/Codex Responses + потоки вызова инструментов)

Уровень 2: Smoke-тест шлюза + dev-агента (что на самом деле делает "@openclaw")

Тест: src/gateway/gateway-models.profiles.live.test.ts
Цель:
- Запустить шлюз в процессе
- Создать/исправить сеанс agent:dev:* (переопределение модели на запуск)
- Перебрать модели с ключами и утверждать:
  - "значимый" ответ (без инструментов)
  - реальный вызов инструмента работает (проверка read)
  - опциональные дополнительные проверки инструментов (проверка exec+read)
  - Пути регрессии OpenAI (только вызов инструмента → продолжение) продолжают работать
Детали проверки (чтобы вы могли быстро объяснить сбои):
- Проверка read: тест записывает файл nonce в рабочее пространство и просит агента read его и вернуть nonce.
- Проверка exec+read: тест просит агента exec-записать nonce во временный файл, затем read его обратно.
- Проверка изображения: тест прикрепляет сгенерированный PNG (кошка + случайный код) и ожидает, что модель вернет cat <CODE>.
- Справочная реализация: src/gateway/gateway-models.profiles.live.test.ts и src/gateway/live-image-probe.ts.
Как включить:
- pnpm test:live (или OPENCLAW_LIVE_TEST=1, если вызываете Vitest напрямую)
Как выбрать модели:
- По умолчанию: современный список разрешений (Opus/Sonnet/Haiku 4.5, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.1, Grok 4)
- OPENCLAW_LIVE_GATEWAY_MODELS=all — это псевдоним для современного списка разрешений
- Или установите OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (или список через запятую) для сужения
Как выбрать провайдеров (избегать "все OpenRouter"):
- OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (список через запятую)
Проверки инструментов + изображений всегда включены в этом live-тесте:
- Проверка read + проверка exec+read (стресс-тест инструментов)
- Проверка изображения выполняется, когда модель сообщает о поддержке ввода изображений
- Поток (высокий уровень):
  - Тест генерирует крошечный PNG с "CAT" + случайным кодом (src/gateway/live-image-probe.ts)
  - Отправляет его через agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
  - Шлюз парсит вложения в images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
  - Встроенный агент пересылает мультимодальное сообщение пользователя модели
  - Утверждение: ответ содержит cat + код (допускается OCR-погрешность: допускаются небольшие ошибки)

Совет: чтобы увидеть, что вы можете протестировать на своей машине (и точные идентификаторы provider/model), выполните:

openclaw models list
openclaw models list --json

Live: smoke-тест setup-token Anthropic

Тест: src/agents/anthropic.setup-token.live.test.ts
Цель: проверить, что Claude Code CLI setup-token (или вставленный профиль setup-token) может выполнить запрос Anthropic.
Включить:
- pnpm test:live (или OPENCLAW_LIVE_TEST=1, если вызываете Vitest напрямую)
- OPENCLAW_LIVE_SETUP_TOKEN=1
Источники токена (выберите один):
- Профиль: OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test
- Необработанный токен: OPENCLAW_LIVE_SETUP_TOKEN_VALUE=sk-ant-oat01-...
Переопределение модели (опционально):
- OPENCLAW_LIVE_SETUP_TOKEN_MODEL=anthropic/claude-opus-4-5

Пример настройки:

openclaw models auth paste-token --provider anthropic --profile-id anthropic:setup-token-test
OPENCLAW_LIVE_SETUP_TOKEN=1 OPENCLAW_LIVE_SETUP_TOKEN_PROFILE=anthropic:setup-token-test pnpm test:live src/agents/anthropic.setup-token.live.test.ts

Live: smoke-тест бэкенда CLI (Claude Code CLI или другие локальные CLI)

Тест: src/gateway/gateway-cli-backend.live.test.ts
Цель: проверить конвейер шлюз + агент с использованием локального CLI-бэкенда, не касаясь вашей конфигурации по умолчанию.
Включить:
- pnpm test:live (или OPENCLAW_LIVE_TEST=1, если вызываете Vitest напрямую)
- OPENCLAW_LIVE_CLI_BACKEND=1
По умолчанию:
- Модель: claude-cli/claude-sonnet-4-5
- Команда: claude
- Аргументы: ["-p","--output-format","json","--dangerously-skip-permissions"]
Переопределения (опционально):
- OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-opus-4-5"
- OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2-codex"
- OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/claude"
- OPENCLAW_LIVE_CLI_BACKEND_ARGS='["-p","--output-format","json","--permission-mode","bypassPermissions"]'
- OPENCLAW_LIVE_CLI_BACKEND_CLEAR_ENV='["ANTHROPIC_API_KEY","ANTHROPIC_API_KEY_OLD"]'
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1 для отправки реального вложения изображения (пути внедряются в запрос).
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" для передачи путей к файлам изображений в качестве аргументов CLI вместо внедрения в запрос.
- OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (или "list") для управления тем, как передаются аргументы изображений, когда установлен IMAGE_ARG.
- OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 для отправки второго хода и проверки потока возобновления.
OPENCLAW_LIVE_CLI_BACKEND_DISABLE_MCP_CONFIG=0 для сохранения включенной конфигурации MCP Claude Code CLI (по умолчанию отключает конфигурацию MCP с временным пустым файлом).

Пример:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="claude-cli/claude-sonnet-4-5" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Live: матрица моделей (что мы охватываем)

Нет фиксированного "списка моделей CI" (live опционален), но это рекомендуемые модели для регулярного охвата на dev-машине с ключами.

Современный набор smoke-тестов (вызов инструментов + изображения)

Это запуск "общих моделей", который, как мы ожидаем, будет продолжать работать:

OpenAI (не Codex): openai/gpt-5.2 (опционально: openai/gpt-5.1)
OpenAI Codex: openai-codex/gpt-5.2 (опционально: openai-codex/gpt-5.2-codex)
Anthropic: anthropic/claude-opus-4-5 (или anthropic/claude-sonnet-4-5)
Google (Gemini API): google/gemini-3-pro-preview и google/gemini-3-flash-preview (избегайте старых моделей Gemini 2.x)
Google (Antigravity): google-antigravity/claude-opus-4-5-thinking и google-antigravity/gemini-3-flash
Z.AI (GLM): zai/glm-4.7
MiniMax: minimax/minimax-m2.1

Запустите smoke-тест шлюза с инструментами + изображением: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Базовый: вызов инструментов (Read + опциональный Exec)

Выберите хотя бы один для каждого семейства провайдеров:

OpenAI: openai/gpt-5.2 (или openai/gpt-5-mini)
Anthropic: anthropic/claude-opus-4-5 (или anthropic/claude-sonnet-4-5)
Google: google/gemini-3-flash-preview (или google/gemini-3-pro-preview)
Z.AI (GLM): zai/glm-4.7
MiniMax: minimax/minimax-m2.1

Опциональное дополнительное покрытие (приятно иметь):

xAI: xai/grok-4 (или последняя доступная)
Mistral: mistral/… (выберите одну модель с поддержкой "tools", которую вы включили)
Cerebras: cerebras/… (если у вас есть доступ)
LM Studio: lmstudio/… (локальная; вызов инструментов зависит от режима API)

Vision: отправка изображения (вложение → мультимодальное сообщение)

Включите хотя бы одну модель с поддержкой изображений в OPENCLAW_LIVE_GATEWAY_MODELS (варианты Claude/Gemini/OpenAI с поддержкой vision и т.д.) для выполнения проверки изображения.

Агрегаторы / альтернативные шлюзы

Если у вас включены ключи, мы также поддерживаем тестирование через:

OpenRouter: openrouter/... (сотни моделей; используйте openclaw models scan для поиска кандидатов с поддержкой инструментов+изображений)
OpenCode Zen: opencode/... (аутентификация через OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Больше провайдеров, которые вы можете включить в live-матрицу (если у вас есть учетные данные/конфигурация):

Встроенные: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, xai, groq, cerebras, mistral, github-copilot
Через models.providers (пользовательские конечные точки): minimax (облако/API), плюс любой прокси, совместимый с OpenAI/Anthropic (LM Studio, vLLM, LiteLLM и т.д.)

Совет: не пытайтесь жестко кодировать "все модели" в документации. Авторитетный список — это то, что возвращает discoverModels(...) на вашей машине + какие ключи доступны.

Учетные данные (никогда не коммитьте)

Live-тесты обнаруживают учетные данные так же, как CLI. Практические последствия:

Если CLI работает, live-тесты должны найти те же ключи.
Если live-тест говорит "нет учетных данных", отлаживайте так же, как вы бы отлаживали openclaw models list / выбор модели.
Хранилище профилей: ~/.openclaw/credentials/ (предпочтительно; что означает "ключи профиля" в тестах)
Конфигурация: ~/.openclaw/openclaw.json (или OPENCLAW_CONFIG_PATH)

Если вы хотите полагаться на ключи окружения (например, экспортированные в вашем ~/.profile), запустите локальные тесты после source ~/.profile, или используйте Docker-раннеры ниже (они могут монтировать ~/.profile в контейнер).

Deepgram live (транскрипция аудио)

Тест: src/media-understanding/providers/deepgram/audio.live.test.ts
Включить: DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

Docker-раннеры (опциональные проверки "работает на Linux")

Они запускают pnpm test:live внутри Docker-образа репозитория, монтируя вашу локальную директорию конфигурации и рабочее пространство (и используя ~/.profile, если смонтирован):

Прямые модели: pnpm test:docker:live-models (скрипт: scripts/test-live-models-docker.sh)
Шлюз + dev-агент: pnpm test:docker:live-gateway (скрипт: scripts/test-live-gateway-models-docker.sh)
Мастер настройки (TTY, полное создание каркаса): pnpm test:docker:onboard (скрипт: scripts/e2e/onboard-docker.sh)
Сеть шлюза (два контейнера, аутентификация WS + работоспособность): pnpm test:docker:gateway-network (скрипт: scripts/e2e/gateway-network-docker.sh)
Плагины (загрузка пользовательского расширения + smoke-тест реестра): pnpm test:docker:plugins (скрипт: scripts/e2e/plugins-docker.sh)

Полезные переменные окружения:

OPENCLAW_CONFIG_DIR=... (по умолчанию: ~/.openclaw) смонтирован в /home/node/.openclaw
OPENCLAW_WORKSPACE_DIR=... (по умолчанию: ~/.openclaw/workspace) смонтирован в /home/node/.openclaw/workspace
OPENCLAW_PROFILE_FILE=... (по умолчанию: ~/.profile) смонтирован в /home/node/.profile и используется перед запуском тестов
OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... для сужения запуска
OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 для обеспечения того, чтобы учетные данные поступали из хранилища профилей (не окружения)

Проверка документации

Выполняйте проверки документации после редактирования документов: pnpm docs:list.

Офлайн-регрессия (безопасно для CI)

Это регрессии "реального конвейера" без реальных провайдеров:

Вызов инструментов шлюза (мок OpenAI, реальный цикл шлюз + агент): src/gateway/gateway.tool-calling.mock-openai.test.ts
Мастер шлюза (WS wizard.start/wizard.next, записывает конфигурацию + аутентификация обязательна): src/gateway/gateway.wizard.e2e.test.ts

Оценка надежности агента (навыки)

У нас уже есть несколько тестов, безопасных для CI, которые ведут себя как "оценки надежности агента":

Мок вызова инструментов через реальный цикл шлюз + агент (src/gateway/gateway.tool-calling.mock-openai.test.ts).
Сквозные потоки мастера, которые проверяют проводку сеанса и эффекты конфигурации (src/gateway/gateway.wizard.e2e.test.ts).

Что все еще отсутствует для навыков (см. Skills):

Принятие решений: когда навыки перечислены в запросе, выбирает ли агент правильный навык (или избегает нерелевантных)?
Соответствие: читает ли агент SKILL.md перед использованием и следует ли необходимым шагам/аргументам?
Контракты рабочих процессов: многоходовые сценарии, которые утверждают порядок инструментов, перенос истории сеанса и границы песочницы.

Будущие оценки должны оставаться детерминированными в первую очередь:

Исполнитель сценариев, использующий мок-провайдеры для утверждения вызовов инструментов + порядка, чтения файлов навыков и проводки сеанса.
Небольшой набор сценариев, ориентированных на навыки (использование против избегания, контроль, внедрение запроса).
Опциональные live-оценки (opt-in, контролируемые окружением) только после того, как набор, безопасный для CI, будет на месте.

Добавление регрессий (руководство)

Когда вы исправляете проблему провайдера/модели, обнаруженную в live:

Добавьте регрессию, безопасную для CI, если возможно (мок/заглушка провайдера, или захват точного преобразования формы запроса)
Если это по своей сути только live (лимиты скорости, политики аутентификации), оставьте live-тест узким и opt-in через переменные окружения
Предпочитайте нацеливание на наименьший слой, который обнаруживает ошибку:
- ошибка преобразования/воспроизведения запроса провайдера → тест прямых моделей
- ошибка конвейера сеанса/истории/инструментов шлюза → live smoke-тест шлюза или мок-тест шлюза, безопасный для CI