openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
80432ba439
docs/docs/uk/help/testing.md
openclaw-docs-i18n[bot] 80432ba439 chore(i18n): refresh uk translations
2026-04-09 22:57:46 +00:00

70 KiB
Raw Blame History

read_when summary title x-i18n
Запуск тестів локально або в CI
Додавання регресійних тестів для багів моделі/провайдера
Налагодження поведінки шлюзу й агента
Набір для тестування: модульні/e2e/live набори, Docker-ранери та що охоплює кожен тест Тестування
generated_at model provider source_hash source_path workflow
2026-04-09T22:54:33Z gpt-5.4 openai 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4 help/testing.md 15

Тестування

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

Цей документ — посібник «як ми тестуємо»:

  • Що охоплює кожен набір (і що він навмисно не охоплює)
  • Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження)
  • Як live-тести знаходять облікові дані та вибирають моделі/провайдерів
  • Як додавати регресійні тести для реальних проблем із моделями/провайдерами

Швидкий старт

У більшості випадків:

  • Повний gate (очікується перед push): pnpm build && pnpm check && pnpm test
  • Швидший локальний запуск повного набору на потужній машині: pnpm test:max
  • Прямий цикл спостереження Vitest: pnpm test:watch
  • Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
  • Під час ітерацій над однією помилкою спочатку надавайте перевагу цільовим запускам.
  • QA-сайт на базі Docker: pnpm qa:lab:up
  • QA-ланка на базі Linux VM: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Коли ви змінюєте тести або хочете мати додаткову впевненість:

  • Gate покриття: pnpm test:coverage
  • Набір E2E: pnpm test:e2e

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

  • Live-набір (моделі + gateway tool/image probes): pnpm test:live
  • Тихий запуск одного live-файлу: pnpm test:live -- src/agents/models.profiles.live.test.ts

Порада: якщо вам потрібен лише один проблемний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче.

Спеціалізовані QA-ранери

Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab:

  • pnpm openclaw qa suite
    • Запускає QA-сценарії з репозиторію безпосередньо на хості.
  • pnpm openclaw qa suite --runner multipass
    • Запускає той самий QA-набір у disposable Linux VM Multipass.
    • Зберігає ту саму поведінку вибору сценаріїв, що й qa suite на хості.
    • Повторно використовує ті самі прапорці вибору провайдера/моделі, що й qa suite.
    • Live-запуски пересилають підтримувані QA-входи автентифікації, які практичні для guest: ключі провайдерів через env, шлях до конфігурації QA live provider і CODEX_HOME, якщо вони присутні.
    • Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace.
    • Записує звичайний QA-звіт і підсумок, а також журнали Multipass у .artifacts/qa-e2e/....
  • pnpm qa:lab:up
    • Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі.

Набори тестів (що де запускається)

Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості):

Unit / integration (типовий)

  • Команда: pnpm test
  • Конфігурація: десять послідовних shard-запусків (vitest.full-*.config.ts) по наявних scoped Vitest-проєктах
  • Файли: core/unit inventory у src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts і whitelisted ui node-тести, які охоплює vitest.unit.config.ts
  • Обсяг:
    • Чисті модульні тести
    • In-process інтеграційні тести (gateway auth, routing, tooling, parsing, config)
    • Детерміновані регресії для відомих багів
  • Очікування:
    • Запускається в CI
    • Реальні ключі не потрібні
    • Має бути швидким і стабільним
  • Примітка щодо проєктів:
    • Ненаправлений pnpm test тепер запускає одинадцять менших shard-конфігурацій (core-unit-src, core-unit-security, core-unit-ui, core-unit-support, core-support-boundary, core-contracts, core-bundled, core-runtime, agentic, auto-reply, extensions) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори.
    • pnpm test --watch усе ще використовує граф проєктів native root vitest.config.ts, оскільки цикл спостереження з кількома shard непрактичний.
    • pnpm test, pnpm test:watch і pnpm test:perf:imports спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts не потребує повної вартості запуску root project.
    • pnpm test:changed розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup усе ще повертаються до ширшого повторного запуску root project.
    • Окремі тести plugin-sdk і commands також маршрутизуються через спеціальні легкі lanes, які пропускають test/setup-openclaw-runtime.ts; stateful/runtime-heavy файли залишаються на наявних lanes.
    • Окремі helper source-файли plugin-sdk і commands також відображають запуски changed-mode на явні sibling-тести в цих легких lanes, тож редагування helper-ів не спричиняє повторний запуск повного важкого набору для цього каталогу.
    • auto-reply тепер має три спеціальні кошики: core helper-і верхнього рівня, інтеграційні тести верхнього рівня reply.* і піддерево src/auto-reply/reply/**. Це утримує найважчу роботу harness reply осторонь дешевих тестів status/chunk/token.
  • Примітка щодо embedded runner:
    • Коли ви змінюєте входи виявлення message-tool або runtime context compaction, зберігайте обидва рівні покриття.
    • Додавайте сфокусовані helper-регресії для чистих меж routing/normalization.
    • Також підтримуйте в належному стані інтеграційні набори embedded runner: src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts, і src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
    • Ці набори перевіряють, що scoped id і поведінка compaction усе ще проходять через реальні шляхи run.ts / compact.ts; самих лише helper-тестів недостатньо як заміни для цих інтеграційних шляхів.
  • Примітка щодо pool:
    • Базова конфігурація Vitest тепер типово використовує threads.
    • Спільна конфігурація Vitest також фіксує isolate: false і використовує non-isolated runner у root projects, e2e та live configs.
    • Root UI lane зберігає своє налаштування jsdom та optimizer, але тепер теж працює на спільному non-isolated runner.
    • Кожен shard pnpm test успадковує ті самі типові значення threads + isolate: false зі спільної конфігурації Vitest.
    • Спільний launcher scripts/run-vitest.mjs тепер також типово додає --no-maglev для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть OPENCLAW_VITEST_ENABLE_MAGLEV=1, якщо потрібно порівняти зі стандартною поведінкою V8.
  • Примітка щодо швидкої локальної ітерації:
    • pnpm test:changed маршрутизує через scoped lanes, коли змінені шляхи однозначно відповідають меншому набору.
    • pnpm test:max і pnpm test:changed:max зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості воркерів.
    • Автомасштабування локальних воркерів тепер навмисно консервативне й також зменшує активність, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди.
    • Базова конфігурація Vitest позначає проєкти/конфіг-файли як forceRerunTriggers, щоб повторні запуски changed-mode залишалися коректними, коли змінюється wiring тестів.
    • Конфігурація зберігає OPENCLAW_VITEST_FS_MODULE_CACHE увімкненим на підтримуваних хостах; установіть OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path, якщо хочете мати одне явне розташування кешу для прямого профілювання.
  • Примітка щодо налагодження продуктивності:
    • pnpm test:perf:imports вмикає звітування Vitest про тривалість імпорту та вивід розбивки імпортів.
    • pnpm test:perf:imports:changed обмежує той самий профільований вигляд файлами, зміненими відносно origin/main.
  • pnpm test:perf:changed:bench -- --ref <git-ref> порівнює маршрутизований test:changed з native root-project path для цього зафіксованого diff і виводить wall time та macOS max RSS.
  • pnpm test:perf:changed:bench -- --worktree вимірює поточне dirty tree, маршрутизуючи список змінених файлів через scripts/test-projects.mjs і root-конфігурацію Vitest.
    • pnpm test:perf:profile:main записує профіль CPU main-thread для накладних витрат запуску й transform у Vitest/Vite.
    • pnpm test:perf:profile:runner записує профілі CPU+heap runner-а для unit-набору з вимкненим file parallelism.

E2E (gateway smoke)

  • Команда: pnpm test:e2e
  • Конфігурація: vitest.e2e.config.ts
  • Файли: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
  • Типові параметри runtime:
    • Використовує Vitest threads з isolate: false, узгоджено з рештою репозиторію.
    • Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1).
    • Типово запускається в тихому режимі, щоб зменшити витрати на I/O консолі.
  • Корисні перевизначення:
    • OPENCLAW_E2E_WORKERS=<n> — примусово задати кількість воркерів (обмежено 16).
    • OPENCLAW_E2E_VERBOSE=1 — знову ввімкнути докладний консольний вивід.
  • Обсяг:
    • End-to-end поведінка gateway з кількома екземплярами
    • Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії
  • Очікування:
    • Запускається в CI (коли увімкнено в pipeline)
    • Реальні ключі не потрібні
    • Більше рухомих частин, ніж у модульних тестах (може бути повільніше)

E2E: smoke OpenShell backend

  • Команда: pnpm test:e2e:openshell
  • Файл: test/openshell-sandbox.e2e.test.ts
  • Обсяг:
    • Запускає ізольований OpenShell gateway на хості через Docker
    • Створює sandbox із тимчасового локального Dockerfile
    • Перевіряє OpenShell backend в OpenClaw через реальні sandbox ssh-config + SSH exec
    • Верифікує remote-canonical поведінку файлової системи через bridge fs sandbox
  • Очікування:
    • Лише opt-in; не входить до типового запуску pnpm test:e2e
    • Потрібен локальний CLI openshell і робочий Docker daemon
    • Використовує ізольовані HOME / XDG_CONFIG_HOME, потім знищує тестовий gateway і sandbox
  • Корисні перевизначення:
    • OPENCLAW_E2E_OPENSHELL=1 — увімкнути тест під час ручного запуску ширшого e2e-набору
    • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell — вказати нестандартний CLI-бінарник або wrapper script

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

  • Команда: pnpm test:live
  • Конфігурація: vitest.live.config.ts
  • Файли: src/**/*.live.test.ts
  • Типово: увімкнено через pnpm test:live (встановлює OPENCLAW_LIVE_TEST=1)
  • Обсяг:
    • «Чи працює цей провайдер/модель сьогодні з реальними обліковими даними?»
    • Виявлення змін формату провайдера, особливостей виклику tools, проблем auth і поведінки rate limit
  • Очікування:
    • Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої)
    • Коштує грошей / використовує rate limits
    • Краще запускати звужені підмножини, а не «все»
  • Live-запуски використовують ~/.profile, щоб підхопити відсутні API-ключі.
  • Типово live-запуски все одно ізолюють HOME і копіюють конфігурацію/матеріали auth у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний ~/.openclaw.
  • Установлюйте OPENCLAW_LIVE_USE_REAL_HOME=1 лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог.
  • pnpm test:live тепер типово працює в тихішому режимі: він зберігає вивід прогресу [live] ..., але приховує додаткове повідомлення про ~/.profile і приглушує журнали запуску gateway/шум Bonjour. Установіть OPENCLAW_LIVE_TEST_QUIET=0, якщо хочете повернути повні стартові журнали.
  • Ротація API-ключів (для конкретного провайдера): установіть *_API_KEYS у форматі з комами/крапками з комою або *_API_KEY_1, *_API_KEY_2 (наприклад, OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) або використовуйте перевизначення для конкретного live-запуску через OPENCLAW_LIVE_*_KEY; тести повторюють спробу у відповідь на rate limit.
  • Вивід прогресу/heartbeat:
    • Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера було видно активними навіть тоді, коли захоплення консолі Vitest працює тихо.
    • vitest.live.config.ts вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway транслюються негайно під час live-запусків.
    • Налаштовуйте heartbeat прямих моделей через OPENCLAW_LIVE_HEARTBEAT_MS.
    • Налаштовуйте heartbeat gateway/probe через OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Який набір мені запускати?

Скористайтеся цією таблицею рішень:

  • Редагуєте логіку/тести: запускайте pnpm test (і pnpm test:coverage, якщо змінили багато)
  • Торкаєтеся мережевої взаємодії gateway / WS protocol / pairing: додайте pnpm test:e2e
  • Налагоджуєте «мій бот не працює» / збої конкретного провайдера / виклик tools: запускайте звужений pnpm test:live

Live: Android node capability sweep

  • Тест: src/gateway/android-node.capabilities.live.test.ts
  • Скрипт: pnpm android:test:integration
  • Мета: викликати кожну команду, яка наразі оголошується підключеним Android-вузлом, і перевірити поведінку контракту команди.
  • Обсяг:
    • Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не спаровує застосунок).
    • Перевірка node.invoke у gateway для вибраного Android-вузла по команді за командою.
  • Необхідне попереднє налаштування:
    • Android-застосунок уже підключений і спарений із gateway.
    • Застосунок утримується на передньому плані.
    • Для можливостей, які ви очікуєте, що пройдуть перевірку, надано дозволи/згоду на захоплення.
  • Необов’язкові перевизначення цілі:
    • OPENCLAW_ANDROID_NODE_ID або OPENCLAW_ANDROID_NODE_NAME.
    • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
  • Повні відомості про налаштування Android: Android App

Live: smoke моделей (ключі профілів)

Live-тести поділено на два шари, щоб можна було ізолювати збої:

  • «Пряма модель» показує, чи може провайдер/модель узагалі відповісти з наданим ключем.
  • «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сеанси, історія, tools, sandbox policy тощо).

Шар 1: Пряме завершення моделі (без gateway)

  • Тест: 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 залишався зосередженим на gateway smoke
  • Як вибирати моделі:
    • OPENCLAW_LIVE_MODELS=modern, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
    • OPENCLAW_LIVE_MODELS=all — це псевдонім для сучасного allowlist
    • або OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (allowlist через кому)
    • Modern/all sweeps типово використовують відібрану верхню межу високосигнальних моделей; установіть OPENCLAW_LIVE_MAX_MODELS=0 для вичерпного modern sweep або додатне число для меншої межі.
  • Як вибирати провайдерів:
    • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (allowlist через кому)
  • Звідки беруться ключі:
    • Типово: сховище профілів і резервні значення з env
    • Установіть OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, щоб примусово використовувати лише сховище профілів
  • Навіщо це існує:
    • Відокремлює «API провайдера зламане / ключ невалідний» від «конвеєр gateway agent зламаний»
    • Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call)

Шар 2: smoke gateway + dev agent (що насправді робить "@openclaw")

  • Тест: src/gateway/gateway-models.profiles.live.test.ts
  • Мета:
    • Підняти in-process gateway
    • Створити/оновити сеанс agent:dev:* (перевизначення моделі для кожного запуску)
    • Перебрати моделі з ключами та перевірити:
      • «змістовну» відповідь (без tools)
      • що працює реальний виклик tool (read probe)
      • необов’язкові додаткові probes tool (exec+read probe)
      • що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати
  • Відомості про probe-и (щоб ви могли швидко пояснити збої):
    • read probe: тест записує nonce-файл у workspace і просить агента read його та повернути nonce.
    • exec+read probe: тест просить агента записати nonce у тимчасовий файл через exec, а потім прочитати його через read.
    • image probe: тест прикріплює згенерований 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 напряму)
  • Як вибирати моделі:
    • Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
    • OPENCLAW_LIVE_GATEWAY_MODELS=all — це псевдонім для сучасного allowlist
    • Або встановіть OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (або список через кому), щоб звузити вибір
    • Modern/all gateway sweeps типово використовують відібрану верхню межу високосигнальних моделей; установіть OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 для вичерпного modern sweep або додатне число для меншої межі.
  • Як вибирати провайдерів (уникати «все OpenRouter»):
    • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (allowlist через кому)
  • Tool та image probes у цьому live-тесті завжди ввімкнені:
    • read probe + exec+read probe (stress для tool)
    • image probe запускається, коли модель оголошує підтримку image input
    • Потік (на високому рівні):
      • Тест генерує крихітний PNG із «CAT» + випадковим кодом (src/gateway/live-image-probe.ts)
      • Надсилає його через agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
      • Gateway розбирає вкладення в images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
      • Embedded agent пересилає моделі мультимодальне повідомлення користувача
      • Перевірка: відповідь містить cat + код (допуск OCR: незначні помилки дозволені)

Порада: щоб побачити, що можна тестувати на вашій машині (і точні ідентифікатори provider/model), виконайте:

openclaw models list
openclaw models list --json

Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI)

  • Тест: src/gateway/gateway-cli-backend.live.test.ts
  • Мета: перевірити конвеєр Gateway + agent із локальним CLI backend, не торкаючись вашої типової конфігурації.
  • Типові значення smoke для конкретного backend зберігаються у визначенні cli-backend.ts розширення-власника.
  • Увімкнення:
    • pnpm test:live (або OPENCLAW_LIVE_TEST=1, якщо запускати Vitest напряму)
    • OPENCLAW_LIVE_CLI_BACKEND=1
  • Типові значення:
    • Типовий провайдер/модель: claude-cli/claude-sonnet-4-6
    • Поведінка command/args/image береться з метаданих plugin-а CLI backend, якому це належить.
  • Перевизначення (необов’язково):
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"
    • OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"
    • OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1, щоб надіслати реальне image-вкладення (шляхи інжектуються в prompt).
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image", щоб передавати шляхи до image-файлів як аргументи CLI замість інжекції в prompt.
    • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (або "list"), щоб керувати способом передавання image-аргументів, коли задано IMAGE_ARG.
    • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1, щоб надіслати другий хід і перевірити потік відновлення.
    • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0, щоб вимкнути типовий probe безперервності того самого сеансу Claude Sonnet -> Opus (установіть 1, щоб примусово його ввімкнути, коли вибрана модель підтримує ціль перемикання).

Приклад:

OPENCLAW_LIVE_CLI_BACKEND=1 \
  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
  pnpm test:live src/gateway/gateway-cli-backend.live.test.ts

Docker-рецепт:

pnpm test:docker:live-cli-backend

Docker-рецепти для одного провайдера:

pnpm test:docker:live-cli-backend:claude
pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini

Примітки:

  • Docker-ранер розташований у scripts/test-live-cli-backend-docker.sh.
  • Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача node.
  • Він визначає метадані smoke CLI з розширення-власника, а потім встановлює відповідний Linux CLI-пакет (@anthropic-ai/claude-code, @openai/codex або @google/gemini-cli) у кешований придатний для запису префікс за адресою OPENCLAW_DOCKER_CLI_TOOLS_DIR (типово: ~/.cache/openclaw/docker-cli-tools).
  • Live smoke CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації image, а потім виклик MCP tool cron, перевірений через CLI gateway.
  • Типовий smoke Claude також оновлює сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку.

Live: smoke ACP bind (/acp spawn ... --bind here)

  • Тест: src/gateway/gateway-acp-bind.live.test.ts
  • Мета: перевірити реальний потік прив’язування розмови ACP із live ACP-агентом:
    • надіслати /acp spawn <agent> --bind here
    • прив’язати synthetic розмову message-channel на місці
    • надіслати звичайне follow-up у тій самій розмові
    • перевірити, що follow-up потрапляє до transcript прив’язаного ACP-сеансу
  • Увімкнення:
    • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
    • OPENCLAW_LIVE_ACP_BIND=1
  • Типові значення:
    • ACP-агенти в Docker: claude,codex,gemini
    • ACP-агент для прямого pnpm test:live ...: claude
    • Synthetic channel: контекст розмови у стилі Slack DM
    • ACP backend: acpx
  • Перевизначення:
    • OPENCLAW_LIVE_ACP_BIND_AGENT=claude
    • OPENCLAW_LIVE_ACP_BIND_AGENT=codex
    • OPENCLAW_LIVE_ACP_BIND_AGENT=gemini
    • OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini
    • OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'
  • Примітки:
    • Ця ланка використовує поверхню gateway chat.send з synthetic originating-route fields лише для адміністраторів, щоб тести могли прикріплювати контекст message-channel без удаваної зовнішньої доставки.
    • Коли OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND не задано, тест використовує вбудований реєстр агентів plugin-а acpx для вибраного ACP harness agent.

Приклад:

OPENCLAW_LIVE_ACP_BIND=1 \
  OPENCLAW_LIVE_ACP_BIND_AGENT=claude \
  pnpm test:live src/gateway/gateway-acp-bind.live.test.ts

Docker-рецепт:

pnpm test:docker:live-acp-bind

Docker-рецепти для одного агента:

pnpm test:docker:live-acp-bind:claude
pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini

Примітки щодо Docker:

  • Docker-ранер розташований у scripts/test-live-acp-bind-docker.sh.
  • Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: claude, codex, потім gemini.
  • Використовуйте OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex або OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini, щоб звузити матрицю.
  • Він використовує ~/.profile, підготовлює відповідні матеріали auth CLI у контейнері, встановлює acpx у придатний для запису npm-префікс, а потім встановлює потрібний live CLI (@anthropic-ai/claude-code, @openai/codex або @google/gemini-cli), якщо його бракує.
  • Усередині Docker раннер установлює OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx, щоб acpx зберігав доступність змінних середовища провайдера з підключеного профілю для дочірнього harness CLI.

Рекомендовані live-рецепти

Найшвидші й найменш нестабільні — вузькі, явні allowlist:

  • Одна модель, напряму (без gateway):

    • OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts

  • Одна модель, gateway smoke:

    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

  • Виклик tools у кількох провайдерів:

    • OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

  • Фокус на Google (API-ключ Gemini + Antigravity):

    • Gemini (API-ключ): OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts
    • Antigravity (OAuth): OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Примітки:

  • google/... використовує Gemini API (API-ключ).
  • google-antigravity/... використовує міст OAuth Antigravity (кінцева точка агента у стилі Cloud Code Assist).
  • google-gemini-cli/... використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tools).
  • Gemini API проти Gemini CLI:
    • API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini».
    • CLI: OpenClaw виконує оболонковий виклик локального бінарника gemini; він має власну автентифікацію й може поводитися інакше (streaming/підтримка tools/розсинхронізація версій).

Live: матриця моделей (що ми охоплюємо)

Фіксованого «списку моделей CI» немає (live — opt-in), але це рекомендовані моделі, які варто регулярно охоплювати на dev-машині з ключами.

Сучасний smoke-набір (виклик tools + image)

Це запуск «поширених моделей», працездатність якого ми очікуємо зберігати:

  • OpenAI (не-Codex): openai/gpt-5.4 (необов’язково: openai/gpt-5.4-mini)
  • OpenAI Codex: openai-codex/gpt-5.4
  • Anthropic: anthropic/claude-opus-4-6 (або anthropic/claude-sonnet-4-6)
  • Google (Gemini API): google/gemini-3.1-pro-preview і google/gemini-3-flash-preview (уникайте старіших моделей Gemini 2.x)
  • Google (Antigravity): google-antigravity/claude-opus-4-6-thinking і google-antigravity/gemini-3-flash
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/MiniMax-M2.7

Запуск gateway smoke з tools + image: OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts

Базовий рівень: виклик tools (Read + необов’язковий Exec)

Виберіть щонайменше одну модель для кожного сімейства провайдерів:

  • OpenAI: openai/gpt-5.4 (або openai/gpt-5.4-mini)
  • Anthropic: anthropic/claude-opus-4-6 (або anthropic/claude-sonnet-4-6)
  • Google: google/gemini-3-flash-preview (або google/gemini-3.1-pro-preview)
  • Z.AI (GLM): zai/glm-4.7
  • MiniMax: minimax/MiniMax-M2.7

Необов’язкове додаткове покриття (бажано мати):

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

Vision: надсилання image (вкладення → мультимодальне повідомлення)

Додайте принаймні одну модель із підтримкою image у OPENCLAW_LIVE_GATEWAY_MODELS (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe.

Агрегатори / альтернативні gateway

Якщо у вас увімкнено ключі, ми також підтримуємо тестування через:

  • OpenRouter: openrouter/... (сотні моделей; використовуйте openclaw models scan, щоб знайти кандидатів із підтримкою tools+image)
  • OpenCode: opencode/... для Zen і opencode-go/... для Go (автентифікація через OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Інші провайдери, яких можна включити в live-матрицю (якщо у вас є облікові дані/конфігурація):

  • Вбудовані: openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, 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/agents/<agentId>/agent/auth-profiles.json (саме це означає «ключі профілів» у live-тестах)

  • Конфігурація: ~/.openclaw/openclaw.json (або OPENCLAW_CONFIG_PATH)

  • Каталог legacy state: ~/.openclaw/credentials/ (копіюється в підготовлений live home, якщо присутній, але не є основним сховищем ключів профілів)

  • Локальні live-запуски типово копіюють активну конфігурацію, файли auth-profiles.json для окремих агентів, legacy credentials/ і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені live home пропускають workspace/ і sandboxes/, а перевизначення шляхів agents.*.workspace / agentDir видаляються, щоб probes не працювали у вашому реальному workspace хоста.

Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому ~/.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

BytePlus coding plan live

  • Тест: src/agents/byteplus.live.test.ts
  • Увімкнення: BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
  • Необов’язкове перевизначення моделі: BYTEPLUS_CODING_MODEL=ark-code-latest

ComfyUI workflow media live

  • Тест: extensions/comfy/comfy.live.test.ts
  • Увімкнення: OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
  • Обсяг:
    • Перевіряє вбудовані шляхи comfy для image, video і music_generate
    • Пропускає кожну можливість, якщо models.providers.comfy.<capability> не налаштовано
    • Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin-а

Live генерації image

  • Тест: src/image-generation/runtime.live.test.ts
  • Команда: pnpm test:live src/image-generation/runtime.live.test.ts
  • Harness: pnpm test:live:media image
  • Обсяг:
    • Перелічує кожен зареєстрований plugin провайдера генерації image
    • Завантажує відсутні env-змінні провайдера з вашої оболонки входу (~/.profile) перед probing
    • Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в auth-profiles.json не маскували реальні облікові дані оболонки
    • Пропускає провайдерів без придатної автентифікації/профілю/моделі
    • Запускає стандартні варіанти генерації image через спільну runtime-можливість:
      • google:flash-generate
      • google:pro-generate
      • google:pro-edit
      • openai:default-generate
  • Поточні вбудовані провайдери, що охоплюються:
    • openai
    • google
  • Необов’язкове звуження:
    • OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"
    • OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"
    • OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"
  • Необов’язкова поведінка автентифікації:
    • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env

Live генерації музики

  • Тест: extensions/music-generation-providers.live.test.ts
  • Увімкнення: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
  • Harness: pnpm test:live:media music
  • Обсяг:
    • Перевіряє спільний вбудований шлях провайдера генерації музики
    • Наразі охоплює Google і MiniMax
    • Завантажує env-змінні провайдера з вашої оболонки входу (~/.profile) перед probing
    • Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в auth-profiles.json не маскували реальні облікові дані оболонки
    • Пропускає провайдерів без придатної автентифікації/профілю/моделі
    • Запускає обидва оголошені runtime-режими, коли вони доступні:
      • generate із введенням лише prompt
      • edit, коли провайдер оголошує capabilities.edit.enabled
    • Поточне покриття спільної лінії:
      • google: generate, edit
      • minimax: generate
      • comfy: окремий live-файл Comfy, а не цей спільний sweep
  • Необов’язкове звуження:
    • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
    • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
  • Необов’язкова поведінка автентифікації:
    • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env

Live генерації відео

  • Тест: extensions/video-generation-providers.live.test.ts
  • Увімкнення: OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
  • Harness: pnpm test:live:media video
  • Обсяг:
    • Перевіряє спільний вбудований шлях провайдера генерації відео
    • Завантажує env-змінні провайдера з вашої оболонки входу (~/.profile) перед probing
    • Типово використовує live/env API-ключі раніше, ніж збережені профілі автентифікації, щоб застарілі тестові ключі в auth-profiles.json не маскували реальні облікові дані оболонки
    • Пропускає провайдерів без придатної автентифікації/профілю/моделі
    • Запускає обидва оголошені runtime-режими, коли вони доступні:
      • generate із введенням лише prompt
      • imageToVideo, коли провайдер оголошує capabilities.imageToVideo.enabled і вибраний провайдер/модель приймає локальний вхід image на основі buffer у спільному sweep
      • videoToVideo, коли провайдер оголошує capabilities.videoToVideo.enabled і вибраний провайдер/модель приймає локальний вхід video на основі buffer у спільному sweep
    • Поточні оголошені, але пропущені провайдери imageToVideo у спільному sweep:
      • vydra, оскільки вбудований veo3 підтримує лише текст, а вбудований kling вимагає віддалений URL image
    • Покриття Vydra, специфічне для провайдера:
      • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
      • цей файл запускає veo3 text-to-video плюс лінію kling, яка типово використовує fixture із віддаленим URL image
    • Поточне live-покриття videoToVideo:
      • лише runway, коли вибрана модель — runway/gen4_aleph
    • Поточні оголошені, але пропущені провайдери videoToVideo у спільному sweep:
      • alibaba, qwen, xai, оскільки ці шляхи наразі вимагають віддалені URL-посилання http(s) / reference MP4
      • google, оскільки поточна спільна лінія Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільному sweep
      • openai, оскільки поточна спільна лінія не гарантує доступу до org-specific video inpaint/remix
  • Необов’язкове звуження:
    • OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"
    • OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"
  • Необов’язкова поведінка автентифікації:
    • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише через env

Media live harness

  • Команда: pnpm test:live:media
  • Призначення:
    • Запускає спільні live-набори image, music і video через один стандартний entrypoint репозиторію
    • Автоматично завантажує відсутні env-змінні провайдера з ~/.profile
    • Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію
    • Повторно використовує scripts/test-live.mjs, тому поведінка heartbeat і quiet-mode залишається узгодженою
  • Приклади:
    • pnpm test:live:media
    • pnpm test:live:media image video --providers openai,google,minimax
    • pnpm test:live:media video --video-providers openai,runway --all-providers
    • pnpm test:live:media music --quiet

Docker-ранери (необов’язкові перевірки «працює в Linux»)

Ці Docker-ранери поділяються на дві групи:

  • Docker-ранери live-моделей: test:docker:live-models і test:docker:live-gateway запускають лише свій відповідний profile-key live-файл усередині Docker-образу репозиторію (src/agents/models.profiles.live.test.ts і src/gateway/gateway-models.profiles.live.test.ts), монтують ваш локальний каталог конфігурації та workspace (і використовують ~/.profile, якщо його змонтовано). Відповідні локальні entrypoint-и: test:live:models-profiles і test:live:gateway-profiles.
  • Docker-ранери live типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним: test:docker:live-models типово використовує OPENCLAW_LIVE_MAX_MODELS=12, а test:docker:live-gateway типово використовує OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 і OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Перевизначайте ці env-змінні, коли ви явно хочете більший вичерпний scan.
  • test:docker:all один раз збирає live Docker-образ через test:docker:live-build, а потім повторно використовує його для двох Docker-ліній live.
  • Контейнерні smoke-ранери: test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels і test:docker:plugins запускають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня.

Docker-ранери live-моделей також bind-mount лише потрібні homes автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста:

  • Прямі моделі: pnpm test:docker:live-models (скрипт: scripts/test-live-models-docker.sh)
  • ACP bind smoke: pnpm test:docker:live-acp-bind (скрипт: scripts/test-live-acp-bind-docker.sh)
  • CLI backend smoke: pnpm test:docker:live-cli-backend (скрипт: scripts/test-live-cli-backend-docker.sh)
  • Gateway + dev agent: pnpm test:docker:live-gateway (скрипт: scripts/test-live-gateway-models-docker.sh)
  • Open WebUI live smoke: pnpm test:docker:openwebui (скрипт: scripts/e2e/openwebui-docker.sh)
  • Майстер onboarding (TTY, повне scaffolding): pnpm test:docker:onboard (скрипт: scripts/e2e/onboard-docker.sh)
  • Мережа gateway (два контейнери, WS auth + health): pnpm test:docker:gateway-network (скрипт: scripts/e2e/gateway-network-docker.sh)
  • MCP channel bridge (ініціалізований Gateway + stdio bridge + raw Claude notification-frame smoke): pnpm test:docker:mcp-channels (скрипт: scripts/e2e/mcp-channels-docker.sh)
  • Plugins (install smoke + псевдонім /plugin + семантика перезапуску Claude-bundle): pnpm test:docker:plugins (скрипт: scripts/e2e/plugins-docker.sh)

Docker-ранери live-моделей також bind-mount поточний checkout лише для читання й підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ компактним, але водночас запускає Vitest точно на ваших локальних source/config. Крок підготовки пропускає великі лише локальні кеші та результати збірки застосунків, як-от .pnpm-store, .worktrees, __openclaw_vitest__ і локальні для застосунку каталоги .build або вивід Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання артефактів, специфічних для машини. Вони також установлюють OPENCLAW_SKIP_CHANNELS=1, щоб live-probes gateway не запускали реальні воркери каналів Telegram/Discord тощо всередині контейнера. test:docker:live-models усе одно запускає pnpm test:live, тож також передавайте OPENCLAW_LIVE_GATEWAY_*, коли потрібно звузити або виключити gateway live-покриття з цієї Docker-лінії. test:docker:openwebui — це smoke-тест сумісності вищого рівня: він запускає контейнер gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що /api/models показує openclaw/default, а потім надсилає реальний chat-запит через проксі /api/chat/completions Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути образ Open WebUI, а Open WebUI може знадобитися завершити власне cold-start налаштування. Ця лінія очікує придатний ключ live-моделі, а OPENCLAW_PROFILE_FILE (типово ~/.profile) є основним способом надати його в Docker-запусках. Успішні запуски виводять невеликий JSON payload на кшталт { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels навмисно детермінований і не потребує реального облікового запису Telegram, Discord або iMessage. Він запускає контейнер Gateway з попередньою ініціалізацією, запускає другий контейнер, який піднімає openclaw mcp serve, а потім перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення каналу + дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень напряму перевіряє raw stdio MCP frames, тож smoke-тест перевіряє те, що bridge справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта.

Ручний smoke plain-language thread для ACP (не CI):

  • bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
  • Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його.

Корисні env-змінні:

  • OPENCLAW_CONFIG_DIR=... (типово: ~/.openclaw) монтується в /home/node/.openclaw
  • OPENCLAW_WORKSPACE_DIR=... (типово: ~/.openclaw/workspace) монтується в /home/node/.openclaw/workspace
  • OPENCLAW_PROFILE_FILE=... (типово: ~/.profile) монтується в /home/node/.profile і використовується перед запуском тестів
  • OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (типово: ~/.cache/openclaw/docker-cli-tools) монтується в /home/node/.npm-global для кешованих встановлень CLI усередині Docker
  • Зовнішні каталоги/файли автентифікації CLI в $HOME монтуються лише для читання в /host-auth..., а потім копіюються в /home/node/... перед початком тестів
    • Типові каталоги: .minimax
    • Типові файли: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
    • Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
    • Ручне перевизначення: OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none або список через кому, як-от OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
  • OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... для звуження запуску
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... для фільтрації провайдерів усередині контейнера
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env)
  • OPENCLAW_OPENWEBUI_MODEL=..., щоб вибрати модель, яку gateway показує для smoke Open WebUI
  • OPENCLAW_OPENWEBUI_PROMPT=..., щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI
  • OPENWEBUI_IMAGE=..., щоб перевизначити pinned тег образу Open WebUI

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

Після редагування документації запускайте перевірки документації: pnpm check:docs. Коли вам також потрібна повна перевірка anchor у Mintlify для заголовків на сторінці, запускайте: pnpm docs:check-links:anchors.

Офлайнова регресія (безпечна для CI)

Це регресії «реального конвеєра» без реальних провайдерів:

  • Виклик tools у gateway (mock OpenAI, реальний цикл gateway + agent): src/gateway/gateway.test.ts (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
  • Майстер gateway (WS wizard.start/wizard.next, із примусовим записом config + auth): src/gateway/gateway.test.ts (випадок: "runs wizard over ws and writes auth token config")

Оцінювання надійності агента (Skills)

У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»:

  • Mock виклику tools через реальний цикл gateway + agent (src/gateway/gateway.test.ts).
  • Наскрізні потоки майстра, що перевіряють wiring сеансу та ефекти конфігурації (src/gateway/gateway.test.ts).

Що ще бракує для Skills (див. Skills):

  • Прийняття рішень: коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)?
  • Дотримання вимог: чи читає агент SKILL.md перед використанням і чи виконує потрібні кроки/аргументи?
  • Контракти робочого процесу: багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сеансу й межі sandbox.

Майбутні оцінювання мають насамперед залишатися детермінованими:

  • Runner сценаріїв із mock-провайдерами для перевірки викликів tools + їх порядку, читання skill-файлів і wiring сеансу.
  • Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, gating, prompt injection).
  • Необов’язкові live-evals (opt-in, із керуванням через env) лише після того, як буде готовий безпечний для CI набір.

Контрактні тести (форма plugin і channel)

Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму інтерфейсному контракту. Вони перебирають усі виявлені plugins і запускають набір перевірок форми та поведінки. Типова unit-лінія pnpm test навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider.

Команди

  • Усі контракти: pnpm test:contracts
  • Лише контракти channel: pnpm test:contracts:channels
  • Лише контракти provider: pnpm test:contracts:plugins

Контракти channel

Розташовані в src/channels/plugins/contracts/*.contract.test.ts:

  • plugin - Базова форма plugin-а (id, name, capabilities)
  • setup - Контракт майстра налаштування
  • session-binding - Поведінка прив’язування сеансу
  • outbound-payload - Структура payload вихідного повідомлення
  • inbound - Обробка вхідних повідомлень
  • actions - Обробники дій каналу
  • threading - Обробка ID thread
  • directory - API каталогу/списку учасників
  • group-policy - Застосування групової політики

Контракти статусу provider

Розташовані в src/plugins/contracts/*.contract.test.ts.

  • status - Перевірки статусу channel
  • registry - Форма реєстру plugin-ів

Контракти provider

Розташовані в src/plugins/contracts/*.contract.test.ts:

  • auth - Контракт потоку автентифікації
  • auth-choice - Вибір/підбір автентифікації
  • catalog - API каталогу моделей
  • discovery - Виявлення plugin-ів
  • loader - Завантаження plugin-ів
  • runtime - Runtime provider-а
  • shape - Форма/інтерфейс plugin-а
  • wizard - Майстер налаштування

Коли запускати

  • Після змін у plugin-sdk exports або subpaths
  • Після додавання чи зміни channel або provider plugin-а
  • Після рефакторингу реєстрації plugin-ів або їх виявлення

Контрактні тести запускаються в CI й не потребують реальних API-ключів.

Додавання регресій (рекомендації)

Коли ви виправляєте проблему provider/model, виявлену в live:

  • За можливості додайте безпечну для CI регресію (mock/stub provider-а або захоплення точної форми трансформації запиту)
  • Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env-змінні
  • Намагайтеся націлюватися на найменший шар, який виявляє баг:
    • баг перетворення/повторного програвання запиту provider-а → тест прямих моделей
    • баг конвеєра сеансу/історії/tool gateway → gateway live smoke або безпечний для CI mock-тест gateway
  • Захисне обмеження обходу SecretRef:
    • src/secrets/exec-secret-ref-id-parity.test.ts виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (listSecretTargetRegistryEntries()), а потім перевіряє, що exec id сегментів обходу відхиляються.
    • Якщо ви додаєте нове сімейство цілей SecretRef includeInPlan у src/secrets/target-registry-data.ts, оновіть classifyTargetClass у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити.