openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh fr translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 18:42:20 +00:00
parent c952ef66cc
commit 5a05b5e12c
5 changed files with 747 additions and 716 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

324
docs/fr/ci.md
View File

@ -3,73 +3,73 @@ read_when:
- Vous devez comprendre pourquoi une tâche CI s’est exécutée ou non
- Vous déboguez une vérification GitHub Actions en échec
- Vous coordonnez une exécution ou une réexécution de validation de version
summary: Graphe des jobs CI, garde-fous de périmètre, regroupements de publication et équivalents locaux des commandes
summary: Graphe des tâches CI, contrôles de périmètre, regroupements de publication et équivalents des commandes locales
title: Pipeline CI
x-i18n:
generated_at: "2026-04-30T07:16:33Z"
generated_at: "2026-04-30T18:38:52Z"
model: gpt-5.5
provider: openai
source_hash: a9c18f0801864ca1030aac9ea81117b011bd7936388984a1809ce3ae6e906e62
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_path: ci.md
workflow: 16
---
OpenClaw CI s’exécute à chaque poussée vers `main` et pour chaque pull request. Le job `preflight` classe le diff et désactive les voies coûteuses lorsque seules des zones sans rapport ont changé. Les exécutions manuelles `workflow_dispatch` contournent volontairement le cadrage intelligent et déploient le graphe complet pour les versions candidates et la validation large. Les voies Android restent optionnelles via `include_android`. La couverture des plugins réservée aux releases se trouve dans le workflow séparé [`Plugin Préversion`](#plugin-prerelease) et ne s’exécute qu’à partir de [`Validation complète de release`](#full-release-validation) ou d’un dispatch manuel explicite.
OpenClaw CI s’exécute à chaque push vers `main` et pour chaque pull request. Le job `preflight` classe le diff et désactive les lanes coûteuses lorsque seules des zones sans rapport ont changé. Les exécutions manuelles `workflow_dispatch` contournent intentionnellement le périmétrage intelligent et déploient tout le graphe pour les release candidates et les validations larges. Les lanes Android restent opt-in via `include_android`. La couverture Plugin réservée aux releases se trouve dans le workflow séparé [`Plugin Prerelease`](#plugin-prerelease) et ne s’exécute qu’à partir de [`Full Release Validation`](#full-release-validation) ou d’un dispatch manuel explicite.
## Vue d’ensemble du pipeline
| Job | Objectif | Quand il s’exécute |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `preflight` | Détecter les changements limités aux docs, les portées modifiées, les extensions modifiées et construire le manifeste CI | Toujours sur les poussées et PR non brouillon |
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les poussées et PR non brouillon |
| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux avis npm | Toujours sur les poussées et PR non brouillon |
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les poussées et PR non brouillon |
| `check-dependencies` | Passe Knip de production limitée aux dépendances, plus garde de la liste d’autorisation des fichiers inutilisés | Changements pertinents pour Node |
| `build-artifacts` | Construire `dist/`, la Control UI, les vérifications d’artefacts construits et les artefacts aval réutilisables | Changements pertinents pour Node |
| `checks-fast-core` | Voies rapides de correction Linux, comme les vérifications bundled/contrat de plugin/protocole | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications fragmentées des contrats de canaux avec un résultat de vérification agrégé stable | Changements pertinents pour Node |
| `checks-node-core-test` | Fragments de tests Node du cœur, hors voies canal, bundled, contrat et extension | Changements pertinents pour Node |
| `check` | Équivalent fragmenté de la porte locale principale : types prod, lint, gardes, types de tests et smoke strict | Changements pertinents pour Node |
| `check-additional` | Fragments d’architecture, de frontière, de gardes de surface d’extension, de frontière de package et de gateway-watch | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de CLI construite et smoke de mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Vérificateur pour les tests de canaux sur artefacts construits | Changements pertinents pour Node |
| `checks-node-compat-node22` | Voie de build et smoke de compatibilité Node 22 | Dispatch CI manuel pour les releases |
| `check-docs` | Formatage, lint et vérifications de liens brisés des docs | Docs modifiées |
| `skills-python` | Ruff + pytest pour les skills adossés à Python | Changements pertinents pour les Skills Python |
| `checks-windows` | Tests de processus/chemins spécifiques à Windows, plus régressions de spécificateurs d’import runtime partagés | Changements pertinents pour Windows |
| `macos-node` | Voie de tests TypeScript macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements pertinents pour macOS |
| `android` | Tests unitaires Android pour les deux variantes, plus un build d’APK debug | Changements pertinents pour Android |
| `test-performance-agent` | Optimisation quotidienne des tests lents Codex après une activité approuvée | Succès de la CI principale ou dispatch manuel |
| Job | Objectif | Quand il s’exécute |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Détecter les changements limités aux docs, les scopes modifiés, les extensions modifiées, et construire le manifeste CI | Toujours sur les pushs et PRs non draft |
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushs et PRs non draft |
| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux avis npm | Toujours sur les pushs et PRs non draft |
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs et PRs non draft |
| `check-dependencies` | Passe Knip de production limitée aux dépendances plus garde de l’allowlist des fichiers inutilisés | Changements pertinents pour Node |
| `build-artifacts` | Construire `dist/`, Control UI, les vérifications d’artefacts construits, et les artefacts aval réutilisables | Changements pertinents pour Node |
| `checks-fast-core` | Lanes de correction Linux rapides telles que les vérifications groupées/contrat Plugin/protocole | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications fragmentées des contrats de channels avec un résultat de vérification agrégé stable | Changements pertinents pour Node |
| `checks-node-core-test` | Shards de tests Node du noyau, hors lanes channel, groupées, contrat et extension | Changements pertinents pour Node |
| `check` | Équivalent fragmenté de la porte locale principale : types prod, lint, gardes, types de tests et smoke strict | Changements pertinents pour Node |
| `check-additional` | Shards d’architecture, de frontières, de gardes de surface d’extension, de frontières de package et de gateway-watch | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de CLI construite et smoke de mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Vérificateur pour les tests de channels d’artefacts construits | Changements pertinents pour Node |
| `checks-node-compat-node22` | Lane de build et smoke de compatibilité Node 22 | Dispatch CI manuel pour les releases |
| `check-docs` | Vérifications de formatage, lint et liens cassés des docs | Docs modifiées |
| `skills-python` | Ruff + pytest pour les skills adossées à Python | Changements pertinents pour les skills Python |
| `checks-windows` | Tests spécifiques Windows de processus/chemins plus régressions de spécificateurs d’import runtime partagés | Changements pertinents pour Windows |
| `macos-node` | Lane de tests TypeScript macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements pertinents pour macOS |
| `android` | Tests unitaires Android pour les deux flavors plus un build APK debug | Changements pertinents pour Android |
| `test-performance-agent` | Optimisation quotidienne des tests lents par Codex après une activité approuvée | Succès de la CI principale ou dispatch manuel |
## Ordre fail-fast
1. `preflight` décide quelles voies existent effectivement. La logique `docs-scope` et `changed-scope` correspond à des étapes dans ce job, et non à des jobs autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds de matrice d’artefacts et de plateformes.
3. `build-artifacts` se chevauche avec les voies Linux rapides afin que les consommateurs aval puissent démarrer dès que le build partagé est prêt.
4. Les voies plus lourdes de plateformes et de runtime se déploient ensuite : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
1. `preflight` décide quelles lanes existent réellement. Les logiques `docs-scope` et `changed-scope` sont des étapes dans ce job, et non des jobs autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds d’artefacts et de matrice de plateformes.
3. `build-artifacts` chevauche les lanes Linux rapides afin que les consommateurs aval puissent commencer dès que le build partagé est prêt.
4. Les lanes de plateformes et de runtimes plus lourdes se déploient ensuite : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
GitHub peut marquer des jobs remplacés comme `cancelled` lorsqu’une poussée plus récente arrive sur la même PR ou la même référence `main`. Traitez cela comme du bruit CI, sauf si l’exécution la plus récente pour la même référence échoue aussi. Les vérifications agrégées de fragments utilisent `!cancelled() && always()` afin de toujours signaler les échecs normaux de fragments, mais sans se mettre en file d’attente après que l’ensemble du workflow a déjà été remplacé. La clé de concurrence CI automatique est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file d’attente ne puisse pas bloquer indéfiniment les nouvelles exécutions principales. Les exécutions manuelles de suite complète utilisent `CI-manual-v1-*` et n’annulent pas les exécutions en cours.
GitHub peut marquer les jobs remplacés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou référence `main`. Traitez cela comme du bruit CI, sauf si la plus récente exécution pour la même référence échoue aussi. Les vérifications agrégées de shards utilisent `!cancelled() && always()` afin de toujours signaler les échecs normaux de shards, sans toutefois se mettre en file d’attente une fois tout le workflow déjà remplacé. La clé de concurrence automatique CI est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file d’attente ne puisse pas bloquer indéfiniment les nouvelles exécutions main. Les exécutions manuelles de suite complète utilisent `CI-manual-v1-*` et n’annulent pas les exécutions en cours.
## Portée et routage
## Périmètre et routage
La logique de portée se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`. Le dispatch manuel ignore la détection `changed-scope` et fait agir le manifeste preflight comme si chaque zone cadrée avait changé.
La logique de périmètre se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`. Le dispatch manuel ignore la détection changed-scope et fait agir le manifeste preflight comme si chaque zone périmétrée avait changé.
- **Les modifications du workflow CI** valident le graphe CI Node ainsi que le lint des workflows, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces voies de plateforme restent limitées aux changements de sources de plateforme.
- **Les modifications limitées au routage CI, certaines modifications peu coûteuses de fixtures de tests du cœur, ainsi que les modifications étroites d’aides/tests de routage de contrat de plugin** utilisent un chemin de manifeste rapide limité à Node : `preflight`, la sécurité et une seule tâche `checks-fast-core`. Ce chemin ignore les artefacts de build, la compatibilité Node 22, les contrats de canaux, les fragments complets du cœur, les fragments de plugins bundled et les matrices de gardes additionnelles lorsque le changement se limite aux surfaces de routage ou d’aide que la tâche rapide exerce directement.
- **Les vérifications Windows Node** sont limitées aux wrappers de processus/chemins spécifiques à Windows, aux aides d’exécution npm/pnpm/UI, à la configuration du gestionnaire de packages et aux surfaces du workflow CI qui exécutent cette voie ; les changements sans rapport de source, de plugin, d’install-smoke et uniquement de tests restent sur les voies Linux Node.
- **Les modifications du workflow CI** valident le graphe CI Node plus le lint des workflows, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces lanes de plateformes restent limitées aux changements de sources de plateformes.
- **Les modifications limitées au routage CI, certaines modifications peu coûteuses de fixtures de tests core, et les modifications étroites de helpers/tests de routage de contrats Plugin** utilisent un chemin de manifeste rapide Node uniquement : `preflight`, sécurité, et une seule tâche `checks-fast-core`. Ce chemin ignore les artefacts de build, la compatibilité Node 22, les contrats de channels, les shards core complets, les shards de Plugins groupés, et les matrices de gardes supplémentaires lorsque le changement est limité aux surfaces de routage ou de helpers directement exercées par la tâche rapide.
- **Les vérifications Node Windows** sont limitées aux wrappers de processus/chemins spécifiques à Windows, aux helpers de runners npm/pnpm/UI, à la configuration du gestionnaire de packages, et aux surfaces du workflow CI qui exécutent cette lane ; les changements sans rapport de sources, Plugin, install-smoke et tests uniquement restent sur les lanes Node Linux.
Les familles de tests Node les plus lentes sont divisées ou équilibrées afin que chaque job reste petit sans sur-réserver les runners : les contrats de canaux s’exécutent en trois fragments pondérés, les petites voies unitaires du cœur sont appariées, auto-reply s’exécute avec quatre workers équilibrés (avec le sous-arbre reply divisé en fragments agent-runner, dispatch et commands/state-routing), et les configurations agentic de Gateway/plugin sont réparties dans les jobs Node agentic existants limités aux sources au lieu d’attendre les artefacts construits. Les tests larges de navigateur, QA, médias et plugins divers utilisent leurs configurations Vitest dédiées plutôt que le fourre-tout partagé des plugins. Les fragments par motifs d’inclusion enregistrent les entrées de durée avec le nom du fragment CI, afin que `.artifacts/vitest-shard-timings.json` puisse distinguer une configuration complète d’un fragment filtré. `check-additional` garde ensemble le travail de compilation/canary de frontière de package et sépare l’architecture de topologie runtime de la couverture gateway watch ; le fragment de garde de frontière exécute ses petits gardes indépendants simultanément dans un seul job. Gateway watch, les tests de canaux et le fragment de frontière de support du cœur s’exécutent simultanément dans `build-artifacts` après que `dist/` et `dist-runtime/` ont déjà été construits.
Les familles de tests Node les plus lentes sont divisées ou équilibrées afin que chaque job reste petit sans sur-réserver de runners : les contrats de channels s’exécutent en trois shards pondérés, les petites lanes d’unités core sont appairées, auto-reply s’exécute avec quatre workers équilibrés (avec le sous-arbre reply divisé en shards agent-runner, dispatch et commands/state-routing), et les configurations agentic gateway/Plugin sont réparties sur les jobs Node agentic existants limités aux sources au lieu d’attendre les artefacts construits. Les tests larges de navigateur, QA, médias et Plugins divers utilisent leurs configs Vitest dédiées au lieu du catch-all Plugin partagé. Les shards à motifs d’inclusion enregistrent les entrées de timing avec le nom de shard CI, afin que `.artifacts/vitest-shard-timings.json` puisse distinguer une config entière d’un shard filtré. `check-additional` conserve ensemble les travaux de compilation/canary de frontières de packages et sépare l’architecture de topologie runtime de la couverture gateway watch ; le shard de garde de frontières exécute ses petits gardes indépendants en parallèle dans un seul job. Gateway watch, les tests de channels et le shard core support-boundary s’exécutent en parallèle dans `build-artifacts` après que `dist/` et `dist-runtime/` ont déjà été construits.
La CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. La variante tierce n’a pas de source set ni de manifeste séparé ; sa voie de tests unitaires compile tout de même la variante avec les flags BuildConfig SMS/call-log, tout en évitant un job de packaging APK debug dupliqué à chaque poussée pertinente pour Android.
La CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. Le flavor tiers n’a pas de source set ni de manifeste séparé ; sa lane de tests unitaires compile tout de même le flavor avec les flags BuildConfig SMS/call-log, tout en évitant un job de packaging APK debug en double à chaque push pertinent pour Android.
Le fragment `check-dependencies` exécute `pnpm deadcode:dependencies` (une passe Knip de production limitée aux dépendances, épinglée à la dernière version de Knip, avec l’âge minimal de release de pnpm désactivé pour l’installation `dlx`) et `pnpm deadcode:unused-files`, qui compare les résultats de fichiers de production inutilisés trouvés par Knip à `scripts/deadcode-unused-files.allowlist.mjs`. Le garde des fichiers inutilisés échoue lorsqu’une PR ajoute un nouveau fichier inutilisé non revu ou laisse une entrée périmée dans la liste d’autorisation, tout en préservant les surfaces intentionnelles de plugin dynamique, générées, de build, de tests live et de ponts de packages que Knip ne peut pas résoudre statiquement.
Le shard `check-dependencies` exécute `pnpm deadcode:dependencies` (une passe Knip de production limitée aux dépendances, épinglée à la dernière version de Knip, avec l’âge minimal de publication de pnpm désactivé pour l’installation `dlx`) et `pnpm deadcode:unused-files`, qui compare les résultats de fichiers de production inutilisés de Knip à `scripts/deadcode-unused-files.allowlist.mjs`. Le garde des fichiers inutilisés échoue lorsqu’une PR ajoute un nouveau fichier inutilisé non revu ou laisse une entrée d’allowlist obsolète, tout en préservant les surfaces intentionnelles de Plugins dynamiques, générées, de build, de live-test et de ponts de packages que Knip ne peut pas résoudre statiquement.
## Dispatchs manuels
## Dispatches manuels
Les dispatchs CI manuels exécutent le même graphe de jobs que la CI normale, mais activent de force chaque voie cadrée non Android : fragments Linux Node, fragments de plugins bundled, contrats de canaux, compatibilité Node 22, `check`, `check-additional`, build smoke, vérifications des docs, Skills Python, Windows, macOS et i18n de la Control UI. Les dispatchs CI manuels autonomes exécutent Android uniquement avec `include_android=true` ; l’ombrelle de release complète active Android en passant `include_android=true`. Les vérifications statiques de préversion de plugins, le fragment `agentic-plugins` réservé aux releases, le balayage complet par lots des extensions et les voies Docker de préversion de plugins sont exclus de la CI. La suite Docker de préversion s’exécute uniquement lorsque `Validation complète de release` déclenche le workflow séparé `Plugin Préversion` avec la porte de validation de release activée.
Les dispatches CI manuels exécutent le même graphe de jobs que la CI normale mais forcent l’activation de chaque lane périmétrée non Android : shards Node Linux, shards de Plugins groupés, contrats de channels, compatibilité Node 22, `check`, `check-additional`, build smoke, vérifications docs, Skills Python, Windows, macOS et i18n Control UI. Les dispatches CI manuels autonomes exécutent Android uniquement avec `include_android=true` ; l’ombrelle de release complète active Android en passant `include_android=true`. Les vérifications statiques de prerelease Plugin, le shard `agentic-plugins` réservé aux releases, le balayage complet par lots des extensions, et les lanes Docker de prerelease Plugin sont exclus de la CI. La suite Docker de prerelease ne s’exécute que lorsque `Full Release Validation` déclenche le workflow séparé `Plugin Prerelease` avec la porte release-validation activée.
Les exécutions manuelles utilisent un groupe de concurrence unique afin qu’une suite complète de release candidate ne soit pas annulée par une autre poussée ou exécution de PR sur la même référence. L’entrée optionnelle `target_ref` permet à un appelant approuvé d’exécuter ce graphe sur une branche, un tag ou un SHA de commit complet, tout en utilisant le fichier de workflow depuis la référence de dispatch sélectionnée.
Les exécutions manuelles utilisent un groupe de concurrence unique afin qu’une suite complète de release candidate ne soit pas annulée par un autre push ou une autre exécution de PR sur la même référence. L’entrée facultative `target_ref` permet à un appelant approuvé d’exécuter ce graphe sur une branche, un tag ou un SHA de commit complet tout en utilisant le fichier de workflow de la référence de dispatch sélectionnée.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -80,14 +80,14 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runners
| Exécuteur | Tâches |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, tâches et agrégats de sécurité rapides (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/bundled, vérifications fragmentées des contrats de canaux, fragments `check` sauf lint, fragments et agrégats `check-additional`, vérificateurs d’agrégats de tests Node, vérifications de docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight install-smoke utilise aussi Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse être mise en file plus tôt |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragments d’extensions plus légers, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` et `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragments de tests Node Linux, fragments de tests de Plugins bundled, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (assez sensible au CPU pour que 8 vCPU aient coûté plus qu’ils n’ont économisé) ; builds Docker install-smoke (le temps de file d’attente 32 vCPU a coûté plus qu’il n’a économisé) |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, tâches de sécurité rapides et agrégats (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/groupées, vérifications fragmentées de contrats de canaux, fragments `check` sauf lint, fragments et agrégats `check-additional`, vérificateurs d’agrégats de tests Node, vérifications de docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight install-smoke utilise aussi Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse se mettre en file plus tôt |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragments de Plugin à charge plus faible, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` et `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragments de tests Node Linux, fragments de tests de Plugins groupés, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (assez sensible au CPU pour que 8 vCPU coûtent plus qu’ils n’économisent) ; builds Docker install-smoke (le temps de file de 32 vCPU coûtait plus qu’il n’économisait) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks se rabattent sur `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks se rabattent sur `macos-latest` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks se replient sur `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks se replient sur `macos-latest` |
## Équivalents locaux
@ -115,25 +115,25 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
```
## Validation complète de release
## Validation complète de publication
`Full Release Validation` est le workflow manuel englobant pour « tout exécuter avant la release ». Il accepte une branche, une balise ou un SHA de commit complet, déclenche le workflow manuel `CI` avec cette cible, déclenche `Plugin Prerelease` pour les preuves réservées à la release concernant Plugin/package/statique/Docker, et déclenche `OpenClaw Release Checks` pour les install smoke, l’acceptation de package, les suites de chemin de release Docker, live/E2E, OpenWebUI, la parité QA Lab, Matrix et les voies Telegram. Il peut aussi exécuter le workflow post-publication `NPM Telegram Beta E2E` lorsqu’une spécification de package publiée est fournie.
`Full Release Validation` est le workflow parapluie manuel pour « tout exécuter avant la publication ». Il accepte une branche, un tag ou un SHA de commit complet, déclenche le workflow manuel `CI` avec cette cible, déclenche `Plugin Prerelease` pour la preuve réservée à la publication des Plugins/packages/statiques/Docker, et déclenche `OpenClaw Release Checks` pour le smoke d’installation, l’acceptation de package, les suites de chemin de publication Docker, le live/E2E, OpenWebUI, la parité QA Lab, Matrix et les voies Telegram. Il peut aussi exécuter le workflow post-publication `NPM Telegram Beta E2E` lorsqu’une spécification de package publiée est fournie.
`release_profile` contrôle l’étendue live/fournisseur transmise aux vérifications de release :
`release_profile` contrôle l’étendue live/fournisseur transmise aux vérifications de publication :
- `minimum` conserve les voies critiques de release OpenAI/core les plus rapides.
- `minimum` conserve les voies OpenAI/core critiques pour la publication les plus rapides.
- `stable` ajoute l’ensemble stable de fournisseurs/backends.
- `full` exécute la large matrice consultative fournisseurs/médias.
- `full` exécute la large matrice consultative fournisseur/médias.
L’englobant enregistre les ID d’exécution enfant déclenchées, et la tâche finale `Verify full validation` revérifie les conclusions actuelles des exécutions enfant et ajoute des tableaux des tâches les plus lentes pour chaque exécution enfant. Si un workflow enfant est relancé et passe au vert, relancez seulement la tâche de vérification parente pour actualiser le résultat englobant et le résumé des temps.
Le parapluie enregistre les identifiants des exécutions enfants déclenchées, et la tâche finale `Verify full validation` revérifie les conclusions actuelles des exécutions enfants et ajoute des tableaux des tâches les plus lentes pour chaque exécution enfant. Si un workflow enfant est relancé et passe au vert, relancez uniquement la tâche de vérification parente pour actualiser le résultat du parapluie et le résumé des temps.
Pour la récupération, `Full Release Validation` et `OpenClaw Release Checks` acceptent tous deux `rerun_group`. Utilisez `all` pour une release candidate, `ci` uniquement pour l’enfant CI complet normal, `release-checks` pour chaque enfant de release, ou un groupe plus étroit : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` sur l’englobant. Cela garde bornée la relance d’une boîte de release échouée après un correctif ciblé.
Pour la récupération, `Full Release Validation` et `OpenClaw Release Checks` acceptent tous deux `rerun_group`. Utilisez `all` pour un candidat de publication, `ci` uniquement pour l’enfant CI complet normal, `release-checks` pour chaque enfant de publication, ou un groupe plus étroit : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` sur le parapluie. Cela limite la relance d’une boîte de publication échouée après un correctif ciblé.
`OpenClaw Release Checks` utilise la ref de workflow de confiance pour résoudre une fois la ref sélectionnée en tarball `release-package-under-test`, puis transmet cet artefact à la fois au workflow Docker de chemin de release live/E2E et au fragment d’acceptation de package. Cela maintient les octets du package cohérents entre les boîtes de release et évite de reconditionner le même candidat dans plusieurs tâches enfant.
`OpenClaw Release Checks` utilise la référence de workflow de confiance pour résoudre une fois la référence sélectionnée en tarball `release-package-under-test`, puis transmet cet artefact à la fois au workflow Docker de chemin de publication live/E2E et au fragment d’acceptation de package. Cela maintient des octets de package cohérents entre les boîtes de publication et évite de réemballer le même candidat dans plusieurs tâches enfants.
## Fragments live et E2E
L’enfant live/E2E de release conserve une large couverture native `pnpm test:live`, mais l’exécute comme fragments nommés via `scripts/test-live-shard.mjs` au lieu d’une tâche sérielle unique :
L’enfant live/E2E de publication conserve une large couverture native `pnpm test:live`, mais l’exécute sous forme de fragments nommés via `scripts/test-live-shard.mjs` au lieu d’une seule tâche série :
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -145,57 +145,57 @@ L’enfant live/E2E de release conserve une large couverture native `pnpm test:l
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- fragments médias audio/vidéo séparés et fragments musicaux filtrés par fournisseur
- fragments médias audio/vidéo séparés et fragments musique filtrés par fournisseur
Cela conserve la même couverture de fichiers tout en rendant les échecs lents de fournisseurs live plus faciles à relancer et à diagnostiquer. Les noms de fragments agrégés `native-live-extensions-o-z`, `native-live-extensions-media` et `native-live-extensions-media-music` restent valides pour les relances manuelles ponctuelles.
Cela conserve la même couverture de fichiers tout en rendant les défaillances lentes des fournisseurs live plus faciles à relancer et à diagnostiquer. Les noms de fragments agrégés `native-live-extensions-o-z`, `native-live-extensions-media` et `native-live-extensions-media-music` restent valides pour les relances manuelles en une seule fois.
Les fragments médias live natifs s’exécutent dans `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, construit par le workflow `Live Media Runner Image`. Cette image préinstalle `ffmpeg` et `ffprobe` ; les tâches médias vérifient seulement les binaires avant la configuration. Gardez les suites live adossées à Docker sur les exécuteurs Blacksmith normaux — les tâches de conteneur ne sont pas le bon endroit pour lancer des tests Docker imbriqués.
Les fragments de médias live natifs s’exécutent dans `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, construit par le workflow `Live Media Runner Image`. Cette image préinstalle `ffmpeg` et `ffprobe` ; les tâches médias ne font que vérifier les binaires avant la configuration. Gardez les suites live adossées à Docker sur des exécuteurs Blacksmith normaux : les tâches conteneur sont le mauvais endroit pour lancer des tests Docker imbriqués.
Les fragments live modèle/backend adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:<sha>` par commit sélectionné. Le workflow live de release construit et pousse cette image une fois, puis les fragments modèle live Docker, Gateway, backend CLI, liaison ACP et harnais Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Si ces fragments reconstruisent indépendamment la cible Docker source complète, l’exécution de release est mal configurée et gaspillera du temps réel sur des builds d’image en double.
Les fragments live de modèles/backends adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:<sha>` par commit sélectionné. Le workflow de publication live construit et pousse cette image une seule fois, puis les fragments du modèle live Docker, du Gateway, du backend CLI, de la liaison ACP et du harnais Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Si ces fragments reconstruisent indépendamment la cible Docker source complète, l’exécution de publication est mal configurée et gaspillera du temps mural avec des builds d’image dupliqués.
## Acceptation de package
Utilisez `Package Acceptance` lorsque la question est « ce package OpenClaw installable fonctionne-t-il comme produit ? ». Elle diffère de la CI normale : la CI normale valide l’arborescence source, tandis que l’acceptation de package valide un seul tarball via le même harnais Docker E2E que les utilisateurs exercent après installation ou mise à jour.
Utilisez `Package Acceptance` lorsque la question est « ce package OpenClaw installable fonctionne-t-il comme un produit ? » C’est différent de la CI normale : la CI normale valide l’arborescence source, tandis que l’acceptation de package valide un tarball unique via le même harnais Docker E2E que les utilisateurs exercent après une installation ou une mise à jour.
### Tâches
1. `resolve_package` extrait `workflow_ref`, résout un candidat package, écrit `.artifacts/docker-e2e-package/openclaw-current.tgz`, écrit `.artifacts/docker-e2e-package/package-candidate.json`, téléverse les deux comme artefact `package-under-test`, et imprime la source, la ref de workflow, la ref de package, la version, le SHA-256 et le profil dans le résumé d’étape GitHub.
2. `docker_acceptance` appelle `openclaw-live-and-e2e-checks-reusable.yml` avec `ref=workflow_ref` et `package_artifact_name=package-under-test`. Le workflow réutilisable télécharge cet artefact, valide l’inventaire du tarball, prépare les images Docker à condensé de package si nécessaire, et exécute les voies Docker sélectionnées contre ce package au lieu de packager l’extraction du workflow. Lorsqu’un profil sélectionne plusieurs `docker_lanes` ciblées, le workflow réutilisable prépare le package et les images partagées une fois, puis déploie ces voies en tâches Docker ciblées parallèles avec des artefacts uniques.
1. `resolve_package` extrait `workflow_ref`, résout un candidat de package, écrit `.artifacts/docker-e2e-package/openclaw-current.tgz`, écrit `.artifacts/docker-e2e-package/package-candidate.json`, téléverse les deux en tant qu’artefact `package-under-test`, et affiche la source, la référence de workflow, la référence de package, la version, le SHA-256 et le profil dans le résumé d’étape GitHub.
2. `docker_acceptance` appelle `openclaw-live-and-e2e-checks-reusable.yml` avec `ref=workflow_ref` et `package_artifact_name=package-under-test`. Le workflow réutilisable télécharge cet artefact, valide l’inventaire du tarball, prépare les images Docker de digest de package lorsque nécessaire, et exécute les voies Docker sélectionnées contre ce package au lieu de packager l’extraction du workflow. Lorsqu’un profil sélectionne plusieurs `docker_lanes` ciblées, le workflow réutilisable prépare le package et les images partagées une seule fois, puis déploie ces voies en tâches Docker ciblées parallèles avec des artefacts uniques.
3. `package_telegram` appelle éventuellement `NPM Telegram Beta E2E`. Il s’exécute lorsque `telegram_mode` n’est pas `none` et installe le même artefact `package-under-test` lorsque Package Acceptance en a résolu un ; un déclenchement Telegram autonome peut toujours installer une spécification npm publiée.
4. `summary` fait échouer le workflow si la résolution de package, l’acceptation Docker ou la voie Telegram facultative a échoué.
4. `summary` fait échouer le workflow si la résolution du package, l’acceptation Docker ou la voie Telegram facultative a échoué.
### Sources candidates
- `source=npm` accepte uniquement `openclaw@beta`, `openclaw@latest` ou une version de publication OpenClaw exacte telle que `openclaw@2026.4.27-beta.2`. Utilisez cela pour l’acceptation publiée bêta/stable.
- `source=ref` empaquette une branche, une balise ou un SHA de commit complet `package_ref` de confiance. Le résolveur récupère les branches/balises OpenClaw, vérifie que le commit sélectionné est accessible depuis l’historique de branche du dépôt ou une balise de publication, installe les dépendances dans un worktree détaché, puis l’empaquette avec `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` accepte uniquement `openclaw@beta`, `openclaw@latest` ou une version de publication OpenClaw exacte telle que `openclaw@2026.4.27-beta.2`. Utilisez ceci pour l’acceptation des versions bêta/stables publiées.
- `source=ref` empaquette une branche, une étiquette ou un SHA de commit complet `package_ref` de confiance. Le résolveur récupère les branches/étiquettes OpenClaw, vérifie que le commit sélectionné est atteignable depuis l’historique des branches du dépôt ou une étiquette de publication, installe les dépendances dans un worktree détaché et l’empaquette avec `scripts/package-openclaw-for-docker.mjs`.
- `source=url` télécharge un `.tgz` HTTPS ; `package_sha256` est requis.
- `source=artifact` télécharge un `.tgz` depuis `artifact_run_id` et `artifact_name` ; `package_sha256` est facultatif mais devrait être fourni pour les artefacts partagés en externe.
- `source=artifact` télécharge un `.tgz` depuis `artifact_run_id` et `artifact_name` ; `package_sha256` est facultatif mais doit être fourni pour les artefacts partagés en externe.
Gardez `workflow_ref` et `package_ref` séparés. `workflow_ref` est le code de workflow/harnais de confiance qui exécute le test. `package_ref` est le commit source qui est empaqueté quand `source=ref`. Cela permet au harnais de test actuel de valider d’anciens commits source de confiance sans exécuter l’ancienne logique de workflow.
Gardez `workflow_ref` et `package_ref` séparés. `workflow_ref` est le code de workflow/harnais de confiance qui exécute le test. `package_ref` est le commit source qui est empaqueté lorsque `source=ref`. Cela permet au harnais de test actuel de valider d’anciens commits source de confiance sans exécuter l’ancienne logique de workflow.
### Profils de suite
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — fragments complets du chemin de publication Docker avec OpenWebUI
- `custom` — `docker_lanes` exact ; requis quand `suite_profile=custom`
- `custom` — `docker_lanes` exact ; requis lorsque `suite_profile=custom`
Le profil `package` utilise une couverture de plugins hors ligne afin que la validation des packages publiés ne dépende pas de la disponibilité en direct de ClawHub. La voie Telegram facultative réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, le chemin de spécification npm publié étant conservé pour les dispatches autonomes.
Le profil `package` utilise une couverture des plugins hors ligne afin que la validation des packages publiés ne dépende pas de la disponibilité en direct de ClawHub. Le lane Telegram facultatif réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, avec le chemin de spécification npm publiée conservé pour les dispatchs autonomes.
Les vérifications de publication appellent Package Acceptance avec `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` et `telegram_mode=mock-openai`. Les fragments Docker du chemin de publication couvrent les voies package/update/plugin qui se chevauchent ; Package Acceptance conserve la compatibilité bundled-channel native de l’artefact, le plugin hors ligne et la preuve Telegram sur la même archive tar de package résolue. Les vérifications de publication inter-OS couvrent toujours l’onboarding, l’installateur et le comportement de plateforme propres à l’OS ; la validation produit package/update devrait commencer avec Package Acceptance. Les voies Windows packaged et installer fresh vérifient aussi qu’un package installé peut importer un remplacement browser-control depuis un chemin Windows absolu brut. Le smoke de tour d’agent OpenAI inter-OS utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` quand il est défini, sinon `openai/gpt-5.4-mini`, afin que la preuve d’installation et de Gateway reste rapide et déterministe.
Les vérifications de publication appellent Package Acceptance avec `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` et `telegram_mode=mock-openai`. Les fragments Docker du chemin de publication couvrent les lanes qui se chevauchent pour les packages/mises à jour/plugins ; Package Acceptance conserve la preuve de compatibilité des canaux groupés native de l’artefact, des plugins hors ligne et de Telegram contre le même tarball de package résolu. Les vérifications de publication multi-OS couvrent toujours l’onboarding propre au système d’exploitation, l’installeur et le comportement de plateforme ; la validation produit des packages/mises à jour doit commencer par Package Acceptance. Les lanes Windows de package et d’installation fraîche vérifient également qu’un package installé peut importer un remplacement de contrôle du navigateur depuis un chemin Windows absolu brut. Le smoke de tour d’agent multi-OS OpenAI utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsqu’il est défini, sinon `openai/gpt-5.4-mini`, afin que la preuve d’installation et de Gateway reste rapide et déterministe.
### Fenêtres de compatibilité héritée
### Fenêtres de compatibilité héritées
Package Acceptance dispose de fenêtres bornées de compatibilité héritée pour les packages déjà publiés. Les packages jusqu’à `2026.4.25`, y compris `2026.4.25-beta.*`, peuvent utiliser le chemin de compatibilité :
- les entrées QA privées connues dans `dist/postinstall-inventory.json` peuvent pointer vers des fichiers omis de l’archive tar ;
- `doctor-switch` peut ignorer le sous-cas de persistance `gateway install --wrapper` quand le package n’expose pas ce drapeau ;
- `update-channel-switch` peut élaguer les `pnpm.patchedDependencies` manquants depuis la fausse fixture git dérivée de l’archive tar et peut journaliser l’absence de `update.channel` persistant ;
- les smokes de plugins peuvent lire d’anciens emplacements d’enregistrement d’installation ou accepter l’absence de persistance de l’enregistrement d’installation de la marketplace ;
- les entrées QA privées connues dans `dist/postinstall-inventory.json` peuvent pointer vers des fichiers omis du tarball ;
- `doctor-switch` peut ignorer le sous-cas de persistance `gateway install --wrapper` lorsque le package n’expose pas cet indicateur ;
- `update-channel-switch` peut supprimer les `pnpm.patchedDependencies` manquantes du faux fixture git dérivé du tarball et peut journaliser l’absence du `update.channel` persistant ;
- les smokes de plugins peuvent lire les anciens emplacements d’enregistrements d’installation ou accepter l’absence de persistance de l’enregistrement d’installation marketplace ;
- `plugin-update` peut autoriser la migration des métadonnées de configuration tout en exigeant que l’enregistrement d’installation et le comportement sans réinstallation restent inchangés.
Le package `2026.4.26` publié peut aussi avertir pour les fichiers d’horodatage de métadonnées de build local déjà livrés. Les packages ultérieurs doivent satisfaire les contrats modernes ; les mêmes conditions échouent au lieu d’avertir ou d’être ignorées.
Le package publié `2026.4.26` peut aussi avertir pour les fichiers d’horodatage de métadonnées de build local déjà livrés. Les packages ultérieurs doivent satisfaire les contrats modernes ; les mêmes conditions échouent au lieu d’émettre un avertissement ou d’être ignorées.
### Exemples
@ -238,60 +238,60 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Lors du débogage d’une exécution Package Acceptance échouée, commencez par le résumé `resolve_package` pour confirmer la source, la version et le SHA-256 du package. Inspectez ensuite l’exécution enfant `docker_acceptance` et ses artefacts Docker : `.artifacts/docker-tests/**/summary.json`, `failures.json`, les journaux de voie, les temps de phase et les commandes de réexécution. Préférez réexécuter le profil de package échoué ou les voies Docker exactes plutôt que de relancer toute la validation de publication.
Lors du débogage d’une exécution Package Acceptance échouée, commencez par le résumé `resolve_package` pour confirmer la source du package, la version et le SHA-256. Inspectez ensuite l’exécution enfant `docker_acceptance` et ses artefacts Docker : `.artifacts/docker-tests/**/summary.json`, `failures.json`, les journaux de lane, les minutages de phase et les commandes de réexécution. Préférez réexécuter le profil de package échoué ou les lanes Docker exacts plutôt que de relancer la validation complète de publication.
## Smoke d’installation
Le workflow `Install Smoke` séparé réutilise le même script de portée via sa propre tâche `preflight`. Il divise la couverture smoke entre `run_fast_install_smoke` et `run_full_install_smoke`.
Le workflow distinct `Install Smoke` réutilise le même script de portée via son propre job `preflight`. Il divise la couverture smoke entre `run_fast_install_smoke` et `run_full_install_smoke`.
- **Chemin rapide** s’exécute pour les pull requests touchant les surfaces Docker/package, les changements de package/manifeste de plugins groupés, ou les surfaces principales de plugin/canal/Gateway/Plugin SDK que les tâches de smoke Docker exercent. Les changements de plugins groupés limités au source, les modifications limitées aux tests et les modifications limitées à la documentation ne réservent pas de workers Docker. Le chemin rapide construit l’image Dockerfile racine une fois, vérifie la CLI, exécute le smoke CLI de suppression des agents dans l’espace de travail partagé, exécute l’e2e gateway-network du conteneur, vérifie un argument de build d’extension groupée, puis exécute le profil Docker borné de plugin groupé sous un délai global de commande de 240 secondes (chaque exécution Docker de scénario étant plafonnée séparément).
- **Chemin complet** conserve l’installation de package QR et la couverture Docker/update de l’installateur pour les exécutions planifiées nocturnes, les dispatches manuels, les vérifications de publication par workflow-call et les pull requests qui touchent réellement les surfaces installateur/package/Docker. En mode complet, install-smoke prépare ou réutilise une image de smoke Dockerfile racine GHCR pour le SHA cible, puis exécute l’installation de package QR, les smokes Dockerfile racine/Gateway, les smokes installateur/update et l’E2E Docker rapide de plugin groupé comme tâches séparées afin que le travail d’installation n’attende pas derrière les smokes de l’image racine.
- **Chemin rapide** s’exécute pour les pull requests touchant les surfaces Docker/package, les changements de package/manifeste de plugin groupé, ou les surfaces Plugin SDK de plugin/canal/Gateway cœur que les jobs smoke Docker exercent. Les changements de plugin groupé uniquement source, les modifications uniquement de tests et les modifications uniquement de documentation ne réservent pas de workers Docker. Le chemin rapide construit une fois l’image Dockerfile racine, vérifie la CLI, exécute le smoke CLI de suppression des agents pour l’espace de travail partagé, exécute l’e2e gateway-network du conteneur, vérifie un argument de build d’extension groupée et exécute le profil Docker borné des plugins groupés sous un délai global de commande de 240 secondes (chaque exécution Docker de scénario étant plafonnée séparément).
- **Chemin complet** conserve la couverture d’installation de package QR et d’installation/mise à jour Docker pour les exécutions nocturnes planifiées, les dispatchs manuels, les vérifications de publication workflow-call et les pull requests qui touchent réellement les surfaces d’installeur/package/Docker. En mode complet, install-smoke prépare ou réutilise une image smoke GHCR Dockerfile racine pour le SHA cible, puis exécute l’installation de package QR, les smokes Dockerfile racine/Gateway, les smokes installeur/mise à jour et l’E2E Docker rapide des plugins groupés comme jobs séparés afin que le travail d’installation n’attende pas derrière les smokes de l’image racine.
Les pushes sur `main` (y compris les commits de merge) ne forcent pas le chemin complet ; quand la logique de portée des changements demanderait une couverture complète sur un push, le workflow conserve le smoke Docker rapide et laisse le smoke d’installation complet à la validation nocturne ou de publication.
Les pushs vers `main` (y compris les commits de fusion) ne forcent pas le chemin complet ; lorsque la logique de portée des changements demanderait une couverture complète sur un push, le workflow conserve le smoke Docker rapide et laisse le smoke d’installation complet à la validation nocturne ou de publication.
Le smoke lent de fournisseur d’image par installation globale Bun est contrôlé séparément par `run_bun_global_install_smoke`. Il s’exécute selon le planning nocturne et depuis le workflow de vérifications de publication, et les dispatches manuels `Install Smoke` peuvent choisir de l’inclure, mais les pull requests et les pushes sur `main` ne le font pas. Les tests Docker QR et installateur conservent leurs propres Dockerfiles centrés sur l’installation.
Le smoke lent du fournisseur d’image d’installation globale Bun est contrôlé séparément par `run_bun_global_install_smoke`. Il s’exécute sur la planification nocturne et depuis le workflow de vérifications de publication, et les dispatchs manuels `Install Smoke` peuvent l’activer, mais pas les pull requests ni les pushs vers `main`. Les tests Docker QR et d’installeur conservent leurs propres Dockerfiles orientés installation.
## E2E Docker local
`pnpm test:docker:all` préconstruit une image de test en direct partagée, empaquette OpenClaw une fois sous forme d’archive tar npm, puis construit deux images `scripts/e2e/Dockerfile` partagées :
`pnpm test:docker:all` préconstruit une image de test en direct partagée, empaquette OpenClaw une fois comme tarball npm et construit deux images `scripts/e2e/Dockerfile` partagées :
- un exécuteur Node/Git minimal pour les voies installateur/update/dépendances de plugin ;
- une image fonctionnelle qui installe la même archive tar dans `/app` pour les voies de fonctionnalité normales.
- un exécuteur Node/Git minimal pour les lanes installeur/mise à jour/dépendance de plugin ;
- une image fonctionnelle qui installe le même tarball dans `/app` pour les lanes de fonctionnalité normale.
Les définitions de voies Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique du planificateur dans `scripts/lib/docker-e2e-plan.mjs`, et l’exécuteur exécute uniquement le plan sélectionné. L’ordonnanceur sélectionne l’image par voie avec `OPENCLAW_DOCKER_E2E_BARE_IMAGE` et `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, puis exécute les voies avec `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Les définitions de lanes Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique du planificateur se trouve dans `scripts/lib/docker-e2e-plan.mjs`, et l’exécuteur n’exécute que le plan sélectionné. L’ordonnanceur sélectionne l’image par lane avec `OPENCLAW_DOCKER_E2E_BARE_IMAGE` et `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, puis exécute les lanes avec `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Paramètres ajustables
| Variable | Par défaut | Objectif |
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre de créneaux du pool principal pour les voies normales. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Nombre de créneaux du pool final sensible aux fournisseurs. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Plafond de voies en direct concurrentes pour éviter que les fournisseurs ne limitent le débit. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Plafond de voies d’installation npm concurrentes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Plafond de voies multi-services concurrentes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Décalage entre les démarrages de voies pour éviter les tempêtes de création du démon Docker ; définissez `0` pour aucun décalage. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai de secours par voie (120 minutes) ; certaines voies live/tail utilisent des plafonds plus stricts. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | non défini | `1` affiche le plan de l’ordonnanceur sans exécuter les voies. |
| `OPENCLAW_DOCKER_ALL_LANES` | non défini | Liste exacte de voies séparées par des virgules ; ignore le smoke de nettoyage afin que les agents puissent reproduire une voie échouée. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre de slots du pool principal pour les lanes normales. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Nombre de slots du pool de fin sensible aux fournisseurs. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Plafond de lanes en direct concurrentes afin que les fournisseurs ne limitent pas le débit. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Plafond de lanes d’installation npm concurrentes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Plafond de lanes multiservices concurrentes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Décalage entre les démarrages de lanes pour éviter les tempêtes de création du démon Docker ; définissez `0` pour aucun décalage. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai de secours par lane (120 minutes) ; certaines lanes en direct/de fin utilisent des plafonds plus stricts. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | non défini | `1` affiche le plan de l’ordonnanceur sans exécuter les lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | non défini | Liste exacte de lanes séparées par des virgules ; ignore le smoke de nettoyage afin que les agents puissent reproduire une lane échouée. |
Une voie plus lourde que son plafond effectif peut tout de même démarrer depuis un pool vide, puis s’exécuter seule jusqu’à libérer de la capacité. Le préflight agrégé local vérifie Docker, supprime les conteneurs E2E OpenClaw obsolètes, émet l’état des voies actives, persiste les temps de voie pour l’ordre du plus long au plus court, et cesse par défaut de planifier de nouvelles voies mutualisées après le premier échec.
Une lane plus lourde que son plafond effectif peut quand même démarrer depuis un pool vide, puis s’exécute seule jusqu’à libérer de la capacité. L’agrégat local effectue les prévalidations Docker, supprime les conteneurs E2E OpenClaw obsolètes, émet l’état des lanes actives, persiste les minutages de lanes pour l’ordre du plus long d’abord et arrête par défaut de planifier de nouvelles lanes groupées après le premier échec.
### Workflow live/E2E réutilisable
### Workflow en direct/E2E réutilisable
Le workflow live/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quelle couverture de package, type d’image, image live, voie et identifiants est requise. `scripts/docker-e2e.mjs` convertit ensuite ce plan en sorties et résumés GitHub. Il empaquette OpenClaw via `scripts/package-openclaw-for-docker.mjs`, télécharge un artefact de package de l’exécution courante, ou télécharge un artefact de package depuis `package_artifact_run_id` ; valide l’inventaire de l’archive tar ; construit et pousse les images E2E Docker GHCR bare/fonctionnelles étiquetées par digest de package via le cache de couches Docker de Blacksmith quand le plan a besoin de voies avec package installé ; et réutilise les entrées `docker_e2e_bare_image`/`docker_e2e_functional_image` fournies ou les images existantes par digest de package au lieu de reconstruire. Les pulls d’images Docker sont retentés avec un délai borné de 180 secondes par tentative afin qu’un flux registre/cache bloqué retente rapidement au lieu de consommer la majeure partie du chemin critique CI.
Le workflow en direct/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quels package, type d’image, image en direct, lane et couverture d’identifiants sont requis. `scripts/docker-e2e.mjs` convertit ensuite ce plan en sorties et résumés GitHub. Il empaquette OpenClaw via `scripts/package-openclaw-for-docker.mjs`, télécharge un artefact de package de l’exécution actuelle ou télécharge un artefact de package depuis `package_artifact_run_id` ; valide l’inventaire du tarball ; construit et pousse des images E2E Docker GHCR bare/fonctionnelles étiquetées par le digest du package via le cache de couches Docker de Blacksmith lorsque le plan nécessite des lanes avec package installé ; et réutilise les entrées `docker_e2e_bare_image`/`docker_e2e_functional_image` fournies ou des images existantes fondées sur le digest du package au lieu de reconstruire. Les extractions d’images Docker sont réessayées avec un délai borné de 180 secondes par tentative afin qu’un flux de registre/cache bloqué soit réessayé rapidement au lieu de consommer l’essentiel du chemin critique CI.
### Fragments du chemin de publication
La couverture Docker de publication exécute des tâches fragmentées plus petites avec `OPENCLAW_SKIP_DOCKER_BUILD=1`, afin que chaque fragment ne tire que le type d’image dont il a besoin et exécute plusieurs voies via le même ordonnanceur pondéré :
La couverture Docker de publication exécute des jobs fragmentés plus petits avec `OPENCLAW_SKIP_DOCKER_BUILD=1`, afin que chaque fragment ne récupère que le type d’image dont il a besoin et exécute plusieurs lanes via le même ordonnanceur pondéré :
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels`
Les fragments Docker de la version actuelle sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` à `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` et `bundled-channels-contracts`. Le fragment agrégé `bundled-channels` reste disponible pour les réexécutions manuelles ponctuelles, et `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés de plugin/runtime. L’alias de voie `install-e2e` reste l’alias de réexécution manuelle agrégé pour les deux voies d’installation des fournisseurs. Le fragment `bundled-channels` exécute des voies scindées `bundled-channel-*` et `bundled-channel-update-*` plutôt que la voie série tout-en-un `bundled-channel-deps`.
Les fragments Docker de la version actuelle sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` à `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` et `bundled-channels-contracts`. Le fragment agrégé `bundled-channels` reste disponible pour les relances manuelles en une seule passe, et `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés de Plugin/runtime. L’alias de voie `install-e2e` reste l’alias de relance manuelle agrégé pour les deux voies d’installation de fournisseur. Le fragment `bundled-channels` exécute les voies divisées `bundled-channel-*` et `bundled-channel-update-*` plutôt que la voie sérielle tout-en-un `bundled-channel-deps`.
OpenWebUI est intégré à `plugins-runtime-services` lorsque la couverture complète du chemin de publication le demande, et conserve un fragment autonome `openwebui` uniquement pour les dispatches limités à OpenWebUI. Les voies de mise à jour des canaux groupés réessaient une fois en cas d’échecs réseau npm transitoires.
OpenWebUI est intégré à `plugins-runtime-services` lorsque la couverture complète du chemin de publication le demande, et conserve un fragment autonome `openwebui` uniquement pour les dispatchs limités à OpenWebUI. Les voies de mise à jour des canaux groupés réessaient une fois en cas d’échecs réseau npm transitoires.
Chaque fragment téléverse `.artifacts/docker-tests/` avec les journaux de voie, les durées, `summary.json`, `failures.json`, les durées de phase, le JSON du planificateur, les tableaux de voies lentes et les commandes de réexécution par voie. L’entrée `docker_lanes` du workflow exécute les voies sélectionnées sur les images préparées au lieu des jobs de fragments, ce qui limite le débogage d’une voie en échec à un seul job Docker ciblé et prépare, télécharge ou réutilise l’artefact de package pour cette exécution ; si une voie sélectionnée est une voie Docker live, le job ciblé construit localement l’image de test live pour cette réexécution. Les commandes de réexécution GitHub générées par voie incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, de sorte qu’une voie en échec puisse réutiliser exactement le package et les images de l’exécution échouée.
Chaque fragment téléverse `.artifacts/docker-tests/` avec les journaux de voie, les timings, `summary.json`, `failures.json`, les timings de phase, le JSON du plan d’ordonnancement, les tableaux des voies lentes et les commandes de relance par voie. L’entrée de workflow `docker_lanes` exécute les voies sélectionnées sur les images préparées au lieu des jobs de fragments, ce qui limite le débogage des voies en échec à un seul job Docker ciblé et prépare, télécharge ou réutilise l’artefact de package pour cette exécution ; si une voie sélectionnée est une voie Docker live, le job ciblé construit localement l’image de test live pour cette relance. Les commandes de relance GitHub générées par voie incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, afin qu’une voie en échec puisse réutiliser exactement le package et les images de l’exécution échouée.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
@ -302,47 +302,47 @@ Le workflow live/E2E planifié exécute quotidiennement la suite Docker complèt
## Préversion de Plugin
`Plugin Prerelease` offre une couverture produit/package plus coûteuse ; il s’agit donc d’un workflow distinct déclenché par `Full Release Validation` ou par un opérateur explicite. Les pull requests normales, les pushes sur `main` et les dispatches CI manuels autonomes gardent cette suite désactivée. Il répartit les tests des plugins groupés sur huit workers d’extension ; ces jobs de fragments d’extension exécutent jusqu’à deux groupes de configuration de plugin à la fois, avec un worker Vitest par groupe et un tas Node plus grand afin que les lots de plugins lourds en imports ne créent pas de jobs CI supplémentaires.
`Plugin Prerelease` offre une couverture produit/package plus coûteuse, c’est donc un workflow séparé déclenché par `Full Release Validation` ou par un opérateur explicite. Les pull requests normales, les poussées sur `main` et les dispatchs CI manuels autonomes laissent cette suite désactivée. Il répartit les tests des Plugins groupés sur huit workers d’extension ; ces jobs de shards d’extension exécutent jusqu’à deux groupes de configuration de Plugin à la fois, avec un worker Vitest par groupe et un tas Node plus grand, afin que les lots de Plugins lourds en imports ne créent pas de jobs CI supplémentaires.
## Labo QA
## Laboratoire QA
Le Labo QA dispose de voies CI dédiées en dehors du workflow principal à périmètre intelligent.
QA Lab dispose de voies CI dédiées en dehors du workflow principal à portée intelligente.
- Le workflow `Parity gate` s’exécute sur les changements de PR correspondants et par dispatch manuel ; il construit le runtime QA privé et compare les packs agentiques fictifs GPT-5.5 et Opus 4.6.
- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et par dispatch manuel ; il répartit en jobs parallèles la porte de parité fictive, la voie Matrix live, ainsi que les voies Telegram et Discord live. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des baux Convex.
- Le workflow `Parity gate` s’exécute sur les changements de PR correspondants et par dispatch manuel ; il construit le runtime QA privé et compare les packs agentiques simulés GPT-5.5 et Opus 4.6.
- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et par dispatch manuel ; il distribue en jobs parallèles la porte de parité simulée, la voie Matrix live et les voies Telegram et Discord live. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des baux Convex.
Les contrôles de publication exécutent les voies de transport live Matrix et Telegram avec le fournisseur fictif déterministe et des modèles qualifiés pour le mock (`mock-openai/gpt-5.5` et `mock-openai/gpt-5.5-alt`), afin que le contrat de canal soit isolé de la latence des modèles live et du démarrage normal des plugins fournisseurs. Le Gateway de transport live désactive la recherche mémoire, car la parité QA couvre séparément le comportement mémoire ; la connectivité fournisseur est couverte par les suites distinctes de modèles live, fournisseurs natifs et fournisseurs Docker.
Les vérifications de publication exécutent les voies de transport live Matrix et Telegram avec le fournisseur simulé déterministe et les modèles qualifiés mock (`mock-openai/gpt-5.5` et `mock-openai/gpt-5.5-alt`) afin que le contrat de canal soit isolé de la latence des modèles live et du démarrage normal des Plugins de fournisseur. Le gateway de transport live désactive la recherche mémoire parce que la parité QA couvre séparément le comportement mémoire ; la connectivité fournisseur est couverte par les suites séparées de modèles live, de fournisseurs natifs et de fournisseurs Docker.
Matrix utilise `--profile fast` pour les portes planifiées et de publication, en ajoutant `--fail-fast` uniquement lorsque la CLI extraite le prend en charge. La valeur par défaut de la CLI et l’entrée manuelle du workflow restent `all` ; un dispatch manuel `matrix_profile=all` fragmente toujours la couverture Matrix complète en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`.
Matrix utilise `--profile fast` pour les portes planifiées et de publication, en ajoutant `--fail-fast` uniquement lorsque la CLI extraite le prend en charge. La valeur par défaut de la CLI et l’entrée de workflow manuelle restent `all` ; le dispatch manuel `matrix_profile=all` répartit toujours la couverture Matrix complète en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`.
`OpenClaw Release Checks` exécute également les voies QA Lab critiques pour la publication avant l’approbation de publication ; sa porte de parité QA exécute les packs candidat et de référence comme jobs de voies parallèles, puis télécharge les deux artefacts dans un petit job de rapport pour la comparaison finale de parité.
`OpenClaw Release Checks` exécute également les voies QA Lab critiques pour la publication avant l’approbation de publication ; sa porte de parité QA exécute les packs candidat et de référence comme jobs de voie parallèles, puis télécharge les deux artefacts dans un petit job de rapport pour la comparaison de parité finale.
Ne placez pas le chemin d’intégration des PR derrière `Parity gate` sauf si le changement touche réellement au runtime QA, à la parité des packs de modèles ou à une surface appartenant au workflow de parité. Pour les correctifs normaux de canal, de configuration, de documentation ou de tests unitaires, traitez-le comme un signal facultatif et suivez plutôt les preuves CI/contrôles à périmètre défini.
Ne placez pas le chemin de landing de PR derrière `Parity gate` sauf si le changement touche réellement le runtime QA, la parité des packs de modèles ou une surface détenue par le workflow de parité. Pour les corrections normales de canal, de configuration, de documentation ou de tests unitaires, traitez-le comme un signal facultatif et suivez plutôt les preuves CI/vérifications à portée limitée.
## CodeQL
Le workflow `CodeQL` est intentionnellement un analyseur de sécurité étroit de premier passage, et non un balayage complet du dépôt. Les exécutions quotidiennes, manuelles et de garde sur pull requests non brouillons analysent le code des workflows Actions ainsi que les surfaces JavaScript/TypeScript les plus risquées, avec des requêtes de sécurité à haute confiance filtrées sur `security-severity` élevée/critique.
Le workflow `CodeQL` est volontairement un analyseur de sécurité de premier passage étroit, et non un balayage complet du dépôt. Les exécutions quotidiennes, manuelles et de garde des pull requests non brouillon analysent le code des workflows Actions ainsi que les surfaces JavaScript/TypeScript les plus à risque, avec des requêtes de sécurité à haute confiance filtrées sur les `security-severity` élevées/critiques.
La garde des pull requests reste légère : elle démarre uniquement pour les changements sous `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, et exécute la même matrice de sécurité à haute confiance que le workflow planifié. Android et macOS CodeQL restent exclus des valeurs par défaut des PR.
La garde des pull requests reste légère : elle ne démarre que pour les changements sous `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, et elle exécute la même matrice de sécurité à haute confiance que le workflow planifié. CodeQL Android et macOS restent exclus des valeurs par défaut des PR.
### Catégories de sécurité
| Catégorie | Surface |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Authentification, secrets, sandbox, Cron et référence du Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation du canal principal, plus runtime de plugin de canal, Gateway, SDK Plugin, secrets et points de contact d’audit |
| `/codeql-security-high/network-ssrf-boundary` | Surfaces SSRF principales, analyse IP, garde réseau, web-fetch et politique SSRF du SDK Plugin |
| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, helpers d’exécution de processus, livraison sortante et portes d’exécution d’outils agent |
| `/codeql-security-high/plugin-trust-boundary` | Installation de Plugin, chargeur, manifeste, registre, préparation des dépendances runtime, chargement des sources et surfaces de confiance du contrat de package du SDK Plugin |
| `/codeql-security-high/core-auth-secrets` | Authentification, secrets, sandbox, cron et base de référence du Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation des canaux cœur, plus le runtime de Plugin de canal, le Gateway, le SDK Plugin, les secrets et les points de contact d’audit |
| `/codeql-security-high/network-ssrf-boundary` | Surfaces SSRF cœur, analyse IP, garde réseau, récupération web et politique SSRF du SDK Plugin |
| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, assistants d’exécution de processus, livraison sortante et portes d’exécution d’outils agent |
| `/codeql-security-high/plugin-trust-boundary` | Surfaces de confiance de l’installation de Plugin, du chargeur, du manifeste, du registre, de la mise en attente des dépendances runtime, du chargement de source et du contrat de package du SDK Plugin |
### Fragments de sécurité spécifiques à la plateforme
### Shards de sécurité propres aux plateformes
- `CodeQL Android Critical Security` — fragment de sécurité Android planifié. Construit manuellement l’application Android pour CodeQL sur le plus petit runner Blacksmith Linux accepté par la vérification de cohérence du workflow. Téléverse sous `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — fragment de sécurité macOS hebdomadaire/manuel. Construit manuellement l’application macOS pour CodeQL sur Blacksmith macOS, filtre les résultats de build de dépendances hors du SARIF téléversé et téléverse sous `/codeql-critical-security/macos`. Conservé hors des valeurs quotidiennes par défaut, car le build macOS domine la durée d’exécution même lorsqu’il est propre.
- `CodeQL Android Critical Security` — shard de sécurité Android planifié. Construit manuellement l’application Android pour CodeQL sur le plus petit runner Blacksmith Linux accepté par la vérification de cohérence du workflow. Téléverse sous `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard de sécurité macOS hebdomadaire/manuel. Construit manuellement l’application macOS pour CodeQL sur Blacksmith macOS, filtre les résultats de build de dépendances hors du SARIF téléversé, et téléverse sous `/codeql-critical-security/macos`. Conservé hors des valeurs par défaut quotidiennes parce que le build macOS domine le temps d’exécution même lorsqu’il est propre.
### Catégories de qualité critiques
### Catégories de qualité critique
`CodeQL Critical Quality` est le fragment non lié à la sécurité correspondant. Il exécute uniquement des requêtes de qualité JavaScript/TypeScript de sévérité erreur et non liées à la sécurité sur des surfaces étroites à forte valeur, sur le plus petit runner Blacksmith Linux. Sa garde de pull request est intentionnellement plus réduite que le profil planifié : les PR non brouillons exécutent uniquement les fragments correspondants `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` et `plugin-sdk-reply-runtime` pour les changements de code d’exécution des commandes/modèles/outils d’agent et de dispatch de réponses, de code de schéma/migration/E/S de configuration, de code auth/secrets/sandbox/sécurité, de runtime des canaux principaux et des plugins de canaux groupés, de protocole Gateway/méthode serveur, de runtime mémoire/liaison SDK, de MCP/processus/livraison sortante, de runtime fournisseur/catalogue de modèles, de diagnostics de session/files de livraison, de chargeur de plugin, de SDK Plugin/contrat de package ou de runtime de réponse du SDK Plugin. Les changements de configuration CodeQL et de workflow qualité exécutent les douze fragments de qualité PR.
`CodeQL Critical Quality` est le shard non lié à la sécurité correspondant. Il exécute uniquement des requêtes de qualité JavaScript/TypeScript de sévérité erreur et non liées à la sécurité sur des surfaces étroites à forte valeur, sur le plus petit runner Blacksmith Linux. Sa garde de pull request est volontairement plus petite que le profil planifié : les PR non brouillon n’exécutent que les shards correspondants `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` et `plugin-sdk-reply-runtime` pour les changements concernant l’exécution de commandes/modèles/outils agent et le code de dispatch des réponses, le schéma/la migration/les E/S de configuration, le code d’authentification/secrets/sandbox/sécurité, le runtime des canaux cœur et des Plugins de canaux groupés, le protocole/la méthode serveur du Gateway, la colle runtime/SDK de mémoire, MCP/processus/livraison sortante, le runtime fournisseur/catalogue de modèles, les diagnostics de session/files de livraison, le chargeur de Plugin, le contrat SDK Plugin/package, ou le runtime de réponse du SDK Plugin. Les changements de configuration CodeQL et de workflow qualité exécutent les douze shards qualité de PR.
Le dispatch manuel accepte :
@ -350,40 +350,40 @@ Le dispatch manuel accepte :
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Les profils étroits sont des points d’entrée d’apprentissage et d’itération pour exécuter un fragment de qualité isolément.
Les profils étroits sont des points d’entrée d’apprentissage/itération pour exécuter un shard qualité isolément.
| Catégorie | Surface |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Code de frontière de sécurité pour l’authentification, les secrets, le sandbox, Cron et le Gateway |
| `/codeql-critical-quality/config-boundary` | Schéma de configuration, migration, normalisation et contrats d’E/S |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas du protocole Gateway et contrats des méthodes serveur |
| `/codeql-critical-quality/channel-runtime-boundary` | Contrats d’implémentation du canal principal et du plugin de canal groupé |
| `/codeql-critical-quality/agent-runtime-boundary` | Exécution des commandes, dispatch des modèles/fournisseurs, dispatch et files de réponse automatique, et contrats d’exécution du plan de contrôle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serveurs MCP et ponts d’outils, assistants de supervision de processus, et contrats de livraison sortante |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK de l’hôte mémoire, façades d’exécution mémoire, alias mémoire du Plugin SDK, logique d’activation de l’exécution mémoire, et commandes doctor de mémoire |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internes de la file de réponses, files de livraison de session, assistants de liaison/livraison de session sortante, surfaces de bundle d’événements/journaux de diagnostic, et contrats CLI doctor de session |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch des réponses entrantes du Plugin SDK, assistants de charge utile/découpage/exécution des réponses, options de réponse de canal, files de livraison, et assistants de liaison session/fil |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte des fournisseurs, enregistrement de l’exécution des fournisseurs, valeurs par défaut/catalogues des fournisseurs, et registres web/recherche/récupération/embedding |
| `/codeql-critical-quality/ui-control-plane` | Amorçage de l’interface de contrôle, persistance locale, flux de contrôle du Gateway, et contrats d’exécution du plan de contrôle des tâches |
| `/codeql-critical-quality/web-media-runtime-boundary` | Contrats d’exécution pour la récupération/recherche web principale, les E/S média, la compréhension média, la génération d’images et la génération de médias |
| `/codeql-critical-quality/plugin-boundary` | Contrats du chargeur, du registre, de la surface publique et des points d’entrée du Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Source du Plugin SDK côté package publié et assistants de contrat de package de plugin |
| Catégorie | Surface |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Code de limite de sécurité pour l’authentification, les secrets, le bac à sable, Cron et le Gateway |
| `/codeql-critical-quality/config-boundary` | Schéma de configuration, migration, normalisation et contrats d’E/S |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas du protocole Gateway et contrats de méthodes serveur |
| `/codeql-critical-quality/channel-runtime-boundary` | Contrats d’implémentation du canal central et des Plugins de canal intégrés |
| `/codeql-critical-quality/agent-runtime-boundary` | Exécution des commandes, dispatch des modèles/fournisseurs, dispatch et files d’attente des réponses automatiques, et contrats d’exécution du plan de contrôle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serveurs MCP et ponts d’outils, assistants de supervision de processus et contrats de livraison sortante |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hôte de mémoire, façades d’exécution de mémoire, alias du SDK de Plugin mémoire, liaison d’activation de l’exécution mémoire et commandes doctor de mémoire |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internes de file de réponses, files de livraison de session, assistants de liaison/livraison de session sortante, surfaces d’événements diagnostiques/de bundles de journaux, et contrats CLI doctor de session |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch des réponses entrantes du SDK de Plugin, assistants de charge utile/segmentation/exécution des réponses, options de réponse de canal, files de livraison et assistants de liaison session/fil |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte des fournisseurs, enregistrement de l’exécution des fournisseurs, valeurs par défaut/catalogues des fournisseurs, et registres web/recherche/récupération/embeddings |
| `/codeql-critical-quality/ui-control-plane` | Amorçage de l’interface de contrôle, persistance locale, flux de contrôle du Gateway et contrats d’exécution du plan de contrôle des tâches |
| `/codeql-critical-quality/web-media-runtime-boundary` | Contrats d’exécution pour la récupération/recherche web centrale, les E/S média, la compréhension des médias, la génération d’images et la génération de médias |
| `/codeql-critical-quality/plugin-boundary` | Contrats du chargeur, du registre, de la surface publique et des points d’entrée du SDK de Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Source du SDK de Plugin côté package publié et assistants de contrat de package de Plugin |
La qualité reste séparée de la sécurité afin que les constats de qualité puissent être planifiés, mesurés, désactivés ou étendus sans masquer le signal de sécurité. L’extension CodeQL pour Swift, Python et les plugins groupés ne doit être réintroduite sous forme de travail de suivi ciblé ou fragmenté qu’une fois que les profils restreints disposent d’une exécution et d’un signal stables.
La qualité reste séparée de la sécurité afin que les constats de qualité puissent être planifiés, mesurés, désactivés ou étendus sans masquer le signal de sécurité. L’extension CodeQL à Swift, Python et aux Plugins intégrés ne doit être réintégrée sous forme de travail de suivi limité ou partitionné qu’une fois que les profils étroits disposent d’une exécution et d’un signal stables.
## Workflows de maintenance
### Docs Agent
Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par les événements pour garder la documentation existante alignée sur les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie issue d’un push non-bot sur `main` peut le déclencher, et un déclenchement manuel peut l’exécuter directement. Les invocations par workflow-run sont ignorées lorsque `main` a avancé ou lorsqu’une autre exécution non ignorée de Docs Agent a été créée au cours de la dernière heure. Lorsqu’il s’exécute, il examine la plage de commits allant du précédent SHA source non ignoré de Docs Agent jusqu’au `main` actuel, de sorte qu’une exécution horaire peut couvrir tous les changements de main accumulés depuis la dernière passe de documentation.
Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par événements pour maintenir les docs existantes alignées avec les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie déclenchée par un push non-bot sur `main` peut le lancer, et un dispatch manuel peut l’exécuter directement. Les invocations par workflow-run sont ignorées lorsque `main` a avancé ou lorsqu’une autre exécution Docs Agent non ignorée a été créée dans la dernière heure. Lorsqu’il s’exécute, il examine la plage de commits allant du SHA source du précédent Docs Agent non ignoré jusqu’au `main` actuel, de sorte qu’une exécution horaire peut couvrir tous les changements de main accumulés depuis le dernier passage docs.
### Test Performance Agent
Le workflow `Test Performance Agent` est une voie de maintenance Codex pilotée par les événements pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie issue d’un push non-bot sur `main` peut le déclencher, mais il s’interrompt si une autre invocation par workflow-run a déjà été exécutée ou est en cours ce jour UTC. Le déclenchement manuel contourne cette barrière d’activité quotidienne. La voie construit un rapport de performance Vitest groupé pour toute la suite, autorise Codex à n’apporter que de petites corrections de performance de tests préservant la couverture au lieu de larges refactorisations, puis réexécute le rapport de toute la suite et rejette les changements qui réduisent le nombre de tests de référence réussis. Si la référence contient des tests en échec, Codex ne peut corriger que les échecs évidents et le rapport de toute la suite après l’agent doit réussir avant que quoi que ce soit soit committé. Lorsque `main` avance avant que le push du bot n’atterrisse, la voie rebase le correctif validé, réexécute `pnpm check:changed`, puis retente le push ; les correctifs obsolètes en conflit sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex puisse conserver la même posture de sécurité sans sudo que l’agent de documentation.
Le workflow `Test Performance Agent` est une voie de maintenance Codex pilotée par événements pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie déclenchée par un push non-bot sur `main` peut le lancer, mais il s’interrompt si une autre invocation par workflow-run a déjà été exécutée ou est en cours ce jour UTC. Le dispatch manuel contourne cette barrière d’activité quotidienne. Cette voie construit un rapport de performance Vitest groupé sur la suite complète, permet à Codex de n’effectuer que de petites corrections de performance de tests qui préservent la couverture au lieu de vastes refactorisations, puis relance le rapport sur la suite complète et rejette les changements qui réduisent le nombre de tests réussis dans la référence. Si la référence comporte des tests en échec, Codex ne peut corriger que les échecs évidents et le rapport de suite complète après agent doit réussir avant tout commit. Lorsque `main` avance avant que le push du bot n’atterrisse, la voie rebase le patch validé, relance `pnpm check:changed` et réessaie le push ; les patchs obsolètes en conflit sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex puisse conserver la même posture de sécurité sans sudo que l’agent docs.
### PR dupliquées après merge
### PRs dupliquées après fusion
Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel pour le nettoyage des doublons après intégration. Il est en simulation par défaut et ne ferme que les PR explicitement listées lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est fusionnée et que chaque doublon possède soit une issue référencée en commun, soit des hunks modifiés qui se chevauchent.
Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel destiné au nettoyage des doublons après intégration. Il utilise le mode simulation par défaut et ne ferme que les PRs explicitement listées lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est fusionnée et que chaque doublon possède soit une issue référencée commune, soit des hunks modifiés qui se chevauchent.
```bash
gh workflow run duplicate-after-merge.yml \
@ -394,25 +394,25 @@ gh workflow run duplicate-after-merge.yml \
## Portes de vérification locales et routage des changements
La logique locale des voies modifiées se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte de vérification locale est plus stricte sur les frontières d’architecture que le périmètre large de la plateforme CI :
La logique locale des voies de changements se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte de vérification locale est plus stricte sur les limites d’architecture que le périmètre large de la plateforme CI :
- les changements de production du cœur exécutent la vérification de types prod du cœur et tests du cœur, plus le lint/les gardes du cœur ;
- les changements concernant uniquement les tests du cœur exécutent seulement la vérification de types des tests du cœur plus le lint du cœur ;
- les changements de production des plugins exécutent la vérification de types prod des plugins et tests des plugins, plus le lint des plugins ;
- les changements concernant uniquement les tests des plugins exécutent la vérification de types des tests des plugins plus le lint des plugins ;
- les changements du Plugin SDK public ou du contrat de plugin s’étendent à la vérification de types des plugins parce que les plugins dépendent de ces contrats du cœur (les balayages d’extensions Vitest restent un travail de test explicite) ;
- les augmentations de version limitées aux métadonnées de release exécutent des vérifications ciblées de version/configuration/dépendances racine ;
- les changements racine/configuration inconnus échouent prudemment vers toutes les voies de vérification.
- les changements de production du cœur exécutent le typecheck de production du cœur et des tests du cœur, ainsi que le lint/les gardes du cœur ;
- les changements limités aux tests du cœur n’exécutent que le typecheck des tests du cœur et le lint du cœur ;
- les changements de production d’extension exécutent le typecheck de production et de test des extensions, ainsi que le lint des extensions ;
- les changements limités aux tests d’extension exécutent le typecheck des tests d’extension et le lint des extensions ;
- les changements publics du SDK de Plugin ou des contrats de Plugin s’étendent au typecheck des extensions, car les extensions dépendent de ces contrats du cœur (les balayages Vitest d’extensions restent un travail de test explicite) ;
- les incréments de version limités aux métadonnées de release exécutent des vérifications ciblées de version/configuration/dépendances racine ;
- les changements racine/config inconnus échouent prudemment vers toutes les voies de vérification.
Le routage local des tests modifiés se trouve dans `scripts/test-projects.test-support.mjs` et est intentionnellement moins coûteux que `check:changed` : les modifications directes de tests s’exécutent elles-mêmes, les modifications de source privilégient les correspondances explicites, puis les tests frères et les dépendants du graphe d’import. La configuration partagée de livraison group-room fait partie des correspondances explicites : les changements apportés à la configuration des réponses visibles de groupe, au mode de livraison des réponses source ou au prompt système de l’outil de message passent par les tests de réponse du cœur, plus les régressions de livraison Discord et Slack, afin qu’un changement de valeur par défaut partagée échoue avant le premier push de PR. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque le changement est suffisamment global au harnais pour que l’ensemble mappé peu coûteux ne soit pas un proxy fiable.
Le routage local des tests modifiés se trouve dans `scripts/test-projects.test-support.mjs` et est volontairement moins coûteux que `check:changed` : les modifications directes de tests exécutent ces tests eux-mêmes, les modifications de source privilégient les mappings explicites, puis les tests voisins et les dépendants du graphe d’import. La configuration partagée de livraison de salle de groupe fait partie des mappings explicites : les changements apportés à la configuration de réponse visible du groupe, au mode de livraison des réponses source ou au prompt système de l’outil de messages passent par les tests de réponse du cœur ainsi que par les régressions de livraison Discord et Slack, afin qu’un changement de valeur par défaut partagée échoue avant le premier push de PR. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque le changement touche assez largement le harnais pour que l’ensemble mappé peu coûteux ne soit pas un proxy fiable.
## Validation Testbox
Exécutez Testbox depuis la racine du dépôt et privilégiez une boîte fraîche préchauffée pour les preuves larges. Avant de consacrer une porte lente à une boîte réutilisée, expirée ou qui vient de signaler une synchronisation inhabituellement volumineuse, exécutez d’abord `pnpm testbox:sanity` dans la boîte.
Exécutez Testbox depuis la racine du dépôt et privilégiez une box fraîche préchauffée pour les preuves larges. Avant de consacrer une porte lente à une box réutilisée, expirée ou venant de signaler une synchronisation anormalement volumineuse, exécutez d’abord `pnpm testbox:sanity` dans la box.
La vérification de cohérence échoue rapidement lorsque des fichiers racine requis comme `pnpm-lock.yaml` ont disparu ou lorsque `git status --short` affiche au moins 200 suppressions suivies. Cela signifie généralement que l’état de synchronisation distant n’est pas une copie fiable de la PR ; arrêtez cette boîte et préchauffez-en une nouvelle au lieu de déboguer l’échec du test produit. Pour les PR avec suppressions massives intentionnelles, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution de cohérence.
La vérification de sanité échoue rapidement lorsque des fichiers racine requis comme `pnpm-lock.yaml` ont disparu ou lorsque `git status --short` affiche au moins 200 suppressions suivies. Cela signifie généralement que l’état de synchronisation distant n’est pas une copie fiable de la PR ; arrêtez cette box et préchauffez-en une nouvelle au lieu de déboguer l’échec du test produit. Pour les PRs comportant intentionnellement de nombreuses suppressions, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution de sanité.
`pnpm testbox:run` termine également une invocation locale du CLI Blacksmith qui reste en phase de synchronisation plus de cinq minutes sans sortie post-synchronisation. Définissez `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` pour désactiver cette garde, ou utilisez une valeur plus grande en millisecondes pour des diffs locaux inhabituellement volumineux.
`pnpm testbox:run` termine également une invocation locale de la CLI Blacksmith qui reste en phase de synchronisation pendant plus de cinq minutes sans sortie post-synchronisation. Définissez `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` pour désactiver cette garde, ou utilisez une valeur en millisecondes plus élevée pour des diffs locaux exceptionnellement volumineux.
## Connexe

144
docs/fr/concepts/agent-loop.md
View File

@ -1,48 +1,49 @@
---
read_when:
- Vous avez besoin d’une procédure pas à pas exacte de la boucle d’agent ou des événements de cycle de vie
- Vous modifiez la mise en file d’attente des sessions, les écritures de transcription ou le comportement du verrou d’écriture de session
summary: Cycle de vie de la boucle de l’agent, flux et sémantique d’attente
title: Boucle de l’agent
- Vous avez besoin d’une procédure pas à pas exacte de la boucle de l’agent ou des événements du cycle de vie
- Vous modifiez la mise en file d’attente des sessions, les écritures dans la transcription ou le comportement du verrou d’écriture de session
summary: Cycle de vie de la boucle d’agent, flux et sémantique d’attente
title: Boucle d’agent
x-i18n:
generated_at: "2026-04-30T07:20:37Z"
generated_at: "2026-04-30T18:38:49Z"
model: gpt-5.5
provider: openai
source_hash: 902d543bd71dd517a810d825cbe92e244fe89230f47eeada72477c657a2bec32
source_hash: 5466893253e1f82482284ff82db56f4c3fca018bf12e4114fad76d37cad954df
source_path: concepts/agent-loop.md
workflow: 16
---
Une boucle agentique est l’exécution complète et « réelle » d’un agent : réception → assemblage du contexte → inférence du modèle →
Une boucle agentique est l’exécution « réelle » complète d’un agent : réception → assemblage du contexte → inférence du modèle →
exécution d’outils → réponses en streaming → persistance. C’est le chemin faisant autorité qui transforme un message
en actions et en réponse finale, tout en maintenant l’état de session cohérent.
en actions et en réponse finale, tout en conservant un état de session cohérent.
Dans OpenClaw, une boucle est une exécution unique, sérialisée par session, qui émet des événements de cycle de vie et de flux
pendant que le modèle réfléchit, appelle des outils et diffuse la sortie. Ce document explique comment cette boucle authentique est
Dans OpenClaw, une boucle est une exécution unique et sérialisée par session, qui émet des événements de cycle de vie et de flux
pendant que le modèle raisonne, appelle des outils et diffuse la sortie. Ce document explique comment cette boucle authentique est
câblée de bout en bout.
## Points d’entrée
- RPC du Gateway : `agent` et `agent.wait`.
- RPC Gateway : `agent` et `agent.wait`.
- CLI : commande `agent`.
## Fonctionnement (vue d’ensemble)
1. Le RPC `agent` valide les paramètres, résout la session (sessionKey/sessionId), persiste les métadonnées de session, puis renvoie immédiatement `{ runId, acceptedAt }`.
1. Le RPC `agent` valide les paramètres, résout la session (sessionKey/sessionId), persiste les métadonnées de session, renvoie immédiatement `{ runId, acceptedAt }`.
2. `agentCommand` exécute l’agent :
- résout les valeurs par défaut du modèle + thinking/verbose/trace
- charge l’instantané des Skills
- résout le modèle et les valeurs par défaut de réflexion/verbosité/trace
- charge l’instantané Skills
- appelle `runEmbeddedPiAgent` (runtime pi-agent-core)
- émet **lifecycle end/error** si la boucle intégrée n’en émet pas
- émet **lifecycle end/error** si la boucle embarquée n’en émet pas
3. `runEmbeddedPiAgent` :
- sérialise les exécutions via des files d’attente par session + globales
- résout le modèle + le profil d’authentification et construit la session Pi
- s’abonne aux événements Pi et diffuse les deltas assistant/outil
- applique le délai d’expiration -> abandonne l’exécution s’il est dépassé
- renvoie les payloads + les métadonnées d’utilisation
4. `subscribeEmbeddedPiSession` relie les événements pi-agent-core au flux `agent` d’OpenClaw :
- sérialise les exécutions via des files par session et globales
- résout le modèle et le profil d’authentification, puis construit la session pi
- s’abonne aux événements pi et diffuse les deltas assistant/outil
- applique le délai d’expiration -> interrompt l’exécution s’il est dépassé
- pour les tours app-server Codex, interrompt un tour accepté qui cesse de produire une progression app-server avant un événement terminal
- renvoie les payloads et les métadonnées d’utilisation
4. `subscribeEmbeddedPiSession` fait le pont entre les événements pi-agent-core et le flux `agent` d’OpenClaw :
- événements d’outil => `stream: "tool"`
- deltas d’assistant => `stream: "assistant"`
- deltas assistant => `stream: "assistant"`
- événements de cycle de vie => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` utilise `waitForAgentRun` :
- attend **lifecycle end/error** pour `runId`
@ -53,137 +54,138 @@ câblée de bout en bout.
- Les exécutions sont sérialisées par clé de session (voie de session) et éventuellement via une voie globale.
- Cela évite les courses entre outils/sessions et maintient l’historique de session cohérent.
- Les canaux de messagerie peuvent choisir des modes de file d’attente (collect/steer/followup) qui alimentent ce système de voies.
Voir [File d’attente des commandes](/fr/concepts/queue).
Voir [File de commandes](/fr/concepts/queue).
- Les écritures de transcript sont également protégées par un verrou d’écriture de session sur le fichier de session. Le verrou est
conscient des processus et basé sur un fichier ; il détecte donc les rédacteurs qui contournent la file en processus ou proviennent
conscient des processus et basé sur les fichiers, ce qui lui permet de détecter les rédacteurs qui contournent la file en processus ou proviennent
d’un autre processus.
- Les verrous d’écriture de session ne sont pas réentrants par défaut. Si un assistant imbrique intentionnellement l’acquisition du
- Par défaut, les verrous d’écriture de session ne sont pas réentrants. Si un assistant imbrique intentionnellement l’acquisition du
même verrou tout en préservant un seul rédacteur logique, il doit l’activer explicitement avec
`allowReentrant: true`.
## Préparation de la session + de l’espace de travail
- L’espace de travail est résolu et créé ; les exécutions en bac à sable peuvent être redirigées vers une racine d’espace de travail de bac à sable.
- Les Skills sont chargés (ou réutilisés depuis un instantané) et injectés dans l’environnement et le prompt.
- Les fichiers de bootstrap/contexte sont résolus et injectés dans le rapport du prompt système.
- Un verrou d’écriture de session est acquis ; `SessionManager` est ouvert et préparé avant le streaming. Tout chemin ultérieur de
réécriture, Compaction ou troncature du transcript doit prendre le même verrou avant d’ouvrir ou de modifier le fichier de transcript.
- Les Skills sont chargées (ou réutilisées depuis un instantané) et injectées dans l’environnement et le prompt.
- Les fichiers de bootstrap/contexte sont résolus et injectés dans le rapport de prompt système.
- Un verrou d’écriture de session est acquis ; `SessionManager` est ouvert et préparé avant le streaming. Tout
chemin ultérieur de réécriture, de Compaction ou de troncature du transcript doit prendre le même verrou avant d’ouvrir ou
de modifier le fichier de transcript.
## Assemblage du prompt + prompt système
- Le prompt système est construit à partir du prompt de base d’OpenClaw, du prompt des Skills, du contexte de bootstrap et des substitutions par exécution.
- Le prompt système est construit à partir du prompt de base d’OpenClaw, du prompt Skills, du contexte de bootstrap et des remplacements par exécution.
- Les limites propres au modèle et les jetons de réserve de Compaction sont appliqués.
- Voir [Prompt système](/fr/concepts/system-prompt) pour ce que voit le modèle.
## Points de hook (où intercepter)
## Points de hook (où vous pouvez intercepter)
OpenClaw dispose de deux systèmes de hooks :
- **Hooks internes** (hooks Gateway) : scripts pilotés par événements pour les commandes et événements de cycle de vie.
- **Hooks de Plugin** : points d’extension dans le cycle de vie agent/outil et le pipeline du Gateway.
- **Hooks internes** (hooks Gateway) : scripts pilotés par événements pour les commandes et les événements de cycle de vie.
- **Hooks Plugin** : points d’extension dans le cycle de vie agent/outil et le pipeline Gateway.
### Hooks internes (hooks Gateway)
- **`agent:bootstrap`** : s’exécute pendant la construction des fichiers de bootstrap, avant la finalisation du prompt système.
Utilisez-le pour ajouter/supprimer des fichiers de contexte de bootstrap.
- **Hooks de commande** : `/new`, `/reset`, `/stop` et autres événements de commande (voir le document Hooks).
- **Hooks de commande** : `/new`, `/reset`, `/stop` et autres événements de commande (voir la documentation Hooks).
Voir [Hooks](/fr/automation/hooks) pour la configuration et des exemples.
Voir [Hooks](/fr/automation/hooks) pour la configuration et les exemples.
### Hooks de Plugin (cycle de vie agent + Gateway)
### Hooks Plugin (cycle de vie agent + Gateway)
Ceux-ci s’exécutent dans la boucle agent ou le pipeline du Gateway :
Ils s’exécutent dans la boucle de l’agent ou le pipeline Gateway :
- **`before_model_resolve`** : s’exécute avant la session (sans `messages`) pour remplacer de manière déterministe le fournisseur/modèle avant la résolution du modèle.
- **`before_prompt_build`** : s’exécute après le chargement de la session (avec `messages`) pour injecter `prependContext`, `systemPrompt`, `prependSystemContext` ou `appendSystemContext` avant l’envoi du prompt. Utilisez `prependContext` pour du texte dynamique par tour et les champs de contexte système pour des directives stables qui doivent résider dans l’espace du prompt système.
- **`before_agent_start`** : hook de compatibilité hérité qui peut s’exécuter dans l’une ou l’autre phase ; privilégiez les hooks explicites ci-dessus.
- **`before_agent_reply`** : s’exécute après les actions en ligne et avant l’appel LLM, ce qui permet à un Plugin de revendiquer le tour et de renvoyer une réponse synthétique ou de réduire entièrement le tour au silence.
- **`agent_end`** : inspecte la liste finale des messages et les métadonnées d’exécution après la fin.
- **`before_prompt_build`** : s’exécute après le chargement de la session (avec `messages`) pour injecter `prependContext`, `systemPrompt`, `prependSystemContext` ou `appendSystemContext` avant l’envoi du prompt. Utilisez `prependContext` pour le texte dynamique par tour et les champs de contexte système pour les directives stables qui doivent résider dans l’espace du prompt système.
- **`before_agent_start`** : hook de compatibilité hérité qui peut s’exécuter dans l’une ou l’autre phase ; préférez les hooks explicites ci-dessus.
- **`before_agent_reply`** : s’exécute après les actions en ligne et avant l’appel au LLM, ce qui permet à un plugin de prendre en charge le tour et de renvoyer une réponse synthétique ou de réduire entièrement le tour au silence.
- **`agent_end`** : inspecte la liste finale des messages et les métadonnées d’exécution après l’achèvement.
- **`before_compaction` / `after_compaction`** : observe ou annote les cycles de Compaction.
- **`before_tool_call` / `after_tool_call`** : intercepte les paramètres/résultats d’outil.
- **`before_install`** : inspecte les résultats d’analyse intégrés et bloque éventuellement les installations de Skills ou de Plugin.
- **`before_install`** : inspecte les résultats d’analyse intégrés et bloque éventuellement les installations de skill ou de plugin.
- **`tool_result_persist`** : transforme de manière synchrone les résultats d’outil avant leur écriture dans un transcript de session appartenant à OpenClaw.
- **`message_received` / `message_sending` / `message_sent`** : hooks de messages entrants + sortants.
- **`session_start` / `session_end`** : limites du cycle de vie de session.
- **`gateway_start` / `gateway_stop`** : événements du cycle de vie du Gateway.
- **`gateway_start` / `gateway_stop`** : événements du cycle de vie Gateway.
Règles de décision des hooks pour les protections sortantes/d’outils :
Règles de décision des hooks pour les garde-fous sortants/outils :
- `before_tool_call` : `{ block: true }` est terminal et arrête les gestionnaires de priorité inférieure.
- `before_tool_call` : `{ block: false }` est un no-op et n’efface pas un blocage antérieur.
- `before_tool_call` : `{ block: false }` est une absence d’opération et n’efface pas un blocage antérieur.
- `before_install` : `{ block: true }` est terminal et arrête les gestionnaires de priorité inférieure.
- `before_install` : `{ block: false }` est un no-op et n’efface pas un blocage antérieur.
- `before_install` : `{ block: false }` est une absence d’opération et n’efface pas un blocage antérieur.
- `message_sending` : `{ cancel: true }` est terminal et arrête les gestionnaires de priorité inférieure.
- `message_sending` : `{ cancel: false }` est un no-op et n’efface pas une annulation antérieure.
- `message_sending` : `{ cancel: false }` est une absence d’opération et n’efface pas une annulation antérieure.
Voir [Hooks de Plugin](/fr/plugins/hooks) pour l’API de hook et les détails d’enregistrement.
Voir [Hooks Plugin](/fr/plugins/hooks) pour l’API de hook et les détails d’enregistrement.
Les harnesses peuvent adapter ces hooks différemment. Le harness app-server Codex conserve
les hooks de Plugin OpenClaw comme contrat de compatibilité pour les surfaces miroir documentées,
tandis que les hooks natifs Codex restent un mécanisme Codex de plus bas niveau séparé.
les hooks Plugin OpenClaw comme contrat de compatibilité pour les surfaces miroirs documentées,
tandis que les hooks natifs Codex restent un mécanisme Codex de niveau inférieur distinct.
## Streaming + réponses partielles
- Les deltas d’assistant sont diffusés depuis pi-agent-core et émis comme événements `assistant`.
- Le streaming par blocs peut émettre des réponses partielles sur `text_end` ou `message_end`.
- Le streaming de raisonnement peut être émis comme flux distinct ou comme réponses par blocs.
- Voir [Streaming](/fr/concepts/streaming) pour le comportement de découpage et de réponse par blocs.
- Les deltas assistant sont diffusés depuis pi-agent-core et émis comme événements `assistant`.
- Le streaming par bloc peut émettre des réponses partielles soit sur `text_end`, soit sur `message_end`.
- Le streaming du raisonnement peut être émis comme flux séparé ou comme réponses par bloc.
- Voir [Streaming](/fr/concepts/streaming) pour le découpage en fragments et le comportement des réponses par bloc.
## Exécution d’outils + outils de messagerie
- Les événements de début/mise à jour/fin d’outil sont émis sur le flux `tool`.
- Les résultats d’outil sont assainis pour la taille et les payloads d’image avant journalisation/émission.
- Les envois d’outils de messagerie sont suivis afin de supprimer les confirmations d’assistant en double.
- Les envois d’outils de messagerie sont suivis pour supprimer les confirmations assistant dupliquées.
## Mise en forme des réponses + suppression
- Les payloads finaux sont assemblés à partir de :
- texte de l’assistant (et raisonnement facultatif)
- résumés d’outils en ligne (quand verbose + autorisé)
- texte d’erreur de l’assistant quand le modèle échoue
- texte assistant (et raisonnement facultatif)
- résumés d’outils en ligne (quand verbeux + autorisé)
- texte d’erreur assistant quand le modèle échoue
- Le jeton silencieux exact `NO_REPLY` / `no_reply` est filtré des payloads
sortants.
- Les doublons d’outils de messagerie sont supprimés de la liste finale des payloads.
- S’il ne reste aucun payload affichable et qu’un outil a échoué, une réponse d’erreur d’outil de secours est émise
- S’il ne reste aucun payload rendable et qu’un outil a échoué, une réponse de secours d’erreur d’outil est émise
(sauf si un outil de messagerie a déjà envoyé une réponse visible par l’utilisateur).
## Compaction + nouvelles tentatives
- La Compaction automatique émet des événements de flux `compaction` et peut déclencher une nouvelle tentative.
- Lors d’une nouvelle tentative, les tampons en mémoire et les résumés d’outils sont réinitialisés pour éviter les sorties en double.
- Lors de la nouvelle tentative, les tampons en mémoire et les résumés d’outils sont réinitialisés pour éviter une sortie dupliquée.
- Voir [Compaction](/fr/concepts/compaction) pour le pipeline de Compaction.
## Flux d’événements (aujourd’hui)
- `lifecycle` : émis par `subscribeEmbeddedPiSession` (et en secours par `agentCommand`)
- `lifecycle` : émis par `subscribeEmbeddedPiSession` (et en repli par `agentCommand`)
- `assistant` : deltas diffusés depuis pi-agent-core
- `tool` : événements d’outil diffusés depuis pi-agent-core
## Gestion des canaux de chat
- Les deltas d’assistant sont mis en tampon dans des messages `delta` de chat.
- Les deltas assistant sont mis en tampon dans des messages de chat `delta`.
- Un `final` de chat est émis sur **lifecycle end/error**.
## Délais d’expiration
- Valeur par défaut de `agent.wait` : 30 s (seulement l’attente). Le paramètre `timeoutMs` remplace cette valeur.
- Runtime de l’agent : `agents.defaults.timeoutSeconds` vaut par défaut 172800 s (48 heures) ; appliqué dans le minuteur d’abandon de `runEmbeddedPiAgent`.
- Runtime Cron : le `timeoutSeconds` isolé du tour d’agent appartient à Cron. Le planificateur démarre ce minuteur au début de l’exécution, abandonne l’exécution sous-jacente à l’échéance configurée, puis exécute un nettoyage borné avant d’enregistrer le délai d’expiration afin qu’une session enfant obsolète ne puisse pas bloquer la voie.
- Récupération de session bloquée : avec les diagnostics activés, `diagnostics.stuckSessionWarnMs` détecte les longues sessions `processing`. Les exécutions intégrées actives, les opérations de réponse actives et les tâches de voie de session actives restent par défaut limitées à des avertissements ; si les diagnostics ne montrent aucun travail actif pour la session, le watchdog libère la voie de session affectée afin que le travail de démarrage en file d’attente puisse s’écouler.
- Délai d’inactivité du modèle : OpenClaw abandonne une requête de modèle quand aucun fragment de réponse n’arrive avant la fenêtre d’inactivité. `models.providers.<id>.timeoutSeconds` étend ce watchdog d’inactivité pour les fournisseurs locaux/auto-hébergés lents ; sinon OpenClaw utilise `agents.defaults.timeoutSeconds` quand il est configuré, plafonné à 120 s par défaut. Les exécutions déclenchées par Cron sans délai de modèle ou d’agent explicite désactivent le watchdog d’inactivité et s’appuient sur le délai externe de Cron.
- Délai d’expiration des requêtes HTTP fournisseur : `models.providers.<id>.timeoutSeconds` s’applique aux fetchs HTTP de modèle de ce fournisseur, y compris la connexion, les en-têtes, le corps, le délai de requête SDK, la gestion totale d’abandon de fetch protégé et le watchdog d’inactivité du flux du modèle. Utilisez-le pour les fournisseurs locaux/auto-hébergés lents comme Ollama avant d’augmenter le délai d’expiration de tout le runtime de l’agent.
- Runtime de l’agent : valeur par défaut de `agents.defaults.timeoutSeconds` à 172800 s (48 heures) ; appliquée dans le minuteur d’interruption `runEmbeddedPiAgent`.
- Runtime Cron : le `timeoutSeconds` de tour d’agent isolé appartient à cron. Le planificateur démarre ce minuteur au début de l’exécution, interrompt l’exécution sous-jacente à l’échéance configurée, puis lance un nettoyage borné avant d’enregistrer le délai d’expiration afin qu’une session enfant obsolète ne puisse pas bloquer la voie.
- Récupération de session bloquée : avec les diagnostics activés, `diagnostics.stuckSessionWarnMs` détecte les sessions longues en `processing`. Les exécutions embarquées actives, les opérations de réponse actives et les tâches actives de voie de session restent par défaut limitées aux avertissements ; si les diagnostics n’indiquent aucun travail actif pour la session, le watchdog libère la voie de session affectée afin que le travail de démarrage en file puisse s’écouler.
- Délai d’inactivité du modèle : OpenClaw interrompt une requête de modèle quand aucun fragment de réponse n’arrive avant la fenêtre d’inactivité. `models.providers.<id>.timeoutSeconds` étend ce watchdog d’inactivité pour les fournisseurs locaux/auto-hébergés lents ; sinon OpenClaw utilise `agents.defaults.timeoutSeconds` lorsqu’il est configuré, plafonné par défaut à 120 s. Les exécutions déclenchées par Cron sans délai explicite de modèle ou d’agent désactivent le watchdog d’inactivité et s’appuient sur le délai externe de Cron.
- Délai d’expiration des requêtes HTTP du fournisseur : `models.providers.<id>.timeoutSeconds` s’applique aux fetches HTTP de modèle de ce fournisseur, y compris la connexion, les en-têtes, le corps, le délai d’expiration des requêtes SDK, la gestion totale de l’interruption guarded-fetch et le watchdog d’inactivité du flux de modèle. Utilisez-le pour les fournisseurs locaux/auto-hébergés lents tels qu’Ollama avant d’augmenter le délai d’exécution global de l’agent.
## Où les choses peuvent se terminer tôt
- Délai d’expiration de l’agent (abandon)
- Délai d’expiration de l’agent (interruption)
- AbortSignal (annulation)
- Déconnexion du Gateway ou délai d’expiration RPC
- Déconnexion Gateway ou délai d’expiration RPC
- Délai d’expiration de `agent.wait` (attente uniquement, n’arrête pas l’agent)
## Connexe
- [Outils](/fr/tools) — outils d’agent disponibles
- [Hooks](/fr/automation/hooks) — scripts pilotés par événements déclenchés par les événements du cycle de vie de l’agent
- [Hooks](/fr/automation/hooks) — scripts pilotés par événements déclenchés par les événements de cycle de vie de l’agent
- [Compaction](/fr/concepts/compaction) — comment les longues conversations sont résumées
- [Approbations d’exécution](/fr/tools/exec-approvals) — portes d’approbation pour les commandes shell
- [Approbations Exec](/fr/tools/exec-approvals) — barrières d’approbation pour les commandes shell
- [Réflexion](/fr/tools/thinking) — configuration du niveau de réflexion/raisonnement

65
docs/fr/concepts/queue.md
View File

@ -1,19 +1,19 @@
---
read_when:
- Modifier l’exécution ou la concurrence des réponses automatiques
- Explication des modes de /queue ou du comportement d’orientation des messages
summary: Modes de file d’attente de réponse automatique, valeurs par défaut et remplacements par session
- Explication des modes /queue ou du comportement d’orientation des messages
summary: Modes de la file d’attente de réponse automatique, valeurs par défaut et remplacements par session
title: File d’attente des commandes
x-i18n:
generated_at: "2026-04-30T07:23:47Z"
generated_at: "2026-04-30T18:38:41Z"
model: gpt-5.5
provider: openai
source_hash: 2ac0c0ded9558b080714fa4b8be0d552f985911bf19b427020f9654ae4955b2d
source_hash: fbf1bb1ffd4ce06fa138f63e31651b8821226d9c95dd6b93d68326a5fb91fdd0
source_path: concepts/queue.md
workflow: 16
---
Nous sérialisons les exécutions de réponse automatique entrantes (tous les canaux) via une petite file d’attente en processus afin d’éviter les collisions entre plusieurs exécutions d’agent, tout en autorisant un parallélisme sûr entre les sessions.
Nous sérialisons les exécutions de réponse automatique entrantes (tous les canaux) via une petite file d’attente en processus afin d’empêcher plusieurs exécutions d’agent d’entrer en collision, tout en permettant un parallélisme sûr entre les sessions.
## Pourquoi
@ -22,11 +22,11 @@ Nous sérialisons les exécutions de réponse automatique entrantes (tous les ca
## Fonctionnement
- Une file d’attente FIFO consciente des voies vide chaque voie avec une limite de concurrence configurable (1 par défaut pour les voies non configurées ; la voie principale utilise 4 par défaut, les sous-agents 8).
- `runEmbeddedPiAgent` met en file d’attente par **clé de session** (voie `session:<key>`) afin de garantir une seule exécution active par session.
- Chaque exécution de session est ensuite placée dans une **voie globale** (`main` par défaut), de sorte que le parallélisme global est limité par `agents.defaults.maxConcurrent`.
- Une file FIFO tenant compte des voies vide chaque voie avec un plafond de concurrence configurable (1 par défaut pour les voies non configurées ; la voie principale vaut 4 par défaut, les sous-agents 8).
- `runEmbeddedPiAgent` met en file par **clé de session** (voie `session:<key>`) afin de garantir une seule exécution active par session.
- Chaque exécution de session est ensuite mise en file dans une **voie globale** (`main` par défaut) afin que le parallélisme global soit plafonné par `agents.defaults.maxConcurrent`.
- Lorsque la journalisation détaillée est activée, les exécutions en file émettent un court avis si elles ont attendu plus d’environ 2 s avant de démarrer.
- Les indicateurs de saisie se déclenchent toujours immédiatement lors de la mise en file (lorsque le canal le prend en charge), de sorte que l’expérience utilisateur reste inchangée pendant l’attente de notre tour.
- Les indicateurs de saisie se déclenchent toujours immédiatement à la mise en file (lorsque le canal le prend en charge), de sorte que l’expérience utilisateur reste inchangée pendant l’attente de notre tour.
## Valeurs par défaut
@ -39,26 +39,26 @@ Lorsqu’elles ne sont pas définies, toutes les surfaces de canaux entrants uti
`steer` est la valeur par défaut, car elle garde le tour du modèle actif réactif sans
démarrer une seconde exécution de session. Elle vide tous les messages de pilotage arrivés
avant la prochaine limite du modèle. Si l’exécution actuelle ne peut pas accepter le pilotage,
OpenClaw revient à une entrée de file de suivi.
avant la prochaine frontière de modèle. Si l’exécution actuelle ne peut pas accepter le pilotage,
OpenClaw se replie sur une entrée de file de suivi.
## Modes de file d’attente
Les messages entrants peuvent piloter l’exécution actuelle, attendre un tour de suivi, ou faire les deux :
- `steer` : met les messages de pilotage en file dans le runtime actif. Pi livre tous les messages de pilotage en attente **après la fin de l’exécution des appels d’outils du tour actuel de l’assistant**, avant le prochain appel LLM ; le serveur d’application Codex reçoit un `turn/steer` groupé. Si l’exécution n’est pas en diffusion active ou si le pilotage est indisponible, OpenClaw revient à une entrée de file de suivi.
- `queue` (hérité) : ancien pilotage un par un. Pi livre un message de pilotage en file à chaque limite du modèle ; le serveur d’application Codex reçoit des requêtes `turn/steer` distinctes. Préférez `steer`, sauf si vous avez besoin du comportement sérialisé précédent.
- `steer` : met en file les messages de pilotage dans le runtime actif. Pi livre tous les messages de pilotage en attente **après que le tour d’assistant actuel a fini d’exécuter ses appels d’outils**, avant le prochain appel LLM ; le serveur d’application Codex reçoit un `turn/steer` groupé. Si l’exécution n’est pas en diffusion active ou si le pilotage n’est pas disponible, OpenClaw se replie sur une entrée de file de suivi.
- `queue` (hérité) : ancien pilotage un par un. Pi livre un message de pilotage en file à chaque frontière de modèle ; le serveur d’application Codex reçoit des requêtes `turn/steer` séparées. Préférez `steer`, sauf si vous avez besoin du comportement sérialisé précédent.
- `followup` : met chaque message en file pour un tour d’agent ultérieur après la fin de l’exécution actuelle.
- `collect` : fusionne les messages en file dans un **seul** tour de suivi après la fenêtre de silence. Si les messages ciblent des canaux/fils différents, ils sont vidés individuellement afin de préserver le routage.
- `collect` : regroupe les messages en file dans un **seul** tour de suivi après la fenêtre de silence. Si les messages ciblent différents canaux/fils, ils sont vidés individuellement afin de préserver le routage.
- `steer-backlog` (alias `steer+backlog`) : pilote maintenant **et** conserve le même message pour un tour de suivi.
- `interrupt` (hérité) : abandonne l’exécution active pour cette session, puis exécute le message le plus récent.
Steer-backlog signifie que vous pouvez obtenir une réponse de suivi après l’exécution pilotée, donc
Steer-backlog signifie que vous pouvez obtenir une réponse de suivi après l’exécution pilotée, de sorte que
les surfaces de diffusion peuvent ressembler à des doublons. Préférez `collect`/`steer` si vous voulez
une réponse par message entrant.
Pour le minutage propre au runtime et le comportement des dépendances, consultez
[File d’attente de pilotage](/fr/concepts/queue-steering).
[File de pilotage](/fr/concepts/queue-steering).
Configurez globalement ou par canal via `messages.queue` :
@ -78,21 +78,21 @@ Configurez globalement ou par canal via `messages.queue` :
## Options de file d’attente
Les options s’appliquent à `followup`, `collect` et `steer-backlog` (ainsi qu’à `steer` ou à l’ancien `queue` lorsque le pilotage revient à un suivi) :
Les options s’appliquent à `followup`, `collect` et `steer-backlog` (ainsi qu’à `steer` ou à l’ancien `queue` lorsque le pilotage se replie sur un suivi) :
- `debounceMs` : fenêtre de silence avant de vider les suivis en file. Les nombres nus sont des millisecondes ; les unités `ms`, `s`, `m`, `h` et `d` sont acceptées par les options `/queue`.
- `debounceMs` : fenêtre de silence avant de vider les suivis en file. Les nombres seuls sont en millisecondes ; les unités `ms`, `s`, `m`, `h` et `d` sont acceptées par les options `/queue`.
- `cap` : nombre maximal de messages en file par session. Les valeurs inférieures à `1` sont ignorées.
- `drop: "summarize"` : valeur par défaut. Supprime les entrées les plus anciennes en file selon les besoins, conserve des résumés compacts et les injecte comme invite de suivi synthétique.
- `drop: "old"` : supprime les entrées les plus anciennes en file selon les besoins, sans conserver de résumés.
- `drop: "summarize"` : valeur par défaut. Supprime les entrées en file les plus anciennes selon les besoins, conserve des résumés compacts et les injecte comme invite de suivi synthétique.
- `drop: "old"` : supprime les entrées en file les plus anciennes selon les besoins, sans conserver de résumés.
- `drop: "new"` : rejette le message le plus récent lorsque la file est déjà pleine.
Valeurs par défaut : `debounceMs: 500`, `cap: 20`, `drop: summarize`.
## Précédence
## Priorité
Pour la sélection du mode, OpenClaw résout :
1. Remplacement `/queue` par session, en ligne ou stocké.
1. Remplacement `/queue` en ligne ou stocké par session.
2. `messages.queue.byChannel.<channel>`.
3. `messages.queue.mode`.
4. Valeur par défaut `steer`.
@ -100,8 +100,8 @@ Pour la sélection du mode, OpenClaw résout :
Pour les options, les options `/queue` en ligne ou stockées l’emportent sur la configuration. Ensuite,
le debounce propre au canal (`messages.queue.debounceMsByChannel`), les valeurs par défaut de debounce du Plugin,
les options globales `messages.queue` et les valeurs par défaut intégrées sont
appliqués. `cap` et `drop` sont des options globales/de session, pas des clés
de configuration par canal.
appliqués. `cap` et `drop` sont des options globales/de session, pas des clés de configuration
par canal.
## Remplacements par session
@ -111,20 +111,21 @@ de configuration par canal.
## Portée et garanties
- S’applique aux exécutions d’agents de réponse automatique sur tous les canaux entrants qui utilisent le pipeline de réponse du Gateway (web WhatsApp, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
- La voie par défaut (`main`) s’applique à tout le processus pour les messages entrants et les Heartbeat principaux ; définissez `agents.defaults.maxConcurrent` pour autoriser plusieurs sessions en parallèle.
- Des voies supplémentaires peuvent exister (par exemple `cron`, `cron-nested`, `nested`, `subagent`) afin que les tâches en arrière-plan puissent s’exécuter en parallèle sans bloquer les réponses entrantes. Les tours d’agent Cron isolés occupent un emplacement `cron` pendant que leur exécution d’agent interne utilise `cron-nested` ; les deux utilisent `cron.maxConcurrentRuns`. Les flux `nested` non Cron partagés conservent leur propre comportement de voie. Ces exécutions détachées sont suivies comme des [tâches en arrière-plan](/fr/automation/tasks).
- S’applique aux exécutions d’agent de réponse automatique sur tous les canaux entrants qui utilisent le pipeline de réponse du Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.).
- La voie par défaut (`main`) est à l’échelle du processus pour les messages entrants et les Heartbeats principaux ; définissez `agents.defaults.maxConcurrent` pour autoriser plusieurs sessions en parallèle.
- Des voies supplémentaires peuvent exister (par exemple `cron`, `cron-nested`, `nested`, `subagent`) afin que les tâches d’arrière-plan puissent s’exécuter en parallèle sans bloquer les réponses entrantes. Les tours d’agent Cron isolés occupent un emplacement `cron` pendant que leur exécution d’agent interne utilise `cron-nested` ; les deux utilisent `cron.maxConcurrentRuns`. Les flux `nested` partagés non-Cron conservent leur propre comportement de voie. Ces exécutions détachées sont suivies comme [tâches d’arrière-plan](/fr/automation/tasks).
- Les voies par session garantissent qu’une seule exécution d’agent touche une session donnée à la fois.
- Aucune dépendance externe ni thread de worker en arrière-plan ; TypeScript pur + promesses.
- Aucune dépendance externe ni thread de worker d’arrière-plan ; TypeScript pur + promesses.
## Dépannage
- Si les commandes semblent bloquées, activez les journaux détaillés et recherchez les lignes « queued for …ms » pour confirmer que la file se vide.
- Si vous avez besoin de la profondeur de file, activez les journaux détaillés et surveillez les lignes de minutage de la file.
- Lorsque les diagnostics sont activés, les sessions qui restent en `processing` au-delà de `diagnostics.stuckSessionWarnMs` journalisent un avertissement de session bloquée. Les exécutions intégrées actives, les opérations de réponse actives et les tâches de voie actives restent uniquement des avertissements par défaut ; une comptabilité de démarrage périmée sans travail de session actif peut libérer la voie de session concernée afin que le travail en file se vide.
- Si vous avez besoin de la profondeur de file, activez les journaux détaillés et surveillez les lignes de minutage de file.
- Les exécutions du serveur d’application Codex qui acceptent un tour puis cessent d’émettre une progression sont interrompues par l’adaptateur Codex afin que la voie de session active puisse se libérer au lieu d’attendre le délai d’expiration de l’exécution externe.
- Lorsque les diagnostics sont activés, les sessions qui restent en `processing` au-delà de `diagnostics.stuckSessionWarnMs` journalisent un avertissement de session bloquée. Les exécutions intégrées actives, les opérations de réponse actives et les tâches de voie actives restent uniquement des avertissements par défaut ; une comptabilité de démarrage obsolète sans travail de session actif peut libérer la voie de session affectée afin que le travail en file se vide.
## Liens connexes
## Connexe
- [Gestion des sessions](/fr/concepts/session)
- [File d’attente de pilotage](/fr/concepts/queue-steering)
- [File de pilotage](/fr/concepts/queue-steering)
- [Politique de nouvelle tentative](/fr/concepts/retry)

823
docs/fr/help/testing.md
View File

File diff suppressed because it is too large Load Diff

107
docs/fr/reference/test.md
View File

@ -4,55 +4,56 @@ read_when:
summary: Comment exécuter les tests localement (vitest) et quand utiliser les modes force/couverture
title: Tests
x-i18n:
generated_at: "2026-04-30T07:47:38Z"
generated_at: "2026-04-30T18:38:34Z"
model: gpt-5.5
provider: openai
source_hash: 9328d6f0383b5067fa8bb5d0f1bf22a3b9048a267908bf85167842ddc3d12e42
source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2
source_path: reference/test.md
workflow: 16
---
- Kit de test complet (suites, en direct, Docker) : [Tests](/fr/help/testing)
- Kit de tests complet (suites, tests en direct, Docker) : [Tests](/fr/help/testing)
- `pnpm test:force` : tue tout processus Gateway persistant qui occupe le port de contrôle par défaut, puis exécute toute la suite Vitest avec un port Gateway isolé afin que les tests serveur n’entrent pas en conflit avec une instance en cours d’exécution. Utilisez cela lorsqu’une exécution Gateway précédente a laissé le port 18789 occupé.
- `pnpm test:coverage` : exécute la suite unitaire avec la couverture V8 (via `vitest.unit.config.ts`). Il s’agit d’un contrôle de couverture unitaire des fichiers chargés, pas d’une couverture de tous les fichiers de tout le dépôt. Les seuils sont 70 % pour les lignes/fonctions/instructions et 55 % pour les branches. Comme `coverage.all` vaut false, le contrôle mesure les fichiers chargés par la suite de couverture unitaire au lieu de traiter chaque fichier source de voie séparée comme non couvert.
- `pnpm test:force` : tue tout processus Gateway persistant qui occupe le port de contrôle par défaut, puis exécute la suite Vitest complète avec un port Gateway isolé afin que les tests serveur n’entrent pas en conflit avec une instance en cours d’exécution. Utilisez-le lorsqu’une exécution Gateway précédente a laissé le port 18789 occupé.
- `pnpm test:coverage` : exécute la suite unitaire avec la couverture V8 (via `vitest.unit.config.ts`). Il s’agit d’une porte de couverture unitaire des fichiers chargés, et non d’une couverture de tous les fichiers de tout le dépôt. Les seuils sont de 70 % pour les lignes/fonctions/instructions et de 55 % pour les branches. Comme `coverage.all` vaut false, la porte mesure les fichiers chargés par la suite de couverture unitaire au lieu de considérer chaque fichier source de voie fractionnée comme non couvert.
- `pnpm test:coverage:changed` : exécute la couverture unitaire uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:changed` : exécution de tests modifiés intelligente et peu coûteuse. Elle exécute des cibles précises à partir des modifications directes de tests, des fichiers frères `*.test.ts`, des correspondances source explicites et du graphe d’import local. Les modifications larges de configuration/paquet sont ignorées sauf si elles correspondent à des tests précis.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` : exécution large explicite des tests modifiés. Utilisez-la lorsqu’une modification de harnais de test/configuration/paquet doit revenir au comportement plus large de Vitest pour les tests modifiés.
- `pnpm test:changed` : exécution de tests modifiés intelligente et peu coûteuse. Elle exécute des cibles précises à partir des modifications directes de tests, des fichiers frères `*.test.ts`, des correspondances de sources explicites et du graphe d’import local. Les changements larges de configuration ou de package sont ignorés sauf s’ils correspondent à des tests précis.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` : exécution large explicite des tests modifiés. Utilisez-la lorsqu’une modification du harnais de test, de la configuration ou d’un package doit revenir au comportement plus large de Vitest pour les tests modifiés.
- `pnpm changed:lanes` : affiche les voies architecturales déclenchées par le diff par rapport à `origin/main`.
- `pnpm check:changed` : exécute le contrôle intelligent des changements pour le diff par rapport à `origin/main`. Il exécute les commandes de typage, de lint et de garde pour les voies architecturales affectées, mais n’exécute pas les tests Vitest. Utilisez `pnpm test:changed` ou `pnpm test <target>` explicite pour la preuve par les tests.
- `pnpm test` : route les cibles de fichier/répertoire explicites vers des voies Vitest limitées. Les exécutions sans cible utilisent des groupes de partitions fixes et s’étendent aux configurations feuilles pour l’exécution parallèle locale ; le groupe d’extensions s’étend toujours aux configurations de partitions par extension au lieu d’un unique processus de projet racine géant.
- Les exécutions de l’enveloppe de test se terminent par un court résumé `[test] passed|failed|skipped ... in ...`. La ligne de durée propre à Vitest reste le détail par partition.
- `pnpm check:changed` : exécute la porte de vérification intelligente des changements pour le diff par rapport à `origin/main`. Elle exécute les commandes de vérification de types, de lint et de garde pour les voies architecturales affectées, mais n’exécute pas les tests Vitest. Utilisez `pnpm test:changed` ou un `pnpm test <target>` explicite comme preuve de test.
- `pnpm test` : achemine les cibles explicites de fichiers/répertoires via les voies Vitest limitées au périmètre. Les exécutions sans cible utilisent des groupes de fragments fixes et se développent en configurations feuilles pour l’exécution parallèle locale ; le groupe d’extensions se développe toujours en configurations de fragments par extension au lieu d’un seul énorme processus de projet racine.
- Les exécutions du wrapper de test se terminent par un court résumé `[test] passed|failed|skipped ... in ...`. La ligne de durée propre à Vitest reste le détail par fragment.
- État de test OpenClaw partagé : utilisez `src/test-utils/openclaw-test-state.ts` depuis Vitest lorsqu’un test a besoin d’un `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, d’un fixture de configuration, d’un espace de travail, d’un répertoire d’agent ou d’un magasin de profils d’authentification isolé.
- Assistants E2E de processus : utilisez `test/helpers/openclaw-test-instance.ts` lorsqu’un test E2E au niveau processus Vitest a besoin d’un Gateway en cours d’exécution, d’un environnement CLI, d’une capture de journaux et du nettoyage au même endroit.
- Assistants E2E Docker/Bash : les voies qui sourcent `scripts/lib/docker-e2e-image.sh` peuvent passer `docker_e2e_test_state_shell_b64 <label> <scenario>` dans le conteneur et le décoder avec `scripts/lib/openclaw-e2e-instance.sh` ; les scripts multi-maisons peuvent passer `docker_e2e_test_state_function_b64` et appeler `openclaw_test_state_create <label> <scenario>` dans chaque flux. Les appelants de plus bas niveau peuvent utiliser `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` pour un extrait shell dans le conteneur, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` pour un fichier d’environnement hôte sourçable. Le `--` avant `create` empêche les runtimes Node plus récents de traiter `--env-file` comme un indicateur Node. Les voies Docker/Bash qui lancent un Gateway peuvent sourcer `scripts/lib/openclaw-e2e-instance.sh` dans le conteneur pour la résolution du point d’entrée, le démarrage OpenAI factice, le lancement du Gateway au premier plan/en arrière-plan, les sondes de disponibilité, l’export de l’environnement d’état, les vidages de journaux et le nettoyage des processus.
- Les exécutions de partitions complètes, d’extensions et à motif d’inclusion mettent à jour les données de minutage locales dans `.artifacts/vitest-shard-timings.json` ; les exécutions ultérieures de configuration complète utilisent ces minutages pour équilibrer les partitions lentes et rapides. Les partitions CI à motif d’inclusion ajoutent le nom de la partition à la clé de minutage, ce qui garde les minutages filtrés visibles sans remplacer les données de minutage de configuration complète. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artefact de minutage local.
- Certains fichiers de test `plugin-sdk` et `commands` sont désormais routés par des voies légères dédiées qui ne conservent que `test/setup.ts`, en laissant les cas lourds à l’exécution sur leurs voies existantes.
- Les fichiers source avec des tests frères correspondent d’abord à ce frère avant de revenir à des globs de répertoire plus larges. Les modifications d’assistants sous `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` et `src/plugins/contracts` utilisent un graphe d’import local pour exécuter les tests importateurs au lieu d’exécuter largement chaque partition lorsque le chemin de dépendance est précis.
- `auto-reply` se sépare désormais aussi en trois configurations dédiées (`core`, `top-level`, `reply`) afin que le harnais de réponse ne domine pas les tests plus légers de statut/jeton/assistant de premier niveau.
- La configuration Vitest de base utilise désormais par défaut `pool: "threads"` et `isolate: false`, avec l’exécuteur non isolé partagé activé dans les configurations du dépôt.
- Helpers E2E de processus : utilisez `test/helpers/openclaw-test-instance.ts` lorsqu’un test E2E Vitest au niveau processus a besoin d’un Gateway en cours d’exécution, d’un environnement CLI, d’une capture de journaux et d’un nettoyage au même endroit.
- Helpers E2E Docker/Bash : les voies qui sourcent `scripts/lib/docker-e2e-image.sh` peuvent transmettre `docker_e2e_test_state_shell_b64 <label> <scenario>` dans le conteneur et le décoder avec `scripts/lib/openclaw-e2e-instance.sh` ; les scripts multi-home peuvent transmettre `docker_e2e_test_state_function_b64` et appeler `openclaw_test_state_create <label> <scenario>` dans chaque flux. Les appelants de plus bas niveau peuvent utiliser `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` pour un extrait shell dans le conteneur, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` pour un fichier d’environnement hôte sourçable. Le `--` avant `create` empêche les runtimes Node récents de traiter `--env-file` comme un indicateur Node. Les voies Docker/Bash qui lancent un Gateway peuvent sourcer `scripts/lib/openclaw-e2e-instance.sh` dans le conteneur pour la résolution de l’entrypoint, le démarrage OpenAI simulé, le lancement Gateway au premier plan/en arrière-plan, les sondes de disponibilité, l’export de l’environnement d’état, les dumps de journaux et le nettoyage des processus.
- Les exécutions fragmentées complètes, par extension et avec motif d’inclusion mettent à jour les données de timings locales dans `.artifacts/vitest-shard-timings.json` ; les exécutions ultérieures de configuration complète utilisent ces timings pour équilibrer les fragments lents et rapides. Les fragments CI avec motif d’inclusion ajoutent le nom du fragment à la clé de timing, ce qui garde les timings filtrés visibles sans remplacer les données de timing de configuration complète. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artifact de timing local.
- Certains fichiers de test `plugin-sdk` et `commands` passent maintenant par des voies légères dédiées qui ne conservent que `test/setup.ts`, en laissant les cas lourds côté runtime sur leurs voies existantes.
- Les fichiers source avec des tests frères correspondent à ce frère avant de revenir à des globs de répertoires plus larges. Les modifications de helpers sous `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` et `src/plugins/contracts` utilisent un graphe d’import local pour exécuter les tests importeurs au lieu d’exécuter largement chaque fragment lorsque le chemin de dépendance est précis.
- `auto-reply` se divise maintenant aussi en trois configurations dédiées (`core`, `top-level`, `reply`) afin que le harnais de réponse ne domine pas les tests plus légers de statut, de jetons et de helpers au niveau supérieur.
- La configuration Vitest de base utilise maintenant par défaut `pool: "threads"` et `isolate: false`, avec le runner non isolé partagé activé dans les configurations du dépôt.
- `pnpm test:channels` exécute `vitest.channels.config.ts`.
- `pnpm test:extensions` et `pnpm test extensions` exécutent toutes les partitions d’extension/plugin. Les plugins de canaux lourds, le plugin navigateur et OpenAI s’exécutent comme partitions dédiées ; les autres groupes de plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une voie de plugin groupé.
- `pnpm test:perf:imports` : active les rapports de durée d’import et de décomposition des imports Vitest, tout en utilisant le routage par voie limitée pour les cibles explicites de fichier/répertoire.
- `pnpm test:extensions` et `pnpm test extensions` exécutent tous les fragments d’extensions/Plugin. Les Plugins de canaux lourds, le Plugin de navigateur et OpenAI s’exécutent comme fragments dédiés ; les autres groupes de Plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une voie de Plugin groupé.
- `pnpm test:perf:imports` : active les rapports de durée d’import et de répartition des imports de Vitest, tout en utilisant toujours le routage par voie limitée au périmètre pour les cibles explicites de fichiers/répertoires.
- `pnpm test:perf:imports:changed` : même profilage des imports, mais uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` mesure le chemin routé en mode changements par rapport à l’exécution native du projet racine pour le même diff git validé.
- `pnpm test:perf:changed:bench -- --worktree` mesure l’ensemble de changements de l’arbre de travail actuel sans validation préalable.
- `pnpm test:perf:profile:main` : écrit un profil CPU pour le thread principal Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner` : écrit des profils CPU et tas pour l’exécuteur unitaire (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute chaque configuration feuille Vitest de suite complète en série et écrit des données de durée groupées ainsi que des artefacts JSON/journaux par configuration. Le Test Performance Agent l’utilise comme référence avant de tenter de corriger les tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après un changement axé sur les performances.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` compare par benchmark le chemin routé en mode changements avec l’exécution native du projet racine pour le même diff git commité.
- `pnpm test:perf:changed:bench -- --worktree` benchmarke l’ensemble de changements du worktree courant sans commit préalable.
- `pnpm test:perf:profile:main` : écrit un profil CPU pour le thread principal de Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner` : écrit des profils CPU + heap pour le runner unitaire (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute chaque configuration feuille Vitest de suite complète en série et écrit des données de durée groupées ainsi que des artifacts JSON/journaux par configuration. Le Test Performance Agent l’utilise comme référence avant de tenter des corrections de tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après une modification axée sur les performances.
- Intégration Gateway : activation explicite via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e` : exécute les tests de fumée de bout en bout du Gateway (appariement multi-instance WS/HTTP/node). Utilise par défaut `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des journaux détaillés.
- `pnpm test:live` : exécute les tests live de fournisseurs (minimax/zai). Nécessite des clés API et `LIVE=1` (ou `*_LIVE_TEST=1` spécifique au fournisseur) pour lever l’exclusion.
- `pnpm test:docker:all` : construit l’image de test live partagée, empaquette OpenClaw une fois comme archive npm, construit/réutilise une image d’exécution Node/Git minimale plus une image fonctionnelle qui installe cette archive dans `/app`, puis exécute les voies de fumée Docker avec `OPENCLAW_SKIP_DOCKER_BUILD=1` via un ordonnanceur pondéré. L’image minimale (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) est utilisée pour les voies d’installation/mise à jour/dépendances de plugin ; ces voies montent l’archive préconstruite au lieu d’utiliser des sources du dépôt copiées. L’image fonctionnelle (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) est utilisée pour les voies de fonctionnalité normale de l’application construite. `scripts/package-openclaw-for-docker.mjs` est l’empaqueteur unique local/CI et valide l’archive ainsi que `dist/postinstall-inventory.json` avant que Docker ne la consomme. Les définitions de voies Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs` ; la logique de planification se trouve dans `scripts/lib/docker-e2e-plan.mjs` ; `scripts/test-docker-all.mjs` exécute le plan sélectionné. `node scripts/test-docker-all.mjs --plan-json` émet le plan CI détenu par l’ordonnanceur pour les voies sélectionnées, les types d’images, les besoins de paquet/image live, les scénarios d’état et les contrôles d’identifiants, sans construire ni exécuter Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` contrôle les emplacements de processus et vaut 10 par défaut ; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` contrôle le groupe de fin sensible aux fournisseurs et vaut 10 par défaut. Les plafonds de voies lourdes valent par défaut `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; les plafonds de fournisseurs valent par défaut une voie lourde par fournisseur via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` et `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Utilisez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` pour des hôtes plus grands. Si une voie dépasse le poids effectif ou le plafond de ressources sur un hôte à faible parallélisme, elle peut tout de même démarrer depuis un groupe vide et s’exécuter seule jusqu’à libérer de la capacité. Les démarrages de voies sont espacés de 2 secondes par défaut pour éviter les tempêtes de création du démon Docker local ; surchargez avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. L’exécuteur précontrôle Docker par défaut, nettoie les conteneurs E2E OpenClaw périmés, émet l’état des voies actives toutes les 30 secondes, partage les caches d’outils CLI de fournisseurs entre voies compatibles, retente une fois par défaut les échecs transitoires de fournisseurs live (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) et stocke les minutages de voies dans `.artifacts/docker-tests/lane-timings.json` pour un ordre du plus long au plus court lors des exécutions suivantes. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour imprimer le manifeste des voies sans exécuter Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` pour ajuster la sortie d’état, ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` pour désactiver la réutilisation des minutages. Utilisez `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` uniquement pour les voies déterministes/locales ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` uniquement pour les voies de fournisseurs live ; les alias de paquet sont `pnpm test:docker:local:all` et `pnpm test:docker:live:all`. Le mode live seul fusionne les voies live principales et de fin dans un groupe unique du plus long au plus court afin que les compartiments de fournisseurs puissent regrouper le travail Claude, Codex et Gemini. L’exécuteur cesse de planifier de nouvelles voies groupées après le premier échec sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque voie a un délai d’expiration de repli de 120 minutes surchargeable avec `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` ; certaines voies live/de fin utilisent des plafonds par voie plus stricts. Les commandes de configuration Docker du backend CLI ont leur propre délai d’expiration via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (180 par défaut). Les journaux par voie, `summary.json`, `failures.json` et les minutages de phases sont écrits sous `.artifacts/docker-tests/<run-id>/` ; utilisez `pnpm test:docker:timings <summary.json>` pour inspecter les voies lentes et `pnpm test:docker:rerun <run-id|summary.json|failures.json>` pour imprimer des commandes de réexécution ciblées peu coûteuses.
- `pnpm test:docker:browser-cdp-snapshot` : construit un conteneur E2E source adossé à Chromium, démarre le CDP brut plus un Gateway isolé, exécute `browser doctor --deep` et vérifie que les instantanés de rôles CDP incluent les URL de liens, les éléments cliquables promus par le curseur, les références d’iframe et les métadonnées de cadre.
- Les sondes Docker live du backend CLI peuvent être exécutées comme voies ciblées, par exemple `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude et Gemini ont des alias `:resume` et `:mcp` correspondants.
- `pnpm test:docker:openwebui` : démarre OpenClaw + Open WebUI dans Docker, se connecte via Open WebUI, vérifie `/api/models`, puis exécute une vraie discussion proxifiée via `/api/chat/completions`. Nécessite une clé de modèle live utilisable (par exemple OpenAI dans `~/.profile`), récupère une image Open WebUI externe et n’est pas censé être stable en CI comme les suites unitaires/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway prérempli et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte de conversations routées, les lectures de transcriptions, les métadonnées de pièces jointes, le comportement de la file d’événements live, le routage des envois sortants, ainsi que les notifications de canal et d’autorisation de style Claude sur le vrai pont stdio. L’assertion de notification Claude lit directement les trames MCP stdio brutes afin que le test de fumée reflète ce que le pont émet réellement.
- `pnpm test:e2e` : exécute les tests smoke Gateway de bout en bout (appariement multi-instance WS/HTTP/node). Utilise par défaut `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des journaux détaillés.
- `pnpm test:live` : exécute les tests live des fournisseurs (minimax/zai). Nécessite des clés API et `LIVE=1` (ou `*_LIVE_TEST=1` propre au fournisseur) pour ne plus être ignoré.
- `pnpm test:docker:all` : construit l’image de test live partagée, empaquette OpenClaw une seule fois comme tarball npm, construit/réutilise une image runner Node/Git nue ainsi qu’une image fonctionnelle qui installe ce tarball dans `/app`, puis exécute les voies smoke Docker avec `OPENCLAW_SKIP_DOCKER_BUILD=1` via un ordonnanceur pondéré. L’image nue (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) est utilisée pour les voies d’installation, de mise à jour et de dépendances de Plugin ; ces voies montent le tarball préconstruit au lieu d’utiliser les sources copiées du dépôt. L’image fonctionnelle (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) est utilisée pour les voies de fonctionnalité normale de l’application construite. `scripts/package-openclaw-for-docker.mjs` est l’unique empaqueteur de package local/CI et valide le tarball ainsi que `dist/postinstall-inventory.json` avant consommation par Docker. Les définitions de voies Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs` ; la logique du planificateur se trouve dans `scripts/lib/docker-e2e-plan.mjs` ; `scripts/test-docker-all.mjs` exécute le plan sélectionné. `node scripts/test-docker-all.mjs --plan-json` émet le plan CI détenu par l’ordonnanceur pour les voies sélectionnées, les types d’images, les besoins de package/image live, les scénarios d’état et les vérifications d’identifiants sans construire ni exécuter Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` contrôle les emplacements de processus et vaut 10 par défaut ; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` contrôle le pool de fin sensible aux fournisseurs et vaut 10 par défaut. Les plafonds de voies lourdes valent par défaut `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; les plafonds de fournisseurs valent par défaut une voie lourde par fournisseur via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` et `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Utilisez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` pour les hôtes plus grands. Si une voie dépasse le poids effectif ou le plafond de ressources sur un hôte à faible parallélisme, elle peut tout de même démarrer depuis un pool vide et s’exécuter seule jusqu’à libérer de la capacité. Les démarrages de voies sont espacés de 2 secondes par défaut pour éviter les tempêtes de création du daemon Docker local ; remplacez ce délai avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Le runner prévérifie Docker par défaut, nettoie les conteneurs E2E OpenClaw obsolètes, émet l’état des voies actives toutes les 30 secondes, partage les caches d’outils CLI fournisseur entre voies compatibles, réessaie une fois par défaut les échecs transitoires de fournisseurs live (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) et stocke les timings des voies dans `.artifacts/docker-tests/lane-timings.json` pour un ordre du plus long au plus court lors des exécutions ultérieures. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour imprimer le manifeste des voies sans exécuter Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` pour ajuster la sortie d’état, ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` pour désactiver la réutilisation des timings. Utilisez `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` uniquement pour les voies déterministes/locales ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` uniquement pour les voies de fournisseurs live ; les alias de package sont `pnpm test:docker:local:all` et `pnpm test:docker:live:all`. Le mode live uniquement fusionne les voies live principales et de fin dans un seul pool du plus long au plus court afin que les compartiments de fournisseurs puissent regrouper le travail Claude, Codex et Gemini. Le runner cesse de planifier de nouvelles voies en pool après le premier échec sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque voie dispose d’un délai d’expiration de repli de 120 minutes remplaçable avec `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` ; certaines voies live/de fin sélectionnées utilisent des plafonds par voie plus stricts. Les commandes de configuration Docker du backend CLI ont leur propre délai d’expiration via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (180 par défaut). Les journaux par voie, `summary.json`, `failures.json` et les timings de phase sont écrits sous `.artifacts/docker-tests/<run-id>/` ; utilisez `pnpm test:docker:timings <summary.json>` pour inspecter les voies lentes et `pnpm test:docker:rerun <run-id|summary.json|failures.json>` pour imprimer des commandes de réexécution ciblées et peu coûteuses.
- `pnpm test:docker:browser-cdp-snapshot` : construit un conteneur E2E source adossé à Chromium, démarre CDP brut ainsi qu’un Gateway isolé, exécute `browser doctor --deep`, puis vérifie que les instantanés de rôle CDP incluent les URL de liens, les éléments cliquables promus par le curseur, les références d’iframe et les métadonnées de frame.
- Les sondes Docker live du backend CLI peuvent être exécutées comme voies ciblées, par exemple `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude et Gemini disposent d’alias `:resume` et `:mcp` correspondants.
- `pnpm test:docker:openwebui` : démarre OpenClaw + Open WebUI dockerisés, se connecte via Open WebUI, vérifie `/api/models`, puis exécute une vraie conversation proxifiée via `/api/chat/completions`. Nécessite une clé de modèle live utilisable (par exemple OpenAI dans `~/.profile`), tire une image Open WebUI externe et n’est pas censé être stable en CI comme les suites unitaires/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway préinitialisé et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte de conversations routées, la lecture de transcriptions, les métadonnées de pièces jointes, le comportement de la file d’événements live, le routage d’envois sortants, ainsi que les notifications de canal et d’autorisation de style Claude via le vrai pont stdio. L’assertion de notification Claude lit directement les trames MCP stdio brutes afin que le smoke reflète ce que le pont émet réellement.
- `pnpm test:docker:upgrade-survivor` : installe l’archive tarball OpenClaw empaquetée par-dessus une fixture sale d’ancien utilisateur, exécute la mise à jour du paquet ainsi que le doctor non interactif sans clés de provider ou de canal actives, puis démarre un Gateway en loopback et vérifie que les agents, la configuration des canaux, les listes d’autorisation des plugins, les fichiers d’espace de travail/session, l’état obsolète des dépendances d’exécution des plugins, le démarrage et l’état RPC survivent.
## Contrôle PR local
## Gate PR local
Pour les vérifications locales d’intégration et de validation de PR, exécutez :
Pour les vérifications locales de fusion/gate de PR, exécutez :
- `pnpm check:changed`
- `pnpm check`
@ -61,27 +62,27 @@ Pour les vérifications locales d’intégration et de validation de PR, exécut
- `pnpm test`
- `pnpm check:docs`
Si `pnpm test` échoue de façon intermittente sur un hôte chargé, relancez-le une fois avant de le considérer comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les hôtes à mémoire contrainte, utilisez :
Si `pnpm test` échoue de manière intermittente sur un hôte fortement chargé, relancez-le une fois avant de considérer cela comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les hôtes contraints en mémoire, utilisez :
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Banc de latence des modèles (clés locales)
## Banc de mesure de latence des modèles (clés locales)
Script : [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
Utilisation :
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Env optionnelles : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt par défaut : « Réponds avec un seul mot : ok. Sans ponctuation ni texte supplémentaire. »
- Variables d’environnement optionnelles : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Invite par défaut : « Reply with a single word: ok. No punctuation or extra text. »
Dernière exécution (2025-12-31, 20 exécutions) :
- médiane minimax 1279 ms (min 1114, max 2431)
- médiane opus 2454 ms (min 1224, max 3170)
- minimax médiane 1279 ms (min 1114, max 2431)
- opus médiane 2454 ms (min 1224, max 3170)
## Banc de démarrage CLI
## Banc de mesure du démarrage de la CLI
Script : [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -109,23 +110,23 @@ Préréglages :
- `real` : `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all` : les deux préréglages
La sortie inclut `sampleCount`, la moyenne, p50, p95, min/max, la distribution des codes de sortie/signaux et les résumés du RSS maximal pour chaque commande. Les options `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 pour chaque exécution afin que la mesure du temps et la capture des profils utilisent le même harnais.
La sortie inclut `sampleCount`, la moyenne, p50, p95, min/max, la distribution code de sortie/signal, ainsi que des résumés du RSS maximal pour chaque commande. Les options facultatives `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 pour chaque exécution afin que le minutage et la capture de profils utilisent le même banc.
Conventions des sorties enregistrées :
Conventions de sortie enregistrée :
- `pnpm test:startup:bench:smoke` écrit l’artefact de smoke ciblé dans `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` écrit l’artefact de suite complète dans `.artifacts/cli-startup-bench-all.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:update` actualise la fixture de référence versionnée dans `test/fixtures/cli-startup-bench.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:smoke` écrit l’artefact ciblé de test de fumée dans `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` écrit l’artefact de la suite complète dans `.artifacts/cli-startup-bench-all.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:update` actualise le jeu de données de référence versionné dans `test/fixtures/cli-startup-bench.json` avec `runs=5` et `warmup=1`
Fixture versionnée :
Jeu de données de test versionné :
- `test/fixtures/cli-startup-bench.json`
- Actualisez avec `pnpm test:startup:bench:update`
- Comparez les résultats actuels à la fixture avec `pnpm test:startup:bench:check`
- Comparez les résultats actuels au jeu de données avec `pnpm test:startup:bench:check`
## E2E d’onboarding (Docker)
## E2E d’intégration initiale (Docker)
Docker est facultatif ; ceci n’est nécessaire que pour les smoke tests d’onboarding conteneurisés.
Docker est facultatif ; cela n’est nécessaire que pour les tests de fumée d’intégration initiale conteneurisés.
Flux complet de démarrage à froid dans un conteneur Linux propre :
@ -135,15 +136,15 @@ scripts/e2e/onboard-docker.sh
Ce script pilote l’assistant interactif via un pseudo-tty, vérifie les fichiers de configuration/espace de travail/session, puis démarre le Gateway et exécute `openclaw health`.
## Smoke d’import QR (Docker)
## Test de fumée d’import QR (Docker)
Vérifie que l’aide d’exécution QR maintenue se charge avec les runtimes Docker Node pris en charge (Node 24 par défaut, Node 22 compatible) :
Vérifie que l’assistant d’exécution QR maintenu se charge sous les environnements d’exécution Docker Node pris en charge (Node 24 par défaut, Node 22 compatible) :
```bash
pnpm test:docker:qr
```
## Connexe
## Associés
- [Tests](/fr/help/testing)
- [Tests en direct](/fr/help/testing-live)