docs/docs/fr/help/testing.md

read_when	summary	title	x-i18n
Exécuter les tests localement ou en CI Ajouter des tests de régression pour les bogues de modèle/provider Débogage du comportement de la gateway + de l’agent	Kit de test : suites unitaires/e2e/live, exécuteurs Docker et ce que couvre chaque test	Tests	generated_at model provider source_hash source_path workflow 2026-04-11T02:45:10Z gpt-5.4 openai 55e75d056306a77b0d112a3902c08c7771f53533250847fc3d785b1df3e0e9e7 help/testing.md 15

Tests

OpenClaw dispose de trois suites Vitest (unit/integration, e2e, live) et d’un petit ensemble d’exécuteurs Docker.

Ce document est un guide « comment nous testons » :

• Ce que couvre chaque suite (et ce qu’elle ne couvre délibérément pas)
• Quelles commandes exécuter pour les workflows courants (local, avant push, débogage)
• Comment les tests live découvrent les identifiants et sélectionnent les modèles/providers
• Comment ajouter des régressions pour des problèmes réels de modèle/provider

Démarrage rapide

La plupart du temps :

• Barrière complète (attendue avant un push) : pnpm build && pnpm check && pnpm test
• Exécution locale plus rapide de la suite complète sur une machine bien dotée : pnpm test:max
• Boucle de watch Vitest directe : pnpm test:watch
• Le ciblage direct de fichiers route désormais aussi les chemins d’extensions/canaux : pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Préférez d’abord les exécutions ciblées lorsque vous itérez sur un seul échec.
• Site QA adossé à Docker : pnpm qa:lab:up
• Voie QA adossée à une VM Linux : pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Lorsque vous touchez aux tests ou souhaitez plus de confiance :

• Barrière de couverture : pnpm test:coverage
• Suite E2E : pnpm test:e2e

Lors du débogage de providers/modèles réels (nécessite de vrais identifiants) :

• Suite live (modèles + sondes gateway outil/image) : pnpm test:live
• Cibler discrètement un seul fichier live : pnpm test:live -- src/agents/models.profiles.live.test.ts

Astuce : lorsque vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous.

Exécuteurs spécifiques à la QA

Ces commandes se trouvent à côté des suites de test principales lorsque vous avez besoin d’un réalisme QA-lab :

• pnpm openclaw qa suite
  • Exécute directement sur l’hôte des scénarios QA adossés au dépôt.
  • Exécute par défaut plusieurs scénarios sélectionnés en parallèle avec des workers gateway isolés, jusqu’à 64 workers ou le nombre de scénarios sélectionnés. Utilisez --concurrency <count> pour ajuster le nombre de workers, ou --concurrency 1 pour retrouver l’ancienne voie sérielle.
• pnpm openclaw qa suite --runner multipass
  • Exécute la même suite QA dans une VM Linux Multipass jetable.
  • Conserve le même comportement de sélection de scénarios que qa suite sur l’hôte.
  • Réutilise les mêmes drapeaux de sélection provider/modèle que qa suite.
  • Les exécutions live transmettent les entrées d’authentification QA prises en charge qui sont pratiques pour l’invité : les clés provider basées sur l’environnement, le chemin de configuration du provider live QA et CODEX_HOME lorsqu’il est présent.
  • Les répertoires de sortie doivent rester sous la racine du dépôt pour que l’invité puisse écrire en retour via l’espace de travail monté.
  • Écrit le rapport QA normal + le résumé ainsi que les logs Multipass sous .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Démarre le site QA adossé à Docker pour un travail QA de type opérateur.
• pnpm openclaw qa matrix
  • Exécute la voie QA live Matrix contre un homeserver Tuwunel jetable adossé à Docker.
  • Provisionne trois utilisateurs Matrix temporaires (driver, sut, observer) plus un salon privé, puis démarre un processus enfant de gateway QA avec le vrai plugin Matrix comme transport du SUT.
  • Utilise par défaut l’image Tuwunel stable épinglée ghcr.io/matrix-construct/tuwunel:v1.5.1. Remplacez-la avec OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE lorsque vous devez tester une autre image.
  • Écrit un rapport QA Matrix, un résumé et un artefact des événements observés sous .artifacts/qa-e2e/....
• pnpm openclaw qa telegram
  • Exécute la voie QA live Telegram contre un vrai groupe privé en utilisant les tokens de bot driver et SUT depuis l’environnement.
  • Nécessite OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN et OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. L’identifiant de groupe doit être l’identifiant numérique du chat Telegram.
  • Nécessite deux bots distincts dans le même groupe privé, avec le bot SUT exposant un nom d’utilisateur Telegram.
  • Pour une observation bot-à-bot stable, activez le mode Bot-to-Bot Communication Mode dans @BotFather pour les deux bots et assurez-vous que le bot driver peut observer le trafic des bots du groupe.
  • Écrit un rapport QA Telegram, un résumé et un artefact des messages observés sous .artifacts/qa-e2e/....

Les voies de transport live partagent un contrat standard unique afin que les nouveaux transports ne dérivent pas.

qa-channel reste la suite QA synthétique large et ne fait pas partie de la matrice de couverture des transports live.

Voie	Canary	Filtrage des mentions	Blocage par liste d’autorisation	Réponse de premier niveau	Reprise après redémarrage	Suivi de fil	Isolation de fil	Observation des réactions	Commande d’aide
Matrix	x	x	x	x	x	x	x	x
Telegram	x								x

Suites de test (ce qui s’exécute où)

Considérez les suites comme ayant un « réalisme croissant » (et une instabilité/un coût croissants) :

Unit / integration (par défaut)

• Commande : pnpm test
• Configuration : dix exécutions de shards séquentielles (vitest.full-*.config.ts) sur les projets Vitest ciblés existants
• Fichiers : inventaires core/unit sous src/**/*.test.ts, packages/**/*.test.ts, test/**/*.test.ts, et les tests Node ui sur liste blanche couverts par vitest.unit.config.ts
• Portée :
  • Tests unitaires purs
  • Tests d’intégration en processus (authentification gateway, routage, outillage, parsing, configuration)
  • Régressions déterministes pour des bogues connus
• Attentes :
  • S’exécute en CI
  • Aucune vraie clé requise
  • Doit être rapide et stable
• Note sur les projets :
  • pnpm test sans ciblage exécute désormais onze configurations de shards plus petites (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) au lieu d’un seul énorme processus natif de projet racine. Cela réduit le pic de RSS sur les machines chargées et évite que le travail auto-reply/extension n’affame les suites non liées.
  • pnpm test --watch utilise toujours le graphe de projets racine natif vitest.config.ts, car une boucle de watch multi-shards n’est pas pratique.
  • pnpm test, pnpm test:watch et pnpm test:perf:imports routent d’abord les cibles explicites de fichier/répertoire via des voies ciblées, afin que pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts évite de payer le coût complet de démarrage du projet racine.
  • pnpm test:changed développe les chemins git modifiés vers ces mêmes voies ciblées lorsque le diff ne touche que des fichiers source/de test routables ; les modifications de config/setup reviennent toujours à la réexécution large du projet racine.
  • Les tests unitaires légers en imports depuis les agents, commandes, plugins, helpers auto-reply, plugin-sdk et zones utilitaires pures similaires passent par la voie unit-fast, qui ignore test/setup-openclaw-runtime.ts ; les fichiers stateful/lourds côté runtime restent sur les voies existantes.
  • Certains fichiers source helpers de plugin-sdk et commands font aussi correspondre les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications de helpers évitent de réexécuter toute la suite lourde de ce répertoire.
  • auto-reply dispose désormais de trois compartiments dédiés : helpers core de premier niveau, tests d’intégration reply.* de premier niveau, et le sous-arbre src/auto-reply/reply/**. Cela garde le travail le plus lourd du harnais reply hors des tests bon marché de statut/fragment/token.
• Note sur l’exécuteur embarqué :
  • Lorsque vous modifiez les entrées de découverte des outils de message ou le contexte runtime de compaction, conservez les deux niveaux de couverture.
  • Ajoutez des régressions helpers ciblées pour les frontières pures de routage/normalisation.
  • Conservez également en bon état les suites d’intégration de l’exécuteur embarqué : src/agents/pi-embedded-runner/compact.hooks.test.ts, src/agents/pi-embedded-runner/run.overflow-compaction.test.ts, et src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts.
  • Ces suites vérifient que les identifiants ciblés et le comportement de compaction traversent toujours les vrais chemins run.ts / compact.ts ; des tests helpers seuls ne suffisent pas à remplacer ces parcours d’intégration.
• Note sur le pool :
  • La configuration Vitest de base utilise désormais threads par défaut.
  • La configuration Vitest partagée fixe également isolate: false et utilise l’exécuteur non isolé sur les projets racine, e2e et live.
  • La voie UI racine conserve sa configuration jsdom et son optimiseur, mais s’exécute maintenant elle aussi sur l’exécuteur partagé non isolé.
  • Chaque shard pnpm test hérite des mêmes valeurs par défaut threads + isolate: false depuis la configuration Vitest partagée.
  • Le lanceur partagé scripts/run-vitest.mjs ajoute désormais aussi --no-maglev par défaut pour les processus Node enfants de Vitest afin de réduire l’agitation de compilation V8 pendant les grosses exécutions locales. Définissez OPENCLAW_VITEST_ENABLE_MAGLEV=1 si vous devez comparer avec le comportement V8 standard.
• Note sur l’itération locale rapide :
  • pnpm test:changed passe par des voies ciblées lorsque les chemins modifiés se mappent proprement à une suite plus petite.
  • pnpm test:max et pnpm test:changed:max conservent le même comportement de routage, simplement avec une limite de workers plus élevée.
  • L’auto-dimensionnement local des workers est désormais intentionnellement conservateur et réduit aussi son agressivité lorsque la charge moyenne de l’hôte est déjà élevée, de sorte que plusieurs exécutions Vitest simultanées causent moins de dégâts par défaut.
  • La configuration Vitest de base marque les fichiers de projets/configuration comme forceRerunTriggers pour que les réexécutions en mode changed restent correctes quand le câblage des tests change.
  • La configuration garde OPENCLAW_VITEST_FS_MODULE_CACHE activé sur les hôtes pris en charge ; définissez OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path si vous souhaitez un emplacement de cache explicite pour un profilage direct.
• Note de débogage des performances :
  • pnpm test:perf:imports active le reporting de durée d’import Vitest ainsi qu’une sortie détaillée par import.
  • pnpm test:perf:imports:changed restreint la même vue de profilage aux fichiers modifiés depuis origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> compare test:changed routé au chemin natif du projet racine pour ce diff validé et affiche le temps mur ainsi que le RSS maximal macOS.
• pnpm test:perf:changed:bench -- --worktree mesure l’arbre de travail modifié actuel en routant la liste des fichiers modifiés via scripts/test-projects.mjs et la configuration Vitest racine.
  • pnpm test:perf:profile:main écrit un profil CPU du thread principal pour la surcharge de démarrage et de transformation de Vitest/Vite.
  • pnpm test:perf:profile:runner écrit des profils CPU+heap de l’exécuteur pour la suite unitaire avec le parallélisme de fichiers désactivé.

E2E (test smoke gateway)

• Commande : pnpm test:e2e
• Configuration : vitest.e2e.config.ts
• Fichiers : src/**/*.e2e.test.ts, test/**/*.e2e.test.ts
• Valeurs par défaut du runtime :
  • Utilise les threads Vitest avec isolate: false, comme le reste du dépôt.
  • Utilise des workers adaptatifs (CI : jusqu’à 2, local : 1 par défaut).
  • S’exécute en mode silencieux par défaut pour réduire la surcharge d’E/S console.
• Surcharges utiles :
  • OPENCLAW_E2E_WORKERS=<n> pour forcer le nombre de workers (plafonné à 16).
  • OPENCLAW_E2E_VERBOSE=1 pour réactiver la sortie console verbeuse.
• Portée :
  • Comportement end-to-end gateway multi-instance
  • Surfaces WebSocket/HTTP, appairage de nœuds et réseau plus lourd
• Attentes :
  • S’exécute en CI (lorsqu’activé dans le pipeline)
  • Aucune vraie clé requise
  • Plus de composants en mouvement que les tests unitaires (peut être plus lent)

E2E : test smoke du backend OpenShell

• Commande : pnpm test:e2e:openshell
• Fichier : test/openshell-sandbox.e2e.test.ts
• Portée :
  • Démarre une gateway OpenShell isolée sur l’hôte via Docker
  • Crée une sandbox à partir d’un Dockerfile local temporaire
  • Exerce le backend OpenShell d’OpenClaw via de vrais sandbox ssh-config + exécutions SSH
  • Vérifie le comportement du système de fichiers canonique distant via le pont fs de la sandbox
• Attentes :
  • Uniquement sur adhésion volontaire ; ne fait pas partie de l’exécution par défaut de pnpm test:e2e
  • Nécessite un openshell CLI local ainsi qu’un démon Docker fonctionnel
  • Utilise des HOME / XDG_CONFIG_HOME isolés, puis détruit la gateway de test et la sandbox
• Surcharges utiles :
  • OPENCLAW_E2E_OPENSHELL=1 pour activer le test lors de l’exécution manuelle de la suite e2e plus large
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell pour pointer vers un binaire CLI non par défaut ou un script wrapper

Live (vrais providers + vrais modèles)

• Commande : pnpm test:live
• Configuration : vitest.live.config.ts
• Fichiers : src/**/*.live.test.ts
• Par défaut : activé par pnpm test:live (définit OPENCLAW_LIVE_TEST=1)
• Portée :
  • « Est-ce que ce provider/modèle fonctionne réellement aujourd’hui avec de vrais identifiants ? »
  • Détecter les changements de format des providers, les particularités d’appel d’outils, les problèmes d’authentification et le comportement face aux limites de débit
• Attentes :
  • Délibérément non stable en CI (vrais réseaux, vraies politiques de providers, quotas, pannes)
  • Coûte de l’argent / consomme des limites de débit
  • Préférez exécuter des sous-ensembles restreints plutôt que « tout »
• Les exécutions live chargent ~/.profile pour récupérer les clés API manquantes.
• Par défaut, les exécutions live isolent quand même HOME et copient le matériel de config/auth dans un home de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai ~/.openclaw.
• Définissez OPENCLAW_LIVE_USE_REAL_HOME=1 uniquement lorsque vous avez intentionnellement besoin que les tests live utilisent votre vrai répertoire personnel.
• pnpm test:live utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression [live] ..., mais supprime l’avis supplémentaire sur ~/.profile et coupe les logs d’amorçage de la gateway / le bruit Bonjour. Définissez OPENCLAW_LIVE_TEST_QUIET=0 si vous voulez récupérer les logs de démarrage complets.
• Rotation des clés API (spécifique au provider) : définissez *_API_KEYS au format virgules/points-virgules ou *_API_KEY_1, *_API_KEY_2 (par exemple OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) ou une surcharge par live via OPENCLAW_LIVE_*_KEY ; les tests réessaient en cas de réponses de limite de débit.
• Sortie de progression/heartbeat :
  • Les suites live émettent désormais des lignes de progression vers stderr afin que les appels longs aux providers paraissent visiblement actifs même lorsque la capture console de Vitest est silencieuse.
  • vitest.live.config.ts désactive l’interception console de Vitest afin que les lignes de progression provider/gateway soient diffusées immédiatement pendant les exécutions live.
  • Ajustez les heartbeats du modèle direct avec OPENCLAW_LIVE_HEARTBEAT_MS.
  • Ajustez les heartbeats de la gateway/des sondes avec OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

Quelle suite dois-je exécuter ?

Utilisez ce tableau de décision :

• Modification de logique/tests : exécutez pnpm test (et pnpm test:coverage si vous avez beaucoup modifié)
• Modification du réseau gateway / protocole WS / appairage : ajoutez pnpm test:e2e
• Débogage de « mon bot est hors service » / échecs spécifiques à un provider / appel d’outils : exécutez un pnpm test:live restreint

Live : balayage des capacités de nœud Android

• Test : src/gateway/android-node.capabilities.live.test.ts
• Script : pnpm android:test:integration
• Objectif : invoquer chaque commande actuellement annoncée par un nœud Android connecté et valider le comportement du contrat de commande.
• Portée :
  • Préconditionné/configuration manuelle (la suite n’installe, n’exécute ni n’appaire pas l’application).
  • Validation node.invoke de la gateway, commande par commande, pour le nœud Android sélectionné.
• Préconfiguration requise :
  • Application Android déjà connectée + appairée à la gateway.
  • Application maintenue au premier plan.
  • Permissions/consentements de capture accordés pour les capacités que vous attendez de voir réussir.
• Surcharges de cible facultatives :
  • OPENCLAW_ANDROID_NODE_ID ou OPENCLAW_ANDROID_NODE_NAME.
  • OPENCLAW_ANDROID_GATEWAY_URL / OPENCLAW_ANDROID_GATEWAY_TOKEN / OPENCLAW_ANDROID_GATEWAY_PASSWORD.
• Détails complets de configuration Android : Application Android

Live : test smoke des modèles (clés de profil)

Les tests live sont répartis en deux couches afin de pouvoir isoler les échecs :

• Le « modèle direct » nous indique si le provider/modèle peut répondre tout court avec la clé donnée.
• Le « test smoke gateway » nous indique si le pipeline complet gateway+agent fonctionne pour ce modèle (sessions, historique, outils, politique sandbox, etc.).

Couche 1 : complétion directe du modèle (sans gateway)

• Test : src/agents/models.profiles.live.test.ts
• Objectif :
  • Énumérer les modèles découverts
  • Utiliser getApiKeyForModel pour sélectionner les modèles pour lesquels vous avez des identifiants
  • Exécuter une petite complétion par modèle (et des régressions ciblées si nécessaire)
• Comment l’activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous invoquez Vitest directement)
• Définissez OPENCLAW_LIVE_MODELS=modern (ou all, alias de modern) pour réellement exécuter cette suite ; sinon elle est ignorée afin que pnpm test:live reste concentré sur le test smoke de la gateway
• Comment sélectionner les modèles :
  • OPENCLAW_LIVE_MODELS=modern pour exécuter la liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_MODELS=all est un alias de la liste d’autorisation moderne
  • ou OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..." (liste d’autorisation séparée par des virgules)
  • Les balayages modern/all utilisent par défaut un plafond organisé à fort signal ; définissez OPENCLAW_LIVE_MAX_MODELS=0 pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit.
• Comment sélectionner les providers :
  • OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli" (liste d’autorisation séparée par des virgules)
• D’où viennent les clés :
  • Par défaut : dépôt de profils et solutions de repli via l’environnement
  • Définissez OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour imposer uniquement le dépôt de profils
• Pourquoi cela existe :
  • Sépare « l’API du provider est cassée / la clé est invalide » de « le pipeline d’agent de la gateway est cassé »
  • Contient de petites régressions isolées (exemple : flux OpenAI Responses/Codex Responses avec replay de raisonnement + appels d’outils)

Couche 2 : test smoke gateway + agent de dev (ce que fait réellement "@openclaw")

• Test : src/gateway/gateway-models.profiles.live.test.ts
• Objectif :
  • Démarrer une gateway en processus
  • Créer/modifier une session agent:dev:* (surcharge de modèle par exécution)
  • Itérer sur les modèles avec clés et vérifier :
    • une réponse « significative » (sans outils)
    • qu’un vrai appel d’outil fonctionne (sonde read)
    • des sondes d’outils supplémentaires facultatives (sonde exec+read)
    • que les chemins de régression OpenAI (appel d’outil seul → suivi) continuent de fonctionner
• Détails des sondes (pour pouvoir expliquer rapidement les échecs) :
  • sonde read : le test écrit un fichier nonce dans l’espace de travail et demande à l’agent de le read puis de renvoyer le nonce.
  • sonde exec+read : le test demande à l’agent de exec l’écriture d’un nonce dans un fichier temporaire, puis de le read.
  • sonde image : le test joint un PNG généré (chat + code aléatoire) et attend du modèle qu’il renvoie cat <CODE>.
  • Référence d’implémentation : src/gateway/gateway-models.profiles.live.test.ts et src/gateway/live-image-probe.ts.
• Comment l’activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous invoquez Vitest directement)
• Comment sélectionner les modèles :
  • Par défaut : liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
  • OPENCLAW_LIVE_GATEWAY_MODELS=all est un alias de la liste d’autorisation moderne
  • Ou définissez OPENCLAW_LIVE_GATEWAY_MODELS="provider/model" (ou une liste séparée par des virgules) pour restreindre
  • Les balayages gateway modern/all utilisent par défaut un plafond organisé à fort signal ; définissez OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0 pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit.
• Comment sélectionner les providers (éviter « OpenRouter tout ») :
  • OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax" (liste d’autorisation séparée par des virgules)
• Les sondes d’outil + d’image sont toujours activées dans ce test live :
  • sonde read + sonde exec+read (stress des outils)
  • la sonde image s’exécute lorsque le modèle annonce la prise en charge des entrées image
  • Flux (haut niveau) :
    • Le test génère un minuscule PNG avec « CAT » + un code aléatoire (src/gateway/live-image-probe.ts)
    • L’envoie via agent attachments: [{ mimeType: "image/png", content: "<base64>" }]
    • La gateway analyse les pièces jointes en images[] (src/gateway/server-methods/agent.ts + src/gateway/chat-attachments.ts)
    • L’agent embarqué transmet un message utilisateur multimodal au modèle
    • Assertion : la réponse contient cat + le code (tolérance OCR : petites erreurs autorisées)

Astuce : pour voir ce que vous pouvez tester sur votre machine (et les identifiants exacts provider/model), exécutez :

openclaw models list
openclaw models list --json

Live : test smoke du backend CLI (Claude, Codex, Gemini ou autres CLI locaux)

• Test : src/gateway/gateway-cli-backend.live.test.ts
• Objectif : valider le pipeline Gateway + agent à l’aide d’un backend CLI local, sans toucher à votre configuration par défaut.
• Les valeurs par défaut de test smoke spécifiques au backend vivent avec la définition cli-backend.ts de l’extension propriétaire.
• Activer :
  • pnpm test:live (ou OPENCLAW_LIVE_TEST=1 si vous invoquez Vitest directement)
  • OPENCLAW_LIVE_CLI_BACKEND=1
• Valeurs par défaut :
  • Provider/modèle par défaut : claude-cli/claude-sonnet-4-6
  • Le comportement des commandes/arguments/images provient des métadonnées du plugin backend CLI propriétaire.
• Surcharges (facultatives) :
  • 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 pour envoyer une vraie pièce jointe image (les chemins sont injectés dans le prompt).
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image" pour passer les chemins de fichiers image comme arguments CLI au lieu d’une injection dans le prompt.
  • OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat" (ou "list") pour contrôler la façon dont les arguments image sont passés lorsque IMAGE_ARG est défini.
  • OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1 pour envoyer un deuxième tour et valider le flux de reprise.
  • OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0 pour désactiver la sonde de continuité par défaut Claude Sonnet -> Opus dans la même session (définissez-la à 1 pour la forcer lorsque le modèle sélectionné prend en charge une cible de changement).

Exemple :

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

Recette Docker :

pnpm test:docker:live-cli-backend

Recettes Docker mono-provider :

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

Remarques :

• L’exécuteur Docker se trouve dans scripts/test-live-cli-backend-docker.sh.
• Il exécute le test smoke live du backend CLI dans l’image Docker du dépôt en tant qu’utilisateur non root node.
• Il résout les métadonnées de test smoke CLI depuis l’extension propriétaire, puis installe le paquet CLI Linux correspondant (@anthropic-ai/claude-code, @openai/codex, ou @google/gemini-cli) dans un préfixe inscriptible mis en cache à OPENCLAW_DOCKER_CLI_TOOLS_DIR (par défaut : ~/.cache/openclaw/docker-cli-tools).
• pnpm test:docker:live-cli-backend:claude-subscription nécessite une authentification OAuth portable d’abonnement Claude Code via soit ~/.claude/.credentials.json avec claudeAiOauth.subscriptionType, soit CLAUDE_CODE_OAUTH_TOKEN depuis claude setup-token. Il prouve d’abord un claude -p direct dans Docker, puis exécute deux tours Gateway CLI-backend sans préserver les variables d’environnement de clé API Anthropic. Cette voie d’abonnement désactive par défaut les sondes MCP/tool et image de Claude, car Claude facture actuellement l’usage d’applications tierces en consommation supplémentaire au lieu d’utiliser les limites normales du plan d’abonnement.
• Le test smoke live du backend CLI exerce désormais le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d’image, puis appel d’outil MCP cron vérifié via la CLI gateway.
• Le test smoke par défaut de Claude modifie aussi la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d’une note antérieure.

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

• Test : src/gateway/gateway-acp-bind.live.test.ts
• Objectif : valider le vrai flux ACP de liaison de conversation avec un agent ACP live :
  • envoyer /acp spawn <agent> --bind here
  • lier sur place une conversation synthétique de canal de messages
  • envoyer un suivi normal sur cette même conversation
  • vérifier que le suivi arrive dans la transcription de session ACP liée
• Activer :
  • pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
  • OPENCLAW_LIVE_ACP_BIND=1
• Valeurs par défaut :
  • Agents ACP dans Docker : claude,codex,gemini
  • Agent ACP pour pnpm test:live ... direct : claude
  • Canal synthétique : contexte de conversation de type message privé Slack
  • Backend ACP : acpx
• Surcharges :
  • 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>'
• Remarques :
  • Cette voie utilise la surface gateway chat.send avec des champs synthétiques d’originating-route réservés à l’administration afin que les tests puissent attacher un contexte de canal de messages sans prétendre livrer quoi que ce soit vers l’extérieur.
  • Lorsque OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND n’est pas défini, le test utilise le registre d’agents intégré du plugin embarqué acpx pour l’agent de harnais ACP sélectionné.

Exemple :

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

Recette Docker :

pnpm test:docker:live-acp-bind

Recettes Docker mono-agent :

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

Remarques Docker :

• L’exécuteur Docker se trouve dans scripts/test-live-acp-bind-docker.sh.
• Par défaut, il exécute le test smoke ACP bind contre tous les agents CLI live pris en charge en séquence : claude, codex, puis gemini.
• Utilisez OPENCLAW_LIVE_ACP_BIND_AGENTS=claude, OPENCLAW_LIVE_ACP_BIND_AGENTS=codex ou OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini pour restreindre la matrice.
• Il charge ~/.profile, prépare dans le conteneur le matériel d’authentification CLI correspondant, installe acpx dans un préfixe npm inscriptible, puis installe le CLI live demandé (@anthropic-ai/claude-code, @openai/codex, ou @google/gemini-cli) s’il manque.
• Dans Docker, l’exécuteur définit OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx afin qu’acpx conserve pour la CLI harnais enfant les variables d’environnement provider issues du profil chargé.

Live : test smoke du harnais app-server Codex

• Objectif : valider le harnais Codex possédé par le plugin via la méthode gateway normale agent :
  • charger le plugin embarqué codex
  • sélectionner OPENCLAW_AGENT_RUNTIME=codex
  • envoyer un premier tour d’agent gateway à codex/gpt-5.4
  • envoyer un second tour à la même session OpenClaw et vérifier que le thread app-server peut reprendre
  • exécuter /codex status et /codex models via le même chemin de commande gateway
• Test : src/gateway/gateway-codex-harness.live.test.ts
• Activer : OPENCLAW_LIVE_CODEX_HARNESS=1
• Modèle par défaut : codex/gpt-5.4
• Sonde image facultative : OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1
• Sonde MCP/tool facultative : OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1
• Le test smoke définit OPENCLAW_AGENT_HARNESS_FALLBACK=none afin qu’un harnais Codex cassé ne puisse pas réussir en se rabattant silencieusement sur PI.
• Authentification : OPENAI_API_KEY depuis le shell/profil, plus éventuels ~/.codex/auth.json et ~/.codex/config.toml copiés

Recette locale :

source ~/.profile
OPENCLAW_LIVE_CODEX_HARNESS=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \
  pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts

Recette Docker :

source ~/.profile
pnpm test:docker:live-codex-harness

Remarques Docker :

• L’exécuteur Docker se trouve dans scripts/test-live-codex-harness-docker.sh.
• Il charge le ~/.profile monté, transmet OPENAI_API_KEY, copie les fichiers d’authentification CLI Codex lorsqu’ils sont présents, installe @openai/codex dans un préfixe npm monté et inscriptible, prépare l’arbre source, puis exécute uniquement le test live du harnais Codex.
• Docker active par défaut les sondes image et MCP/tool. Définissez OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 ou OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 lorsque vous avez besoin d’une exécution de débogage plus restreinte.
• Docker exporte aussi OPENCLAW_AGENT_HARNESS_FALLBACK=none, conformément à la configuration du test live, de sorte qu’un repli openai-codex/* ou PI ne puisse pas masquer une régression du harnais Codex.

Recettes live recommandées

Des listes d’autorisation étroites et explicites sont les plus rapides et les moins instables :

• Modèle unique, direct (sans gateway) :

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

• Modèle unique, test smoke gateway :

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

• Appel d’outils sur plusieurs providers :

  • 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

• Focus Google (clé API Gemini + Antigravity) :

  • Gemini (clé 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

Remarques :

• google/... utilise l’API Gemini (clé API).
• google-antigravity/... utilise le pont OAuth Antigravity (point de terminaison d’agent de style Cloud Code Assist).
• google-gemini-cli/... utilise la CLI Gemini locale sur votre machine (authentification distincte + particularités de tooling).
• API Gemini vs CLI Gemini :
  • API : OpenClaw appelle l’API Gemini hébergée par Google via HTTP (authentification par clé API / profil) ; c’est ce que la plupart des utilisateurs entendent par « Gemini ».
  • CLI : OpenClaw exécute en shell un binaire local gemini ; il a sa propre authentification et peut se comporter différemment (streaming/prise en charge des outils/décalage de version).

Live : matrice de modèles (ce que nous couvrons)

Il n’existe pas de « liste de modèles CI » fixe (le live fonctionne sur adhésion volontaire), mais voici les modèles recommandés à couvrir régulièrement sur une machine de développement avec des clés.

Ensemble de test smoke moderne (appel d’outils + image)

C’est l’exécution des « modèles courants » que nous nous attendons à maintenir fonctionnelle :

• OpenAI (hors Codex) : openai/gpt-5.4 (facultatif : openai/gpt-5.4-mini)
• OpenAI Codex : openai-codex/gpt-5.4
• Anthropic : anthropic/claude-opus-4-6 (ou anthropic/claude-sonnet-4-6)
• Google (API Gemini) : google/gemini-3.1-pro-preview et google/gemini-3-flash-preview (évitez les anciens modèles Gemini 2.x)
• Google (Antigravity) : google-antigravity/claude-opus-4-6-thinking et google-antigravity/gemini-3-flash
• Z.AI (GLM) : zai/glm-4.7
• MiniMax : minimax/MiniMax-M2.7

Exécuter le test smoke gateway avec outils + 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

Référence : appel d’outils (Read + Exec facultatif)

Choisissez-en au moins un par famille de providers :

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

Couverture supplémentaire facultative (souhaitable) :

• xAI : xai/grok-4 (ou la dernière version disponible)
• Mistral : mistral/… (choisissez un modèle compatible « tools » que vous avez activé)
• Cerebras : cerebras/… (si vous y avez accès)
• LM Studio : lmstudio/… (local ; l’appel d’outils dépend du mode API)

Vision : envoi d’image (pièce jointe → message multimodal)

Incluez au moins un modèle compatible image dans OPENCLAW_LIVE_GATEWAY_MODELS (variants Claude/Gemini/OpenAI compatibles vision, etc.) afin d’exercer la sonde image.

Agrégateurs / gateways alternatives

Si vous avez des clés activées, nous prenons aussi en charge les tests via :

• OpenRouter : openrouter/... (des centaines de modèles ; utilisez openclaw models scan pour trouver des candidats compatibles outils+image)
• OpenCode : opencode/... pour Zen et opencode-go/... pour Go (authentification via OPENCODE_API_KEY / OPENCODE_ZEN_API_KEY)

Autres providers que vous pouvez inclure dans la matrice live (si vous avez les identifiants/la configuration) :

• Intégrés : openai, openai-codex, anthropic, google, google-vertex, google-antigravity, google-gemini-cli, zai, openrouter, opencode, opencode-go, xai, groq, cerebras, mistral, github-copilot
• Via models.providers (points de terminaison personnalisés) : minimax (cloud/API), plus tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)

Astuce : n’essayez pas de coder en dur « tous les modèles » dans la documentation. La liste de référence est celle que renvoie discoverModels(...) sur votre machine + les clés disponibles.

Identifiants (ne jamais valider)

Les tests live découvrent les identifiants de la même manière que la CLI. Conséquences pratiques :

• Si la CLI fonctionne, les tests live devraient trouver les mêmes clés.

• Si un test live indique « aucun identifiant », déboguez-le comme vous le feriez pour openclaw models list / la sélection de modèle.

• Profils d’authentification par agent : ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (c’est ce que signifient les « profile keys » dans les tests live)

• Configuration : ~/.openclaw/openclaw.json (ou OPENCLAW_CONFIG_PATH)

• Répertoire d’état hérité : ~/.openclaw/credentials/ (copié dans le home live préparé lorsqu’il est présent, mais pas le dépôt principal de profile keys)

• Les exécutions live locales copient par défaut la configuration active, les fichiers auth-profiles.json par agent, credentials/ hérité et les répertoires d’authentification CLI externes pris en charge dans un home de test temporaire ; les homes live préparés ignorent workspace/ et sandboxes/, et les surcharges de chemin agents.*.workspace / agentDir sont supprimées afin que les sondes restent hors de votre véritable espace de travail hôte.

Si vous voulez vous appuyer sur des clés d’environnement (par exemple exportées dans votre ~/.profile), exécutez les tests locaux après source ~/.profile, ou utilisez les exécuteurs Docker ci-dessous (ils peuvent monter ~/.profile dans le conteneur).

Live Deepgram (transcription audio)

• Test : src/media-understanding/providers/deepgram/audio.live.test.ts
• Activer : DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts

Live BytePlus coding plan

• Test : src/agents/byteplus.live.test.ts
• Activer : BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts
• Surcharge de modèle facultative : BYTEPLUS_CODING_MODEL=ark-code-latest

Live média de workflow ComfyUI

• Test : extensions/comfy/comfy.live.test.ts
• Activer : OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
• Portée :
  • Exerce les chemins image, vidéo et music_generate du plugin comfy embarqué
  • Ignore chaque capacité tant que models.providers.comfy.<capability> n’est pas configuré
  • Utile après des modifications de soumission de workflow comfy, de polling, de téléchargements ou d’enregistrement de plugin

Live génération d’images

• Test : src/image-generation/runtime.live.test.ts
• Commande : pnpm test:live src/image-generation/runtime.live.test.ts
• Harness : pnpm test:live:media image
• Portée :
  • Énumère chaque plugin provider de génération d’images enregistré
  • Charge les variables d’environnement provider manquantes depuis votre shell de connexion (~/.profile) avant de sonder
  • Utilise par défaut les clés API live/d’environnement avant les profils d’authentification stockés, afin que des clés de test obsolètes dans auth-profiles.json ne masquent pas les vrais identifiants du shell
  • Ignore les providers sans authentification/profil/modèle utilisable
  • Exécute les variantes standard de génération d’images via la capacité runtime partagée :
    • google:flash-generate
    • google:pro-generate
    • google:pro-edit
    • openai:default-generate
• Providers embarqués actuellement couverts :
  • openai
  • google
• Restriction facultative :
  • 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"
• Comportement d’authentification facultatif :
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour imposer l’authentification via le dépôt de profils et ignorer les surcharges uniquement basées sur l’environnement

Live génération de musique

• Test : extensions/music-generation-providers.live.test.ts
• Activer : OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
• Harness : pnpm test:live:media music
• Portée :
  • Exerce le chemin partagé embarqué des providers de génération de musique
  • Couvre actuellement Google et MiniMax
  • Charge les variables d’environnement provider depuis votre shell de connexion (~/.profile) avant de sonder
  • Utilise par défaut les clés API live/d’environnement avant les profils d’authentification stockés, afin que des clés de test obsolètes dans auth-profiles.json ne masquent pas les vrais identifiants du shell
  • Ignore les providers sans authentification/profil/modèle utilisable
  • Exécute les deux modes runtime déclarés lorsqu’ils sont disponibles :
    • generate avec une entrée basée uniquement sur un prompt
    • edit lorsque le provider déclare capabilities.edit.enabled
  • Couverture actuelle de la voie partagée :
    • google : generate, edit
    • minimax : generate
    • comfy : fichier live Comfy séparé, pas dans ce balayage partagé
• Restriction facultative :
  • OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"
  • OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"
• Comportement d’authentification facultatif :
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour imposer l’authentification via le dépôt de profils et ignorer les surcharges uniquement basées sur l’environnement

Live génération de vidéos

• Test : extensions/video-generation-providers.live.test.ts
• Activer : OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
• Harness : pnpm test:live:media video
• Portée :
  • Exerce le chemin partagé embarqué des providers de génération de vidéos
  • Charge les variables d’environnement provider depuis votre shell de connexion (~/.profile) avant de sonder
  • Utilise par défaut les clés API live/d’environnement avant les profils d’authentification stockés, afin que des clés de test obsolètes dans auth-profiles.json ne masquent pas les vrais identifiants du shell
  • Ignore les providers sans authentification/profil/modèle utilisable
  • Exécute les deux modes runtime déclarés lorsqu’ils sont disponibles :
    • generate avec une entrée basée uniquement sur un prompt
    • imageToVideo lorsque le provider déclare capabilities.imageToVideo.enabled et que le provider/modèle sélectionné accepte une entrée image locale adossée à un buffer dans le balayage partagé
    • videoToVideo lorsque le provider déclare capabilities.videoToVideo.enabled et que le provider/modèle sélectionné accepte une entrée vidéo locale adossée à un buffer dans le balayage partagé
  • Providers actuellement déclarés mais ignorés pour imageToVideo dans le balayage partagé :
    • vydra parce que le veo3 embarqué est uniquement texte et que le kling embarqué nécessite une URL d’image distante
  • Couverture spécifique au provider Vydra :
    • OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts
    • ce fichier exécute veo3 texte-vers-vidéo plus une voie kling qui utilise par défaut un fixture d’URL d’image distante
  • Couverture live actuelle de videoToVideo :
    • runway uniquement lorsque le modèle sélectionné est runway/gen4_aleph
  • Providers actuellement déclarés mais ignorés pour videoToVideo dans le balayage partagé :
    • alibaba, qwen, xai car ces chemins nécessitent actuellement des URL de référence distantes http(s) / MP4
    • google car la voie partagée Gemini/Veo actuelle utilise une entrée locale adossée à un buffer et ce chemin n’est pas accepté dans le balayage partagé
    • openai car la voie partagée actuelle ne garantit pas l’accès spécifique à l’organisation pour l’inpainting/remix vidéo
• Restriction facultative :
  • 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"
• Comportement d’authentification facultatif :
  • OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour imposer l’authentification via le dépôt de profils et ignorer les surcharges uniquement basées sur l’environnement

Harness média live

• Commande : pnpm test:live:media
• Objectif :
  • Exécute les suites live partagées image, musique et vidéo via un point d’entrée natif au dépôt
  • Charge automatiquement les variables d’environnement provider manquantes depuis ~/.profile
  • Restreint automatiquement chaque suite aux providers qui disposent actuellement d’une authentification exploitable par défaut
  • Réutilise scripts/test-live.mjs, de sorte que le comportement de heartbeat et du mode silencieux reste cohérent
• Exemples :
  • 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

Exécuteurs Docker (vérifications facultatives « fonctionne sous Linux »)

Ces exécuteurs Docker se répartissent en deux catégories :

• Exécuteurs live-model : test:docker:live-models et test:docker:live-gateway n’exécutent que leur fichier live correspondant à base de profile keys dans l’image Docker du dépôt (src/agents/models.profiles.live.test.ts et src/gateway/gateway-models.profiles.live.test.ts), en montant votre répertoire de configuration local et votre espace de travail (et en chargeant ~/.profile s’il est monté). Les points d’entrée locaux correspondants sont test:live:models-profiles et test:live:gateway-profiles.
• Les exécuteurs Docker live utilisent par défaut un plafond de test smoke plus réduit afin qu’un balayage Docker complet reste praticable : test:docker:live-models utilise par défaut OPENCLAW_LIVE_MAX_MODELS=12, et test:docker:live-gateway utilise par défaut OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000, et OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Remplacez ces variables d’environnement lorsque vous voulez explicitement le balayage exhaustif plus large.
• test:docker:all construit l’image Docker live une fois via test:docker:live-build, puis la réutilise pour les deux voies Docker live.
• Exécuteurs smoke de conteneur : test:docker:openwebui, test:docker:onboard, test:docker:gateway-network, test:docker:mcp-channels et test:docker:plugins démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d’intégration de plus haut niveau.

Les exécuteurs Docker live-model montent aussi en bind uniquement les homes d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le home du conteneur avant l’exécution afin que l’OAuth des CLI externes puisse rafraîchir les tokens sans modifier le dépôt d’authentification de l’hôte :

• Modèles directs : pnpm test:docker:live-models (script : scripts/test-live-models-docker.sh)
• Test smoke ACP bind : pnpm test:docker:live-acp-bind (script : scripts/test-live-acp-bind-docker.sh)
• Test smoke backend CLI : pnpm test:docker:live-cli-backend (script : scripts/test-live-cli-backend-docker.sh)
• Test smoke harnais app-server Codex : pnpm test:docker:live-codex-harness (script : scripts/test-live-codex-harness-docker.sh)
• Gateway + agent de dev : pnpm test:docker:live-gateway (script : scripts/test-live-gateway-models-docker.sh)
• Test smoke live Open WebUI : pnpm test:docker:openwebui (script : scripts/e2e/openwebui-docker.sh)
• Assistant d’onboarding (TTY, échafaudage complet) : pnpm test:docker:onboard (script : scripts/e2e/onboard-docker.sh)
• Réseau gateway (deux conteneurs, auth WS + health) : pnpm test:docker:gateway-network (script : scripts/e2e/gateway-network-docker.sh)
• Pont de canal MCP (Gateway amorcée + pont stdio + test smoke brut de trame de notification Claude) : pnpm test:docker:mcp-channels (script : scripts/e2e/mcp-channels-docker.sh)
• Plugins (test smoke d’installation + alias /plugin + sémantique de redémarrage du bundle Claude) : pnpm test:docker:plugins (script : scripts/e2e/plugins-docker.sh)

Les exécuteurs Docker live-model montent aussi en bind la checkout actuelle en lecture seule et la préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela permet de garder l’image runtime légère tout en exécutant Vitest sur votre source/configuration locale exacte. L’étape de préparation ignore les gros caches locaux uniquement et les sorties de build d’applications telles que .pnpm-store, .worktrees, __openclaw_vitest__, ainsi que les répertoires locaux .build ou de sortie Gradle propres aux applications, afin que les exécutions Docker live ne passent pas des minutes à copier des artefacts spécifiques à la machine. Ils définissent aussi OPENCLAW_SKIP_CHANNELS=1 afin que les sondes gateway live ne démarrent pas de vrais workers de canaux Telegram/Discord/etc. à l’intérieur du conteneur. test:docker:live-models exécute toujours pnpm test:live, donc transmettez aussi OPENCLAW_LIVE_GATEWAY_* lorsque vous devez restreindre ou exclure la couverture gateway live de cette voie Docker. test:docker:openwebui est un test smoke de compatibilité de plus haut niveau : il démarre un conteneur gateway OpenClaw avec les points de terminaison HTTP compatibles OpenAI activés, démarre un conteneur Open WebUI épinglé contre cette gateway, se connecte via Open WebUI, vérifie que /api/models expose openclaw/default, puis envoie une vraie requête de chat via le proxy /api/chat/completions d’Open WebUI. La première exécution peut être sensiblement plus lente parce que Docker peut devoir récupérer l’image Open WebUI et qu’Open WebUI peut devoir terminer sa propre configuration de démarrage à froid. Cette voie attend une clé de modèle live exploitable, et OPENCLAW_PROFILE_FILE (~/.profile par défaut) est le principal moyen de la fournir dans les exécutions Dockerisées. Les exécutions réussies affichent une petite payload JSON comme { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels est volontairement déterministe et n’a pas besoin d’un vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway amorcé, lance un second conteneur qui exécute openclaw mcp serve, puis vérifie la découverte de conversation routée, les lectures de transcription, les métadonnées de pièces jointes, le comportement de la file d’attente d’événements live, le routage des envois sortants, ainsi que les notifications de canal + permissions de style Claude sur le vrai pont stdio MCP. La vérification des notifications inspecte directement les trames MCP stdio brutes afin que le test smoke valide ce que le pont émet réellement, et non simplement ce qu’un SDK client particulier expose par hasard.

Test smoke manuel ACP en langage naturel sur fil (pas en CI) :

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Conservez ce script pour les workflows de régression/débogage. Il pourra être à nouveau nécessaire pour la validation du routage de fils ACP, donc ne le supprimez pas.

Variables d’environnement utiles :

• OPENCLAW_CONFIG_DIR=... (par défaut : ~/.openclaw) monté sur /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (par défaut : ~/.openclaw/workspace) monté sur /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (par défaut : ~/.profile) monté sur /home/node/.profile et chargé avant l’exécution des tests
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (par défaut : ~/.cache/openclaw/docker-cli-tools) monté sur /home/node/.npm-global pour les installations CLI mises en cache dans Docker
• Les répertoires/fichiers d’authentification CLI externes sous $HOME sont montés en lecture seule sous /host-auth..., puis copiés dans /home/node/... avant le démarrage des tests
  • Répertoires par défaut : .minimax
  • Fichiers par défaut : ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Les exécutions restreintes par provider ne montent que les répertoires/fichiers nécessaires déduits de OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Remplacez manuellement avec OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none, ou une liste séparée par des virgules comme OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... pour restreindre l’exécution
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... pour filtrer les providers dans le conteneur
• OPENCLAW_SKIP_DOCKER_BUILD=1 pour réutiliser une image existante openclaw:local-live lors des relances qui ne nécessitent pas de reconstruction
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 pour s’assurer que les identifiants proviennent du dépôt de profils (et non de l’environnement)
• OPENCLAW_OPENWEBUI_MODEL=... pour choisir le modèle exposé par la gateway pour le test smoke Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... pour surcharger le prompt de vérification du nonce utilisé par le test smoke Open WebUI
• OPENWEBUI_IMAGE=... pour surcharger le tag d’image Open WebUI épinglé

Vérification rapide de la documentation

Exécutez les vérifications de documentation après des modifications de docs : pnpm check:docs. Exécutez la validation complète des ancres Mintlify lorsque vous avez aussi besoin de vérifier les titres dans la page : pnpm docs:check-links:anchors.

Régression hors ligne (compatible CI)

Il s’agit de régressions « pipeline réel » sans providers réels :

• Appel d’outils via gateway (OpenAI simulé, vraie gateway + vraie boucle d’agent) : src/gateway/gateway.test.ts (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Assistant gateway (WS wizard.start/wizard.next, écrit config + auth imposée) : src/gateway/gateway.test.ts (cas : "runs wizard over ws and writes auth token config")

Évaluations de fiabilité d’agent (Skills)

Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité d’agent » :

• Appel d’outils simulé via la vraie gateway + la vraie boucle d’agent (src/gateway/gateway.test.ts).
• Flux d’assistant end-to-end qui valident le câblage de session et les effets de configuration (src/gateway/gateway.test.ts).

Ce qui manque encore pour les Skills (voir Skills) :

• Prise de décision : lorsque les Skills sont listées dans le prompt, l’agent choisit-il la bonne Skill (ou évite-t-il les Skills non pertinentes) ?
• Conformité : l’agent lit-il SKILL.md avant utilisation et suit-il les étapes/arguments requis ?
• Contrats de workflow : scénarios multi-tours qui valident l’ordre des outils, la conservation de l’historique de session et les frontières de sandbox.

Les évaluations futures doivent d’abord rester déterministes :

• Un exécuteur de scénarios utilisant des providers simulés pour valider les appels d’outils + leur ordre, les lectures de fichiers de Skill et le câblage de session.
• Une petite suite de scénarios centrés sur les Skills (utiliser vs éviter, filtrage, injection de prompt).
• Des évaluations live facultatives (sur adhésion volontaire, contrôlées par env) seulement une fois la suite compatible CI en place.

Tests de contrat (forme des plugins et des canaux)

Les tests de contrat vérifient que chaque plugin et canal enregistré est conforme à son contrat d’interface. Ils itèrent sur tous les plugins découverts et exécutent une suite d’assertions de forme et de comportement. La voie unitaire par défaut pnpm test ignore intentionnellement ces fichiers de couture partagée et de smoke ; exécutez les commandes de contrat explicitement lorsque vous modifiez des surfaces partagées de canal ou de provider.

Commandes

• Tous les contrats : pnpm test:contracts
• Contrats de canal uniquement : pnpm test:contracts:channels
• Contrats de provider uniquement : pnpm test:contracts:plugins

Contrats de canal

Situés dans src/channels/plugins/contracts/*.contract.test.ts :

• plugin - Forme de base du plugin (id, nom, capacités)
• setup - Contrat de l’assistant de configuration
• session-binding - Comportement de liaison de session
• outbound-payload - Structure de la payload de message
• inbound - Gestion des messages entrants
• actions - Gestionnaires d’actions de canal
• threading - Gestion des identifiants de fil
• directory - API de répertoire/liste
• group-policy - Application de la politique de groupe

Contrats de statut de provider

Situés dans src/plugins/contracts/*.contract.test.ts.

• status - Sondes de statut de canal
• registry - Forme du registre de plugins

Contrats de provider

Situés dans src/plugins/contracts/*.contract.test.ts :

• auth - Contrat du flux d’authentification
• auth-choice - Choix/sélection de l’authentification
• catalog - API du catalogue de modèles
• discovery - Découverte des plugins
• loader - Chargement des plugins
• runtime - Runtime du provider
• shape - Forme/interface du plugin
• wizard - Assistant de configuration

Quand les exécuter

• Après avoir modifié les exports ou sous-chemins de plugin-sdk
• Après avoir ajouté ou modifié un plugin de canal ou de provider
• Après avoir refactorisé l’enregistrement ou la découverte des plugins

Les tests de contrat s’exécutent en CI et ne nécessitent pas de vraies clés API.

Ajouter des régressions (recommandations)

Lorsque vous corrigez un problème de provider/modèle découvert en live :

• Ajoutez si possible une régression compatible CI (provider simulé/stub, ou capture de la transformation exacte de forme de requête)
• Si le problème est intrinsèquement live-only (limites de débit, politiques d’authentification), gardez le test live étroit et activable sur adhésion volontaire via des variables d’environnement
• Préférez cibler la plus petite couche qui détecte le bogue :
  • bogue de conversion/rejeu de requête provider → test direct des modèles
  • bogue du pipeline gateway session/historique/outils → test smoke gateway live ou test simulé de gateway compatible CI
• Garde-fou de traversée SecretRef :
  • src/secrets/exec-secret-ref-id-parity.test.ts dérive une cible échantillonnée par classe SecretRef à partir des métadonnées du registre (listSecretTargetRegistryEntries()), puis vérifie que les identifiants exec des segments de traversée sont rejetés.
  • Si vous ajoutez une nouvelle famille cible SecretRef includeInPlan dans src/secrets/target-registry-data.ts, mettez à jour classifyTargetClass dans ce test. Le test échoue volontairement sur les identifiants de cible non classifiés afin qu’aucune nouvelle classe ne puisse être ignorée silencieusement.