diff --git a/docs/fr/automation/tasks.md b/docs/fr/automation/tasks.md index 76d5fc418..c27aaf725 100644 --- a/docs/fr/automation/tasks.md +++ b/docs/fr/automation/tasks.md @@ -1,42 +1,42 @@ --- read_when: - - Inspection des tâches en arrière-plan en cours ou récemment terminées - - Débogage des échecs de livraison pour les exécutions d’agent détachées + - Inspection des travaux en arrière-plan en cours ou récemment terminés + - Débogage des échecs de remise pour les exécutions d’agent détachées - Comprendre comment les exécutions en arrière-plan s’articulent avec les sessions, Cron et Heartbeat sidebarTitle: Background tasks summary: Suivi des tâches en arrière-plan pour les exécutions ACP, les sous-agents, les tâches Cron isolées et les opérations CLI title: Tâches en arrière-plan x-i18n: - generated_at: "2026-05-05T01:44:37Z" + generated_at: "2026-05-05T06:16:18Z" model: gpt-5.5 provider: openai - source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 + source_hash: bafd959feaf2e220820ec56bf1ef144207d05757418e9971ebf427844cf30c46 source_path: automation/tasks.md workflow: 16 --- -Vous cherchez la planification ? Consultez [Automatisation et tâches](/fr/automation) pour choisir le bon mécanisme. Cette page est le registre d'activité du travail en arrière-plan, pas le planificateur. +Vous cherchez la planification ? Consultez [Automatisation et tâches](/fr/automation) pour choisir le bon mécanisme. Cette page est le journal d’activité du travail en arrière-plan, pas le planificateur. -Les tâches en arrière-plan suivent le travail qui s'exécute **en dehors de votre session de conversation principale** : exécutions ACP, lancements de sous-agents, exécutions de tâches Cron isolées et opérations lancées par la CLI. +Les tâches en arrière-plan suivent le travail qui s’exécute **en dehors de votre session de conversation principale** : exécutions ACP, lancements de sous-agents, exécutions isolées de tâches Cron et opérations lancées par la CLI. -Les tâches ne remplacent **pas** les sessions, les tâches Cron ni les Heartbeats — elles sont le **registre d'activité** qui consigne quel travail détaché a eu lieu, quand, et s'il a réussi. +Les tâches ne remplacent **pas** les sessions, les tâches Cron ni les Heartbeats : elles sont le **journal d’activité** qui consigne quel travail détaché a eu lieu, quand, et s’il a réussi. -Toutes les exécutions d'agent ne créent pas de tâche. Les tours Heartbeat et la discussion interactive normale n'en créent pas. Toutes les exécutions Cron, les lancements ACP, les lancements de sous-agents et les commandes d'agent CLI en créent. +Toutes les exécutions d’agent ne créent pas une tâche. Les tours Heartbeat et la conversation interactive normale n’en créent pas. Toutes les exécutions Cron, les lancements ACP, les lancements de sous-agents et les commandes d’agent CLI en créent. -## En bref +## TL;DR -- Les tâches sont des **enregistrements**, pas des planificateurs — Cron et Heartbeat décident _quand_ le travail s'exécute, les tâches suivent _ce qui s'est passé_. -- ACP, les sous-agents, toutes les tâches Cron et les opérations CLI créent des tâches. Les tours Heartbeat n'en créent pas. -- Chaque tâche passe par `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost). -- Les tâches Cron restent actives tant que l'environnement d'exécution Cron possède toujours la tâche ; si l'état d'exécution en mémoire a disparu, la maintenance des tâches vérifie d'abord l'historique durable des exécutions Cron avant de marquer une tâche comme perdue. -- La finalisation est pilotée par notification : le travail détaché peut notifier directement ou réveiller la session/le Heartbeat du demandeur lorsqu'il se termine ; les boucles d'interrogation de l'état sont donc généralement la mauvaise approche. -- Les exécutions Cron isolées et les finalisations de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant la comptabilité finale du nettoyage. -- La livraison Cron isolée supprime les réponses parent intermédiaires obsolètes pendant que le travail de sous-agents descendants est encore en train de se terminer, et elle privilégie la sortie finale des descendants lorsqu'elle arrive avant la livraison. -- Les notifications de finalisation sont livrées directement à un canal ou mises en file d'attente pour le prochain Heartbeat. +- Les tâches sont des **enregistrements**, pas des planificateurs : Cron et Heartbeat décident _quand_ le travail s’exécute, les tâches suivent _ce qui s’est passé_. +- ACP, les sous-agents, toutes les tâches Cron et les opérations CLI créent des tâches. Les tours Heartbeat n’en créent pas. +- Chaque tâche passe par `queued → running → terminal` (réussie, échouée, expirée, annulée ou perdue). +- Les tâches Cron restent actives tant que le runtime Cron possède encore la tâche ; si l’état du runtime en mémoire a disparu, la maintenance des tâches vérifie d’abord l’historique durable des exécutions Cron avant de marquer une tâche comme perdue. +- L’achèvement est piloté par notification : le travail détaché peut notifier directement ou réveiller la session/le Heartbeat demandeur lorsqu’il se termine, donc les boucles de sondage d’état sont généralement la mauvaise approche. +- Les exécutions Cron isolées et les achèvements de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant la comptabilité finale de nettoyage. +- La livraison Cron isolée supprime les réponses parentes intermédiaires obsolètes pendant que le travail des sous-agents descendants est encore en cours d’écoulement, et elle préfère la sortie finale descendante lorsqu’elle arrive avant la livraison. +- Les notifications d’achèvement sont livrées directement à un canal ou mises en file d’attente pour le prochain Heartbeat. - `openclaw tasks list` affiche toutes les tâches ; `openclaw tasks audit` fait remonter les problèmes. - Les enregistrements terminaux sont conservés pendant 7 jours, puis automatiquement purgés. @@ -93,33 +93,33 @@ Toutes les exécutions d'agent ne créent pas de tâche. Les tours Heartbeat et ## Ce qui crée une tâche -| Source | Type d'exécution | Moment où un enregistrement de tâche est créé | Politique de notification par défaut | -| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| Exécutions ACP en arrière-plan | `acp` | Lancement d'une session enfant ACP | `done_only` | -| Orchestration des sous-agents | `subagent` | Lancement d'un sous-agent via `sessions_spawn` | `done_only` | -| Tâches Cron (tous types) | `cron` | Chaque exécution Cron (session principale et isolée) | `silent` | -| Opérations CLI | `cli` | Commandes `openclaw agent` qui passent par le Gateway | `silent` | -| Tâches média d'agent | `cli` | Exécutions `music_generate`/`video_generate` adossées à une session | `silent` | +| Source | Type de runtime | Quand un enregistrement de tâche est créé | Politique de notification par défaut | +| ---------------------- | --------------- | --------------------------------------------------------- | ------------------------------------ | +| Exécutions ACP en arrière-plan | `acp` | Lancement d’une session ACP enfant | `done_only` | +| Orchestration de sous-agent | `subagent` | Lancement d’un sous-agent via `sessions_spawn` | `done_only` | +| Tâches Cron (tous types) | `cron` | Chaque exécution Cron (session principale et isolée) | `silent` | +| Opérations CLI | `cli` | Commandes `openclaw agent` qui passent par le Gateway | `silent` | +| Tâches média d’agent | `cli` | Exécutions `music_generate`/`video_generate` adossées à une session | `silent` | - - Les tâches Cron de session principale utilisent par défaut la politique de notification `silent` — elles créent des enregistrements pour le suivi, mais ne génèrent pas de notifications. Les tâches Cron isolées utilisent aussi `silent` par défaut, mais elles sont plus visibles parce qu'elles s'exécutent dans leur propre session. + + Les tâches Cron de session principale utilisent la politique de notification `silent` par défaut : elles créent des enregistrements pour le suivi mais ne génèrent pas de notifications. Les tâches Cron isolées utilisent aussi `silent` par défaut, mais sont plus visibles parce qu’elles s’exécutent dans leur propre session. - Les exécutions `music_generate` et `video_generate` adossées à une session utilisent aussi la politique de notification `silent`. Elles créent quand même des enregistrements de tâche, mais la finalisation est renvoyée à la session d'agent d'origine sous forme de réveil interne, afin que l'agent puisse écrire le message de suivi et joindre lui-même le média terminé. Les finalisations de groupe/canal suivent la politique normale de réponse visible ; l'agent utilise donc l'outil de message lorsque la remise d'origine l'exige. + Les exécutions `music_generate` et `video_generate` adossées à une session utilisent aussi la politique de notification `silent`. Elles créent tout de même des enregistrements de tâche, mais l’achèvement est renvoyé à la session d’agent d’origine sous forme de réveil interne afin que l’agent puisse écrire le message de suivi et joindre lui-même le média terminé. Les achèvements de groupe/canal suivent la politique normale de réponse visible, donc l’agent utilise l’outil de messagerie lorsque la livraison source l’exige. Si l’agent d’achèvement ne produit pas de preuve de livraison par outil de messagerie dans une route uniquement par outil, OpenClaw envoie la solution de repli d’achèvement directement au canal d’origine au lieu de laisser le média privé. - - Tant qu'une tâche `video_generate` adossée à une session est encore active, l'outil agit aussi comme garde-fou : les appels `video_generate` répétés dans cette même session renvoient l'état de la tâche active au lieu de démarrer une deuxième génération concurrente. Utilisez `action: "status"` lorsque vous voulez une recherche explicite de progression/d'état depuis le côté agent. + + Tant qu’une tâche `video_generate` adossée à une session est encore active, l’outil agit aussi comme garde-fou : les appels `video_generate` répétés dans cette même session renvoient l’état de la tâche active au lieu de démarrer une deuxième génération concurrente. Utilisez `action: "status"` lorsque vous voulez une consultation explicite de progression/d’état côté agent. - Tours Heartbeat — session principale ; voir [Heartbeat](/fr/gateway/heartbeat) - - Tours de discussion interactive normaux - - Réponses directes à `/command` + - Tours de conversation interactive normale + - Réponses directes `/command` -## Cycle de vie des tâches +## Cycle de vie d’une tâche ```mermaid stateDiagram-v2 @@ -135,50 +135,50 @@ stateDiagram-v2 | État | Signification | | ----------- | -------------------------------------------------------------------------- | -| `queued` | Créée, en attente du démarrage de l'agent | -| `running` | Le tour d'agent est en cours d'exécution active | +| `queued` | Créée, en attente du démarrage de l’agent | +| `running` | Le tour d’agent est en cours d’exécution active | | `succeeded` | Terminée avec succès | | `failed` | Terminée avec une erreur | -| `timed_out` | A dépassé le délai d'expiration configuré | -| `cancelled` | Arrêtée par l'opérateur via `openclaw tasks cancel` | -| `lost` | L'environnement d'exécution a perdu l'état de support faisant autorité après une période de grâce de 5 minutes | +| `timed_out` | A dépassé le délai d’expiration configuré | +| `cancelled` | Arrêtée par l’opérateur via `openclaw tasks cancel` | +| `lost` | Le runtime a perdu l’état de référence faisant autorité après un délai de grâce de 5 minutes | -Les transitions se produisent automatiquement — lorsque l'exécution d'agent associée se termine, l'état de la tâche est mis à jour en conséquence. +Les transitions se produisent automatiquement : lorsque l’exécution d’agent associée se termine, l’état de la tâche est mis à jour en conséquence. -La fin de l'exécution d'agent fait autorité pour les enregistrements de tâches actifs. Une exécution détachée réussie se finalise en `succeeded`, les erreurs d'exécution ordinaires se finalisent en `failed`, et les résultats de délai expiré ou d'abandon se finalisent en `timed_out`. Si un opérateur a déjà annulé la tâche, ou si l'environnement d'exécution a déjà enregistré un état terminal plus fort comme `failed`, `timed_out` ou `lost`, un signal de réussite ultérieur ne rétrograde pas cet état terminal. +L’achèvement d’exécution d’agent fait autorité pour les enregistrements de tâche actifs. Une exécution détachée réussie se finalise en `succeeded`, les erreurs d’exécution ordinaires se finalisent en `failed`, et les résultats d’expiration ou d’abandon se finalisent en `timed_out`. Si un opérateur a déjà annulé la tâche, ou si le runtime a déjà enregistré un état terminal plus fort comme `failed`, `timed_out` ou `lost`, un signal de réussite ultérieur ne rétrograde pas cet état terminal. -`lost` tient compte de l'environnement d'exécution : +`lost` tient compte du runtime : -- Tâches ACP : les métadonnées de session enfant ACP de support ont disparu. -- Tâches de sous-agent : la session enfant de support a disparu du stockage de l'agent cible. -- Tâches Cron : l'environnement d'exécution Cron ne suit plus la tâche comme active et l'historique durable des exécutions Cron n'indique pas de résultat terminal pour cette exécution. L'audit CLI hors ligne ne considère pas son propre état d'exécution Cron en processus vide comme faisant autorité. -- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent plutôt le contexte d'exécution actif, de sorte que les lignes de session persistantes de canal/groupe/direct ne les maintiennent pas en vie. Les exécutions `openclaw agent` adossées au Gateway se finalisent aussi à partir de leur résultat d'exécution, de sorte que les exécutions terminées ne restent pas actives jusqu'à ce que le processus de nettoyage les marque `lost`. +- Tâches ACP : les métadonnées de session ACP enfant sous-jacentes ont disparu. +- Tâches de sous-agent : la session enfant sous-jacente a disparu du magasin de l’agent cible. +- Tâches Cron : le runtime Cron ne suit plus la tâche comme active et l’historique durable des exécutions Cron n’indique pas de résultat terminal pour cette exécution. L’audit CLI hors ligne ne traite pas son propre état vide de runtime Cron en cours de processus comme faisant autorité. +- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent plutôt le contexte d’exécution actif, donc les lignes persistantes de session canal/groupe/direct ne les maintiennent pas en vie. Les exécutions `openclaw agent` adossées au Gateway se finalisent aussi à partir de leur résultat d’exécution, donc les exécutions terminées ne restent pas actives jusqu’à ce que le balayeur les marque `lost`. ## Livraison et notifications -Lorsqu'une tâche atteint un état terminal, OpenClaw vous notifie. Il existe deux chemins de livraison : +Lorsqu’une tâche atteint un état terminal, OpenClaw vous notifie. Il existe deux chemins de livraison : -**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message de finalisation va directement à ce canal (Telegram, Discord, Slack, etc.). Pour les finalisations de sous-agents, OpenClaw préserve aussi le routage de fil/sujet lié lorsqu'il est disponible et peut renseigner un `to` / compte manquant à partir de la route stockée dans la session du demandeur (`lastChannel` / `lastTo` / `lastAccountId`) avant d'abandonner la livraison directe. +**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message d’achèvement va directement à ce canal (Telegram, Discord, Slack, etc.). Pour les achèvements de sous-agents, OpenClaw préserve aussi le routage lié au fil/sujet lorsqu’il est disponible et peut renseigner un `to` / compte manquant depuis la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d’abandonner la livraison directe. -**Livraison mise en file d'attente de session** — si la livraison directe échoue ou si aucune origine n'est définie, la mise à jour est mise en file d'attente comme événement système dans la session du demandeur et apparaît au prochain Heartbeat. +**Livraison mise en file d’attente de session** — si la livraison directe échoue ou qu’aucune origine n’est définie, la mise à jour est mise en file d’attente comme événement système dans la session du demandeur et apparaît au prochain Heartbeat. -La finalisation d'une tâche déclenche un réveil Heartbeat immédiat, afin que vous voyiez rapidement le résultat — vous n'avez pas besoin d'attendre la prochaine impulsion Heartbeat planifiée. +L’achèvement de tâche déclenche un réveil Heartbeat immédiat afin que vous voyiez rapidement le résultat : vous n’avez pas à attendre le prochain tick Heartbeat planifié. -Cela signifie que le flux de travail habituel repose sur les notifications : démarrez le travail détaché une fois, puis laissez l'environnement d'exécution vous réveiller ou vous notifier à la fin. Interrogez l'état des tâches uniquement lorsque vous avez besoin de débogage, d'intervention ou d'un audit explicite. +Cela signifie que le flux de travail habituel est fondé sur des notifications : démarrez le travail détaché une fois, puis laissez le runtime vous réveiller ou vous notifier à l’achèvement. Sondez l’état de la tâche uniquement lorsque vous avez besoin de débogage, d’intervention ou d’un audit explicite. ### Politiques de notification -Contrôlez la quantité d'informations que vous recevez pour chaque tâche : +Contrôlez le volume d’informations que vous recevez pour chaque tâche : -| Politique | Ce qui est livré | +| Politique | Ce qui est livré | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (par défaut) | Seul l'état terminal (succeeded, failed, etc.) — **c'est la valeur par défaut** | -| `state_changes` | Chaque transition d'état et mise à jour de progression | +| `done_only` (par défaut) | Uniquement l’état terminal (réussie, échouée, etc.) — **c’est la valeur par défaut** | +| `state_changes` | Chaque transition d’état et mise à jour de progression | | `silent` | Rien du tout | -Modifiez la politique pendant qu'une tâche est en cours d'exécution : +Changez la politique pendant qu’une tâche s’exécute : ```bash openclaw tasks notify state_changes @@ -192,7 +192,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - Colonnes de sortie : ID de tâche, Type, État, Livraison, ID d'exécution, Session enfant, Résumé. + Colonnes de sortie : ID de tâche, Type, État, Livraison, ID d’exécution, Session enfant, Résumé. @@ -200,7 +200,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - Le jeton de recherche accepte un ID de tâche, un ID d'exécution ou une clé de session. Affiche l'enregistrement complet, notamment le minutage, l'état de livraison, l'erreur et le résumé terminal. + Le jeton de recherche accepte un ID de tâche, un ID d’exécution ou une clé de session. Affiche l’enregistrement complet, notamment la temporisation, l’état de livraison, l’erreur et le résumé terminal. @@ -208,7 +208,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - Pour les tâches ACP et de sous-agent, cela tue la session enfant. Pour les tâches suivies par la CLI, l'annulation est enregistrée dans le registre des tâches (il n'existe pas de handle d'exécution enfant séparé). L'état passe à `cancelled` et une notification de livraison est envoyée le cas échéant. + Pour les tâches ACP et de sous-agent, cela tue la session enfant. Pour les tâches suivies par la CLI, l’annulation est enregistrée dans le registre des tâches (il n’existe pas de handle de runtime enfant séparé). L’état passe à `cancelled` et une notification de livraison est envoyée le cas échéant. @@ -223,14 +223,14 @@ openclaw tasks notify state_changes Fait remonter les problèmes opérationnels. Les constats apparaissent aussi dans `openclaw status` lorsque des problèmes sont détectés. - | Finding | Severity | Trigger | + | Constat | Gravité | Déclencheur | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | - | `stale_queued` | warn | En file d'attente depuis plus de 10 minutes | - | `stale_running` | error | En cours depuis plus de 30 minutes | - | `lost` | warn/error | La propriété de la tâche adossée au runtime a disparu ; les tâches perdues conservées émettent un avertissement jusqu'à `cleanupAfter`, puis deviennent des erreurs | - | `delivery_failed` | warn | La livraison a échoué et la politique de notification n'est pas `silent` | - | `missing_cleanup` | warn | Tâche terminale sans horodatage de nettoyage | - | `inconsistent_timestamps` | warn | Violation de chronologie (par exemple terminée avant d'avoir commencé) | + | `stale_queued` | warn | En file d’attente depuis plus de 10 minutes | + | `stale_running` | error | En cours d’exécution depuis plus de 30 minutes | + | `lost` | warn/error | La propriété de la tâche adossée à l’exécution a disparu ; les tâches perdues conservées émettent un avertissement jusqu’à `cleanupAfter`, puis deviennent des erreurs | + | `delivery_failed` | warn | La livraison a échoué et la stratégie de notification n’est pas `silent` | + | `missing_cleanup` | warn | Tâche terminale sans horodatage de nettoyage | + | `inconsistent_timestamps` | warn | Violation de la chronologie (par exemple, terminée avant d’avoir commencé) | @@ -239,47 +239,47 @@ openclaw tasks notify state_changes openclaw tasks maintenance --apply [--json] ``` - Utilisez ceci pour prévisualiser ou appliquer la réconciliation, l'horodatage de nettoyage et l'élagage pour les tâches et l'état Task Flow. + Utilisez cette commande pour prévisualiser ou appliquer la réconciliation, l’horodatage du nettoyage et l’élagage des tâches et de l’état Task Flow. - La réconciliation tient compte du runtime : + La réconciliation tient compte de l’exécution : - - Les tâches ACP/subagent vérifient leur session enfant sous-jacente. - - Les tâches de subagent dont la session enfant possède une tombe de récupération après redémarrage sont marquées comme perdues au lieu d'être traitées comme des sessions sous-jacentes récupérables. - - Les tâches Cron vérifient si le runtime cron possède toujours la tâche, puis récupèrent l'état terminal depuis les journaux d'exécution cron persistés/l'état de tâche avant de revenir à `lost`. Seul le processus Gateway fait autorité pour l'ensemble en mémoire des tâches cron actives ; l'audit CLI hors ligne utilise l'historique durable mais ne marque pas une tâche cron comme perdue uniquement parce que ce Set local est vide. - - Les tâches CLI adossées au chat vérifient le contexte d'exécution actif propriétaire, pas seulement la ligne de session de chat. + - Les tâches ACP/sous-agent vérifient leur session enfant sous-jacente. + - Les tâches de sous-agent dont la session enfant possède une pierre tombale de récupération après redémarrage sont marquées comme perdues au lieu d’être traitées comme des sessions sous-jacentes récupérables. + - Les tâches Cron vérifient si l’exécution cron possède toujours la tâche, puis récupèrent l’état terminal depuis les journaux persistés des exécutions cron/l’état de la tâche avant de basculer vers `lost`. Seul le processus Gateway fait autorité pour l’ensemble en mémoire des tâches actives cron ; l’audit CLI hors ligne utilise l’historique durable, mais ne marque pas une tâche cron comme perdue uniquement parce que ce Set local est vide. + - Les tâches CLI adossées au chat vérifient le contexte d’exécution actif propriétaire, pas seulement la ligne de session de chat. - Le nettoyage d'achèvement tient aussi compte du runtime : + Le nettoyage de fin tient également compte de l’exécution : - - L'achèvement d'un subagent ferme, au mieux, les onglets/processus de navigateur suivis pour la session enfant avant la poursuite du nettoyage d'annonce. - - L'achèvement d'un cron isolé ferme, au mieux, les onglets/processus de navigateur suivis pour la session cron avant que l'exécution ne se termine complètement. - - La livraison cron isolée attend le suivi des subagents descendants lorsque nécessaire et supprime le texte d'accusé de réception parent obsolète au lieu de l'annoncer. - - La livraison d'achèvement d'un subagent préfère le dernier texte d'assistant visible ; s'il est vide, elle se rabat sur le dernier texte d'outil/toolResult assaini, et les exécutions d'appels d'outil terminées uniquement par délai d'attente peuvent être réduites à un bref résumé de progression partielle. Les exécutions terminales échouées annoncent l'état d'échec sans rejouer le texte de réponse capturé. + - La fin d’un sous-agent ferme au mieux les onglets de navigateur/processus suivis pour la session enfant avant la poursuite du nettoyage d’annonce. + - La fin d’un Cron isolé ferme au mieux les onglets de navigateur/processus suivis pour la session cron avant le démontage complet de l’exécution. + - La livraison Cron isolée attend la suite d’un sous-agent descendant si nécessaire et supprime le texte d’accusé de réception parent obsolète au lieu de l’annoncer. + - La livraison de fin d’un sous-agent privilégie le dernier texte d’assistant visible ; s’il est vide, elle se rabat sur le dernier texte d’outil/toolResult assaini, et les exécutions avec appels d’outils uniquement interrompues par expiration peuvent être réduites à un court résumé de progression partielle. Les exécutions terminales en échec annoncent l’état d’échec sans rejouer le texte de réponse capturé. - Les échecs de nettoyage ne masquent pas le résultat réel de la tâche. - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - Utilisez ces commandes lorsque le Task Flow orchestrateur est ce qui vous intéresse, plutôt qu'un enregistrement individuel de tâche en arrière-plan. + Utilisez ces commandes lorsque le Task Flow orchestrateur est ce qui vous intéresse, plutôt qu’un enregistrement individuel de tâche en arrière-plan. -## Tableau des tâches de chat (`/tasks`) +## Tableau de tâches du chat (`/tasks`) -Utilisez `/tasks` dans n'importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche les tâches actives et récemment terminées avec le runtime, l'état, les informations de durée, et les détails de progression ou d'erreur. +Utilisez `/tasks` dans n’importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche les tâches actives et récemment terminées avec l’exécution, l’état, le minutage et les détails de progression ou d’erreur. -Lorsque la session actuelle n'a aucune tâche liée visible, `/tasks` se rabat sur les compteurs de tâches locaux à l'agent afin que vous obteniez tout de même une vue d'ensemble sans divulguer les détails d'autres sessions. +Lorsque la session actuelle n’a aucune tâche liée visible, `/tasks` se rabat sur les nombres de tâches locales à l’agent afin de vous donner tout de même une vue d’ensemble sans divulguer les détails d’autres sessions. Pour le registre opérateur complet, utilisez la CLI : `openclaw tasks list`. -## Intégration de l'état (pression des tâches) +## Intégration de l’état (pression des tâches) -`openclaw status` inclut un résumé rapide des tâches : +`openclaw status` inclut un résumé des tâches en un coup d’œil : ``` Tasks: 3 queued · 2 running · 1 issues @@ -289,80 +289,79 @@ Le résumé indique : - **actives** — nombre de `queued` + `running` - **échecs** — nombre de `failed` + `timed_out` + `lost` -- **byRuntime** — répartition par `acp`, `subagent`, `cron`, `cli` +- **byRuntime** — ventilation par `acp`, `subagent`, `cron`, `cli` -`/status` et l'outil `session_status` utilisent tous deux un instantané des tâches tenant compte du nettoyage : les tâches actives sont privilégiées, les lignes terminées obsolètes sont masquées, et les échecs récents ne s'affichent que lorsqu'aucun travail actif ne reste. Cela garde la carte d'état concentrée sur ce qui compte maintenant. +`/status` et l’outil `session_status` utilisent tous deux un instantané des tâches tenant compte du nettoyage : les tâches actives sont privilégiées, les lignes terminées obsolètes sont masquées et les échecs récents n’apparaissent que lorsqu’il ne reste aucun travail actif. Cela garde la carte d’état centrée sur ce qui compte maintenant. ## Stockage et maintenance -### Où résident les tâches +### Où vivent les tâches -Les enregistrements de tâches persistent dans SQLite à : +Les enregistrements de tâches persistent dans SQLite à l’emplacement suivant : ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` Le registre est chargé en mémoire au démarrage du Gateway et synchronise les écritures vers SQLite pour assurer la durabilité entre les redémarrages. -Le Gateway maintient le journal write-ahead log de SQLite borné en utilisant le seuil -d'autocheckpoint par défaut de SQLite ainsi que des points de contrôle `TRUNCATE` périodiques et à l'arrêt. +Le Gateway maintient le journal d’écriture anticipée SQLite dans des limites définies en utilisant le seuil d’autocheckpoint par défaut de SQLite, plus des points de contrôle `TRUNCATE` périodiques et à l’arrêt. ### Maintenance automatique -Un balayeur s'exécute toutes les **60 secondes** et gère quatre choses : +Un balayeur s’exécute toutes les **60 secondes** et gère quatre éléments : - Vérifie si les tâches actives ont toujours un support runtime faisant autorité. Les tâches ACP/subagent utilisent l'état de session enfant, les tâches cron utilisent la propriété des tâches actives, et les tâches CLI adossées au chat utilisent le contexte d'exécution propriétaire. Si cet état sous-jacent a disparu depuis plus de 5 minutes, la tâche est marquée `lost`. + Vérifie si les tâches actives disposent toujours d’un support d’exécution faisant autorité. Les tâches ACP/sous-agent utilisent l’état de session enfant, les tâches cron utilisent la propriété des tâches actives, et les tâches CLI adossées au chat utilisent le contexte d’exécution propriétaire. Si cet état sous-jacent a disparu depuis plus de 5 minutes, la tâche est marquée `lost`. - - Ferme les sessions ACP terminales ou orphelines à exécution unique appartenant au parent, et ferme les sessions ACP persistantes terminales ou orphelines obsolètes uniquement lorsqu'aucune liaison de conversation active ne reste. + + Ferme les sessions ACP ponctuelles terminales ou orphelines appartenant au parent, et ferme les sessions ACP persistantes terminales ou orphelines obsolètes uniquement lorsqu’il ne reste aucune liaison de conversation active. - - Définit un horodatage `cleanupAfter` sur les tâches terminales (endedAt + 7 jours). Pendant la rétention, les tâches perdues apparaissent encore dans l'audit comme avertissements ; après l'expiration de `cleanupAfter` ou lorsque les métadonnées de nettoyage manquent, ce sont des erreurs. + + Définit un horodatage `cleanupAfter` sur les tâches terminales (endedAt + 7 jours). Pendant la rétention, les tâches perdues apparaissent encore dans l’audit comme avertissements ; après l’expiration de `cleanupAfter` ou lorsque les métadonnées de nettoyage sont manquantes, elles sont des erreurs. - Supprime les enregistrements après leur date `cleanupAfter`. + Supprime les enregistrements dont la date `cleanupAfter` est dépassée. -**Rétention :** les enregistrements de tâches terminales sont conservés pendant **7 jours**, puis automatiquement élagués. Aucune configuration nécessaire. +**Rétention :** les enregistrements de tâches terminales sont conservés pendant **7 jours**, puis automatiquement élagués. Aucune configuration requise. ## Relation des tâches avec les autres systèmes - [Task Flow](/fr/automation/taskflow) est la couche d'orchestration de flux au-dessus des tâches en arrière-plan. Un flux unique peut coordonner plusieurs tâches au cours de sa durée de vie à l'aide de modes de synchronisation gérés ou en miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements de tâches individuels et `openclaw tasks flow` pour inspecter le flux orchestrateur. + [Task Flow](/fr/automation/taskflow) est la couche d’orchestration de flux au-dessus des tâches en arrière-plan. Un même flux peut coordonner plusieurs tâches au cours de sa durée de vie au moyen de modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements de tâches individuels et `openclaw tasks flow` pour inspecter le flux orchestrateur. Consultez [Task Flow](/fr/automation/taskflow) pour plus de détails. - Une **définition** de tâche cron réside dans `~/.openclaw/cron/jobs.json` ; l'état d'exécution runtime réside à côté, dans `~/.openclaw/cron/jobs-state.json`. **Chaque** exécution cron crée un enregistrement de tâche — à la fois pour les sessions principales et isolées. Les tâches cron de session principale utilisent par défaut la politique de notification `silent` afin d'être suivies sans générer de notifications. + Une **définition** de tâche cron se trouve dans `~/.openclaw/cron/jobs.json` ; l’état d’exécution à l’exécution se trouve à côté, dans `~/.openclaw/cron/jobs-state.json`. **Chaque** exécution cron crée un enregistrement de tâche, qu’elle soit en session principale ou isolée. Les tâches cron en session principale utilisent par défaut la stratégie de notification `silent`, ce qui leur permet d’être suivies sans générer de notifications. Consultez [Tâches Cron](/fr/automation/cron-jobs). - Les exécutions Heartbeat sont des tours de session principale — elles ne créent pas d'enregistrements de tâches. Lorsqu'une tâche se termine, elle peut déclencher un réveil Heartbeat afin que vous voyiez rapidement le résultat. + Les exécutions Heartbeat sont des tours de session principale ; elles ne créent pas d’enregistrements de tâches. Lorsqu’une tâche se termine, elle peut déclencher un réveil Heartbeat afin que vous voyiez rapidement le résultat. Consultez [Heartbeat](/fr/gateway/heartbeat). - Une tâche peut référencer une `childSessionKey` (où le travail s'exécute) et une `requesterSessionKey` (qui l'a démarrée). Les sessions sont le contexte de conversation ; les tâches sont le suivi d'activité par-dessus. + Une tâche peut référencer un `childSessionKey` (où le travail s’exécute) et un `requesterSessionKey` (qui l’a démarrée). Les sessions constituent le contexte de conversation ; les tâches ajoutent un suivi d’activité par-dessus. - - Le `runId` d'une tâche établit un lien vers l'exécution d'agent qui effectue le travail. Les événements du cycle de vie de l'agent (début, fin, erreur) mettent automatiquement à jour l'état de la tâche — vous n'avez pas besoin de gérer le cycle de vie manuellement. + + Le `runId` d’une tâche pointe vers l’exécution d’agent qui effectue le travail. Les événements de cycle de vie de l’agent (début, fin, erreur) mettent automatiquement à jour l’état de la tâche ; vous n’avez pas besoin de gérer le cycle de vie manuellement. ## Connexe -- [Automatisation et tâches](/fr/automation) — tous les mécanismes d'automatisation en un coup d'œil +- [Automatisation et tâches](/fr/automation) — tous les mécanismes d’automatisation en un coup d’œil - [CLI : tâches](/fr/cli/tasks) — référence des commandes CLI -- [Heartbeat](/fr/gateway/heartbeat) — tours périodiques de session principale -- [Tâches planifiées](/fr/automation/cron-jobs) — planifier du travail en arrière-plan +- [Heartbeat](/fr/gateway/heartbeat) — tours périodiques en session principale +- [Tâches planifiées](/fr/automation/cron-jobs) — planification du travail en arrière-plan - [Task Flow](/fr/automation/taskflow) — orchestration de flux au-dessus des tâches diff --git a/docs/fr/channels/telegram.md b/docs/fr/channels/telegram.md index b798556fe..92950bdec 100644 --- a/docs/fr/channels/telegram.md +++ b/docs/fr/channels/telegram.md @@ -1,25 +1,25 @@ --- read_when: - Travailler sur les fonctionnalités Telegram ou les Webhooks -summary: État de la prise en charge, fonctionnalités et configuration du bot Telegram +summary: État de prise en charge du bot Telegram, capacités et configuration title: Telegram x-i18n: - generated_at: "2026-05-04T09:37:03Z" + generated_at: "2026-05-05T06:16:04Z" model: gpt-5.5 provider: openai - source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932 + source_hash: 03c75169335378482b80f1ceb669cefaa034ad3e589cf5f1d14c8252608ee46a source_path: channels/telegram.md workflow: 16 --- -Prêt pour la production pour les messages privés et les groupes de bots via grammY. L’interrogation longue est le mode par défaut ; le mode Webhook est facultatif. +Prêt pour la production pour les MP de bots et les groupes via grammY. Le mode par défaut est le long polling ; le mode Webhook est facultatif. - La politique de messages privés par défaut pour Telegram est l’appairage. + La politique de MP par défaut pour Telegram est l’appairage. - Diagnostics intercanaux et guides de réparation. + Diagnostics multicanaux et guides de réparation. Modèles et exemples complets de configuration de canal. @@ -30,13 +30,13 @@ Prêt pour la production pour les messages privés et les groupes de bots via gr - Ouvrez Telegram et discutez avec **@BotFather** (confirmez que l’identifiant est exactement `@BotFather`). + Ouvrez Telegram et discutez avec **@BotFather** (vérifiez que l’identifiant est exactement `@BotFather`). Exécutez `/newbot`, suivez les invites et enregistrez le jeton. - + ```json5 { @@ -51,12 +51,12 @@ Prêt pour la production pour les messages privés et les groupes de bots via gr } ``` - Solution de repli par env : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement). + Repli env : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement). Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans la config/l’env, puis démarrez le Gateway. - + ```bash openclaw gateway @@ -69,26 +69,26 @@ openclaw pairing approve telegram - Ajoutez le bot à votre groupe, puis définissez `channels.telegram.groups` et `groupPolicy` pour correspondre à votre modèle d’accès. + Ajoutez le bot à votre groupe, puis définissez `channels.telegram.groups` et `groupPolicy` selon votre modèle d’accès. -L’ordre de résolution du jeton tient compte du compte. En pratique, les valeurs de configuration l’emportent sur la solution de repli par env, et `TELEGRAM_BOT_TOKEN` ne s’applique qu’au compte par défaut. +L’ordre de résolution des jetons tient compte du compte. En pratique, les valeurs de config priment sur le repli env, et `TELEGRAM_BOT_TOKEN` s’applique uniquement au compte par défaut. ## Paramètres côté Telegram - Les bots Telegram utilisent par défaut le **mode confidentialité**, qui limite les messages de groupe qu’ils reçoivent. + Les bots Telegram utilisent par défaut le **Mode confidentialité**, qui limite les messages de groupe qu’ils reçoivent. - Si le bot doit voir tous les messages de groupe, vous pouvez soit : + Si le bot doit voir tous les messages de groupe, vous pouvez : - - désactiver le mode confidentialité via `/setprivacy`, soit + - désactiver le mode confidentialité via `/setprivacy`, ou - faire du bot un administrateur du groupe. - Lorsque vous activez ou désactivez le mode confidentialité, supprimez puis rajoutez le bot dans chaque groupe afin que Telegram applique le changement. + Lorsque vous changez le mode confidentialité, supprimez puis rajoutez le bot dans chaque groupe pour que Telegram applique le changement. @@ -101,8 +101,8 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu - - `/setjoingroups` pour autoriser/refuser les ajouts à des groupes - - `/setprivacy` pour le comportement de visibilité dans les groupes + - `/setjoingroups` pour autoriser/refuser les ajouts aux groupes + - `/setprivacy` pour le comportement de visibilité en groupe @@ -110,7 +110,7 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu ## Contrôle d’accès et activation - + `channels.telegram.dmPolicy` contrôle l’accès aux messages directs : - `pairing` (par défaut) @@ -118,27 +118,27 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu - `open` (nécessite que `allowFrom` inclue `"*"`) - `disabled` - `dmPolicy: "open"` avec `allowFrom: ["*"]` permet à tout compte Telegram qui trouve ou devine le nom d’utilisateur du bot de commander le bot. Utilisez-le uniquement pour des bots volontairement publics avec des outils strictement restreints ; les bots à propriétaire unique devraient utiliser `allowlist` avec des ID utilisateur numériques. + `dmPolicy: "open"` avec `allowFrom: ["*"]` permet à tout compte Telegram qui trouve ou devine le nom d’utilisateur du bot de commander le bot. Utilisez-le uniquement pour des bots volontairement publics avec des outils strictement restreints ; les bots à propriétaire unique doivent utiliser `allowlist` avec des ID utilisateur numériques. `channels.telegram.allowFrom` accepte les ID utilisateur Telegram numériques. Les préfixes `telegram:` / `tg:` sont acceptés et normalisés. - Dans les configurations multicompte, un `channels.telegram.allowFrom` restrictif au niveau supérieur est traité comme une limite de sécurité : les entrées `allowFrom: ["*"]` au niveau du compte ne rendent pas ce compte public sauf si la liste d’autorisation effective du compte contient toujours un joker explicite après fusion. - `dmPolicy: "allowlist"` avec `allowFrom` vide bloque tous les messages privés et est rejeté par la validation de configuration. + Dans les configurations multicomptes, un `channels.telegram.allowFrom` restrictif au niveau supérieur est traité comme une limite de sécurité : les entrées `allowFrom: ["*"]` au niveau du compte ne rendent pas ce compte public, sauf si la liste d’autorisation effective du compte contient encore un joker explicite après fusion. + `dmPolicy: "allowlist"` avec `allowFrom` vide bloque tous les MP et est rejeté par la validation de config. La configuration demande uniquement des ID utilisateur numériques. - Si vous avez effectué une mise à niveau et que votre configuration contient des entrées de liste d’autorisation `@username`, exécutez `openclaw doctor --fix` pour les résoudre (au mieux ; nécessite un jeton de bot Telegram). - Si vous vous appuyiez précédemment sur des fichiers de liste d’autorisation du magasin d’appairage, `openclaw doctor --fix` peut récupérer les entrées dans `channels.telegram.allowFrom` dans les flux de liste d’autorisation (par exemple lorsque `dmPolicy: "allowlist"` n’a pas encore d’ID explicites). + Si vous avez effectué une mise à niveau et que votre config contient des entrées de liste d’autorisation `@username`, exécutez `openclaw doctor --fix` pour les résoudre (meilleur effort ; nécessite un jeton de bot Telegram). + Si vous vous appuyiez auparavant sur des fichiers de liste d’autorisation du magasin d’appairage, `openclaw doctor --fix` peut récupérer les entrées dans `channels.telegram.allowFrom` dans les flux de liste d’autorisation (par exemple lorsque `dmPolicy: "allowlist"` n’a pas encore d’ID explicites). - Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID numériques `allowFrom` explicites afin de conserver une politique d’accès durable dans la configuration (plutôt que de dépendre des approbations d’appairage précédentes). + Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID `allowFrom` numériques explicites afin de conserver une politique d’accès durable dans la config (au lieu de dépendre d’approbations d’appairage précédentes). - Confusion fréquente : l’approbation d’appairage des messages privés ne signifie pas « cet expéditeur est autorisé partout ». - L’appairage accorde l’accès aux messages privés. Si aucun propriétaire de commande n’existe encore, le premier appairage approuvé définit aussi `commands.ownerAllowFrom` afin que les commandes réservées au propriétaire et les approbations d’exécution aient un compte opérateur explicite. - L’autorisation des expéditeurs de groupe provient toujours des listes d’autorisation explicites de la configuration. - Si vous voulez « je suis autorisé une fois, et les messages privés comme les commandes de groupe fonctionnent », placez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom` ; pour les commandes réservées au propriétaire, assurez-vous que `commands.ownerAllowFrom` contient `telegram:`. + Confusion fréquente : l’approbation d’appairage en MP ne signifie pas « cet expéditeur est autorisé partout ». + L’appairage accorde l’accès aux MP. Si aucun propriétaire de commandes n’existe encore, le premier appairage approuvé définit aussi `commands.ownerAllowFrom` afin que les commandes réservées au propriétaire et les approbations d’exécution disposent d’un compte opérateur explicite. + L’autorisation des expéditeurs de groupe provient toujours des listes d’autorisation explicites de la config. + Si vous voulez « je suis autorisé une fois et les MP comme les commandes de groupe fonctionnent », placez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom` ; pour les commandes réservées au propriétaire, vérifiez que `commands.ownerAllowFrom` contient `telegram:`. ### Trouver votre ID utilisateur Telegram Plus sûr (sans bot tiers) : - 1. Envoyez un message privé à votre bot. + 1. Envoyez un MP à votre bot. 2. Exécutez `openclaw logs --follow`. 3. Lisez `from.id`. @@ -157,7 +157,7 @@ curl "https://api.telegram.org/bot/getUpdates" 1. **Quels groupes sont autorisés** (`channels.telegram.groups`) - aucune config `groups` : - - avec `groupPolicy: "open"` : tout groupe peut réussir les contrôles d’ID de groupe + - avec `groupPolicy: "open"` : n’importe quel groupe peut passer les vérifications d’ID de groupe - avec `groupPolicy: "allowlist"` (par défaut) : les groupes sont bloqués jusqu’à ce que vous ajoutiez des entrées `groups` (ou `"*"`) - `groups` configuré : agit comme liste d’autorisation (ID explicites ou `"*"`) @@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot/getUpdates" `groupAllowFrom` est utilisé pour le filtrage des expéditeurs de groupe. S’il n’est pas défini, Telegram se rabat sur `allowFrom`. Les entrées `groupAllowFrom` doivent être des ID utilisateur Telegram numériques (les préfixes `telegram:` / `tg:` sont normalisés). - Ne mettez pas d’ID de chat de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de chat négatifs appartiennent à `channels.telegram.groups`. - Les entrées non numériques sont ignorées pour l’autorisation des expéditeurs. - Limite de sécurité (`2026.2.25+`) : l’authentification des expéditeurs de groupe n’hérite **pas** des approbations du magasin d’appairage de messages privés. - L’appairage reste limité aux messages privés. Pour les groupes, définissez `groupAllowFrom` ou `allowFrom` par groupe/par sujet. + Ne mettez pas d’ID de chat de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de chat négatifs doivent être placés sous `channels.telegram.groups`. + Les entrées non numériques sont ignorées pour l’autorisation d’expéditeur. + Limite de sécurité (`2026.2.25+`) : l’authentification des expéditeurs de groupe n’hérite **pas** des approbations du magasin d’appairage en MP. + L’appairage reste limité aux MP. Pour les groupes, définissez `groupAllowFrom` ou `allowFrom` par groupe/par sujet. Si `groupAllowFrom` n’est pas défini, Telegram se rabat sur la config `allowFrom`, pas sur le magasin d’appairage. - Modèle pratique pour les bots à propriétaire unique : définissez votre ID utilisateur dans `channels.telegram.allowFrom`, laissez `groupAllowFrom` non défini, et autorisez les groupes cibles sous `channels.telegram.groups`. - Note d’exécution : si `channels.telegram` est complètement absent, l’exécution utilise par défaut `groupPolicy="allowlist"` en échec fermé, sauf si `channels.defaults.groupPolicy` est explicitement défini. + Modèle pratique pour les bots à propriétaire unique : définissez votre ID utilisateur dans `channels.telegram.allowFrom`, laissez `groupAllowFrom` non défini et autorisez les groupes cibles sous `channels.telegram.groups`. + Note d’exécution : si `channels.telegram` est totalement absent, l’exécution utilise par défaut `groupPolicy="allowlist"` avec échec fermé, sauf si `channels.defaults.groupPolicy` est explicitement défini. Exemple : autoriser n’importe quel membre dans un groupe spécifique : @@ -214,8 +214,8 @@ curl "https://api.telegram.org/bot/getUpdates" Erreur fréquente : `groupAllowFrom` n’est pas une liste d’autorisation de groupes Telegram. - Placez les ID de chat de groupe ou de supergroupe Telegram négatifs comme `-1001234567890` sous `channels.telegram.groups`. - - Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes qui, dans un groupe autorisé, peuvent déclencher le bot. - - Utilisez `groupAllowFrom: ["*"]` uniquement lorsque vous voulez que tout membre d’un groupe autorisé puisse parler au bot. + - Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes qui peuvent déclencher le bot dans un groupe autorisé. + - Utilisez `groupAllowFrom: ["*"]` uniquement lorsque vous voulez que n’importe quel membre d’un groupe autorisé puisse parler au bot. @@ -224,10 +224,10 @@ curl "https://api.telegram.org/bot/getUpdates" Les réponses de groupe nécessitent une mention par défaut. - La mention peut provenir de : + La mention peut provenir : - - une mention native `@botusername`, ou - - des motifs de mention dans : + - d’une mention native `@botusername`, ou + - de modèles de mention dans : - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - Celles-ci ne mettent à jour que l’état de la session. Utilisez la configuration pour la persistance. + Elles mettent uniquement à jour l’état de session. Utilisez la config pour la persistance. - Exemple de configuration persistante : + Exemple de config persistante : ```json5 { @@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Obtenir l’ID du chat de groupe : + Obtenir l’ID de chat du groupe : - transférer un message de groupe à `@userinfobot` / `@getidsbot` - ou lire `chat.id` depuis `openclaw logs --follow` @@ -261,16 +261,16 @@ curl "https://api.telegram.org/bot/getUpdates" -## Comportement à l’exécution +## Comportement d’exécution -- Telegram est géré par le processus Gateway. -- Le routage est déterministe : les réponses entrantes de Telegram repartent vers Telegram (le modèle ne choisit pas les canaux). -- Les messages entrants sont normalisés dans l’enveloppe de canal partagée avec les métadonnées de réponse et les espaces réservés de médias. -- Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent `:topic:` pour garder les sujets isolés. -- Les messages privés peuvent porter `message_thread_id` ; OpenClaw conserve l’ID de fil pour les réponses mais garde par défaut les messages privés sur la session plate. Configurez `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true` ou une configuration de sujet correspondante lorsque vous voulez intentionnellement isoler les sessions de sujets en messages privés. -- L’interrogation longue utilise grammY runner avec un séquençage par chat/par fil. La concurrence globale du récepteur du runner utilise `agents.defaults.maxConcurrent`. -- L’interrogation longue est protégée dans chaque processus Gateway afin qu’un seul poller actif puisse utiliser un jeton de bot à la fois. Si vous voyez toujours des conflits `getUpdates` 409, un autre Gateway OpenClaw, script ou poller externe utilise probablement le même jeton. -- Les redémarrages de surveillance de l’interrogation longue se déclenchent par défaut après 120 secondes sans liveness `getUpdates` terminée. Augmentez `channels.telegram.pollingStallThresholdMs` uniquement si votre déploiement voit encore de faux redémarrages pour blocage d’interrogation pendant des travaux de longue durée. La valeur est en millisecondes et est autorisée de `30000` à `600000` ; les remplacements par compte sont pris en charge. +- Telegram appartient au processus Gateway. +- Le routage est déterministe : les entrées Telegram répondent vers Telegram (le modèle ne choisit pas les canaux). +- Les messages entrants sont normalisés dans l’enveloppe de canal partagée avec les métadonnées de réponse et les espaces réservés de média. +- Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent `:topic:` pour maintenir l’isolation des sujets. +- Les messages MP peuvent transporter `message_thread_id` ; OpenClaw préserve l’ID de fil pour les réponses, mais conserve les MP sur la session plate par défaut. Configurez `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct..threadReplies: "inbound"`, `requireTopic: true`, ou une config de sujet correspondante lorsque vous voulez intentionnellement isoler les sessions par sujet de MP. +- Le long polling utilise le runner grammY avec séquencement par chat/par fil. La concurrence globale du collecteur du runner utilise `agents.defaults.maxConcurrent`. +- Le long polling est protégé dans chaque processus Gateway afin qu’un seul poller actif puisse utiliser un jeton de bot à la fois. Si vous voyez encore des conflits `getUpdates` 409, un autre Gateway OpenClaw, script ou poller externe utilise probablement le même jeton. +- Les redémarrages du chien de garde de long polling se déclenchent par défaut après 120 secondes sans vivacité `getUpdates` terminée. Augmentez `channels.telegram.pollingStallThresholdMs` uniquement si votre déploiement observe encore de faux redémarrages pour blocage de polling pendant des tâches longues. La valeur est en millisecondes et est autorisée de `30000` à `600000` ; les remplacements par compte sont pris en charge. - L’API Bot Telegram ne prend pas en charge les accusés de lecture (`sendReadReceipts` ne s’applique pas). ## Référence des fonctionnalités @@ -285,12 +285,12 @@ curl "https://api.telegram.org/bot/getUpdates" Exigence : - `channels.telegram.streaming` vaut `off | partial | block | progress` (par défaut : `partial`) - - `progress` conserve un brouillon d’état modifiable et le met à jour avec la progression des outils jusqu’à la livraison finale + - `progress` conserve un brouillon de statut modifiable et le met à jour avec la progression des outils jusqu’à la livraison finale - `streaming.preview.toolProgress` contrôle si les mises à jour d’outil/de progression réutilisent le même message d’aperçu modifié (par défaut : `true` lorsque le streaming d’aperçu est actif) - - `streaming.preview.commandText` contrôle les détails de commande/d’exécution dans ces lignes de progression d’outil : `raw` (par défaut, conserve le comportement publié) ou `status` (libellé d’outil uniquement) + - `streaming.preview.commandText` contrôle le détail de commande/d’exécution dans ces lignes de progression d’outil : `raw` (par défaut, préserve le comportement publié) ou `status` (étiquette d’outil uniquement) - les anciens `channels.telegram.streamMode` et valeurs booléennes `streaming` sont détectés ; exécutez `openclaw doctor --fix` pour les migrer vers `channels.telegram.streaming.mode` - Les mises à jour d’aperçu de progression d’outil sont les courtes lignes d’état affichées pendant l’exécution des outils, par exemple l’exécution de commandes, les lectures de fichiers, les mises à jour de planification ou les résumés de patch. Telegram les garde activées par défaut pour correspondre au comportement publié d’OpenClaw depuis `v2026.4.22` et versions ultérieures. Pour conserver l’aperçu modifié pour le texte de réponse mais masquer les lignes de progression d’outil, définissez : + Les mises à jour d’aperçu de progression d’outil sont les courtes lignes de statut affichées pendant l’exécution des outils, par exemple l’exécution de commandes, la lecture de fichiers, les mises à jour de planification ou les résumés de correctifs. Telegram les garde activées par défaut pour correspondre au comportement OpenClaw publié depuis `v2026.4.22` et les versions ultérieures. Pour conserver l’aperçu modifié pour le texte de réponse tout en masquant les lignes de progression d’outil, définissez : ```json { @@ -307,7 +307,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Pour garder la progression des outils visible mais masquer le texte de commande/d’exécution, définissez : + Pour garder la progression d’outil visible mais masquer le texte de commande/d’exécution, définissez : ```json { @@ -324,7 +324,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Pour le mode brouillon de progression, placez la même stratégie de texte de commande sous `streaming.progress`: + Pour le mode brouillon de progression, placez la même politique de texte de commande sous `streaming.progress` : ```json { @@ -342,26 +342,27 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Utilisez `streaming.mode: "off"` uniquement lorsque vous voulez une livraison finale uniquement: les modifications d’aperçu Telegram sont désactivées et le bavardage générique d’outil/progression est supprimé au lieu d’être envoyé comme messages d’état autonomes. Les invites d’approbation, les charges utiles multimédias et les erreurs passent toujours par la livraison finale normale. Utilisez `streaming.preview.toolProgress: false` lorsque vous voulez seulement conserver les modifications d’aperçu de réponse tout en masquant les lignes d’état de progression des outils. + Utilisez `streaming.mode: "off"` uniquement lorsque vous voulez une livraison finale seulement : les modifications d’aperçu Telegram sont désactivées et les bavardages génériques d’outil/de progression sont supprimés au lieu d’être envoyés comme messages d’état autonomes. Les invites d’approbation, les charges utiles multimédias et les erreurs passent toujours par la livraison finale normale. Utilisez `streaming.preview.toolProgress: false` lorsque vous voulez seulement conserver les modifications d’aperçu de réponse tout en masquant les lignes d’état de progression de l’outil. - Les réponses à citation sélectionnée Telegram sont l’exception. Lorsque `replyToMode` vaut `"first"`, `"all"` ou `"batched"` et que le message entrant inclut du texte de citation sélectionné, OpenClaw envoie la réponse finale via le chemin natif de réponse avec citation de Telegram au lieu de modifier l’aperçu de réponse; `streaming.preview.toolProgress` ne peut donc pas afficher les courtes lignes d’état pour ce tour. Les réponses au message courant sans texte de citation sélectionné conservent toujours le streaming d’aperçu. Définissez `replyToMode: "off"` lorsque la visibilité de la progression des outils compte davantage que les réponses natives avec citation, ou définissez `streaming.preview.toolProgress: false` pour accepter ce compromis. + Les réponses Telegram à citation sélectionnée sont l’exception. Lorsque `replyToMode` vaut `"first"`, `"all"` ou `"batched"` et que le message entrant inclut un texte de citation sélectionné, OpenClaw envoie la réponse finale via le chemin de réponse avec citation natif de Telegram au lieu de modifier l’aperçu de réponse ; `streaming.preview.toolProgress` ne peut donc pas afficher les courtes lignes d’état pour ce tour. Les réponses au message courant sans texte de citation sélectionné conservent toujours le streaming d’aperçu. Définissez `replyToMode: "off"` lorsque la visibilité de la progression des outils compte davantage que les réponses avec citation natives, ou définissez `streaming.preview.toolProgress: false` pour accepter le compromis. - Pour les réponses texte uniquement: + Pour les réponses en texte uniquement : - - aperçus courts en DM/groupe/sujet: OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place, sauf si un message visible qui n’est pas un aperçu a été envoyé après l’apparition de l’aperçu - - aperçus suivis d’une sortie visible qui n’est pas un aperçu: OpenClaw envoie la réponse terminée comme nouveau message final et nettoie l’ancien aperçu, afin que la réponse finale apparaisse après la sortie intermédiaire - - aperçus datant de plus d’environ une minute: OpenClaw envoie la réponse terminée comme nouveau message final puis nettoie l’aperçu, afin que l’horodatage visible de Telegram reflète l’heure d’achèvement plutôt que l’heure de création de l’aperçu + - aperçus courts de DM/groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place, sauf si un message visible hors aperçu a été envoyé après l’apparition de l’aperçu + - les textes finaux longs qui se divisent en plusieurs messages Telegram réutilisent si possible l’aperçu existant comme premier fragment final, puis envoient uniquement les fragments restants + - aperçus suivis d’une sortie visible hors aperçu : OpenClaw envoie la réponse terminée comme nouveau message final et nettoie l’ancien aperçu, afin que la réponse finale apparaisse après la sortie intermédiaire + - aperçus vieux d’environ plus d’une minute : OpenClaw envoie la réponse terminée comme nouveau message final puis nettoie l’aperçu, afin que l’horodatage visible de Telegram reflète l’heure d’achèvement plutôt que l’heure de création de l’aperçu Pour les réponses complexes (par exemple les charges utiles multimédias), OpenClaw revient à la livraison finale normale puis nettoie le message d’aperçu. - Le streaming d’aperçu est distinct du streaming par blocs. Lorsque le streaming par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter un double streaming. + Le streaming d’aperçu est séparé du streaming par blocs. Lorsque le streaming par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu afin d’éviter un double streaming. - Flux de raisonnement propre à Telegram: + Flux de raisonnement propre à Telegram : - - `/reasoning stream` envoie le raisonnement à l’aperçu en direct pendant la génération - - l’aperçu du raisonnement est supprimé après la livraison finale; utilisez `/reasoning on` lorsque le raisonnement doit rester visible + - `/reasoning stream` envoie le raisonnement dans l’aperçu en direct pendant la génération + - l’aperçu de raisonnement est supprimé après la livraison finale ; utilisez `/reasoning on` lorsque le raisonnement doit rester visible - la réponse finale est envoyée sans texte de raisonnement @@ -370,7 +371,7 @@ curl "https://api.telegram.org/bot/getUpdates" Le texte sortant utilise Telegram `parse_mode: "HTML"`. - Le texte de type Markdown est rendu en HTML compatible avec Telegram. - - Le HTML brut du modèle est échappé pour réduire les échecs d’analyse Telegram. + - Le HTML brut du modèle est échappé afin de réduire les échecs d’analyse Telegram. - Si Telegram rejette le HTML analysé, OpenClaw réessaie en texte brut. Les aperçus de liens sont activés par défaut et peuvent être désactivés avec `channels.telegram.linkPreview: false`. @@ -378,13 +379,13 @@ curl "https://api.telegram.org/bot/getUpdates" - L’inscription du menu de commandes Telegram est gérée au démarrage avec `setMyCommands`. + L’enregistrement du menu de commandes Telegram est géré au démarrage avec `setMyCommands`. - Valeurs par défaut des commandes natives: + Valeurs par défaut des commandes natives : - `commands.native: "auto"` active les commandes natives pour Telegram - Ajoutez des entrées de menu de commandes personnalisées: + Ajoutez des entrées de menu de commandes personnalisées : ```json5 { @@ -399,49 +400,49 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Règles: + Règles : - les noms sont normalisés (suppression du `/` initial, minuscules) - - motif valide: `a-z`, `0-9`, `_`, longueur `1..32` + - motif valide : `a-z`, `0-9`, `_`, longueur `1..32` - les commandes personnalisées ne peuvent pas remplacer les commandes natives - - les conflits/doublons sont ignorés et journalisés + - les conflits/doublons sont ignorés et consignés - Notes: + Notes : - - les commandes personnalisées ne sont que des entrées de menu; elles n’implémentent pas automatiquement un comportement - - les commandes de plugin/skill peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne sont pas affichées dans le menu Telegram + - les commandes personnalisées sont uniquement des entrées de menu ; elles n’implémentent pas automatiquement un comportement + - les commandes de Plugin/Skill peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne sont pas affichées dans le menu Telegram - Si les commandes natives sont désactivées, les commandes intégrées sont supprimées. Les commandes personnalisées/de plugin peuvent toujours s’inscrire si elles sont configurées. + Si les commandes natives sont désactivées, les commandes intégrées sont supprimées. Les commandes personnalisées/de Plugin peuvent toujours s’enregistrer si elles sont configurées. - Échecs de configuration courants: + Échecs de configuration courants : - - `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram dépassait encore la limite après réduction; réduisez les commandes de plugin/skill/personnalisées ou désactivez `channels.telegram.commands.native`. - - l’échec de `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` avec `404: Not Found` alors que les commandes curl directes de l’API Bot fonctionnent peut signifier que `channels.telegram.apiRoot` a été défini sur le point de terminaison complet `/bot`. `apiRoot` doit être uniquement la racine de l’API Bot, et `openclaw doctor --fix` supprime un suffixe accidentel `/bot`. - - `getMe returned 401` signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` avec le jeton BotFather actuel; OpenClaw s’arrête avant l’interrogation, donc ce n’est pas signalé comme un échec de nettoyage de Webhook. + - `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram débordait encore après réduction ; réduisez les commandes de Plugin/Skill/personnalisées ou désactivez `channels.telegram.commands.native`. + - l’échec de `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` avec `404: Not Found` alors que les commandes curl directes de la Bot API fonctionnent peut signifier que `channels.telegram.apiRoot` a été défini sur le point de terminaison complet `/bot`. `apiRoot` doit être uniquement la racine de la Bot API, et `openclaw doctor --fix` supprime un `/bot` final accidentel. + - `getMe returned 401` signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation, ce qui n’est donc pas signalé comme un échec de nettoyage de Webhook. - `setMyCommands failed` avec des erreurs réseau/fetch signifie généralement que le DNS/HTTPS sortant vers `api.telegram.org` est bloqué. - ### Commandes d’association d’appareil (plugin `device-pair`) + ### Commandes d’appairage d’appareil (Plugin `device-pair`) - Lorsque le plugin `device-pair` est installé: + Lorsque le Plugin `device-pair` est installé : 1. `/pair` génère le code de configuration 2. collez le code dans l’application iOS 3. `/pair pending` liste les demandes en attente (y compris rôle/portées) - 4. approuvez la demande: + 4. approuvez la demande : - `/pair approve ` pour une approbation explicite - `/pair approve` lorsqu’il n’y a qu’une seule demande en attente - `/pair approve latest` pour la plus récente - Le code de configuration transporte un jeton d’amorçage de courte durée. Le transfert d’amorçage intégré conserve le jeton du nœud principal à `scopes: []`; tout jeton d’opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de portée d’amorçage sont préfixées par rôle, donc cette liste d’autorisation d’opérateur ne satisfait que les demandes d’opérateur; les rôles non opérateurs ont toujours besoin de portées sous leur propre préfixe de rôle. + Le code de configuration transporte un jeton d’amorçage à courte durée de vie. Le transfert d’amorçage intégré conserve le jeton du nœud principal à `scopes: []` ; tout jeton opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de portée d’amorçage sont préfixées par rôle ; cette liste d’autorisation d’opérateur ne satisfait donc que les demandes d’opérateur, et les rôles non opérateurs ont toujours besoin de portées sous leur propre préfixe de rôle. - Si un appareil réessaie avec des détails d’authentification modifiés (par exemple rôle/portées/clé publique), la demande précédente en attente est remplacée et la nouvelle demande utilise un autre `requestId`. Relancez `/pair pending` avant d’approuver. + Si un appareil réessaie avec des détails d’authentification modifiés (par exemple rôle/portées/clé publique), la demande précédente en attente est remplacée et la nouvelle demande utilise un `requestId` différent. Relancez `/pair pending` avant d’approuver. - Plus de détails: [Association](/fr/channels/pairing#pair-via-telegram-recommended-for-ios). + Plus de détails : [Appairage](/fr/channels/pairing#pair-via-telegram-recommended-for-ios). - - Configurez la portée du clavier intégré: + + Configurez la portée du clavier en ligne : ```json5 { @@ -455,7 +456,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Remplacement par compte: + Remplacement par compte : ```json5 { @@ -473,7 +474,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Portées: + Portées : - `off` - `dm` @@ -483,7 +484,7 @@ curl "https://api.telegram.org/bot/getUpdates" L’ancien `capabilities: ["inlineButtons"]` correspond à `inlineButtons: "all"`. - Exemple d’action de message: + Exemple d’action de message : ```json5 { @@ -501,71 +502,71 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Les clics de rappel sont transmis à l’agent comme texte: + Les clics de rappel sont transmis à l’agent sous forme de texte : `callback_data: ` - - Les actions d’outil Telegram incluent: + + Les actions d’outil Telegram incluent : - - `sendMessage` (`to`, `content`, optionnel `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `sendMessage` (`to`, `content`, `mediaUrl` facultatif, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, optionnel `iconColor`, `iconCustomEmojiId`) + - `createForumTopic` (`chatId`, `name`, `iconColor` facultatif, `iconCustomEmojiId`) Les actions de message de canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Contrôles de garde: + Contrôles de verrouillage : - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - - `channels.telegram.actions.sticker` (par défaut: désactivé) + - `channels.telegram.actions.sticker` (par défaut : désactivé) - Note: `edit` et `topic-create` sont actuellement activés par défaut et n’ont pas de bascules `channels.telegram.actions.*` séparées. - Les envois à l’exécution utilisent l’instantané actif de configuration/secrets (démarrage/rechargement), donc les chemins d’action ne réévaluent pas les SecretRef ad hoc à chaque envoi. + Remarque : `edit` et `topic-create` sont actuellement activés par défaut et n’ont pas de bascules `channels.telegram.actions.*` séparées. + Les envois à l’exécution utilisent l’instantané actif de configuration/secrets (démarrage/rechargement), les chemins d’action ne réeffectuent donc pas de résolution SecretRef ad hoc à chaque envoi. - Sémantique de suppression des réactions: [/tools/reactions](/fr/tools/reactions) + Sémantique de suppression des réactions : [/tools/reactions](/fr/tools/reactions) - - Telegram prend en charge les balises explicites de fil de réponse dans la sortie générée: + + Telegram prend en charge des balises explicites de fil de réponse dans la sortie générée : - `[[reply_to_current]]` répond au message déclencheur - `[[reply_to:]]` répond à un ID de message Telegram spécifique - `channels.telegram.replyToMode` contrôle la gestion: + `channels.telegram.replyToMode` contrôle la gestion : - `off` (par défaut) - `first` - `all` - Lorsque le fil de réponse est activé et que le texte ou la légende Telegram d’origine est disponible, OpenClaw inclut automatiquement un extrait de citation natif Telegram. Telegram limite le texte de citation natif à 1024 unités de code UTF-16; les messages plus longs sont donc cités depuis le début et reviennent à une réponse simple si Telegram rejette la citation. + Lorsque le fil de réponse est activé et que le texte ou la légende Telegram d’origine est disponible, OpenClaw inclut automatiquement un extrait de citation Telegram natif. Telegram limite le texte de citation natif à 1024 unités de code UTF-16 ; les messages plus longs sont donc cités depuis le début et reviennent à une réponse simple si Telegram rejette la citation. - Note: `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` sont toujours respectées. + Remarque : `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` sont toujours honorées. - Supergroupes de forum: + Supergroupes de forum : - les clés de session de sujet ajoutent `:topic:` - - les réponses et l’indication de saisie ciblent le fil du sujet - - chemin de configuration du sujet: + - les réponses et la saisie ciblent le fil du sujet + - chemin de configuration du sujet : `channels.telegram.groups..topics.` - Cas particulier du sujet général (`threadId=1`): + Cas particulier du sujet général (`threadId=1`) : - les envois de message omettent `message_thread_id` (Telegram rejette `sendMessage(...thread_id=1)`) - les actions de saisie incluent toujours `message_thread_id` - Héritage de sujet: les entrées de sujet héritent des paramètres de groupe sauf remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + Héritage de sujet : les entrées de sujet héritent des paramètres de groupe sauf remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` est propre au sujet et n’hérite pas des valeurs par défaut du groupe. - **Routage d’agent par sujet**: chaque sujet peut router vers un agent différent en définissant `agentId` dans la configuration du sujet. Cela donne à chaque sujet son propre espace de travail, sa propre mémoire et sa propre session isolés. Exemple: + **Routage d’agent par sujet** : Chaque sujet peut être routé vers un agent différent en définissant `agentId` dans la configuration du sujet. Cela donne à chaque sujet son propre espace de travail, sa mémoire et sa session isolés. Exemple : ```json5 { @@ -585,13 +586,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Chaque sujet a ensuite sa propre clé de session: `agent:zu:telegram:group:-1001234567890:topic:3` + Chaque sujet possède alors sa propre clé de session : `agent:zu:telegram:group:-1001234567890:topic:3` - **Liaison persistante de sujet ACP**: les sujets de forum peuvent épingler les sessions de harnais ACP au moyen de liaisons ACP typées de premier niveau (`bindings[]` avec `type: "acp"` et `match.channel: "telegram"`, `peer.kind: "group"`, et un id qualifié par sujet comme `-1001234567890:topic:42`). Actuellement limité aux sujets de forum dans les groupes/supergroupes. Consultez [Agents ACP](/fr/tools/acp-agents). + **Liaison persistante de sujet ACP** : Les sujets de forum peuvent épingler les sessions de harnais ACP via des liaisons ACP typées de niveau supérieur (`bindings[]` avec `type: "acp"` et `match.channel: "telegram"`, `peer.kind: "group"` et un identifiant qualifié par sujet comme `-1001234567890:topic:42`). Actuellement limité aux sujets de forum dans les groupes/supergroupes. Voir [Agents ACP](/fr/tools/acp-agents). - **Création ACP liée au fil depuis la discussion**: `/acp spawn --thread here|auto` lie le sujet courant à une nouvelle session ACP; les messages suivants y sont routés directement. OpenClaw épingle la confirmation de création dans le sujet. Nécessite que `channels.telegram.threadBindings.spawnSessions` reste activé (par défaut: `true`). + **Création ACP liée au fil depuis le chat** : `/acp spawn --thread here|auto` lie le sujet actuel à une nouvelle session ACP ; les suivis y sont routés directement. OpenClaw épingle la confirmation de création dans le sujet. Nécessite que `channels.telegram.threadBindings.spawnSessions` reste activé (par défaut : `true`). - Le contexte du modèle expose `MessageThreadId` et `IsForum`. Les discussions en DM avec `message_thread_id` conservent par défaut le routage DM et les métadonnées de réponse sur des sessions plates ; elles n’utilisent des clés de session tenant compte des fils que lorsqu’elles sont configurées avec `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true`, ou une configuration de sujet correspondante. Utilisez `channels.telegram.dm.threadReplies` au niveau supérieur pour la valeur par défaut du compte, ou `direct..threadReplies` pour un DM. + Le contexte du modèle expose `MessageThreadId` et `IsForum`. Les conversations DM avec `message_thread_id` conservent par défaut le routage DM et les métadonnées de réponse sur les sessions plates ; elles n’utilisent des clés de session tenant compte des fils que lorsqu’elles sont configurées avec `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true`, ou une configuration de sujet correspondante. Utilisez `channels.telegram.dm.threadReplies` au niveau supérieur pour la valeur par défaut du compte, ou `direct..threadReplies` pour un DM. @@ -601,10 +602,10 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram distingue les notes vocales des fichiers audio. - par défaut : comportement de fichier audio - - balise `[[audio_as_voice]]` dans la réponse de l’agent pour forcer l’envoi en note vocale + - balise `[[audio_as_voice]]` dans la réponse de l’agent pour forcer l’envoi d’une note vocale - les transcriptions de notes vocales entrantes sont encadrées comme du texte généré par machine, - non fiable dans le contexte de l’agent ; la détection des mentions utilise toujours la - transcription brute afin que les messages vocaux soumis à mention continuent de fonctionner. + non fiable, dans le contexte de l’agent ; la détection de mention utilise toujours la transcription + brute, de sorte que les messages vocaux soumis à mention continuent de fonctionner. Exemple d’action de message : @@ -644,7 +645,7 @@ curl "https://api.telegram.org/bot/getUpdates" - TGS animé : ignoré - WEBM vidéo : ignoré - Champs de contexte de sticker : + Champs de contexte des stickers : - `Sticker.emoji` - `Sticker.setName` @@ -656,7 +657,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Les stickers sont décrits une fois (lorsque possible) et mis en cache afin de réduire les appels de vision répétés. + Les stickers sont décrits une fois (lorsque c’est possible) et mis en cache afin de réduire les appels de vision répétés. Activer les actions de sticker : @@ -672,7 +673,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Action d’envoi de sticker : + Envoyer une action de sticker : ```json5 { @@ -683,7 +684,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Rechercher des stickers en cache : + Rechercher des stickers mis en cache : ```json5 { @@ -697,47 +698,47 @@ curl "https://api.telegram.org/bot/getUpdates" - Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (séparées des charges utiles de message). + Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (séparées des payloads de message). - Lorsqu’elles sont activées, OpenClaw met en file des événements système comme : + Lorsqu’elles sont activées, OpenClaw met en file d’attente des événements système comme : - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` - Configuration : + Config : - - `channels.telegram.reactionNotifications` : `off | own | all` (par défaut : `own`) - - `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` (par défaut : `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all` (par défaut : `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (par défaut : `minimal`) Notes : - - `own` signifie uniquement les réactions utilisateur aux messages envoyés par le bot (au mieux via le cache des messages envoyés). + - `own` signifie uniquement les réactions des utilisateurs aux messages envoyés par le bot (au mieux, via le cache des messages envoyés). - Les événements de réaction respectent toujours les contrôles d’accès Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`) ; les expéditeurs non autorisés sont ignorés. - Telegram ne fournit pas d’ID de fil dans les mises à jour de réaction. - - les groupes non-forum sont routés vers la session de discussion de groupe - - les groupes forum sont routés vers la session du sujet général du groupe (`:topic:1`), et non vers le sujet d’origine exact + - les groupes non-forum sont routés vers la session de discussion du groupe + - les groupes de forum sont routés vers la session du sujet général du groupe (`:topic:1`), et non vers le sujet d’origine exact - `allowed_updates` pour le polling/Webhook inclut automatiquement `message_reaction`. + `allowed_updates` pour le polling/webhook inclut automatiquement `message_reaction`. - `ackReaction` envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant. + `ackReaction` envoie un émoji d’accusé de réception pendant qu’OpenClaw traite un message entrant. Ordre de résolution : - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - solution de secours avec l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀") + - repli sur l’émoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀") Notes : - - Telegram attend un emoji unicode (par exemple "👀"). + - Telegram attend un émoji unicode (par exemple "👀"). - Utilisez `""` pour désactiver la réaction pour un canal ou un compte. - + Les écritures de configuration de canal sont activées par défaut (`configWrites !== false`). Les écritures déclenchées par Telegram incluent : @@ -759,32 +760,32 @@ curl "https://api.telegram.org/bot/getUpdates" - - La valeur par défaut est le long polling. Pour le mode Webhook, définissez `channels.telegram.webhookUrl` et `channels.telegram.webhookSecret` ; `webhookPath`, `webhookHost`, `webhookPort` sont facultatifs (valeurs par défaut `/telegram-webhook`, `127.0.0.1`, `8787`). + + Le comportement par défaut est le long polling. Pour le mode webhook, définissez `channels.telegram.webhookUrl` et `channels.telegram.webhookSecret` ; `webhookPath`, `webhookHost`, `webhookPort` sont facultatifs (valeurs par défaut : `/telegram-webhook`, `127.0.0.1`, `8787`). - L’écouteur local se lie à `127.0.0.1:8787`. Pour une entrée publique, placez soit un proxy inverse devant le port local, soit définissez intentionnellement `webhookHost: "0.0.0.0"`. + L’écouteur local se lie à `127.0.0.1:8787`. Pour une entrée publique, placez un proxy inverse devant le port local ou définissez intentionnellement `webhookHost: "0.0.0.0"`. - Le mode Webhook valide les protections de requête, le jeton secret Telegram et le corps JSON avant de renvoyer `200` à Telegram. - OpenClaw traite ensuite la mise à jour de manière asynchrone via les mêmes files bot par discussion/par sujet que celles utilisées par le long polling, de sorte que les tours d’agent lents ne bloquent pas l’ACK de livraison de Telegram. + Le mode webhook valide les gardes de requête, le jeton secret Telegram et le corps JSON avant de retourner `200` à Telegram. + OpenClaw traite ensuite la mise à jour de manière asynchrone via les mêmes voies de bot par discussion/par sujet que celles utilisées par le long polling, de sorte que les tours d’agent lents ne bloquent pas l’ACK de livraison de Telegram. - - La valeur par défaut de `channels.telegram.textChunkLimit` est 4000. - - `channels.telegram.chunkMode="newline"` privilégie les limites de paragraphes (lignes vides) avant le découpage par longueur. - - `channels.telegram.mediaMaxMb` (par défaut 100) limite la taille des médias Telegram entrants et sortants. - - `channels.telegram.mediaGroupFlushMs` (par défaut 500) contrôle la durée pendant laquelle les albums/groupes de médias Telegram sont mis en tampon avant qu’OpenClaw les envoie comme un seul message entrant. Augmentez-la si les parties d’album arrivent tard ; diminuez-la pour réduire la latence de réponse aux albums. - - `channels.telegram.timeoutSeconds` remplace le délai d’expiration du client API Telegram (si non défini, la valeur par défaut de grammY s’applique). Les clients bot bornent les valeurs configurées sous la protection de 60 secondes des requêtes de texte/saisie sortantes afin que grammY n’interrompe pas la livraison visible des réponses avant que la protection de transport et la solution de secours d’OpenClaw puissent s’exécuter. Le long polling utilise toujours une protection de requête `getUpdates` de 45 secondes afin que les polls inactifs ne soient pas abandonnés indéfiniment. - - `channels.telegram.pollingStallThresholdMs` vaut `120000` par défaut ; réglez-la entre `30000` et `600000` uniquement pour les redémarrages de polling bloqué faussement positifs. - - l’historique de contexte de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (par défaut 50) ; `0` le désactive. - - le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel que reçu. - - les listes d’autorisation Telegram contrôlent principalement qui peut déclencher l’agent, et ne constituent pas une frontière complète de caviardage du contexte supplémentaire. - - Contrôles de l’historique des DM : + - `channels.telegram.textChunkLimit` vaut 4000 par défaut. + - `channels.telegram.chunkMode="newline"` privilégie les limites de paragraphe (lignes vides) avant le découpage par longueur. + - `channels.telegram.mediaMaxMb` (par défaut 100) plafonne la taille des médias Telegram entrants et sortants. + - `channels.telegram.mediaGroupFlushMs` (par défaut 500) contrôle la durée pendant laquelle les albums/groupes de médias Telegram sont mis en mémoire tampon avant qu’OpenClaw ne les distribue comme un seul message entrant. Augmentez cette valeur si les parties d’album arrivent tard ; réduisez-la pour diminuer la latence de réponse aux albums. + - `channels.telegram.timeoutSeconds` remplace le délai d’expiration du client API Telegram (si non défini, la valeur par défaut de grammY s’applique). Les clients bot limitent les valeurs configurées sous le garde de requête de texte/saisie sortante de 60 secondes, afin que grammY n’interrompe pas la livraison visible de la réponse avant que le garde de transport et le repli d’OpenClaw puissent s’exécuter. Le long polling utilise toujours un garde de requête `getUpdates` de 45 secondes afin que les polls inactifs ne soient pas abandonnés indéfiniment. + - `channels.telegram.pollingStallThresholdMs` vaut par défaut `120000` ; ajustez entre `30000` et `600000` uniquement pour les redémarrages de polling bloqué faux positifs. + - l’historique du contexte de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (par défaut 50) ; `0` le désactive. + - le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel qu’il est reçu. + - les listes d’autorisation Telegram contrôlent principalement qui peut déclencher l’agent, et non une frontière complète de caviardage du contexte supplémentaire. + - Contrôles de l’historique DM : - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - La configuration `channels.telegram.retry` s’applique aux assistants d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de réponse finale entrante utilise aussi une nouvelle tentative d’envoi sécurisé bornée pour les échecs Telegram avant connexion, mais elle ne retente pas les enveloppes réseau ambiguës après envoi qui pourraient dupliquer des messages visibles. + - La config `channels.telegram.retry` s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de réponse finale entrante utilise également une nouvelle tentative d’envoi sûr bornée pour les échecs Telegram avant connexion, mais elle ne réessaie pas les enveloppes réseau ambiguës après envoi qui pourraient dupliquer les messages visibles. - Les cibles d’envoi CLI et d’outil de message peuvent être un ID de discussion numérique, un nom d’utilisateur, ou une cible de sujet forum : + Les cibles d’envoi CLI et d’outil de message peuvent être un ID de discussion numérique, un nom d’utilisateur ou une cible de sujet de forum : ```bash openclaw message send --channel telegram --target 123456789 --message "hi" @@ -792,7 +793,7 @@ openclaw message send --channel telegram --target @name --message "hi" openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic" ``` - Les polls Telegram utilisent `openclaw message poll` et prennent en charge les sujets forum : + Les polls Telegram utilisent `openclaw message poll` et prennent en charge les sujets de forum : ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -802,18 +803,18 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Indicateurs de poll propres à Telegram : + Flags de poll propres à Telegram : - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` pour les sujets forum (ou utilisez une cible `:topic:`) + - `--thread-id` pour les sujets de forum (ou utilisez une cible `:topic:`) - L’envoi Telegram prend aussi en charge : + L’envoi Telegram prend également en charge : - - `--presentation` avec des blocs `buttons` pour les claviers inline lorsque `channels.telegram.capabilities.inlineButtons` l’autorise + - `--presentation` avec des blocs `buttons` pour les claviers en ligne lorsque `channels.telegram.capabilities.inlineButtons` l’autorise - `--pin` ou `--delivery '{"pin":true}'` pour demander une livraison épinglée lorsque le bot peut épingler dans cette discussion - - `--force-document` pour envoyer les images et GIF sortants comme documents plutôt que comme photos compressées ou téléversements de médias animés + - `--force-document` pour envoyer les images sortantes et les GIF comme documents plutôt que comme photos compressées ou téléversements de médias animés Contrôle des actions : @@ -823,20 +824,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Telegram prend en charge les approbations exec dans les DM des approbateurs et peut facultativement publier les prompts dans la discussion ou le sujet d’origine. Les approbateurs doivent être des ID utilisateur Telegram numériques. + Telegram prend en charge les approbations exec dans les DM des approbateurs et peut éventuellement publier des invites dans la discussion ou le sujet d’origine. Les approbateurs doivent être des ID d’utilisateur Telegram numériques. - Chemin de configuration : + Chemin de config : - `channels.telegram.execApprovals.enabled` (s’active automatiquement lorsqu’au moins un approbateur peut être résolu) - - `channels.telegram.execApprovals.approvers` (revient aux ID propriétaires numériques de `commands.ownerAllowFrom`) - - `channels.telegram.execApprovals.target` : `dm` (par défaut) | `channel` | `both` + - `channels.telegram.execApprovals.approvers` (se rabat sur les ID propriétaires numériques depuis `commands.ownerAllowFrom`) + - `channels.telegram.execApprovals.target`: `dm` (par défaut) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom` et `defaultTo` contrôlent qui peut parler au bot et où il envoie les réponses normales. Ils ne font pas de quelqu’un un approbateur exec. Le premier appairage DM approuvé initialise `commands.ownerAllowFrom` lorsqu’aucun propriétaire de commande n’existe encore, de sorte que la configuration à propriétaire unique fonctionne toujours sans dupliquer les ID sous `execApprovals.approvers`. + `channels.telegram.allowFrom`, `groupAllowFrom` et `defaultTo` contrôlent qui peut parler au bot et où il envoie les réponses normales. Ils ne font pas de quelqu’un un approbateur exec. Le premier appairage DM approuvé amorce `commands.ownerAllowFrom` lorsqu’aucun propriétaire de commande n’existe encore, de sorte que la configuration à propriétaire unique fonctionne toujours sans dupliquer les ID sous `execApprovals.approvers`. - La livraison au canal affiche le texte de la commande dans la discussion ; n’activez `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque le prompt arrive dans un sujet forum, OpenClaw conserve le sujet pour le prompt d’approbation et le suivi. Les approbations exec expirent par défaut après 30 minutes. + La livraison au canal affiche le texte de la commande dans la discussion ; n’activez `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw conserve le sujet pour l’invite d’approbation et le suivi. Les approbations exec expirent au bout de 30 minutes par défaut. - Les boutons d’approbation inline nécessitent aussi que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`). Les ID d’approbation préfixés par `plugin:` sont résolus via les approbations de plugin ; les autres sont d’abord résolus via les approbations exec. + Les boutons d’approbation en ligne exigent également que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`). Les ID d’approbation préfixés par `plugin:` sont résolus via les approbations de plugins ; les autres sont d’abord résolus via les approbations exec. Voir [Approbations exec](/fr/tools/exec-approvals). @@ -845,14 +846,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## Contrôles des réponses d’erreur -Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut soit répondre avec le texte de l’erreur, soit le supprimer. Deux clés de configuration contrôlent ce comportement : +Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut soit répondre avec le texte de l’erreur, soit le supprimer. Deux clés de config contrôlent ce comportement : -| Clé | Valeurs | Par défaut | Description | -| ----------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial dans la discussion. `silent` supprime entièrement les réponses d’erreur. | -| `channels.telegram.errorCooldownMs` | nombre (ms) | `60000` | Temps minimal entre les réponses d’erreur à la même discussion. Empêche le spam d’erreurs pendant les pannes. | +| Clé | Valeurs | Par défaut | Description | +| ----------------------------------- | ----------------- | ---------- | -------------------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial à la discussion. `silent` supprime entièrement les réponses d’erreur. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Temps minimal entre les réponses d’erreur à la même discussion. Empêche le spam d’erreurs pendant les interruptions. | -Les remplacements par compte, par groupe et par sujet sont pris en charge (même héritage que les autres clés de configuration Telegram). +Les remplacements par compte, par groupe et par sujet sont pris en charge (même héritage que les autres clés de config Telegram). ```json5 { @@ -875,11 +876,11 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même - - Si `requireMention=false`, le mode de confidentialité de Telegram doit autoriser une visibilité complète. - - BotFather : `/setprivacy` -> Disable - - puis supprimez et ajoutez de nouveau le bot au groupe - - `openclaw channels status` avertit quand la configuration attend des messages de groupe sans mention. - - `openclaw channels status --probe` peut vérifier les ID de groupe numériques explicites ; le caractère générique `"*"` ne peut pas faire l’objet d’une vérification d’appartenance. + - Si `requireMention=false`, le mode confidentialité de Telegram doit permettre une visibilité complète. + - BotFather : `/setprivacy` -> Désactiver + - puis supprimez et rajoutez le bot au groupe + - `openclaw channels status` avertit lorsque la configuration attend des messages de groupe sans mention. + - `openclaw channels status --probe` peut vérifier les identifiants numériques explicites de groupes ; le joker `"*"` ne peut pas faire l'objet d'une vérification d'appartenance. - test rapide de session : `/activation always`. @@ -887,42 +888,42 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même - lorsque `channels.telegram.groups` existe, le groupe doit être listé (ou inclure `"*"`) - - vérifiez l’appartenance du bot au groupe - - consultez les journaux : `openclaw logs --follow` pour connaître les raisons de l’ignorance + - vérifiez l'appartenance du bot au groupe + - consultez les journaux : `openclaw logs --follow` pour les raisons d'omission - - autorisez votre identité d’expéditeur (jumelage et/ou `allowFrom` numérique) - - l’autorisation des commandes s’applique toujours même lorsque la stratégie de groupe est `open` - - `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif contient trop d’entrées ; réduisez les commandes Plugin/Skills/personnalisées ou désactivez les menus natifs - - les appels de démarrage `deleteMyCommands` / `setMyCommands` et les appels de saisie `sendChatAction` sont bornés et réessayés une fois via le repli de transport de Telegram en cas d’expiration de la requête. Les erreurs réseau/fetch persistantes indiquent généralement des problèmes de joignabilité DNS/HTTPS vers `api.telegram.org` + - autorisez l'identité de votre expéditeur (appariement et/ou `allowFrom` numérique) + - l'autorisation des commandes s'applique toujours même lorsque la stratégie de groupe est `open` + - `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif comporte trop d'entrées ; réduisez les commandes de Plugin/Skills/personnalisées ou désactivez les menus natifs + - les appels de démarrage `deleteMyCommands` / `setMyCommands` et les appels de saisie `sendChatAction` sont bornés et réessayés une fois via le repli de transport de Telegram en cas d'expiration de requête. Les erreurs réseau/fetch persistantes indiquent généralement des problèmes d'accessibilité DNS/HTTPS vers `api.telegram.org` - - `getMe returned 401` est un échec d’authentification Telegram pour le jeton de bot configuré. - - Recopiez ou régénérez le jeton du bot dans BotFather, puis mettez à jour `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` ou `TELEGRAM_BOT_TOKEN` pour le compte par défaut. - - `deleteWebhook 401 Unauthorized` pendant le démarrage est également un échec d’authentification ; le traiter comme « aucun Webhook n’existe » ne ferait que reporter le même échec de mauvais jeton aux appels API ultérieurs. + - `getMe returned 401` est un échec d'authentification Telegram pour le jeton de bot configuré. + - Recopiez ou régénérez le jeton de bot dans BotFather, puis mettez à jour `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` ou `TELEGRAM_BOT_TOKEN` pour le compte par défaut. + - `deleteWebhook 401 Unauthorized` pendant le démarrage est aussi un échec d'authentification ; le traiter comme « aucun webhook n'existe » ne ferait que reporter le même échec de mauvais jeton à des appels API ultérieurs. - + - - Node 22+ + un fetch/proxy personnalisé peuvent déclencher un comportement d’abandon immédiat si les types AbortSignal ne correspondent pas. - - Certains hôtes résolvent d’abord `api.telegram.org` en IPv6 ; une sortie IPv6 défectueuse peut provoquer des échecs intermittents de l’API Telegram. + - Node 22+ + fetch/proxy personnalisé peuvent déclencher un comportement d'abandon immédiat si les types AbortSignal ne correspondent pas. + - Certains hôtes résolvent d'abord `api.telegram.org` en IPv6 ; une sortie IPv6 défaillante peut provoquer des échecs intermittents de l'API Telegram. - Si les journaux incluent `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, OpenClaw réessaie désormais ces erreurs comme des erreurs réseau récupérables. - - Pendant le démarrage du polling, OpenClaw réutilise la sonde `getMe` de démarrage réussie pour grammY afin que le runner n’ait pas besoin d’un second `getMe` avant le premier `getUpdates`. - - Si `deleteWebhook` échoue avec une erreur réseau transitoire pendant le démarrage du polling, OpenClaw continue en long polling au lieu d’effectuer un autre appel de plan de contrôle avant le polling. Un Webhook encore actif apparaît comme un conflit `getUpdates` ; OpenClaw reconstruit alors le transport Telegram et réessaie le nettoyage du Webhook. - - Si les sockets Telegram se recyclent selon une cadence fixe courte, vérifiez si `channels.telegram.timeoutSeconds` est bas ; les clients de bot plafonnent les valeurs configurées sous les protections des requêtes sortantes et `getUpdates`, mais les anciennes versions pouvaient interrompre chaque polling ou réponse lorsque cette valeur était définie sous ces protections. - - Si les journaux incluent `Polling stall detected`, OpenClaw redémarre le polling et reconstruit le transport Telegram après 120 secondes sans liveness de long polling terminé par défaut. - - `openclaw channels status --probe` et `openclaw doctor` avertissent lorsqu’un compte en polling actif n’a pas terminé `getUpdates` après la période de grâce de démarrage, lorsqu’un compte Webhook actif n’a pas terminé `setWebhook` après la période de grâce de démarrage, ou lorsque la dernière activité réussie du transport de polling est obsolète. - - N’augmentez `channels.telegram.pollingStallThresholdMs` que lorsque les appels `getUpdates` de longue durée sont sains mais que votre hôte signale encore à tort des redémarrages pour blocage du polling. Les blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou sortie TLS entre l’hôte et `api.telegram.org`. - - Telegram respecte également les variables d’environnement de proxy du processus pour le transport de l’API Bot, y compris `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` et leurs variantes en minuscules. `NO_PROXY` / `no_proxy` peuvent toujours contourner `api.telegram.org`. - - Si le proxy géré par OpenClaw est configuré via `OPENCLAW_PROXY_URL` pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise aussi cette URL pour le transport de l’API Bot. - - Sur les hôtes VPS avec une sortie directe/TLS instable, routez les appels de l’API Telegram via `channels.telegram.proxy` : + - Pendant le démarrage du polling, OpenClaw réutilise la sonde `getMe` de démarrage réussie pour grammY afin que l'exécuteur n'ait pas besoin d'un second `getMe` avant le premier `getUpdates`. + - Si `deleteWebhook` échoue avec une erreur réseau transitoire pendant le démarrage du polling, OpenClaw poursuit en long polling au lieu d'effectuer un autre appel de plan de contrôle avant polling. Un webhook encore actif apparaît comme un conflit `getUpdates` ; OpenClaw reconstruit alors le transport Telegram et réessaie le nettoyage du webhook. + - Si les sockets Telegram sont recyclées selon une cadence fixe courte, vérifiez si `channels.telegram.timeoutSeconds` est faible ; les clients de bot bornent les valeurs configurées sous les gardes des requêtes sortantes et `getUpdates`, mais les anciennes versions pouvaient abandonner chaque polling ou réponse lorsque cette valeur était définie sous ces gardes. + - Si les journaux incluent `Polling stall detected`, OpenClaw redémarre le polling et reconstruit le transport Telegram après 120 secondes sans vivacité de long polling terminée par défaut. + - `openclaw channels status --probe` et `openclaw doctor` avertissent lorsqu'un compte de polling en cours d'exécution n'a pas terminé `getUpdates` après le délai de grâce de démarrage, lorsqu'un compte webhook en cours d'exécution n'a pas terminé `setWebhook` après le délai de grâce de démarrage, ou lorsque la dernière activité réussie du transport de polling est obsolète. + - Augmentez `channels.telegram.pollingStallThresholdMs` uniquement lorsque les appels `getUpdates` longue durée sont sains mais que votre hôte signale encore de faux redémarrages pour blocage de polling. Les blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou sortie TLS entre l'hôte et `api.telegram.org`. + - Telegram respecte également les variables d'environnement de proxy du processus pour le transport de l'API Bot, notamment `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` et leurs variantes en minuscules. `NO_PROXY` / `no_proxy` peuvent toujours contourner `api.telegram.org`. + - Si le proxy géré par OpenClaw est configuré via `OPENCLAW_PROXY_URL` pour un environnement de service et qu'aucune variable d'environnement de proxy standard n'est présente, Telegram utilise aussi cette URL pour le transport de l'API Bot. + - Sur les hôtes VPS avec une sortie directe/TLS instable, acheminez les appels à l'API Telegram via `channels.telegram.proxy` : ```yaml channels: @@ -930,8 +931,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ utilise par défaut `autoSelectFamily=true` (sauf WSL2). L’ordre des résultats DNS de Telegram respecte `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, puis `channels.telegram.network.dnsResultOrder`, puis la valeur par défaut du processus comme `NODE_OPTIONS=--dns-result-order=ipv4first` ; si rien ne s’applique, Node 22+ revient à `ipv4first`. - - Si votre hôte est WSL2 ou fonctionne explicitement mieux avec un comportement IPv4 uniquement, forcez la sélection de famille : + - Node 22+ utilise par défaut `autoSelectFamily=true` (sauf WSL2). L'ordre des résultats DNS Telegram respecte `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, puis `channels.telegram.network.dnsResultOrder`, puis la valeur par défaut du processus comme `NODE_OPTIONS=--dns-result-order=ipv4first` ; si aucun ne s'applique, Node 22+ se replie sur `ipv4first`. + - Si votre hôte est WSL2 ou fonctionne explicitement mieux avec un comportement IPv4 seul, forcez la sélection de famille : ```yaml channels: @@ -940,11 +941,11 @@ channels: autoSelectFamily: false ``` - - Les réponses de plage de benchmark RFC 2544 (`198.18.0.0/15`) sont déjà autorisées - par défaut pour les téléchargements de médias Telegram. Si un proxy fake-IP ou - transparent de confiance réécrit `api.telegram.org` vers une autre - adresse privée/interne/à usage spécial pendant les téléchargements de médias, vous pouvez - activer le contournement propre à Telegram : + - Les réponses de plage de banc d'essai RFC 2544 (`198.18.0.0/15`) sont déjà autorisées + par défaut pour les téléchargements de médias Telegram. Si un faux IP fiable ou + un proxy transparent réécrit `api.telegram.org` vers une autre adresse + privée/interne/à usage spécial pendant les téléchargements de médias, vous pouvez + activer le contournement limité à Telegram : ```yaml channels: @@ -955,19 +956,19 @@ channels: - La même activation est disponible par compte à `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Si votre proxy résout les hôtes de médias Telegram en `198.18.x.x`, laissez d’abord le - drapeau dangereux désactivé. Les médias Telegram autorisent déjà par défaut la plage de - benchmark RFC 2544. + - Si votre proxy résout les hôtes de médias Telegram en `198.18.x.x`, laissez d'abord + l'indicateur dangereux désactivé. Les médias Telegram autorisent déjà la plage + de banc d'essai RFC 2544 par défaut. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections SSRF - des médias Telegram. Utilisez-le uniquement pour des environnements de proxy contrôlés par un opérateur - de confiance, tels que le routage fake-IP de Clash, Mihomo ou Surge, lorsqu’ils - synthétisent des réponses privées ou à usage spécial en dehors de la plage de benchmark - RFC 2544. Laissez-le désactivé pour un accès Telegram normal via l’internet public. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections + SSRF des médias Telegram. Utilisez-le uniquement pour les environnements de proxy + fiables contrôlés par l'opérateur comme Clash, Mihomo ou le routage faux IP de Surge lorsqu'ils + synthétisent des réponses privées ou à usage spécial hors de la plage de banc d'essai + RFC 2544. Laissez-le désactivé pour un accès Telegram normal à l'internet public. - - Remplacements d’environnement (temporaires) : + - Surcharges d'environnement (temporaires) : - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -981,24 +982,24 @@ dig +short api.telegram.org AAAA -Aide supplémentaire : [Dépannage des canaux](/fr/channels/troubleshooting). +Plus d'aide : [Dépannage des canaux](/fr/channels/troubleshooting). ## Référence de configuration Référence principale : [Référence de configuration - Telegram](/fr/gateway/config-channels#telegram). - + -- démarrage/authentification : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier standard ; les liens symboliques sont rejetés) -- contrôle d’accès : `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de premier niveau (`type: "acp"`) -- approbations d’exécution : `execApprovals`, `accounts.*.execApprovals` +- démarrage/authentification : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier normal ; les liens symboliques sont rejetés) +- contrôle d'accès : `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de niveau supérieur (`type: "acp"`) +- approbations d'exécution : `execApprovals`, `accounts.*.execApprovals` - commande/menu : `commands.native`, `commands.nativeSkills`, `customCommands` - fils/réponses : `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies` - streaming : `streaming` (aperçu), `streaming.preview.toolProgress`, `blockStreaming` -- formatage/livraison : `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- mise en forme/livraison : `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - médias/réseau : `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- racine d’API personnalisée : `apiRoot` (racine de l’API Bot uniquement ; n’incluez pas `/bot`) -- Webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- racine d'API personnalisée : `apiRoot` (racine de l'API Bot uniquement ; n'incluez pas `/bot`) +- webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - actions/capacités : `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - réactions : `reactionNotifications`, `reactionLevel` - erreurs : `errorPolicy`, `errorCooldownMs` @@ -1007,26 +1008,26 @@ Référence principale : [Référence de configuration - Telegram](/fr/gateway/c -Priorité multi-compte : lorsque deux ID de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) pour rendre le routage par défaut explicite. Sinon, OpenClaw revient au premier ID de compte normalisé et `openclaw doctor` émet un avertissement. Les comptes nommés héritent de `channels.telegram.allowFrom` / `groupAllowFrom`, mais pas des valeurs `accounts.default.*`. +Priorité multi-compte : lorsque deux identifiants de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) pour rendre explicite le routage par défaut. Sinon, OpenClaw se replie sur le premier identifiant de compte normalisé et `openclaw doctor` avertit. Les comptes nommés héritent de `channels.telegram.allowFrom` / `groupAllowFrom`, mais pas des valeurs `accounts.default.*`. -## Associé +## Connexe - - Jumelez un utilisateur Telegram au Gateway. + + Appariez un utilisateur Telegram au Gateway. - Comportement des listes d’autorisation de groupes et de sujets. + Comportement de liste d'autorisation des groupes et des sujets. - Routez les messages entrants vers les agents. + Routez les messages entrants vers des agents. Modèle de menace et durcissement. - Associez les groupes et les sujets aux agents. + Associez des groupes et des sujets à des agents. Diagnostics inter-canaux. diff --git a/docs/fr/channels/whatsapp.md b/docs/fr/channels/whatsapp.md index ae7db8bed..e27633bf0 100644 --- a/docs/fr/channels/whatsapp.md +++ b/docs/fr/channels/whatsapp.md @@ -4,25 +4,25 @@ read_when: summary: Prise en charge du canal WhatsApp, contrôles d’accès, comportement de livraison et opérations title: WhatsApp x-i18n: - generated_at: "2026-05-03T07:08:25Z" + generated_at: "2026-05-05T06:15:59Z" model: gpt-5.5 provider: openai - source_hash: 2f12709fc8ecb45e1b060647daf9a4624485d52b7b6436c3d07f171e6807babf + source_hash: 52a81fc323568e06d11606931e34465fe5a823a0699d8e0638195b8667c3ebee source_path: channels/whatsapp.md workflow: 16 --- -Statut : prêt pour la production via WhatsApp Web (Baileys). Le Gateway possède les sessions liées. +Statut : prêt pour la production via WhatsApp Web (Baileys). Gateway gère les sessions liées. ## Installation (à la demande) -- L’intégration (`openclaw onboard`) et `openclaw channels add --channel whatsapp` +- L’onboarding (`openclaw onboard`) et `openclaw channels add --channel whatsapp` proposent d’installer le Plugin WhatsApp la première fois que vous le sélectionnez. -- `openclaw channels login --channel whatsapp` propose également le flux d’installation lorsque +- `openclaw channels login --channel whatsapp` propose aussi le flux d’installation lorsque le Plugin n’est pas encore présent. -- Canal de développement + checkout git : utilise par défaut le chemin du Plugin local. -- Stable/Bêta : utilise le paquet npm `@openclaw/whatsapp` sur l’étiquette de version officielle - actuelle. +- Canal de développement + dépôt git extrait : utilise par défaut le chemin du Plugin local. +- Stable/Bêta : utilise le package npm `@openclaw/whatsapp` sur l’étiquette de version + officielle actuelle. L’installation manuelle reste disponible : @@ -30,17 +30,27 @@ L’installation manuelle reste disponible : openclaw plugins install @openclaw/whatsapp ``` -Utilisez le paquet nu pour suivre l’étiquette de version officielle actuelle. Épinglez une version +Utilisez le package nu pour suivre l’étiquette de version officielle actuelle. Épinglez une version exacte uniquement lorsque vous avez besoin d’une installation reproductible. +Sous Windows, le Plugin WhatsApp a besoin de Git sur `PATH` pendant l’installation npm, car +l’une de ses dépendances Baileys/libsignal est récupérée depuis une URL git. Installez +Git for Windows, puis redémarrez le shell et relancez l’installation : + +```powershell +winget install --id Git.Git -e +``` + +Portable Git fonctionne aussi si son répertoire `bin` est sur `PATH`. + - - La politique par défaut pour les messages directs consiste à utiliser l’appairage pour les expéditeurs inconnus. + + La politique de MP par défaut est l’appairage pour les expéditeurs inconnus. - - Diagnostics et guides de réparation intercanaux. + + Diagnostics intercanaux et procédures de réparation. - + Modèles et exemples complets de configuration de canal. @@ -48,7 +58,7 @@ exacte uniquement lorsque vous avez besoin d’une installation reproductible. ## Configuration rapide - + ```json5 { @@ -65,19 +75,19 @@ exacte uniquement lorsque vous avez besoin d’une installation reproductible. - + ```bash openclaw channels login --channel whatsapp ``` - Pour un compte précis : + Pour un compte spécifique : ```bash openclaw channels login --channel whatsapp --account work ``` - Pour attacher un répertoire d’authentification WhatsApp Web existant/personnalisé avant la connexion : + Pour joindre un répertoire d’authentification WhatsApp Web existant/personnalisé avant la connexion : ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -86,7 +96,7 @@ openclaw channels login --channel whatsapp --account work - + ```bash openclaw gateway @@ -94,7 +104,7 @@ openclaw gateway - + ```bash openclaw pairing list whatsapp @@ -107,18 +117,18 @@ openclaw pairing approve whatsapp -OpenClaw recommande d’exécuter WhatsApp sur un numéro séparé lorsque c’est possible. (Les métadonnées du canal et le flux de configuration sont optimisés pour cette configuration, mais les configurations avec numéro personnel sont également prises en charge.) +OpenClaw recommande d’exécuter WhatsApp sur un numéro séparé lorsque c’est possible. (Les métadonnées du canal et le flux de configuration sont optimisés pour cette configuration, mais les configurations avec numéro personnel sont aussi prises en charge.) ## Modèles de déploiement - + C’est le mode opérationnel le plus propre : - identité WhatsApp séparée pour OpenClaw - - listes d’autorisation de messages directs et limites de routage plus claires - - risque plus faible de confusion avec les messages à soi-même + - listes d’autorisation de MP et limites de routage plus claires + - risque plus faible de confusion avec les conversations avec soi-même Modèle de politique minimal : @@ -135,45 +145,45 @@ OpenClaw recommande d’exécuter WhatsApp sur un numéro séparé lorsque c’e - - L’intégration prend en charge le mode numéro personnel et écrit une base compatible avec les messages à soi-même : + + L’onboarding prend en charge le mode numéro personnel et écrit une base compatible avec les conversations avec soi-même : - `dmPolicy: "allowlist"` - `allowFrom` inclut votre numéro personnel - `selfChatMode: true` - À l’exécution, les protections contre les messages à soi-même s’appuient sur le numéro lié à soi-même et sur `allowFrom`. + À l’exécution, les protections de conversation avec soi-même s’appuient sur le numéro propre lié et sur `allowFrom`. - - Le canal de plateforme de messagerie est basé sur WhatsApp Web (`Baileys`) dans l’architecture actuelle des canaux OpenClaw. + + Le canal de la plateforme de messagerie est basé sur WhatsApp Web (`Baileys`) dans l’architecture actuelle des canaux OpenClaw. - Il n’existe pas de canal de messagerie WhatsApp Twilio distinct dans le registre intégré des canaux de discussion. + Il n’existe pas de canal de messagerie WhatsApp Twilio séparé dans le registre intégré des canaux de chat. ## Modèle d’exécution -- Le Gateway possède le socket WhatsApp et la boucle de reconnexion. -- Le mécanisme de surveillance de reconnexion utilise l’activité de transport WhatsApp Web, et pas seulement le volume de messages applicatifs entrants, de sorte qu’une session d’appareil lié silencieuse n’est pas redémarrée uniquement parce que personne n’a envoyé de message récemment. Un plafond plus long de silence applicatif force toujours une reconnexion si les trames de transport continuent d’arriver mais qu’aucun message applicatif n’est traité pendant la fenêtre de surveillance ; après une reconnexion transitoire pour une session récemment active, cette vérification du silence applicatif utilise le délai d’expiration normal des messages pour la première fenêtre de récupération. -- Les délais du socket Baileys sont explicites sous `web.whatsapp.*` : `keepAliveIntervalMs` contrôle les pings applicatifs WhatsApp Web, `connectTimeoutMs` contrôle le délai d’expiration de la poignée de main d’ouverture, et `defaultQueryTimeoutMs` contrôle les délais d’expiration des requêtes Baileys. +- Gateway gère la socket WhatsApp et la boucle de reconnexion. +- Le chien de garde de reconnexion utilise l’activité de transport WhatsApp Web, pas seulement le volume de messages applicatifs entrants, de sorte qu’une session d’appareil lié silencieuse n’est pas redémarrée uniquement parce que personne n’a envoyé de message récemment. Une limite plus longue de silence applicatif force tout de même une reconnexion si des trames de transport continuent d’arriver, mais qu’aucun message applicatif n’est traité pendant la fenêtre du chien de garde ; après une reconnexion transitoire pour une session récemment active, cette vérification de silence applicatif utilise le délai normal des messages pour la première fenêtre de récupération. +- Les temporisations de socket Baileys sont explicites sous `web.whatsapp.*` : `keepAliveIntervalMs` contrôle les pings applicatifs WhatsApp Web, `connectTimeoutMs` contrôle le délai d’expiration de la poignée de main d’ouverture, et `defaultQueryTimeoutMs` contrôle les délais d’expiration des requêtes Baileys. - Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible. -- Les envois de groupe attachent les métadonnées de mention natives pour les jetons `@+` et `@` dans le texte et les légendes de médias lorsque le jeton correspond aux métadonnées actuelles des participants WhatsApp, y compris les groupes adossés à un LID. -- Les discussions de statut et de diffusion sont ignorées (`@status`, `@broadcast`). -- Le mécanisme de surveillance de reconnexion suit l’activité de transport WhatsApp Web, et pas seulement le volume de messages applicatifs entrants : les sessions d’appareils liés silencieuses restent actives tant que les trames de transport continuent, mais un blocage du transport force une reconnexion bien avant le chemin ultérieur de déconnexion distante. -- Les discussions directes utilisent les règles de session de messages directs (`session.dmScope` ; la valeur par défaut `main` regroupe les messages directs dans la session principale de l’agent). +- Les envois de groupe joignent les métadonnées de mention natives pour les jetons `@+` et `@` dans le texte et les légendes de médias lorsque le jeton correspond aux métadonnées de participant WhatsApp actuelles, y compris les groupes adossés à LID. +- Les chats de statut et de diffusion sont ignorés (`@status`, `@broadcast`). +- Le chien de garde de reconnexion suit l’activité de transport WhatsApp Web, pas seulement le volume de messages applicatifs entrants : les sessions d’appareil lié silencieuses restent actives tant que les trames de transport continuent, mais un blocage du transport force une reconnexion bien avant le chemin ultérieur de déconnexion distante. +- Les chats directs utilisent les règles de session de MP (`session.dmScope` ; la valeur par défaut `main` regroupe les MP dans la session principale de l’agent). - Les sessions de groupe sont isolées (`agent::whatsapp:group:`). -- Les canaux/newsletters WhatsApp peuvent être des cibles sortantes explicites avec leur JID natif `@newsletter`. Les envois sortants de newsletter utilisent les métadonnées de session de canal (`agent::whatsapp:channel:`) plutôt que la sémantique des sessions de messages directs. +- Les canaux/newsletters WhatsApp peuvent être des cibles sortantes explicites avec leur JID natif `@newsletter`. Les envois sortants de newsletter utilisent les métadonnées de session de canal (`agent::whatsapp:channel:`) plutôt que la sémantique de session de MP. - Le transport WhatsApp Web respecte les variables d’environnement de proxy standard sur l’hôte du Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / variantes en minuscules). Préférez la configuration de proxy au niveau de l’hôte aux paramètres de proxy WhatsApp propres au canal. -- Lorsque `messages.removeAckAfterReply` est activé, OpenClaw efface la réaction d’accusé de réception WhatsApp après la livraison d’une réponse visible. +- Lorsque `messages.removeAckAfterReply` est activé, OpenClaw efface la réaction d’accusé de réception WhatsApp après la remise d’une réponse visible. ## Hooks de Plugin et confidentialité -Les messages entrants WhatsApp peuvent contenir du contenu de message personnel, des numéros de téléphone, -des identifiants de groupe, des noms d’expéditeur et des champs de corrélation de session. Pour cette raison, -WhatsApp ne diffuse pas les charges utiles du hook entrant `message_received` aux Plugins +Les messages entrants WhatsApp peuvent contenir le contenu de messages personnels, des numéros de téléphone, +des identifiants de groupe, des noms d’expéditeurs et des champs de corrélation de session. Pour cette raison, +WhatsApp ne diffuse pas les charges utiles de hook `message_received` entrant aux plugins sauf si vous l’activez explicitement : ```json5 @@ -206,92 +216,93 @@ Vous pouvez limiter l’activation à un seul compte : } ``` -N’activez ceci que pour les plugins auxquels vous faites confiance pour recevoir le contenu et les identifiants des messages WhatsApp entrants. +Activez cette option uniquement pour les plugins auxquels vous faites confiance pour recevoir le contenu +et les identifiants des messages WhatsApp entrants. ## Contrôle d’accès et activation - - `channels.whatsapp.dmPolicy` contrôle l’accès aux discussions directes : + + `channels.whatsapp.dmPolicy` contrôle l’accès aux chats directs : - `pairing` (par défaut) - `allowlist` - `open` (nécessite que `allowFrom` inclue `"*"`) - `disabled` - `allowFrom` accepte les numéros au format E.164 (normalisés en interne). + `allowFrom` accepte les numéros au style E.164 (normalisés en interne). - `allowFrom` est une liste de contrôle d’accès des expéditeurs en DM. Elle ne filtre pas les envois sortants explicites vers des JID de groupes WhatsApp ou des JID de canaux `@newsletter`. + `allowFrom` est une liste de contrôle d’accès des expéditeurs de MP. Elle ne filtre pas les envois sortants explicites vers des JID de groupe WhatsApp ou des JID de canal `@newsletter`. - Remplacement multi-compte : `channels.whatsapp.accounts..dmPolicy` (et `allowFrom`) ont priorité sur les valeurs par défaut au niveau du canal pour ce compte. + Remplacement multicomptes : `channels.whatsapp.accounts..dmPolicy` (et `allowFrom`) prennent le pas sur les valeurs par défaut au niveau du canal pour ce compte. Détails du comportement à l’exécution : - - les associations sont conservées dans le magasin d’autorisations du canal et fusionnées avec `allowFrom` configuré - - l’automatisation planifiée et le repli des destinataires Heartbeat utilisent des cibles de livraison explicites ou `allowFrom` configuré ; les approbations d’association DM ne sont pas implicitement des destinataires Cron ou Heartbeat - - si aucune liste d’autorisation n’est configurée, le numéro personnel lié est autorisé par défaut - - OpenClaw n’associe jamais automatiquement les DM sortants `fromMe` (messages que vous vous envoyez à vous-même depuis l’appareil lié) + - les appairages sont conservés dans le magasin d’autorisations du canal et fusionnés avec `allowFrom` configuré + - l’automatisation planifiée et le repli de destinataire Heartbeat utilisent des cibles de livraison explicites ou `allowFrom` configuré ; les approbations d’appairage de MP ne sont pas des destinataires Cron ou Heartbeat implicites + - si aucune liste d’autorisation n’est configurée, le numéro propre lié est autorisé par défaut + - OpenClaw n’appaire jamais automatiquement les MP sortants `fromMe` (messages que vous vous envoyez depuis l’appareil lié) - + L’accès aux groupes comporte deux couches : 1. **Liste d’autorisation d’appartenance aux groupes** (`channels.whatsapp.groups`) - si `groups` est omis, tous les groupes sont éligibles - - si `groups` est présent, il agit comme une liste d’autorisation de groupes (`"*"` autorisé) + - si `groups` est présent, il agit comme liste d’autorisation de groupes (`"*"` autorisé) - 2. **Politique des expéditeurs de groupe** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) + 2. **Politique d’expéditeur de groupe** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) - `open` : liste d’autorisation des expéditeurs contournée - `allowlist` : l’expéditeur doit correspondre à `groupAllowFrom` (ou `*`) - - `disabled` : bloquer tous les entrants de groupe + - `disabled` : bloque tous les entrants de groupe - Repli de la liste d’autorisation des expéditeurs : + Repli de liste d’autorisation des expéditeurs : - - si `groupAllowFrom` n’est pas défini, l’exécution se replie sur `allowFrom` lorsqu’il est disponible - - les listes d’autorisation des expéditeurs sont évaluées avant l’activation par mention/réponse + - si `groupAllowFrom` n’est pas défini, l’exécution se rabat sur `allowFrom` lorsqu’il est disponible + - les listes d’autorisation d’expéditeurs sont évaluées avant l’activation par mention/réponse - Remarque : si aucun bloc `channels.whatsapp` n’existe, le repli de la politique de groupe à l’exécution est `allowlist` (avec un journal d’avertissement), même si `channels.defaults.groupPolicy` est défini. + Remarque : si aucun bloc `channels.whatsapp` n’existe, le repli de politique de groupe à l’exécution est `allowlist` (avec un journal d’avertissement), même si `channels.defaults.groupPolicy` est défini. - Les réponses de groupe exigent une mention par défaut. + Les réponses de groupe nécessitent une mention par défaut. - La détection des mentions inclut : + La détection de mentions inclut : - les mentions WhatsApp explicites de l’identité du bot - - les modèles regex de mention configurés (`agents.list[].groupChat.mentionPatterns`, repli `messages.groupChat.mentionPatterns`) + - les motifs regex de mention configurés (`agents.list[].groupChat.mentionPatterns`, repli `messages.groupChat.mentionPatterns`) - les transcriptions de notes vocales entrantes pour les messages de groupe autorisés - - la détection implicite des réponses au bot (l’expéditeur de la réponse correspond à l’identité du bot) + - la détection implicite de réponse au bot (l’expéditeur de la réponse correspond à l’identité du bot) Note de sécurité : - - la citation/réponse ne satisfait que le filtrage par mention ; elle n’accorde **pas** l’autorisation à l’expéditeur - - avec `groupPolicy: "allowlist"`, les expéditeurs non présents dans la liste d’autorisation restent bloqués, même s’ils répondent au message d’un utilisateur présent dans la liste d’autorisation + - la citation/réponse ne satisfait que le filtrage par mention ; elle n’accorde **pas** l’autorisation de l’expéditeur + - avec `groupPolicy: "allowlist"`, les expéditeurs absents de la liste d’autorisation restent bloqués même s’ils répondent au message d’un utilisateur autorisé Commande d’activation au niveau de la session : - `/activation mention` - `/activation always` - `activation` met à jour l’état de la session (pas la configuration globale). Elle est restreinte au propriétaire. + `activation` met à jour l’état de session (pas la configuration globale). Elle est limitée au propriétaire. -## Comportement du numéro personnel et de l’auto-discussion +## Comportement avec numéro personnel et conversation avec soi-même -Lorsque le numéro personnel lié est également présent dans `allowFrom`, les garde-fous d’auto-discussion WhatsApp s’activent : +Lorsque le numéro propre lié est aussi présent dans `allowFrom`, les protections WhatsApp de conversation avec soi-même s’activent : -- ignorer les accusés de lecture pour les tours d’auto-discussion -- ignorer le comportement de déclenchement automatique par JID de mention qui vous pinguerait autrement vous-même -- si `messages.responsePrefix` n’est pas défini, les réponses d’auto-discussion utilisent par défaut `[{identity.name}]` ou `[openclaw]` +- ignorer les accusés de lecture pour les tours de conversation avec soi-même +- ignorer le comportement de déclenchement automatique par JID de mention qui vous notifierait autrement vous-même +- si `messages.responsePrefix` n’est pas défini, les réponses de conversation avec soi-même utilisent par défaut `[{identity.name}]` ou `[openclaw]` ## Normalisation des messages et contexte - + Les messages WhatsApp entrants sont enveloppés dans l’enveloppe entrante partagée. Si une réponse citée existe, le contexte est ajouté sous cette forme : @@ -302,16 +313,16 @@ Lorsque le numéro personnel lié est également présent dans `allowFrom`, les [/Replying] ``` - Les champs de métadonnées de réponse sont également renseignés lorsqu’ils sont disponibles (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 de l’expéditeur). - Lorsque la cible de réponse citée est un média téléchargeable, OpenClaw l’enregistre via - le magasin de médias entrants normal et l’expose sous forme de `MediaPath`/`MediaType` afin que + Les champs de métadonnées de réponse sont aussi renseignés lorsqu’ils sont disponibles (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 de l’expéditeur). + Lorsque la cible de la réponse citée est un média téléchargeable, OpenClaw l’enregistre via + le magasin normal de médias entrants et l’expose comme `MediaPath`/`MediaType` afin que l’agent puisse inspecter l’image référencée au lieu de voir uniquement ``. - - Les messages entrants contenant uniquement des médias sont normalisés avec des espaces réservés tels que : + + Les messages entrants ne contenant que des médias sont normalisés avec des espaces réservés tels que : - `` - `` @@ -320,15 +331,15 @@ Lorsque le numéro personnel lié est également présent dans `allowFrom`, les - `` Les notes vocales de groupe autorisées sont transcrites avant le filtrage par mention lorsque le - corps est uniquement ``, de sorte que prononcer la mention du bot dans la note vocale peut - déclencher la réponse. Si la transcription ne mentionne toujours pas le bot, la - transcription est conservée dans l’historique de groupe en attente au lieu de l’espace réservé brut. + corps est uniquement ``, donc prononcer la mention du bot dans la note vocale peut + déclencher la réponse. Si la transcription ne mentionne toujours pas le bot, elle est + conservée dans l’historique de groupe en attente au lieu de l’espace réservé brut. - Les corps de localisation utilisent un texte concis de coordonnées. Les libellés/commentaires de localisation et les détails de contact/vCard sont rendus sous forme de métadonnées non fiables dans un bloc clôturé, et non comme texte de prompt en ligne. + Les corps de localisation utilisent un texte de coordonnées concis. Les libellés/commentaires de localisation et les détails de contact/vCard sont rendus comme des métadonnées non fiables clôturées, pas comme du texte d’invite en ligne. - + Pour les groupes, les messages non traités peuvent être mis en mémoire tampon et injectés comme contexte lorsque le bot est enfin déclenché. - limite par défaut : `50` @@ -374,31 +385,31 @@ Lorsque le numéro personnel lié est également présent dans `allowFrom`, les } ``` - Les tours de conversation avec soi-même ignorent les accusés de lecture, même lorsqu’ils sont activés globalement. + Les tours en auto-discussion ignorent les accusés de lecture, même lorsqu’ils sont activés globalement. -## Livraison, segmentation et médias +## Livraison, découpage et médias - - - limite de segment par défaut : `channels.whatsapp.textChunkLimit = 4000` + + - limite de découpage par défaut : `channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - le mode `newline` privilégie les limites de paragraphe (lignes vides), puis revient à une segmentation sûre par longueur + - le mode `newline` privilégie les limites de paragraphe (lignes vides), puis revient à un découpage sûr par longueur - prend en charge les charges utiles d’image, de vidéo, d’audio (note vocale PTT) et de document - - les médias audio sont envoyés via la charge utile `audio` de Baileys avec `ptt: true`, afin que les clients WhatsApp les affichent comme une note vocale push-to-talk - - les charges utiles de réponse conservent `audioAsVoice` ; la sortie de note vocale TTS pour WhatsApp reste sur ce chemin PTT même lorsque le fournisseur renvoie du MP3 ou du WebM - - l’audio Ogg/Opus natif est envoyé comme `audio/ogg; codecs=opus` pour la compatibilité avec les notes vocales - - l’audio non Ogg, y compris la sortie MP3/WebM TTS de Microsoft Edge, est transcodé avec `ffmpeg` en Ogg/Opus mono 48 kHz avant la livraison PTT + - les médias audio sont envoyés via la charge utile `audio` de Baileys avec `ptt: true`, afin que les clients WhatsApp les affichent comme une note vocale en mode pression pour parler + - les charges utiles de réponse préservent `audioAsVoice` ; la sortie de note vocale TTS pour WhatsApp reste sur ce chemin PTT, même lorsque le fournisseur renvoie du MP3 ou du WebM + - l’audio Ogg/Opus natif est envoyé sous la forme `audio/ogg; codecs=opus` pour la compatibilité avec les notes vocales + - l’audio non Ogg, y compris la sortie MP3/WebM de Microsoft Edge TTS, est transcodé avec `ffmpeg` en Ogg/Opus mono 48 kHz avant la livraison PTT - `/tts latest` envoie la dernière réponse de l’assistant comme une seule note vocale et supprime les envois répétés pour la même réponse ; `/tts chat on|off|default` contrôle le TTS automatique pour la discussion WhatsApp actuelle - - la lecture des GIF animés est prise en charge via `gifPlayback: true` sur les envois vidéo - - les légendes sont appliquées au premier élément média lors de l’envoi de charges utiles de réponse multimédia, sauf que les notes vocales PTT envoient d’abord l’audio puis le texte visible séparément, car les clients WhatsApp n’affichent pas les légendes de notes vocales de façon cohérente - - la source média peut être HTTP(S), `file://` ou des chemins locaux + - la lecture des GIF animés est prise en charge via `gifPlayback: true` lors des envois vidéo + - les légendes sont appliquées au premier élément multimédia lors de l’envoi de charges utiles de réponse multimédias, sauf pour les notes vocales PTT, qui envoient d’abord l’audio puis le texte visible séparément, car les clients WhatsApp n’affichent pas toujours les légendes de notes vocales + - la source du média peut être HTTP(S), `file://` ou des chemins locaux @@ -406,21 +417,21 @@ Lorsque le numéro personnel lié est également présent dans `allowFrom`, les - plafond d’enregistrement des médias entrants : `channels.whatsapp.mediaMaxMb` (par défaut `50`) - plafond d’envoi des médias sortants : `channels.whatsapp.mediaMaxMb` (par défaut `50`) - les remplacements par compte utilisent `channels.whatsapp.accounts..mediaMaxMb` - - les images sont automatiquement optimisées (redimensionnement/balayage de qualité) pour respecter les limites - - en cas d’échec d’envoi de média, le repli sur le premier élément envoie un avertissement textuel au lieu de supprimer silencieusement la réponse + - les images sont optimisées automatiquement (redimensionnement/balayage de qualité) pour respecter les limites + - en cas d’échec d’envoi de média, le repli du premier élément envoie un avertissement textuel au lieu de supprimer silencieusement la réponse -## Citation de réponse +## Citation des réponses -WhatsApp prend en charge la citation de réponse native, où les réponses sortantes citent visiblement le message entrant. Contrôlez-la avec `channels.whatsapp.replyToMode`. +WhatsApp prend en charge la citation native des réponses, où les réponses sortantes citent visiblement le message entrant. Contrôlez-la avec `channels.whatsapp.replyToMode`. | Valeur | Comportement | -| ----------- | --------------------------------------------------------------------- | -| `"off"` | Ne jamais citer ; envoyer comme un message simple | -| `"first"` | Ne citer que le premier segment de réponse sortante | -| `"all"` | Citer chaque segment de réponse sortante | +| ----------- | -------------------------------------------------------------------- | +| `"off"` | Ne jamais citer ; envoyer comme un message simple | +| `"first"` | Citer uniquement le premier fragment de réponse sortante | +| `"all"` | Citer chaque fragment de réponse sortante | | `"batched"` | Citer les réponses groupées en file d’attente tout en laissant les réponses immédiates sans citation | La valeur par défaut est `"off"`. Les remplacements par compte utilisent `channels.whatsapp.accounts..replyToMode`. @@ -437,14 +448,14 @@ La valeur par défaut est `"off"`. Les remplacements par compte utilisent `chann ## Niveau de réaction -`channels.whatsapp.reactionLevel` contrôle l’étendue avec laquelle l’agent utilise les réactions emoji sur WhatsApp : +`channels.whatsapp.reactionLevel` contrôle l’étendue de l’utilisation des réactions emoji par l’agent sur WhatsApp : -| Niveau | Réactions d’accusé | Réactions initiées par l’agent | Description | -| ------------- | ------------------ | ------------------------------ | ------------------------------------------------ | -| `"off"` | Non | Non | Aucune réaction | -| `"ack"` | Oui | Non | Réactions d’accusé uniquement (réception avant réponse) | -| `"minimal"` | Oui | Oui (conservateur) | Accusé + réactions d’agent avec consignes conservatrices | -| `"extensive"` | Oui | Oui (encouragé) | Accusé + réactions d’agent avec consignes encouragées | +| Niveau | Réactions d’accusé de réception | Réactions initiées par l’agent | Description | +| ------------- | ------------------------------- | ------------------------------ | --------------------------------------------------------------------------- | +| `"off"` | Non | Non | Aucune réaction | +| `"ack"` | Oui | Non | Réactions d’accusé de réception uniquement (accusé avant réponse) | +| `"minimal"` | Oui | Oui (conservateur) | Accusé de réception + réactions de l’agent avec consignes conservatrices | +| `"extensive"` | Oui | Oui (encouragé) | Accusé de réception + réactions de l’agent avec consignes encourageantes | Par défaut : `"minimal"`. @@ -462,8 +473,8 @@ Les remplacements par compte utilisent `channels.whatsapp.accounts..reaction ## Réactions d’accusé de réception -WhatsApp prend en charge les réactions d’accusé immédiates à la réception entrante via `channels.whatsapp.ackReaction`. -Les réactions d’accusé sont contrôlées par `reactionLevel` — elles sont supprimées lorsque `reactionLevel` vaut `"off"`. +WhatsApp prend en charge les réactions d’accusé de réception immédiates à la réception entrante via `channels.whatsapp.ackReaction`. +Les réactions d’accusé de réception sont contrôlées par `reactionLevel` — elles sont supprimées lorsque `reactionLevel` vaut `"off"`. ```json5 { @@ -481,17 +492,17 @@ Les réactions d’accusé sont contrôlées par `reactionLevel` — elles sont Notes de comportement : -- envoyées immédiatement après l’acceptation de l’entrée (avant réponse) -- les échecs sont journalisés mais ne bloquent pas la livraison normale de la réponse -- le mode de groupe `mentions` réagit sur les tours déclenchés par mention ; l’activation de groupe `always` sert de contournement pour cette vérification +- envoyées immédiatement après l’acceptation du message entrant (avant la réponse) +- les échecs sont journalisés, mais ne bloquent pas la livraison normale de la réponse +- le mode de groupe `mentions` réagit sur les tours déclenchés par une mention ; l’activation de groupe `always` agit comme contournement pour cette vérification - WhatsApp utilise `channels.whatsapp.ackReaction` (l’ancien `messages.ackReaction` n’est pas utilisé ici) ## Comptes multiples et identifiants - + - les identifiants de compte proviennent de `channels.whatsapp.accounts` - - sélection de compte par défaut : `default` s’il est présent, sinon le premier identifiant de compte configuré (trié) + - sélection du compte par défaut : `default` s’il est présent, sinon le premier identifiant de compte configuré (trié) - les identifiants de compte sont normalisés en interne pour la recherche @@ -499,16 +510,16 @@ Notes de comportement : - chemin d’authentification actuel : `~/.openclaw/credentials/whatsapp//creds.json` - fichier de sauvegarde : `creds.json.bak` - - l’authentification par défaut héritée dans `~/.openclaw/credentials/` est toujours reconnue/migrée pour les flux de compte par défaut + - l’authentification par défaut héritée dans `~/.openclaw/credentials/` est encore reconnue/migrée pour les flux de compte par défaut `openclaw channels logout --channel whatsapp [--account ]` efface l’état d’authentification WhatsApp pour ce compte. - Lorsqu’un Gateway est joignable, la déconnexion arrête d’abord l’écouteur WhatsApp actif pour le compte sélectionné afin que la session liée ne continue pas à recevoir des messages jusqu’au prochain redémarrage. `openclaw channels remove --channel whatsapp` arrête aussi l’écouteur actif avant de désactiver ou supprimer la configuration du compte. + Lorsqu’un Gateway est joignable, la déconnexion arrête d’abord l’écouteur WhatsApp actif pour le compte sélectionné afin que la session liée ne continue pas à recevoir des messages jusqu’au prochain redémarrage. `openclaw channels remove --channel whatsapp` arrête également l’écouteur actif avant de désactiver ou de supprimer la configuration du compte. - Dans les répertoires d’authentification hérités, `oauth.json` est conservé tandis que les fichiers d’authentification Baileys sont supprimés. + Dans les répertoires d’authentification hérités, `oauth.json` est préservé tandis que les fichiers d’authentification Baileys sont supprimés. @@ -527,7 +538,7 @@ Notes de comportement : Symptôme : l’état du canal indique qu’il n’est pas lié. - Correctif : + Correction : ```bash openclaw channels login --channel whatsapp @@ -539,14 +550,9 @@ Notes de comportement : Symptôme : compte lié avec déconnexions répétées ou tentatives de reconnexion. - Les comptes silencieux peuvent rester connectés au-delà du délai normal de message ; le chien de garde - redémarre lorsque l’activité de transport WhatsApp Web s’arrête, que le socket se ferme ou que - l’activité au niveau de l’application reste silencieuse au-delà de la fenêtre de sécurité plus longue. + Les comptes peu actifs peuvent rester connectés au-delà du délai normal des messages ; le chien de garde redémarre lorsque l’activité du transport WhatsApp Web s’arrête, que le socket se ferme ou que l’activité au niveau de l’application reste silencieuse au-delà de la fenêtre de sécurité plus longue. - Si les journaux affichent des `status=408 Request Time-out Connection was lost` répétés, ajustez - les minutages du socket Baileys sous `web.whatsapp`. Commencez par raccourcir - `keepAliveIntervalMs` sous le délai d’inactivité de votre réseau et augmenter - `connectTimeoutMs` sur les liaisons lentes ou avec pertes : + Si les journaux affichent des occurrences répétées de `status=408 Request Time-out Connection was lost`, ajustez les temporisations de socket Baileys sous `web.whatsapp`. Commencez par raccourcir `keepAliveIntervalMs` sous le délai d’inactivité de votre réseau et par augmenter `connectTimeoutMs` sur les liens lents ou avec pertes : ```json5 { @@ -560,29 +566,23 @@ Notes de comportement : } ``` - Correctif : + Correction : ```bash openclaw doctor openclaw logs --follow ``` - Si `~/.openclaw/logs/whatsapp-health.log` indique `Gateway inactive` mais que - `openclaw gateway status` et `openclaw channels status --probe` montrent que le - Gateway et WhatsApp sont sains, exécutez `openclaw doctor`. Sur Linux, le doctor - avertit à propos des entrées crontab héritées qui invoquent encore - `~/.openclaw/bin/ensure-whatsapp.sh` ; supprimez ces entrées obsolètes avec - `crontab -e`, car cron peut ne pas disposer de l’environnement du bus utilisateur systemd et - faire en sorte que cet ancien script signale à tort l’état de santé du Gateway. + Si `~/.openclaw/logs/whatsapp-health.log` indique `Gateway inactive`, mais que `openclaw gateway status` et `openclaw channels status --probe` montrent que le Gateway et WhatsApp sont sains, exécutez `openclaw doctor`. Sous Linux, le diagnostic avertit au sujet d’entrées crontab héritées qui invoquent encore `~/.openclaw/bin/ensure-whatsapp.sh` ; supprimez ces entrées obsolètes avec `crontab -e`, car cron peut ne pas disposer de l’environnement du bus utilisateur systemd et faire en sorte que cet ancien script signale à tort l’état du Gateway. - Si nécessaire, liez à nouveau avec `channels login`. + Si nécessaire, reliez avec `channels login`. Symptôme : `openclaw channels login --channel whatsapp` échoue avant d’afficher un code QR utilisable avec `status=408 Request Time-out` ou une déconnexion de socket TLS. - La connexion WhatsApp Web utilise l’environnement proxy standard de l’hôte Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, variantes en minuscules et `NO_PROXY`). Vérifiez que le processus Gateway hérite de l’environnement proxy et que `NO_PROXY` ne correspond pas à `mmg.whatsapp.net`. + La connexion WhatsApp Web utilise l’environnement proxy standard de l’hôte du Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, variantes en minuscules et `NO_PROXY`). Vérifiez que le processus Gateway hérite de l’environnement proxy et que `NO_PROXY` ne correspond pas à `mmg.whatsapp.net`. @@ -596,25 +596,25 @@ Notes de comportement : Les lignes de transcription enregistrent ce que l’agent a généré. La livraison WhatsApp est vérifiée séparément : OpenClaw ne considère une réponse automatique comme envoyée qu’après que Baileys a renvoyé un identifiant de message sortant pour au moins un envoi de texte visible ou de média. - Les réactions d’accusé sont des accusés de réception indépendants avant réponse. Une réaction réussie ne prouve pas que la réponse texte ou média ultérieure a été acceptée par WhatsApp. + Les réactions d’accusé de réception sont des accusés indépendants avant réponse. Une réaction réussie ne prouve pas que la réponse texte ou média ultérieure a été acceptée par WhatsApp. - Vérifiez les journaux Gateway pour `auto-reply delivery failed` ou `auto-reply was not accepted by WhatsApp provider`. + Consultez les journaux du Gateway pour `auto-reply delivery failed` ou `auto-reply was not accepted by WhatsApp provider`. - + Vérifiez dans cet ordre : - `groupPolicy` - `groupAllowFrom` / `allowFrom` - entrées de liste d’autorisation `groups` - - filtrage par mention (`requireMention` + motifs de mention) - - clés en double dans `openclaw.json` (JSON5) : les entrées ultérieures remplacent les précédentes, donc conservez un seul `groupPolicy` par portée + - filtrage par mention (`requireMention` + modèles de mention) + - clés en double dans `openclaw.json` (JSON5) : les entrées ultérieures remplacent les précédentes, conservez donc un seul `groupPolicy` par portée - L’exécution Gateway de WhatsApp doit utiliser Node. Bun est signalé comme incompatible avec un fonctionnement Gateway WhatsApp/Telegram stable. + L’environnement d’exécution du Gateway WhatsApp doit utiliser Node. Bun est signalé comme incompatible avec un fonctionnement stable du Gateway WhatsApp/Telegram. @@ -624,30 +624,30 @@ WhatsApp prend en charge les prompts système de style Telegram pour les groupes Hiérarchie de résolution pour les messages de groupe : -La carte `groups` effective est déterminée en premier : si le compte définit ses propres `groups`, elle remplace entièrement la carte `groups` racine (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante : +La carte effective `groups` est déterminée en premier : si le compte définit ses propres `groups`, elle remplace entièrement la carte racine `groups` (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante : -1. **Prompt système propre au groupe** (`groups[""].systemPrompt`) : utilisé lorsque l’entrée de groupe spécifique existe dans la carte **et** que sa clé `systemPrompt` est définie. Si `systemPrompt` est une chaîne vide (`""`), le caractère générique est supprimé et aucun prompt système n’est appliqué. -2. **Prompt système générique de groupe** (`groups["*"].systemPrompt`) : utilisé lorsque l’entrée de groupe spécifique est entièrement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé `systemPrompt`. +1. **Prompt système propre au groupe** (`groups[""].systemPrompt`) : utilisé lorsque l’entrée du groupe spécifique existe dans la carte **et** que sa clé `systemPrompt` est définie. Si `systemPrompt` est une chaîne vide (`""`), le caractère générique est supprimé et aucun prompt système n’est appliqué. +2. **Prompt système générique de groupe** (`groups["*"].systemPrompt`) : utilisé lorsque l’entrée du groupe spécifique est entièrement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé `systemPrompt`. Hiérarchie de résolution pour les messages directs : -La carte `direct` effective est déterminée en premier : si le compte définit son propre `direct`, elle remplace entièrement la carte `direct` racine (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante : +La carte effective `direct` est déterminée en premier : si le compte définit sa propre carte `direct`, elle remplace entièrement la carte racine `direct` (pas de fusion profonde). La recherche de prompt s’exécute ensuite sur la carte unique résultante : -1. **Prompt système propre au direct** (`direct[""].systemPrompt`) : utilisé lorsque l’entrée de pair spécifique existe dans la carte **et** que sa clé `systemPrompt` est définie. Si `systemPrompt` est une chaîne vide (`""`), le caractère générique est supprimé et aucun prompt système n’est appliqué. -2. **Prompt système générique direct** (`direct["*"].systemPrompt`) : utilisé lorsque l’entrée de pair spécifique est entièrement absente de la carte, ou lorsqu’elle existe mais ne définit aucune clé `systemPrompt`. +1. **Invite système spécifique au direct** (`direct[""].systemPrompt`) : utilisée lorsque l’entrée du pair spécifique existe dans la map **et** que sa clé `systemPrompt` est définie. Si `systemPrompt` est une chaîne vide (`""`), le joker est supprimé et aucune invite système n’est appliquée. +2. **Invite système joker du direct** (`direct["*"].systemPrompt`) : utilisée lorsque l’entrée du pair spécifique est totalement absente de la map, ou lorsqu’elle existe mais ne définit aucune clé `systemPrompt`. -`dms` reste le compartiment léger de remplacement d’historique par DM (`dms..historyLimit`). Les remplacements de prompt vivent sous `direct`. +`dms` reste le bucket léger de remplacement d’historique par DM (`dms..historyLimit`). Les remplacements d’invites se trouvent sous `direct`. -**Différence avec le comportement multi-compte de Telegram :** Dans Telegram, la clé racine `groups` est volontairement supprimée pour tous les comptes dans une configuration multi-compte, même les comptes qui ne définissent aucun `groups` propre, afin d’éviter qu’un bot reçoive des messages de groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection : les clés racine `groups` et `direct` sont toujours héritées par les comptes qui ne définissent aucune substitution au niveau du compte, quel que soit le nombre de comptes configurés. Dans une configuration WhatsApp multi-compte, si vous voulez des prompts de groupe ou directs par compte, définissez explicitement la carte complète sous chaque compte plutôt que de vous appuyer sur les valeurs par défaut au niveau racine. +**Différence avec le comportement multi-compte de Telegram :** Dans Telegram, `groups` à la racine est volontairement supprimé pour tous les comptes dans une configuration multi-compte, même les comptes qui ne définissent pas leurs propres `groups`, afin d’empêcher un bot de recevoir des messages de groupes auxquels il n’appartient pas. WhatsApp n’applique pas cette protection : `groups` et `direct` à la racine sont toujours hérités par les comptes qui ne définissent aucun remplacement au niveau du compte, quel que soit le nombre de comptes configurés. Dans une configuration WhatsApp multi-compte, si vous voulez des invites de groupe ou de direct par compte, définissez explicitement la map complète sous chaque compte plutôt que de vous appuyer sur les valeurs par défaut au niveau racine. Comportement important : -- `channels.whatsapp.groups` est à la fois une carte de configuration par groupe et la liste d’autorisation des groupes au niveau du chat. À la portée racine ou compte, `groups["*"]` signifie « tous les groupes sont admis » pour cette portée. -- N’ajoutez un `systemPrompt` de groupe générique que si vous voulez déjà que cette portée admette tous les groupes. Si vous voulez toujours que seul un ensemble fixe d’ID de groupes soit éligible, n’utilisez pas `groups["*"]` pour la valeur par défaut du prompt. Répétez plutôt le prompt sur chaque entrée de groupe explicitement autorisée. -- L’admission des groupes et l’autorisation de l’expéditeur sont des vérifications distinctes. `groups["*"]` élargit l’ensemble des groupes qui peuvent atteindre le traitement des groupes, mais n’autorise pas à lui seul tous les expéditeurs de ces groupes. L’accès des expéditeurs reste contrôlé séparément par `channels.whatsapp.groupPolicy` et `channels.whatsapp.groupAllowFrom`. -- `channels.whatsapp.direct` n’a pas le même effet de bord pour les DM. `direct["*"]` fournit uniquement une configuration par défaut pour les chats directs après qu’un DM a déjà été admis par `dmPolicy` plus `allowFrom` ou les règles du magasin d’appairage. +- `channels.whatsapp.groups` est à la fois une map de configuration par groupe et la liste d’autorisation des groupes au niveau du chat. À la racine comme au niveau du compte, `groups["*"]` signifie « tous les groupes sont admis » pour cette portée. +- N’ajoutez un `systemPrompt` de groupe joker que si vous voulez déjà que cette portée admette tous les groupes. Si vous voulez toujours que seul un ensemble fixe d’ID de groupes soit éligible, n’utilisez pas `groups["*"]` comme valeur par défaut de l’invite. Répétez plutôt l’invite sur chaque entrée de groupe explicitement autorisée. +- L’admission des groupes et l’autorisation des expéditeurs sont deux vérifications distinctes. `groups["*"]` élargit l’ensemble des groupes pouvant atteindre le traitement des groupes, mais n’autorise pas à lui seul chaque expéditeur dans ces groupes. L’accès des expéditeurs reste contrôlé séparément par `channels.whatsapp.groupPolicy` et `channels.whatsapp.groupAllowFrom`. +- `channels.whatsapp.direct` n’a pas le même effet secondaire pour les DM. `direct["*"]` fournit seulement une configuration de chat direct par défaut après qu’un DM a déjà été admis par `dmPolicy` plus `allowFrom` ou les règles du stockage d’appairage. Exemple : @@ -699,12 +699,12 @@ Champs WhatsApp à fort signal : - accès : `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` - livraison : `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` -- multi-compte : `accounts..enabled`, `accounts..authDir`, substitutions au niveau du compte +- multi-compte : `accounts..enabled`, `accounts..authDir`, remplacements au niveau du compte - opérations : `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*` - comportement de session : `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` -- prompts : `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` +- invites : `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` -## Associé +## Connexe - [Appairage](/fr/channels/pairing) - [Groupes](/fr/channels/groups) diff --git a/docs/fr/ci.md b/docs/fr/ci.md index 5fab5e8ee..1305bb48e 100644 --- a/docs/fr/ci.md +++ b/docs/fr/ci.md @@ -3,92 +3,92 @@ 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 - - Vous modifiez le routage de ClawSweeper ou le transfert de l’activité GitHub -summary: Graphe des tâches CI, contrôles de périmètre, regroupements de publication et équivalents de commandes locales + - Vous modifiez l’envoi ClawSweeper ou le transfert de l’activité GitHub +summary: Graphe des tâches CI, contrôles de périmètre, validations globales de release et équivalents des commandes locales title: Pipeline CI x-i18n: - generated_at: "2026-05-05T01:44:41Z" + generated_at: "2026-05-05T06:16:22Z" model: gpt-5.5 provider: openai - source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66 + source_hash: 31fe6704e18f9efc519a1a73fc3aa8ae3909d6a27553874eb477e73979a94af2 source_path: ci.md workflow: 16 --- -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 le graphe complet pour les candidats de release et la validation large. Les lanes Android restent opt-in via `include_android`. La couverture des Plugins réservée aux releases se trouve dans le workflow séparé [`Prépublication de Plugin`](#plugin-prerelease) et ne s’exécute qu’à partir de [`Validation complète de release`](#full-release-validation) ou d’un déclenchement manuel explicite. +OpenClaw CI s’exécute à chaque push vers `main` et à chaque pull request. Le job `preflight` classe le diff et désactive les lanes coûteuses lorsque seules des zones sans lien ont changé. Les exécutions manuelles `workflow_dispatch` contournent intentionnellement le cadrage intelligent et déploient tout le graphe pour les release candidates et la validation large. Les lanes Android restent optionnelles 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 que depuis [`Full Release Validation`](#full-release-validation) ou un déclenchement manuel explicite. ## Vue d’ensemble du pipeline -| Job | Objectif | Quand il s’exécute | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | -| `preflight` | Détecter les changements docs-only, les périmètres modifiés, les extensions modifiées et construire le manifeste CI | Toujours sur les pushs non brouillons et les PR | -| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushs non brouillons et les PR | -| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux avis npm | Toujours sur les pushs non brouillons et les PR | -| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs non brouillons et les PR | -| `check-dependencies` | Passe Knip de production limitée aux dépendances, plus garde allowlist 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` | Lanes de correction Linux rapides, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node | -| `checks-fast-contracts-channels` | Vérifications sharded des contrats de canaux avec un résultat de vérification agrégé stable | Changements pertinents pour Node | -| `checks-node-core-test` | Shards de tests Node du cœur, hors lanes de canaux, bundled, contrats et extensions | Changements pertinents pour Node | -| `check` | Équivalent sharded de la porte locale principale : types prod, lint, gardes, types de test et smoke strict | Changements pertinents pour Node | -| `check-additional` | Architecture, drift sharded des frontières/prompts, gardes d’extension, frontière de package et Gateway watch | Changements pertinents pour Node | -| `build-smoke` | Tests smoke de la 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` | Lane de build et smoke de compatibilité Node 22 | Déclenchement CI manuel pour les releases | -| `check-docs` | Formatage, lint et vérifications de liens brisés de la documentation | Docs modifiées | -| `skills-python` | Ruff + pytest pour les skills adossées à Python | Changements pertinents pour les skills Python | -| `checks-windows` | Tests de processus/chemins propres à Windows, plus régressions partagées des spécificateurs d’import runtime | 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 par Codex des tests lents après activité fiable | Succès de la CI principale ou dispatch manuel | -| `openclaw-performance` | Rapports de performance runtime Kova quotidiens/à la demande avec lanes mock-provider, deep-profile et GPT 5.4 live | Dispatch planifié et 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 pushes et PR non brouillons | +| `security-scm-fast` | Détection de clés privées et audit de workflow via `zizmor` | Toujours sur les pushes et PR non brouillons | +| `security-dependency-audit` | Audit du lockfile de production, sans dépendances, par rapport aux advisories npm | Toujours sur les pushes et PR non brouillons | +| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushes et PR non brouillons | +| `check-dependencies` | Passe Knip de production limitée aux dépendances, plus garde de la liste d’autorisation des fichiers inutilisés | Changements liés à Node | +| `build-artifacts` | Construire `dist/`, l’UI de contrôle, les vérifications d’artefacts construits et les artefacts réutilisables en aval | Changements liés à Node | +| `checks-fast-core` | Lanes rapides de correction Linux, comme les vérifications groupées/contrat Plugin/protocole | Changements liés à Node | +| `checks-fast-contracts-channels` | Vérifications fragmentées des contrats de canaux avec un résultat agrégé stable | Changements liés à Node | +| `checks-node-core-test` | Fragments de tests Core Node, hors lanes canal, groupées, contrat et extension | Changements liés à Node | +| `check` | Équivalent fragmenté de la gate locale principale : types prod, lint, gardes, types de test et smoke strict | Changements liés à Node | +| `check-additional` | Architecture, dérive fragmentée des limites/prompts, gardes d’extension, limite de package et surveillance Gateway | Changements liés à Node | +| `build-smoke` | Tests smoke de la CLI construite et smoke mémoire au démarrage | Changements liés à Node | +| `checks` | Vérificateur pour les tests de canaux sur artefacts construits | Changements liés à Node | +| `checks-node-compat-node22` | Build de compatibilité Node 22 et lane smoke | Déclenchement manuel CI pour les releases | +| `check-docs` | Formatage, lint et vérifications de liens cassés des docs | Docs modifiées | +| `skills-python` | Ruff + pytest pour les Skills adossées à Python | Changements liés aux Skills Python | +| `checks-windows` | Tests spécifiques à Windows sur processus/chemins, plus régressions partagées de spécificateurs d’import runtime | Changements liés à Windows | +| `macos-node` | Lane de tests TypeScript macOS utilisant les artefacts construits partagés | Changements liés à macOS | +| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements liés à macOS | +| `android` | Tests unitaires Android pour les deux saveurs, plus un build APK de debug | Changements liés à Android | +| `test-performance-agent` | Optimisation quotidienne des tests lents Codex après activité fiable | Succès CI principal ou déclenchement manuel | +| `openclaw-performance` | Rapports quotidiens/à la demande de performance runtime Kova avec lanes fournisseur mock, profil profond et GPT 5.4 live | Déclenchement planifié et manuel | -## Ordre fail-fast +## Ordre d’échec rapide 1. `preflight` décide quelles lanes existent réellement. Les logiques `docs-scope` et `changed-scope` sont des étapes dans ce job, pas 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` chevauche les lanes Linux rapides afin que les consommateurs aval puissent démarrer dès que le build partagé est prêt. -4. Les lanes 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`. +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 artefacts et plateformes. +3. `build-artifacts` chevauche les lanes Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt. +4. Les lanes plus lourdes de plateforme 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`. -GitHub peut marquer les jobs supplantés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou ref `main`. Traitez cela comme du bruit CI, sauf si l’exécution la plus récente pour la même ref échoue aussi. Les vérifications agrégées des shards utilisent `!cancelled() && always()` afin de toujours signaler les échecs normaux de shards, mais sans se mettre en file après que tout le workflow a déjà été supplanté. La clé de concurrence CI automatique est versionnée (`CI-v7-*`), afin qu’un zombie côté GitHub dans un ancien groupe de file ne puisse pas bloquer indéfiniment les exécutions plus récentes sur main. 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 supplanté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 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 signaler quand même les échecs normaux de fragments, sans se mettre en file après que tout le workflow a déjà été supplanté. La clé de concurrence CI automatique est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file 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. -## Périmètre et routage +## Scope et routage -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é. +La logique de scope se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`. Le déclenchement manuel ignore la détection changed-scope et fait agir le manifeste preflight comme si chaque zone scopée avait changé. -- **Les modifications de workflows CI** valident le graphe CI Node plus le linting de 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 plateforme. -- **Les modifications limitées au routage CI, certaines modifications de fixtures de tests cœur peu coûteuses, et les modifications étroites d’aides/tests de routage des contrats de Plugin** utilisent un chemin de manifeste rapide limité à Node : `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 canaux, les shards complets du cœur, les shards de Plugins bundled et les matrices de gardes additionnelles lorsque le changement est limité aux surfaces de routage ou d’aides que la tâche rapide exerce directement. -- **Les vérifications Windows Node** sont limitées aux wrappers de processus/chemins propres à Windows, aux aides de runners npm/pnpm/UI, à la configuration de gestionnaire de packages et aux surfaces de workflows CI qui exécutent cette lane ; les changements sans rapport de sources, de Plugins, d’install-smoke et de tests seuls restent sur les lanes Linux Node. +- **Les modifications des workflows CI** valident le graphe CI Node et le linting de workflow, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces lanes 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 core, et les modifications étroites d’aides/tests de routage de contrats Plugin** utilisent un chemin de manifeste rapide limité à Node : `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 canaux, les fragments core complets, les fragments de Plugins groupés et les matrices de gardes additionnelles lorsque le changement se limite aux surfaces de routage ou d’aides que la tâche rapide exerce directement. +- **Les vérifications Node Windows** sont limitées aux wrappers processus/chemins spécifiques à Windows, aux aides npm/pnpm/runner UI, à la config de gestionnaire de packages et aux surfaces de workflow CI qui exécutent cette lane ; les changements de sources, Plugin, install-smoke et tests seuls sans lien restent sur les lanes Linux Node. -Les familles de tests Node les plus lentes sont divisées ou équilibrées afin que chaque job reste petit sans réserver trop de runners : les contrats de canaux s’exécutent en trois shards pondérés, les lanes rapides/support d’unités cœur s’exécutent séparément, l’infrastructure runtime cœur est divisée entre shards d’état et de processus/config, auto-reply s’exécute avec des workers équilibrés (avec le sous-arbre reply divisé en shards agent-runner, dispatch et commands/state-routing), et les configurations agentiques Gateway/server sont divisées entre lanes chat/auth/model/http-plugin/runtime/startup 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 catch-all partagé des Plugins. Les shards par 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 configuration complète d’un shard 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 ; la liste des gardes de frontière est répartie sur quatre shards de matrice, chacun exécutant des gardes indépendantes sélectionnées en parallèle et affichant les timings par vérification, y compris `pnpm prompt:snapshots:check`, afin que le drift des prompts du chemin heureux du runtime Codex soit rattaché à la PR qui l’a causé. Gateway watch, les tests de canaux et le shard de frontière de support du cœur s’exécutent en parallèle dans `build-artifacts` après que `dist/` et `dist-runtime/` ont déjà été construits. +Les familles de tests Node les plus lentes sont découpé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 lanes core unit fast/support s’exécutent séparément, l’infrastructure runtime core est répartie entre des fragments state et process/config, auto-reply s’exécute en workers équilibrés (avec le sous-arbre reply découpé en fragments agent-runner, dispatch et commands/state-routing), et les configs agentic gateway/server sont réparties entre les lanes chat/auth/model/http-plugin/runtime/startup au lieu d’attendre les artefacts construits. Les tests larges navigateur, QA, média et Plugins divers utilisent leurs configs Vitest dédiées au lieu du catch-all Plugin partagé. Les fragments par motifs d’inclusion enregistrent les entrées de timing avec le nom de fragment CI, afin que `.artifacts/vitest-shard-timings.json` puisse distinguer une config entière d’un fragment filtré. `check-additional` regroupe le travail de compilation/canary package-boundary et sépare l’architecture de topologie runtime de la couverture de surveillance Gateway ; la liste des gardes de limites est répartie sur quatre fragments de matrice, chacun exécutant des gardes indépendants sélectionnés en parallèle et imprimant les timings par vérification, y compris `pnpm prompt:snapshots:check` afin que la dérive du prompt du chemin heureux runtime Codex soit rattachée à la PR qui l’a causée. La surveillance Gateway, les tests de canaux et le fragment support-boundary core s’exécutent en parallèle dans `build-artifacts` une fois `dist/` et `dist-runtime/` déjà construits. -La CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. Le flavor third-party n’a pas de source set ni de manifeste séparés ; sa lane de tests unitaires compile tout de même le flavor avec les indicateurs BuildConfig SMS/call-log, tout en évitant un job de packaging APK debug dupliqué à chaque push pertinent pour Android. +Android CI exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK de debug Play. La saveur tierce n’a pas de source set ni de manifeste séparé ; sa lane de tests unitaires compile quand même la saveur avec les indicateurs BuildConfig SMS/journal d’appels, tout en évitant un job de packaging APK de debug en double à chaque push lié à Android. -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 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 de Knip avec `scripts/deadcode-unused-files.allowlist.mjs`. La 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 pont de packages que Knip ne peut pas résoudre statiquement. +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 publication de pnpm désactivé pour l’installation `dlx`) et `pnpm deadcode:unused-files`, qui compare les constats de fichiers de production inutilisés de Knip à `scripts/deadcode-unused-files.allowlist.mjs`. La garde unused-file échoue lorsqu’une PR ajoute un nouveau fichier inutilisé non révisé ou laisse une entrée obsolète dans la liste d’autorisation, tout en préservant les surfaces intentionnelles de Plugins dynamiques, générées, de build, de tests live et de ponts de packages que Knip ne peut pas résoudre statiquement. ## Transfert de l’activité ClawSweeper -`.github/workflows/clawsweeper-dispatch.yml` est le pont côté cible entre l’activité du dépôt OpenClaw et ClawSweeper. Il ne checkout ni n’exécute de code de pull request non fiable. Le workflow crée un jeton GitHub App à partir de `CLAWSWEEPER_APP_PRIVATE_KEY`, puis envoie des payloads `repository_dispatch` compacts à `openclaw/clawsweeper`. +`.github/workflows/clawsweeper-dispatch.yml` est le pont côté cible depuis l’activité du dépôt OpenClaw vers ClawSweeper. Il ne checkout pas et n’exécute pas de code de pull request non fiable. Le workflow crée un jeton GitHub App à partir de `CLAWSWEEPER_APP_PRIVATE_KEY`, puis envoie des payloads `repository_dispatch` compacts à `openclaw/clawsweeper`. Le workflow comporte quatre lanes : - `clawsweeper_item` pour les demandes exactes de revue d’issues et de pull requests ; - `clawsweeper_comment` pour les commandes ClawSweeper explicites dans les commentaires d’issues ; -- `clawsweeper_commit_review` pour les demandes de revue au niveau commit sur les pushs vers `main` ; +- `clawsweeper_commit_review` pour les demandes de revue au niveau commit sur les pushes vers `main` ; - `github_activity` pour l’activité GitHub générale que l’agent ClawSweeper peut inspecter. -La lane `github_activity` transfère uniquement des métadonnées normalisées : type d’événement, action, acteur, dépôt, numéro d’item, URL, titre, état et courts extraits pour les commentaires ou revues lorsqu’ils sont présents. Elle évite intentionnellement de transférer le corps complet du Webhook. Le workflow récepteur dans `openclaw/clawsweeper` est `.github/workflows/github-activity.yml`, qui publie l’événement normalisé vers le hook OpenClaw Gateway pour l’agent ClawSweeper. +La lane `github_activity` transfère uniquement les métadonnées normalisées : type d’événement, action, acteur, dépôt, numéro d’élément, URL, titre, état et courts extraits de commentaires ou de revues lorsqu’ils sont présents. Elle évite intentionnellement de transférer le corps complet du Webhook. Le workflow récepteur dans `openclaw/clawsweeper` est `.github/workflows/github-activity.yml`, qui publie l’événement normalisé dans le hook OpenClaw Gateway pour l’agent ClawSweeper. -L’activité générale relève de l’observation, pas d’une livraison par défaut. L’agent ClawSweeper reçoit la cible Discord dans son prompt et ne doit publier dans `#clawsweeper` que lorsque l’événement est surprenant, actionnable, risqué ou utile opérationnellement. Les ouvertures, modifications, bruit de bots, bruit de Webhooks dupliqués et trafic normal de revue doivent produire `NO_REPLY`. +L’activité générale relève de l’observation, pas de la livraison par défaut. L’agent ClawSweeper reçoit la cible Discord dans son prompt et ne doit publier dans `#clawsweeper` que lorsque l’événement est surprenant, actionnable, risqué ou utile sur le plan opérationnel. Les ouvertures routinières, modifications, bruit de bots, bruit de Webhook dupliqué et trafic de revue normal doivent produire `NO_REPLY`. -Traitez les titres, commentaires, corps, textes de revue, noms de branches et messages de commit GitHub comme des données non fiables sur tout ce chemin. Ce sont des entrées pour la synthèse et le triage, pas des instructions pour le workflow ou le runtime de l’agent. +Traitez les titres, commentaires, corps, textes de revue, noms de branches et messages de commit GitHub comme des données non fiables tout au long de ce chemin. Ce sont des entrées pour la synthèse et le triage, pas des instructions pour le workflow ou le runtime de l’agent. -## Dispatches manuels +## Déclenchements manuels -Les dispatches CI manuels exécutent le même graphe de jobs que la CI normale, mais activent de force chaque lane à portée non Android : shards Linux Node, shards de plugins groupés, contrats de canaux, compatibilité Node 22, `check`, `check-additional`, smoke de build, vérifications de docs, Skills Python, Windows, macOS et i18n de Control UI. Les dispatches CI manuels autonomes exécutent uniquement Android avec `include_android=true`; l’umbrella de version complète active Android en passant `include_android=true`. Les vérifications statiques de préversion de Plugin, le shard `agentic-plugins` réservé aux releases, le balayage complet par lots des extensions et les lanes Docker de préversion de Plugin sont exclus de la CI. La suite de préversion Docker s’exécute uniquement lorsque `Full Release Validation` dispatche le workflow `Plugin Prerelease` séparé avec la gate de validation de release activée. +Les dispatchs CI manuels exécutent le même graphe de tâches que la CI normale, mais forcent l’activation de chaque lane à portée non Android : shards Linux Node, shards de plugins intégrés, contrats de canaux, compatibilité Node 22, `check`, `check-additional`, smoke de build, vérifications docs, Skills Python, Windows, macOS et i18n Control UI. Les dispatchs CI manuels autonomes exécutent uniquement Android avec `include_android=true` ; l’ombrelle de release complète active Android en passant `include_android=true`. Les vérifications statiques de prérelease Plugin, le shard `agentic-plugins` réservé aux releases, le balayage complet par lot des extensions et les lanes Docker de prérelease Plugin sont exclus de la CI. La suite Docker de prérelease s’exécute uniquement lorsque `Full Release Validation` dispatche le workflow `Plugin Prerelease` distinct avec la gate de validation de release activée. -Les exécutions manuelles utilisent un groupe de concurrence unique afin qu’une suite complète de version candidate ne soit pas annulée par une autre exécution de push ou de PR sur la même ref. L’entrée facultative `target_ref` permet à un appelant de confiance d’exécuter ce graphe contre une branche, un tag ou un SHA de commit complet tout en utilisant le fichier de workflow de la ref 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 une autre exécution de push ou de PR sur la même ref. L’entrée facultative `target_ref` permet à un appelant de confiance d’exécuter ce graphe sur une branche, une balise ou un SHA de commit complet tout en utilisant le fichier de workflow de la ref de dispatch sélectionnée. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runners -| Runner | Jobs | +| Runner | Tâches | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, jobs de sécurité rapides et agrégats (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/plugins groupés, vérifications de contrats de canaux shardées, shards `check` sauf lint, shards 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 | +| `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/intégrés, vérifications de contrats de canaux en shards, shards `check` sauf lint, shards et agrégats `check-additional`, vérificateurs d’agrégats de tests Node, vérifications 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 d’attente plus tôt | | `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards 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, shards de tests Linux Node, shards 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 d’attente de file 32 vCPU coûtait plus qu’il n’économisait) | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de tests Linux Node, shards de tests de plugins intégrés, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (assez sensible au CPU pour que 8 vCPU coûtent plus qu’ils n’économisaient) ; builds Docker install-smoke (le temps de file d’attente 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 rabattent sur `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks se rabattent sur `macos-latest` | ## Équivalents locaux @@ -145,30 +145,30 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3 ``` -Un dispatch manuel benchmarke normalement la ref du workflow. Définissez `target_ref` pour benchmarker un tag de release ou une autre branche avec l’implémentation actuelle du workflow. Les chemins de rapports publiés et les pointeurs latest sont indexés par la ref testée, et chaque `index.md` enregistre la ref/SHA testé, la ref/SHA du workflow, la ref Kova, le profil, le mode d’authentification de lane, le modèle, le nombre de répétitions et les filtres de scénarios. +Le dispatch manuel benchmarke normalement la ref du workflow. Définissez `target_ref` pour benchmarker une balise de release ou une autre branche avec l’implémentation actuelle du workflow. Les chemins de rapports publiés et les pointeurs latest sont indexés par la ref testée, et chaque `index.md` consigne la ref/SHA testé, la ref/SHA du workflow, la ref Kova, le profil, le mode d’authentification de lane, le modèle, le nombre de répétitions et les filtres de scénario. Le workflow installe OCM depuis une release épinglée et Kova depuis `openclaw/Kova` à l’entrée `kova_ref` épinglée, puis exécute trois lanes : -- `mock-provider` : scénarios de diagnostic Kova contre un runtime buildé localement avec une fausse authentification déterministe compatible OpenAI. -- `mock-deep-profile` : profilage CPU/tas/trace pour les points chauds au démarrage, dans le Gateway et lors d’un tour d’agent. -- `live-gpt54` : un vrai tour d’agent OpenAI `openai/gpt-5.4`, ignoré quand `OPENAI_API_KEY` n’est pas disponible. +- `mock-provider` : scénarios de diagnostic Kova contre un runtime de build local avec une authentification compatible OpenAI factice et déterministe. +- `mock-deep-profile` : profilage CPU/heap/trace pour les points chauds de démarrage, Gateway et tour d’agent. +- `live-gpt54` : un vrai tour d’agent OpenAI `openai/gpt-5.4`, ignoré lorsque `OPENAI_API_KEY` n’est pas disponible. -La lane mock-provider exécute aussi des sondes de source natives OpenClaw après le passage Kova : timing de démarrage du Gateway et mémoire dans les cas de démarrage par défaut, avec hook et avec 50 plugins ; boucles répétées de salutations `channel-chat-baseline` mock-OpenAI ; et commandes de démarrage CLI contre le Gateway démarré. Le résumé Markdown des sondes de source se trouve dans `source/index.md` dans le bundle de rapport, avec le JSON brut à côté. +La lane mock-provider exécute aussi des sondes source natives OpenClaw après le passage Kova : timing de démarrage Gateway et mémoire pour les cas de démarrage par défaut, hook et 50 plugins ; boucles hello répétées mock-OpenAI `channel-chat-baseline` ; et commandes de démarrage CLI contre le Gateway démarré. Le résumé Markdown des sondes source se trouve dans `source/index.md` dans le bundle de rapport, avec le JSON brut à côté. -Chaque lane téléverse des artefacts GitHub. Quand `CLAWGRIT_REPORTS_TOKEN` est configuré, le workflow commit aussi `report.json`, `report.md`, les bundles, `index.md` et les artefacts de sondes de source dans `openclaw/clawgrit-reports` sous `openclaw-performance//-//`. Le pointeur actuel de la ref testée est écrit sous `openclaw-performance//latest-.json`. +Chaque lane téléverse des artefacts GitHub. Lorsque `CLAWGRIT_REPORTS_TOKEN` est configuré, le workflow commit aussi `report.json`, `report.md`, les bundles, `index.md` et les artefacts de sonde source dans `openclaw/clawgrit-reports` sous `openclaw-performance//-//`. Le pointeur actuel de la ref testée est écrit comme `openclaw-performance//latest-.json`. -## Validation de release complète +## Validation complète de release -`Full Release Validation` est le workflow umbrella manuel pour « tout exécuter avant la release ». Il accepte une branche, un tag ou un SHA de commit complet, dispatche le workflow `CI` manuel avec cette cible, dispatche `Plugin Prerelease` pour les preuves réservées aux releases de Plugin/package/statique/Docker, et dispatche `OpenClaw Release Checks` pour le smoke d’installation, l’acceptation de package, les vérifications de package multi-OS, la parité QA Lab, Matrix et les lanes Telegram. Les exécutions stables/par défaut gardent la couverture exhaustive live/E2E et du chemin de release Docker derrière `run_release_soak=true` ; `release_profile=full` force l’activation de cette couverture soak afin que la validation large des avis reste large. Avec `rerun_group=all` et `release_profile=full`, il exécute aussi `NPM Telegram Beta E2E` contre l’artefact `release-package-under-test` des vérifications de release. Après publication, passez `npm_telegram_package_spec` pour réexécuter la même lane de package Telegram contre le package npm publié. +`Full Release Validation` est le workflow ombrelle manuel pour « tout exécuter avant la release ». Il accepte une branche, une balise ou un SHA de commit complet, dispatche le workflow manuel `CI` avec cette cible, dispatche `Plugin Prerelease` pour la preuve plugins/packages/statique/Docker réservée aux releases, et dispatche `OpenClaw Release Checks` pour le smoke d’installation, l’acceptation de package, les vérifications de package cross-OS, la parité QA Lab, Matrix et les lanes Telegram. Les exécutions stables/par défaut gardent la couverture live/E2E exhaustive et le chemin de release Docker derrière `run_release_soak=true` ; `release_profile=full` force cette couverture soak afin que la validation d’advisory large reste large. Avec `rerun_group=all` et `release_profile=full`, il exécute aussi `NPM Telegram Beta E2E` contre l’artefact `release-package-under-test` des vérifications de release. Après publication, passez `npm_telegram_package_spec` pour relancer la même lane de package Telegram contre le package npm publié. -Voir [validation de release complète](/fr/reference/full-release-validation) pour la -matrice d’étapes, les noms exacts des jobs de workflow, les différences de -profils, les artefacts et les handles de réexécution ciblée. +Consultez [Validation complète de release](/fr/reference/full-release-validation) pour la +matrice d’étapes, les noms exacts des tâches de workflow, les différences de profils, les artefacts et +les handles de relance ciblés. `OpenClaw Release Publish` est le workflow de release manuel et mutateur. Dispatchez-le -depuis `release/YYYY.M.D` ou `main` après l’existence du tag de release et après la +depuis `release/YYYY.M.D` ou `main` après l’existence de la balise de release et après la réussite du preflight npm OpenClaw. Il vérifie `pnpm plugins:sync:check`, -dispatche `Plugin NPM Release` pour tous les packages de Plugin publiables, dispatche +dispatche `Plugin NPM Release` pour tous les packages Plugin publiables, dispatche `Plugin ClawHub Release` pour le même SHA de release, puis seulement ensuite dispatche `OpenClaw NPM Release` avec le `preflight_run_id` enregistré. @@ -180,39 +180,39 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Pour une preuve par commit épinglé sur une branche qui évolue vite, utilisez l’aide au lieu de +Pour une preuve de commit épinglé sur une branche qui évolue vite, utilisez l’assistant au lieu de `gh workflow run ... --ref main -f ref=` : ```bash pnpm ci:full-release --sha ``` -Les refs de dispatch de workflow GitHub doivent être des branches ou des tags, pas des SHA de commit bruts. L’aide pousse une branche temporaire `release-ci/-...` au SHA cible, +Les refs de dispatch de workflow GitHub doivent être des branches ou des balises, pas des SHA de commit bruts. L’assistant pousse une branche temporaire `release-ci/-...` au SHA cible, dispatche `Full Release Validation` depuis cette ref épinglée, vérifie que chaque -workflow enfant a un `headSha` qui correspond à la cible, et supprime la branche temporaire quand -l’exécution se termine. Le vérificateur umbrella échoue aussi si un workflow enfant s’est exécuté à un +workflow enfant `headSha` correspond à la cible, et supprime la branche temporaire lorsque +l’exécution se termine. Le vérificateur ombrelle échoue aussi si un workflow enfant s’est exécuté sur un SHA différent. -`release_profile` contrôle l’étendue live/fournisseur transmise aux vérifications de publication. Les workflows de publication manuels utilisent `stable` par défaut ; utilisez `full` uniquement lorsque vous voulez intentionnellement la large matrice consultative de fournisseurs/médias. `run_release_soak` contrôle si les vérifications de publication stables/par défaut exécutent le soak exhaustif live/E2E et Docker du chemin de publication ; `full` force l’activation du soak. +`release_profile` contrôle l’étendue live/fournisseur transmise aux vérifications de publication. Les workflows de publication manuelle utilisent `stable` par défaut ; utilisez `full` seulement lorsque vous voulez intentionnellement la large matrice consultative de fournisseurs/médias. `run_release_soak` contrôle si les vérifications de publication stables/par défaut exécutent le soak exhaustif live/E2E et Docker du chemin de publication ; `full` force l’activation du soak. -- `minimum` conserve les lanes OpenAI/core critiques pour la publication les plus rapides. -- `stable` ajoute l’ensemble stable de fournisseurs/backends. +- `minimum` conserve les lanes critiques de publication OpenAI/core les plus rapides. +- `stable` ajoute l’ensemble stable de fournisseurs/back-ends. - `full` exécute la large matrice consultative de fournisseurs/médias. -L’umbrella 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 afin d’actualiser le résultat umbrella et le récapitulatif des timings. +Le workflow 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 parapluie et le résumé des timings. -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, `plugin-prerelease` uniquement pour l’enfant de prépublication de Plugin, `release-checks` pour chaque enfant de publication, ou un groupe plus restreint : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` sur l’umbrella. Cela permet de borner la relance d’une boîte de publication échouée après un correctif ciblé. Pour une lane cross-OS échouée, combinez `rerun_group=cross-os` avec `cross_os_suite_filter`, par exemple `windows/packaged-upgrade` ; les longues commandes cross-OS émettent des lignes Heartbeat et les récapitulatifs packaged-upgrade incluent les timings par phase. Les lanes QA des release-checks sont consultatives, donc les échecs QA uniquement avertissent, mais ne bloquent pas le vérificateur des release-checks. +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, `plugin-prerelease` uniquement pour l’enfant de prépublication de Plugin, `release-checks` pour chaque enfant de publication, ou un groupe plus restreint : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` sur le workflow parapluie. Cela permet de borner la relance d’une boîte de publication échouée après une correction ciblée. Pour une seule lane cross-OS échouée, combinez `rerun_group=cross-os` avec `cross_os_suite_filter`, par exemple `windows/packaged-upgrade` ; les longues commandes cross-OS émettent des lignes de heartbeat et les résumés packaged-upgrade incluent les timings par phase. Les lanes QA des vérifications de publication sont consultatives ; les échecs uniquement QA avertissent donc sans bloquer le vérificateur des vérifications de publication. -`OpenClaw Release Checks` utilise la référence de workflow de confiance pour résoudre la référence sélectionnée une fois en une archive `release-package-under-test`, puis transmet cet artefact aux vérifications cross-OS et à Package Acceptance, ainsi qu’au workflow Docker live/E2E du chemin de publication lorsque la couverture de soak s’exécute. Cela garde les octets du package cohérents entre les boîtes de publication et évite de reconditionner le même candidat dans plusieurs tâches enfants. +`OpenClaw Release Checks` utilise la ref de workflow approuvée pour résoudre la ref sélectionnée une fois en une archive tar `release-package-under-test`, puis transmet cet artefact aux vérifications cross-OS et à l’acceptation du package, ainsi qu’au workflow Docker live/E2E du chemin de publication lorsque la couverture de soak s’exécute. Cela garde les octets du package cohérents entre les boîtes de publication et évite de reconditionner le même candidat dans plusieurs tâches enfants. -Les exécutions `Full Release Validation` dupliquées pour `ref=main` et `rerun_group=all` -remplacent l’umbrella plus ancien. Le moniteur parent annule tout workflow enfant -qu’il a déjà déclenché lorsque le parent est annulé, afin que la validation main -plus récente ne reste pas derrière une ancienne exécution de release-check de deux heures. La validation de branche/tag de publication et les groupes de relance ciblés conservent `cancel-in-progress: false`. +Les exécutions `Full Release Validation` en double pour `ref=main` et `rerun_group=all` +remplacent le workflow parapluie plus ancien. Le moniteur parent annule tout workflow enfant +qu’il a déjà déclenché lorsque le parent est annulé, de sorte qu’une validation main plus récente +ne reste pas bloquée derrière une exécution obsolète de vérifications de publication de deux heures. La validation de branche/tag de publication et les groupes de relance ciblés conservent `cancel-in-progress: false`. -## Shards live et E2E +## Fragments live et E2E -L’enfant live/E2E de publication conserve une large couverture native `pnpm test:live`, mais l’exécute sous forme de shards nommés via `scripts/test-live-shard.mjs` au lieu d’une seule tâche série : +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érielle : - `native-live-src-agents` - `native-live-src-gateway-core` @@ -224,61 +224,61 @@ L’enfant live/E2E de publication conserve une large couverture native `pnpm te - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- shards média audio/vidéo séparés et shards musique filtrés par fournisseur +- fragments audio/vidéo média 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 shards 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 é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 des relances manuelles ponctuelles. -Les shards média 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édia vérifient seulement les binaires avant la configuration. Gardez les suites live adossées à Docker sur des runners Blacksmith normaux — les tâches conteneurisées ne sont pas le bon endroit pour lancer des tests Docker imbriqués. +Les fragments média 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édia vérifient seulement les binaires avant la configuration. Gardez les suites live adossées à Docker sur des runners Blacksmith normaux : les tâches conteneurisées ne sont pas l’endroit approprié pour lancer des tests Docker imbriqués. -Les shards live modèle/backend adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:` par commit sélectionné. Le workflow de publication live construit et pousse cette image une seule fois, puis les shards modèle live Docker, Gateway segmenté par fournisseur, backend CLI, liaison ACP et harnais Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Les shards Docker Gateway portent des plafonds explicites de `timeout` au niveau du script, inférieurs au délai d’expiration de la tâche du workflow, afin qu’un conteneur bloqué ou un chemin de nettoyage échoue rapidement au lieu de consommer tout le budget des release-checks. Si ces shards reconstruisent indépendamment la cible Docker source complète, l’exécution de publication est mal configurée et gaspillera du temps réel sur des constructions d’image dupliquées. +Les fragments live de modèles/back-ends adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:` pour chaque commit sélectionné. Le workflow de publication live construit et pousse cette image une fois, puis les fragments Docker live de modèles, Gateway par fournisseur, back-end CLI, liaison ACP et harnais Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Les fragments Gateway Docker portent des limites `timeout` explicites au niveau du script, inférieures au délai d’expiration de la tâche du workflow, afin qu’un conteneur bloqué ou un chemin de nettoyage échoue rapidement au lieu de consommer tout le budget des vérifications de publication. 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 réel en constructions d’images dupliquées. -## Package Acceptance +## Acceptation du package -Utilisez `Package Acceptance` lorsque la question est : « ce package OpenClaw installable fonctionne-t-il comme produit ? » C’est différent de la CI normale : la CI normale valide l’arborescence source, tandis que Package Acceptance valide une seule archive via le même harnais Docker E2E que les utilisateurs exercent après une installation ou une 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 du package valide une seule archive tar via le même harnais Docker E2E que les utilisateurs exercent après installation ou mise à jour. ### Tâches -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 comme artefact `package-under-test`, et imprime 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 de l’archive, prépare les images Docker package-digest si nécessaire, et exécute les lanes 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 distribue ces lanes 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 spec npm publiée. -4. `summary` fait échouer le workflow si la résolution du package, l’acceptation Docker ou la lane Telegram optionnelle a échoué. +1. `resolve_package` extrait `workflow_ref`, résout un candidat package unique, é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 de l’archive tar, prépare les images Docker à résumé de package si nécessaire, et exécute les lanes Docker sélectionnées contre ce package au lieu de conditionner 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 diffuse ces lanes 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 l’acceptation du package 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 du package, l’acceptation Docker ou la lane Telegram facultative a échoué. ### Sources de candidats -- `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 de prépublication/stable publiée. -- `source=ref` package une branche, un tag ou un SHA de commit complet `package_ref` de confiance. Le résolveur récupère les branches/tags OpenClaw, vérifie que le commit sélectionné est atteignable depuis l’historique des branches du dépôt ou un tag de publication, installe les dépendances dans un worktree détaché, puis le package 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 cela pour l’acceptation de prépublication/publication stable publiée. +- `source=ref` conditionne une branche, un tag ou un SHA de commit complet `package_ref` approuvé. Le résolveur récupère les branches/tags OpenClaw, vérifie que le commit sélectionné est joignable depuis l’historique de branche du dépôt ou depuis un tag de publication, installe les dépendances dans un worktree détaché, puis le conditionne 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 optionnel, mais devrait être fourni pour les artefacts partagés en externe. +- `source=artifact` télécharge un seul `.tgz` depuis `artifact_run_id` et `artifact_name` ; `package_sha256` est facultatif mais devrait ê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 packagé 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. +Gardez `workflow_ref` et `package_ref` séparés. `workflow_ref` est le code de workflow/harnais approuvé qui exécute le test. `package_ref` est le commit source qui est conditionné lorsque `source=ref`. Cela permet au harnais de test actuel de valider d’anciens commits source approuvés sans exécuter une 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`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update` - `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full` — chunks complets Docker du chemin de publication avec OpenWebUI +- `full` — fragments Docker complets du chemin de publication avec OpenWebUI - `custom` — `docker_lanes` exactes ; requis lorsque `suite_profile=custom` -Le profil `package` utilise une couverture Plugin hors ligne afin que la validation du package publié ne dépende pas de la disponibilité live de ClawHub. La lane Telegram optionnelle réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, avec le chemin de spec npm publiée conservé pour les déclenchements autonomes. +Le profil `package` utilise une couverture Plugin hors ligne afin que la validation de package publié ne dépende pas de la disponibilité live de ClawHub. La lane Telegram facultative réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, tandis que le chemin de spécification npm publiée est conservé pour les déclenchements autonomes. -Pour la politique dédiée de test des mises à jour et des Plugins, y compris les commandes locales, -les lanes Docker, les entrées Package Acceptance, les valeurs par défaut de publication et le triage des échecs, +Pour la politique dédiée de mise à jour et de test des Plugins, y compris les commandes locales, +les lanes Docker, les entrées d’acceptation du package, les valeurs par défaut de publication et le triage des échecs, consultez [Tester les mises à jour et les Plugins](/fr/help/testing-updates-plugins). -Les release checks appellent Package Acceptance avec `source=artifact`, l’artefact de package de publication préparé, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` et `telegram_mode=mock-openai`. Cela garde la preuve de migration de package, mise à jour, nettoyage de dépendances de Plugin obsolètes, réparation d’installation de Plugin configuré, Plugin hors ligne, mise à jour de Plugin et Telegram sur la même archive de package résolue. Définissez `package_acceptance_package_spec` sur Full Release Validation ou OpenClaw Release Checks pour exécuter cette même matrice contre un package npm livré plutôt que l’artefact construit depuis le SHA. Les release checks cross-OS couvrent toujours l’onboarding, l’installeur et le comportement de plateforme propres à l’OS ; la validation produit package/mise à jour devrait commencer par Package Acceptance. La lane Docker `published-upgrade-survivor` valide une base de référence de package publié par exécution dans le chemin de publication bloquant. Dans Package Acceptance, l’archive `package-under-test` résolue est toujours le candidat et `published_upgrade_survivor_baseline` sélectionne la base de référence publiée de repli, avec `openclaw@latest` par défaut ; les commandes de relance de lane échouée préservent cette base de référence. Full Release Validation avec `run_release_soak=true` ou `release_profile=full` définit `published_upgrade_survivor_baselines=all-since-2026.4.23` et `published_upgrade_survivor_scenarios=reported-issues` pour étendre la couverture à chaque publication npm stable de `2026.4.23` à `latest` et à des fixtures calquées sur les issues pour la configuration Feishu, les fichiers bootstrap/persona préservés, les installations de Plugin OpenClaw configurées, les chemins de journaux avec tilde et les racines de dépendances de Plugin héritées obsolètes. Le workflow distinct `Update Migration` utilise la lane Docker `update-migration` avec `all-since-2026.4.23` et `plugin-deps-cleanup` lorsque la question porte sur le nettoyage exhaustif des mises à jour publiées, et non sur l’étendue normale de la CI Full Release. Les exécutions agrégées locales peuvent passer des specs de package exactes avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, conserver une seule lane avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` telle que `openclaw@2026.4.15`, ou définir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` pour la matrice de scénarios. La lane publiée configure la base de référence avec une recette de commande `openclaw config set` intégrée, enregistre les étapes de recette dans `summary.json`, et sonde `/healthz`, `/readyz`, ainsi que le statut RPC après le démarrage du Gateway. Les lanes Windows fresh packagées et installeur vérifient également qu’un package installé peut importer un remplacement browser-control depuis un chemin Windows absolu brut. Le smoke agent-turn cross-OS OpenAI utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsqu’il est défini, sinon `openai/gpt-5.4`, afin que la preuve d’installation et de Gateway reste sur un modèle de test GPT-5 tout en évitant les valeurs par défaut GPT-4.x. +Les vérifications de publication appellent l’acceptation du package avec `source=artifact`, l’artefact de package de publication préparé, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` et `telegram_mode=mock-openai`. Cela garde la migration de package, la mise à jour, le nettoyage de dépendances de Plugins obsolètes, la réparation d’installation de Plugins configurés, le Plugin hors ligne, la mise à jour de Plugins et la preuve Telegram sur la même archive tar de package résolue. Définissez `package_acceptance_package_spec` sur Full Release Validation ou OpenClaw Release Checks pour exécuter cette même matrice contre un package npm publié au lieu de l’artefact construit depuis le SHA. Les vérifications de publication cross-OS couvrent toujours l’intégration, l’installeur et le comportement de plateforme propres à l’OS ; la validation produit du package/de la mise à jour devrait commencer par l’acceptation du package. La lane Docker `published-upgrade-survivor` valide une ligne de base de package publié par exécution dans le chemin de publication bloquant. Dans l’acceptation du package, l’archive tar `package-under-test` résolue est toujours le candidat et `published_upgrade_survivor_baseline` sélectionne la ligne de base publiée de repli, par défaut `openclaw@latest` ; les commandes de relance de lane échouée préservent cette ligne de base. Full Release Validation avec `run_release_soak=true` ou `release_profile=full` définit `published_upgrade_survivor_baselines='last-stable-4 2026.4.23 2026.5.2 2026.4.15'` et `published_upgrade_survivor_scenarios=reported-issues` afin d’élargir aux quatre dernières publications npm stables plus des publications de frontière de compatibilité Plugin épinglées et des fixtures en forme de problèmes pour la configuration Feishu, les fichiers bootstrap/persona préservés, les installations de Plugins OpenClaw configurées, les chemins de journaux avec tilde et les racines de dépendances de Plugins héritées obsolètes. Les sélections published-upgrade survivor multi-lignes de base sont fragmentées par ligne de base en tâches runner Docker ciblées séparées. Le workflow distinct `Update Migration` utilise la lane Docker `update-migration` avec `all-since-2026.4.23` et `plugin-deps-cleanup` lorsque la question est le nettoyage exhaustif des mises à jour publiées, et non l’étendue normale de la CI Full Release. Les exécutions agrégées locales peuvent transmettre des spécifications de package exactes avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, conserver une seule lane avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` comme `openclaw@2026.4.15`, ou définir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` pour la matrice de scénarios. La lane publiée configure la ligne de base avec une recette de commande `openclaw config set` intégrée, enregistre les étapes de recette dans `summary.json` et sonde `/healthz`, `/readyz`, ainsi que le statut RPC après le démarrage du Gateway. Les lanes fraîches Windows packagées et installeur vérifient aussi qu’un package installé peut importer une surcharge browser-control depuis un chemin Windows absolu brut. Le smoke de tour d’agent OpenAI cross-OS utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsqu’il est défini, sinon `openai/gpt-5.4`, afin que la preuve d’installation et de Gateway reste sur un modèle de test GPT-5 tout en évitant les valeurs par défaut GPT-4.x. ### Fenêtres de compatibilité héritée -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é : +L’acceptation du package dispose de fenêtres de compatibilité héritée bornées 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 ; -- `doctor-switch` peut ignorer le sous-cas de persistance `gateway install --wrapper` lorsque le package n’expose pas cet indicateur ; -- `update-channel-switch` peut élaguer les `pnpm.patchedDependencies` manquantes depuis la fixture fake git dérivée de l’archive et peut journaliser l’absence de `update.channel` persisté ; -- les smokes de Plugin peuvent lire d’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 toujours que l’enregistrement d’installation et le comportement sans réinstallation restent inchangés. +- 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` lorsque le package n’expose pas ce flag ; +- `update-channel-switch` peut retirer les `pnpm.patchedDependencies` manquantes de la fixture git factice dérivée de l’archive tar et peut journaliser l’absence de `update.channel` persisté ; +- les smokes de Plugin peuvent lire les emplacements hérités des enregistrements d’installation ou accepter l’absence de persistance d’enregistrement d’installation de 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 publié `2026.4.26` peut aussi avertir pour les fichiers d’empreinte de métadonnées de build locales qui avaient déjà été 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 paquet publié `2026.4.26` peut aussi émettre un avertissement pour des fichiers d’horodatage de métadonnées de build local qui avaient déjà été livrés. Les paquets ultérieurs doivent satisfaire aux contrats modernes ; les mêmes conditions échouent au lieu d’avertir ou d’être ignorées. ### Exemples @@ -321,151 +321,151 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Lorsque vous déboguez une exécution d’acceptation de package échouée, commencez par le récapitulatif `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 lanes, les timings de phases et les commandes de réexécution. Préférez réexécuter le profil de package échoué ou les lanes Docker exactes plutôt que de relancer la validation complète de release. +Lors du débogage d’une exécution d’acceptation de paquet échouée, commencez par le résumé `resolve_package` pour confirmer la source du paquet, sa version et son SHA-256. Inspectez ensuite l’exécution enfant `docker_acceptance` et ses artefacts Docker : `.artifacts/docker-tests/**/summary.json`, `failures.json`, les journaux des lanes, les minutages des phases et les commandes de réexécution. Préférez réexécuter le profil de paquet échoué ou les lanes Docker exactes plutôt que de relancer toute la validation de release. -## Vérification d’installation +## Test de fumée d’installation -Le workflow séparé `Install Smoke` réutilise le même script de périmètre via son propre job `preflight`. Il répartit la couverture de vérification entre `run_fast_install_smoke` et `run_full_install_smoke`. +Le workflow séparé `Install Smoke` réutilise le même script de portée via son propre job `preflight`. Il divise la couverture de fumée en `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 de Plugin SDK, Gateway, channel ou plugin cœur que les jobs de vérification Docker exercent. Les changements de plugins groupés limités aux sources, 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 du Dockerfile racine une seule fois, vérifie la CLI, exécute la vérification CLI de suppression d’agents dans l’espace de travail partagé, exécute l’e2e du réseau Gateway en conteneur, vérifie un argument de build d’extension groupée, et exécute le profil Docker borné des plugins groupés avec 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 d’installation/mise à jour pour les exécutions planifiées nocturnes, les déclenchements manuels, les vérifications de release via 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 vérification du Dockerfile racine GHCR au SHA cible, puis exécute l’installation de package QR, les vérifications du Dockerfile racine/Gateway, les vérifications d’installation/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 vérifications de l’image racine. +- **Chemin rapide** s’exécute pour les pull requests qui touchent les surfaces Docker/paquet, les changements de paquet/manifeste de plugins intégrés, ou les surfaces centrales plugin/canal/gateway/Plugin SDK exercées par les jobs de fumée Docker. Les changements de plugins intégrés limités au code 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 une fois l’image du Dockerfile racine, vérifie la CLI, exécute le test de fumée CLI de suppression d’agents avec espace de travail partagé, exécute l’e2e du réseau de Gateway en conteneur, vérifie un argument de build d’extension intégrée et exécute le profil Docker borné de plugin intégré avec un délai d’expiration agrégé 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 paquet QR et Docker/update de l’installateur pour les exécutions planifiées nocturnes, les déclenchements manuels, les vérifications de release par workflow-call et les pull requests qui touchent réellement les surfaces installateur/paquet/Docker. En mode complet, install-smoke prépare ou réutilise une image de fumée Dockerfile racine GHCR pour le SHA cible, puis exécute l’installation de paquet QR, les fumées Dockerfile racine/Gateway, les fumées installateur/update et l’E2E Docker rapide des plugins intégrés comme des jobs séparés afin que le travail de l’installateur n’attende pas derrière les fumées de l’image racine. -Les pushes sur `main` (y compris les commits de fusion) ne forcent pas le chemin complet ; lorsque la logique de périmètre modifié demanderait une couverture complète sur un push, le workflow conserve la vérification Docker rapide et laisse la vérification complète d’installation aux validations nocturnes ou de release. +Les poussées sur `main` (y compris les commits de merge) ne forcent pas le chemin complet ; lorsque la logique de portée modifiée demanderait une couverture complète sur une poussée, le workflow conserve la fumée Docker rapide et laisse la fumée d’installation complète à la validation nocturne ou de release. -La vérification lente du fournisseur d’images avec installation globale Bun est contrôlée séparément par `run_bun_global_install_smoke`. Elle s’exécute selon la planification nocturne et depuis le workflow de vérifications de release, et les déclenchements manuels de `Install Smoke` peuvent l’activer, 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. +La fumée lente d’installation globale Bun pour image-provider est contrôlée séparément par `run_bun_global_install_smoke`. Elle s’exécute selon la planification nocturne et depuis le workflow de vérifications de release, et les déclenchements manuels de `Install Smoke` peuvent l’activer, mais les pull requests et les poussées sur `main` ne le font pas. Les tests Docker QR et installateur conservent leurs propres Dockerfiles axés sur l’installation. ## E2E Docker local -`pnpm test:docker:all` préconstruit une image de test live partagée, emballe OpenClaw une seule fois sous forme d’archive tar npm, et construit deux images `scripts/e2e/Dockerfile` partagées : +`pnpm test:docker:all` préconstruit une image de test live partagée, empaquette OpenClaw une fois comme archive npm, et construit deux images `scripts/e2e/Dockerfile` partagées : -- un runner Node/Git minimal pour les lanes installateur/mise à jour/dépendance de plugin ; -- une image fonctionnelle qui installe la même archive tar dans `/app` pour les lanes de fonctionnalité normale. +- un exécuteur Node/Git nu pour les lanes installateur/update/dépendance de plugin ; +- une image fonctionnelle qui installe la même archive dans `/app` pour les lanes de fonctionnalité normale. -Les définitions de lanes Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique de planification se trouve dans `scripts/lib/docker-e2e-plan.mjs`, et le runner n’exécute que le plan sélectionné. Le planificateur 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`. +Les définitions de lanes Docker résident dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique du planificateur réside dans `scripts/lib/docker-e2e-plan.mjs`, et l’exécuteur n’exécute que le plan sélectionné. Le planificateur 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 réglables +### Paramètres ajustables -| Variable | Valeur par défaut | Objectif | -| -------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre d’emplacements du pool principal pour les lanes normales. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Nombre d’emplacements du pool de fin sensible aux fournisseurs. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Plafond de lanes live 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 des rafales de création du daemon Docker ; définissez `0` pour aucun décalage. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai de secours par lane (120 minutes) ; les lanes live/de fin sélectionnées utilisent des plafonds plus stricts. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` affiche le plan du planificateur sans exécuter les lanes. | -| `OPENCLAW_DOCKER_ALL_LANES` | unset | Liste exacte de lanes séparées par des virgules ; ignore la vérification de nettoyage afin que les agents puissent reproduire une lane échouée. | +| Variable | Par défaut | Objectif | +| -------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre de créneaux du pool principal pour les lanes 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 lanes live 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 multi-services 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 daemon Docker ; définissez `0` pour aucun décalage. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai d’expiration de repli par lane (120 minutes) ; certaines lanes live/finales utilisent des plafonds plus stricts. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` affiche le plan du planificateur sans exécuter les lanes. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | Liste exacte de lanes séparées par des virgules ; ignore la fumée de nettoyage afin que les agents puissent reproduire une lane échouée. | -Une lane plus lourde que son plafond effectif peut tout de même démarrer depuis un pool vide, puis s’exécute seule jusqu’à libérer de la capacité. Le prévol agrégé local vérifie Docker, supprime les conteneurs OpenClaw E2E obsolètes, émet l’état des lanes actives, persiste les timings de lanes pour l’ordonnancement du plus long au plus court, et cesse par défaut de planifier de nouvelles lanes mises en pool après le premier échec. +Une lane 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 sa capacité. Les précontrôles agrégés locaux vérifient Docker, suppriment les conteneurs E2E OpenClaw obsolètes, émettent le statut des lanes actives, persistent les minutages de lanes pour l’ordre du plus long au plus court, et cessent par défaut de planifier de nouvelles lanes groupées après le premier échec. ### Workflow live/E2E réutilisable -Le workflow live/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quelle couverture de package, de type d’image, d’image live, de lane et d’identifiants est requise. `scripts/docker-e2e.mjs` convertit ensuite ce plan en sorties et récapitulatifs GitHub. Il emballe 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 des images Docker E2E GHCR nues/fonctionnelles étiquetées avec 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 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 de registre/cache bloqué soit réessayé rapidement au lieu de consommer la majeure partie du chemin critique CI. +Le workflow live/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quels paquet, type d’image, image live, 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 paquet de l’exécution courante, ou télécharge un artefact de paquet depuis `package_artifact_run_id` ; valide l’inventaire de l’archive ; construit et pousse des images E2E Docker GHCR nues/fonctionnelles taguées par digest de paquet via le cache de couches Docker de Blacksmith lorsque le plan nécessite des lanes avec paquet installé ; et réutilise les entrées `docker_e2e_bare_image`/`docker_e2e_functional_image` fournies ou les images existantes taguées par digest de paquet au lieu de reconstruire. Les extractions d’images Docker sont retentées avec un délai d’expiration borné de 180 secondes par tentative afin qu’un flux registry/cache bloqué réessaie rapidement au lieu de consommer la majeure partie du chemin critique CI. -### Fragments du chemin de release +### Morceaux du chemin de release -La couverture Docker de release exécute des jobs fragmentés plus petits 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 lanes via le même planificateur pondéré : +La couverture Docker de release exécute des jobs découpés plus petits avec `OPENCLAW_SKIP_DOCKER_BUILD=1` afin que chaque morceau ne tire que le type d’image dont il a besoin et exécute plusieurs lanes via le même planificateur 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` -Les fragments Docker de release actuels sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, et `plugins-runtime-install-a` à `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés plugin/runtime. L’alias de lane `install-e2e` reste l’alias de réexécution manuelle agrégée pour les deux lanes d’installation fournisseur. +Les morceaux Docker de release actuels sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, et `plugins-runtime-install-a` à `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés plugin/runtime. L’alias de lane `install-e2e` reste l’alias agrégé de réexécution manuelle pour les deux lanes d’installateur de fournisseurs. -OpenWebUI est intégré à `plugins-runtime-services` lorsque la couverture complète du chemin de release le demande, et conserve un fragment autonome `openwebui` uniquement pour les déclenchements propres à OpenWebUI. Les lanes de mise à jour de channels 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 release-path le demande, et conserve un morceau autonome `openwebui` uniquement pour les déclenchements limités à OpenWebUI. Les lanes de mise à jour des canaux intégrés réessaient une fois en cas de défaillances réseau npm transitoires. -Chaque fragment téléverse `.artifacts/docker-tests/` avec les journaux de lanes, timings, `summary.json`, `failures.json`, timings de phases, JSON du plan du planificateur, tableaux des lanes lentes et commandes de réexécution par lane. L’entrée `docker_lanes` du workflow exécute les lanes sélectionnées sur les images préparées au lieu des jobs de fragments, ce qui limite le débogage d’une lane échouée à un seul job Docker ciblé et prépare, télécharge ou réutilise l’artefact de package pour cette exécution ; si une lane sélectionnée est une lane 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 lane incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, afin qu’une lane échouée puisse réutiliser le package et les images exacts de l’exécution échouée. +Chaque morceau téléverse `.artifacts/docker-tests/` avec les journaux de lanes, les minutages, `summary.json`, `failures.json`, les minutages des phases, le JSON du plan du planificateur, les tableaux de lanes lentes et les commandes de réexécution par lane. L’entrée `docker_lanes` du workflow exécute les lanes sélectionnées contre les images préparées au lieu des jobs de morceaux, ce qui limite le débogage d’une lane échouée à un seul job Docker ciblé et prépare, télécharge ou réutilise l’artefact de paquet pour cette exécution ; si une lane sélectionnée est une lane 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 lane incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, afin qu’une lane échouée puisse réutiliser le paquet et les images exacts de l’exécution échouée. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -Le workflow live/E2E planifié exécute quotidiennement la suite Docker complète du chemin de release. +Le workflow live/E2E planifié exécute chaque jour la suite Docker release-path complète. -## Prérelease Plugin +## Prérelease de Plugin -`Plugin Prerelease` est une couverture produit/package plus coûteuse ; il s’agit donc d’un workflow séparé déclenché par `Full Release Validation` ou par un opérateur explicite. Les pull requests normales, les pushes sur `main` et les déclenchements CI manuels autonomes gardent cette suite désactivée. Il équilibre les tests de plugins groupés sur huit workers d’extension ; ces jobs de shards d’extension exécutent jusqu’à deux groupes de configuration de plugins à 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. Le chemin de prérelease Docker réservé à la release regroupe les lanes Docker ciblées en petits groupes pour éviter de réserver des dizaines de runners pour des jobs d’une à trois minutes. +`Plugin Prerelease` est une couverture produit/paquet 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 déclenchements CI manuels autonomes gardent cette suite désactivée. Il équilibre les tests de plugins intégrés sur huit workers d’extension ; ces jobs de fragments d’extension exécutent jusqu’à deux groupes de configuration de plugins à la fois avec un worker Vitest par groupe et un tas Node plus grand afin que les lots de plugins riches en imports ne créent pas de jobs CI supplémentaires. Le chemin de prérelease Docker réservé aux releases regroupe les lanes Docker ciblées en petits groupes pour éviter de réserver des dizaines d’exécuteurs pour des jobs d’une à trois minutes. -## Laboratoire QA +## QA Lab -Le laboratoire QA dispose de lanes CI dédiées en dehors du workflow principal à périmètre intelligent. La parité agentique est imbriquée sous les harnais QA et de release larges, et non dans un workflow PR autonome. Utilisez `Full Release Validation` avec `rerun_group=qa-parity` lorsque la parité doit accompagner une exécution de validation large. +QA Lab dispose de lanes CI dédiées en dehors du workflow principal à portée intelligente. La parité agentique est imbriquée sous les grands harnais QA et release, et non dans un workflow PR autonome. Utilisez `Full Release Validation` avec `rerun_group=qa-parity` lorsque la parité doit accompagner une large exécution de validation. -- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et sur déclenchement manuel ; il déploie en éventail la lane de parité mock, la lane Matrix live, et les lanes Telegram et Discord live en jobs parallèles. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des baux Convex. +- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et lors d’un déclenchement manuel ; il déploie en éventail la lane de parité simulée, la lane Matrix live et les lanes Telegram et Discord live comme jobs parallèles. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des baux Convex. -Les vérifications de release exécutent les lanes de transport live Matrix et Telegram avec le fournisseur mock déterministe et des modèles qualifiés mock (`mock-openai/gpt-5.5` et `mock-openai/gpt-5.5-alt`), afin que le contrat de channel 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 séparées de modèle live, de fournisseur natif et de fournisseur Docker. +Les vérifications de release exécutent les lanes de transport live Matrix et Telegram avec le fournisseur simulé déterministe et des 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 fournisseurs. Le Gateway de transport live désactive la recherche en mémoire parce que la parité QA couvre séparément le comportement mémoire ; la connectivité des fournisseurs est couverte par les suites séparées de modèle live, fournisseur natif et fournisseur Docker. -Matrix utilise `--profile fast` pour les gates planifiés et de release, 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` ; un déclenchement manuel `matrix_profile=all` répartit 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 release, 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 déclenchement manuel `matrix_profile=all` divise toujours la couverture Matrix complète en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`. -`OpenClaw Release Checks` exécute aussi les lanes QA Lab critiques pour la release avant l’approbation de release ; son gate de parité QA exécute les packages candidats et de référence comme jobs de lanes 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 lanes QA Lab critiques pour la release avant l’approbation de release ; sa porte de parité QA exécute les packs candidat et de référence comme jobs de lanes parallèles, puis télécharge les deux artefacts dans un petit job de rapport pour la comparaison finale de parité. -Pour les PR normales, suivez les preuves CI/check à périmètre limité au lieu de traiter la parité comme un état requis. +Pour les PR normales, suivez les preuves de CI/vérification ciblées au lieu de traiter la parité comme un statut requis. ## CodeQL -Le workflow `CodeQL` est volontairement un analyseur de sécurité de première passe étroit, et non un balayage complet du dépôt. Les exécutions de garde quotidiennes, manuelles et sur demandes d’extraction non brouillon 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 les valeurs `security-severity` élevées/critiques. +Le workflow `CodeQL` est volontairement un scanner de sécurité étroit de première passe, et non un balayage complet du dépôt. Les exécutions de garde quotidiennes, manuelles et de pull request non brouillon 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 une `security-severity` élevée/critique. -La garde des demandes d’extraction reste légère : elle ne démarre que pour les modifications 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é. CodeQL Android et macOS restent hors des valeurs par défaut des demandes d’extraction. +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é. Android et macOS CodeQL 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, bac à sable, cron et socle Gateway | -| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation des canaux cœur, ainsi que l’exécution du plugin de canal, le Gateway, le SDK Plugin, les secrets et les points de contact d’audit | -| `/codeql-security-high/network-ssrf-boundary` | Surfaces cœur de politique SSRF, analyse d’IP, garde réseau, récupération web et SSRF du SDK Plugin | -| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, assistants d’exécution de processus, livraison sortante et gardes d’exécution d’outils d’agent | -| `/codeql-security-high/plugin-trust-boundary` | Surfaces de confiance pour l’installation de Plugin, le chargeur, le manifeste, le registre, l’installation par gestionnaire de paquets, le chargement de source et le contrat de paquet du SDK Plugin | +| Catégorie | Surface | +| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `/codeql-security-high/core-auth-secrets` | Authentification, secrets, bac à sable, Cron et base de référence du Gateway | +| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation des canaux du cœur plus le runtime de Plugin de canal, le Gateway, le Plugin SDK, les secrets, les points d’audit | +| `/codeql-security-high/network-ssrf-boundary` | Surfaces SSRF du cœur, analyse IP, garde réseau, récupération web et politique SSRF du Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, helpers d’exécution de processus, livraison sortante et gardes d’exécution d’outils d’agent | +| `/codeql-security-high/plugin-trust-boundary` | Surfaces de confiance de l’installation de Plugin, du chargeur, du manifeste, du registre, de l’installation par gestionnaire de packages, du chargement de source et du contrat de package du Plugin SDK | ### Fragments de sécurité propres aux plateformes -- `CodeQL Android Critical Security` — fragment de sécurité Android planifié. Compile l’application Android manuellement pour CodeQL sur le plus petit exécuteur Blacksmith Linux accepté par le contrôle de cohérence du workflow. Téléverse sous `/codeql-critical-security/android`. -- `CodeQL macOS Critical Security` — fragment de sécurité macOS hebdomadaire/manuel. Compile l’application macOS manuellement pour CodeQL sur Blacksmith macOS, filtre les résultats de compilation des 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 la compilation macOS domine le temps d’exécution même lorsqu’elle est propre. +- `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 par défaut quotidiennes, car le build macOS domine le temps d’exécution même quand il est propre. ### 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 sans sécurité et de sévérité erreur, sur des surfaces étroites à forte valeur, sur le plus petit exécuteur Blacksmith Linux. Sa garde des demandes d’extraction est volontairement plus petite que le profil planifié : les demandes d’extraction non brouillon n’exécutent que 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 touchant le code d’exécution de commandes/modèles/outils d’agent et de distribution de réponses, le code de schéma/migration/E/S de configuration, le code d’authentification/secrets/bac à sable/sécurité, l’exécution cœur des canaux et des plugins de canal intégrés, le protocole Gateway/la méthode serveur, la colle d’exécution mémoire/SDK, MCP/processus/livraison sortante, le catalogue d’exécution/modèles de fournisseurs, les diagnostics de session/files de livraison, le chargeur de Plugin, le contrat SDK Plugin/paquet, ou l’exécution de réponse du SDK Plugin. Les changements de configuration CodeQL et de workflow qualité exécutent les douze fragments de qualité des demandes d’extraction. +`CodeQL Critical Quality` est le fragment non sécurité correspondant. Il exécute uniquement des requêtes de qualité JavaScript/TypeScript sans sécurité, de sévérité erreur, 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 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 de commandes/modèles/outils d’agent et d’envoi de réponses, de schéma/migration/E/S de config, d’authentification/secrets/bac à sable/sécurité, de runtime du canal du cœur et du Plugin de canal groupé, de protocole/méthode serveur du Gateway, de runtime mémoire/glue SDK, de livraison MCP/processus/sortante, de runtime fournisseur/catalogue de modèles, de diagnostics de session/files de livraison, de chargeur de Plugin, de contrat Plugin SDK/package ou de runtime de réponse du Plugin SDK. Les changements de config CodeQL et de workflow qualité exécutent les douze fragments qualité de PR. -Le déclenchement manuel accepte : +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’accroche d’apprentissage/itération pour exécuter un fragment de qualité isolément. +Les profils étroits sont des hooks pédagogiques/d’itération pour exécuter un fragment qualité isolément. -| Catégorie | Surface | -| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Authentification, secrets, bac à sable, cron et code de frontière de sécurité Gateway | -| `/codeql-critical-quality/config-boundary` | Contrats de schéma de configuration, migration, normalisation et E/S | -| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas de protocole Gateway et contrats de méthodes serveur | -| `/codeql-critical-quality/channel-runtime-boundary` | Contrats d’implémentation des canaux cœur et des plugins de canal intégrés | -| `/codeql-critical-quality/agent-runtime-boundary` | Exécution de commandes, distribution modèles/fournisseurs, distribution et files de 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 de l’hôte mémoire, façades d’exécution mémoire, alias mémoire du SDK Plugin, colle d’activation de l’exécution mémoire et commandes doctor 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/bundles de journaux et contrats CLI doctor de session | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Distribution des réponses entrantes du SDK Plugin, assistants de payload/fragmentation/exécution de réponse, options de réponse de canal, files de livraison et assistants de liaison session/thread | -| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte de fournisseurs, enregistrement d’exécution de fournisseurs, valeurs par défaut/catalogues de 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 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 cœur de récupération/recherche web, E/S médias, compréhension média, génération d’images et génération de médias | -| `/codeql-critical-quality/plugin-boundary` | Contrats de chargeur, registre, surface publique et points d’entrée du SDK Plugin | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Source SDK Plugin côté paquet publié et assistants de contrat de paquet plugin | +| Catégorie | Surface | +| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Code de frontière de sécurité pour l’authentification, les secrets, le bac à sable, Cron et le Gateway | +| `/codeql-critical-quality/config-boundary` | Contrats de schéma de config, migration, normalisation et E/S | +| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas de protocole du Gateway et contrats de méthodes serveur | +| `/codeql-critical-quality/channel-runtime-boundary` | Contrats d’implémentation du canal du cœur et du Plugin de canal groupé | +| `/codeql-critical-quality/agent-runtime-boundary` | Exécution de commandes, dispatch modèle/fournisseur, dispatch et files de réponse automatique, et contrats de runtime du plan de contrôle ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serveurs MCP et ponts d’outils, helpers de supervision de processus et contrats de livraison sortante | +| `/codeql-critical-quality/memory-runtime-boundary` | SDK hôte mémoire, façades de runtime mémoire, alias mémoire du Plugin SDK, glue d’activation du runtime mémoire et commandes doctor mémoire | +| `/codeql-critical-quality/session-diagnostics-boundary` | Internes de file de réponses, files de livraison de session, helpers de liaison/livraison de session sortante, surfaces d’événements de diagnostic/bundles de logs et contrats CLI doctor de session | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch de réponse entrante du Plugin SDK, helpers de charge utile/découpage/runtime de réponse, options de réponse de canal, files de livraison et helpers de liaison session/thread | +| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte fournisseur, enregistrement du runtime fournisseur, valeurs par défaut/catalogues fournisseur et registres web/recherche/récupération/embedding | +| `/codeql-critical-quality/ui-control-plane` | Amorçage de l’UI de contrôle, persistance locale, flux de contrôle du Gateway et contrats de runtime du plan de contrôle des tâches | +| `/codeql-critical-quality/web-media-runtime-boundary` | Contrats de runtime pour récupération/recherche web du cœur, E/S média, compréhension des médias, génération d’images et 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 helpers 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 à Swift, Python et aux plugins intégrés devrait être réajoutée uniquement comme travail de suivi borné ou fragmenté, une fois que les profils étroits ont un temps d’exécution et un signal stables. +La qualité reste séparée de la sécurité afin que les résultats 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éajoutée comme travail de suivi ciblé ou fragmenté qu’après stabilisation du runtime et du signal des profils étroits. ## Workflows de maintenance -### Agent Docs +### Docs Agent -Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par événements pour garder la documentation existante alignée avec les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie sur `main` après un push non-bot peut le déclencher, et le 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 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 depuis le SHA source du précédent Docs Agent non ignoré jusqu’à `main` actuel, de sorte qu’une exécution horaire peut couvrir tous les changements de main accumulés depuis le dernier passage documentaire. +Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par é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 d’un push non-bot sur `main` peut le déclencher, et le 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 non ignorée de Docs Agent a été créée dans la dernière heure. Lorsqu’il s’exécute, il passe en revue la plage de commits depuis le 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 documentation. -### Agent de performance des tests +### Test Performance Agent -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 sur `main` après un push non-bot peut le déclencher, mais il s’arrête 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 garde d’activité quotidienne. La voie produit un rapport de performance Vitest groupé de suite complète, laisse Codex faire seulement de petites corrections de performance de tests qui préservent la couverture au lieu de larges refactorisations, puis réexécute le rapport de 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 contient des tests en échec, Codex ne peut corriger que les échecs évidents, et le rapport de suite complète après agent doit passer avant tout commit. Lorsque `main` avance avant que le push du bot n’aboutisse, la voie rebase le patch validé, réexécute `pnpm check:changed` et retente 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. +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’un push non-bot sur `main` peut le déclencher, mais il est ignoré 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 garde d’activité quotidienne. La voie construit un rapport de performance Vitest groupé de suite complète, permet à Codex de n’apporter que de petites corrections de performance de test préservant la couverture au lieu de refontes larges, puis réexécute le rapport de suite complète et rejette les changements qui réduisent le nombre de tests passants de la ligne de base. Si la ligne de base contient 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 arrive, la voie rebase le patch validé, réexécute `pnpm check:changed` et retente 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 de documentation. -### Demandes d’extraction dupliquées après fusion +### PR dupliquées après merge -Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel pour le nettoyage des doublons après intégration. Il utilise par défaut un mode simulation et ne ferme les demandes d’extraction explicitement listées que lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la demande d’extraction intégrée est fusionnée et que chaque doublon a soit un ticket référencé commun, soit des hunks modifiés qui se chevauchent. +Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel pour le nettoyage des doublons après intégration. Il utilise par défaut le mode dry-run et ne ferme les PR explicitement listées que lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est mergée et que chaque doublon a soit une issue référencée partagée, soit des hunks modifiés qui se chevauchent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -474,29 +474,29 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Gardes de vérification locale et routage des changements +## Garde-fous de vérification locale et routage des changements -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 garde 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 de voies de changements réside dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette garde de vérification locale est plus stricte sur les frontières d’architecture que le périmètre large de la plateforme CI : -- les changements de production cœur exécutent la vérification de types cœur prod et cœur test, ainsi que le lint/les gardes cœur ; -- les changements cœur uniquement de test exécutent seulement la vérification de types cœur test, ainsi que le lint cœur ; -- les changements de production d’extension exécutent la vérification de types extension prod et extension test, ainsi que le lint extension ; -- les changements d’extension uniquement de test exécutent la vérification de types extension test, ainsi que le lint extension ; -- les changements du SDK Plugin public ou du contrat de plugin s’étendent à la vérification de types des extensions parce que les extensions dépendent de ces contrats cœur (les balayages d’extensions Vitest restent un travail de test explicite) ; -- les montées de version uniquement de métadonnées de publication 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 la vérification de types prod du cœur et tests du cœur plus lint/gardes du cœur ; +- les changements seulement de tests du cœur exécutent uniquement la vérification de types des tests du cœur plus lint du cœur ; +- les changements de production d’extension exécutent la vérification de types prod d’extension et tests d’extension plus lint d’extension ; +- les changements seulement de tests d’extension exécutent la vérification de types des tests d’extension plus lint d’extension ; +- les changements publics du Plugin SDK ou de contrat de Plugin s’étendent à la vérification de types d’extension parce que les extensions 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/config/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 volontairement moins coûteux que `check:changed` : les modifications directes de tests exécutent ces tests, les modifications de source privilégient les correspondances explicites, puis les tests frères et les dépendants du graphe d’import. La configuration de livraison partagée des salles de groupe fait partie des correspondances explicites : les changements de la configuration de réponse visible au groupe, du mode de livraison des réponses source ou du prompt système de l’outil de message passent par les tests de réponse cœur ainsi que 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 demande d’extraction. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque le changement est assez large au niveau du harnais pour que l’ensemble mappé peu coûteux ne soit pas un substitut fiable. +Le routage local des tests modifiés réside dans `scripts/test-projects.test-support.mjs` et est volontairement moins coûteux que `check:changed` : les modifications directes de tests s’exécutent elles-mêmes, les modifications de source privilégient les mappages explicites, puis les tests voisins et les dépendants du graphe d’imports. La config partagée de livraison de salon de groupe fait partie des mappages explicites : les changements de la config de réponse visible par le groupe, du mode de livraison de réponse source ou du 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 touche assez largement le harnais pour que l’ensemble mappé léger ne soit pas un proxy fiable. ## Validation Testbox -Exécutez Testbox depuis la racine du dépôt et privilégiez une nouvelle box préchauffée pour une preuve large. Avant de lancer une gate lente sur une box qui a été réutilisée, a expiré ou vient de signaler une synchronisation étonnamment volumineuse, exécutez d’abord `pnpm testbox:sanity` dans la box. +Exécutez Testbox depuis la racine du dépôt et privilégiez une boîte fraîchement préparée pour les preuves larges. Avant de lancer une porte lente sur une boîte réutilisée, expirée ou qui vient de signaler une synchronisation anormalement volumineuse, exécutez d’abord `pnpm testbox:sanity` dans la boîte. -Le contrôle 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 box et préchauffez-en une nouvelle au lieu de déboguer l’échec du test produit. Pour les PRs avec de nombreuses suppressions intentionnelles, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution de cohérence. +Le contrôle 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éparez-en une fraîche au lieu de déboguer l’échec du test produit. Pour les PR avec de nombreuses suppressions intentionnelles, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution de cohérence. -`pnpm testbox:run` met également fin à une invocation locale de la Blacksmith CLI 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 protection, ou utilisez une valeur en millisecondes plus élevée pour des diffs locaux exceptionnellement volumineux. +`pnpm testbox:run` termine aussi une invocation locale de la CLI Blacksmith qui reste en phase de synchronisation pendant plus de cinq minutes sans sortie après synchronisation. Définissez `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` pour désactiver cette garde, ou utilisez une valeur plus élevée en millisecondes pour les diffs locaux exceptionnellement volumineux. -Crabbox est le wrapper de box distante détenu par le dépôt pour les preuves Linux des mainteneurs. Utilisez-le lorsqu’un contrôle est trop large pour une boucle d’édition locale, lorsque la parité CI compte, ou lorsque la preuve nécessite des secrets, Docker, des lanes de paquets, des boxes réutilisables ou des journaux distants. Le backend OpenClaw normal est `blacksmith-testbox` ; la capacité AWS/Hetzner détenue est une solution de repli en cas de pannes Blacksmith, de problèmes de quota ou de tests explicites sur capacité détenue. +Crabbox est le wrapper de boîte distante appartenant au dépôt pour les preuves Linux des mainteneurs. Utilisez-le lorsqu’un contrôle est trop large pour une boucle d’édition locale, lorsque la parité CI compte, ou lorsque la preuve nécessite des secrets, Docker, des voies de paquets, des boîtes réutilisables ou des journaux distants. Le backend OpenClaw normal est `blacksmith-testbox` ; la capacité AWS/Hetzner possédée est une solution de repli pour les pannes Blacksmith, les problèmes de quota ou les tests explicites sur capacité possédée. Avant une première exécution, vérifiez le wrapper depuis la racine du dépôt : @@ -504,9 +504,9 @@ Avant une première exécution, vérifiez le wrapper depuis la racine du dépôt pnpm crabbox:run -- --help | sed -n '1,120p' ``` -Le wrapper du dépôt refuse un binaire Crabbox obsolète qui n’annonce pas `blacksmith-testbox`. Passez le fournisseur explicitement même si `.crabbox.yaml` contient des valeurs par défaut pour le cloud détenu. +Le wrapper du dépôt refuse un binaire Crabbox obsolète qui n’annonce pas `blacksmith-testbox`. Passez explicitement le fournisseur même si `.crabbox.yaml` contient des valeurs par défaut de cloud possédé. -Gate des changements : +Porte des changements : ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -521,7 +521,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed" ``` -Réexécution de test ciblée : +Relance de test ciblée : ```bash pnpm crabbox:run -- --provider blacksmith-testbox \ @@ -551,21 +551,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \ "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test" ``` -Lisez le résumé JSON final. Les champs utiles sont `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` et `totalMs`. Les exécutions Crabbox ponctuelles adossées à Blacksmith devraient arrêter la Testbox automatiquement ; si une exécution est interrompue ou si le nettoyage est incertain, inspectez les boxes actives et arrêtez uniquement celles que vous avez créées : +Lisez le résumé JSON final. Les champs utiles sont `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` et `totalMs`. Les exécutions Crabbox ponctuelles appuyées par Blacksmith devraient arrêter automatiquement le Testbox ; si une exécution est interrompue ou si le nettoyage n’est pas clair, inspectez les boîtes actives et arrêtez uniquement celles que vous avez créées : ```bash blacksmith testbox list blacksmith testbox stop --id ``` -N’utilisez la réutilisation que lorsque vous avez intentionnellement besoin de plusieurs commandes sur la même box hydratée : +N’utilisez la réutilisation que lorsque vous avez intentionnellement besoin de plusieurs commandes sur la même boîte hydratée : ```bash pnpm crabbox:run -- --provider blacksmith-testbox --id --no-sync --timing-json --shell -- "pnpm test " pnpm crabbox:stop -- ``` -Si Crabbox est la couche défaillante mais que Blacksmith lui-même fonctionne, utilisez Blacksmith directement comme solution de repli étroite : +Si Crabbox est la couche défectueuse mais que Blacksmith lui-même fonctionne, utilisez Blacksmith directement comme solution de repli étroite : ```bash blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 @@ -573,7 +573,7 @@ blacksmith testbox run --id "env CI=1 NODE_OPTIONS=--max-old-space-size blacksmith testbox stop --id ``` -Ne passez à la capacité Crabbox détenue que lorsque Blacksmith est indisponible, limité par quota, dépourvu de l’environnement nécessaire, ou lorsque la capacité détenue est explicitement l’objectif : +N’escaladez vers la capacité Crabbox possédée que lorsque Blacksmith est indisponible, limité par quota, ne fournit pas l’environnement requis, ou que la capacité possédée est explicitement l’objectif : ```bash pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m @@ -582,9 +582,9 @@ pnpm crabbox:run -- --id --timing-json --shell -- "env NODE_OPT pnpm crabbox:stop -- ``` -`.crabbox.yaml` définit les valeurs par défaut du fournisseur, de la synchronisation et de l’hydratation GitHub Actions pour les lanes de cloud détenu. Il exclut le `.git` local afin que le checkout Actions hydraté conserve ses propres métadonnées Git distantes au lieu de synchroniser les remotes et magasins d’objets locaux du mainteneur, et il exclut les artefacts locaux d’exécution/de build qui ne doivent jamais être transférés. `.github/workflows/crabbox-hydrate.yml` définit le checkout, la configuration Node/pnpm, la récupération de `origin/main` et la transmission d’environnement non secret pour les commandes `crabbox run --id ` sur cloud détenu. +`.crabbox.yaml` possède les valeurs par défaut du fournisseur, de la synchronisation et de l’hydratation GitHub Actions pour les voies de cloud possédé. Il exclut le `.git` local afin que le checkout Actions hydraté conserve ses propres métadonnées Git distantes au lieu de synchroniser les remotes et magasins d’objets locaux du mainteneur, et il exclut les artefacts locaux d’exécution/de build qui ne doivent jamais être transférés. `.github/workflows/crabbox-hydrate.yml` possède le checkout, la configuration Node/pnpm, la récupération de `origin/main` et la transmission d’environnement non secret pour les commandes de cloud possédé `crabbox run --id `. -## Connexe +## Associé - [Vue d’ensemble de l’installation](/fr/install) - [Canaux de développement](/fr/install/development-channels) diff --git a/docs/fr/cli/cron.md b/docs/fr/cli/cron.md index ceed2f4ca..eb991efff 100644 --- a/docs/fr/cli/cron.md +++ b/docs/fr/cli/cron.md @@ -1,21 +1,21 @@ --- read_when: - - Vous souhaitez des tâches planifiées et des réveils + - Vous voulez des tâches planifiées et des réveils - Vous déboguez l’exécution de Cron et les journaux summary: Référence CLI pour `openclaw cron` (planifier et exécuter des tâches en arrière-plan) title: Cron x-i18n: - generated_at: "2026-05-02T07:01:24Z" + generated_at: "2026-05-05T06:16:13Z" model: gpt-5.5 provider: openai - source_hash: 298ac3fc868462eb301febbc1aa5296d8087cad7fdc466870487081444c5856f + source_hash: 804efac75b8653b03cec197247be847498e084b50b00fb7bd3fbd94067ef25d4 source_path: cli/cron.md workflow: 16 --- # `openclaw cron` -Gérez les tâches Cron pour le planificateur du Gateway. +Gérez les tâches Cron du planificateur Gateway. Exécutez `openclaw cron --help` pour voir toute la surface de commande. Consultez [Tâches Cron](/fr/automation/cron-jobs) pour le guide conceptuel. @@ -28,38 +28,38 @@ Exécutez `openclaw cron --help` pour voir toute la surface de commande. Consult - `main` se lie à la session principale de l’agent. - - `isolated` crée une transcription et un identifiant de session neufs pour chaque exécution. + - `isolated` crée une nouvelle transcription et un nouvel identifiant de session pour chaque exécution. - `current` se lie à la session active au moment de la création. - `session:` épingle une clé de session persistante explicite. - Les exécutions isolées réinitialisent le contexte de conversation ambiant. Le routage des canaux et des groupes, la politique d’envoi/de file d’attente, l’élévation, l’origine et la liaison d’exécution ACP sont réinitialisés pour la nouvelle exécution. Les préférences sûres et les remplacements explicites du modèle ou de l’authentification sélectionnés par l’utilisateur peuvent être conservés entre les exécutions. + Les exécutions isolées réinitialisent le contexte de conversation ambiant. Le routage des canaux et des groupes, la politique d’envoi/de mise en file, l’élévation, l’origine et la liaison d’exécution ACP sont réinitialisés pour la nouvelle exécution. Les préférences sûres et les substitutions explicites de modèle ou d’authentification sélectionnées par l’utilisateur peuvent être conservées entre les exécutions. ## Livraison -`openclaw cron list` et `openclaw cron show ` prévisualisent la route de livraison résolue. Pour `channel: "last"`, l’aperçu indique si la route est résolue depuis la session principale ou actuelle, ou si elle échouera fermée. +`openclaw cron list` et `openclaw cron show ` affichent un aperçu de la route de livraison résolue. Pour `channel: "last"`, l’aperçu indique si la route a été résolue depuis la session principale ou actuelle, ou si elle échouera de manière fermée. -Les cibles préfixées par un fournisseur peuvent lever l’ambiguïté des canaux d’annonce non résolus. Par exemple, `to: "telegram:123"` sélectionne Telegram lorsque `delivery.channel` est omis ou vaut `last`. Seuls les préfixes annoncés par le Plugin chargé sont des sélecteurs de fournisseur. Si `delivery.channel` est explicite, le préfixe doit correspondre à ce canal ; `channel: "whatsapp"` avec `to: "telegram:123"` est rejeté. Les préfixes de service tels que `imessage:` et `sms:` restent une syntaxe de cible propre au canal. +Les cibles préfixées par un fournisseur peuvent lever l’ambiguïté des canaux d’annonce non résolus. Par exemple, `to: "telegram:123"` sélectionne Telegram lorsque `delivery.channel` est omis ou vaut `last`. Seuls les préfixes annoncés par le Plugin chargé sont des sélecteurs de fournisseur. Si `delivery.channel` est explicite, le préfixe doit correspondre à ce canal ; `channel: "whatsapp"` avec `to: "telegram:123"` est rejeté. Les préfixes de service comme `imessage:` et `sms:` restent une syntaxe de cible propre au canal. -Les tâches `cron add` isolées utilisent par défaut la livraison `--announce`. Utilisez `--no-deliver` pour garder la sortie interne. `--deliver` reste disponible comme alias obsolète de `--announce`. +Les tâches `cron add` isolées utilisent par défaut la livraison `--announce`. Utilisez `--no-deliver` pour garder la sortie interne. `--deliver` reste un alias obsolète de `--announce`. ### Propriété de la livraison -La livraison de chat Cron isolée est partagée entre l’agent et le runner : +La livraison de chat Cron isolée est partagée entre l’agent et le lanceur : - L’agent peut envoyer directement avec l’outil `message` lorsqu’une route de chat est disponible. -- `announce` livre en secours la réponse finale uniquement lorsque l’agent n’a pas envoyé directement vers la cible résolue. +- `announce` livre la réponse finale en secours uniquement lorsque l’agent n’a pas envoyé directement vers la cible résolue. - `webhook` publie la charge utile terminée vers une URL. -- `none` désactive la livraison de secours du runner. +- `none` désactive la livraison de secours par le lanceur. -`--announce` est la livraison de secours du runner pour la réponse finale. `--no-deliver` désactive ce secours, mais ne supprime pas l’outil `message` de l’agent lorsqu’une route de chat est disponible. +`--announce` est la livraison de secours par le lanceur pour la réponse finale. `--no-deliver` désactive ce secours, mais ne retire pas l’outil `message` de l’agent lorsqu’une route de chat est disponible. -Les rappels créés depuis un chat actif conservent la cible de livraison du chat en direct pour la livraison d’annonce de secours. Les clés de session internes peuvent être en minuscules ; ne les utilisez pas comme source de vérité pour des identifiants de fournisseur sensibles à la casse, tels que les identifiants de salons Matrix. +Les rappels créés depuis un chat actif conservent la cible de livraison du chat en direct pour la livraison d’annonce de secours. Les clés de session internes peuvent être en minuscules ; ne les utilisez pas comme source de vérité pour des identifiants de fournisseur sensibles à la casse, comme les identifiants de salle Matrix. ### Livraison des échecs @@ -67,13 +67,13 @@ Les notifications d’échec sont résolues dans cet ordre : 1. `delivery.failureDestination` sur la tâche. 2. `cron.failureDestination` global. -3. La cible d’annonce principale de la tâche (lorsqu’aucune destination d’échec explicite n’est définie). +3. La cible d’annonce principale de la tâche, lorsqu’aucune destination d’échec explicite n’est définie. Les tâches de session principale ne peuvent utiliser `delivery.failureDestination` que lorsque le mode de livraison principal est `webhook`. Les tâches isolées l’acceptent dans tous les modes. -Remarque : les exécutions Cron isolées traitent les échecs d’agent au niveau de l’exécution comme des erreurs de tâche, même lorsqu’aucune charge utile de réponse n’est produite ; les échecs de modèle/fournisseur incrémentent donc quand même les compteurs d’erreurs et déclenchent les notifications d’échec. +Remarque : les exécutions Cron isolées traitent les échecs d’agent au niveau de l’exécution comme des erreurs de tâche même quand aucune charge utile de réponse n’est produite, afin que les échecs de modèle/fournisseur incrémentent quand même les compteurs d’erreurs et déclenchent les notifications d’échec. ## Planification @@ -87,20 +87,20 @@ Les tâches ponctuelles sont supprimées après réussite par défaut. Utilisez ### Tâches récurrentes -Les tâches récurrentes utilisent un intervalle de nouvelle tentative exponentiel après des erreurs consécutives : 30 s, 1 min, 5 min, 15 min, 60 min. La planification revient à la normale après la prochaine exécution réussie. +Les tâches récurrentes utilisent un délai de nouvelle tentative exponentiel après des erreurs consécutives : 30 s, 1 min, 5 min, 15 min, 60 min. La planification revient à la normale après la prochaine exécution réussie. -Les exécutions ignorées sont suivies séparément des erreurs d’exécution. Elles n’affectent pas l’intervalle de nouvelle tentative, mais `openclaw cron edit --failure-alert-include-skipped` peut inclure les exécutions ignorées répétées dans les alertes d’échec. +Les exécutions ignorées sont suivies séparément des erreurs d’exécution. Elles n’affectent pas le délai de nouvelle tentative, mais `openclaw cron edit --failure-alert-include-skipped` permet d’inclure les notifications répétées d’exécutions ignorées dans les alertes d’échec. -Pour les tâches isolées qui ciblent un fournisseur de modèles local configuré, Cron exécute une vérification préalable légère du fournisseur avant de démarrer le tour de l’agent. Les fournisseurs `api: "ollama"` en loopback, réseau privé et `.local` sont interrogés sur `/api/tags` ; les fournisseurs locaux compatibles OpenAI, tels que vLLM, SGLang et LM Studio, sont interrogés sur `/models`. Si le point de terminaison est injoignable, l’exécution est enregistrée comme `skipped` et réessayée lors d’une planification ultérieure ; les points de terminaison morts correspondants sont mis en cache pendant 5 minutes afin d’éviter que de nombreuses tâches martèlent le même serveur local. +Pour les tâches isolées qui ciblent un fournisseur de modèle local configuré, Cron exécute un précontrôle léger du fournisseur avant de démarrer le tour d’agent. Les fournisseurs `api: "ollama"` en local loopback, sur réseau privé et `.local` sont sondés sur `/api/tags` ; les fournisseurs locaux compatibles OpenAI comme vLLM, SGLang et LM Studio sont sondés sur `/models`. Si le point de terminaison est injoignable, l’exécution est enregistrée comme `skipped` et réessayée lors d’une planification ultérieure ; les points de terminaison morts correspondants sont mis en cache pendant 5 minutes pour éviter que de nombreuses tâches ne martèlent le même serveur local. -Remarque : les définitions des tâches Cron se trouvent dans `jobs.json`, tandis que l’état d’exécution en attente se trouve dans `jobs-state.json`. Si `jobs.json` est modifié de l’extérieur, le Gateway recharge les planifications modifiées et efface les créneaux en attente obsolètes ; les réécritures de formatage uniquement n’effacent pas le créneau en attente. +Remarque : les définitions de tâches Cron vivent dans `jobs.json`, tandis que l’état d’exécution en attente vit dans `jobs-state.json`. Si `jobs.json` est modifié extérieurement, le Gateway recharge les planifications modifiées et efface les créneaux en attente obsolètes ; les réécritures limitées au formatage n’effacent pas le créneau en attente. ### Exécutions manuelles -`openclaw cron run` retourne dès que l’exécution manuelle est mise en file d’attente. Les réponses réussies incluent `{ ok: true, enqueued: true, runId }`. Utilisez `openclaw cron runs --id ` pour suivre le résultat final. +`openclaw cron run` retourne dès que l’exécution manuelle est mise en file. Les réponses réussies incluent `{ ok: true, enqueued: true, runId }`. Utilisez `openclaw cron runs --id ` pour suivre le résultat final. -`openclaw cron run ` force l’exécution par défaut. Utilisez `--due` pour conserver l’ancien comportement « exécuter seulement si dû ». +`openclaw cron run ` force l’exécution par défaut. Utilisez `--due` pour conserver l’ancien comportement « exécuter uniquement si l’échéance est atteinte ». ## Modèles @@ -111,43 +111,43 @@ Remarque : les définitions des tâches Cron se trouvent dans `jobs.json`, tandi Si le modèle n’est pas autorisé ou ne peut pas être résolu, Cron fait échouer l’exécution avec une erreur de validation explicite au lieu de se rabattre sur l’agent de la tâche ou sur la sélection de modèle par défaut. -Le `--model` de Cron est un **modèle principal de tâche**, pas un remplacement `/model` de session de chat. Cela signifie que : +Cron `--model` est un **principal de tâche**, pas une substitution `/model` de session de chat. Cela signifie que : - Les modèles de secours configurés s’appliquent toujours lorsque le modèle de tâche sélectionné échoue. -- La charge utile `fallbacks` propre à la tâche remplace la liste de secours configurée lorsqu’elle est présente. -- Une liste de secours propre à la tâche vide (`fallbacks: []` dans la charge utile/API de la tâche) rend l’exécution Cron stricte. -- Lorsqu’une tâche a `--model` mais qu’aucune liste de secours n’est configurée, OpenClaw transmet un remplacement de secours vide explicite afin que le modèle principal de l’agent ne soit pas ajouté comme cible de nouvelle tentative cachée. +- Le champ `fallbacks` de la charge utile par tâche remplace la liste de secours configurée lorsqu’il est présent. +- Une liste de secours par tâche vide (`fallbacks: []` dans la charge utile/API de la tâche) rend l’exécution Cron stricte. +- Lorsqu’une tâche a `--model` mais qu’aucune liste de secours n’est configurée, OpenClaw transmet une substitution de secours vide explicite afin que le principal de l’agent ne soit pas ajouté comme cible de nouvelle tentative masquée. -### Précédence des modèles Cron isolés +### Priorité des modèles Cron isolés Cron isolé résout le modèle actif dans cet ordre : -1. Remplacement du hook Gmail. -2. `--model` propre à la tâche. -3. Remplacement de modèle stocké dans la session Cron (lorsque l’utilisateur en a sélectionné un). -4. Sélection du modèle de l’agent ou du modèle par défaut. +1. Substitution du hook Gmail. +2. `--model` par tâche. +3. Substitution de modèle de session Cron stockée, lorsque l’utilisateur en a sélectionné une. +4. Sélection du modèle de l’agent ou par défaut. ### Mode rapide -Le mode rapide de Cron isolé suit la sélection de modèle en direct résolue. La configuration de modèle `params.fastMode` s’applique par défaut, mais un remplacement de session `fastMode` stocké l’emporte toujours sur la configuration. +Le mode rapide Cron isolé suit la sélection de modèle en direct résolue. La configuration de modèle `params.fastMode` s’applique par défaut, mais une substitution `fastMode` de session stockée prime toujours sur la configuration. ### Nouvelles tentatives après changement de modèle en direct -Si une exécution isolée lève `LiveSessionModelSwitchError`, Cron persiste le fournisseur et le modèle basculés (ainsi que le remplacement de profil d’authentification basculé, lorsqu’il est présent) pour l’exécution active avant de réessayer. La boucle externe de nouvelle tentative est limitée à deux nouvelles tentatives de bascule après la tentative initiale, puis abandonne au lieu de boucler indéfiniment. +Si une exécution isolée lève `LiveSessionModelSwitchError`, Cron persiste le fournisseur et le modèle changés, ainsi que la substitution de profil d’authentification changée lorsqu’elle est présente, pour l’exécution active avant de réessayer. La boucle externe de nouvelle tentative est limitée à deux nouvelles tentatives de changement après la tentative initiale, puis abandonne au lieu de boucler indéfiniment. ## Sortie d’exécution et refus ### Suppression des accusés de réception obsolètes -Les tours Cron isolés suppriment les réponses obsolètes qui ne sont que des accusés de réception. Si le premier résultat n’est qu’une mise à jour d’état intermédiaire et qu’aucune exécution de sous-agent descendante n’est responsable de la réponse finale, Cron relance une seule fois la demande pour obtenir le résultat réel avant livraison. +Les tours Cron isolés suppriment les réponses obsolètes ne contenant qu’un accusé de réception. Si le premier résultat n’est qu’une mise à jour d’état intermédiaire et qu’aucune exécution de sous-agent descendant n’est responsable de la réponse finale, Cron relance une fois la demande pour obtenir le vrai résultat avant livraison. -### Suppression du jeton silencieux +### Suppression des jetons silencieux -Si une exécution Cron isolée retourne uniquement le jeton silencieux (`NO_REPLY` ou `no_reply`), Cron supprime à la fois la livraison sortante directe et le chemin de résumé mis en file d’attente de secours, de sorte que rien n’est republié dans le chat. +Si une exécution Cron isolée retourne uniquement le jeton silencieux (`NO_REPLY` ou `no_reply`), Cron supprime à la fois la livraison sortante directe et le chemin de résumé mis en file de secours ; rien n’est donc publié en retour dans le chat. ### Refus structurés -Les exécutions Cron isolées privilégient les métadonnées structurées de refus d’exécution provenant de l’exécution intégrée, puis se rabattent sur les marqueurs de refus connus dans la sortie finale, tels que `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` et les formules de refus liées à l’approbation. +Les exécutions Cron isolées privilégient les métadonnées structurées de refus d’exécution depuis l’exécution intégrée, puis se rabattent sur les marqueurs de refus connus dans la sortie finale, comme `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` et les formulations de refus liées aux approbations. `cron list` et l’historique des exécutions affichent la raison du refus au lieu de signaler une commande bloquée comme `ok`. @@ -155,18 +155,18 @@ Les exécutions Cron isolées privilégient les métadonnées structurées de re La rétention et l’élagage sont contrôlés dans la configuration : -- `cron.sessionRetention` (`24h` par défaut) élague les sessions d’exécution isolées terminées. +- `cron.sessionRetention` (par défaut `24h`) élague les sessions d’exécution isolée terminées. - `cron.runLog.maxBytes` et `cron.runLog.keepLines` élaguent `~/.openclaw/cron/runs/.jsonl`. -## Migration d’anciennes tâches +## Migration des anciennes tâches -Si vous avez des tâches Cron antérieures au format actuel de livraison et de stockage, exécutez `openclaw doctor --fix`. Doctor normalise les anciens champs Cron (`jobId`, `schedule.cron`, les champs de livraison de premier niveau, y compris l’ancien `threadId`, et les alias de livraison `provider` de la charge utile) et migre les tâches simples de secours Webhook `notify: true` vers une livraison Webhook explicite lorsque `cron.webhook` est configuré. +Si vous avez des tâches Cron créées avant le format actuel de livraison et de stockage, exécutez `openclaw doctor --fix`. Doctor normalise les anciens champs Cron (`jobId`, `schedule.cron`, champs de livraison de premier niveau dont l’ancien `threadId`, alias de livraison `provider` dans la charge utile) et migre les tâches de secours Webhook simples `notify: true` vers une livraison Webhook explicite lorsque `cron.webhook` est configuré. ## Modifications courantes -Mettre à jour les paramètres de livraison sans modifier le message : +Mettre à jour les paramètres de livraison sans changer le message : ```bash openclaw cron edit --announce --channel telegram --to "123456789" @@ -178,13 +178,13 @@ Désactiver la livraison pour une tâche isolée : openclaw cron edit --no-deliver ``` -Activer le contexte d’amorçage léger pour une tâche isolée : +Activer un contexte de bootstrap léger pour une tâche isolée : ```bash openclaw cron edit --light-context ``` -Annoncer sur un canal spécifique : +Annoncer vers un canal spécifique : ```bash openclaw cron edit --announce --channel slack --to "channel:C1234567890" @@ -196,7 +196,7 @@ Annoncer vers un sujet de forum Telegram : openclaw cron edit --announce --channel telegram --to "-1001234567890" --thread-id 42 ``` -Créer une tâche isolée avec un contexte d’amorçage léger : +Créer une tâche isolée avec un contexte de bootstrap léger : ```bash openclaw cron add \ @@ -208,7 +208,7 @@ openclaw cron add \ --no-deliver ``` -`--light-context` s’applique uniquement aux tâches de tour d’agent isolées. Pour les exécutions Cron, le mode léger garde le contexte d’amorçage vide au lieu d’injecter l’ensemble complet d’amorçage de l’espace de travail. +`--light-context` s’applique uniquement aux tâches de tour d’agent isolées. Pour les exécutions Cron, le mode léger garde le contexte de bootstrap vide au lieu d’injecter l’ensemble complet de bootstrap de l’espace de travail. ## Commandes d’administration courantes @@ -216,13 +216,16 @@ Exécution manuelle et inspection : ```bash openclaw cron list +openclaw cron list --agent ops openclaw cron show openclaw cron run openclaw cron run --due openclaw cron runs --id --limit 50 ``` -Les entrées de `cron runs` incluent des diagnostics de livraison avec la cible Cron prévue, la cible résolue, les envois par l’outil de message, l’utilisation du secours et l’état de livraison. +`openclaw cron list` affiche toutes les tâches correspondantes par défaut. Passez `--agent ` pour afficher uniquement les tâches dont l’identifiant d’agent normalisé effectif correspond ; les tâches sans identifiant d’agent stocké comptent comme l’agent par défaut configuré. + +Les entrées `cron runs` incluent des diagnostics de livraison avec la cible Cron prévue, la cible résolue, les envois par l’outil de message, l’utilisation du secours et l’état livré. Reciblage de l’agent et de la session : @@ -233,7 +236,7 @@ openclaw cron edit --session current openclaw cron edit --session "session:daily-brief" ``` -`openclaw cron add` avertit lorsque `--agent` est omis sur les tâches de tour d’agent et se rabat sur l’agent par défaut (`main`). Passez `--agent ` au moment de la création pour épingler un agent spécifique. +`openclaw cron add` avertit lorsque `--agent` est omis sur les tâches de tour d’agent et se rabat sur l’agent par défaut (`main`). Passez `--agent ` à la création pour épingler un agent spécifique. Ajustements de livraison : diff --git a/docs/fr/cli/status.md b/docs/fr/cli/status.md index c747677c0..fc8865646 100644 --- a/docs/fr/cli/status.md +++ b/docs/fr/cli/status.md @@ -1,21 +1,21 @@ --- read_when: - - Vous souhaitez un diagnostic rapide de l’état des canaux + des destinataires des sessions récentes - - Vous souhaitez un état « all » prêt à coller pour le débogage + - Vous voulez un diagnostic rapide de l’état de santé des canaux + des destinataires des sessions récentes + - Vous voulez un statut « all » prêt à coller pour le débogage summary: Référence CLI pour `openclaw status` (diagnostics, sondes, instantanés d’utilisation) title: Statut x-i18n: - generated_at: "2026-04-30T07:20:09Z" + generated_at: "2026-05-05T06:16:20Z" model: gpt-5.5 provider: openai - source_hash: a85613e1830dc24253847e6517d3e155c175bb39ff6b01031ac5cb4291e276fa + source_hash: 5025ed99d351a43adc60b6896349366b225fd7ecb8ab422dba376f2d157f0033 source_path: cli/status.md workflow: 16 --- # `openclaw status` -Diagnostics pour les canaux + les sessions. +Diagnostics des canaux et des sessions. ```bash openclaw status @@ -24,27 +24,28 @@ openclaw status --deep openclaw status --usage ``` -Notes : +Remarques : - `--deep` exécute des sondes en direct (WhatsApp Web + Telegram + Discord + Slack + Signal). -- `openclaw status` simple reste sur le chemin rapide en lecture seule et marque la mémoire comme `not checked` au lieu de non disponible lorsqu’il ignore l’inspection de la mémoire. L’audit de sécurité lourd, la compatibilité des plugins et les sondes de vecteurs mémoire sont laissés à `openclaw status --all`, `openclaw status --deep`, `openclaw security audit` et `openclaw memory status --deep`. -- `status --json --all` signale les détails de mémoire depuis le runtime du plugin de mémoire active sélectionné par `plugins.slots.memory`. Les plugins de mémoire personnalisés peuvent laisser `agents.defaults.memorySearch.enabled` intégré désactivé tout en signalant leurs propres fichiers, segments, vecteurs et état FTS. -- `--usage` affiche les fenêtres d’utilisation normalisées des fournisseurs sous la forme `X% left`. -- La sortie de statut de session sépare `Execution:` de `Runtime:`. `Execution` correspond au chemin du bac à sable (`direct`, `docker/*`), tandis que `Runtime` indique si la session utilise `OpenClaw Pi Default`, `OpenAI Codex`, un backend CLI ou un backend ACP tel que `codex (acp/acpx)`. Consultez [Runtimes d’agent](/fr/concepts/agent-runtimes) pour la distinction entre fournisseur, modèle et runtime. -- Les champs bruts `usage_percent` / `usagePercent` de MiniMax représentent le quota restant ; OpenClaw les inverse donc avant l’affichage. Les champs basés sur le comptage l’emportent lorsqu’ils sont présents. Les réponses `model_remains` privilégient l’entrée du modèle de chat, dérivent l’étiquette de fenêtre à partir des horodatages si nécessaire et incluent le nom du modèle dans l’étiquette du plan. -- Lorsque l’instantané de session actuel est fragmentaire, `/status` peut compléter les compteurs de tokens et de cache à partir du journal d’utilisation de transcript le plus récent. Les valeurs en direct non nulles existantes l’emportent toujours sur les valeurs de repli du transcript. -- Le repli sur transcript peut aussi récupérer l’étiquette du modèle de runtime actif lorsqu’elle manque dans l’entrée de session en direct. Si ce modèle de transcript diffère du modèle sélectionné, le statut résout la fenêtre de contexte d’après le modèle de runtime récupéré au lieu du modèle sélectionné. -- Pour la comptabilisation de la taille d’invite, le repli sur transcript privilégie le total orienté invite le plus élevé lorsque les métadonnées de session sont absentes ou inférieures, afin que les sessions de fournisseurs personnalisés ne retombent pas sur des affichages à `0` token. +- `openclaw status` simple reste sur le chemin rapide en lecture seule et marque la mémoire comme `not checked` au lieu d’indisponible lorsqu’il ignore l’inspection de la mémoire. L’audit de sécurité lourd, la compatibilité des plugins et les sondes de vecteurs mémoire sont réservés à `openclaw status --all`, `openclaw status --deep`, `openclaw security audit` et `openclaw memory status --deep`. +- `status --json --all` signale les détails de mémoire depuis l’environnement d’exécution du plugin de mémoire actif sélectionné par `plugins.slots.memory`. Les plugins de mémoire personnalisés peuvent laisser le réglage intégré `agents.defaults.memorySearch.enabled` désactivé tout en signalant leurs propres fichiers, fragments, vecteurs et état FTS. +- `--usage` affiche les fenêtres d’utilisation normalisées du fournisseur sous la forme `X% left`. +- La sortie d’état de session sépare `Execution:` de `Runtime:`. `Execution` est le chemin du bac à sable (`direct`, `docker/*`), tandis que `Runtime` indique si la session utilise `OpenClaw Pi Default`, `OpenAI Codex`, un backend CLI ou un backend ACP tel que `codex (acp/acpx)`. Consultez [Environnements d’exécution des agents](/fr/concepts/agent-runtimes) pour la distinction entre fournisseur, modèle et environnement d’exécution. +- Les champs bruts `usage_percent` / `usagePercent` de MiniMax correspondent au quota restant ; OpenClaw les inverse donc avant l’affichage. Les champs basés sur le nombre l’emportent lorsqu’ils sont présents. Les réponses `model_remains` privilégient l’entrée du modèle de chat, déduisent l’étiquette de fenêtre à partir des horodatages si nécessaire et incluent le nom du modèle dans l’étiquette du forfait. +- Lorsque l’instantané de la session actuelle est clairsemé, `/status` peut compléter les compteurs de jetons et de cache depuis le journal d’utilisation de transcript le plus récent. Les valeurs en direct non nulles existantes l’emportent toujours sur les valeurs de repli du transcript. +- `/status` inclut la disponibilité compacte du processus Gateway et la disponibilité du système hôte. +- Le repli sur transcript peut aussi récupérer l’étiquette du modèle d’environnement d’exécution actif lorsque l’entrée de session en direct ne l’inclut pas. Si ce modèle de transcript diffère du modèle sélectionné, l’état résout la fenêtre de contexte par rapport au modèle d’environnement d’exécution récupéré plutôt qu’au modèle sélectionné. +- Pour la comptabilisation de la taille d’invite, le repli sur transcript privilégie le total orienté invite le plus élevé lorsque les métadonnées de session sont absentes ou inférieures, afin que les sessions de fournisseurs personnalisés ne s’effondrent pas vers des affichages à `0` jeton. - La sortie inclut les magasins de sessions par agent lorsque plusieurs agents sont configurés. -- La vue d’ensemble inclut le statut d’installation et de runtime du Gateway + service hôte Node lorsqu’il est disponible. -- La vue d’ensemble inclut le canal de mise à jour + le SHA git (pour les checkouts source). -- Les informations de mise à jour apparaissent dans la vue d’ensemble ; si une mise à jour est disponible, le statut affiche une indication invitant à exécuter `openclaw update` (voir [Mise à jour](/fr/install/updating)). -- Les surfaces de statut en lecture seule (`status`, `status --json`, `status --all`) résolvent les SecretRefs pris en charge pour leurs chemins de configuration ciblés lorsque c’est possible. -- Si un SecretRef de canal pris en charge est configuré mais indisponible dans le chemin de commande actuel, le statut reste en lecture seule et signale une sortie dégradée au lieu de planter. La sortie humaine affiche des avertissements tels que « jeton configuré indisponible dans ce chemin de commande », et la sortie JSON inclut `secretDiagnostics`. -- Lorsque la résolution de SecretRef locale à la commande réussit, le statut privilégie l’instantané résolu et efface les marqueurs transitoires « secret unavailable » des canaux dans la sortie finale. +- La vue d’ensemble inclut l’état d’installation et d’exécution du service hôte Gateway + node lorsqu’il est disponible. +- La vue d’ensemble inclut le canal de mise à jour + le SHA git (pour les extractions source). +- Les informations de mise à jour apparaissent dans la vue d’ensemble ; si une mise à jour est disponible, l’état affiche une indication pour exécuter `openclaw update` (voir [Mise à jour](/fr/install/updating)). +- Les surfaces d’état en lecture seule (`status`, `status --json`, `status --all`) résolvent les SecretRefs pris en charge pour leurs chemins de configuration ciblés lorsque c’est possible. +- Si un SecretRef de canal pris en charge est configuré mais indisponible dans le chemin de commande actuel, l’état reste en lecture seule et signale une sortie dégradée au lieu de planter. La sortie destinée aux humains affiche des avertissements tels que « jeton configuré indisponible dans ce chemin de commande », et la sortie JSON inclut `secretDiagnostics`. +- Lorsque la résolution command-local de SecretRef réussit, l’état privilégie l’instantané résolu et efface les marqueurs transitoires « secret indisponible » du canal dans la sortie finale. - `status --all` inclut une ligne de vue d’ensemble des secrets et une section de diagnostic qui résume les diagnostics de secrets (tronqués pour la lisibilité) sans arrêter la génération du rapport. -## Associé +## Voir aussi - [Référence CLI](/fr/cli) - [Doctor](/fr/gateway/doctor) diff --git a/docs/fr/concepts/agent-loop.md b/docs/fr/concepts/agent-loop.md index 7e8dc5c00..e345e0854 100644 --- a/docs/fr/concepts/agent-loop.md +++ b/docs/fr/concepts/agent-loop.md @@ -1,24 +1,24 @@ --- read_when: - - Vous avez besoin d’une procédure pas à pas précise de la boucle de l’agent ou des événements du cycle de vie + - Vous avez besoin d’un guide pas à pas précis 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 de 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 +title: Boucle de l’agent x-i18n: - generated_at: "2026-05-03T21:29:42Z" + generated_at: "2026-05-05T06:16:16Z" model: gpt-5.5 provider: openai - source_hash: 1bdd8e98710dce6412f499c37d2d74445f44f93142364c30993de517fdea6c56 + source_hash: 1c7031a2b70e7a891f51fa127df6f04663db81400715717f50dd840a3fa5b745 source_path: concepts/agent-loop.md workflow: 16 --- -Une boucle agentique est l’exécution complète « réelle » d’un agent : réception → assemblage du contexte → inférence du modèle → -exécution des 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 gardant l’état de session cohérent. +Une boucle agentique correspond à 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 de référence qui transforme un message +en actions et en réponse finale, tout en maintenant la cohérence de l’état de session. 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 réfléchit, appelle des outils et diffuse la sortie. Cette documentation explique comment cette boucle authentique est +pendant que le modèle réfléchit, 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 @@ -28,117 +28,117 @@ câblée de bout en bout. ## Fonctionnement (vue d’ensemble) -1. La RPC `agent` valide les paramètres, résout la session (sessionKey/sessionId), persiste les métadonnées de session, retourne 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 + - charge l’instantané des Skills - appelle `runEmbeddedPiAgent` (runtime pi-agent-core) - émet **fin/erreur de cycle de vie** si la boucle intégrée n’en émet pas 3. `runEmbeddedPiAgent` : - - sérialise les exécutions via des files d’attente par session + globales + - sérialise les exécutions via des files par session + globale - résout le modèle + le profil d’authentification et construit la session pi - - s’abonne aux événements pi et diffuse les deltas d’assistant/d’outil - - applique le délai d’expiration -> abandonne l’exécution s’il est dépassé - - pour les tours du serveur d’application Codex, abandonne un tour accepté qui cesse de produire de la progression côté serveur d’application avant un événement terminal - - retourne les charges utiles + les métadonnées d’utilisation + - s’abonne aux événements pi et diffuse les deltas assistant/outil + - impose un délai d’expiration -> interrompt l’exécution si celui-ci est dépassé + - pour les tours du serveur d’application Codex, interrompt un tour accepté qui cesse de produire de la progression du serveur d’application avant un événement terminal + - renvoie les charges utiles + les métadonnées d’utilisation 4. `subscribeEmbeddedPiSession` relie les événements pi-agent-core au flux `agent` d’OpenClaw : - événements d’outil => `stream: "tool"` - - deltas d’assistant => `stream: "assistant"` + - deltas de l’assistant => `stream: "assistant"` - événements de cycle de vie => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` utilise `waitForAgentRun` : - attend **fin/erreur de cycle de vie** pour `runId` - - retourne `{ status: ok|error|timeout, startedAt, endedAt, error? }` + - renvoie `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## Mise en file d’attente + concurrence +## Mise en file + concurrence -- 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 garde 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). -- Les écritures de transcription sont également protégées par un verrou d’écriture de session sur le fichier de session. Le verrou est - conscient du processus et basé sur fichier ; il détecte donc les rédacteurs qui contournent la file d’attente en processus ou proviennent - d’un autre processus. Les rédacteurs de transcription de session attendent jusqu’à `session.writeLock.acquireTimeoutMs` +- 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 la cohérence de l’historique de session. +- Les canaux de messagerie peuvent choisir des modes de file (collect/steer/followup) qui alimentent ce système de voies. + 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 du processus et basé sur un fichier, ce qui lui permet de détecter les rédacteurs qui contournent la file en processus ou proviennent + d’un autre processus. Les rédacteurs de transcripts de session attendent jusqu’à `session.writeLock.acquireTimeoutMs` avant de signaler que la session est occupée ; la valeur par défaut est `60000` ms. -- Les verrous d’écriture de session sont non réentrants par défaut. Si un assistant imbrique intentionnellement l’acquisition du - même verrou tout en préservant un rédacteur logique unique, il doit s’y inscrire explicitement avec +- Les verrous d’écriture de session ne sont pas réentrants par défaut. Si un helper 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 en bac à sable. +- 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. +- 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 transcription, Compaction ou troncature doit prendre le même verrou avant d’ouvrir ou - de modifier le fichier de transcription. + 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. ## 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 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 savoir ce que voit le modèle. +- Les limites propres au modèle et les jetons réservés à la Compaction sont appliqués. +- Voir [Prompt système](/fr/concepts/system-prompt) pour ce que le modèle voit. -## Points d’accroche (où vous pouvez intercepter) +## Points de hook (où vous pouvez intercepter) -OpenClaw dispose de deux systèmes de hooks : +OpenClaw possè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 Plugin** : points d’extension dans le cycle de vie de l’agent/outil et le pipeline Gateway. +- **Hooks internes** (hooks Gateway) : scripts pilotés par événements pour les commandes et les événements de cycle de vie. +- **Hooks de Plugin** : points d’extension dans le cycle de vie de l’agent/outil et le pipeline Gateway. ### Hooks internes (hooks Gateway) -- **`agent:bootstrap`** : s’exécute lors de la construction des fichiers de bootstrap avant la finalisation du prompt système. +- **`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 la documentation Hooks). Voir [Hooks](/fr/automation/hooks) pour la configuration et des exemples. -### Hooks Plugin (cycle de vie de l’agent + Gateway) +### Hooks de Plugin (cycle de vie agent + Gateway) -Ils s’exécutent dans la boucle d’agent ou le pipeline Gateway : +Ils s’exécutent dans la boucle agent ou le pipeline Gateway : -- **`before_model_resolve`** : s’exécute avant la session (sans `messages`) pour remplacer déterministiquement 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 la soumission du prompt. Utilisez `prependContext` pour le texte dynamique par tour et les champs de contexte système pour les consignes stables qui doivent résider dans l’espace du prompt système. +- **`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 session (avec `messages`) pour injecter `prependContext`, `systemPrompt`, `prependSystemContext` ou `appendSystemContext` avant la soumission du prompt. Utilisez `prependContext` pour le texte dynamique par tour et les champs de contexte système pour les consignes stables qui doivent rester 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, permettant à un Plugin de revendiquer le tour et de retourner une réponse synthétique ou de rendre le tour entièrement silencieux. -- **`agent_end`** : inspecte la liste finale des messages et les métadonnées d’exécution après achèvement. +- **`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 rendre le tour entièrement silencieux. +- **`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 de scan intégrés et peut éventuellement bloquer les installations de skill ou de Plugin. -- **`tool_result_persist`** : transforme de façon synchrone les résultats d’outil avant leur écriture dans une transcription de session appartenant à OpenClaw. +- **`before_install`** : inspecte les résultats de scan intégrés et peut bloquer les installations de Skills ou de plugins. +- **`tool_result_persist`** : transforme de manière synchrone les résultats d’outil avant leur écriture dans un transcript de session détenu par OpenClaw. - **`message_received` / `message_sending` / `message_sent`** : hooks de messages entrants + sortants. -- **`session_start` / `session_end`** : limites de cycle de vie de session. +- **`session_start` / `session_end`** : limites du cycle de vie de session. - **`gateway_start` / `gateway_stop`** : événements de cycle de vie Gateway. -Règles de décision des hooks pour les garde-fous sortants/d’outils : +Règles de décision des hooks pour les protections sortantes/d’outil : - `before_tool_call` : `{ block: true }` est terminal et arrête les gestionnaires de priorité inférieure. -- `before_tool_call` : `{ block: false }` est sans effet et n’efface pas un blocage antérieur. +- `before_tool_call` : `{ block: false }` est un no-op et n’efface pas un blocage précédent. - `before_install` : `{ block: true }` est terminal et arrête les gestionnaires de priorité inférieure. -- `before_install` : `{ block: false }` est sans effet et n’efface pas un blocage antérieur. +- `before_install` : `{ block: false }` est un no-op et n’efface pas un blocage précédent. - `message_sending` : `{ cancel: true }` est terminal et arrête les gestionnaires de priorité inférieure. -- `message_sending` : `{ cancel: false }` est sans effet et n’efface pas une annulation antérieure. +- `message_sending` : `{ cancel: false }` est un no-op et n’efface pas une annulation précédente. -Voir [Hooks Plugin](/fr/plugins/hooks) pour l’API des hooks et les détails d’inscription. +Voir [Hooks de Plugin](/fr/plugins/hooks) pour l’API de hooks et les détails d’enregistrement. Les harnais peuvent adapter ces hooks différemment. Le harnais du serveur d’application Codex conserve -les hooks Plugin OpenClaw comme contrat de compatibilité pour les surfaces miroir documentées, +les hooks de Plugin OpenClaw comme contrat de compatibilité pour les surfaces documentées en miroir, tandis que les hooks natifs Codex restent un mécanisme Codex distinct de plus bas niveau. ## Streaming + réponses partielles -- Les deltas d’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`. +- Les deltas de l’assistant sont diffusés depuis pi-agent-core et émis comme événements `assistant`. +- Le streaming par blocs peut émettre des réponses partielles soit sur `text_end`, soit sur `message_end`. - Le streaming de raisonnement peut être émis comme flux séparé ou comme réponses par blocs. -- Voir [Streaming](/fr/concepts/streaming) pour le comportement de découpage et de réponse par bloc. +- Voir [Streaming](/fr/concepts/streaming) pour le comportement de découpage et de réponse par blocs. ## 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 charges utiles d’image avant journalisation/émission. -- Les envois d’outil de messagerie sont suivis pour supprimer les confirmations d’assistant dupliquées. +- Les résultats d’outil sont nettoyés en taille et en charges utiles d’image avant journalisation/émission. +- Les envois par outil de messagerie sont suivis pour supprimer les confirmations d’assistant en double. -## Mise en forme + suppression des réponses +## Façonnage + suppression des réponses - Les charges utiles finales sont assemblées à partir de : - texte de l’assistant (et raisonnement facultatif) @@ -146,44 +146,44 @@ tandis que les hooks natifs Codex restent un mécanisme Codex distinct de plus b - texte d’erreur de l’assistant lorsque le modèle échoue - Le jeton silencieux exact `NO_REPLY` / `no_reply` est filtré des charges utiles sortantes. -- Les doublons d’outil de messagerie sont retirés de la liste finale des charges utiles. +- Les doublons d’outils de messagerie sont retirés de la liste finale des charges utiles. - S’il ne reste aucune charge utile affichable 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 une sortie dupliquée. +- Lors d’une nouvelle tentative, les tampons en mémoire et les résumés d’outils sont réinitialisés afin d’éviter les sorties en double. - Voir [Compaction](/fr/concepts/compaction) pour le pipeline de Compaction. ## Flux d’événements (aujourd’hui) -- `lifecycle` : émis par `subscribeEmbeddedPiSession` (et en solution de repli par `agentCommand`) +- `lifecycle` : émis par `subscribeEmbeddedPiSession` (et en secours 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 de chat `delta`. -- Un `final` de chat est émis lors de **fin/erreur de cycle de vie**. +- Les deltas de l’assistant sont mis en tampon dans des messages de chat `delta`. +- Un `final` de chat est émis sur **fin/erreur de cycle de vie**. ## Délais d’expiration - Valeur par défaut de `agent.wait` : 30 s (uniquement 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` d’un tour d’agent isolé appartient à cron. Le planificateur démarre ce minuteur lorsque l’exécution commence, 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. -- Diagnostics de vivacité de session : lorsque les diagnostics sont activés, `diagnostics.stuckSessionWarnMs` classe les longues sessions `processing` qui n’ont aucune réponse, outil, statut, bloc ou progression ACP observés. Les exécutions intégrées actives, appels de modèle et appels d’outil sont signalés comme `session.long_running` ; le travail actif sans progression récente est signalé comme `session.stalled` ; `session.stuck` est réservé à la comptabilité de session obsolète sans travail actif. La comptabilité de session obsolète libère immédiatement la voie de session concernée ; les exécutions intégrées bloquées ne sont abandonnées et drainées qu’après une fenêtre prolongée sans progression (au moins 10 minutes et 5x le seuil d’avertissement), afin que le travail en file puisse reprendre sans interrompre des exécutions simplement lentes. Les diagnostics `session.stuck` répétés appliquent un délai progressif tant que la session reste inchangée. -- Délai d’inactivité du modèle : OpenClaw abandonne une requête de modèle lorsqu’aucun fragment de réponse n’arrive avant la fenêtre d’inactivité. `models.providers..timeoutSeconds` étend ce chien de garde d’inactivité pour les fournisseurs locaux/auto-hébergés lents ; sinon OpenClaw utilise `agents.defaults.timeoutSeconds` lorsqu’il est configuré, plafonné à 120 s par défaut. Les exécutions déclenchées par Cron sans délai d’expiration explicite de modèle ou d’agent désactivent le chien de garde d’inactivité et s’appuient sur le délai d’expiration externe de Cron. -- Délai d’expiration des requêtes HTTP du fournisseur : `models.providers..timeoutSeconds` s’applique aux récupérations HTTP de modèle de ce fournisseur, y compris la connexion, les en-têtes, le corps, le délai d’expiration de requête du SDK, la gestion d’abandon guarded-fetch totale et le chien de garde d’inactivité du flux de 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 agent : `agents.defaults.timeoutSeconds` vaut par défaut 172800 s (48 heures) ; appliqué dans le minuteur d’interruption de `runEmbeddedPiAgent`. +- Runtime Cron : le `timeoutSeconds` des tours agent isolés appartient à Cron. Le planificateur démarre ce minuteur lorsque l’exécution commence, interrompt 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. +- Diagnostics de vivacité de session : avec les diagnostics activés, `diagnostics.stuckSessionWarnMs` classe les longues sessions `processing` qui n’ont pas de réponse, outil, statut, bloc ou progression ACP observés. Les exécutions intégrées, appels de modèle et appels d’outil actifs sont signalés comme `session.long_running` ; le travail actif sans progression récente est signalé comme `session.stalled` ; `session.stuck` est réservé à la comptabilité de session obsolète sans travail actif. La comptabilité de session obsolète libère immédiatement la voie de session affectée ; les exécutions intégrées bloquées ne sont interrompues puis drainées qu’après `diagnostics.stuckSessionAbortMs` (par défaut : au moins 10 minutes et 5x le seuil d’avertissement), afin que le travail en file puisse reprendre sans interrompre de simples exécutions lentes. La récupération émet des résultats structurés demandés/terminés, et l’état de diagnostic n’est marqué inactif que si la même génération de traitement est toujours courante. Les diagnostics `session.stuck` répétés appliquent un backoff tant que la session reste inchangée. +- Délai d’inactivité du modèle : OpenClaw interrompt une requête de modèle lorsqu’aucun fragment de réponse n’arrive avant la fenêtre d’inactivité. `models.providers..timeoutSeconds` étend ce chien de garde d’inactivité pour les fournisseurs locaux/auto-hébergés lents ; sinon OpenClaw utilise `agents.defaults.timeoutSeconds` lorsqu’il est configuré, plafonné à 120 s par défaut. Les exécutions déclenchées par Cron sans délai d’expiration explicite de modèle ou d’agent désactivent le chien de garde d’inactivité et s’appuient sur le délai d’expiration externe de Cron. +- Délai d’expiration des requêtes HTTP du fournisseur : `models.providers..timeoutSeconds` s’applique aux fetches HTTP du 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 d’interruption de fetch gardé total et le chien de garde d’inactivité du flux de modèle. Utilisez-le pour les fournisseurs locaux/auto-hébergés lents comme Ollama avant d’augmenter le délai d’expiration global du runtime agent. -## Où les choses peuvent se terminer plus tôt +## 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 Gateway ou délai d’expiration RPC - Délai d’expiration `agent.wait` (attente uniquement, n’arrête pas l’agent) -## Associé +## Associés - [Outils](/fr/tools) — outils d’agent disponibles - [Hooks](/fr/automation/hooks) — scripts pilotés par événements déclenchés par les événements de cycle de vie de l’agent diff --git a/docs/fr/concepts/mantis.md b/docs/fr/concepts/mantis.md index 8506d2b7d..7a0606f8e 100644 --- a/docs/fr/concepts/mantis.md +++ b/docs/fr/concepts/mantis.md @@ -1,65 +1,65 @@ --- read_when: - - Mettre en place ou exécuter un contrôle qualité visuel en direct pour les bogues OpenClaw + - Créer ou exécuter une assurance qualité visuelle en direct pour les bogues OpenClaw - Ajout d’une vérification avant et après pour une demande de tirage - - Ajout de scénarios de transport en direct pour Discord, Slack, WhatsApp ou autres - - Débogage des exécutions QA nécessitant des captures d’écran, l’automatisation du navigateur ou un accès VNC + - Ajout de scénarios de transport en direct Discord, Slack, WhatsApp ou autres + - Débogage des exécutions d’assurance qualité nécessitant des captures d’écran, l’automatisation du navigateur ou un accès VNC summary: Mantis est le système de vérification visuelle de bout en bout permettant de reproduire les bogues d’OpenClaw sur des transports en direct, de capturer des preuves avant et après, et de joindre des artefacts aux PR. title: Mante x-i18n: - generated_at: "2026-05-04T07:03:09Z" + generated_at: "2026-05-05T06:16:29Z" model: gpt-5.5 provider: openai - source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164 + source_hash: 26a9671135e38bf82d3627364f691f8d91cc8649ffc2e5fa782ebef474a44fa1 source_path: concepts/mantis.md workflow: 16 --- -Mantis est le système de vérification de bout en bout d’OpenClaw pour les bugs qui nécessitent un environnement d’exécution réel, un transport réel et une preuve visible. Il exécute un scénario contre une ref connue comme défectueuse, capture les preuves, exécute le même scénario contre une ref candidate, puis publie la comparaison sous forme d’artefacts qu’un mainteneur peut inspecter depuis une PR ou depuis une commande locale. +Mantis est le système de vérification de bout en bout d’OpenClaw pour les bugs qui nécessitent un vrai runtime, un vrai transport et une preuve visible. Il exécute un scénario contre une référence connue comme défectueuse, capture les éléments de preuve, exécute le même scénario contre une référence candidate et publie la comparaison sous forme d’artefacts qu’un mainteneur peut inspecter depuis une PR ou depuis une commande locale. -Mantis commence avec Discord parce que Discord nous donne une première voie à forte valeur : authentification de bot réelle, vrais salons de guilde, réactions, fils de discussion, commandes natives et une interface navigateur où les humains peuvent confirmer visuellement ce que le transport a montré. +Mantis commence avec Discord parce que Discord nous donne une première voie à forte valeur : authentification réelle du bot, vrais canaux de guilde, réactions, fils, commandes natives et une UI de navigateur où les humains peuvent confirmer visuellement ce que le transport a montré. ## Objectifs -- Reproduire un bug depuis une issue ou une PR GitHub avec la même forme de transport que celle vue par les utilisateurs. -- Capturer un artefact **avant** sur la ref de référence avant d’appliquer le correctif. -- Capturer un artefact **après** sur la ref candidate après avoir appliqué le correctif. -- Utiliser un oracle déterministe chaque fois que possible, comme une lecture de réaction via l’API REST Discord ou une vérification de transcription de salon. -- Capturer des captures d’écran lorsque le bug possède une surface d’interface visible. -- S’exécuter localement depuis une CLI contrôlée par un agent et à distance depuis GitHub. -- Préserver suffisamment d’état machine pour un secours VNC lorsque la connexion, l’automatisation du navigateur ou l’authentification du fournisseur se bloque. -- Publier un statut concis dans un salon Discord opérateur lorsque l’exécution est bloquée, nécessite une aide VNC manuelle ou se termine. +- Reproduire un bug depuis une issue GitHub ou une PR avec la même forme de transport que celle que voient les utilisateurs. +- Capturer un artefact **avant** sur la référence de base avant d’appliquer le correctif. +- Capturer un artefact **après** sur la référence candidate après avoir appliqué le correctif. +- Utiliser un oracle déterministe chaque fois que possible, comme une lecture de réaction via l’API REST Discord ou une vérification de transcription de canal. +- Capturer des captures d’écran lorsque le bug a une surface UI visible. +- Exécuter localement depuis une CLI contrôlée par un agent et à distance depuis GitHub. +- Préserver assez d’état machine pour un secours VNC lorsque la connexion, l’automatisation du navigateur ou l’authentification du fournisseur se bloque. +- Publier un statut concis dans un canal Discord opérateur lorsque l’exécution est bloquée, nécessite une aide VNC manuelle ou se termine. ## Non-objectifs -- Mantis ne remplace pas les tests unitaires. Une exécution Mantis devrait généralement devenir un test de régression plus petit une fois le correctif compris. -- Mantis n’est pas le portail CI rapide normal. Il est plus lent, utilise des identifiants réels et est réservé aux bugs où l’environnement réel compte. -- Mantis ne devrait pas nécessiter d’humain en fonctionnement normal. Le VNC manuel est une voie de secours, pas le chemin nominal. +- Mantis ne remplace pas les tests unitaires. Une exécution Mantis doit généralement devenir un test de régression plus petit une fois le correctif compris. +- Mantis n’est pas le gate CI rapide normal. Il est plus lent, utilise des identifiants live et est réservé aux bugs où l’environnement live compte. +- Mantis ne doit pas nécessiter d’humain en fonctionnement normal. Le VNC manuel est une voie de secours, pas le chemin nominal. - Mantis ne stocke pas de secrets bruts dans les artefacts, journaux, captures d’écran, rapports Markdown ou commentaires de PR. ## Propriété Mantis vit dans la pile QA d’OpenClaw. -- OpenClaw possède l’environnement d’exécution des scénarios, les adaptateurs de transport, le schéma de preuves et la CLI locale sous `pnpm openclaw qa mantis`. -- QA Lab possède les éléments du harnais de transport réel, les assistants de capture navigateur et les rédacteurs d’artefacts. +- OpenClaw possède le runtime de scénario, les adaptateurs de transport, le schéma de preuves et la CLI locale sous `pnpm openclaw qa mantis`. +- QA Lab possède les pièces du harnais de transport live, les assistants de capture du navigateur et les rédacteurs d’artefacts. - Crabbox possède les machines Linux préchauffées lorsqu’une VM distante est nécessaire. - GitHub Actions possède le point d’entrée du workflow distant et la rétention des artefacts. -- ClawSweeper possède le routage des commentaires GitHub : analyse des commandes mainteneur, déclenchement du workflow et publication du commentaire final sur la PR. +- ClawSweeper possède le routage des commentaires GitHub : analyse des commandes de mainteneur, déclenchement du workflow et publication du commentaire final de PR. - Les agents OpenClaw pilotent Mantis via Codex lorsqu’un scénario nécessite une configuration agentique, du débogage ou un signalement d’état bloqué. -Cette limite garde la connaissance du transport dans OpenClaw, la planification des machines dans Crabbox et la colle du workflow mainteneur dans ClawSweeper. +Cette limite conserve la connaissance du transport dans OpenClaw, la planification des machines dans Crabbox et la glue du workflow mainteneur dans ClawSweeper. -## Forme de commande +## Forme des commandes -La première commande locale vérifie le bot Discord, la guilde, le salon, l’envoi de message, l’envoi de réaction et le chemin d’artefact : +La première commande locale vérifie le bot Discord, la guilde, le canal, l’envoi de message, l’envoi de réaction et le chemin des artefacts : ```bash pnpm openclaw qa mantis discord-smoke \ --output-dir .artifacts/qa-e2e/mantis/discord-smoke ``` -L’exécuteur local avant et après accepte cette forme : +Le lanceur local avant et après accepte cette forme : ```bash pnpm openclaw qa mantis run \ @@ -70,7 +70,7 @@ pnpm openclaw qa mantis run \ --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions ``` -L’exécuteur crée des worktrees détachés de référence et candidats sous le répertoire de sortie, installe les dépendances, construit chaque ref, exécute le scénario avec `--allow-failures`, puis écrit `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md`. Pour le premier scénario Discord, une vérification réussie signifie que le statut de référence est `fail` et que le statut candidat est `pass`. +Le lanceur crée des worktrees détachés pour la référence de base et la candidate sous le répertoire de sortie, installe les dépendances, construit chaque référence, exécute le scénario avec `--allow-failures`, puis écrit `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md`. Pour le premier scénario Discord, une vérification réussie signifie que le statut de base est `fail` et que le statut candidat est `pass`. La première primitive VM/navigateur est le smoke desktop : @@ -79,14 +79,14 @@ pnpm openclaw qa mantis desktop-browser-smoke \ --output-dir .artifacts/qa-e2e/mantis/desktop-browser ``` -Elle loue ou réutilise une machine desktop Crabbox, démarre un navigateur visible dans la session VNC, capture le desktop, rapatrie les artefacts dans le répertoire de sortie local et écrit la commande de reconnexion dans le rapport. La commande utilise par défaut le fournisseur Hetzner parce qu’il est le premier fournisseur avec une couverture desktop/VNC fonctionnelle dans la voie Mantis. Remplacez-le avec `--provider`, `--crabbox-bin` ou `OPENCLAW_MANTIS_CRABBOX_PROVIDER` lors de l’exécution contre une autre flotte Crabbox. +Elle loue ou réutilise une machine desktop Crabbox, démarre un navigateur visible dans la session VNC, capture le bureau, récupère les artefacts dans le répertoire de sortie local et écrit la commande de reconnexion dans le rapport. La commande utilise par défaut le fournisseur Hetzner parce qu’il est le premier fournisseur avec une couverture desktop/VNC fonctionnelle dans la voie Mantis. Remplacez-le avec `--provider`, `--crabbox-bin` ou `OPENCLAW_MANTIS_CRABBOX_PROVIDER` lors de l’exécution contre une autre flotte Crabbox. -Options utiles du smoke desktop : +Indicateurs utiles pour le smoke desktop : - `--lease-id ` ou `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` réutilise un desktop préchauffé. - `--browser-url ` change la page ouverte dans le navigateur visible. -- `--html-file ` rend un artefact HTML local au dépôt dans le navigateur visible. Mantis l’utilise pour capturer la chronologie générée des réactions de statut Discord via un vrai desktop Crabbox. -- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` garde ouverte une location nouvellement créée et réussie pour inspection VNC. Les exécutions échouées gardent la location par défaut lorsqu’elle a été créée afin qu’un opérateur puisse se reconnecter. +- `--html-file ` affiche un artefact HTML local au dépôt dans le navigateur visible. Mantis l’utilise pour capturer la chronologie générée des réactions de statut Discord via un vrai desktop Crabbox. +- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` conserve ouverte une location nouvellement créée et réussie pour inspection VNC. Les exécutions échouées conservent la location par défaut lorsqu’elle a été créée afin qu’un opérateur puisse se reconnecter. - `--class`, `--idle-timeout` et `--ttl` ajustent la taille de machine et la durée de vie de la location. La première primitive complète de transport desktop est le smoke desktop Slack : @@ -99,9 +99,9 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Elle loue ou réutilise une machine desktop Crabbox, synchronise le checkout courant dans la VM, exécute `pnpm openclaw qa slack` dans cette VM, ouvre Slack Web dans le navigateur VNC, capture le desktop visible et recopie à la fois les artefacts QA Slack et la capture d’écran VNC dans le répertoire de sortie local. C’est la première forme Mantis où le Gateway OpenClaw SUT et le navigateur vivent tous deux dans la même VM desktop Linux. +Elle loue ou réutilise une machine desktop Crabbox, synchronise le checkout actuel dans la VM, exécute `pnpm openclaw qa slack` dans cette VM, ouvre Slack Web dans le navigateur VNC, capture le bureau visible et copie à la fois les artefacts QA Slack et la capture d’écran VNC dans le répertoire de sortie local. C’est la première forme Mantis où le Gateway OpenClaw du SUT et le navigateur vivent tous deux dans la même VM desktop Linux. -Avec `--gateway-setup`, la commande prépare un home OpenClaw jetable persistant dans `$HOME/.openclaw-mantis/slack-openclaw`, corrige la configuration Slack Socket Mode pour le salon sélectionné, démarre `openclaw gateway run` sur le port `38973` et garde Chrome en cours d’exécution dans la session VNC. C’est le mode « laisse-moi un desktop Linux avec Slack et un claw en cours d’exécution » ; la voie QA Slack bot-à-bot reste la valeur par défaut lorsque `--gateway-setup` est omis. +Avec `--gateway-setup`, la commande prépare un home OpenClaw jetable persistant à `$HOME/.openclaw-mantis/slack-openclaw`, patche la configuration Slack Socket Mode pour le canal sélectionné, démarre `openclaw gateway run` sur le port `38973` et garde Chrome en cours d’exécution dans la session VNC. C’est le mode « laissez-moi un desktop Linux avec Slack et un claw en cours d’exécution » ; la voie QA Slack bot-à-bot reste la valeur par défaut lorsque `--gateway-setup` est omis. Entrées requises pour `--credential-source env` : @@ -109,32 +109,32 @@ Entrées requises pour `--credential-source env` : - `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN` - `OPENCLAW_QA_SLACK_SUT_APP_TOKEN` -- `OPENCLAW_LIVE_OPENAI_KEY` pour la voie modèle distante. Si seul `OPENAI_API_KEY` est défini localement, Mantis le mappe vers `OPENCLAW_LIVE_OPENAI_KEY` avant d’invoquer Crabbox afin que le transfert d’env `OPENCLAW_*` de Crabbox puisse le transporter dans la VM. +- `OPENCLAW_LIVE_OPENAI_KEY` pour la voie de modèle distante. Si seul `OPENAI_API_KEY` est défini localement, Mantis le mappe vers `OPENCLAW_LIVE_OPENAI_KEY` avant d’invoquer Crabbox afin que la transmission des variables d’environnement `OPENCLAW_*` de Crabbox puisse l’acheminer dans la VM. -Options utiles du desktop Slack : +Indicateurs utiles pour le desktop Slack : -- `--lease-id ` réexécute contre une machine où un opérateur s’est déjà connecté à Slack Web via VNC. +- `--lease-id ` relance contre une machine où un opérateur s’est déjà connecté à Slack Web via VNC. - `--gateway-setup` démarre un Gateway Slack OpenClaw persistant dans la VM au lieu d’exécuter uniquement la voie QA bot-à-bot. -- `--slack-url ` ouvre une URL Slack Web spécifique. Sans celle-ci, Mantis dérive `https://app.slack.com/client//` depuis `auth.test` de Slack lorsque le jeton du bot SUT est disponible. -- `--slack-channel-id ` contrôle la liste d’autorisation des salons Slack utilisée par la configuration du Gateway. -- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` contrôle le profil Chrome persistant dans la VM. La valeur par défaut est `$HOME/.config/openclaw-mantis/slack-chrome-profile`, afin qu’une connexion manuelle à Slack Web survive aux réexécutions sur la même location. -- `--credential-source convex --credential-role ci` utilise le pool d’identifiants partagé au lieu des jetons env Slack directs. -- `--provider-mode`, `--model`, `--alt-model` et `--fast` sont transmis à la voie Slack réelle. +- `--slack-url ` ouvre une URL Slack Web spécifique. Sans cela, Mantis dérive `https://app.slack.com/client//` depuis `auth.test` de Slack lorsque le jeton du bot SUT est disponible. +- `--slack-channel-id ` contrôle la liste d’autorisation des canaux Slack utilisée par la configuration du Gateway. +- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` contrôle le profil Chrome persistant dans la VM. La valeur par défaut est `$HOME/.config/openclaw-mantis/slack-chrome-profile`, donc une connexion manuelle à Slack Web survit aux relances sur la même location. +- `--credential-source convex --credential-role ci` utilise le pool d’identifiants partagé au lieu de jetons d’environnement Slack directs. +- `--provider-mode`, `--model`, `--alt-model` et `--fast` sont transmis à la voie live Slack. -Le workflow de smoke GitHub est `Mantis Discord Smoke`. Le workflow GitHub avant et après pour le premier vrai scénario est `Mantis Discord Status Reactions`. Il accepte : +Le workflow smoke GitHub est `Mantis Discord Smoke`. Le workflow GitHub avant et après pour le premier scénario réel est `Mantis Discord Status Reactions`. Il accepte : -- `baseline_ref` : la ref censée reproduire le comportement uniquement en file d’attente. -- `candidate_ref` : la ref censée montrer `queued -> thinking -> done`. +- `baseline_ref` : la référence censée reproduire le comportement uniquement en file d’attente. +- `candidate_ref` : la référence censée afficher `queued -> thinking -> done`. -Il checkout la ref du harnais de workflow, construit des worktrees distincts de référence et candidats, exécute `discord-status-reactions-tool-only` contre chaque worktree et téléverse `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md` comme artefacts Actions. Il rend aussi le HTML de chronologie de chaque voie dans un navigateur desktop Crabbox et publie ces captures d’écran VNC à côté des PNG de chronologie déterministes dans le commentaire de PR. Le workflow construit la CLI Crabbox depuis `openclaw/crabbox` main afin de pouvoir utiliser les options de location desktop/navigateur actuelles avant la prochaine publication du binaire Crabbox. +Il checkout la référence du harnais de workflow, construit des worktrees séparés pour la référence de base et la candidate, exécute `discord-status-reactions-tool-only` contre chaque worktree et téléverse `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md` comme artefacts Actions. Il rend également le HTML de chronologie de chaque voie dans un navigateur desktop Crabbox et publie ces captures d’écran VNC à côté des PNG de chronologie déterministes dans le commentaire de PR. Le même commentaire de PR pointe vers les enregistrements MP4 du desktop capturés pendant le rendu du navigateur VNC, tandis que les captures d’écran restent intégrées pour une revue rapide. Le workflow construit la CLI Crabbox depuis `openclaw/crabbox` main afin de pouvoir utiliser les indicateurs actuels de location desktop/navigateur avant la prochaine publication du binaire Crabbox. -Vous pouvez aussi déclencher l’exécution des réactions de statut directement depuis un commentaire de PR : +Vous pouvez aussi déclencher l’exécution status-reactions directement depuis un commentaire de PR : ```text @Mantis discord status reactions ``` -Le déclencheur par commentaire est volontairement étroit. Il ne s’exécute que sur les commentaires de pull request provenant d’utilisateurs disposant des droits write, maintain ou admin, et il ne reconnaît que les requêtes de réactions de statut Discord. Par défaut, il utilise la ref de référence connue comme défectueuse et le SHA de tête de la PR courante comme candidat. Les mainteneurs peuvent remplacer l’une ou l’autre ref : +Le déclencheur par commentaire est volontairement étroit. Il ne s’exécute que sur les commentaires de pull request provenant d’utilisateurs disposant d’un accès write, maintain ou admin, et il ne reconnaît que les requêtes de réactions de statut Discord. Par défaut, il utilise la référence de base connue comme défectueuse et le SHA de tête de la PR actuelle comme candidat. Les mainteneurs peuvent remplacer l’une ou l’autre référence : ```text @Mantis discord status reactions baseline=origin/main candidate=HEAD @@ -147,42 +147,42 @@ Exemples de commandes ClawSweeper : @clawsweeper verify e2e discord ``` -La première commande est explicite et centrée sur le scénario. La seconde pourra plus tard mapper une PR ou une issue vers des scénarios Mantis recommandés à partir des libellés, des fichiers modifiés et des constats de revue ClawSweeper. +La première commande est explicite et centrée sur le scénario. La seconde pourra plus tard mapper une PR ou une issue vers des scénarios Mantis recommandés à partir des libellés, des fichiers modifiés et des conclusions de revue ClawSweeper. -## Cycle de vie de l’exécution +## Cycle de vie d’exécution 1. Acquérir les identifiants. 2. Allouer ou réutiliser une VM. -3. Préparer le profil desktop/navigateur lorsque le scénario nécessite une preuve d’interface. -4. Préparer un checkout propre pour la ref de référence. +3. Préparer le profil desktop/navigateur lorsque le scénario nécessite une preuve UI. +4. Préparer un checkout propre pour la référence de base. 5. Installer les dépendances et construire uniquement ce dont le scénario a besoin. 6. Démarrer un Gateway OpenClaw enfant avec un répertoire d’état isolé. -7. Configurer le transport réel, le fournisseur, le modèle et le profil navigateur. -8. Exécuter le scénario et capturer les preuves de référence. +7. Configurer le transport live, le fournisseur, le modèle et le profil navigateur. +8. Exécuter le scénario et capturer les preuves de base. 9. Arrêter le Gateway et préserver les journaux. -10. Préparer la ref candidate dans la même VM. +10. Préparer la référence candidate dans la même VM. 11. Exécuter le même scénario et capturer les preuves candidates. 12. Comparer les résultats de l’oracle et les preuves visuelles. -13. Écrire le Markdown, le JSON, les journaux, les captures d’écran et les artefacts de trace facultatifs. +13. Écrire Markdown, JSON, journaux, captures d’écran et artefacts de trace facultatifs. 14. Téléverser les artefacts GitHub Actions. -15. Publier un message de statut concis sur la PR ou Discord. +15. Publier un message de statut concis dans une PR ou Discord. -Le scénario devrait pouvoir échouer de deux façons différentes : +Le scénario doit pouvoir échouer de deux façons différentes : -- **Bug reproduit** : la référence a échoué de la façon attendue. -- **Échec du harnais** : la configuration de l’environnement, les identifiants, l’API Discord, le navigateur ou le fournisseur ont échoué avant que l’oracle du bug ne soit significatif. +- **Bug reproduit** : la référence de base a échoué de la manière attendue. +- **Échec du harnais** : la configuration de l’environnement, les identifiants, l’API Discord, le navigateur ou le fournisseur ont échoué avant que l’oracle du bug soit significatif. -Le rapport final doit séparer ces cas afin que les mainteneurs ne confondent pas un environnement flaky avec le comportement du produit. +Le rapport final doit séparer ces cas afin que les mainteneurs ne confondent pas un environnement instable avec le comportement du produit. ## MVP Discord -Le premier scénario devrait cibler les réactions de statut Discord dans les salons de guilde où le mode de livraison de réponse source est `message_tool_only`. +Le premier scénario doit cibler les réactions de statut Discord dans les canaux de guilde où le mode de livraison de réponse source est `message_tool_only`. Pourquoi c’est une bonne graine Mantis : - C’est visible dans Discord sous forme de réactions sur le message déclencheur. -- Il possède un oracle REST solide via l’état des réactions au message Discord. -- Il exerce un vrai Gateway OpenClaw, l’authentification du bot Discord, la distribution de messages, le mode de livraison de réponse source, l’état des réactions de statut et le cycle de vie du tour du modèle. +- Il dispose d’un oracle REST solide via l’état des réactions de message Discord. +- Il exerce un vrai Gateway OpenClaw, l’authentification du bot Discord, la distribution de messages, le mode de livraison de réponse source, l’état des réactions de statut et le cycle de vie d’un tour de modèle. - Il est assez étroit pour garder la première implémentation honnête. Forme de scénario attendue : @@ -216,9 +216,9 @@ evidence: screenshotMessageRow: true ``` -Les preuves de référence devraient montrer la réaction d’accusé de réception en file d’attente, mais aucune transition de cycle de vie en mode tool-only. Les preuves candidates devraient montrer les réactions de statut de cycle de vie s’exécutant lorsque `messages.statusReactions.enabled` est explicitement `true`. +Les preuves de base doivent montrer la réaction d’accusé de réception en file d’attente, mais aucune transition de cycle de vie en mode tool-only. Les preuves candidates doivent montrer les réactions de statut du cycle de vie en cours d’exécution lorsque `messages.statusReactions.enabled` est explicitement `true`. -La première tranche exécutable est le scénario QA Discord réel opt-in : +La première tranche exécutable est le scénario QA live Discord opt-in : ```bash pnpm openclaw qa discord \ @@ -230,22 +230,33 @@ pnpm openclaw qa discord \ --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate ``` -Il configure le SUT avec une gestion des serveurs toujours activée, `visibleReplies: -"message_tool"`, `ackReaction: "👀"` et des réactions de statut explicites. L’oracle interroge le vrai message déclencheur Discord et attend la séquence observée `👀 -> 🤔 -> 👍`. Les artefacts incluent `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` et `discord-status-reactions-tool-only-timeline.png`. +Il configure le SUT avec la gestion des guildes toujours activée, `visibleReplies: +"message_tool"`, `ackReaction: "👀"`, et des réactions d’état explicites. L’oracle +interroge le vrai message déclencheur Discord et attend la séquence observée +`👀 -> 🤔 -> 👍`. Les artefacts incluent `discord-qa-reaction-timelines.json`, +`discord-status-reactions-tool-only-timeline.html`, et +`discord-status-reactions-tool-only-timeline.png`. -## Composants QA existants +## Éléments QA existants -Mantis doit s’appuyer sur la pile QA privée existante au lieu de repartir de zéro : +Mantis doit s’appuyer sur la pile QA privée existante au lieu de repartir de +zéro : -- `pnpm openclaw qa discord` exécute déjà une voie Discord en direct avec des bots pilote et SUT. -- Le runner de transport en direct écrit déjà les rapports et les artefacts de messages observés sous `.artifacts/qa-e2e/`. -- Les baux d’identifiants Convex fournissent déjà un accès exclusif aux identifiants de transport en direct partagés. -- Le service de contrôle du navigateur prend déjà en charge les captures d’écran, les instantanés, les profils gérés headless et les profils CDP distants. -- QA Lab dispose déjà d’une interface de débogage et d’un bus pour les tests de type transport. +- `pnpm openclaw qa discord` exécute déjà une voie Discord en direct avec des bots + pilote et SUT. +- L’exécuteur de transport en direct écrit déjà des rapports et des artefacts de + messages observés sous `.artifacts/qa-e2e/`. +- Les baux d’identifiants Convex fournissent déjà un accès exclusif aux + identifiants de transport en direct partagés. +- Le service de contrôle du navigateur prend déjà en charge les captures d’écran, les instantanés, + les profils gérés headless, et les profils CDP distants. +- QA Lab dispose déjà d’une interface de débogage et d’un bus pour les tests + en forme de transport. -La première implémentation de Mantis peut être un runner avant/après léger par-dessus ces composants, avec une couche de preuve visuelle. +La première implémentation de Mantis peut être un mince exécuteur avant/après par-dessus ces +éléments, avec une couche de preuve visuelle. -## Modèle de preuves +## Modèle de preuve Chaque exécution écrit un répertoire d’artefacts stable : @@ -267,63 +278,77 @@ Chaque exécution écrit un répertoire d’artefacts stable : run.log ``` -`mantis-summary.json` doit être la source de vérité lisible par machine. Le rapport Markdown est destiné aux commentaires de PR et à la revue humaine. +`mantis-summary.json` doit être la source de vérité lisible par machine. Le +rapport Markdown est destiné aux commentaires de PR et à la revue humaine. Le résumé doit inclure : -- les refs et les SHA testés -- le transport et l’id du scénario +- les refs et SHA testés +- le transport et l’id de scénario - le fournisseur de machine et l’id de machine ou l’id de bail - la source des identifiants sans valeurs secrètes - le résultat de la baseline - le résultat du candidat - si le bug s’est reproduit sur la baseline - si le candidat l’a corrigé -- les chemins des artefacts -- les problèmes de configuration ou de nettoyage nettoyés +- les chemins d’artefacts +- les problèmes de configuration ou de nettoyage assainis -Les captures d’écran sont des preuves, pas des secrets. Elles exigent tout de même une discipline de caviardage : des noms de canaux privés, des noms d’utilisateurs ou le contenu de messages peuvent apparaître. Pour les PR publiques, préférez les liens d’artefacts GitHub Actions aux images intégrées tant que la stratégie de caviardage n’est pas plus solide. +Les captures d’écran sont des preuves, pas des secrets. Elles nécessitent quand même une discipline de +masquage : des noms de canaux privés, des noms d’utilisateurs ou le contenu de messages peuvent apparaître. Pour les PR publiques, +préférer les liens d’artefacts GitHub Actions aux images intégrées tant que la stratégie de masquage +n’est pas plus solide. ## Navigateur et VNC -La voie navigateur dispose de deux modes : +La voie navigateur a deux modes : -- **Automatisation headless** : par défaut pour la CI. Chrome s’exécute avec CDP activé, et Playwright ou le contrôle de navigateur OpenClaw capture les captures d’écran. -- **Secours VNC** : activé sur la même VM lorsque la connexion, le MFA, l’anti-automatisation Discord ou le débogage visuel nécessitent un humain. +- **Automatisation headless** : valeur par défaut pour CI. Chrome s’exécute avec CDP activé, et + Playwright ou le contrôle de navigateur OpenClaw capture les captures d’écran. +- **Secours VNC** : activé sur la même VM lorsque la connexion, la MFA, l’anti-automatisation Discord + ou le débogage visuel nécessite une intervention humaine. -Le profil de navigateur observateur Discord doit être suffisamment persistant pour éviter une connexion à chaque exécution, mais isolé de l’état du navigateur personnel. Un profil appartient au pool de machines Mantis, pas à un ordinateur portable de développeur. +Le profil de navigateur observateur Discord doit être assez persistant pour éviter +une connexion à chaque exécution, mais isolé de l’état du navigateur personnel. Un profil +appartient au pool de machines Mantis, pas à l’ordinateur portable d’un développeur. -Quand Mantis se bloque, il publie un message de statut Discord avec : +Quand Mantis se bloque, il publie un message d’état Discord avec : - l’id d’exécution -- l’id du scénario +- l’id de scénario - le fournisseur de machine - le répertoire d’artefacts - les instructions de connexion VNC ou noVNC si disponibles -- un court texte décrivant le blocage +- un court texte de blocage -Le premier déploiement privé peut publier ces messages dans le canal opérateur existant et migrer plus tard vers un canal Mantis dédié. +Le premier déploiement privé peut publier ces messages dans le canal opérateur +existant, puis migrer plus tard vers un canal Mantis dédié. ## Machines -Mantis doit privilégier AWS via Crabbox pour la première implémentation distante. Crabbox nous fournit des machines préchauffées, le suivi des baux, l’hydratation, les journaux, les résultats et le nettoyage. Si la capacité AWS est trop lente ou indisponible, ajoutez un fournisseur Hetzner derrière la même interface de machine. +Mantis doit privilégier AWS via Crabbox pour la première implémentation distante. +Crabbox nous donne des machines préchauffées, le suivi des baux, l’hydratation, les journaux, les résultats, et +le nettoyage. Si la capacité AWS est trop lente ou indisponible, ajouter un fournisseur Hetzner +derrière la même interface de machine. -Exigences minimales pour la VM : +Exigences minimales de VM : -- Linux avec une installation Chrome ou Chromium capable d’exécuter un bureau +- Linux avec une installation Chrome ou Chromium capable d’afficher un bureau - accès CDP pour l’automatisation du navigateur - VNC ou noVNC pour le secours - Node 22 et pnpm -- checkout OpenClaw et cache des dépendances -- cache du navigateur Chromium Playwright lorsque Playwright est utilisé -- suffisamment de CPU et de mémoire pour un Gateway OpenClaw, un navigateur et une exécution de modèle -- accès sortant vers Discord, GitHub, les fournisseurs de modèles et le courtier d’identifiants +- checkout OpenClaw et cache de dépendances +- cache du navigateur Playwright Chromium lorsque Playwright est utilisé +- assez de CPU et de mémoire pour un Gateway OpenClaw, un navigateur, et une exécution de modèle +- accès sortant à Discord, GitHub, aux fournisseurs de modèles, et au courtier d’identifiants -La VM ne doit pas conserver de secrets bruts de longue durée en dehors des magasins d’identifiants ou de profils de navigateur attendus. +La VM ne doit pas conserver de secrets bruts à longue durée de vie en dehors des magasins +d’identifiants ou de profils de navigateur attendus. ## Secrets -Les secrets résident dans les secrets d’organisation ou de dépôt GitHub pour les exécutions distantes, et dans un fichier de secrets local contrôlé par l’opérateur pour les exécutions locales. +Les secrets vivent dans les secrets d’organisation ou de dépôt GitHub pour les exécutions distantes, et dans +un fichier de secrets local contrôlé par l’opérateur pour les exécutions locales. Noms de secrets recommandés : @@ -339,26 +364,43 @@ Noms de secrets recommandés : - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR` - `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN` -À long terme, le pool d’identifiants Convex doit rester la source normale des identifiants de transport en direct. Les secrets GitHub initialisent le courtier et les voies de secours. Le workflow de réactions de statut Discord remappe les secrets Crabbox Mantis vers les variables d’environnement `CRABBOX_COORDINATOR` et `CRABBOX_COORDINATOR_TOKEN` attendues par la CLI Crabbox. Les noms de secrets GitHub `CRABBOX_*` simples restent acceptés comme solution de compatibilité. +À long terme, le pool d’identifiants Convex doit rester la source normale pour les +identifiants de transport en direct. Les secrets GitHub amorcent le courtier et les voies de secours. +Le workflow des réactions d’état Discord mappe les secrets Mantis Crabbox vers +les variables d’environnement `CRABBOX_COORDINATOR` et `CRABBOX_COORDINATOR_TOKEN` +attendues par la CLI Crabbox. Les noms de secrets GitHub simples `CRABBOX_*` restent +acceptés comme solution de compatibilité. -Le runner Mantis ne doit jamais afficher : +L’exécuteur Mantis ne doit jamais imprimer : -- les tokens de bot Discord -- les clés API de fournisseur +- les tokens de bots Discord +- les clés d’API de fournisseurs - les cookies de navigateur - le contenu des profils d’authentification - les mots de passe VNC -- les charges utiles d’identifiants bruts +- les charges utiles d’identifiants brutes -Les téléversements d’artefacts publics doivent aussi caviarder les métadonnées de cible Discord telles que les ids de bot, de serveur, de canal et de message. Le workflow de smoke GitHub active `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour cette raison. +Les téléversements d’artefacts publics doivent aussi masquer les métadonnées de cible Discord telles que les ids de bot, +de guilde, de canal, et de message. Le workflow de smoke GitHub active +`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour cette raison. -Si un token est accidentellement collé dans une issue, une PR, une discussion ou un journal, faites-le pivoter après avoir stocké le nouveau secret. +Si un token est collé accidentellement dans une issue, une PR, un chat, ou un journal, le faire tourner +après le stockage du nouveau secret. ## Artefacts GitHub et commentaires de PR -Les workflows Mantis doivent téléverser le bundle de preuves complet comme artefact Actions à durée de vie courte. Lorsque le workflow est exécuté pour un rapport de bug ou une PR de correctif, il doit aussi publier les captures d’écran PNG caviardées sur la branche `qa-artifacts` et mettre à jour ou créer un commentaire sur ce bug ou cette PR de correctif avec des captures d’écran avant/après intégrées. Ne publiez pas la preuve principale uniquement sur une PR générique d’automatisation QA. Les journaux bruts, les messages observés et les autres preuves volumineuses restent dans l’artefact Actions. +Les workflows Mantis doivent téléverser l’ensemble complet de preuves comme artefact Actions +à courte durée de vie. Lorsque le workflow est exécuté pour un rapport de bug ou une PR de correction, il doit aussi +publier les captures d’écran PNG masquées sur la branche `qa-artifacts` et mettre à jour ou créer un +commentaire sur ce bug ou cette PR de correction avec des captures d’écran avant/après intégrées. Ne pas publier +la preuve principale uniquement sur une PR générique d’automatisation QA. Les journaux bruts, messages observés, +et autres preuves volumineuses restent dans l’artefact Actions. -Les workflows de production doivent publier ces commentaires avec la GitHub App Mantis, pas avec `github-actions[bot]`. Stockez l’id d’application et la clé privée dans les secrets GitHub Actions `MANTIS_GITHUB_APP_ID` et `MANTIS_GITHUB_APP_PRIVATE_KEY`. Le workflow utilise un marqueur masqué comme clé de mise à jour, met à jour ce commentaire lorsque le token peut le modifier, et crée un nouveau commentaire appartenant à Mantis lorsqu’un ancien marqueur appartenant au bot ne peut pas être modifié. +Les workflows de production doivent publier ces commentaires avec la GitHub App Mantis, et non +avec `github-actions[bot]`. Stocker l’id d’app et la clé privée comme secrets GitHub Actions +`MANTIS_GITHUB_APP_ID` et `MANTIS_GITHUB_APP_PRIVATE_KEY`. Le workflow utilise un marqueur masqué comme clé de mise à jour, +met à jour ce commentaire lorsque le token peut le modifier, et crée un nouveau commentaire possédé par Mantis lorsque +un ancien marqueur possédé par un bot ne peut pas être modifié. Le commentaire de PR doit être court et visuel : @@ -380,60 +422,73 @@ candidate showed the expected queued -> thinking -> done sequence. | | | ``` -Lorsque l’exécution échoue parce que le harnais a échoué, le commentaire doit le dire au lieu de laisser entendre que le candidat a échoué. +Lorsque l’exécution échoue parce que le harnais a échoué, le commentaire doit le dire au lieu +de laisser entendre que le candidat a échoué. ## Notes de déploiement privé -Un déploiement privé peut déjà disposer d’une application Discord Mantis. Réutilisez cette application au lieu de créer une autre application lorsqu’elle dispose des bonnes autorisations de bot et peut être tournée en toute sécurité. +Un déploiement privé peut déjà avoir une application Discord Mantis. Réutiliser cette +application au lieu de créer une autre app lorsqu’elle dispose des bonnes +autorisations de bot et peut être tournée en sécurité. -Définissez le canal initial de notification opérateur via des secrets ou la configuration de déploiement. Il peut d’abord pointer vers un canal de maintenance ou d’opérations existant, puis migrer vers un canal Mantis dédié lorsqu’il existera. +Définir le canal initial de notification des opérateurs via des secrets ou la configuration de déploiement. +Il peut pointer d’abord vers un canal existant de mainteneurs ou d’opérations, +puis migrer vers un canal Mantis dédié une fois qu’il existe. -Ne mettez pas d’ids de serveur, d’ids de canal, de tokens de bot, de cookies de navigateur ni de mots de passe VNC dans ce document. Stockez-les dans les secrets GitHub, le courtier d’identifiants ou le magasin de secrets local de l’opérateur. +Ne pas mettre d’ids de guilde, d’ids de canal, de tokens de bot, de cookies de navigateur, ou de mots de passe VNC +dans ce document. Les stocker dans des secrets GitHub, le courtier d’identifiants, ou le +magasin de secrets local de l’opérateur. ## Ajouter un scénario Un scénario Mantis doit déclarer : -- un id et un titre -- le transport -- les identifiants requis -- la politique de ref de baseline -- la politique de ref de candidat -- le patch de configuration OpenClaw -- les étapes de configuration -- le stimulus -- l’oracle attendu pour la baseline -- l’oracle attendu pour le candidat -- les cibles de capture visuelle -- le budget de délai d’expiration -- les étapes de nettoyage +- id et titre +- transport +- identifiants requis +- politique de ref de baseline +- politique de ref de candidat +- correctif de configuration OpenClaw +- étapes de configuration +- stimulus +- oracle de baseline attendu +- oracle de candidat attendu +- cibles de capture visuelle +- budget de délai d’expiration +- étapes de nettoyage Les scénarios doivent privilégier de petits oracles typés : -- l’état des réactions Discord pour les bugs de réaction -- les références de messages Discord pour les bugs de fil de discussion -- le ts de fil Slack et l’état de l’API de réactions pour les bugs Slack -- les ids et en-têtes de messages e-mail pour les bugs e-mail -- les captures d’écran du navigateur lorsque l’UI est le seul observable fiable +- état des réactions Discord pour les bugs de réactions +- références de messages Discord pour les bugs de fils +- ts de fil Slack et état de l’API de réactions pour les bugs Slack +- ids et en-têtes de messages e-mail pour les bugs d’e-mail +- captures d’écran de navigateur lorsque l’UI est le seul observable fiable -Les vérifications par vision doivent être additives. Si une API de plateforme peut prouver le bug, utilisez l’API comme oracle de réussite/échec et gardez les captures d’écran pour renforcer la confiance humaine. +Les vérifications par vision doivent être additives. Si une API de plateforme peut prouver le bug, utiliser +l’API comme oracle de réussite/échec et conserver les captures d’écran pour renforcer la confiance humaine. ## Extension des fournisseurs -Après Discord, le même runner peut ajouter : +Après Discord, le même exécuteur peut ajouter : -- Slack : réactions, fils, mentions d’application, modales, téléversements de fichiers. -- E-mail : authentification Gmail et threading de messages avec `gog` lorsque les connecteurs ne suffisent pas. -- WhatsApp : connexion par QR code, réidentification, livraison de messages, médias, réactions. -- Telegram : contrôle des mentions de groupe, commandes, réactions lorsque disponibles. +- Slack : réactions, fils, mentions d’app, modales, téléversements de fichiers. +- E-mail : authentification Gmail et fils de messages avec `gog` lorsque les connecteurs ne sont pas + suffisants. +- WhatsApp : connexion QR, ré-identification, livraison de messages, médias, réactions. +- Telegram : filtrage des mentions de groupe, commandes, réactions lorsque disponibles. - Matrix : salons chiffrés, relations de fil ou de réponse, reprise après redémarrage. -Chaque transport doit avoir un scénario smoke peu coûteux et un ou plusieurs scénarios par classe de bugs. Les scénarios visuels coûteux doivent rester opt-in. +Chaque transport doit avoir un scénario de smoke peu coûteux et un ou plusieurs scénarios par classe de bug. +Les scénarios visuels coûteux doivent rester opt-in. ## Questions ouvertes -- Quel bot Discord doit être le pilote, et lequel doit être le SUT, lorsque le bot Mantis existant est réutilisé ? -- La connexion du navigateur observateur doit-elle utiliser un compte Discord humain, un compte de test ou seulement des preuves REST lisibles par bot pour la première phase ? +- Quel bot Discord doit être le pilote, et lequel doit être le SUT, lorsque le + bot Mantis existant est réutilisé ? +- La connexion du navigateur observateur doit-elle utiliser un compte Discord humain, un compte de test, + ou uniquement des preuves REST lisibles par bot pour la première phase ? - Combien de temps GitHub doit-il conserver les artefacts Mantis pour les PR ? -- Quand ClawSweeper doit-il recommander automatiquement Mantis au lieu d’attendre une commande d’un mainteneur ? -- Les captures d’écran doivent-elles être caviardées ou recadrées avant le téléversement pour les PR publiques ? +- Quand ClawSweeper doit-il recommander automatiquement Mantis au lieu d’attendre une + commande de mainteneur ? +- Les captures d’écran doivent-elles être masquées ou recadrées avant téléversement pour les PR publiques ? diff --git a/docs/fr/concepts/qa-e2e-automation.md b/docs/fr/concepts/qa-e2e-automation.md index daebcee89..5a7d2e2c1 100644 --- a/docs/fr/concepts/qa-e2e-automation.md +++ b/docs/fr/concepts/qa-e2e-automation.md @@ -1,80 +1,81 @@ --- read_when: - Comprendre comment la pile d’assurance qualité s’articule - - Étendre qa-lab, qa-channel ou un adaptateur de transport - - Ajout de scénarios de QA adossés au dépôt + - Extension de qa-lab, qa-channel ou d’un adaptateur de transport + - Ajout de scénarios QA adossés au dépôt - Créer une automatisation d’assurance qualité plus réaliste autour du tableau de bord Gateway summary: 'Vue d’ensemble de la pile QA : qa-lab, qa-channel, scénarios adossés au dépôt, voies de transport en direct, adaptateurs de transport et rapports.' -title: Vue d’ensemble de l’assurance qualité +title: Aperçu de l’assurance qualité x-i18n: - generated_at: "2026-05-05T01:45:26Z" + generated_at: "2026-05-05T06:17:12Z" model: gpt-5.5 provider: openai - source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96 + source_hash: d313abf9e0f13a159ce28c023e2a1c4c1518529da1354a130e9f495e65faac19 source_path: concepts/qa-e2e-automation.md workflow: 16 --- -La pile QA privée vise à exercer OpenClaw d’une façon plus réaliste, -proche d’un canal, qu’un seul test unitaire ne peut le faire. +La pile QA privée vise à exercer OpenClaw d’une manière plus réaliste, +façonnée par les canaux, que ne le permet un simple test unitaire. -Éléments actuels : +Composants actuels : -- `extensions/qa-channel` : canal de messages synthétique avec surfaces de DM, - canal, fil, réaction, modification et suppression. -- `extensions/qa-lab` : UI de débogage et bus QA pour observer la transcription, +- `extensions/qa-channel` : canal de messages synthétique avec surfaces de DM, canal, fil, + réaction, modification et suppression. +- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription, injecter des messages entrants et exporter un rapport Markdown. -- `extensions/qa-matrix`, futurs plugins d’exécution : adaptateurs de transport réel qui - pilotent un vrai canal dans un Gateway QA enfant. -- `qa/` : ressources d’amorçage appuyées par le dépôt pour la tâche de lancement et les - scénarios QA de référence. -- [Mantis](/fr/concepts/mantis) : vérification réelle avant et après pour les bogues qui - nécessitent de vrais transports, des captures d’écran de navigateur, l’état de VM et des preuves de PR. +- `extensions/qa-matrix`, futurs plugins de runner : adaptateurs de transports en direct qui + pilotent un vrai canal à l’intérieur d’un Gateway QA enfant. +- `qa/` : ressources d’amorçage adossées au dépôt pour la tâche de démarrage et les scénarios QA + de référence. +- [Mantis](/fr/concepts/mantis) : vérification en direct avant et après pour les bogues qui + nécessitent de vrais transports, des captures d’écran de navigateur, l’état d’une VM et des preuves de PR. ## Surface de commande -Chaque flux QA s’exécute sous `pnpm openclaw qa `. Beaucoup ont des alias de scripts `pnpm qa:*` ; les deux formes sont prises en charge. +Chaque flux QA s’exécute sous `pnpm openclaw qa `. Beaucoup ont des alias de script `pnpm qa:*` ; +les deux formes sont prises en charge. | Commande | Objectif | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `qa run` | Auto-vérification QA groupée ; écrit un rapport Markdown. | -| `qa suite` | Exécuter les scénarios appuyés par le dépôt contre la voie du Gateway QA. Alias : `pnpm openclaw qa suite --runner multipass` pour une VM Linux jetable. | -| `qa coverage` | Afficher l’inventaire markdown de couverture des scénarios (`--json` pour une sortie machine). | -| `qa parity-report` | Comparer deux fichiers `qa-suite-summary.json` et écrire le rapport de parité agentique. | -| `qa character-eval` | Exécuter le scénario QA de personnage sur plusieurs modèles réels avec un rapport évalué. Voir [Rapports](#reporting). | -| `qa manual` | Exécuter un prompt ponctuel contre la voie du fournisseur/modèle sélectionné. | -| `qa ui` | Démarrer l’UI de débogage QA et le bus QA local (alias : `pnpm qa:lab:ui`). | -| `qa docker-build-image` | Construire l’image Docker QA préintégrée. | -| `qa docker-scaffold` | Écrire un échafaudage docker-compose pour le tableau de bord QA + la voie Gateway. | -| `qa up` | Construire le site QA, démarrer la pile appuyée par Docker, afficher l’URL (alias : `pnpm qa:lab:up` ; la variante `:fast` ajoute `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | -| `qa aimock` | Démarrer uniquement le serveur de fournisseur AIMock. | -| `qa mock-openai` | Démarrer uniquement le serveur de fournisseur `mock-openai` conscient des scénarios. | -| `qa credentials doctor` / `add` / `list` / `remove` | Gérer le pool partagé d’identifiants Convex. | -| `qa matrix` | Voie de transport réel contre un homeserver Tuwunel jetable. Voir [Matrix QA](/fr/concepts/qa-matrix). | -| `qa telegram` | Voie de transport réel contre un vrai groupe privé Telegram. | -| `qa discord` | Voie de transport réel contre un vrai canal de guilde privé Discord. | -| `qa slack` | Voie de transport réel contre un vrai canal privé Slack. | -| `qa mantis` | Exécuteur de vérification avant et après pour les bogues de transport réel, avec preuves de réactions de statut Discord, smoke desktop/navigateur Crabbox et smoke Slack dans VNC. Voir [Mantis](/fr/concepts/mantis). | +| `qa run` | Auto-vérification QA intégrée ; écrit un rapport Markdown. | +| `qa suite` | Exécute les scénarios adossés au dépôt contre la voie Gateway QA. Alias : `pnpm openclaw qa suite --runner multipass` pour une VM Linux jetable. | +| `qa coverage` | Affiche l’inventaire Markdown de couverture des scénarios (`--json` pour une sortie machine). | +| `qa parity-report` | Compare deux fichiers `qa-suite-summary.json` et écrit le rapport de parité agentique. | +| `qa character-eval` | Exécute le scénario QA de personnage sur plusieurs modèles en direct avec un rapport jugé. Voir [Rapports](#reporting). | +| `qa manual` | Exécute une invite ponctuelle contre la voie fournisseur/modèle sélectionnée. | +| `qa ui` | Démarre l’interface de débogage QA et le bus QA local (alias : `pnpm qa:lab:ui`). | +| `qa docker-build-image` | Construit l’image Docker QA préassemblée. | +| `qa docker-scaffold` | Écrit un échafaudage docker-compose pour le tableau de bord QA + la voie Gateway. | +| `qa up` | Construit le site QA, démarre la pile adossée à Docker, affiche l’URL (alias : `pnpm qa:lab:up` ; la variante `:fast` ajoute `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). | +| `qa aimock` | Démarre uniquement le serveur fournisseur AIMock. | +| `qa mock-openai` | Démarre uniquement le serveur fournisseur `mock-openai` conscient des scénarios. | +| `qa credentials doctor` / `add` / `list` / `remove` | Gère le pool d’identifiants Convex partagé. | +| `qa matrix` | Voie de transport en direct contre un homeserver Tuwunel jetable. Voir [QA Matrix](/fr/concepts/qa-matrix). | +| `qa telegram` | Voie de transport en direct contre un vrai groupe Telegram privé. | +| `qa discord` | Voie de transport en direct contre un vrai canal de guilde Discord privé. | +| `qa slack` | Voie de transport en direct contre un vrai canal Slack privé. | +| `qa mantis` | Runner de vérification avant et après pour les bogues de transport en direct, avec preuves de réactions de statut Discord, smoke desktop/navigateur Crabbox et smoke Slack-dans-VNC. Voir [Mantis](/fr/concepts/mantis). | ## Flux opérateur Le flux opérateur QA actuel est un site QA à deux volets : - Gauche : tableau de bord Gateway (Control UI) avec l’agent. -- Droite : QA Lab, affichant la transcription de style Slack et le plan de scénario. +- Droite : QA Lab, affichant la transcription de type Slack et le plan de scénario. -Exécutez-le avec : +Lancez-le avec : ```bash pnpm qa:lab:up ``` -Cela construit le site QA, démarre la voie Gateway appuyée par Docker et expose la +Cela construit le site QA, démarre la voie Gateway adossée à Docker et expose la page QA Lab où un opérateur ou une boucle d’automatisation peut donner à l’agent une mission -QA, observer le comportement réel du canal et consigner ce qui a fonctionné, échoué ou +QA, observer le comportement réel du canal et enregistrer ce qui a fonctionné, échoué ou est resté bloqué. -Pour itérer plus vite sur l’UI QA Lab locale sans reconstruire l’image Docker à chaque fois, +Pour une itération plus rapide sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois, démarrez la pile avec un bundle QA Lab monté par liaison : ```bash @@ -86,8 +87,7 @@ pnpm qa:lab:watch `qa:lab:up:fast` garde les services Docker sur une image préconstruite et monte par liaison `extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch` -reconstruit ce bundle à chaque changement, et le navigateur se recharge automatiquement lorsque le hachage des ressources QA Lab -change. +reconstruit ce bundle à chaque modification, et le navigateur se recharge automatiquement quand le hachage des ressources QA Lab change. Pour un smoke local de trace OpenTelemetry, exécutez : @@ -97,16 +97,16 @@ pnpm qa:otel:smoke Ce script démarre un récepteur local de traces OTLP/HTTP, exécute le scénario QA `otel-trace-smoke` avec le plugin `diagnostics-otel` activé, puis -décode les spans protobuf exportés et vérifie la forme critique pour la release : +décode les spans protobuf exportés et vérifie la forme critique pour la publication : `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled` et `openclaw.message.delivery` doivent être présents ; -les appels de modèle ne doivent pas exporter `StreamAbandoned` lors des tours réussis ; les ID de diagnostic bruts et les -attributs `openclaw.content.*` doivent rester hors de la trace. Il écrit +les appels de modèle ne doivent pas exporter `StreamAbandoned` sur les tours réussis ; les ID de diagnostic bruts et les +attributs `openclaw.content.*` doivent rester absents de la trace. Il écrit `otel-smoke-summary.json` à côté des artefacts de la suite QA. -La QA d’observabilité reste réservée aux checkouts source. La tarball npm omet intentionnellement -QA Lab, donc les voies de release Docker de package n’exécutent pas les commandes `qa`. Utilisez -`pnpm qa:otel:smoke` depuis un checkout source construit lors des changements de l’instrumentation +La QA d’observabilité reste réservée aux extractions de source. Le tarball npm omet intentionnellement +QA Lab, donc les voies de publication Docker de package n’exécutent pas les commandes `qa`. Utilisez +`pnpm qa:otel:smoke` depuis une extraction de source construite lorsque vous modifiez l’instrumentation de diagnostic. Pour une voie smoke Matrix avec transport réel, exécutez : @@ -115,9 +115,9 @@ Pour une voie smoke Matrix avec transport réel, exécutez : pnpm openclaw qa matrix --profile fast --fail-fast ``` -La référence CLI complète, le catalogue des profils/scénarios, les variables d’environnement et la disposition des artefacts pour cette voie se trouvent dans [Matrix QA](/fr/concepts/qa-matrix). En bref : elle provisionne un homeserver Tuwunel jetable dans Docker, enregistre des utilisateurs temporaires driver/SUT/observer, exécute le vrai plugin Matrix dans un Gateway QA enfant limité à ce transport (pas de `qa-channel`), puis écrit un rapport Markdown, un résumé JSON, un artefact d’événements observés et un journal de sortie combiné sous `.artifacts/qa-e2e/matrix-/`. +La référence CLI complète, le catalogue des profils/scénarios, les variables d’environnement et l’organisation des artefacts pour cette voie se trouvent dans [QA Matrix](/fr/concepts/qa-matrix). En bref : elle provisionne un homeserver Tuwunel jetable dans Docker, enregistre des utilisateurs temporaires driver/SUT/observer, exécute le vrai plugin Matrix dans un Gateway QA enfant limité à ce transport (pas de `qa-channel`), puis écrit un rapport Markdown, un résumé JSON, un artefact d’événements observés et un journal de sortie combiné sous `.artifacts/qa-e2e/matrix-/`. -Pour les voies smoke à transport réel Telegram, Discord et Slack : +Pour les voies smoke Telegram, Discord et Slack avec transport réel : ```bash pnpm openclaw qa telegram @@ -136,78 +136,105 @@ pnpm openclaw qa mantis slack-desktop-smoke \ --keep-lease ``` -Cette commande loue une machine desktop/navigateur Crabbox, exécute la voie live Slack +Cette commande loue une machine desktop/navigateur Crabbox, exécute la voie Slack en direct dans la VM, ouvre Slack Web dans le navigateur VNC, capture le bureau et -copie `slack-qa/` ainsi que `slack-desktop-smoke.png` dans le répertoire d’artefacts Mantis. -Réutilisez `--lease-id ` après vous être connecté manuellement à Slack Web +copie `slack-qa/`, `slack-desktop-smoke.png` et `slack-desktop-smoke.mp4` +lorsque la capture vidéo est disponible, vers le répertoire d’artefacts Mantis. Réutilisez `--lease-id ` après vous être connecté manuellement à Slack Web via VNC. Avec `--gateway-setup`, Mantis laisse un Gateway Slack OpenClaw persistant -en cours d’exécution dans la VM sur le port `38973` ; sans cela, la commande exécute la -voie QA Slack bot-à-bot normale et quitte après la capture des artefacts. +en cours d’exécution dans la VM sur le port `38973` ; sans cette option, la commande exécute la +voie QA Slack bot-à-bot normale et se termine après la capture des artefacts. -Avant d’utiliser des identifiants réels mutualisés, exécutez : +Pour une tâche desktop de style agent/CV, exécutez : + +```bash +pnpm openclaw qa mantis visual-task \ + --browser-url https://example.net \ + --expect-text "Example Domain" \ + --vision-model openai/gpt-5.4 +``` + +`visual-task` loue ou réutilise une machine desktop/navigateur Crabbox, démarre +`crabbox record --while`, pilote le navigateur visible via un +`visual-driver` imbriqué, capture `visual-task.png`, exécute `openclaw infer image describe` +sur la capture d’écran lorsque `--vision-mode image-describe` est sélectionné, et +écrit `visual-task.mp4`, `mantis-visual-task-summary.json`, +`mantis-visual-task-driver-result.json` et `mantis-visual-task-report.md`. +Lorsque `--expect-text` est défini, l’invite de vision demande un verdict JSON structuré +et ne réussit que lorsque le modèle signale une preuve visible positive ; une +réponse négative qui se contente de citer le texte cible échoue à l’assertion. +Utilisez `--vision-mode metadata` pour un smoke sans modèle qui prouve la plomberie +du bureau, du navigateur, de la capture d’écran et de la vidéo sans appeler de fournisseur de compréhension d’image. L’enregistrement est un artefact obligatoire pour `visual-task` ; si Crabbox n’enregistre +aucun `visual-task.mp4` non vide, la tâche échoue même si le driver visuel +a réussi. En cas d’échec, Mantis conserve la location pour VNC sauf si la tâche avait déjà +réussi et que `--keep-lease` n’était pas défini. + +Avant d’utiliser des identifiants en direct mis en pool, exécutez : ```bash pnpm openclaw qa credentials doctor ``` -Le doctor vérifie l’environnement du courtier Convex, valide les paramètres d’endpoint et vérifie l’accessibilité admin/list lorsque le secret mainteneur est présent. Il ne signale que l’état défini/manquant des secrets. +Le doctor vérifie l’environnement du broker Convex, valide les paramètres de point de terminaison et vérifie l’accessibilité admin/list lorsque le secret mainteneur est présent. Il ne signale que l’état défini/manquant des secrets. -## Couverture des transports réels +## Couverture des transports en direct -Les voies de transport réel partagent un contrat unique au lieu que chacune invente sa propre forme de liste de scénarios. `qa-channel` est la suite synthétique large de comportements produit et ne fait pas partie de la matrice de couverture des transports réels. +Les voies de transport en direct partagent un contrat unique au lieu d’inventer chacune leur propre forme de liste de scénarios. `qa-channel` est la vaste suite synthétique de comportement produit et ne fait pas partie de la matrice de couverture des transports en direct. -| Voie | Canary | Contrôle des mentions | Bot-à-bot | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation de fil | Observation des réactions | Commande d’aide | Enregistrement de commande native | -| -------- | ------ | --------------------- | ---------- | -------------------------------- | ------------------------- | ------------------------- | ------------ | ---------------- | ------------------------- | --------------- | --------------------------------- | -| Matrix | x | x | x | x | x | x | x | x | x | | | -| Telegram | x | x | x | | | | | | | x | | -| Discord | x | x | x | | | | | | | | x | -| Slack | x | x | x | | | | | | | | | +| Voie | Canari | Filtrage par mention | Bot à bot | Blocage par liste d’autorisation | Réponse de niveau supérieur | Reprise après redémarrage | Suivi de fil | Isolation du fil | Observation des réactions | Commande d’aide | Enregistrement de commande native | +| -------- | ------ | -------------------- | --------- | -------------------------------- | --------------------------- | ------------------------- | ------------ | ---------------- | -------------------------- | --------------- | ---------------------------------- | +| Matrix | x | x | x | x | x | x | x | x | x | | | +| Telegram | x | x | x | | | | | | | x | | +| Discord | x | x | x | | | | | | | | x | +| Slack | x | x | x | | | | | | | | | -Cela garde `qa-channel` comme suite large de comportements produit, tandis que Matrix, -Telegram et les futurs transports réels partagent une checklist explicite de contrat de transport. +Cela conserve `qa-channel` comme suite large de comportement produit, tandis que Matrix, +Telegram et les futurs transports live partagent une même liste de contrôle +explicite de contrat de transport. -Pour une voie de VM Linux jetable sans faire entrer Docker dans le chemin QA, exécutez : +Pour une voie de VM Linux jetable sans introduire Docker dans le chemin QA, exécutez : ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Cela démarre un nouvel invité Multipass, installe les dépendances, compile OpenClaw -dans l’invité, exécute `qa suite`, puis recopie le rapport QA normal et le +Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw +dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le résumé dans `.artifacts/qa-e2e/...` sur l’hôte. Il réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte. -Les exécutions de suite sur l’hôte et avec Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle -avec des workers Gateway isolés. `qa-channel` utilise par défaut une concurrence -de 4, limitée au nombre de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster -le nombre de workers, ou `--concurrency 1` pour une exécution série. -La commande se termine avec un code non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque -vous voulez obtenir les artefacts sans code de sortie en échec. -Les exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour -l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA, et -`CODEX_HOME` lorsqu’il est présent. Gardez `--output-dir` sous la racine du dépôt afin que l’invité -puisse réécrire via l’espace de travail monté. +Les exécutions de suite sur l’hôte et Multipass exécutent par défaut plusieurs +scénarios sélectionnés en parallèle avec des workers Gateway isolés. `qa-channel` +utilise par défaut une concurrence de 4, plafonnée par le nombre de scénarios +sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, +ou `--concurrency 1` pour une exécution en série. +La commande se termine avec un code non nul lorsqu’un scénario échoue. Utilisez +`--allow-failures` lorsque vous voulez des artefacts sans code de sortie d’échec. +Les exécutions live transmettent les entrées d’authentification QA prises en charge +qui sont pratiques pour l’invité : clés de fournisseur basées sur l’environnement, +chemin de configuration du fournisseur live QA et `CODEX_HOME` lorsqu’il est présent. +Gardez `--output-dir` sous la racine du dépôt afin que l’invité puisse réécrire +via l’espace de travail monté. -## Référence QA pour Telegram, Discord et Slack +## Référence QA Telegram, Discord et Slack -Matrix dispose d’une [page dédiée](/fr/concepts/qa-matrix) en raison de son nombre de scénarios et du provisionnement de homeserver adossé à Docker. Telegram, Discord et Slack sont plus petits — une poignée de scénarios chacun, sans système de profils, contre des canaux réels préexistants — leur référence se trouve donc ici. +Matrix dispose d’une [page dédiée](/fr/concepts/qa-matrix) en raison de son nombre de scénarios et de son provisionnement de serveur domestique basé sur Docker. Telegram, Discord et Slack sont plus petits — quelques scénarios chacun, aucun système de profil, contre des canaux réels préexistants — leur référence se trouve donc ici. -### Options CLI partagées +### Indicateurs CLI partagés -Ces voies s’enregistrent via `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` et acceptent les mêmes options : +Ces voies s’enregistrent via `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` et acceptent les mêmes indicateurs : -| Option | Par défaut | Description | -| ------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `--scenario ` | — | Exécute uniquement ce scénario. Répétable. | -| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Emplacement où les rapports, le résumé, les messages observés et le journal de sortie sont écrits. Les chemins relatifs sont résolus par rapport à `--repo-root`. | -| `--repo-root ` | `process.cwd()` | Racine du dépôt lors d’un appel depuis un cwd neutre. | -| `--sut-account ` | `sut` | Id de compte temporaire dans la configuration du Gateway QA. | -| `--provider-mode ` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` hérité fonctionne toujours). | -| `--model ` / `--alt-model ` | valeur par défaut du fournisseur | Références du modèle principal/secondaire. | -| `--fast` | désactivé | Mode rapide du fournisseur lorsqu’il est pris en charge. | -| `--credential-source ` | `env` | Voir [Pool d’identifiants Convex](#convex-credential-pool). | -| `--credential-role ` | `ci` en CI, `maintainer` sinon | Rôle utilisé lorsque `--credential-source convex`. | +| Indicateur | Par défaut | Description | +| ------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `--scenario ` | — | Exécuter uniquement ce scénario. Répétable. | +| `--output-dir ` | `/.artifacts/qa-e2e/{telegram,discord,slack}-` | Emplacement où les rapports, résumés, messages observés et le journal de sortie sont écrits. Les chemins relatifs sont résolus par rapport à `--repo-root`. | +| `--repo-root ` | `process.cwd()` | Racine du dépôt lors de l’appel depuis un cwd neutre. | +| `--sut-account ` | `sut` | Identifiant de compte temporaire dans la configuration Gateway QA. | +| `--provider-mode ` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` hérité fonctionne toujours). | +| `--model ` / `--alt-model ` | valeur par défaut du fournisseur | Références du modèle principal/alternatif. | +| `--fast` | désactivé | Mode rapide du fournisseur lorsqu’il est pris en charge. | +| `--credential-source ` | `env` | Voir [pool d’identifiants Convex](#convex-credential-pool). | +| `--credential-role ` | `ci` dans CI, `maintainer` sinon | Rôle utilisé lorsque `--credential-source convex`. | -Chaque voie se termine avec un code non nul en cas d’échec d’un scénario. `--allow-failures` écrit les artefacts sans définir de code de sortie en échec. +Chaque voie se termine avec un code non nul si un scénario échoue. `--allow-failures` écrit les artefacts sans définir de code de sortie d’échec. ### QA Telegram @@ -215,17 +242,17 @@ Chaque voie se termine avec un code non nul en cas d’échec d’un scénario. pnpm openclaw qa telegram ``` -Cible un groupe Telegram privé réel avec deux bots distincts (driver + SUT). Le bot SUT doit avoir un nom d’utilisateur Telegram ; l’observation bot-à-bot fonctionne mieux lorsque les deux bots ont activé le **Bot-to-Bot Communication Mode** dans `@BotFather`. +Cible un groupe Telegram privé réel avec deux bots distincts (pilote + SUT). Le bot SUT doit avoir un nom d’utilisateur Telegram ; l’observation bot à bot fonctionne mieux lorsque les deux bots ont le **Bot-to-Bot Communication Mode** activé dans `@BotFather`. Environnement requis lorsque `--credential-source env` : -- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id de discussion numérique (chaîne). +- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — identifiant numérique du chat (chaîne). - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN` Facultatif : -- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` conserve les corps des messages dans les artefacts de messages observés (masqués par défaut). +- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés (masqué par défaut). Scénarios (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`) : @@ -237,11 +264,13 @@ Scénarios (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtim - `telegram-tools-compact-command` - `telegram-whoami-command` - `telegram-context-command` +- `telegram-long-final-reuses-preview` +- `telegram-long-final-three-chunks` Artefacts de sortie : - `telegram-qa-report.md` -- `telegram-qa-summary.json` — inclut le RTT par réponse (envoi du driver → réponse SUT observée) à partir du canary. +- `telegram-qa-summary.json` — inclut le RTT par réponse (envoi du pilote → réponse SUT observée) à partir du canari. - `telegram-qa-observed-messages.json` — corps masqués sauf si `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`. ### QA Discord @@ -250,7 +279,7 @@ Artefacts de sortie : pnpm openclaw qa discord ``` -Cible un canal de guilde Discord privé réel avec deux bots : un bot driver contrôlé par le harness et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Discord groupé. Vérifie la gestion des mentions de canal, que le bot SUT a enregistré la commande native `/help` auprès de Discord, ainsi que les scénarios de preuves Mantis opt-in. +Cible un canal de guilde Discord privé réel avec deux bots : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Discord groupé. Vérifie la gestion des mentions de canal, que le bot SUT a enregistré la commande native `/help` auprès de Discord, et les scénarios de preuves Mantis avec consentement explicite. Environnement requis lorsque `--credential-source env` : @@ -258,18 +287,18 @@ Environnement requis lorsque `--credential-source env` : - `OPENCLAW_QA_DISCORD_CHANNEL_ID` - `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN` - `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN` -- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — doit correspondre à l’id utilisateur du bot SUT renvoyé par Discord (sinon la voie échoue rapidement). +- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — doit correspondre à l’identifiant utilisateur du bot SUT renvoyé par Discord (sinon la voie échoue rapidement). Facultatif : -- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` conserve les corps des messages dans les artefacts de messages observés. +- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés. Scénarios (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`) : - `discord-canary` - `discord-mention-gating` - `discord-native-help-command-registration` -- `discord-status-reactions-tool-only` — scénario Mantis opt-in. S’exécute seul, car il fait passer le SUT en mode toujours actif, réponses de guilde uniquement par outil avec `messages.statusReactions.enabled=true`, puis capture une chronologie de réactions REST ainsi qu’un artefact visuel HTML/PNG. +- `discord-status-reactions-tool-only` — scénario Mantis avec consentement explicite. S’exécute seul, car il bascule le SUT vers des réponses de guilde toujours actives et uniquement via outils avec `messages.statusReactions.enabled=true`, puis capture une chronologie de réactions REST ainsi que des artefacts visuels HTML/PNG. Les rapports Mantis avant/après préservent également les artefacts MP4 fournis par le scénario sous forme de `baseline.mp4` et `candidate.mp4`. Exécutez explicitement le scénario de réactions de statut Mantis : @@ -295,7 +324,7 @@ Artefacts de sortie : pnpm openclaw qa slack ``` -Cible un canal Slack privé réel avec deux bots distincts : un bot driver contrôlé par le harness et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Slack groupé. +Cible un canal Slack privé réel avec deux bots distincts : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Slack groupé. Environnement requis lorsque `--credential-source env` : @@ -306,7 +335,7 @@ Environnement requis lorsque `--credential-source env` : Facultatif : -- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` conserve les corps des messages dans les artefacts de messages observés. +- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés. Scénarios (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`) : @@ -319,18 +348,18 @@ Artefacts de sortie : - `slack-qa-summary.json` - `slack-qa-observed-messages.json` — corps masqués sauf si `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`. -#### Configurer l’espace de travail Slack +#### Configuration de l’espace de travail Slack La voie nécessite deux applications Slack distinctes dans un même espace de travail, ainsi qu’un canal dont les deux bots sont membres : -- `channelId` — l’id `Cxxxxxxxxxx` d’un canal auquel les deux bots ont été invités. Utilisez un canal dédié ; la voie publie à chaque exécution. +- `channelId` — l’identifiant `Cxxxxxxxxxx` d’un canal auquel les deux bots ont été invités. Utilisez un canal dédié ; la voie publie à chaque exécution. - `driverBotToken` — jeton de bot (`xoxb-...`) de l’application **Driver**. -- `sutBotToken` — jeton de bot (`xoxb-...`) de l’application **SUT**, qui doit être une application Slack séparée du driver afin que son id utilisateur de bot soit distinct. -- `sutAppToken` — jeton de niveau application (`xapp-...`) de l’application SUT avec `connections:write`, utilisé par Socket Mode afin que l’application SUT puisse recevoir des événements. +- `sutBotToken` — jeton de bot (`xoxb-...`) de l’application **SUT**, qui doit être une application Slack séparée du pilote afin que son identifiant utilisateur de bot soit distinct. +- `sutAppToken` — jeton de niveau application (`xapp-...`) de l’application SUT avec `connections:write`, utilisé par Socket Mode afin que l’application SUT puisse recevoir les événements. -Préférez un espace de travail Slack dédié à la QA plutôt que de réutiliser un espace de travail de production. +Préférez un espace de travail Slack dédié à la QA plutôt que la réutilisation d’un espace de travail de production. -Le manifeste SUT ci-dessous reflète l’installation de production du Plugin Slack groupé (`extensions/slack/src/setup-shared.ts:10`). Pour la configuration du canal de production telle que les utilisateurs la voient, consultez [Configuration rapide du canal Slack](/fr/channels/slack#quick-setup) ; la paire Driver/SUT QA est volontairement séparée, car la voie a besoin de deux ids utilisateur de bot distincts dans un même espace de travail. +Le manifeste SUT ci-dessous reflète l’installation de production du Plugin Slack groupé (`extensions/slack/src/setup-shared.ts:10`). Pour la configuration du canal de production telle que les utilisateurs la voient, consultez [configuration rapide du canal Slack](/fr/channels/slack#quick-setup) ; la paire QA Driver/SUT est intentionnellement séparée, car la voie nécessite deux identifiants utilisateur de bot distincts dans un même espace de travail. **1. Créer l’application Driver** @@ -359,11 +388,11 @@ Accédez à [api.slack.com/apps](https://api.slack.com/apps) → _Create New App } ``` -Copiez le _Bot User OAuth Token_ (`xoxb-...`) — il devient `driverBotToken`. Le driver a seulement besoin de publier des messages et de s’identifier ; pas d’événements, pas de Socket Mode. +Copiez le _Bot User OAuth Token_ (`xoxb-...`) — il devient `driverBotToken`. Le pilote a seulement besoin de publier des messages et de s’identifier ; aucun événement, aucun Socket Mode. **2. Créer l’application SUT** -Répétez _Create New App → From a manifest_ dans le même espace de travail. L’ensemble de portées reflète l’installation de production du Plugin Slack groupé (`extensions/slack/src/setup-shared.ts:10`) : +Répétez _Create New App → From a manifest_ dans le même espace de travail. L’ensemble des portées reflète l’installation de production du Plugin Slack groupé (`extensions/slack/src/setup-shared.ts:10`) : ```json { @@ -434,12 +463,12 @@ Répétez _Create New App → From a manifest_ dans le même espace de travail. } ``` -Après que Slack a créé l’application, effectuez deux actions sur sa page de paramètres : +Une fois que Slack a créé l’app, effectuez deux actions sur sa page de paramètres : - _Install to Workspace_ → copiez le _Bot User OAuth Token_ → il devient `sutBotToken`. -- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → ajoutez la portée `connections:write` → enregistrez → copiez la valeur `xapp-...` → elle devient `sutAppToken`. +- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → ajoutez le scope `connections:write` → enregistrez → copiez la valeur `xapp-...` → elle devient `sutAppToken`. -Vérifiez que les deux bots ont des identifiants utilisateur distincts en appelant `auth.test` sur chaque jeton. Le runtime distingue le pilote et le SUT par identifiant utilisateur ; réutiliser une seule application pour les deux fera échouer immédiatement le filtrage des mentions. +Vérifiez que les deux bots ont des identifiants utilisateur distincts en appelant `auth.test` sur chaque token. Le runtime distingue le pilote et le SUT par identifiant utilisateur ; réutiliser une seule app pour les deux fera échouer immédiatement le filtrage des mentions. **3. Créer le canal** @@ -450,11 +479,11 @@ Dans l’espace de travail QA, créez un canal (par exemple `#openclaw-qa`) et i /invite @OpenClaw QA SUT ``` -Copiez l’identifiant `Cxxxxxxxxxx` depuis _infos du canal → À propos → ID du canal_ — il devient `channelId`. Un canal public fonctionne ; si vous utilisez un canal privé, les deux applications disposent déjà de `groups:history`, donc les lectures d’historique du harnais réussiront quand même. +Copiez l’identifiant `Cxxxxxxxxxx` depuis _channel info → About → Channel ID_ : il devient `channelId`. Un canal public fonctionne ; si vous utilisez un canal privé, les deux apps disposent déjà de `groups:history`, donc les lectures d’historique du harnais réussiront tout de même. **4. Enregistrer les identifiants** -Deux options. Utilisez des variables d’environnement pour le débogage sur une seule machine (définissez les quatre variables `OPENCLAW_QA_SLACK_*` et passez `--credential-source env`), ou alimentez le pool Convex partagé afin que CI et les autres mainteneurs puissent les réserver. +Deux options. Utilisez des variables d’environnement pour le débogage sur une seule machine (définissez les quatre variables `OPENCLAW_QA_SLACK_*` et passez `--credential-source env`), ou alimentez le pool Convex partagé afin que CI et les autres mainteneurs puissent les louer. Pour le pool Convex, écrivez les quatre champs dans un fichier JSON : @@ -482,7 +511,7 @@ Attendez-vous à `count: 1`, `status: "active"`, sans champ `lease`. **5. Vérifier de bout en bout** -Exécutez la lane localement pour confirmer que les deux bots peuvent communiquer entre eux via le broker : +Exécutez le lane localement pour confirmer que les deux bots peuvent communiquer entre eux via le broker : ```bash pnpm openclaw qa slack \ @@ -491,76 +520,76 @@ pnpm openclaw qa slack \ --output-dir .artifacts/qa-e2e/slack-local ``` -Une exécution réussie se termine largement en moins de 30 secondes et `slack-qa-report.md` affiche `slack-canary` et `slack-mention-gating` avec le statut `pass`. Si la lane se bloque pendant environ 90 secondes puis se termine avec `Convex credential pool exhausted for kind "slack"`, soit le pool est vide, soit chaque ligne est réservée — `qa credentials list --kind slack --status all --json` vous indiquera lequel de ces cas s’applique. +Une exécution verte se termine en bien moins de 30 secondes, et `slack-qa-report.md` affiche `slack-canary` et `slack-mention-gating` avec le statut `pass`. Si le lane reste bloqué pendant environ 90 secondes puis se termine avec `Convex credential pool exhausted for kind "slack"`, soit le pool est vide, soit toutes les lignes sont louées : `qa credentials list --kind slack --status all --json` vous indiquera laquelle de ces situations s’applique. ### Pool d’identifiants Convex -Les lanes Telegram, Discord et Slack peuvent réserver des identifiants depuis un pool Convex partagé au lieu de lire les variables d’environnement ci-dessus. Passez `--credential-source convex` (ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) ; QA Lab acquiert une réservation exclusive, maintient son Heartbeat pendant toute la durée de l’exécution, puis la libère à l’arrêt. Les types de pool sont `"telegram"`, `"discord"` et `"slack"`. +Les lanes Telegram, Discord et Slack peuvent louer des identifiants depuis un pool Convex partagé au lieu de lire les variables d’environnement ci-dessus. Passez `--credential-source convex` (ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) ; QA Lab acquiert un bail exclusif, envoie des heartbeats pendant toute la durée de l’exécution et le libère à l’arrêt. Les types de pool sont `"telegram"`, `"discord"` et `"slack"`. -Formes de payload que le broker valide sur `admin/add` : +Formes de payload validées par le broker sur `admin/add` : -- Telegram (`kind: "telegram"`) : `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` doit être une chaîne d’identifiant de discussion numérique. -- Discord (`kind: "discord"`) : `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. -- Slack (`kind: "slack"`) : `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` doit correspondre à `^[A-Z][A-Z0-9]+$` (un identifiant Slack comme `Cxxxxxxxxxx`). Consultez [Configurer l’espace de travail Slack](#setting-up-the-slack-workspace) pour le provisionnement de l’application et des portées. +- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` doit être une chaîne d’identifiant de chat numérique. +- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`. +- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` doit correspondre à `^[A-Z][A-Z0-9]+$` (un identifiant Slack comme `Cxxxxxxxxxx`). Consultez [Configurer l’espace de travail Slack](#setting-up-the-slack-workspace) pour le provisionnement de l’app et des scopes. Les variables d’environnement opérationnelles et le contrat d’endpoint du broker Convex se trouvent dans [Tests → Identifiants Telegram partagés via Convex](/fr/help/testing#shared-telegram-credentials-via-convex-v1) (le nom de la section est antérieur à la prise en charge de Discord ; la sémantique du broker est identique pour les deux types). ## Seeds adossés au dépôt -Les ressources de seed se trouvent dans `qa/` : +Les assets de seed se trouvent dans `qa/` : - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Elles sont intentionnellement dans git afin que le plan QA soit visible à la fois par les humains et par l’agent. +Ils sont intentionnellement versionnés dans git afin que le plan QA soit visible à la fois par les humains et par l’agent. -`qa-lab` doit rester un exécuteur Markdown générique. Chaque fichier Markdown de scénario est la source de vérité pour une exécution de test et doit définir : +`qa-lab` doit rester un runner Markdown générique. Chaque fichier de scénario Markdown est la source de vérité pour une exécution de test et doit définir : - les métadonnées du scénario - les métadonnées facultatives de catégorie, capacité, lane et risque -- les références de documentation et de code +- les références de docs et de code - les exigences facultatives de Plugin -- le correctif facultatif de configuration du Gateway +- le correctif facultatif de configuration Gateway - le `qa-flow` exécutable -La surface de runtime réutilisable qui sous-tend `qa-flow` peut rester générique et transversale. Par exemple, les scénarios Markdown peuvent combiner des assistants côté transport avec des assistants côté navigateur qui pilotent la Control UI intégrée via la jonction `browser.request` du Gateway, sans ajouter d’exécuteur de cas particulier. +La surface de runtime réutilisable qui soutient `qa-flow` peut rester générique et transversale. Par exemple, les scénarios Markdown peuvent combiner des helpers côté transport avec des helpers côté navigateur qui pilotent l’interface Control UI intégrée via la jointure Gateway `browser.request`, sans ajouter de runner spécial. -Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier de l’arborescence source. Gardez les identifiants de scénario stables lorsque les fichiers sont déplacés ; utilisez `docsRefs` et `codeRefs` pour la traçabilité de l’implémentation. +Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier de l’arborescence source. Gardez les identifiants de scénario stables lorsque les fichiers changent d’emplacement ; utilisez `docsRefs` et `codeRefs` pour la traçabilité de l’implémentation. -La liste de référence doit rester suffisamment large pour couvrir : +La liste de base doit rester assez large pour couvrir : -- les messages directs et la discussion de canal -- le comportement des fils +- les discussions DM et de canal +- le comportement des threads - le cycle de vie des actions de message - les callbacks cron -- le rappel de mémoire +- le rappel mémoire - le changement de modèle - le transfert vers un sous-agent - la lecture du dépôt et de la documentation - une petite tâche de build comme Lobster Invaders -## Lanes de mocks de fournisseur +## Lanes de mocks fournisseur -`qa suite` possède deux lanes locales de mock de fournisseur : +`qa suite` comporte deux lanes locales de mocks fournisseur : -- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste la lane de mock déterministe par défaut pour la QA adossée au dépôt et les portes de parité. -- `aimock` démarre un serveur fournisseur basé sur AIMock pour la couverture expérimentale du protocole, des fixtures, de l’enregistrement/relecture et du chaos. Il est additif et ne remplace pas le répartiteur de scénarios `mock-openai`. +- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste le lane de mock déterministe par défaut pour la QA adossée au dépôt et les portes de parité. +- `aimock` démarre un serveur fournisseur adossé à AIMock pour la couverture expérimentale du protocole, des fixtures, de l’enregistrement/relecture et du chaos. Il est additif et ne remplace pas le répartiteur de scénarios `mock-openai`. -L’implémentation des lanes de fournisseur se trouve sous `extensions/qa-lab/src/providers/`. Chaque fournisseur possède ses valeurs par défaut, le démarrage de son serveur local, la configuration de modèle du Gateway, les besoins de préparation de profils d’authentification et les indicateurs de capacité live/mock. Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu de créer des branches sur les noms de fournisseurs. +L’implémentation des lanes fournisseur se trouve sous `extensions/qa-lab/src/providers/`. Chaque fournisseur possède ses valeurs par défaut, le démarrage de son serveur local, la configuration du modèle Gateway, ses besoins de préparation d’auth-profile et ses indicateurs de capacité live/mock. Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu de brancher sur les noms de fournisseurs. ## Adaptateurs de transport -`qa-lab` possède une jonction de transport générique pour les scénarios QA Markdown. `qa-channel` est le premier adaptateur sur cette jonction, mais la cible de conception est plus large : les futurs canaux réels ou synthétiques doivent se brancher sur le même exécuteur de suite au lieu d’ajouter un exécuteur QA spécifique au transport. +`qa-lab` possède une jointure de transport générique pour les scénarios QA Markdown. `qa-channel` est le premier adaptateur sur cette jointure, mais la cible de conception est plus large : les futurs canaux réels ou synthétiques doivent se brancher au même runner de suite plutôt que d’ajouter un runner QA spécifique au transport. -Au niveau architectural, la séparation est la suivante : +Au niveau de l’architecture, la séparation est la suivante : - `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting. -- L’adaptateur de transport possède la configuration du Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé. +- L’adaptateur de transport possède la configuration Gateway, la disponibilité, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé. - Les fichiers de scénario Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface de runtime réutilisable qui les exécute. ### Ajouter un canal -Ajouter un canal au système QA Markdown nécessite exactement deux éléments : +Ajouter un canal au système QA Markdown exige exactement deux choses : 1. Un adaptateur de transport pour le canal. 2. Un pack de scénarios qui exerce le contrat du canal. @@ -577,37 +606,37 @@ N’ajoutez pas de nouvelle racine de commande QA de premier niveau lorsque l’ - l’exécution des scénarios - les alias de compatibilité pour les anciens scénarios `qa-channel` -Les plugins d’exécuteur possèdent le contrat de transport : +Les plugins runner possèdent le contrat de transport : -- comment `openclaw qa ` est monté sous la racine partagée `qa` -- comment le Gateway est configuré pour ce transport -- comment l’état prêt est vérifié -- comment les événements entrants sont injectés -- comment les messages sortants sont observés -- comment les transcriptions et l’état de transport normalisé sont exposés -- comment les actions adossées au transport sont exécutées -- comment la réinitialisation ou le nettoyage spécifique au transport est géré +- la manière dont `openclaw qa ` est monté sous la racine partagée `qa` +- la manière dont le Gateway est configuré pour ce transport +- la manière dont la disponibilité est vérifiée +- la manière dont les événements entrants sont injectés +- la manière dont les messages sortants sont observés +- la manière dont les transcripts et l’état de transport normalisé sont exposés +- la manière dont les actions adossées au transport sont exécutées +- la manière dont la réinitialisation ou le nettoyage spécifique au transport est géré -Le seuil minimal d’adoption pour un nouveau canal : +Le seuil minimum d’adoption pour un nouveau canal : 1. Garder `qa-lab` comme propriétaire de la racine partagée `qa`. -2. Implémenter l’exécuteur de transport sur la jonction d’hôte partagée de `qa-lab`. -3. Garder les mécanismes propres au transport dans le Plugin d’exécuteur ou le harnais de canal. -4. Monter l’exécuteur comme `openclaw qa ` au lieu d’enregistrer une racine de commande concurrente. Les Plugins d’exécuteur doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. Gardez `runtime-api.ts` léger ; la CLI paresseuse et l’exécution de l’exécuteur doivent rester derrière des points d’entrée séparés. +2. Implémenter le runner de transport sur la jointure d’hôte partagée `qa-lab`. +3. Garder les mécanismes spécifiques au transport dans le Plugin runner ou le harnais de canal. +4. Monter le runner comme `openclaw qa ` au lieu d’enregistrer une commande racine concurrente. Les plugins runner doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. Gardez `runtime-api.ts` léger ; la CLI paresseuse et l’exécution du runner doivent rester derrière des points d’entrée séparés. 5. Rédiger ou adapter des scénarios Markdown sous les répertoires thématiques `qa/scenarios/`. -6. Utiliser les assistants de scénario génériques pour les nouveaux scénarios. -7. Garder les alias de compatibilité existants opérationnels, sauf si le dépôt effectue une migration intentionnelle. +6. Utiliser les helpers de scénario génériques pour les nouveaux scénarios. +7. Garder les alias de compatibilité existants fonctionnels, sauf si le dépôt effectue une migration intentionnelle. La règle de décision est stricte : -- Si le comportement peut être exprimé une seule fois dans `qa-lab`, placez-le dans `qa-lab`. -- Si le comportement dépend d’un seul transport de canal, gardez-le dans ce Plugin d’exécuteur ou dans le harnais du Plugin. -- Si un scénario a besoin d’une nouvelle capacité que plusieurs canaux peuvent utiliser, ajoutez un assistant générique au lieu d’une branche spécifique au canal dans `suite.ts`. -- Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique au transport et rendez-le explicite dans le contrat du scénario. +- Si un comportement peut être exprimé une seule fois dans `qa-lab`, mettez-le dans `qa-lab`. +- Si un comportement dépend d’un transport de canal, gardez-le dans ce Plugin runner ou dans le harnais de Plugin. +- Si un scénario a besoin d’une nouvelle capacité que plusieurs canaux peuvent utiliser, ajoutez un helper générique au lieu d’une branche spécifique au canal dans `suite.ts`. +- Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique au transport et rendez cela explicite dans le contrat du scénario. -### Noms des assistants de scénario +### Noms des helpers de scénario -Assistants génériques recommandés pour les nouveaux scénarios : +Helpers génériques préférés pour les nouveaux scénarios : - `waitForTransportReady` - `waitForChannelReady` @@ -622,21 +651,21 @@ Assistants génériques recommandés pour les nouveaux scénarios : - `formatTransportTranscript` - `resetTransport` -Les alias de compatibilité restent disponibles pour les scénarios existants — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mais la rédaction de nouveaux scénarios doit utiliser les noms génériques. Les alias existent pour éviter une migration à date fixe, pas comme modèle pour l’avenir. +Les alias de compatibilité restent disponibles pour les scénarios existants — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mais la rédaction de nouveaux scénarios doit utiliser les noms génériques. Les alias existent pour éviter une migration instantanée, pas comme modèle pour la suite. ## Reporting -`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie du bus observée. -Le rapport doit répondre à : +`qa-lab` exporte un rapport de protocole Markdown depuis la chronologie de bus observée. +Le rapport doit répondre à ces questions : - Ce qui a fonctionné - Ce qui a échoué - Ce qui est resté bloqué - Les scénarios de suivi qu’il vaut la peine d’ajouter -Pour l’inventaire des scénarios disponibles — utile pour dimensionner les travaux de suivi ou câbler un nouveau transport — exécutez `pnpm openclaw qa coverage` (ajoutez `--json` pour une sortie lisible par machine). +Pour l’inventaire des scénarios disponibles — utile pour dimensionner le travail de suivi ou câbler un nouveau transport — exécutez `pnpm openclaw qa coverage` (ajoutez `--json` pour une sortie lisible par machine). -Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèle live et écrivez un rapport Markdown évalué : +Pour les contrôles de caractère et de style, exécutez le même scénario sur plusieurs refs de modèle live et écrivez un rapport Markdown jugé : ```bash pnpm openclaw qa character-eval \ @@ -655,47 +684,23 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -La commande exécute des processus enfants QA gateway locaux, pas Docker. Les scénarios -d’évaluation de personnage doivent définir la persona via `SOUL.md`, puis exécuter -des tours utilisateur ordinaires comme le chat, l’aide sur l’espace de travail et de -petites tâches sur des fichiers. Le modèle candidat ne doit pas être informé qu’il -est en cours d’évaluation. La commande préserve chaque transcription complète, -enregistre les statistiques d’exécution de base, puis demande aux modèles juges en -mode rapide, avec un raisonnement `xhigh` lorsque c’est pris en charge, de classer -les exécutions selon leur naturel, leur vibe et leur humour. Utilisez -`--blind-judge-models` lorsque vous comparez des fournisseurs : le prompt du juge -reçoit toujours chaque transcription et état d’exécution, mais les références des -candidats sont remplacées par des libellés neutres comme `candidate-01` ; le rapport -associe de nouveau les classements aux références réelles après l’analyse. -Les exécutions candidates utilisent par défaut une réflexion `high`, avec `medium` -pour GPT-5.5 et `xhigh` pour les anciennes références d’évaluation OpenAI qui le -prennent en charge. Remplacez un candidat précis en ligne avec -`--model provider/model,thinking=`. `--thinking ` définit toujours une -solution de repli globale, et l’ancienne forme `--model-thinking ` -est conservée pour compatibilité. -Les références candidates OpenAI utilisent par défaut le mode rapide afin que le -traitement prioritaire soit utilisé lorsque le fournisseur le prend en charge. -Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un seul candidat ou juge -nécessite un remplacement. Passez `--fast` uniquement lorsque vous voulez forcer le -mode rapide pour chaque modèle candidat. Les durées des candidats et des juges sont -enregistrées dans le rapport pour l’analyse comparative, mais les prompts des juges -indiquent explicitement de ne pas classer selon la vitesse. -Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une -concurrence de 16. Réduisez `--concurrency` ou `--judge-concurrency` lorsque les -limites du fournisseur ou la pression sur le gateway local rendent une exécution -trop bruitée. -Lorsqu’aucun candidat `--model` n’est transmis, l’évaluation de personnage utilise par défaut +La commande exécute des processus enfants du Gateway QA local, pas Docker. Les scénarios d’évaluation de personnage doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires comme du chat, de l’aide sur l’espace de travail et de petites tâches sur les fichiers. Le modèle candidat ne doit pas être informé qu’il est évalué. La commande conserve chaque transcription complète, enregistre des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide, avec un raisonnement `xhigh` lorsque c’est pris en charge, de classer les exécutions selon le naturel, l’ambiance et l’humour. +Utilisez `--blind-judge-models` lorsque vous comparez des fournisseurs : le prompt du juge reçoit toujours chaque transcription et statut d’exécution, mais les références des candidats sont remplacées par des libellés neutres comme `candidate-01` ; le rapport associe de nouveau les classements aux références réelles après l’analyse. +Les exécutions candidates utilisent par défaut un raisonnement `high`, avec `medium` pour GPT-5.5 et `xhigh` pour les anciennes références d’évaluation OpenAI qui le prennent en charge. Remplacez un candidat précis en ligne avec `--model provider/model,thinking=`. `--thinking ` définit toujours un repli global, et l’ancienne forme `--model-thinking ` est conservée pour la compatibilité. +Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé lorsque le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un candidat ou juge unique a besoin d’un remplacement. Passez `--fast` uniquement lorsque vous voulez forcer le mode rapide pour chaque modèle candidat. Les durées des candidats et des juges sont enregistrées dans le rapport pour l’analyse comparative, mais les prompts des juges indiquent explicitement de ne pas classer selon la vitesse. +Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez `--concurrency` ou `--judge-concurrency` lorsque les limites des fournisseurs ou la pression sur le Gateway local rendent une exécution trop bruyante. +Lorsqu’aucun candidat `--model` n’est passé, l’évaluation de personnage utilise par défaut `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, -`moonshot/kimi-k2.5`, et -`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est transmis. -Lorsqu’aucun `--judge-model` n’est transmis, les juges utilisent par défaut +`moonshot/kimi-k2.5` et +`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est passé. +Lorsqu’aucun `--judge-model` n’est passé, les juges utilisent par défaut `openai/gpt-5.5,thinking=xhigh,fast` et `anthropic/claude-opus-4-6,thinking=high`. -## Docs associées +## Docs connexes -- [QA matricielle](/fr/concepts/qa-matrix) +- [Matrice QA](/fr/concepts/qa-matrix) - [Canal QA](/fr/channels/qa-channel) - [Tests](/fr/help/testing) - [Tableau de bord](/fr/web/dashboard) diff --git a/docs/fr/gateway/configuration-reference.md b/docs/fr/gateway/configuration-reference.md index 8a85c56be..ce75bb27b 100644 --- a/docs/fr/gateway/configuration-reference.md +++ b/docs/fr/gateway/configuration-reference.md @@ -2,37 +2,37 @@ read_when: - Vous avez besoin de la sémantique exacte de la configuration au niveau des champs ou des valeurs par défaut - Vous validez des blocs de configuration de canal, de modèle, de Gateway ou d’outil -summary: Référence de configuration du Gateway pour les clés OpenClaw principales, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes +summary: Référence de configuration du Gateway pour les clés principales d’OpenClaw, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes title: Référence de configuration x-i18n: - generated_at: "2026-05-05T01:46:23Z" + generated_at: "2026-05-05T06:17:08Z" model: gpt-5.5 provider: openai - source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684 + source_hash: fd0b6bf9a77d91bcc240088e4be92e44b6e70910efe00f7ed99534fb70983479 source_path: gateway/configuration-reference.md workflow: 16 --- -Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâche, consultez [Configuration](/fr/gateway/configuration). +Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâches, consultez [Configuration](/fr/gateway/configuration). -Couvre les principales surfaces de configuration d’OpenClaw et renvoie vers d’autres pages lorsqu’un sous-système dispose de sa propre référence plus approfondie. Les catalogues de commandes appartenant aux canaux et aux plugins, ainsi que les réglages avancés de mémoire/QMD, se trouvent sur leurs propres pages plutôt que sur celle-ci. +Couvre les principales surfaces de configuration d’OpenClaw et fournit des liens lorsqu’un sous-système dispose de sa propre référence plus détaillée. Les catalogues de commandes propres aux canaux et aux Plugins, ainsi que les réglages avancés de mémoire/QMD, se trouvent sur leurs propres pages plutôt que sur celle-ci. Vérité du code : -- `openclaw config schema` affiche le JSON Schema actif utilisé pour la validation et la Control UI, avec les métadonnées intégrées/plugin/canal fusionnées lorsqu’elles sont disponibles +- `openclaw config schema` affiche le JSON Schema actif utilisé pour la validation et l’interface utilisateur de contrôle, avec les métadonnées groupées/des Plugins/des canaux fusionnées lorsqu’elles sont disponibles - `config.schema.lookup` renvoie un nœud de schéma limité à un chemin pour les outils d’exploration détaillée -- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hachage de référence de la documentation de configuration par rapport à la surface de schéma actuelle +- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hash de référence de la documentation de configuration par rapport à la surface de schéma actuelle -Chemin de recherche de l’agent : utilisez l’action d’outil `gateway` `config.schema.lookup` pour -obtenir la documentation et les contraintes exactes au niveau des champs avant toute modification. Utilisez -[Configuration](/fr/gateway/configuration) pour des conseils orientés tâche et cette page -pour la carte plus générale des champs, les valeurs par défaut et les liens vers les références des sous-systèmes. +Chemin de recherche d’agent : utilisez l’action d’outil `gateway` `config.schema.lookup` pour +obtenir la documentation et les contraintes exactes au niveau des champs avant les modifications. Utilisez +[Configuration](/fr/gateway/configuration) pour des conseils orientés tâches et cette page +pour la cartographie plus large des champs, les valeurs par défaut et les liens vers les références des sous-systèmes. -Références approfondies dédiées : +Références détaillées dédiées : -- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` et la configuration de Dreaming sous `plugins.entries.memory-core.config.dreaming` -- [Commandes slash](/fr/tools/slash-commands) pour le catalogue actuel des commandes intégrées + incluses -- pages des canaux/plugins propriétaires pour les surfaces de commandes propres aux canaux +- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` et la configuration Dreaming sous `plugins.entries.memory-core.config.dreaming` +- [Commandes slash](/fr/tools/slash-commands) pour le catalogue actuel des commandes intégrées + groupées +- pages propriétaires des canaux/Plugins pour les surfaces de commandes propres aux canaux Le format de configuration est **JSON5** (commentaires + virgules finales autorisés). Tous les champs sont facultatifs — OpenClaw utilise des valeurs par défaut sûres lorsqu’ils sont omis. @@ -40,35 +40,35 @@ Le format de configuration est **JSON5** (commentaires + virgules finales autori ## Canaux -Les clés de configuration par canal ont été déplacées vers une page dédiée — consultez +Les clés de configuration par canal ont été déplacées vers une page dédiée — voir [Configuration — canaux](/fr/gateway/config-channels) pour `channels.*`, notamment Slack, Discord, Telegram, WhatsApp, Matrix, iMessage et les autres -canaux inclus (authentification, contrôle d’accès, multi-compte, filtrage des mentions). +canaux groupés (authentification, contrôle d’accès, multi-compte, filtrage des mentions). ## Valeurs par défaut des agents, multi-agent, sessions et messages -Déplacé vers une page dédiée — consultez +Déplacé vers une page dédiée — voir [Configuration — agents](/fr/gateway/config-agents) pour : -- `agents.defaults.*` (espace de travail, modèle, raisonnement, Heartbeat, mémoire, médias, Skills, bac à sable) +- `agents.defaults.*` (espace de travail, modèle, réflexion, Heartbeat, mémoire, médias, Skills, bac à sable) - `multiAgent.*` (routage et liaisons multi-agent) - `session.*` (cycle de vie des sessions, Compaction, élagage) -- `messages.*` (livraison des messages, TTS, rendu markdown) +- `messages.*` (livraison des messages, TTS, rendu Markdown) - `talk.*` (mode Talk) - `talk.speechLocale` : identifiant de locale BCP 47 facultatif pour la reconnaissance vocale Talk sur iOS/macOS - - `talk.silenceTimeoutMs` : lorsqu’il n’est pas défini, Talk conserve la fenêtre de pause par défaut de la plateforme avant d’envoyer la transcription (`700 ms on macOS and Android, 900 ms on iOS`) + - `talk.silenceTimeoutMs` : lorsque non défini, Talk conserve la fenêtre de pause par défaut de la plateforme avant d’envoyer la transcription (`700 ms on macOS and Android, 900 ms on iOS`) ## Outils et fournisseurs personnalisés -La politique d’outils, les bascules expérimentales, la configuration d’outils adossés à des fournisseurs et la configuration de -fournisseur personnalisé / URL de base ont été déplacées vers une page dédiée — consultez +La politique d’outils, les bascules expérimentales, la configuration d’outils adossée à des fournisseurs et la configuration de +fournisseur / URL de base personnalisée ont été déplacées vers une page dédiée — voir [Configuration — outils et fournisseurs personnalisés](/fr/gateway/config-tools). ## Modèles Les définitions de fournisseurs, les listes d’autorisation de modèles et la configuration de fournisseurs personnalisés se trouvent dans [Configuration — outils et fournisseurs personnalisés](/fr/gateway/config-tools#custom-providers-and-base-urls). -La racine `models` possède également le comportement global du catalogue de modèles. +La racine `models` possède aussi le comportement global du catalogue de modèles. ```json5 { @@ -80,16 +80,16 @@ La racine `models` possède également le comportement global du catalogue de mo ``` - `models.mode` : comportement du catalogue de fournisseurs (`merge` ou `replace`). -- `models.providers` : carte des fournisseurs personnalisés indexée par identifiant de fournisseur. -- `models.pricing.enabled` : contrôle l’amorçage de tarification en arrière-plan qui - démarre après que les sidecars et les canaux atteignent le chemin prêt du Gateway. Lorsqu’il vaut `false`, - le Gateway ignore les récupérations de catalogues de tarification OpenRouter et LiteLLM ; les valeurs - `models.providers.*.models[].cost` configurées fonctionnent toujours pour les estimations de coût locales. +- `models.providers` : carte de fournisseurs personnalisés indexée par identifiant de fournisseur. +- `models.pricing.enabled` : contrôle l’amorçage en arrière-plan de la tarification qui + démarre après que les sidecars et les canaux atteignent le chemin Gateway prêt. Lorsque `false`, + le Gateway ignore les récupérations des catalogues de tarification OpenRouter et LiteLLM ; les valeurs + `models.providers.*.models[].cost` configurées continuent de fonctionner pour les estimations de coût locales. ## MCP -Les définitions de serveurs MCP gérées par OpenClaw se trouvent sous `mcp.servers` et sont -consommées par Pi intégré et les autres adaptateurs d’exécution. Les commandes `openclaw mcp list`, +Les définitions de serveurs MCP gérés par OpenClaw se trouvent sous `mcp.servers` et sont +consommées par Pi intégré et d’autres adaptateurs d’exécution. Les commandes `openclaw mcp list`, `show`, `set` et `unset` gèrent ce bloc sans se connecter au serveur cible pendant les modifications de configuration. @@ -115,20 +115,20 @@ serveur cible pendant les modifications de configuration. } ``` -- `mcp.servers` : définitions de serveurs MCP stdio ou distants nommées pour les environnements d’exécution qui +- `mcp.servers` : définitions nommées de serveurs MCP stdio ou distants pour les environnements d’exécution qui exposent les outils MCP configurés. Les entrées distantes utilisent `transport: "streamable-http"` ou `transport: "sse"` ; `type: "http"` est un alias natif de la CLI que `openclaw mcp set` et `openclaw doctor --fix` normalisent dans le champ canonique `transport`. -- `mcp.sessionIdleTtlMs` : TTL d’inactivité pour les environnements d’exécution MCP inclus à portée de session. - Les exécutions intégrées ponctuelles demandent un nettoyage en fin d’exécution ; ce TTL sert de filet de sécurité pour - les sessions de longue durée et les futurs appelants. +- `mcp.sessionIdleTtlMs` : TTL d’inactivité pour les environnements d’exécution MCP groupés à portée de session. + Les exécutions intégrées ponctuelles demandent un nettoyage de fin d’exécution ; ce TTL est le garde-fou pour + les sessions longues et les futurs appelants. - Les modifications sous `mcp.*` s’appliquent à chaud en supprimant les environnements d’exécution MCP de session en cache. - La découverte/utilisation suivante des outils les recrée à partir de la nouvelle configuration, de sorte que les entrées - `mcp.servers` supprimées sont récupérées immédiatement au lieu d’attendre le TTL d’inactivité. + La prochaine découverte/utilisation d’outil les recrée à partir de la nouvelle configuration, de sorte que les entrées + `mcp.servers` supprimées sont collectées immédiatement au lieu d’attendre le TTL d’inactivité. Consultez [MCP](/fr/cli/mcp#openclaw-as-an-mcp-client-registry) et -[Backends CLI](/fr/gateway/cli-backends#bundle-mcp-overlays) pour le comportement à l’exécution. +[Backends CLI](/fr/gateway/cli-backends#bundle-mcp-overlays) pour le comportement d’exécution. ## Skills @@ -155,14 +155,14 @@ Consultez [MCP](/fr/cli/mcp#openclaw-as-an-mcp-client-registry) et } ``` -- `allowBundled` : liste d’autorisation facultative pour les Skills inclus uniquement (les Skills gérées/de l’espace de travail ne sont pas affectées). -- `load.extraDirs` : racines de Skills partagées supplémentaires (priorité la plus basse). -- `install.preferBrew` : lorsqu’il vaut true, privilégie les installateurs Homebrew lorsque `brew` est - disponible avant de revenir aux autres types d’installateurs. -- `install.nodeManager` : préférence d’installateur node pour les spécifications `metadata.openclaw.install` +- `allowBundled` : liste d’autorisation facultative pour les Skills groupées uniquement (Skills gérées/de l’espace de travail non affectées). +- `load.extraDirs` : racines de Skills partagées supplémentaires (priorité la plus faible). +- `install.preferBrew` : lorsque vrai, privilégie les installateurs Homebrew lorsque `brew` est + disponible avant de revenir à d’autres types d’installateurs. +- `install.nodeManager` : préférence d’installateur Node pour les spécifications `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` désactive une Skill même si elle est incluse/installée. -- `entries..apiKey` : raccourci pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef). +- `entries..enabled: false` désactive une Skill même si elle est groupée/installée. +- `entries..apiKey` : commodité pour les Skills déclarant une variable d’environnement principale (chaîne en texte clair ou objet SecretRef). --- @@ -192,44 +192,44 @@ Consultez [MCP](/fr/cli/mcp#openclaw-as-an-mcp-client-registry) et ``` - Chargés depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, plus `plugins.load.paths`. -- La découverte accepte les plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude sans manifeste à disposition par défaut. -- **Les changements de configuration nécessitent un redémarrage du gateway.** -- `allow` : liste d’autorisation facultative (seuls les plugins listés se chargent). `deny` prévaut. +- La découverte accepte les Plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude de disposition par défaut sans manifeste. +- **Les modifications de configuration nécessitent un redémarrage du Gateway.** +- `allow` : liste d’autorisation facultative (seuls les Plugins listés se chargent). `deny` l’emporte. - `bundledDiscovery` : vaut par défaut `"allowlist"` pour les nouvelles configurations, de sorte qu’un - `plugins.allow` non vide filtre aussi les plugins fournisseurs inclus, y compris les fournisseurs d’exécution + `plugins.allow` non vide filtre aussi les Plugins de fournisseurs groupés, y compris les fournisseurs d’exécution de recherche web. Doctor écrit `"compat"` pour les configurations de liste d’autorisation héritées migrées - afin de préserver le comportement existant des fournisseurs inclus jusqu’à votre activation explicite. -- `plugins.entries..apiKey` : champ pratique de clé API au niveau du plugin (lorsqu’il est pris en charge par le plugin). -- `plugins.entries..env` : carte de variables d’environnement limitée au plugin. -- `plugins.entries..hooks.allowPromptInjection` : lorsqu’il vaut `false`, le cœur bloque `before_prompt_build` et ignore les champs modifiant le prompt issus de l’ancien `before_agent_start`, tout en préservant les anciens `modelOverride` et `providerOverride`. S’applique aux hooks de plugins natifs et aux répertoires de hooks fournis par des bundles pris en charge. -- `plugins.entries..hooks.allowConversationAccess` : lorsqu’il vaut `true`, les plugins non inclus approuvés peuvent lire le contenu brut des conversations depuis des hooks typés comme `llm_input`, `llm_output`, `before_agent_finalize` et `agent_end`. -- `plugins.entries..subagent.allowModelOverride` : approuve explicitement ce plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions de sous-agents en arrière-plan. -- `plugins.entries..subagent.allowedModels` : liste d’autorisation facultative de cibles canoniques `provider/model` pour les remplacements de sous-agents approuvés. Utilisez `"*"` uniquement lorsque vous voulez intentionnellement autoriser n’importe quel modèle. -- `plugins.entries..config` : objet de configuration défini par le plugin (validé par le schéma du plugin OpenClaw natif lorsqu’il est disponible). -- Les paramètres de compte/d’exécution des plugins de canal se trouvent sous `channels.` et doivent être décrits par les métadonnées `channelConfigs` du manifeste du plugin propriétaire, et non par un registre central d’options OpenClaw. + afin de préserver le comportement existant des fournisseurs groupés jusqu’à votre adhésion. +- `plugins.entries..apiKey` : champ pratique de clé API au niveau du Plugin (lorsque pris en charge par le Plugin). +- `plugins.entries..env` : carte de variables d’environnement limitée au Plugin. +- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le cœur bloque `before_prompt_build` et ignore les champs qui modifient le prompt issus de l’ancien `before_agent_start`, tout en préservant les anciens `modelOverride` et `providerOverride`. S’applique aux hooks de Plugins natifs et aux répertoires de hooks fournis par bundle pris en charge. +- `plugins.entries..hooks.allowConversationAccess` : lorsque `true`, les Plugins non groupés de confiance peuvent lire le contenu brut des conversations depuis des hooks typés tels que `llm_input`, `llm_output`, `before_agent_finalize` et `agent_end`. +- `plugins.entries..subagent.allowModelOverride` : faire explicitement confiance à ce Plugin pour demander des substitutions `provider` et `model` par exécution pour les exécutions de sous-agents en arrière-plan. +- `plugins.entries..subagent.allowedModels` : liste d’autorisation facultative de cibles canoniques `provider/model` pour les substitutions de sous-agents de confiance. Utilisez `"*"` uniquement lorsque vous voulez intentionnellement autoriser n’importe quel modèle. +- `plugins.entries..config` : objet de configuration défini par le Plugin (validé par le schéma de Plugin OpenClaw natif lorsqu’il est disponible). +- Les paramètres de compte/d’exécution des Plugins de canal se trouvent sous `channels.` et doivent être décrits par les métadonnées `channelConfigs` du manifeste du Plugin propriétaire, et non par un registre central d’options OpenClaw. - `plugins.entries.firecrawl.config.webFetch` : paramètres du fournisseur de récupération web Firecrawl. - `apiKey` : clé API Firecrawl (accepte SecretRef). Se rabat sur `plugins.entries.firecrawl.config.webSearch.apiKey`, l’ancien `tools.web.fetch.firecrawl.apiKey` ou la variable d’environnement `FIRECRAWL_API_KEY`. - - `baseUrl` : URL de base de l’API Firecrawl (par défaut : `https://api.firecrawl.dev` ; les remplacements auto-hébergés doivent cibler des points de terminaison privés/internes). - - `onlyMainContent` : extrait uniquement le contenu principal des pages (par défaut : `true`). + - `baseUrl` : URL de base de l’API Firecrawl (par défaut : `https://api.firecrawl.dev` ; les substitutions auto-hébergées doivent cibler des points de terminaison privés/internes). + - `onlyMainContent` : extraire uniquement le contenu principal des pages (par défaut : `true`). - `maxAgeMs` : âge maximal du cache en millisecondes (par défaut : `172800000` / 2 jours). - - `timeoutSeconds` : délai d’expiration de la requête de scraping en secondes (par défaut : `60`). + - `timeoutSeconds` : délai d’expiration des requêtes de scraping en secondes (par défaut : `60`). - `plugins.entries.xai.config.xSearch` : paramètres xAI X Search (recherche web Grok). - - `enabled` : active le fournisseur X Search. + - `enabled` : activer le fournisseur X Search. - `model` : modèle Grok à utiliser pour la recherche (par ex. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming` : paramètres de Dreaming mémoire. Consultez [Dreaming](/fr/concepts/dreaming) pour les phases et les seuils. - - `enabled` : interrupteur principal de Dreaming (par défaut `false`). - - `frequency` : cadence Cron pour chaque balayage complet de Dreaming (`"0 3 * * *"` par défaut). - - `model` : remplacement facultatif du modèle de sous-agent Dream Diary. Nécessite `plugins.entries.memory-core.subagent.allowModelOverride: true` ; associez-le à `allowedModels` pour restreindre les cibles. Les erreurs de modèle indisponible réessaient une fois avec le modèle par défaut de la session ; les échecs de confiance ou de liste d’autorisation ne se rabattent pas silencieusement. - - la politique des phases et les seuils sont des détails d’implémentation (pas des clés de configuration exposées à l’utilisateur). +- `plugins.entries.memory-core.config.dreaming` : paramètres de Dreaming de la mémoire. Consultez [Dreaming](/fr/concepts/dreaming) pour les phases et les seuils. + - `enabled` : commutateur maître Dreaming (par défaut `false`). + - `frequency` : cadence Cron pour chaque balayage Dreaming complet (`"0 3 * * *"` par défaut). + - `model` : substitution facultative du modèle de sous-agent Dream Diary. Nécessite `plugins.entries.memory-core.subagent.allowModelOverride: true` ; associez-le à `allowedModels` pour restreindre les cibles. Les erreurs de modèle indisponible réessaient une fois avec le modèle par défaut de la session ; les échecs de confiance ou de liste d’autorisation ne se rabattent pas silencieusement. + - la politique des phases et les seuils sont des détails d’implémentation (pas des clés de configuration destinées aux utilisateurs). - La configuration complète de la mémoire se trouve dans [Référence de configuration de la mémoire](/fr/reference/memory-config) : - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Les plugins de bundle Claude activés peuvent aussi contribuer des valeurs par défaut Pi intégrées depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, pas comme correctifs bruts de configuration OpenClaw. -- `plugins.slots.memory` : choisit l’identifiant du plugin de mémoire actif, ou `"none"` pour désactiver les plugins de mémoire. -- `plugins.slots.contextEngine` : choisit l’identifiant du plugin de moteur de contexte actif ; vaut par défaut `"legacy"` sauf si vous installez et sélectionnez un autre moteur. +- Les Plugins de bundle Claude activés peuvent aussi contribuer des valeurs par défaut Pi intégrées depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, et non comme correctifs bruts de configuration OpenClaw. +- `plugins.slots.memory` : choisir l’identifiant du Plugin de mémoire actif, ou `"none"` pour désactiver les Plugins de mémoire. +- `plugins.slots.contextEngine` : choisir l’identifiant du Plugin de moteur de contexte actif ; vaut par défaut `"legacy"` sauf si vous installez et sélectionnez un autre moteur. Consultez [Plugins](/fr/tools/plugin). @@ -237,9 +237,9 @@ Consultez [Plugins](/fr/tools/plugin). ## Engagements -`commitments` contrôle la mémoire de suivi inférée : OpenClaw peut détecter les points de suivi à partir des tours de conversation et les livrer via les exécutions Heartbeat. +`commitments` contrôle la mémoire de suivi inférée : OpenClaw peut détecter des points de suivi depuis les tours de conversation et les livrer via des exécutions Heartbeat. -- `commitments.enabled` : active l’extraction LLM masquée, le stockage et la livraison par Heartbeat des engagements de suivi inférés. Par défaut : `false`. +- `commitments.enabled` : activer l’extraction LLM masquée, le stockage et la livraison Heartbeat des engagements de suivi inférés. Par défaut : `false`. - `commitments.maxPerDay` : nombre maximal d’engagements de suivi inférés livrés par session d’agent sur une journée glissante. Par défaut : `3`. Consultez [Engagements inférés](/fr/concepts/commitments). @@ -293,49 +293,47 @@ Consultez [Engagements inférés](/fr/concepts/commitments). ``` - `evaluateEnabled: false` désactive `act:evaluate` et `wait --fn`. -- `tabCleanup` récupère les onglets suivis de l’agent principal après le délai d’inactivité ou lorsqu’une - session dépasse son plafond. Définissez `idleMinutes: 0` ou `maxTabsPerSession: 0` pour - désactiver ces modes de nettoyage individuels. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini ; la navigation du navigateur reste donc stricte par défaut. +- `tabCleanup` récupère les onglets suivis de l’agent principal après une période d’inactivité ou lorsqu’une session dépasse sa limite. Définissez `idleMinutes: 0` ou `maxTabsPerSession: 0` pour désactiver ces modes de nettoyage individuellement. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini, de sorte que la navigation du navigateur reste stricte par défaut. - Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` uniquement lorsque vous faites intentionnellement confiance à la navigation du navigateur sur le réseau privé. -- En mode strict, les points de terminaison des profils CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage des réseaux privés pendant les contrôles d’accessibilité/découverte. +- En mode strict, les points de terminaison des profils CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage du réseau privé lors des contrôles d’accessibilité/de découverte. - `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias hérité. - En mode strict, utilisez `ssrfPolicy.hostnameAllowlist` et `ssrfPolicy.allowedHostnames` pour les exceptions explicites. -- Les profils distants sont en attachement uniquement (démarrage/arrêt/réinitialisation désactivés). +- Les profils distants sont uniquement en attachement (démarrage/arrêt/réinitialisation désactivés). - `profiles.*.cdpUrl` accepte `http://`, `https://`, `ws://` et `wss://`. - Utilisez HTTP(S) lorsque vous voulez qu’OpenClaw découvre `/json/version` ; utilisez WS(S) + Utilisez HTTP(S) lorsque vous voulez qu’OpenClaw découvre `/json/version`; utilisez WS(S) lorsque votre fournisseur vous donne une URL WebSocket DevTools directe. - `remoteCdpTimeoutMs` et `remoteCdpHandshakeTimeoutMs` s’appliquent à l’accessibilité CDP distante et - `attachOnly`, ainsi qu’aux requêtes d’ouverture d’onglets. Les profils gérés en loopback - conservent les valeurs CDP locales par défaut. + `attachOnly`, ainsi qu’aux demandes d’ouverture d’onglets. Les profils local loopback + gérés conservent les valeurs CDP locales par défaut. - Si un service CDP géré en externe est accessible via loopback, définissez - `attachOnly: true` pour ce profil ; sinon OpenClaw traite le port loopback comme un - profil de navigateur local géré et peut signaler des erreurs de propriété de port local. + `attachOnly: true` pour ce profil ; sinon, OpenClaw traite le port loopback comme un + profil de navigateur géré localement et peut signaler des erreurs de propriété de port local. - Les profils `existing-session` utilisent Chrome MCP au lieu de CDP et peuvent s’attacher sur l’hôte sélectionné ou via un nœud de navigateur connecté. -- Les profils `existing-session` peuvent définir `userDataDir` pour cibler un profil de navigateur - basé sur Chromium spécifique, comme Brave ou Edge. +- Les profils `existing-session` peuvent définir `userDataDir` pour cibler un profil + de navigateur basé sur Chromium spécifique, comme Brave ou Edge. - Les profils `existing-session` conservent les limites de routage Chrome MCP actuelles : - actions pilotées par instantané/référence au lieu du ciblage par sélecteur CSS, hooks de téléversement - d’un fichier, aucune substitution de délai d’expiration des boîtes de dialogue, pas de - `wait --load networkidle`, et pas de `responsebody`, d’export PDF, d’interception des téléchargements ni d’actions par lot. -- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; ne - définissez explicitement `cdpUrl` que pour le CDP distant. + actions pilotées par instantané/référence au lieu du ciblage par sélecteur CSS, hooks + d’envoi d’un seul fichier, aucune surcharge des délais d’expiration de dialogue, pas de + `wait --load networkidle`, et pas de `responsebody`, d’export PDF, d’interception des téléchargements ni d’actions par lots. +- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; définissez + `cdpUrl` explicitement uniquement pour le CDP distant. - Les profils gérés localement peuvent définir `executablePath` pour remplacer le - `browser.executablePath` global pour ce profil. Utilisez-le pour exécuter un profil dans + `browser.executablePath` global pour ce profil. Utilisez cela pour exécuter un profil dans Chrome et un autre dans Brave. -- Les profils gérés localement utilisent `browser.localLaunchTimeoutMs` pour la découverte HTTP Chrome CDP - après le démarrage du processus et `browser.localCdpReadyTimeoutMs` pour - l’état prêt du websocket CDP après le lancement. Augmentez-les sur les hôtes plus lents où Chrome - démarre correctement mais où les contrôles de disponibilité entrent en concurrence avec le démarrage. Les deux valeurs doivent être - des entiers positifs jusqu’à `120000` ms ; les valeurs de configuration invalides sont rejetées. +- Les profils gérés localement utilisent `browser.localLaunchTimeoutMs` pour la découverte HTTP CDP de Chrome + après le démarrage du processus et `browser.localCdpReadyTimeoutMs` pour la disponibilité + WebSocket CDP après le lancement. Augmentez ces valeurs sur les hôtes plus lents où Chrome + démarre correctement, mais où les contrôles de disponibilité devancent le démarrage. Les deux valeurs doivent être + des entiers positifs jusqu’à `120000` ms ; les valeurs de configuration non valides sont rejetées. - Ordre de détection automatique : navigateur par défaut s’il est basé sur Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` et `browser.profiles..executablePath` acceptent tous deux - `~` et `~/...` pour le répertoire personnel de votre OS avant le lancement de Chromium. - `userDataDir` par profil sur les profils `existing-session` fait aussi l’objet d’une expansion du tilde. + `~` et `~/...` pour le répertoire personnel de votre système d’exploitation avant le lancement de Chromium. + `userDataDir` par profil sur les profils `existing-session` est également développé à partir du tilde. - Service de contrôle : loopback uniquement (port dérivé de `gateway.port`, valeur par défaut `18791`). - `extraArgs` ajoute des indicateurs de lancement supplémentaires au démarrage local de Chromium (par exemple - `--disable-gpu`, le dimensionnement de fenêtre ou les indicateurs de débogage). + `--disable-gpu`, le dimensionnement de fenêtre ou des indicateurs de débogage). --- @@ -353,8 +351,8 @@ Consultez [Engagements inférés](/fr/concepts/commitments). } ``` -- `seamColor` : couleur d’accentuation pour le chrome de l’interface utilisateur de l’application native (teinte de la bulle du mode Talk, etc.). -- `assistant` : remplacement de l’identité de Control UI. Se rabat sur l’identité de l’agent actif. +- `seamColor` : couleur d’accentuation pour le chrome de l’interface utilisateur de l’application native (teinte de bulle du mode Conversation, etc.). +- `assistant` : remplacement de l’identité de l’interface de contrôle. Reprend l’identité de l’agent actif par défaut. --- @@ -432,54 +430,54 @@ Consultez [Engagements inférés](/fr/concepts/commitments). -- `mode` : `local` (lancer le Gateway) ou `remote` (se connecter au Gateway distant). Le Gateway refuse de démarrer sauf si la valeur est `local`. +- `mode` : `local` (exécuter le Gateway) ou `remote` (se connecter au Gateway distant). Le Gateway refuse de démarrer sauf si la valeur est `local`. - `port` : port multiplexé unique pour WS + HTTP. Priorité : `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind` : `auto`, `loopback` (par défaut), `lan` (`0.0.0.0`), `tailnet` (IP Tailscale uniquement), ou `custom`. -- **Alias bind hérités** : utilisez les valeurs de mode bind dans `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), pas les alias d’hôte (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Note Docker** : le bind `loopback` par défaut écoute sur `127.0.0.1` à l’intérieur du conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc le Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. -- **Auth** : requise par défaut. Les binds non-loopback exigent l’authentification du Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse sensible à l’identité avec `gateway.auth.mode: "trusted-proxy"`. L’assistant d’onboarding génère un jeton par défaut. -- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés (y compris via SecretRefs), définissez explicitement `gateway.auth.mode` sur `token` ou `password`. Les flux de démarrage et d’installation/réparation du service échouent lorsque les deux sont configurés et que le mode n’est pas défini. -- `gateway.auth.mode: "none"` : mode explicite sans auth. À utiliser uniquement pour les configurations local loopback de confiance ; ce mode n’est intentionnellement pas proposé par les invites d’onboarding. -- `gateway.auth.mode: "trusted-proxy"` : délègue l’authentification navigateur/utilisateur à un proxy inverse sensible à l’identité et fait confiance aux en-têtes d’identité provenant de `gateway.trustedProxies` (voir [Auth par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend par défaut une source de proxy **non-loopback** ; les proxys inverses loopback sur le même hôte nécessitent `gateway.auth.trustedProxy.allowLoopback = true` explicite. Les appelants internes sur le même hôte peuvent utiliser `gateway.auth.password` comme solution de repli directe locale ; `gateway.auth.token` reste mutuellement exclusif avec le mode trusted-proxy. -- `gateway.auth.allowTailscale` : lorsque `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’authentification de la Control UI/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison de l’API HTTP n’utilisent **pas** cette authentification par en-tête Tailscale ; ils suivent plutôt le mode d’authentification HTTP normal du Gateway. Ce flux sans jeton suppose que l’hôte du Gateway est fiable. La valeur par défaut est `true` lorsque `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit` : limiteur optionnel des échecs d’authentification. S’applique par IP client et par périmètre d’authentification (shared-secret et device-token sont suivis indépendamment). Les tentatives bloquées renvoient `429` + `Retry-After`. - - Sur le chemin asynchrone Tailscale Serve Control UI, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives incorrectes concurrentes depuis le même client peuvent donc déclencher le limiteur dès la deuxième requête au lieu de toutes passer simultanément comme de simples non-correspondances. - - `gateway.auth.rateLimit.exemptLoopback` vaut `true` par défaut ; définissez `false` lorsque vous voulez intentionnellement limiter aussi le trafic localhost (pour des configurations de test ou des déploiements de proxy stricts). -- Les tentatives d’auth WS provenant d’une origine navigateur sont toujours limitées, avec l’exemption loopback désactivée (défense en profondeur contre la force brute localhost depuis le navigateur). -- Sur loopback, ces verrouillages provenant d’une origine navigateur sont isolés par valeur - `Origin` normalisée, de sorte que les échecs répétés depuis une origine localhost ne verrouillent pas automatiquement - une autre origine. -- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite une auth). -- `controlUi.allowedOrigins` : liste d’autorisation explicite des origines navigateur pour les connexions WebSocket au Gateway. Requise lorsque des clients navigateur sont attendus depuis des origines non-loopback. -- `controlUi.chatMessageMaxWidth` : largeur maximale optionnelle pour les messages de chat groupés de la Control UI. Accepte des valeurs de largeur CSS contraintes telles que `960px`, `82%`, `min(1280px, 82%)` et `calc(100% - 2rem)`. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active la solution de repli d’origine basée sur l’en-tête Host pour les déploiements qui s’appuient intentionnellement sur une politique d’origine fondée sur l’en-tête Host. +- `bind` : `auto`, `loopback` (par défaut), `lan` (`0.0.0.0`), `tailnet` (IP Tailscale uniquement) ou `custom`. +- **Alias bind hérités** : utilisez les valeurs du mode bind dans `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), pas les alias d’hôte (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Note Docker** : le bind `loopback` par défaut écoute sur `127.0.0.1` à l’intérieur du conteneur. Avec le réseau bridge de Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc le Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. +- **Auth** : requise par défaut. Les binds hors loopback nécessitent l’authentification du Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un reverse proxy sensible à l’identité avec `gateway.auth.mode: "trusted-proxy"`. L’assistant d’onboarding génère un jeton par défaut. +- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés (y compris avec SecretRefs), définissez explicitement `gateway.auth.mode` sur `token` ou `password`. Les flux de démarrage et d’installation/réparation du service échouent lorsque les deux sont configurés et que le mode n’est pas défini. +- `gateway.auth.mode: "none"` : mode explicite sans auth. À utiliser uniquement pour les configurations local loopback de confiance ; il n’est volontairement pas proposé par les invites d’onboarding. +- `gateway.auth.mode: "trusted-proxy"` : déléguez l’auth navigateur/utilisateur à un reverse proxy sensible à l’identité et faites confiance aux en-têtes d’identité provenant de `gateway.trustedProxies` (voir [Auth par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend par défaut une source de proxy **hors loopback** ; les reverse proxies loopback sur le même hôte nécessitent `gateway.auth.trustedProxy.allowLoopback = true` explicite. Les appelants internes sur le même hôte peuvent utiliser `gateway.auth.password` comme repli direct local ; `gateway.auth.token` reste mutuellement exclusif avec le mode trusted-proxy. +- `gateway.auth.allowTailscale` : lorsque `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’auth de Control UI/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison de l’API HTTP n’utilisent **pas** cette auth par en-tête Tailscale ; ils suivent à la place le mode d’auth HTTP normal du Gateway. Ce flux sans jeton suppose que l’hôte du Gateway est fiable. Par défaut à `true` lorsque `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit` : limiteur facultatif des échecs d’auth. S’applique par IP client et par portée d’auth (shared-secret et device-token sont suivis indépendamment). Les tentatives bloquées renvoient `429` + `Retry-After`. + - Sur le chemin async Control UI Tailscale Serve, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives incorrectes simultanées depuis le même client peuvent donc déclencher le limiteur dès la deuxième requête au lieu de passer toutes deux comme de simples incompatibilités. + - `gateway.auth.rateLimit.exemptLoopback` vaut `true` par défaut ; définissez `false` lorsque vous voulez intentionnellement limiter aussi le trafic localhost (pour des configurations de test ou des déploiements proxy stricts). +- Les tentatives d’auth WS d’origine navigateur sont toujours limitées avec l’exemption loopback désactivée (défense en profondeur contre la force brute localhost depuis le navigateur). +- Sur loopback, ces blocages d’origine navigateur sont isolés par valeur `Origin` + normalisée, de sorte que des échecs répétés depuis une origine localhost ne verrouillent pas automatiquement + une origine différente. +- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite auth). +- `controlUi.allowedOrigins` : liste d’autorisation explicite des origines navigateur pour les connexions WebSocket au Gateway. Requis lorsque des clients navigateur sont attendus depuis des origines hors loopback. +- `controlUi.chatMessageMaxWidth` : largeur maximale facultative pour les messages de chat Control UI groupés. Accepte des valeurs de largeur CSS contraintes comme `960px`, `82%`, `min(1280px, 82%)` et `calc(100% - 2rem)`. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le repli d’origine par en-tête Host pour les déploiements qui s’appuient intentionnellement sur une politique d’origine fondée sur l’en-tête Host. - `remote.transport` : `ssh` (par défaut) ou `direct` (ws/wss). Pour `direct`, `remote.url` doit être `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : dérogation d’urgence côté client via l’environnement de processus - qui autorise `ws://` en clair vers des IPs de réseau privé de confiance ; - la valeur par défaut reste loopback-only pour le texte en clair. Il n’existe pas d’équivalent - `openclaw.json`, et la configuration de réseau privé navigateur telle que +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : échappatoire côté client dans l’environnement du processus + qui autorise le `ws://` en texte clair vers des IPs de réseau privé + de confiance ; la valeur par défaut reste limitée au loopback pour le texte clair. Il n’existe pas d’équivalent dans `openclaw.json`, + et la configuration de réseau privé du navigateur comme `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` n’affecte pas les clients WebSocket du Gateway. -- `gateway.remote.token` / `.password` sont des champs d’identifiants du client distant. Ils ne configurent pas l’authentification du Gateway à eux seuls. -- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après qu’ils publient des enregistrements adossés au relais vers le Gateway. Cette URL doit correspondre à l’URL de relais compilée dans le build iOS. -- `gateway.push.apns.relay.timeoutMs` : délai d’expiration d’envoi Gateway-vers-relais en millisecondes. Valeur par défaut : `10000`. -- Les enregistrements adossés au relais sont délégués à une identité de Gateway spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement de relais et transmet au Gateway une autorisation d’envoi limitée à l’enregistrement. Un autre Gateway ne peut pas réutiliser cet enregistrement stocké. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements env temporaires pour la configuration de relais ci-dessus. +- `gateway.remote.token` / `.password` sont des champs d’identifiants client distant. Ils ne configurent pas l’auth du Gateway à eux seuls. +- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après publication des enregistrements adossés au relais vers le Gateway. Cette URL doit correspondre à l’URL du relais compilée dans le build iOS. +- `gateway.push.apns.relay.timeoutMs` : délai d’expiration d’envoi Gateway-vers-relais en millisecondes. Par défaut à `10000`. +- Les enregistrements adossés au relais sont délégués à une identité Gateway spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais et transmet au Gateway une autorisation d’envoi limitée à l’enregistrement. Un autre Gateway ne peut pas réutiliser cet enregistrement stocké. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : surcharges temporaires d’env pour la configuration du relais ci-dessus. - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` : échappatoire réservée au développement pour les URL de relais HTTP loopback. Les URL de relais de production doivent rester en HTTPS. -- `gateway.handshakeTimeoutMs` : délai d’expiration de la négociation WebSocket pré-auth du Gateway en millisecondes. Par défaut : `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` est prioritaire lorsqu’il est défini. Augmentez cette valeur sur les hôtes chargés ou peu puissants où les clients locaux peuvent se connecter alors que le préchauffage du démarrage est encore en cours de stabilisation. +- `gateway.handshakeTimeoutMs` : délai d’expiration de la négociation WebSocket pré-auth du Gateway, en millisecondes. Par défaut : `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` est prioritaire lorsqu’il est défini. Augmentez cette valeur sur des hôtes chargés ou peu puissants lorsque les clients locaux peuvent se connecter alors que le préchauffage du démarrage est encore en cours. - `gateway.channelHealthCheckMinutes` : intervalle du moniteur de santé des canaux en minutes. Définissez `0` pour désactiver globalement les redémarrages du moniteur de santé. Par défaut : `5`. - `gateway.channelStaleEventThresholdMinutes` : seuil de socket obsolète en minutes. Gardez cette valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`. -- `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages du moniteur de santé par canal/compte sur une heure glissante. Par défaut : `10`. -- `channels..healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur de santé tout en gardant le moniteur global activé. -- `channels..accounts..healthMonitor.enabled` : remplacement par compte pour les canaux multi-comptes. Lorsqu’il est défini, il est prioritaire sur le remplacement au niveau du canal. -- Les chemins d’appel du Gateway local peuvent utiliser `gateway.remote.*` comme solution de repli uniquement lorsque `gateway.auth.*` n’est pas défini. -- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en mode fermé (aucune solution de repli distante ne masque l’échec). -- `trustedProxies` : IPs de proxy inverse qui terminent TLS ou injectent des en-têtes de client transféré. Ne listez que les proxys que vous contrôlez. Les entrées loopback restent valides pour les configurations de proxy/détection locale sur le même hôte (par exemple Tailscale Serve ou un proxy inverse local), mais elles ne rendent **pas** les requêtes loopback éligibles à `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback` : lorsque `true`, le Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Valeur par défaut `false` pour un comportement fail-closed. -- `gateway.nodes.pairing.autoApproveCidrs` : liste d’autorisation CIDR/IP optionnelle pour approuver automatiquement le premier appairage d’appareil de nœud sans périmètres demandés. Elle est désactivée lorsqu’elle n’est pas définie. Cela n’approuve pas automatiquement l’appairage opérateur/navigateur/Control UI/WebChat, ni les mises à niveau de rôle, de périmètre, de métadonnées ou de clé publique. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands` : façonnage global allow/deny pour les commandes de nœud déclarées après l’appairage et l’évaluation de la liste d’autorisation de plateforme. Utilisez `allowCommands` pour activer explicitement des commandes de nœud dangereuses telles que `camera.snap`, `camera.clip` et `screen.record` ; `denyCommands` supprime une commande même si une valeur par défaut de plateforme ou une autorisation explicite l’inclurait autrement. Après qu’un nœud a modifié sa liste de commandes déclarées, rejetez puis réapprouvez cet appairage d’appareil afin que le Gateway stocke l’instantané de commandes mis à jour. +- `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages par moniteur de santé, par canal/compte, sur une heure glissante. Par défaut : `10`. +- `channels..healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur de santé tout en conservant le moniteur global activé. +- `channels..accounts..healthMonitor.enabled` : surcharge par compte pour les canaux multi-comptes. Lorsqu’elle est définie, elle prend le pas sur la surcharge au niveau du canal. +- Les chemins d’appel Gateway locaux peuvent utiliser `gateway.remote.*` comme repli uniquement lorsque `gateway.auth.*` n’est pas défini. +- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en fermeture sécurisée (aucun masquage par repli distant). +- `trustedProxies` : IPs de reverse proxy qui terminent TLS ou injectent des en-têtes de client transférés. Ne listez que les proxies que vous contrôlez. Les entrées loopback restent valides pour les configurations proxy/détection locale sur le même hôte (par exemple Tailscale Serve ou un reverse proxy local), mais elles ne rendent **pas** les requêtes loopback éligibles à `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback` : lorsque `true`, le Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Valeur par défaut `false` pour un comportement fermé en cas d’échec. +- `gateway.nodes.pairing.autoApproveCidrs` : liste d’autorisation CIDR/IP facultative pour approuver automatiquement le premier appairage d’un appareil Node sans portées demandées. Elle est désactivée lorsqu’elle n’est pas définie. Cela n’approuve pas automatiquement l’appairage opérateur/navigateur/Control UI/WebChat, ni les mises à niveau de rôle, de portée, de métadonnées ou de clé publique. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands` : façonnage global autoriser/refuser pour les commandes Node déclarées après l’appairage et l’évaluation de la liste d’autorisation de plateforme. Utilisez `allowCommands` pour opter pour des commandes Node dangereuses comme `camera.snap`, `camera.clip` et `screen.record` ; `denyCommands` supprime une commande même si une valeur par défaut de plateforme ou une autorisation explicite l’inclurait autrement. Après qu’un Node modifie sa liste de commandes déclarées, rejetez puis réapprouvez l’appairage de cet appareil afin que le Gateway stocke l’instantané de commandes mis à jour. - `gateway.tools.deny` : noms d’outils supplémentaires bloqués pour HTTP `POST /tools/invoke` (étend la liste de refus par défaut). -- `gateway.tools.allow` : supprime des noms d’outils de la liste de refus HTTP par défaut. +- `gateway.tools.allow` : retire des noms d’outils de la liste de refus HTTP par défaut. @@ -487,18 +485,18 @@ Consultez [Engagements inférés](/fr/concepts/commitments). - Chat Completions : désactivé par défaut. Activez avec `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API : `gateway.http.endpoints.responses.enabled`. -- Renforcement des entrées URL de Responses : +- Durcissement des entrées URL Responses : - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Les listes d’autorisation vides sont traitées comme non définies ; utilisez `gateway.http.endpoints.responses.files.allowUrl=false` et/ou `gateway.http.endpoints.responses.images.allowUrl=false` pour désactiver la récupération d’URL. -- En-tête optionnel de renforcement des réponses : +- En-tête facultatif de durcissement des réponses : - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour les origines HTTPS que vous contrôlez ; voir [Auth par proxy de confiance](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolation multi-instance -Exécutez plusieurs Gateways sur un même hôte avec des ports et répertoires d’état uniques : +Exécutez plusieurs Gateway sur un même hôte avec des ports et répertoires d’état uniques : ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -506,9 +504,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). +Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + le port `19001`), `--profile ` (utilise `~/.openclaw-`). -Voir [Gateways multiples](/fr/gateway/multiple-gateways). +Voir [Plusieurs Gateway](/fr/gateway/multiple-gateways). ### `gateway.tls` @@ -526,11 +524,11 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). } ``` -- `enabled` : active la terminaison TLS au niveau de l’écouteur du Gateway (HTTPS/WSS) (par défaut : `false`). -- `autoGenerate` : génère automatiquement une paire cert/key locale auto-signée lorsque les fichiers explicites ne sont pas configurés ; à utiliser uniquement en local/dev. +- `enabled` : active la terminaison TLS sur l’écouteur du Gateway (HTTPS/WSS) (par défaut : `false`). +- `autoGenerate` : génère automatiquement une paire cert/key locale auto-signée lorsque des fichiers explicites ne sont pas configurés ; réservé à un usage local/dev. - `certPath` : chemin du système de fichiers vers le fichier de certificat TLS. -- `keyPath` : chemin du système de fichiers vers le fichier de clé privée TLS ; gardez des permissions restreintes. -- `caPath` : chemin optionnel vers le bundle CA pour la vérification client ou les chaînes de confiance personnalisées. +- `keyPath` : chemin du système de fichiers vers le fichier de clé privée TLS ; gardez les permissions restreintes. +- `caPath` : chemin facultatif vers le bundle CA pour la vérification client ou les chaînes de confiance personnalisées. ### `gateway.reload` @@ -546,13 +544,13 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). } ``` -- `mode` : contrôle la manière dont les modifications de configuration sont appliquées à l’exécution. +- `mode` : contrôle la façon dont les modifications de configuration sont appliquées à l’exécution. - `"off"` : ignore les modifications live ; les changements nécessitent un redémarrage explicite. - `"restart"` : redémarre toujours le processus Gateway lors d’un changement de configuration. - - `"hot"` : applique les changements dans le processus sans redémarrer. - - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; revient au redémarrage si nécessaire. -- `debounceMs` : fenêtre de debounce en ms avant application des changements de configuration (entier non négatif). -- `deferralTimeoutMs` : temps maximal optionnel en ms à attendre pour les opérations en cours avant de forcer un redémarrage. Omettez-le pour utiliser l’attente bornée par défaut (`300000`) ; définissez `0` pour attendre indéfiniment et journaliser périodiquement des avertissements indiquant que des opérations sont encore en attente. + - `"hot"` : applique les changements dans le processus sans redémarrage. + - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; se rabat sur un redémarrage si nécessaire. +- `debounceMs` : fenêtre de debounce en ms avant l’application des changements de configuration (entier non négatif). +- `deferralTimeoutMs` : durée maximale facultative en ms à attendre pour les opérations en cours avant de forcer un redémarrage. Omettez-la pour utiliser l’attente bornée par défaut (`300000`) ; définissez `0` pour attendre indéfiniment et journaliser périodiquement des avertissements encore en attente. --- @@ -589,39 +587,39 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). } ``` -Auth : `Authorization: Bearer ` ou `x-openclaw-token: `. +Authentification : `Authorization: Bearer ` ou `x-openclaw-token: `. Les jetons de hook dans la chaîne de requête sont rejetés. Notes de validation et de sécurité : - `hooks.enabled=true` nécessite un `hooks.token` non vide. - `hooks.token` doit être **distinct** de `gateway.auth.token` ; la réutilisation du jeton du Gateway est rejetée. -- `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié tel que `/hooks`. +- `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié comme `/hooks`. - Si `hooks.allowRequestSessionKey=true`, limitez `hooks.allowedSessionKeyPrefixes` (par exemple `["hook:"]`). -- Si un mappage ou un préréglage utilise une `sessionKey` basée sur un modèle, définissez `hooks.allowedSessionKeyPrefixes` et `hooks.allowRequestSessionKey=true`. Les clés de mappage statiques ne nécessitent pas cette activation explicite. +- Si un mappage ou un préréglage utilise un `sessionKey` à modèle, définissez `hooks.allowedSessionKeyPrefixes` et `hooks.allowRequestSessionKey=true`. Les clés de mappage statiques ne nécessitent pas cette activation explicite. **Points de terminaison :** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` issue de la charge utile de la requête n’est acceptée que lorsque `hooks.allowRequestSessionKey=true` (par défaut : `false`). + - Le `sessionKey` de la charge utile de la requête n’est accepté que lorsque `hooks.allowRequestSessionKey=true` (valeur par défaut : `false`). - `POST /hooks/` → résolu via `hooks.mappings` - - Les valeurs `sessionKey` de mappage rendues par modèle sont traitées comme fournies de l’extérieur et nécessitent aussi `hooks.allowRequestSessionKey=true`. + - Les valeurs de `sessionKey` de mappage rendues à partir d’un modèle sont traitées comme fournies de l’extérieur et nécessitent aussi `hooks.allowRequestSessionKey=true`. -- `match.path` correspond au sous-chemin après `/hooks` (par ex. `/hooks/gmail` → `gmail`). +- `match.path` correspond au sous-chemin après `/hooks` (p. ex. `/hooks/gmail` → `gmail`). - `match.source` correspond à un champ de charge utile pour les chemins génériques. - Les modèles comme `{{messages[0].subject}}` lisent depuis la charge utile. - `transform` peut pointer vers un module JS/TS qui renvoie une action de hook. - - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et les traversées sont rejetés). - - Gardez `hooks.transformsDir` sous `~/.openclaw/hooks/transforms` ; les répertoires de Skills de l’espace de travail sont rejetés. Si `openclaw doctor` signale ce chemin comme invalide, déplacez le module de transformation dans le répertoire des transformations de hooks ou supprimez `hooks.transformsDir`. -- `agentId` achemine vers un agent spécifique ; les identifiants inconnus reviennent à la valeur par défaut. -- `allowedAgentIds` : restreint le routage explicite (`*` ou omis = tout autoriser, `[]` = tout refuser). + - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et la traversée sont rejetés). + - Gardez `hooks.transformsDir` sous `~/.openclaw/hooks/transforms` ; les répertoires Skills de l’espace de travail sont rejetés. Si `openclaw doctor` signale ce chemin comme invalide, déplacez le module de transformation dans le répertoire des transformations de hooks ou supprimez `hooks.transformsDir`. +- `agentId` route vers un agent spécifique ; les ID inconnus reviennent à la valeur par défaut. +- `allowedAgentIds` : limite le routage explicite (`*` ou omis = tout autoriser, `[]` = tout refuser). - `defaultSessionKey` : clé de session fixe facultative pour les exécutions d’agent de hook sans `sessionKey` explicite. -- `allowRequestSessionKey` : autorise les appelants de `/hooks/agent` et les clés de session de mappage pilotées par modèle à définir `sessionKey` (par défaut : `false`). -- `allowedSessionKeyPrefixes` : liste d’autorisation facultative de préfixes pour les valeurs `sessionKey` explicites (requête + mappage), par ex. `["hook:"]`. Elle devient obligatoire lorsqu’un mappage ou un préréglage utilise une `sessionKey` basée sur un modèle. -- `deliver: true` envoie la réponse finale à un canal ; `channel` vaut `last` par défaut. +- `allowRequestSessionKey` : autorise les appelants de `/hooks/agent` et les clés de session de mappage pilotées par modèle à définir `sessionKey` (valeur par défaut : `false`). +- `allowedSessionKeyPrefixes` : liste d’autorisation facultative de préfixes pour les valeurs explicites de `sessionKey` (requête + mappage), p. ex. `["hook:"]`. Elle devient obligatoire lorsqu’un mappage ou un préréglage utilise un `sessionKey` à modèle. +- `deliver: true` envoie la réponse finale à un canal ; `channel` utilise `last` par défaut. - `model` remplace le LLM pour cette exécution de hook (doit être autorisé si le catalogue de modèles est défini). @@ -630,7 +628,7 @@ Notes de validation et de sécurité : - Le préréglage Gmail intégré utilise `sessionKey: "hook:gmail:{{messages[0].id}}"`. - Si vous conservez ce routage par message, définissez `hooks.allowRequestSessionKey: true` et limitez `hooks.allowedSessionKeyPrefixes` pour correspondre à l’espace de noms Gmail, par exemple `["hook:", "hook:gmail:"]`. -- Si vous avez besoin de `hooks.allowRequestSessionKey: false`, remplacez le préréglage par une `sessionKey` statique au lieu de la valeur par défaut basée sur un modèle. +- Si vous avez besoin de `hooks.allowRequestSessionKey: false`, remplacez le préréglage par un `sessionKey` statique au lieu de la valeur par défaut à modèle. ```json5 { @@ -658,7 +656,7 @@ Notes de validation et de sécurité : --- -## Hôte de canevas +## Hôte Canvas ```json5 { @@ -673,13 +671,13 @@ Notes de validation et de sécurité : - Sert les fichiers HTML/CSS/JS modifiables par l’agent et A2UI via HTTP sous le port du Gateway : - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Local uniquement : conservez `gateway.bind: "loopback"` (par défaut). -- Liaisons non loopback : les routes du canevas nécessitent l’authentification du Gateway (jeton/mot de passe/proxy de confiance), comme les autres surfaces HTTP du Gateway. -- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; une fois qu’un Node est appairé et connecté, le Gateway annonce des URL de capacité propres au Node pour l’accès au canevas/A2UI. +- Local uniquement : gardez `gateway.bind: "loopback"` (valeur par défaut). +- Liaisons non loopback : les routes canvas nécessitent l’authentification Gateway (jeton/mot de passe/proxy de confiance), comme les autres surfaces HTTP du Gateway. +- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; après l’appairage et la connexion d’un Node, le Gateway annonce des URL de capacité limitées au Node pour l’accès canvas/A2UI. - Les URL de capacité sont liées à la session WS active du Node et expirent rapidement. Aucun repli fondé sur l’adresse IP n’est utilisé. - Injecte le client de rechargement à chaud dans le HTML servi. -- Crée automatiquement un `index.html` de départ lorsqu’il est vide. -- Sert également A2UI à l’emplacement `/__openclaw__/a2ui/`. +- Crée automatiquement un `index.html` de démarrage lorsqu’il est vide. +- Sert aussi A2UI à `/__openclaw__/a2ui/`. - Les changements nécessitent un redémarrage du Gateway. - Désactivez le rechargement à chaud pour les grands répertoires ou les erreurs `EMFILE`. @@ -699,11 +697,11 @@ Notes de validation et de sécurité : } ``` -- `minimal` (par défaut lorsque le Plugin `bonjour` fourni est activé) : omettre `cliPath` + `sshPort` des enregistrements TXT. -- `full` : inclure `cliPath` + `sshPort` ; l’annonce multicast LAN nécessite toujours que le Plugin `bonjour` fourni soit activé. -- `off` : supprime l’annonce multicast LAN sans modifier l’activation du Plugin. -- Le Plugin `bonjour` fourni démarre automatiquement sur les hôtes macOS et est optionnel sur Linux, Windows et les déploiements Gateway conteneurisés. -- Le nom d’hôte utilise par défaut le nom d’hôte du système lorsqu’il s’agit d’une étiquette DNS valide, avec repli sur `openclaw`. Remplacez-le avec `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (valeur par défaut lorsque le plugin `bonjour` intégré est activé) : omet `cliPath` + `sshPort` des enregistrements TXT. +- `full` : inclut `cliPath` + `sshPort` ; l’annonce multicast LAN nécessite toujours que le plugin `bonjour` intégré soit activé. +- `off` : supprime l’annonce multicast LAN sans changer l’activation du plugin. +- Le plugin `bonjour` intégré démarre automatiquement sur les hôtes macOS et est optionnel sur Linux, Windows et les déploiements Gateway conteneurisés. +- Le nom d’hôte utilise par défaut le nom d’hôte système lorsqu’il s’agit d’une étiquette DNS valide, avec repli sur `openclaw`. Remplacez-le avec `OPENCLAW_MDNS_HOSTNAME`. ### Zone étendue (DNS-SD) @@ -741,7 +739,7 @@ Configuration : `openclaw dns setup --apply`. ``` - Les variables d’environnement en ligne ne sont appliquées que si l’environnement du processus ne contient pas la clé. -- Fichiers `.env` : `.env` du CWD + `~/.openclaw/.env` (aucun des deux ne remplace les variables existantes). +- Fichiers `.env` : `.env` du CWD + `~/.openclaw/.env` (aucun ne remplace les variables existantes). - `shellEnv` : importe les clés attendues manquantes depuis le profil de votre shell de connexion. - Consultez [Environnement](/fr/help/environment) pour la précédence complète. @@ -758,15 +756,15 @@ Référencez des variables d’environnement dans n’importe quelle chaîne de ``` - Seuls les noms en majuscules correspondent : `[A-Z_][A-Z0-9_]*`. -- Les variables manquantes ou vides déclenchent une erreur au chargement de la configuration. -- Échappez avec `$${VAR}` pour un `${VAR}` littéral. +- Les variables manquantes/vides déclenchent une erreur au chargement de la configuration. +- Échappez avec `$${VAR}` pour obtenir un `${VAR}` littéral. - Fonctionne avec `$include`. --- ## Secrets -Les références de secret sont additives : les valeurs en texte brut fonctionnent toujours. +Les références de secrets sont additives : les valeurs en texte brut fonctionnent toujours. ### `SecretRef` @@ -778,11 +776,11 @@ Utilisez une forme d’objet : Validation : -- motif `provider` : `^[a-z][a-z0-9_-]{0,63}$` -- motif d’id pour `source: "env"` : `^[A-Z][A-Z0-9_]{0,127}$` -- id pour `source: "file"` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) -- motif d’id pour `source: "exec"` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- les ids `source: "exec"` ne doivent pas contenir de segments de chemin délimités par des barres obliques `.` ou `..` (par exemple, `a/../b` est rejeté) +- motif de `provider` : `^[a-z][a-z0-9_-]{0,63}$` +- motif d’identifiant pour `source: "env"` : `^[A-Z][A-Z0-9_]{0,127}$` +- identifiant pour `source: "file"` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) +- motif d’identifiant pour `source: "exec"` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- les identifiants `source: "exec"` ne doivent pas contenir de segments de chemin délimités par des barres obliques `.` ou `..` (par exemple `a/../b` est rejeté) ### Surface d’identifiants prise en charge @@ -821,13 +819,13 @@ Validation : Notes : - Le fournisseur `file` prend en charge `mode: "json"` et `mode: "singleValue"` (`id` doit être `"value"` en mode singleValue). -- Les chemins des fournisseurs file et exec échouent de manière fermée lorsque la vérification des ACL Windows n’est pas disponible. Définissez `allowInsecurePath: true` uniquement pour les chemins de confiance qui ne peuvent pas être vérifiés. +- Les chemins des fournisseurs file et exec échouent de manière fermée lorsque la vérification ACL Windows n’est pas disponible. Définissez `allowInsecurePath: true` uniquement pour les chemins de confiance qui ne peuvent pas être vérifiés. - Le fournisseur `exec` exige un chemin `command` absolu et utilise des charges utiles de protocole sur stdin/stdout. -- Par défaut, les chemins de commande sous forme de lien symbolique sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins de lien symbolique tout en validant le chemin cible résolu. -- Si `trustedDirs` est configuré, la vérification du répertoire de confiance s’applique au chemin cible résolu. +- Par défaut, les chemins de commande symboliques sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symboliques tout en validant le chemin cible résolu. +- Si `trustedDirs` est configuré, la vérification des répertoires de confiance s’applique au chemin cible résolu. - L’environnement enfant `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. -- Les références de secret sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête lisent uniquement cet instantané. -- Le filtrage de surface active s’applique pendant l’activation : les références non résolues sur les surfaces activées font échouer le démarrage ou le rechargement, tandis que les surfaces inactives sont ignorées avec des diagnostics. +- Les références de secrets sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête ne lisent que cet instantané. +- Le filtrage de la surface active s’applique pendant l’activation : les références non résolues sur les surfaces activées font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec des diagnostics. --- @@ -851,12 +849,12 @@ Notes : - Les profils par agent sont stockés dans `/auth-profiles.json`. - `auth-profiles.json` prend en charge les références au niveau des valeurs (`keyRef` pour `api_key`, `tokenRef` pour `token`) pour les modes d’identifiants statiques. -- Les anciens mappages plats `auth-profiles.json`, tels que `{ "provider": { "apiKey": "..." } }`, ne sont pas un format d’exécution ; `openclaw doctor --fix` les réécrit en profils de clé API canoniques `provider:default` avec une sauvegarde `.legacy-flat.*.bak`. -- Les profils en mode OAuth (`auth.profiles..mode = "oauth"`) ne prennent pas en charge les identifiants de profil d’authentification basés sur SecretRef. -- Les identifiants statiques d’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. +- Les anciennes cartes plates `auth-profiles.json`, telles que `{ "provider": { "apiKey": "..." } }`, ne sont pas un format d’exécution ; `openclaw doctor --fix` les réécrit en profils de clé API canoniques `provider:default` avec une sauvegarde `.legacy-flat.*.bak`. +- Les profils en mode OAuth (`auth.profiles..mode = "oauth"`) ne prennent pas en charge les identifiants de profil d’authentification adossés à SecretRef. +- Les identifiants d’exécution statiques proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. - Les anciens imports OAuth proviennent de `~/.openclaw/credentials/oauth.json`. - Consultez [OAuth](/fr/concepts/oauth). -- Comportement d’exécution des secrets et outillage `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). +- Comportement d’exécution des secrets et outils `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). ### `auth.cooldowns` @@ -878,15 +876,15 @@ Notes : } ``` -- `billingBackoffHours` : délai d’attente de base en heures lorsqu’un profil échoue en raison de véritables erreurs de facturation/crédit insuffisant (par défaut : `5`). Un texte explicite de facturation peut tout de même arriver ici même sur des réponses `401`/`403`, mais les correspondances de texte propres à un fournisseur restent limitées au fournisseur qui les possède (par exemple OpenRouter `Key limit exceeded`). Les messages HTTP `402` réessayables de fenêtre d’usage ou de limite de dépenses d’organisation/espace de travail restent plutôt dans le chemin `rate_limit`. +- `billingBackoffHours` : délai d’attente exponentiel de base en heures lorsqu’un profil échoue à cause de véritables erreurs de facturation/crédit insuffisant (par défaut : `5`). Le texte explicite de facturation peut toujours arriver ici, même sur les réponses `401`/`403`, mais les correspondances de texte propres au fournisseur restent limitées au fournisseur qui les possède (par exemple OpenRouter `Key limit exceeded`). Les messages HTTP `402` réessayables liés à la fenêtre d’utilisation ou aux limites de dépenses de l’organisation/de l’espace de travail restent plutôt dans le chemin `rate_limit`. - `billingBackoffHoursByProvider` : remplacements facultatifs par fournisseur pour les heures de délai d’attente de facturation. - `billingMaxHours` : plafond en heures pour la croissance exponentielle du délai d’attente de facturation (par défaut : `24`). -- `authPermanentBackoffMinutes` : délai d’attente de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`). +- `authPermanentBackoffMinutes` : délai d’attente de base en minutes pour les échecs `auth_permanent` à haut niveau de confiance (par défaut : `10`). - `authPermanentMaxMinutes` : plafond en minutes pour la croissance du délai d’attente `auth_permanent` (par défaut : `60`). - `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de délai d’attente (par défaut : `24`). - `overloadedProfileRotations` : nombre maximal de rotations de profils d’authentification du même fournisseur pour les erreurs de surcharge avant de basculer vers le repli de modèle (par défaut : `1`). Les formes indiquant un fournisseur occupé, comme `ModelNotReadyException`, arrivent ici. - `overloadedBackoffMs` : délai fixe avant de réessayer une rotation de fournisseur/profil surchargé (par défaut : `0`). -- `rateLimitedProfileRotations` : nombre maximal de rotations de profils d’authentification du même fournisseur pour les erreurs de limite de débit avant de basculer vers le repli de modèle (par défaut : `1`). Ce compartiment de limite de débit inclut du texte façonné par les fournisseurs, comme `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. +- `rateLimitedProfileRotations` : nombre maximal de rotations de profils d’authentification du même fournisseur pour les erreurs de limite de débit avant de basculer vers le repli de modèle (par défaut : `1`). Ce compartiment de limite de débit inclut du texte façonné par le fournisseur comme `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. --- @@ -909,7 +907,7 @@ Notes : - Définissez `logging.file` pour un chemin stable. - `consoleLevel` passe à `debug` avec `--verbose`. - `maxFileBytes` : taille maximale du fichier journal actif en octets avant rotation (entier positif ; par défaut : `104857600` = 100 Mo). OpenClaw conserve jusqu’à cinq archives numérotées à côté du fichier actif. -- `redactSensitive` / `redactPatterns` : masquage au mieux pour la sortie console, les journaux de fichiers, les enregistrements de journaux OTLP et le texte persistant des transcriptions de session. `redactSensitive: "off"` ne désactive que cette politique générale de journaux/transcriptions ; les surfaces de sécurité de l’interface, des outils et des diagnostics continuent de masquer les secrets avant émission. +- `redactSensitive` / `redactPatterns` : masquage au mieux pour la sortie console, les journaux de fichier, les enregistrements de journal OTLP et le texte persistant des transcriptions de session. `redactSensitive: "off"` désactive uniquement cette politique générale de journaux/transcriptions ; les surfaces de sécurité UI/outils/diagnostics masquent toujours les secrets avant émission. --- @@ -921,6 +919,7 @@ Notes : enabled: true, flags: ["telegram.*"], stuckSessionWarnMs: 30000, + stuckSessionAbortMs: 600000, otel: { enabled: false, @@ -959,21 +958,22 @@ Notes : - `enabled` : interrupteur principal pour la sortie d’instrumentation (par défaut : `true`). - `flags` : tableau de chaînes d’indicateurs activant une sortie de journal ciblée (prend en charge les jokers comme `"telegram.*"` ou `"*"`). -- `stuckSessionWarnMs` : seuil d’âge sans progression en ms pour classer les sessions de traitement de longue durée comme `session.long_running`, `session.stalled` ou `session.stuck`. Les réponses, outils, statuts, blocs et la progression ACP réinitialisent le minuteur ; les diagnostics `session.stuck` répétés augmentent leur délai tant qu’ils restent inchangés. +- `stuckSessionWarnMs` : seuil d’âge sans progression en ms pour classer les sessions de traitement longues comme `session.long_running`, `session.stalled` ou `session.stuck`. Les réponses, outils, statuts, blocs et la progression ACP réinitialisent le minuteur ; les diagnostics `session.stuck` répétés reculent tant que rien ne change. +- `stuckSessionAbortMs` : seuil d’âge sans progression en ms avant que le travail actif bloqué admissible puisse être vidé par abandon pour récupération. S’il n’est pas défini, OpenClaw utilise la fenêtre d’exécution intégrée étendue plus sûre d’au moins 10 minutes et 5 fois `stuckSessionWarnMs`. - `otel.enabled` : active le pipeline d’export OpenTelemetry (par défaut : `false`). Pour la configuration complète, le catalogue des signaux et le modèle de confidentialité, consultez [Export OpenTelemetry](/fr/gateway/opentelemetry). - `otel.endpoint` : URL du collecteur pour l’export OTel. -- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint` : points de terminaison OTLP facultatifs propres à un signal. Lorsqu’ils sont définis, ils remplacent `otel.endpoint` uniquement pour ce signal. +- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint` : points de terminaison OTLP facultatifs propres au signal. Lorsqu’ils sont définis, ils remplacent `otel.endpoint` uniquement pour ce signal. - `otel.protocol` : `"http/protobuf"` (par défaut) ou `"grpc"`. - `otel.headers` : en-têtes de métadonnées HTTP/gRPC supplémentaires envoyés avec les requêtes d’export OTel. - `otel.serviceName` : nom du service pour les attributs de ressource. -- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export des traces, métriques ou journaux. +- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export de traces, de métriques ou de journaux. - `otel.sampleRate` : taux d’échantillonnage des traces `0`–`1`. -- `otel.flushIntervalMs` : intervalle périodique de vidage de la télémétrie en ms. -- `otel.captureContent` : capture de contenu brut avec consentement explicite pour les attributs de spans OTEL. Désactivé par défaut. Le booléen `true` capture le contenu non système des messages/outils ; la forme objet permet d’activer explicitement `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` et `systemPrompt`. -- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` : interrupteur d’environnement pour les derniers attributs expérimentaux de fournisseur de spans GenAI. Par défaut, les spans conservent l’attribut historique `gen_ai.system` pour la compatibilité ; les métriques GenAI utilisent des attributs sémantiques bornés. +- `otel.flushIntervalMs` : intervalle de vidage périodique de la télémétrie en ms. +- `otel.captureContent` : capture optionnelle du contenu brut pour les attributs d’étendue OTEL. Désactivée par défaut. Le booléen `true` capture le contenu non système des messages/outils ; la forme objet vous permet d’activer explicitement `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` et `systemPrompt`. +- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` : interrupteur d’environnement pour les derniers attributs expérimentaux de fournisseur d’étendues GenAI. Par défaut, les étendues conservent l’attribut hérité `gen_ai.system` pour la compatibilité ; les métriques GenAI utilisent des attributs sémantiques bornés. - `OPENCLAW_OTEL_PRELOADED=1` : interrupteur d’environnement pour les hôtes qui ont déjà enregistré un SDK OpenTelemetry global. OpenClaw ignore alors le démarrage/l’arrêt du SDK possédé par le plugin tout en gardant les écouteurs de diagnostics actifs. -- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` et `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` : variables d’environnement de points de terminaison propres à un signal, utilisées lorsque la clé de configuration correspondante n’est pas définie. -- `cacheTrace.enabled` : journalise des instantanés de trace de cache pour les exécutions intégrées (par défaut : `false`). +- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` et `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` : variables d’environnement de point de terminaison propres au signal, utilisées lorsque la clé de configuration correspondante n’est pas définie. +- `cacheTrace.enabled` : journalise les instantanés de trace de cache pour les exécutions intégrées (par défaut : `false`). - `cacheTrace.filePath` : chemin de sortie pour le JSONL de trace de cache (par défaut : `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem` : contrôlent ce qui est inclus dans la sortie de trace de cache (tous par défaut : `true`). @@ -998,11 +998,11 @@ Notes : ``` - `channel` : canal de publication pour les installations npm/git — `"stable"`, `"beta"` ou `"dev"`. -- `checkOnStart` : vérifie les mises à jour npm au démarrage du Gateway (par défaut : `true`). -- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de packages (par défaut : `false`). -- `auto.stableDelayHours` : délai minimal en heures avant application automatique sur le canal stable (par défaut : `6` ; max. : `168`). +- `checkOnStart` : recherche les mises à jour npm au démarrage du Gateway (par défaut : `true`). +- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de paquet (par défaut : `false`). +- `auto.stableDelayHours` : délai minimal en heures avant l’application automatique sur le canal stable (par défaut : `6` ; max. : `168`). - `auto.stableJitterHours` : fenêtre supplémentaire de répartition du déploiement du canal stable en heures (par défaut : `12` ; max. : `168`). -- `auto.betaCheckIntervalHours` : fréquence des vérifications du canal bêta, en heures (par défaut : `1` ; max. : `24`). +- `auto.betaCheckIntervalHours` : fréquence des vérifications du canal bêta en heures (par défaut : `1` ; max. : `24`). --- @@ -1035,22 +1035,22 @@ Notes : } ``` -- `enabled` : garde-fou global de la fonctionnalité ACP (par défaut : `true` ; définissez `false` pour masquer les possibilités de dispatch et de spawn ACP). -- `dispatch.enabled` : garde-fou indépendant pour le dispatch des tours de session ACP (par défaut : `true`). Définissez `false` pour garder les commandes ACP disponibles tout en bloquant l’exécution. -- `backend` : id du backend d’exécution ACP par défaut (doit correspondre à un plugin d’exécution ACP enregistré). - Installez d’abord le plugin de backend et, si `plugins.allow` est défini, incluez l’id du plugin de backend (par exemple `acpx`), sinon le backend ACP ne se chargera pas. -- `defaultAgent` : id d’agent cible ACP de repli lorsque les spawns ne spécifient pas de cible explicite. -- `allowedAgents` : liste d’autorisation des ids d’agents permis pour les sessions d’exécution ACP ; vide signifie aucune restriction supplémentaire. +- `enabled` : garde globale de fonctionnalité ACP (par défaut : `true` ; définissez `false` pour masquer la répartition ACP et les affordances de création). +- `dispatch.enabled` : garde indépendante pour la répartition des tours de session ACP (par défaut : `true`). Définissez `false` pour garder les commandes ACP disponibles tout en bloquant l’exécution. +- `backend` : identifiant du backend d’exécution ACP par défaut (doit correspondre à un plugin d’exécution ACP enregistré). + Installez d’abord le plugin backend et, si `plugins.allow` est défini, incluez l’identifiant du plugin backend (par exemple `acpx`) ou le backend ACP ne se chargera pas. +- `defaultAgent` : identifiant d’agent cible ACP de repli lorsque les créations ne spécifient pas de cible explicite. +- `allowedAgents` : liste d’autorisation des identifiants d’agents permis pour les sessions d’exécution ACP ; vide signifie aucune restriction supplémentaire. - `maxConcurrentSessions` : nombre maximal de sessions ACP actives simultanément. -- `stream.coalesceIdleMs` : fenêtre de vidage en cas d’inactivité, en ms, pour le texte diffusé. -- `stream.maxChunkChars` : taille maximale d’un segment avant découpage de la projection de bloc diffusée. +- `stream.coalesceIdleMs` : fenêtre de vidage au repos en ms pour le texte diffusé. +- `stream.maxChunkChars` : taille maximale de fragment avant découpage de la projection de bloc diffusé. - `stream.repeatSuppression` : supprime les lignes de statut/outil répétées par tour (par défaut : `true`). -- `stream.deliveryMode` : `"live"` diffuse incrémentalement ; `"final_only"` met en mémoire tampon jusqu’aux événements terminaux du tour. -- `stream.hiddenBoundarySeparator` : séparateur avant le texte visible après des événements d’outils masqués (par défaut : `"paragraph"`). -- `stream.maxOutputChars` : nombre maximal de caractères de sortie d’assistant projetés par tour ACP. -- `stream.maxSessionUpdateChars` : nombre maximal de caractères pour les lignes projetées de statut/mise à jour ACP. +- `stream.deliveryMode` : `"live"` diffuse progressivement ; `"final_only"` met en mémoire tampon jusqu’aux événements terminaux du tour. +- `stream.hiddenBoundarySeparator` : séparateur avant le texte visible après des événements d’outil masqués (par défaut : `"paragraph"`). +- `stream.maxOutputChars` : nombre maximal de caractères de sortie assistant projetés par tour ACP. +- `stream.maxSessionUpdateChars` : nombre maximal de caractères pour les lignes de statut/mise à jour ACP projetées. - `stream.tagVisibility` : enregistrement des noms de balises vers des remplacements booléens de visibilité pour les événements diffusés. -- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant qu’ils soient éligibles au nettoyage. +- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant nettoyage admissible. - `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement d’exécution ACP. --- @@ -1067,11 +1067,11 @@ Notes : } ``` -- `cli.banner.taglineMode` contrôle le style du slogan de bannière : - - `"random"` (par défaut) : slogans amusants/saisonniers en rotation. +- `cli.banner.taglineMode` contrôle le style de slogan de la bannière : + - `"random"` (par défaut) : slogans tournants amusants/saisonniers. - `"default"` : slogan neutre fixe (`All your chats, one OpenClaw.`). - `"off"` : aucun texte de slogan (le titre/la version de la bannière restent affichés). -- Pour masquer toute la bannière (pas seulement les slogans), définissez l’environnement `OPENCLAW_HIDE_BANNER=1`. +- Pour masquer toute la bannière (pas seulement les slogans), définissez l’env `OPENCLAW_HIDE_BANNER=1`. --- @@ -1095,7 +1095,7 @@ Métadonnées écrites par les flux de configuration guidée de la CLI (`onboard ## Identité -Voir les champs d’identité `agents.list` sous [Valeurs par défaut des agents](/fr/gateway/config-agents#agent-defaults). +Consultez les champs d’identité `agents.list` sous [Valeurs par défaut de l’agent](/fr/gateway/config-agents#agent-defaults). --- @@ -1103,7 +1103,7 @@ Voir les champs d’identité `agents.list` sous [Valeurs par défaut des agents Les builds actuels n’incluent plus le pont TCP. Les Nodes se connectent via le WebSocket du Gateway. Les clés `bridge.*` ne font plus partie du schéma de configuration (la validation échoue jusqu’à leur suppression ; `openclaw doctor --fix` peut retirer les clés inconnues). - + ```json { @@ -1141,11 +1141,11 @@ Les builds actuels n’incluent plus le pont TCP. Les Nodes se connectent via le } ``` -- `sessionRetention` : durée de conservation des sessions d’exécutions cron isolées terminées avant élagage depuis `sessions.json`. Contrôle aussi le nettoyage des transcriptions cron supprimées archivées. Par défaut : `24h` ; définissez `false` pour désactiver. -- `runLog.maxBytes` : taille maximale par fichier journal d’exécution (`cron/runs/.jsonl`) avant élagage. Par défaut : `2_000_000` octets. -- `runLog.keepLines` : lignes les plus récentes conservées lorsque l’élagage du journal d’exécution est déclenché. Par défaut : `2000`. -- `webhookToken` : jeton bearer utilisé pour la livraison POST du Webhook Cron (`delivery.mode = "webhook"`), si omis aucun en-tête d’authentification n’est envoyé. -- `webhook` : URL Webhook héritée de repli obsolète (http/https) utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. +- `sessionRetention`: durée pendant laquelle conserver les sessions d’exécution Cron isolées terminées avant leur suppression de `sessions.json`. Contrôle aussi le nettoyage des transcriptions Cron supprimées archivées. Par défaut : `24h`; définissez sur `false` pour désactiver. +- `runLog.maxBytes`: taille maximale par fichier de journal d’exécution (`cron/runs/.jsonl`) avant suppression. Par défaut : `2_000_000` octets. +- `runLog.keepLines`: lignes les plus récentes conservées lorsque la suppression du journal d’exécution est déclenchée. Par défaut : `2000`. +- `webhookToken`: jeton bearer utilisé pour la livraison POST du Webhook Cron (`delivery.mode = "webhook"`); s’il est omis, aucun en-tête d’authentification n’est envoyé. +- `webhook`: URL Webhook de secours héritée obsolète (http/https) utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. ### `cron.retry` @@ -1161,9 +1161,9 @@ Les builds actuels n’incluent plus le pont TCP. Les Nodes se connectent via le } ``` -- `maxAttempts` : nombre maximal de nouvelles tentatives pour les tâches ponctuelles en cas d’erreurs transitoires (par défaut : `3` ; plage : `0`–`10`). -- `backoffMs` : tableau des délais d’attente en ms pour chaque nouvelle tentative (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). -- `retryOn` : types d’erreurs qui déclenchent de nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez ce champ pour réessayer tous les types transitoires. +- `maxAttempts`: nombre maximal de nouvelles tentatives pour les tâches ponctuelles en cas d’erreurs transitoires (par défaut : `3`; plage : `0`–`10`). +- `backoffMs`: tableau de délais d’attente en ms pour chaque nouvelle tentative (par défaut : `[30000, 60000, 300000]`; 1 à 10 entrées). +- `retryOn`: types d’erreurs qui déclenchent de nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez ce champ pour réessayer tous les types transitoires. S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes utilisent une gestion des échecs distincte. @@ -1184,12 +1184,12 @@ S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes u } ``` -- `enabled` : active les alertes d’échec pour les tâches Cron (par défaut : `false`). -- `after` : nombre d’échecs consécutifs avant le déclenchement d’une alerte (entier positif, min. : `1`). -- `cooldownMs` : nombre minimal de millisecondes entre des alertes répétées pour la même tâche (entier non négatif). -- `includeSkipped` : compte les exécutions ignorées consécutives dans le seuil d’alerte (par défaut : `false`). Les exécutions ignorées sont suivies séparément et n’affectent pas le délai d’attente après erreur d’exécution. -- `mode` : mode de livraison — `"announce"` envoie via un message de canal ; `"webhook"` publie vers le webhook configuré. -- `accountId` : compte ou ID de canal facultatif pour limiter la portée de la livraison des alertes. +- `enabled`: active les alertes d’échec pour les tâches Cron (par défaut : `false`). +- `after`: nombre d’échecs consécutifs avant le déclenchement d’une alerte (entier positif, min. : `1`). +- `cooldownMs`: délai minimal en millisecondes entre les alertes répétées pour la même tâche (entier non négatif). +- `includeSkipped`: comptabilise les exécutions ignorées consécutives dans le seuil d’alerte (par défaut : `false`). Les exécutions ignorées sont suivies séparément et n’affectent pas le délai d’attente après erreur d’exécution. +- `mode`: mode de livraison — `"announce"` envoie via un message de canal; `"webhook"` publie vers le Webhook configuré. +- `accountId`: compte ou identifiant de canal facultatif pour limiter la portée de la livraison des alertes. ### `cron.failureDestination` @@ -1206,51 +1206,51 @@ S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes u } ``` -- Destination par défaut des notifications d’échec Cron pour toutes les tâches. -- `mode` : `"announce"` ou `"webhook"` ; utilise `"announce"` par défaut lorsque les données de cible suffisantes existent. -- `channel` : remplacement du canal pour la livraison par annonce. `"last"` réutilise le dernier canal de livraison connu. -- `to` : cible d’annonce explicite ou URL de webhook. Obligatoire en mode webhook. -- `accountId` : remplacement facultatif du compte pour la livraison. -- `delivery.failureDestination` propre à la tâche remplace cette valeur globale par défaut. -- Lorsque ni la destination d’échec globale ni celle propre à la tâche n’est définie, les tâches qui livrent déjà via `announce` reviennent à cette cible d’annonce principale en cas d’échec. +- Destination par défaut pour les notifications d’échec Cron sur toutes les tâches. +- `mode`: `"announce"` ou `"webhook"`; utilise par défaut `"announce"` lorsque les données de cible sont suffisantes. +- `channel`: remplacement du canal pour la livraison par annonce. `"last"` réutilise le dernier canal de livraison connu. +- `to`: cible d’annonce explicite ou URL Webhook. Obligatoire pour le mode Webhook. +- `accountId`: remplacement facultatif du compte pour la livraison. +- Le `delivery.failureDestination` propre à une tâche remplace cette valeur globale par défaut. +- Lorsque ni la destination d’échec globale ni celle propre à la tâche n’est définie, les tâches qui livrent déjà via `announce` se rabattent sur cette cible d’annonce principale en cas d’échec. - `delivery.failureDestination` n’est pris en charge que pour les tâches `sessionTarget="isolated"`, sauf si le `delivery.mode` principal de la tâche est `"webhook"`. Voir [Tâches Cron](/fr/automation/cron-jobs). Les exécutions Cron isolées sont suivies comme des [tâches en arrière-plan](/fr/automation/tasks). --- -## Variables de modèle pour les modèles média +## Variables de modèle de média -Variables d’emplacement développées dans `tools.media.models[].args` : +Espaces réservés de modèle développés dans `tools.media.models[].args`: -| Variable | Description | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Corps complet du message entrant | -| `{{RawBody}}` | Corps brut (sans enveloppes d’historique/expéditeur) | -| `{{BodyStripped}}` | Corps dont les mentions de groupe ont été supprimées | -| `{{From}}` | Identifiant de l’expéditeur | -| `{{To}}` | Identifiant de destination | -| `{{MessageSid}}` | ID du message de canal | -| `{{SessionId}}` | UUID de la session actuelle | -| `{{IsNewSession}}` | `"true"` lorsqu’une nouvelle session est créée | -| `{{MediaUrl}}` | Pseudo-URL du média entrant | -| `{{MediaPath}}` | Chemin local du média | -| `{{MediaType}}` | Type de média (image/audio/document/…) | -| `{{Transcript}}` | Transcription audio | -| `{{Prompt}}` | Invite média résolue pour les entrées CLI | +| Variable | Description | +| ------------------ | --------------------------------------------------------------- | +| `{{Body}}` | Corps complet du message entrant | +| `{{RawBody}}` | Corps brut (sans enveloppes d’historique/d’expéditeur) | +| `{{BodyStripped}}` | Corps avec les mentions de groupe supprimées | +| `{{From}}` | Identifiant de l’expéditeur | +| `{{To}}` | Identifiant de destination | +| `{{MessageSid}}` | Identifiant du message du canal | +| `{{SessionId}}` | UUID de la session actuelle | +| `{{IsNewSession}}` | `"true"` lorsqu’une nouvelle session est créée | +| `{{MediaUrl}}` | Pseudo-URL du média entrant | +| `{{MediaPath}}` | Chemin local du média | +| `{{MediaType}}` | Type de média (image/audio/document/…) | +| `{{Transcript}}` | Transcription audio | +| `{{Prompt}}` | Invite média résolue pour les entrées CLI | | `{{MaxChars}}` | Nombre maximal de caractères de sortie résolu pour les entrées CLI | -| `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | Sujet du groupe (au mieux) | -| `{{GroupMembers}}` | Aperçu des membres du groupe (au mieux) | -| `{{SenderName}}` | Nom d’affichage de l’expéditeur (au mieux) | -| `{{SenderE164}}` | Numéro de téléphone de l’expéditeur (au mieux) | -| `{{Provider}}` | Indication de fournisseur (whatsapp, telegram, discord, etc.) | +| `{{ChatType}}` | `"direct"` ou `"group"` | +| `{{GroupSubject}}` | Sujet du groupe (au mieux) | +| `{{GroupMembers}}` | Aperçu des membres du groupe (au mieux) | +| `{{SenderName}}` | Nom d’affichage de l’expéditeur (au mieux) | +| `{{SenderE164}}` | Numéro de téléphone de l’expéditeur (au mieux) | +| `{{Provider}}` | Indice de fournisseur (whatsapp, telegram, discord, etc.) | --- ## Inclusions de configuration (`$include`) -Divisez la configuration en plusieurs fichiers : +Divisez la configuration en plusieurs fichiers: ```json5 // ~/.openclaw/openclaw.json @@ -1263,20 +1263,20 @@ Divisez la configuration en plusieurs fichiers : } ``` -**Comportement de fusion :** +**Comportement de fusion:** -- Fichier unique : remplace l’objet contenant. -- Tableau de fichiers : fusion profonde dans l’ordre (les fichiers ultérieurs remplacent les précédents). -- Clés sœurs : fusionnées après les inclusions (remplacent les valeurs incluses). -- Inclusions imbriquées : jusqu’à 10 niveaux de profondeur. -- Chemins : résolus relativement au fichier incluant, mais doivent rester dans le répertoire de configuration de plus haut niveau (`dirname` de `openclaw.json`). Les formes absolues/`../` ne sont autorisées que lorsqu’elles se résolvent toujours à l’intérieur de cette limite. -- Les écritures appartenant à OpenClaw qui ne modifient qu’une seule section de plus haut niveau appuyée par une inclusion de fichier unique écrivent directement dans ce fichier inclus. Par exemple, `plugins install` met à jour `plugins: { $include: "./plugins.json5" }` dans `plugins.json5` et laisse `openclaw.json` intact. -- Les inclusions racine, les tableaux d’inclusions et les inclusions avec remplacements par clés sœurs sont en lecture seule pour les écritures appartenant à OpenClaw ; ces écritures échouent de manière fermée au lieu d’aplatir la configuration. -- Erreurs : messages clairs pour les fichiers manquants, les erreurs d’analyse et les inclusions circulaires. +- Fichier unique: remplace l’objet conteneur. +- Tableau de fichiers: fusion profonde dans l’ordre (les suivants remplacent les précédents). +- Clés voisines: fusionnées après les inclusions (remplacent les valeurs incluses). +- Inclusions imbriquées: jusqu’à 10 niveaux de profondeur. +- Chemins: résolus par rapport au fichier qui inclut, mais doivent rester dans le répertoire de configuration de niveau supérieur (`dirname` de `openclaw.json`). Les formes absolues/`../` ne sont autorisées que lorsqu’elles se résolvent toujours à l’intérieur de cette limite. +- Les écritures appartenant à OpenClaw qui ne modifient qu’une seule section de niveau supérieur adossée à une inclusion de fichier unique écrivent directement dans ce fichier inclus. Par exemple, `plugins install` met à jour `plugins: { $include: "./plugins.json5" }` dans `plugins.json5` et laisse `openclaw.json` intact. +- Les inclusions racine, les tableaux d’inclusions et les inclusions avec remplacements par clés voisines sont en lecture seule pour les écritures appartenant à OpenClaw; ces écritures échouent de manière fermée au lieu d’aplatir la configuration. +- Erreurs: messages clairs pour les fichiers manquants, les erreurs d’analyse et les inclusions circulaires. --- -_Connexe : [Configuration](/fr/gateway/configuration) · [Exemples de configuration](/fr/gateway/configuration-examples) · [Doctor](/fr/gateway/doctor)_ +_Related: [Configuration](/fr/gateway/configuration) · [Exemples de configuration](/fr/gateway/configuration-examples) · [Doctor](/fr/gateway/doctor)_ ## Connexe diff --git a/docs/fr/gateway/opentelemetry.md b/docs/fr/gateway/opentelemetry.md index c0a03dbcb..73ec3fd47 100644 --- a/docs/fr/gateway/opentelemetry.md +++ b/docs/fr/gateway/opentelemetry.md @@ -1,42 +1,40 @@ --- read_when: - - Vous souhaitez envoyer l’utilisation des modèles OpenClaw, le flux des messages ou les métriques de session à un collecteur OpenTelemetry - - Vous raccordez des traces, des métriques ou des journaux à Grafana, Datadog, Honeycomb, New Relic, Tempo ou à un autre backend OTLP - - Vous avez besoin des noms exacts des métriques, des noms des segments ou des structures des attributs pour créer des tableaux de bord ou des alertes -summary: Exporter les diagnostics d’OpenClaw vers n’importe quel collecteur OpenTelemetry via le Plugin diagnostics-otel (OTLP/HTTP) + - Vous souhaitez envoyer l’utilisation des modèles d’OpenClaw, le flux de messages ou les métriques de session à un collecteur OpenTelemetry + - Vous connectez des traces, des métriques ou des journaux à Grafana, Datadog, Honeycomb, New Relic, Tempo ou un autre backend OTLP + - Vous avez besoin des noms exacts des métriques, des noms des étendues ou de la structure des attributs pour créer des tableaux de bord ou des alertes +summary: Exportez les diagnostics OpenClaw vers n’importe quel collecteur OpenTelemetry via le plugin diagnostics-otel (OTLP/HTTP) title: Export OpenTelemetry x-i18n: - generated_at: "2026-05-04T02:24:48Z" + generated_at: "2026-05-05T06:17:23Z" model: gpt-5.5 provider: openai - source_hash: d0b5be99b29fe5f13132b03cfeaf3ce978ee16f29e307aa76769bc414b5ca35f + source_hash: b5030b8b16624f114e31838d3a055c24e8a23a6c77d63495a445cb9f2e227b6a source_path: gateway/opentelemetry.md workflow: 16 --- OpenClaw exporte les diagnostics via le plugin officiel `diagnostics-otel` -avec **OTLP/HTTP (protobuf)**. Tout collecteur ou backend qui accepte OTLP/HTTP -fonctionne sans modification du code. Pour les journaux de fichiers locaux et la -façon de les lire, consultez [Journalisation](/fr/logging). +en utilisant **OTLP/HTTP (protobuf)**. Tout collecteur ou backend qui accepte OTLP/HTTP +fonctionne sans modification du code. Pour les journaux de fichiers locaux et la façon de les lire, consultez +[Journalisation](/fr/logging). -## Comment l’ensemble s’articule +## Fonctionnement d’ensemble -- Les **événements de diagnostic** sont des enregistrements structurés, en cours - de processus, émis par le Gateway et les plugins groupés pour les exécutions - de modèles, le flux de messages, les sessions, les files d’attente et exec. -- Le **plugin `diagnostics-otel`** s’abonne à ces événements et les exporte sous - forme de **métriques**, **traces** et **journaux** OpenTelemetry via OTLP/HTTP. -- Les **appels de fournisseur** reçoivent un en-tête W3C `traceparent` depuis le - contexte de span d’appel de modèle approuvé d’OpenClaw lorsque le transport du - fournisseur accepte les en-têtes personnalisés. Le contexte de trace émis par - un plugin n’est pas propagé. -- Les exportateurs ne s’attachent que lorsque la surface de diagnostics et le - plugin sont tous deux activés, de sorte que le coût en cours de processus - reste proche de zéro par défaut. +- Les **événements de diagnostic** sont des enregistrements structurés, internes au processus, émis par le + Gateway et les plugins groupés pour les exécutions de modèle, le flux de messages, les sessions, les files d’attente + et exec. +- Le **plugin `diagnostics-otel`** s’abonne à ces événements et les exporte sous forme de + **métriques**, **traces** et **journaux** OpenTelemetry via OTLP/HTTP. +- Les **appels de fournisseur** reçoivent un en-tête W3C `traceparent` depuis le contexte de span + d’appel de modèle de confiance d’OpenClaw lorsque le transport du fournisseur accepte les en-têtes + personnalisés. Le contexte de trace émis par les plugins n’est pas propagé. +- Les exporters ne s’attachent que lorsque la surface de diagnostic et le plugin sont tous deux + activés, de sorte que le coût interne au processus reste proche de zéro par défaut. ## Démarrage rapide -Pour les installations empaquetées, installez d’abord le plugin : +Pour les installations packagées, installez d’abord le plugin : ```bash openclaw plugins install clawhub:@openclaw/diagnostics-otel @@ -67,26 +65,26 @@ openclaw plugins install clawhub:@openclaw/diagnostics-otel } ``` -Vous pouvez également activer le plugin depuis la CLI : +Vous pouvez aussi activer le plugin depuis la CLI : ```bash openclaw plugins enable diagnostics-otel ``` -`protocol` ne prend actuellement en charge que `http/protobuf`. `grpc` est ignoré. +`protocol` prend actuellement en charge uniquement `http/protobuf`. `grpc` est ignoré. ## Signaux exportés -| Signal | Ce qu’il contient | -| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Signal | Ce qu’il contient | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Métriques** | Compteurs et histogrammes pour l’utilisation des tokens, le coût, la durée d’exécution, le flux de messages, les voies de file d’attente, l’état de session, exec et la pression mémoire. | -| **Traces** | Spans pour l’utilisation des modèles, les appels de modèles, le cycle de vie du harnais, l’exécution d’outils, exec, le traitement Webhook/message, l’assemblage du contexte et les boucles d’outils. | -| **Journaux** | Enregistrements structurés `logging.file` exportés via OTLP lorsque `diagnostics.otel.logs` est activé. | +| **Traces** | Spans pour l’utilisation du modèle, les appels de modèle, le cycle de vie du harness, l’exécution d’outils, exec, le traitement webhook/message, l’assemblage du contexte et les boucles d’outils. | +| **Journaux** | Enregistrements structurés `logging.file` exportés via OTLP lorsque `diagnostics.otel.logs` est activé. | -Activez ou désactivez `traces`, `metrics` et `logs` indépendamment. Les trois -sont activés par défaut lorsque `diagnostics.otel.enabled` vaut true. +Activez ou désactivez `traces`, `metrics` et `logs` indépendamment. Les trois sont activés par défaut +lorsque `diagnostics.otel.enabled` vaut true. ## Référence de configuration @@ -123,139 +121,136 @@ sont activés par défaut lorsque `diagnostics.otel.enabled` vaut true. ### Variables d’environnement -| Variable | Objectif | -| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | Remplace `diagnostics.otel.endpoint`. Si la valeur contient déjà `/v1/traces`, `/v1/metrics` ou `/v1/logs`, elle est utilisée telle quelle. | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Remplacements de point de terminaison propres au signal, utilisés lorsque la clé de configuration `diagnostics.otel.*Endpoint` correspondante n’est pas définie. La configuration propre au signal prime sur l’environnement propre au signal, qui prime sur le point de terminaison partagé. | -| `OTEL_SERVICE_NAME` | Remplace `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Remplace le protocole filaire (seul `http/protobuf` est honoré aujourd’hui). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Définissez sur `gen_ai_latest_experimental` pour émettre le dernier attribut expérimental de span GenAI (`gen_ai.provider.name`) au lieu de l’ancien `gen_ai.system`. Les métriques GenAI utilisent toujours des attributs sémantiques bornés et de faible cardinalité, quoi qu’il en soit. | -| `OPENCLAW_OTEL_PRELOADED` | Définissez sur `1` lorsqu’un autre préchargement ou processus hôte a déjà enregistré le SDK OpenTelemetry global. Le plugin ignore alors son propre cycle de vie NodeSDK, mais connecte tout de même les écouteurs de diagnostic et respecte `traces`/`metrics`/`logs`. | +| Variable | Objectif | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | Remplace `diagnostics.otel.endpoint`. Si la valeur contient déjà `/v1/traces`, `/v1/metrics` ou `/v1/logs`, elle est utilisée telle quelle. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Remplacements d’endpoint propres au signal, utilisés lorsque la clé de configuration `diagnostics.otel.*Endpoint` correspondante n’est pas définie. La configuration propre au signal prime sur l’env propre au signal, qui prime sur l’endpoint partagé. | +| `OTEL_SERVICE_NAME` | Remplace `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Remplace le protocole de transport (seul `http/protobuf` est pris en compte aujourd’hui). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Définissez sur `gen_ai_latest_experimental` pour émettre le dernier attribut de span GenAI expérimental (`gen_ai.provider.name`) au lieu de l’ancien `gen_ai.system`. Les métriques GenAI utilisent toujours des attributs sémantiques bornés et à faible cardinalité. | +| `OPENCLAW_OTEL_PRELOADED` | Définissez sur `1` lorsqu’un autre préchargement ou processus hôte a déjà enregistré le SDK OpenTelemetry global. Le plugin ignore alors son propre cycle de vie NodeSDK, mais câble tout de même les écouteurs de diagnostic et respecte `traces`/`metrics`/`logs`. | ## Confidentialité et capture du contenu -Le contenu brut des modèles/outils n’est **pas** exporté par défaut. Les spans -transportent des identifiants bornés (canal, fournisseur, modèle, catégorie -d’erreur, identifiants de requête sous forme de hachage uniquement) et -n’incluent jamais le texte de prompt, le texte de réponse, les entrées d’outil, -les sorties d’outil ni les clés de session. +Le contenu brut de modèle/outil n’est **pas** exporté par défaut. Les spans transportent des +identifiants bornés (canal, fournisseur, modèle, catégorie d’erreur, identifiants de requête avec hachage uniquement) +et n’incluent jamais le texte du prompt, le texte de réponse, les entrées d’outil, les sorties d’outil ni +les clés de session. -Les requêtes de modèle sortantes peuvent inclure un en-tête W3C `traceparent`. -Cet en-tête est généré uniquement à partir du contexte de trace de diagnostic -appartenant à OpenClaw pour l’appel de modèle actif. Les en-têtes `traceparent` -fournis par l’appelant existant sont remplacés, de sorte que les plugins ou les -options de fournisseur personnalisées ne peuvent pas usurper l’ascendance de -trace entre services. +Les requêtes de modèle sortantes peuvent inclure un en-tête W3C `traceparent`. Cet en-tête est +généré uniquement à partir du contexte de trace de diagnostic appartenant à OpenClaw pour l’appel de modèle +actif. Les en-têtes `traceparent` existants fournis par l’appelant sont remplacés, de sorte que les plugins ou +options de fournisseur personnalisées ne peuvent pas usurper l’ascendance de trace interservices. -Définissez `diagnostics.otel.captureContent.*` sur `true` uniquement lorsque -votre collecteur et votre politique de rétention sont approuvés pour le texte de -prompt, de réponse, d’outil ou de prompt système. Chaque sous-clé est activée -indépendamment : +Définissez `diagnostics.otel.captureContent.*` sur `true` uniquement lorsque votre collecteur et votre +politique de rétention sont approuvés pour le texte de prompt, de réponse, d’outil ou de prompt système. +Chaque sous-clé est optionnelle indépendamment : -- `inputMessages` — contenu de prompt utilisateur. -- `outputMessages` — contenu de réponse du modèle. -- `toolInputs` — charges utiles d’arguments d’outil. -- `toolOutputs` — charges utiles de résultats d’outil. +- `inputMessages` — contenu du prompt utilisateur. +- `outputMessages` — contenu de la réponse du modèle. +- `toolInputs` — charges utiles des arguments d’outil. +- `toolOutputs` — charges utiles des résultats d’outil. - `systemPrompt` — prompt système/développeur assemblé. -Lorsqu’une sous-clé est activée, les spans de modèle et d’outil reçoivent des -attributs `openclaw.content.*` bornés et expurgés pour cette classe uniquement. +Lorsqu’une sous-clé est activée, les spans de modèle et d’outil reçoivent des attributs +`openclaw.content.*` bornés et expurgés pour cette classe uniquement. ## Échantillonnage et vidage -- **Traces :** `diagnostics.otel.sampleRate` (span racine uniquement, `0.0` - abandonne tout, `1.0` conserve tout). +- **Traces :** `diagnostics.otel.sampleRate` (span racine uniquement, `0.0` supprime tout, + `1.0` conserve tout). - **Métriques :** `diagnostics.otel.flushIntervalMs` (minimum `1000`). -- **Journaux :** les journaux OTLP respectent `logging.level` (niveau de journal - de fichier). Ils utilisent le chemin d’expurgation des enregistrements de - journal de diagnostic, et non le formatage console. Les installations à volume - élevé devraient préférer l’échantillonnage/filtrage du collecteur OTLP à - l’échantillonnage local. -- **Corrélation des journaux de fichiers :** les journaux de fichiers JSONL - incluent les champs de niveau supérieur `traceId`, `spanId`, `parentSpanId` et - `traceFlags` lorsque l’appel de journal porte un contexte de trace de - diagnostic valide, ce qui permet aux processeurs de journaux de joindre les - lignes de journal locales aux spans exportés. -- **Corrélation des requêtes :** les requêtes HTTP du Gateway et les trames - WebSocket créent une portée de trace de requête interne. Les journaux et les - événements de diagnostic dans cette portée héritent de la trace de requête par - défaut, tandis que les spans d’exécution d’agent et d’appel de modèle sont - créés comme enfants afin que les en-têtes `traceparent` du fournisseur restent - sur la même trace. +- **Journaux :** les journaux OTLP respectent `logging.level` (niveau de journal de fichier). Ils utilisent le + chemin d’expurgation des enregistrements de journal de diagnostic, pas le formatage de la console. Les installations + à fort volume doivent préférer l’échantillonnage/filtrage du collecteur OTLP à l’échantillonnage local. +- **Corrélation des journaux de fichiers :** les journaux de fichiers JSONL incluent `traceId`, + `spanId`, `parentSpanId` et `traceFlags` au niveau supérieur lorsque l’appel de journal contient un contexte de trace + de diagnostic valide, ce qui permet aux processeurs de journaux de joindre les lignes de journal locales aux + spans exportés. +- **Corrélation des requêtes :** les requêtes HTTP du Gateway et les trames WebSocket créent une + portée de trace de requête interne. Les journaux et événements de diagnostic dans cette portée + héritent par défaut de la trace de requête, tandis que les spans d’exécution d’agent et d’appel de modèle sont + créés comme enfants, afin que les en-têtes `traceparent` du fournisseur restent sur la même trace. ## Métriques exportées -### Utilisation des modèles +### Utilisation du modèle -- `openclaw.tokens` (compteur, attrs : `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`) -- `openclaw.cost.usd` (compteur, attrs : `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.run.duration_ms` (histogramme, attrs : `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (histogramme, attrs : `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (histogramme, métrique de conventions sémantiques GenAI, attrs : `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (histogramme, secondes, métrique de conventions sémantiques GenAI, attrs : `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, `error.type` facultatif) -- `openclaw.model_call.duration_ms` (histogramme, attrs : `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, plus `openclaw.errorCategory` et `openclaw.failureKind` sur les erreurs classifiées) -- `openclaw.model_call.request_bytes` (histogramme, taille en octets UTF-8 de la charge utile finale de requête de modèle ; aucun contenu brut de charge utile) -- `openclaw.model_call.response_bytes` (histogramme, taille en octets UTF-8 des événements de réponse de modèle diffusés ; aucun contenu brut de réponse) -- `openclaw.model_call.time_to_first_byte_ms` (histogramme, temps écoulé avant le premier événement de réponse diffusé) +- `openclaw.tokens` (counter, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`) +- `openclaw.cost.usd` (counter, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `gen_ai.client.token.usage` (histogram, GenAI semantic-conventions metric, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (histogram, seconds, GenAI semantic-conventions metric, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, optional `error.type`) +- `openclaw.model_call.duration_ms` (histogram, attrs: `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport`, plus `openclaw.errorCategory` and `openclaw.failureKind` on classified errors) +- `openclaw.model_call.request_bytes` (histogram, taille en octets UTF-8 de la charge utile finale de la requête de modèle ; aucun contenu brut de charge utile) +- `openclaw.model_call.response_bytes` (histogram, taille en octets UTF-8 des événements de réponse de modèle diffusés ; aucun contenu brut de réponse) +- `openclaw.model_call.time_to_first_byte_ms` (histogram, temps écoulé avant le premier événement de réponse diffusé) ### Flux de messages -- `openclaw.webhook.received` (compteur, attrs : `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.error` (compteur, attrs : `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (histogramme, attrs : `openclaw.channel`, `openclaw.webhook`) -- `openclaw.message.queued` (compteur, attrs : `openclaw.channel`, `openclaw.source`) -- `openclaw.message.processed` (compteur, attrs : `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.duration_ms` (histogramme, attrs : `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.delivery.started` (compteur, attrs : `openclaw.channel`, `openclaw.delivery.kind`) -- `openclaw.message.delivery.duration_ms` (histogramme, attrs : `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) +- `openclaw.webhook.received` (counter, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.error` (counter, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.webhook.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.webhook`) +- `openclaw.message.queued` (counter, attrs: `openclaw.channel`, `openclaw.source`) +- `openclaw.message.processed` (counter, attrs: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.outcome`) +- `openclaw.message.delivery.started` (counter, attrs: `openclaw.channel`, `openclaw.delivery.kind`) +- `openclaw.message.delivery.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) ### Files d’attente et sessions -- `openclaw.queue.lane.enqueue` (compteur, attrs : `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (compteur, attrs : `openclaw.lane`) -- `openclaw.queue.depth` (histogramme, attrs : `openclaw.lane` ou `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (histogramme, attrs : `openclaw.lane`) -- `openclaw.session.state` (compteur, attrs : `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (compteur, attrs : `openclaw.state` ; émis uniquement pour la comptabilité des sessions obsolètes sans travail actif) -- `openclaw.session.stuck_age_ms` (histogramme, attrs : `openclaw.state` ; émis uniquement pour la comptabilité des sessions obsolètes sans travail actif) -- `openclaw.run.attempt` (compteur, attrs : `openclaw.attempt`) +- `openclaw.queue.lane.enqueue` (counter, attrs: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (counter, attrs: `openclaw.lane`) +- `openclaw.queue.depth` (histogram, attrs: `openclaw.lane` or `openclaw.channel=heartbeat`) +- `openclaw.queue.wait_ms` (histogram, attrs: `openclaw.lane`) +- `openclaw.session.state` (counter, attrs: `openclaw.state`, `openclaw.reason`) +- `openclaw.session.stuck` (counter, attrs: `openclaw.state`; émis uniquement pour la comptabilité des sessions obsolètes sans travail actif) +- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`; émis uniquement pour la comptabilité des sessions obsolètes sans travail actif) +- `openclaw.run.attempt` (counter, attrs: `openclaw.attempt`) ### Télémétrie de vivacité des sessions -`diagnostics.stuckSessionWarnMs` est le seuil d’âge sans progression pour les -diagnostics de vivacité des sessions. Une session `processing` ne vieillit pas -vers ce seuil tant qu’OpenClaw observe une progression d’exécution de réponse, -d’outil, de statut, de bloc ou d’ACP. Les keepalives de saisie ne sont pas -comptés comme une progression, de sorte qu’un modèle ou un harnais silencieux -peut tout de même être détecté. +`diagnostics.stuckSessionWarnMs` est le seuil d’âge sans progression pour les diagnostics de +vivacité des sessions. Une session `processing` ne vieillit pas vers ce seuil +tant qu’OpenClaw observe une progression d’exécution via réponse, outil, statut, bloc ou ACP. +Les keepalives de saisie ne sont pas comptés comme progression, de sorte qu’un modèle ou harness silencieux peut +tout de même être détecté. OpenClaw classe les sessions selon le travail qu’il peut encore observer : -- `session.long_running` : travaux intégrés actifs, appels de modèle ou appels d’outils - toujours en progression. -- `session.stalled` : des travaux actifs existent, mais l’exécution active n’a pas signalé +- `session.long_running` : travail intégré actif, appels au modèle ou appels d’outil + encore en progression. +- `session.stalled` : un travail actif existe, mais l’exécution active n’a pas signalé de progression récente. Les exécutions intégrées bloquées restent d’abord en observation seule, puis - passent en arrêt-drain après au moins 10 minutes et 5x `diagnostics.stuckSessionWarnMs` - sans progression, afin que les tours en file d’attente derrière la voie puissent reprendre. -- `session.stuck` : comptabilité de session obsolète sans travaux actifs. Cela libère - immédiatement la voie de session affectée. + passent en abandon avec vidage après `diagnostics.stuckSessionAbortMs` sans progression afin que les tours + en file d’attente derrière la voie puissent reprendre. Quand la valeur n’est pas définie, le seuil d’abandon utilise par défaut + la fenêtre étendue plus sûre d’au moins 10 minutes et 5x + `diagnostics.stuckSessionWarnMs`. +- `session.stuck` : suivi de session obsolète sans travail actif. Cela libère + immédiatement la voie de session concernée. + +La récupération émet des événements structurés `session.recovery.requested` et +`session.recovery.completed`. L’état de session de diagnostic n’est marqué comme inactif +qu’après un résultat de récupération modificateur (`aborted` ou `released`) et uniquement si la +même génération de traitement est encore actuelle. Seul `session.stuck` émet le compteur `openclaw.session.stuck`, l’histogramme -`openclaw.session.stuck_age_ms` et le span `openclaw.session.stuck`. -Les diagnostics `session.stuck` répétés appliquent un backoff tant que la session reste -inchangée ; les tableaux de bord devraient donc alerter sur des augmentations soutenues plutôt qu’à chaque -tick de Heartbeat. Pour le paramètre de configuration et les valeurs par défaut, consultez +`openclaw.session.stuck_age_ms` et le span `openclaw.session.stuck`. Les diagnostics +`session.stuck` répétés appliquent un délai exponentiel tant que la session reste +inchangée ; les tableaux de bord doivent donc alerter sur des augmentations soutenues plutôt qu’à chaque +tick de Heartbeat. Pour le réglage de configuration et les valeurs par défaut, consultez [Référence de configuration](/fr/gateway/configuration-reference#diagnostics). ### Cycle de vie du harnais - `openclaw.harness.duration_ms` (histogramme, attrs : `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.harness.phase` en cas d’erreurs) -### Exec +### Exécution - `openclaw.exec.duration_ms` (histogramme, attrs : `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) -### Internes de diagnostic (mémoire et boucle d’outils) +### Internes de diagnostic (mémoire et boucle d’outil) - `openclaw.memory.heap_used_bytes` (histogramme, attrs : `openclaw.memory.kind`) - `openclaw.memory.rss_bytes` (histogramme) @@ -280,7 +275,7 @@ tick de Heartbeat. Pour le paramètre de configuration et les valeurs par défau - `openclaw.provider.request_id_hash` (hachage borné basé sur SHA de l’identifiant de requête du fournisseur amont ; les identifiants bruts ne sont pas exportés) - `openclaw.harness.run` - `openclaw.harness.id`, `openclaw.harness.plugin`, `openclaw.outcome`, `openclaw.provider`, `openclaw.model`, `openclaw.channel` - - À la fin : `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active` + - À l’achèvement : `openclaw.harness.result_classification`, `openclaw.harness.yield_detected`, `openclaw.harness.items.started`, `openclaw.harness.items.completed`, `openclaw.harness.items.active` - En cas d’erreur : `openclaw.harness.phase`, `openclaw.errorCategory`, `openclaw.harness.cleanup_failed` facultatif - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` @@ -297,26 +292,26 @@ tick de Heartbeat. Pour le paramètre de configuration et les valeurs par défau - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (aucun prompt, historique, réponse ni contenu de clé de session) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (aucun contenu d’invite, d’historique, de réponse ou de clé de session) - `openclaw.tool.loop` - - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (aucun message de boucle, paramètre ni sortie d’outil) + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (aucun message de boucle, paramètre ou sortie d’outil) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` Lorsque la capture de contenu est explicitement activée, les spans de modèle et d’outil peuvent aussi -inclure des attributs `openclaw.content.*` bornés et expurgés pour les classes de -contenu spécifiques auxquelles vous avez souscrit. +inclure des attributs bornés et expurgés `openclaw.content.*` pour les classes de contenu +spécifiques auxquelles vous avez souscrit. ## Catalogue des événements de diagnostic -Les événements ci-dessous alimentent les métriques et les spans ci-dessus. Les Plugins peuvent aussi s’y abonner +Les événements ci-dessous alimentent les métriques et spans ci-dessus. Les Plugins peuvent aussi s’y abonner directement sans export OTLP. **Utilisation du modèle** -- `model.usage` — tokens, coût, durée, contexte, fournisseur/modèle/canal, - identifiants de session. `usage` correspond à la comptabilité fournisseur/tour pour le coût et la télémétrie ; - `context.used` est l’instantané courant du prompt/contexte et peut être inférieur au +- `model.usage` — jetons, coût, durée, contexte, fournisseur/modèle/canal, + identifiants de session. `usage` est la comptabilisation fournisseur/tour pour le coût et la télémétrie ; + `context.used` est l’instantané actuel de l’invite/contexte et peut être inférieur à `usage.total` du fournisseur lorsque des entrées mises en cache ou des appels de boucle d’outils sont impliqués. **Flux de messages** @@ -330,27 +325,26 @@ directement sans export OTLP. - `queue.lane.enqueue` / `queue.lane.dequeue` - `session.state` / `session.long_running` / `session.stalled` / `session.stuck` - `run.attempt` / `run.progress` -- `diagnostic.heartbeat` (compteurs agrégés : Webhooks/file d’attente/session) +- `diagnostic.heartbeat` (compteurs agrégés : webhooks/file d’attente/session) **Cycle de vie du harnais** - `harness.run.started` / `harness.run.completed` / `harness.run.error` — - cycle de vie par exécution pour le harnais d’agent. Inclut `harnessId`, `pluginId` - facultatif, fournisseur/modèle/canal et identifiant d’exécution. La fin ajoute - `durationMs`, `outcome`, `resultClassification` facultatif, `yieldDetected`, - et les décomptes `itemLifecycle`. Les erreurs ajoutent `phase` + cycle de vie par exécution pour le harnais d’agent. Inclut `harnessId`, `pluginId` facultatif, fournisseur/modèle/canal et identifiant d’exécution. L’achèvement ajoute + `durationMs`, `outcome`, `resultClassification` facultatif, `yieldDetected` + et les compteurs `itemLifecycle`. Les erreurs ajoutent `phase` (`prepare`/`start`/`send`/`resolve`/`cleanup`), `errorCategory` et `cleanupFailed` facultatif. -**Exec** +**Exécution** -- `exec.process.completed` — résultat terminal, durée, cible, mode, code de sortie - et type d’échec. Le texte de la commande et les répertoires de travail ne sont pas +- `exec.process.completed` — résultat du terminal, durée, cible, mode, code de sortie + et type d’échec. Le texte de commande et les répertoires de travail ne sont pas inclus. ## Sans exportateur -Vous pouvez garder les événements de diagnostic disponibles pour les Plugins ou les collecteurs personnalisés sans +Vous pouvez garder les événements de diagnostic disponibles pour les Plugins ou les récepteurs personnalisés sans exécuter `diagnostics-otel` : ```json5 @@ -359,8 +353,7 @@ exécuter `diagnostics-otel` : } ``` -Pour une sortie de débogage ciblée sans augmenter `logging.level`, utilisez les indicateurs de diagnostic. -Les indicateurs sont insensibles à la casse et prennent en charge les caractères génériques (par exemple `telegram.*` ou +Pour une sortie de débogage ciblée sans augmenter `logging.level`, utilisez les indicateurs de diagnostic. Les indicateurs sont insensibles à la casse et prennent en charge les caractères génériques (par exemple `telegram.*` ou `*`) : ```json5 @@ -369,13 +362,13 @@ Les indicateurs sont insensibles à la casse et prennent en charge les caractèr } ``` -Ou sous forme de surcharge d’environnement ponctuelle : +Ou comme surcharge d’environnement ponctuelle : ```bash OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -La sortie des indicateurs est envoyée au fichier journal standard (`logging.file`) et reste +La sortie des indicateurs va dans le fichier journal standard (`logging.file`) et reste expurgée par `logging.redactSensitive`. Guide complet : [Indicateurs de diagnostic](/fr/diagnostics/flags). @@ -392,8 +385,8 @@ Vous pouvez aussi omettre `diagnostics-otel` de `plugins.allow`, ou exécuter ## Connexe -- [Journalisation](/fr/logging) — journaux de fichiers, sortie console, suivi CLI et onglet Logs de l’interface Control +- [Journalisation](/fr/logging) — journaux de fichiers, sortie console, suivi CLI et onglet Logs de l’interface Control UI - [Internes de journalisation du Gateway](/fr/gateway/logging) — styles de journaux WS, préfixes de sous-systèmes et capture de console -- [Indicateurs de diagnostic](/fr/diagnostics/flags) — indicateurs de journal de débogage ciblés -- [Export de diagnostic](/fr/gateway/diagnostics) — outil de support bundle pour opérateurs (distinct de l’export OTEL) +- [Indicateurs de diagnostic](/fr/diagnostics/flags) — indicateurs de journal de débogage ciblé +- [Export de diagnostic](/fr/gateway/diagnostics) — outil de bundle de support opérateur (distinct de l’export OTEL) - [Référence de configuration](/fr/gateway/configuration-reference#diagnostics) — référence complète des champs `diagnostics.*` diff --git a/docs/fr/help/testing-updates-plugins.md b/docs/fr/help/testing-updates-plugins.md index 72aade8cc..ffadaa4a4 100644 --- a/docs/fr/help/testing-updates-plugins.md +++ b/docs/fr/help/testing-updates-plugins.md @@ -2,46 +2,46 @@ read_when: - Modification du comportement de mise à jour, de doctor, d’acceptation des packages ou d’installation de Plugin d’OpenClaw - Préparer ou approuver une version candidate - - Débogage des régressions de mise à jour de package, de nettoyage des dépendances de Plugin ou d’installation de Plugin + - Débogage de la mise à jour de packages, du nettoyage des dépendances de Plugin ou des régressions d’installation de Plugin sidebarTitle: Update and plugin tests -summary: Comment OpenClaw valide les chemins de mise à jour, les migrations de paquets et le comportement d’installation/mise à jour des Plugins -title: 'Tests : mises à jour et Plugins' +summary: Comment OpenClaw valide les chemins de mise à jour, les migrations de paquets et le comportement d’installation/mise à jour du Plugin +title: 'Tests : mises à jour et plugins' x-i18n: - generated_at: "2026-05-05T01:47:53Z" + generated_at: "2026-05-05T06:17:52Z" model: gpt-5.5 provider: openai - source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286 + source_hash: 19ae526d3daa8a1b67cb2f74225138b3e1fa192c9f956c9dd6d0e407581b9ed9 source_path: help/testing-updates-plugins.md workflow: 16 --- -Ceci est la checklist dédiée à la validation des mises à jour et des Plugins. L’objectif est -simple : prouver que le paquet installable peut mettre à jour un état utilisateur réel, réparer -l’état hérité obsolète via `doctor`, et continuer à installer, charger, mettre à jour et désinstaller -des Plugins depuis les sources prises en charge. +Voici la checklist dédiée à la validation des mises à jour et des plugins. L’objectif est +simple : prouver que le package installable peut mettre à jour un état utilisateur réel, +réparer un état hérité obsolète via `doctor`, et toujours installer, charger, mettre à jour +et désinstaller des plugins depuis les sources prises en charge. -Pour la cartographie plus large de l’exécuteur de tests, consultez [Tests](/fr/help/testing). Pour les clés -des fournisseurs live et les suites qui touchent au réseau, consultez [Tests live](/fr/help/testing-live). +Pour la carte plus large du lanceur de tests, consultez [Tests](/fr/help/testing). Pour les +clés de fournisseurs en direct et les suites qui touchent au réseau, consultez [Tests en direct](/fr/help/testing-live). ## Ce que nous protégeons -Les tests de mise à jour et de Plugins protègent ces contrats : +Les tests de mise à jour et de plugins protègent ces contrats : -- Une archive tarball de paquet est complète, possède un `dist/postinstall-inventory.json` - valide, et ne dépend pas de fichiers de dépôt non empaquetés. -- Un utilisateur peut passer d’un paquet publié plus ancien au paquet candidat - sans perdre la configuration, les agents, les sessions, les espaces de travail, les listes d’autorisation de Plugins, ni - la configuration de canal. +- Une archive tarball de package est complète, possède un `dist/postinstall-inventory.json` valide, + et ne dépend pas de fichiers de dépôt non empaquetés. +- Un utilisateur peut passer d’un package publié plus ancien au package candidat + sans perdre la configuration, les agents, les sessions, les espaces de travail, les listes d’autorisation de plugins ou + la configuration des canaux. - `openclaw doctor --fix --non-interactive` possède les chemins de nettoyage et de réparation hérités. Le démarrage ne doit pas accumuler de migrations de compatibilité cachées pour l’état - obsolète des Plugins. -- Les installations de Plugins fonctionnent depuis des répertoires locaux, des dépôts git, des paquets npm et le - chemin du registre ClawHub. -- Les dépendances npm des Plugins sont installées dans la racine npm gérée, analysées avant - confiance, et supprimées via npm pendant la désinstallation afin que les dépendances hissées ne + obsolète des plugins. +- Les installations de plugins fonctionnent depuis des répertoires locaux, des dépôts git, des packages npm et le + chemin de registre ClawHub. +- Les dépendances npm de plugins sont installées dans la racine npm gérée, analysées avant + la confiance, et supprimées via npm pendant la désinstallation afin que les dépendances hissées ne persistent pas. -- La mise à jour des Plugins est stable quand rien n’a changé : les enregistrements d’installation, la source - résolue, l’agencement des dépendances installées et l’état activé restent intacts. +- La mise à jour des plugins est stable lorsque rien n’a changé : les enregistrements d’installation, la source + résolue, l’organisation des dépendances installées et l’état activé restent intacts. ## Preuve locale pendant le développement @@ -53,31 +53,31 @@ pnpm check:changed pnpm test:changed ``` -Pour les changements d’installation, de désinstallation, de dépendances ou d’inventaire de paquet de Plugins, exécutez aussi +Pour les changements d’installation, de désinstallation, de dépendances ou d’inventaire de package de plugins, exécutez aussi les tests ciblés qui couvrent la jonction modifiée : ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -Avant qu’une voie Docker de paquet ne consomme une tarball, prouvez l’artefact de paquet : +Avant qu’une lane Docker de package ne consomme une tarball, prouvez l’artefact de package : ```bash pnpm release:check ``` -`release:check` exécute les vérifications de dérive configuration/docs/API, écrit l’inventaire de distribution -du paquet, exécute `npm pack --dry-run`, rejette les fichiers empaquetés interdits, installe -la tarball dans un préfixe temporaire, exécute postinstall, et effectue un smoke test des points d’entrée -des canaux groupés. +`release:check` exécute les contrôles de dérive config/docs/API, écrit l’inventaire dist du package, +exécute `npm pack --dry-run`, rejette les fichiers empaquetés interdits, installe +la tarball dans un préfixe temporaire, exécute postinstall et teste rapidement les points d’entrée +des canaux intégrés. -## Voies Docker +## Lanes Docker -Les voies Docker constituent la preuve au niveau produit. Elles installent ou mettent à jour un vrai -paquet dans des conteneurs Linux et valident le comportement via des commandes CLI, +Les lanes Docker sont la preuve au niveau produit. Elles installent ou mettent à jour un vrai +package dans des conteneurs Linux et vérifient le comportement via des commandes CLI, le démarrage du Gateway, des sondes HTTP, l’état RPC et l’état du système de fichiers. -Utilisez les voies ciblées pendant l’itération : +Utilisez les lanes ciblées pendant l’itération : ```bash pnpm test:docker:plugins @@ -85,39 +85,44 @@ pnpm test:docker:plugin-lifecycle-matrix pnpm test:docker:plugin-update pnpm test:docker:upgrade-survivor pnpm test:docker:published-upgrade-survivor +pnpm test:docker:update-restart-auth pnpm test:docker:update-migration ``` -Voies importantes : +Lanes importantes : -- `test:docker:plugins` valide le smoke test d’installation de Plugins, les installations de dossiers locaux, - le comportement de saut de mise à jour des dossiers locaux, les dossiers locaux avec des - dépendances préinstallées, les installations de paquets `file:`, les installations git avec exécution CLI, les mises à jour - de références mobiles git, les installations de registre npm avec dépendances transitives - hissées, les no-ops de mise à jour npm, les installations de fixtures ClawHub locales et les - no-ops de mise à jour, le comportement de mise à jour de la marketplace, ainsi que l’activation/inspection du bundle Claude. Définissez +- `test:docker:plugins` valide le smoke test d’installation de plugin, les installations de dossiers locaux, + le comportement d’omission des mises à jour de dossiers locaux, les dossiers locaux avec dépendances + préinstallées, les installations de packages `file:`, les installations git avec exécution CLI, les mises à jour + de refs git mobiles, les installations depuis le registre npm avec dépendances transitives + hissées, les no-op de mise à jour npm, les installations depuis fixture ClawHub locale et les no-op + de mise à jour, le comportement de mise à jour de marketplace, et l’activation/inspection du bundle Claude. Définissez `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` pour garder le bloc ClawHub hermétique/hors ligne. -- `test:docker:plugin-lifecycle-matrix` installe le paquet candidat dans un conteneur - nu, fait passer un Plugin npm par l’installation, l’inspection, la désactivation, l’activation, - la mise à niveau explicite, le retour à une version antérieure explicite et la désinstallation après suppression du code du Plugin. - Il journalise les métriques RSS et CPU pour chaque phase. -- `test:docker:plugin-update` valide qu’un Plugin installé inchangé ne - se réinstalle pas et ne perd pas ses métadonnées d’installation pendant `openclaw plugins update`. +- `test:docker:plugin-lifecycle-matrix` installe le package candidat dans un conteneur nu, + fait passer un plugin npm par installation, inspection, désactivation, activation, + mise à niveau explicite, rétrogradation explicite et désinstallation après suppression du code + du plugin. Il journalise les métriques RSS et CPU pour chaque phase. +- `test:docker:plugin-update` vérifie qu’un plugin installé inchangé ne se + réinstalle pas et ne perd pas ses métadonnées d’installation pendant `openclaw plugins update`. - `test:docker:upgrade-survivor` installe la tarball candidate par-dessus une fixture - d’ancien utilisateur sale, exécute la mise à jour du paquet plus un doctor non interactif, puis démarre - un Gateway local loopback et vérifie la préservation de l’état. + d’ancien utilisateur sale, exécute la mise à jour du package plus doctor non interactif, puis démarre + un Gateway loopback et vérifie la préservation de l’état. - `test:docker:published-upgrade-survivor` installe d’abord une base publiée, la configure via une recette `openclaw config set` intégrée, la met à jour vers la - tarball candidate, exécute doctor, vérifie le nettoyage hérité, démarre le Gateway, et + tarball candidate, exécute doctor, vérifie le nettoyage hérité, démarre le Gateway et sonde `/healthz`, `/readyz` et l’état RPC. -- `test:docker:update-migration` est la voie de mise à jour publiée centrée sur le nettoyage. Elle - part d’un état utilisateur configuré de style Discord/Telegram, exécute le doctor - de base afin que les dépendances de Plugins configurées aient une chance de se matérialiser, injecte - des débris de dépendances de Plugins hérités pour un Plugin empaqueté configuré, met à jour vers - la tarball candidate, et exige que le doctor post-mise à jour supprime les racines - de dépendances héritées. +- `test:docker:update-restart-auth` installe le package candidat, démarre un + Gateway géré avec auth par jeton, supprime l’env d’auth gateway de l’appelant pour + `openclaw update --yes --json`, et exige que la commande de mise à jour candidate + redémarre le Gateway avant les sondes normales. +- `test:docker:update-migration` est la lane de mise à jour publiée axée sur le nettoyage. Elle + part d’un état utilisateur configuré de style Discord/Telegram, exécute le doctor de base + afin que les dépendances de plugins configurées aient une chance de se matérialiser, ensemence + des débris hérités de dépendances de plugins pour un plugin packagé configuré, met à jour vers + la tarball candidate, et exige que le doctor post-mise à jour supprime les racines de dépendances + héritées. -Variantes utiles du survivor de mise à niveau publiée : +Variantes utiles de published-upgrade survivor : ```bash OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \ @@ -132,13 +137,13 @@ pnpm test:docker:published-upgrade-survivor Les scénarios disponibles sont `base`, `feishu-channel`, `bootstrap-persona`, `plugin-deps-cleanup`, `configured-plugin-installs`, `stale-source-plugin-shadow`, `tilde-log-path` et `versioned-runtime-deps`. Dans les exécutions agrégées, -`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` s’étend à tous les scénarios ayant la forme -d’incidents signalés, y compris la migration d’installation de Plugins configurés. +`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` s’étend à tous les scénarios +en forme de problèmes signalés, y compris la migration d’installation de plugins configurés. -La migration complète de mise à jour est intentionnellement séparée de Full Release CI. Utilisez le -workflow manuel `Update Migration` quand la question de release est « chaque -release stable publiée à partir de 2026.4.23 peut-elle se mettre à jour vers ce candidat et -nettoyer les débris de dépendances de Plugins ? » : +La migration complète de mise à jour est intentionnellement séparée de la CI Full Release. Utilisez le +workflow manuel `Update Migration` lorsque la question de release est « chaque +release stable publiée depuis 2026.4.23 peut-elle être mise à jour vers ce candidat et +nettoyer les débris de dépendances de plugins ? » : ```bash gh workflow run update-migration.yml \ @@ -149,53 +154,64 @@ gh workflow run update-migration.yml \ -f scenarios=plugin-deps-cleanup ``` -## Acceptation du paquet +## Package Acceptance -Package Acceptance est le garde-fou de paquet natif GitHub. Il résout un paquet -candidat en tarball `package-under-test`, enregistre la version et le SHA-256, puis -exécute des voies Docker E2E réutilisables contre cette tarball exacte. La référence du harnais -de workflow est séparée de la référence source du paquet, afin que la logique de test actuelle puisse valider -d’anciennes releases fiables. +Package Acceptance est la gate de package native GitHub. Elle résout un package +candidat en une tarball `package-under-test`, enregistre la version et le SHA-256, puis +exécute des lanes Docker E2E réutilisables contre cette tarball exacte. La ref du harnais de workflow +est séparée de la ref source du package, afin que la logique de test actuelle puisse valider +des releases de confiance plus anciennes. Sources candidates : - `source=npm` : valider `openclaw@beta`, `openclaw@latest` ou une version publiée exacte. -- `source=ref` : empaqueter une branche, une balise ou un commit fiable avec le harnais actuel +- `source=ref` : empaqueter une branche, un tag ou un commit de confiance avec le harnais actuel sélectionné. -- `source=url` : valider une tarball HTTPS avec `package_sha256` obligatoire. +- `source=url` : valider une tarball HTTPS avec `package_sha256` requis. - `source=artifact` : réutiliser une tarball téléversée par une autre exécution Actions. -Full Release Validation utilise `source=artifact` par défaut, construite depuis le +Full Release Validation utilise `source=artifact` par défaut, construit depuis le SHA de release résolu. Pour une preuve post-publication, passez `package_acceptance_package_spec=openclaw@YYYY.M.D` afin que la même matrice de mise à niveau -cible plutôt le paquet npm livré. +cible plutôt le package npm livré. -Les vérifications de release appellent Package Acceptance avec l’ensemble paquet/mise à jour/Plugin : +Les contrôles de release appellent Package Acceptance avec l’ensemble package/update/restart/plugin : ```text -doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update +doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update ``` -Elles passent aussi : +Lorsque le soak de release est activé, ils passent aussi : ```text -published_upgrade_survivor_baselines=all-since-2026.4.23 +published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15 published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -Cela garde la migration de paquet, le changement de canal de mise à jour, le nettoyage des dépendances -obsolètes de Plugins, la couverture hors ligne des Plugins, le comportement de mise à jour des Plugins et la QA de paquet -Telegram sur le même artefact résolu. +Cela garde la migration de package, le changement de canal de mise à jour, le nettoyage des dépendances +de plugins obsolètes, la couverture de plugins hors ligne, le comportement de mise à jour de plugins et la QA du package +Telegram sur le même artefact résolu, sans faire parcourir chaque release publiée +à la gate de package de release par défaut. -`all-since-2026.4.23` est l’échantillon de mise à niveau Full Release CI : chaque release stable publiée sur npm de `2026.4.23` jusqu’à `latest`. Pour une couverture exhaustive de migration -de mise à jour publiée, utilisez `all-since-2026.4.23` dans le workflow Update -Migration séparé au lieu de Full Release CI. `release-history` reste -disponible pour un échantillonnage manuel plus large quand vous voulez aussi l’ancre héritée +`last-stable-4` se résout aux quatre dernières releases OpenClaw stables publiées sur npm. +L’acceptation du package de release épingle `2026.4.23` comme première limite de compatibilité +de mise à jour des plugins, `2026.5.2` comme limite de turbulence d’architecture de plugins, et +`2026.4.15` comme base de mise à jour publiée 2026.4.1x plus ancienne ; le résolveur +déduplique les épingles déjà présentes dans les quatre dernières. Pour une couverture exhaustive de migration de +mise à jour publiée, utilisez `all-since-2026.4.23` dans le workflow Update Migration +séparé au lieu de la CI Full Release. `release-history` reste +disponible pour un échantillonnage manuel plus large lorsque vous voulez aussi l’ancre héritée antérieure à la date. -Exécutez manuellement un profil de paquet lors de la validation d’un candidat avant release : +Lorsque plusieurs bases published-upgrade survivor sont sélectionnées, le workflow Docker +réutilisable répartit chaque base dans son propre job de runner ciblé. Chaque +fragment de base exécute toujours l’ensemble de scénarios sélectionné, mais les journaux et artefacts restent +par base et le temps total est borné par le fragment le plus lent au lieu d’un gros +job sériel. + +Exécutez manuellement un profil de package lors de la validation d’un candidat avant release : ```bash gh workflow run package-acceptance.yml \ @@ -204,73 +220,77 @@ gh workflow run package-acceptance.yml \ -f source=npm \ -f package_spec=openclaw@beta \ -f suite_profile=package \ - -f published_upgrade_survivor_baselines=all-since-2026.4.23 \ + -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \ -f published_upgrade_survivor_scenarios=reported-issues \ -f telegram_mode=mock-openai ``` -Utilisez `suite_profile=product` quand la question de release inclut les canaux MCP, +Utilisez `suite_profile=product` lorsque la question de release inclut les canaux MCP, le nettoyage cron/sous-agent, la recherche web OpenAI ou OpenWebUI. Utilisez `suite_profile=full` -uniquement quand vous avez besoin d’une couverture Docker complète du chemin de release. +uniquement lorsque vous avez besoin d’une couverture Docker complète du chemin de release. ## Valeur par défaut de release -Pour les candidats de release, la pile de preuves par défaut est : +Pour les candidats de release, la pile de preuve par défaut est : 1. `pnpm check:changed` et `pnpm test:changed` pour les régressions au niveau source. -2. `pnpm release:check` pour l’intégrité de l’artefact de paquet. -3. Le profil `package` de Package Acceptance ou les voies de paquet personnalisées de release-check - pour les contrats d’installation/mise à jour/Plugin. -4. Les vérifications de release multi-OS pour le comportement propre aux installateurs, à l’onboarding et à la plateforme. -5. Les suites live uniquement lorsque la surface modifiée touche au comportement d’un fournisseur ou d’un service hébergé. +2. `pnpm release:check` pour l’intégrité de l’artefact de package. +3. Le profil `package` de Package Acceptance ou les lanes de package personnalisées des contrôles de release + pour les contrats d’installation/mise à jour/redémarrage/plugin. +4. Les contrôles de release inter-OS pour le comportement spécifique à l’OS de l’installateur, + de l’onboarding et de la plateforme. +5. Les suites live uniquement lorsque la surface modifiée touche au comportement d’un fournisseur ou d’un service + hébergé. -Sur les machines des mainteneurs, les grands garde-fous et les preuves produit Docker/paquet doivent s’exécuter -dans Testbox, sauf en cas de preuve locale explicite. +Sur les machines de mainteneurs, les gates larges et la preuve produit Docker/package doivent s’exécuter +dans Testbox sauf en cas de preuve locale explicite. ## Compatibilité héritée La tolérance de compatibilité est étroite et limitée dans le temps : -- Les paquets jusqu’à `2026.4.25`, y compris `2026.4.25-beta.*`, peuvent tolérer - les lacunes de métadonnées de paquet déjà livrées dans Package Acceptance. -- Le paquet publié `2026.4.26` peut avertir pour les fichiers d’estampille de métadonnées de build local - déjà livrés. -- Les paquets ultérieurs doivent satisfaire les contrats modernes. Les mêmes lacunes échouent au lieu - d’avertir ou de sauter. +- Les packages jusqu’à `2026.4.25`, y compris `2026.4.25-beta.*`, peuvent tolérer + les lacunes de métadonnées de package déjà livrées dans Package Acceptance. +- Le package publié `2026.4.26` peut 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 lacunes échouent au lieu + d’avertir ou de passer. N’ajoutez pas de nouvelles migrations au démarrage pour ces anciennes formes. Ajoutez ou étendez une réparation -doctor, puis prouvez-la avec `upgrade-survivor` ou `published-upgrade-survivor`. +doctor, puis prouvez-la avec `upgrade-survivor`, `published-upgrade-survivor` ou +`update-restart-auth` lorsque la commande de mise à jour possède le redémarrage. ## Ajouter de la couverture -Lorsque vous modifiez le comportement de mise à jour ou de Plugin, ajoutez une couverture à la couche la plus basse qui +Lorsque vous changez le comportement de mise à jour ou de plugins, ajoutez de la couverture à la couche la plus basse qui peut échouer pour la bonne raison : - Logique pure de chemin ou de métadonnées : test unitaire à côté de la source. -- Inventaire de paquet ou comportement de fichiers empaquetés : test `package-dist-inventory` ou - vérificateur de tarball. -- Comportement CLI d’installation/mise à jour : assertion ou fixture de voie Docker. +- Comportement d’inventaire de package ou de fichiers empaquetés : `package-dist-inventory` ou test de vérificateur + de tarball. +- Comportement CLI d’installation/mise à jour : assertion ou fixture de lane Docker. - Comportement de migration de release publiée : scénario `published-upgrade-survivor`. -- Comportement de registre/source de paquet : fixture `test:docker:plugins` ou serveur de fixture ClawHub. -- Comportement d’agencement ou de nettoyage des dépendances : affirmer à la fois l’exécution runtime et la - frontière du système de fichiers. Les dépendances npm peuvent être hissées sous la racine npm - gérée ; les tests doivent donc prouver que la racine est analysée/nettoyée au lieu de supposer une - arborescence `node_modules` locale au paquet. +- Comportement de redémarrage possédé par la mise à jour : `update-restart-auth`. +- Comportement de source registre/package : fixture `test:docker:plugins` ou serveur de fixture ClawHub. +- Comportement d’organisation ou de nettoyage des dépendances : vérifiez à la fois l’exécution runtime et la + limite du système de fichiers. Les dépendances npm peuvent être hissées sous la racine npm + gérée, les tests doivent donc prouver que la racine est analysée/nettoyée au lieu de supposer une + arborescence `node_modules` locale au package. Gardez les nouvelles fixtures Docker hermétiques par défaut. Utilisez des registres de fixtures locaux et -de faux paquets, sauf si le but du test est le comportement du registre live. +de faux packages, sauf si l’objectif du test est le comportement d’un registre live. ## Triage des échecs Commencez par l’identité de l’artefact : -- Résumé `resolve_package` de Package Acceptance : source, version, SHA-256 et +- Résumé `resolve_package` de l’acceptation du paquet : source, version, SHA-256 et nom de l’artefact. - Artefacts Docker : `.artifacts/docker-tests/**/summary.json`, - `failures.json`, journaux de voie et commandes de réexécution. -- Résumé upgrade survivor : `.artifacts/upgrade-survivor/summary.json`, - incluant la version de base, la version candidate, le scénario, les timings de phase et - les étapes de recette. + `failures.json`, journaux de voie d’exécution et commandes de relance. +- Résumé des éléments survivants à la mise à niveau : `.artifacts/upgrade-survivor/summary.json`, + comprenant la version de référence, la version candidate, le scénario, les durées + des phases et les étapes de la recette. -Préférez relancer la voie exacte échouée avec le même artefact de paquet plutôt que -relancer tout le parapluie de release. +Préférez relancer la voie d’exécution exacte qui a échoué avec le même artefact +de paquet plutôt que relancer toute l’ombrelle de publication. diff --git a/docs/fr/help/testing.md b/docs/fr/help/testing.md index 488c08c2d..949b80e5a 100644 --- a/docs/fr/help/testing.md +++ b/docs/fr/help/testing.md @@ -1,20 +1,21 @@ --- read_when: - - Exécution des tests localement ou en CI + - Exécuter les tests localement ou en intégration continue - Ajout de tests de régression pour les bogues de modèle/fournisseur - Débogage du comportement du Gateway et de l’agent -summary: 'Kit de test : suites unitaires/e2e/en direct, exécuteurs Docker et ce que couvre chaque test' +summary: 'Kit de test : suites unitaires/e2e/live, exécutants Docker et couverture de chaque test' title: Tests x-i18n: - generated_at: "2026-05-05T01:48:09Z" + generated_at: "2026-05-05T06:17:55Z" model: gpt-5.5 provider: openai - source_hash: 8d051bf6a01f6caf7755ad1d7107f21ae2d440b55a65bb7f18ee4a81f5f0e3b2 + source_hash: 63f27190fb00b7091c99f64edcb990be14b1025db89bc091d9c54bd1322dda24 source_path: help/testing.md workflow: 16 --- -OpenClaw dispose de trois suites Vitest (unitaire/intégration, e2e, live) et d’un petit ensemble d’exécuteurs Docker. Ce document est un guide « comment nous testons » : +OpenClaw comporte trois suites Vitest (unitaire/intégration, e2e, live) et un petit ensemble +d’exécuteurs Docker. Ce document est un guide « comment nous testons » : - Ce que couvre chaque suite (et ce qu’elle ne couvre délibérément _pas_). - Quelles commandes exécuter pour les workflows courants (local, avant push, débogage). @@ -28,73 +29,74 @@ OpenClaw dispose de trois suites Vitest (unitaire/intégration, e2e, live) et d - [QA Matrix](/fr/concepts/qa-matrix) — référence pour `pnpm openclaw qa matrix`. - [Canal QA](/fr/channels/qa-channel) — le Plugin de transport synthétique utilisé par les scénarios adossés au dépôt. -Cette page couvre l’exécution des suites de tests régulières et des exécuteurs Docker/Parallels. La section des exécuteurs propres à la QA ci-dessous ([Exécuteurs propres à la QA](#qa-specific-runners)) liste les invocations `qa` concrètes et renvoie aux références ci-dessus. +Cette page couvre l’exécution des suites de tests régulières et des exécuteurs Docker/Parallels. La section sur les exécuteurs spécifiques à la QA ci-dessous ([Exécuteurs spécifiques à la QA](#qa-specific-runners)) liste les invocations `qa` concrètes et renvoie aux références ci-dessus. ## Démarrage rapide La plupart du temps : -- Garde complète (attendue avant push) : `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Exécution locale plus rapide de toute la suite sur une machine confortable : `pnpm test:max` +- Gate complet (attendu avant un push) : `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Exécution complète plus rapide en local sur une machine confortable : `pnpm test:max` - Boucle de surveillance Vitest directe : `pnpm test:watch` -- Le ciblage direct de fichiers achemine maintenant aussi les chemins d’extensions/canaux : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Le ciblage direct de fichiers achemine aussi désormais les chemins d’extensions/canaux : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Privilégiez d’abord les exécutions ciblées lorsque vous itérez sur un seul échec. - Site QA adossé à Docker : `pnpm qa:lab:up` - Voie QA adossée à une VM Linux : `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Lorsque vous touchez aux tests ou souhaitez davantage de confiance : +Quand vous touchez aux tests ou voulez plus de confiance : -- Garde de couverture : `pnpm test:coverage` +- Gate de couverture : `pnpm test:coverage` - Suite E2E : `pnpm test:e2e` Lors du débogage de fournisseurs/modèles réels (nécessite de vrais identifiants) : -- Suite live (modèles + sondes d’outils/images Gateway) : `pnpm test:live` -- Cibler silencieusement un fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Rapports de performance d’exécution : déclencher `OpenClaw Performance` avec +- Suite live (modèles + sondes Gateway outil/image) : `pnpm test:live` +- Cibler un fichier live en mode silencieux : `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Rapports de performances d’exécution : déclenchez `OpenClaw Performance` avec `live_gpt54=true` pour un tour d’agent réel `openai/gpt-5.4` ou - `deep_profile=true` pour les artefacts CPU/tas/trace Kova. Les exécutions planifiées quotidiennes + `deep_profile=true` pour les artefacts CPU/tas/trace Kova. Les exécutions quotidiennes planifiées publient les artefacts des voies fournisseur simulé, profil profond et GPT 5.4 vers `openclaw/clawgrit-reports` lorsque `CLAWGRIT_REPORTS_TOKEN` est configuré. Le - rapport fournisseur simulé inclut aussi des mesures au niveau source sur le démarrage Gateway, la mémoire, - la pression des plugins, la boucle répétée hello-loop de faux modèle et le démarrage CLI. -- Balayage de modèles live Docker : `pnpm test:docker:live-models` - - Chaque modèle sélectionné exécute maintenant un tour de texte plus une petite sonde de type lecture de fichier. - Les modèles dont les métadonnées annoncent une entrée `image` exécutent aussi un minuscule tour d’image. + rapport fournisseur simulé inclut aussi les chiffres de démarrage Gateway au niveau source, de mémoire, + de pression Plugin, de boucle hello fake-model répétée et de démarrage CLI. +- Balayage Docker des modèles live : `pnpm test:docker:live-models` + - Chaque modèle sélectionné exécute désormais un tour texte plus une petite sonde de type lecture de fichier. + Les modèles dont les métadonnées annoncent une entrée `image` exécutent aussi un minuscule tour image. Désactivez les sondes supplémentaires avec `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` lorsque vous isolez des échecs de fournisseur. - - Couverture CI : les vérifications quotidiennes `OpenClaw Scheduled Live And E2E Checks` et manuelles - `OpenClaw Release Checks` appellent toutes deux le workflow réutilisable live/E2E avec - `include_live_suites: true`, ce qui inclut des jobs de matrice de modèles live Docker distincts - découpés par fournisseur. - - Pour des réexécutions CI ciblées, déclenchez `OpenClaw Live And E2E Checks (Reusable)` + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` lorsque vous isolez des échecs fournisseur. + - Couverture CI : les workflows quotidiens `OpenClaw Scheduled Live And E2E Checks` et manuels + `OpenClaw Release Checks` appellent tous deux le workflow live/E2E réutilisable avec + `include_live_suites: true`, ce qui inclut des jobs de matrice Docker de modèles live séparés, + partitionnés par fournisseur. + - Pour des relances CI ciblées, déclenchez `OpenClaw Live And E2E Checks (Reusable)` avec `include_live_suites: true` et `live_models_only: true`. - Ajoutez les nouveaux secrets fournisseur à fort signal à `scripts/ci-hydrate-live-auth.sh` ainsi qu’à `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` et à ses - appelants planifiés/de publication. -- Smoke de conversation liée Codex natif : `pnpm test:docker:live-codex-bind` - - Exécute une voie live Docker contre le chemin serveur d’application Codex, lie un DM Slack synthétique + appelants planifiés/release. +- Smoke de discussion liée Codex native : `pnpm test:docker:live-codex-bind` + - Exécute une voie live Docker contre le chemin app-server Codex, lie un DM Slack synthétique avec `/codex bind`, exerce `/codex fast` et - `/codex permissions`, puis vérifie qu’une réponse simple et qu’une pièce jointe image - transitent par la liaison Plugin native au lieu d’ACP. -- Smoke du harnais serveur d’application Codex : `pnpm test:docker:live-codex-harness` - - Exécute des tours d’agent Gateway via le harnais serveur d’application Codex détenu par le Plugin, + `/codex permissions`, puis vérifie qu’une réponse simple et une pièce jointe image + passent par la liaison Plugin native au lieu d’ACP. +- Smoke du harnais app-server Codex : `pnpm test:docker:live-codex-harness` + - Exécute les tours d’agent Gateway via le harnais app-server Codex appartenant au Plugin, vérifie `/codex status` et `/codex models`, et exerce par défaut les sondes image, - Cron MCP, sous-agent et Guardian. Désactivez la sonde de sous-agent avec - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` lorsque vous isolez d’autres échecs du - serveur d’application Codex. Pour une vérification ciblée du sous-agent, désactivez les autres sondes : + MCP Cron, sous-agent et Guardian. Désactivez la sonde sous-agent avec + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` lorsque vous isolez d’autres échecs + app-server Codex. Pour une vérification sous-agent ciblée, désactivez les autres sondes : `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Cela se termine après la sonde de sous-agent sauf si + Cela quitte après la sonde sous-agent sauf si `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` est défini. - Smoke de commande de secours Crestodian : `pnpm test:live:crestodian-rescue-channel` - - Vérification opt-in redondante pour la surface de commande de secours du canal de messages. + - Vérification opt-in de précaution de la surface de commande de secours du canal de messages. Elle exerce `/crestodian status`, met en file d’attente un changement de modèle persistant, répond `/crestodian yes`, et vérifie le chemin d’écriture audit/config. - Smoke Docker du planificateur Crestodian : `pnpm test:docker:crestodian-planner` - - Exécute Crestodian dans un conteneur sans configuration avec une fausse CLI Claude dans le `PATH` - et vérifie que le repli du planificateur approximatif se traduit par une écriture de configuration typée auditée. -- Smoke Docker de première exécution Crestodian : `pnpm test:docker:crestodian-first-run` + - Exécute Crestodian dans un conteneur sans configuration avec une fausse CLI Claude dans `PATH` + et vérifie que le repli du planificateur approximatif se traduit par une écriture de configuration typée + auditée. +- Smoke Docker du premier lancement Crestodian : `pnpm test:docker:crestodian-first-run` - Démarre depuis un répertoire d’état OpenClaw vide, achemine `openclaw` nu vers Crestodian, applique les écritures setup/modèle/agent/Plugin Discord + SecretRef, valide la configuration et vérifie les entrées d’audit. Le même chemin de configuration Ring 0 est @@ -103,124 +105,127 @@ Lors du débogage de fournisseurs/modèles réels (nécessite de vrais identifia - Smoke de coût Moonshot/Kimi : avec `MOONSHOT_API_KEY` défini, exécutez `openclaw models list --provider moonshot --json`, puis exécutez un `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - isolé contre `moonshot/kimi-k2.6`. Vérifiez que le JSON signale Moonshot/K2.6 et que le - transcript de l’assistant stocke `usage.cost` normalisé. + isolé contre `moonshot/kimi-k2.6`. Vérifiez que le JSON indique Moonshot/K2.6 et que la + transcription de l’assistant stocke `usage.cost` normalisé. -Lorsque vous n’avez besoin que d’un cas en échec, privilégiez le ciblage des tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. +Lorsque vous n’avez besoin que d’un cas en échec, privilégiez le rétrécissement des tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. -## Exécuteurs propres à la QA +## Exécuteurs spécifiques à la QA -Ces commandes accompagnent les suites de tests principales lorsque vous avez besoin du réalisme de QA-lab : +Ces commandes complètent les suites de tests principales lorsque vous avez besoin du réalisme QA Lab : -La CI exécute QA Lab dans des workflows dédiés. La parité agentique est imbriquée sous -`QA-Lab - All Lanes` et la validation de publication, pas dans un workflow PR autonome. +CI exécute QA Lab dans des workflows dédiés. La parité agentique est imbriquée sous +`QA-Lab - All Lanes` et la validation de release, et non dans un workflow PR autonome. La validation large doit utiliser `Full Release Validation` avec -`rerun_group=qa-parity` ou le groupe QA des vérifications de publication. Les vérifications de publication stables/par défaut -gardent le soak live/Docker exhaustif derrière `run_release_soak=true` ; le -profil `full` force l’activation du soak. `QA-Lab - All Lanes` -s’exécute chaque nuit sur `main` et depuis un déclenchement manuel avec la voie de parité simulée, la voie Matrix live, la voie Telegram live gérée par Convex et la voie Discord live gérée par Convex comme jobs parallèles. La QA planifiée et les vérifications de publication passent Matrix -`--profile fast` explicitement, tandis que la CLI Matrix et l’entrée de workflow manuelle -restent par défaut sur `all` ; un déclenchement manuel peut découper `all` en jobs `transport`, +`rerun_group=qa-parity` ou le groupe QA des release-checks. Les vérifications de release stables/par défaut +gardent le trempage live/Docker exhaustif derrière `run_release_soak=true` ; le +profil `full` force l’activation du trempage. `QA-Lab - All Lanes` +s’exécute chaque nuit sur `main` et depuis un déclenchement manuel avec la voie de parité simulée, la voie +Matrix live, la voie Telegram live gérée par Convex et la voie Discord +live gérée par Convex sous forme de jobs parallèles. Les vérifications QA planifiées et de release passent explicitement +Matrix `--profile fast`, tandis que la CLI Matrix et l’entrée du workflow manuel +restent par défaut sur `all` ; le déclenchement manuel peut partitionner `all` en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`. `OpenClaw Release -Checks` exécute la parité plus les voies Matrix rapide et Telegram avant l’approbation de publication, -en utilisant `mock-openai/gpt-5.5` pour les vérifications de transport de publication afin qu’elles restent -déterministes et évitent le démarrage normal du Plugin fournisseur. Ces passerelles de transport live +Checks` exécute la parité plus les voies Matrix rapide et Telegram avant l’approbation de release, +en utilisant `mock-openai/gpt-5.5` pour les vérifications de transport de release afin qu’elles restent +déterministes et évitent le démarrage normal du Plugin fournisseur. Ces Gateway de transport live désactivent la recherche mémoire ; le comportement mémoire reste couvert par les suites de parité QA. -Les shards de médias live de publication complète utilisent -`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, qui contient déjà -`ffmpeg` et `ffprobe`. Les shards de modèles/backends live Docker utilisent l’image partagée -`ghcr.io/openclaw/openclaw-live-test:` construite une fois par commit sélectionné, -puis la récupèrent avec `OPENCLAW_SKIP_DOCKER_BUILD=1` au lieu de reconstruire -dans chaque shard. +Les partitions live media de release complète utilisent +`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, qui dispose déjà de +`ffmpeg` et `ffprobe`. Les partitions Docker de modèles/backends live utilisent l’image partagée +`ghcr.io/openclaw/openclaw-live-test:` construite une seule fois par commit sélectionné, +puis la téléchargent avec `OPENCLAW_SKIP_DOCKER_BUILD=1` au lieu de reconstruire +dans chaque partition. - `pnpm openclaw qa suite` - Exécute les scénarios QA adossés au dépôt directement sur l’hôte. - - Exécute par défaut plusieurs scénarios sélectionnés en parallèle avec des workers - Gateway isolés. `qa-channel` utilise par défaut une concurrence de 4 (limitée par le - nombre de scénarios sélectionnés). Utilisez `--concurrency ` pour ajuster le - nombre de workers, ou `--concurrency 1` pour l’ancienne voie série. + - Exécute par défaut plusieurs scénarios sélectionnés en parallèle avec des + workers Gateway isolés. `qa-channel` utilise par défaut une concurrence de 4 (limitée par le + nombre de scénarios sélectionnés). Utilisez `--concurrency ` pour ajuster le nombre de + workers, ou `--concurrency 1` pour l’ancienne voie sérielle. - Se termine avec un code non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque vous - voulez des artefacts sans code de sortie d’échec. - - Prend en charge les modes de fournisseur `live-frontier`, `mock-openai` et `aimock`. - `aimock` démarre un serveur de fournisseur local adossé à AIMock pour une couverture expérimentale - des fixtures et des mocks de protocole sans remplacer la voie `mock-openai` sensible aux scénarios. + voulez obtenir les artefacts sans code de sortie en échec. + - Prend en charge les modes fournisseur `live-frontier`, `mock-openai` et `aimock`. + `aimock` lance un serveur fournisseur local adossé à AIMock pour une couverture expérimentale + des fixtures et des mocks de protocole sans remplacer la voie `mock-openai` + sensible aux scénarios. - `pnpm test:plugins:kitchen-sink-live` - - Exécute le parcours d’épreuves live du Plugin OpenAI Kitchen Sink via QA Lab. Il - installe le paquet Kitchen Sink externe, vérifie l’inventaire de la surface du SDK de plugin, - sonde `/healthz` et `/readyz`, enregistre les preuves CPU/RSS du Gateway, + - Exécute le parcours complet live du Plugin OpenAI Kitchen Sink via QA Lab. Il + installe le package Kitchen Sink externe, vérifie l’inventaire de la surface du SDK Plugin, + sonde `/healthz` et `/readyz`, enregistre des preuves CPU/RSS du Gateway, exécute un tour OpenAI live et vérifie les diagnostics adversariaux. Nécessite une authentification OpenAI live comme `OPENAI_API_KEY`. Dans les sessions Testbox hydratées, il source automatiquement le profil d’authentification live Testbox lorsque l’assistant `openclaw-testbox-env` est présent. - `pnpm test:gateway:cpu-scenarios` - - Exécute le banc de démarrage du Gateway plus un petit ensemble de scénarios QA Lab simulés + - Exécute le banc de démarrage du Gateway plus un petit pack de scénarios mock QA Lab (`channel-chat-baseline`, `memory-failure-fallback`, `gateway-restart-inflight-run`) et écrit un résumé combiné des observations CPU sous `.artifacts/gateway-cpu-scenarios/`. - - Signale par défaut uniquement les observations de CPU chaud soutenu (`--cpu-core-warn` - plus `--hot-wall-warn-ms`), afin que les courts pics de démarrage soient enregistrés comme métriques + - Signale par défaut uniquement les observations de CPU chaud soutenues (`--cpu-core-warn` + plus `--hot-wall-warn-ms`), afin que les brefs pics de démarrage soient enregistrés comme métriques sans ressembler à la régression de Gateway bloqué pendant plusieurs minutes. - - Utilise les artefacts `dist` construits ; exécutez d’abord une construction lorsque le checkout ne - dispose pas déjà d’une sortie runtime fraîche. + - Utilise les artefacts `dist` générés ; lancez d’abord un build lorsque le checkout ne dispose pas + déjà d’une sortie d’exécution fraîche. - `pnpm openclaw qa suite --runner multipass` - Exécute la même suite QA dans une VM Linux Multipass jetable. - Conserve le même comportement de sélection de scénarios que `qa suite` sur l’hôte. - - Réutilise les mêmes options de sélection de fournisseur/modèle que `qa suite`. + - Réutilise les mêmes flags de sélection fournisseur/modèle que `qa suite`. - Les exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour l’invité : - clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA live, et `CODEX_HOME` + clés fournisseur basées sur l’env, chemin de configuration du fournisseur QA live, et `CODEX_HOME` lorsqu’il est présent. - Les répertoires de sortie doivent rester sous la racine du dépôt afin que l’invité puisse réécrire via l’espace de travail monté. - - Écrit le rapport QA normal + le résumé ainsi que les journaux Multipass sous + - Écrit le rapport QA normal, le résumé et les journaux Multipass sous `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Démarre le site QA adossé à Docker pour le travail QA de style opérateur. + - Démarre le site QA adossé à Docker pour le travail QA de type opérateur. - `pnpm test:docker:npm-onboard-channel-agent` - - Construit un tarball npm à partir du checkout actuel, l’installe globalement dans - Docker, exécute l’onboarding non interactif par clé d’API OpenAI, configure Telegram - par défaut, vérifie que le runtime de plugin empaqueté se charge sans réparation de dépendances + - Construit une archive tar npm depuis le checkout courant, l’installe globalement dans + Docker, exécute l’onboarding non interactif avec clé API OpenAI, configure Telegram + par défaut, vérifie que le runtime Plugin packagé se charge sans réparation de dépendances au démarrage, exécute doctor, puis exécute un tour d’agent local contre un - endpoint OpenAI simulé. - - Utilisez `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` pour exécuter la même voie d’installation empaquetée + endpoint OpenAI mocké. + - Utilisez `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` pour exécuter la même voie d’installation packagée avec Discord. - `pnpm test:docker:session-runtime-context` - - Exécute un smoke Docker déterministe de l’application construite pour les transcriptions de contexte runtime - embarqué. Il vérifie que le contexte runtime OpenClaw masqué est persisté comme un - message personnalisé non affiché au lieu de fuir dans le tour utilisateur visible, - puis initialise une session JSONL cassée affectée et vérifie que - `openclaw doctor --fix` la réécrit vers la branche active avec une sauvegarde. + - Exécute un smoke Docker déterministe de l’application construite pour les transcripts de contexte runtime + intégré. Il vérifie que le contexte runtime OpenClaw masqué est persisté comme + message personnalisé non affiché au lieu de fuiter dans le tour utilisateur visible, + puis amorce un JSONL de session cassé affecté et vérifie que + `openclaw doctor --fix` le réécrit vers la branche active avec une sauvegarde. - `pnpm test:docker:npm-telegram-live` - - Installe un paquet candidat OpenClaw dans Docker, exécute l’onboarding du paquet installé, + - Installe un package candidat OpenClaw dans Docker, exécute l’onboarding du package installé, configure Telegram via la CLI installée, puis réutilise la voie QA Telegram live - avec ce paquet installé comme Gateway SUT. + avec ce package installé comme Gateway SUT. - Utilise par défaut `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta` ; définissez `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` ou - `OPENCLAW_CURRENT_PACKAGE_TGZ` pour tester un tarball local résolu au lieu - d’installer depuis le registre. - - Utilise les mêmes identifiants d’environnement Telegram ou la même source d’identifiants Convex que + `OPENCLAW_CURRENT_PACKAGE_TGZ` pour tester une archive tar locale résolue au lieu d’une + installation depuis le registre. + - Utilise les mêmes identifiants env Telegram ou source d’identifiants Convex que `pnpm openclaw qa telegram`. Pour l’automatisation CI/release, définissez - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` plus + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` ainsi que `OPENCLAW_QA_CONVEX_SITE_URL` et le secret de rôle. Si `OPENCLAW_QA_CONVEX_SITE_URL` et un secret de rôle Convex sont présents en CI, - le wrapper Docker sélectionne automatiquement Convex. - - Le wrapper valide l’environnement des identifiants Telegram ou Convex sur l’hôte avant - le travail de construction/installation Docker. Définissez `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` + le wrapper Docker sélectionne Convex automatiquement. + - Le wrapper valide l’env d’identifiants Telegram ou Convex sur l’hôte avant le + travail de build/installation Docker. Définissez `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1` uniquement lors du débogage volontaire de la configuration préalable aux identifiants. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` remplace le `OPENCLAW_QA_CREDENTIAL_ROLE` partagé pour cette voie uniquement. - - GitHub Actions expose cette voie comme workflow manuel mainteneur - `NPM Telegram Beta E2E`. Il ne s’exécute pas lors d’un merge. Le workflow utilise l’environnement + - GitHub Actions expose cette voie comme workflow mainteneur manuel + `NPM Telegram Beta E2E`. Il ne s’exécute pas à la fusion. Le workflow utilise l’environnement `qa-live-shared` et les baux d’identifiants CI Convex. -- GitHub Actions expose également `Package Acceptance` pour une preuve produit exécutée en parallèle - contre un paquet candidat. Il accepte une ref de confiance, une spécification npm publiée, - une URL de tarball HTTPS plus SHA-256, ou un artefact tarball d’une autre exécution, téléverse +- GitHub Actions expose aussi `Package Acceptance` pour une preuve produit en exécution latérale + contre un package candidat. Il accepte une ref de confiance, une spécification npm publiée, + une URL d’archive tar HTTPS avec SHA-256, ou un artefact d’archive tar depuis une autre exécution, téléverse le `openclaw-current.tgz` normalisé comme `package-under-test`, puis exécute le - planificateur Docker E2E existant avec des profils de voie smoke, package, product, full ou custom. - Définissez `telegram_mode=mock-openai` ou `live-frontier` pour exécuter le - workflow QA Telegram contre le même artefact `package-under-test`. + planificateur Docker E2E existant avec les profils de voie smoke, package, produit, complet ou personnalisé. + Définissez `telegram_mode=mock-openai` ou `live-frontier` pour exécuter le workflow QA + Telegram contre le même artefact `package-under-test`. - Preuve produit de la dernière bêta : ```bash @@ -231,7 +236,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- La preuve par URL exacte de tarball nécessite un condensat : +- La preuve par URL exacte d’archive tar nécessite un condensat : ```bash gh workflow run package-acceptance.yml --ref main \ @@ -241,7 +246,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- La preuve par artefact télécharge un artefact tarball depuis une autre exécution Actions : +- La preuve par artefact télécharge un artefact d’archive tar depuis une autre exécution Actions : ```bash gh workflow run package-acceptance.yml --ref main \ @@ -252,102 +257,103 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - Emballe et installe la construction OpenClaw actuelle dans Docker, démarre le Gateway - avec OpenAI configuré, puis active les canaux/plugins groupés via des modifications - de configuration. - - Vérifie que la découverte de configuration laisse absents les plugins téléchargeables non configurés, - que la première réparation doctor configurée installe explicitement chaque plugin téléchargeable - manquant, et qu’un second redémarrage n’exécute pas de réparation de dépendances masquée. - - Installe également une ancienne baseline npm connue, active Telegram avant d’exécuter - `openclaw update --tag `, et vérifie que le doctor post-mise à jour du candidat - nettoie les débris de dépendances de plugin hérités sans réparation postinstall côté - harnais. + - Package et installe la build OpenClaw courante dans Docker, démarre le Gateway + avec OpenAI configuré, puis active les channels/Plugins groupés via des modifications + de config. + - Vérifie que la découverte de configuration laisse absents les Plugins téléchargeables non configurés, + que la première réparation doctor configurée installe explicitement chaque Plugin téléchargeable + manquant, et qu’un second redémarrage n’exécute pas de réparation de dépendances + masquée. + - Installe aussi une ancienne baseline npm connue, active Telegram avant d’exécuter + `openclaw update --tag `, et vérifie que le doctor post-mise à jour + du candidat nettoie les débris de dépendances Plugin héritées sans + réparation postinstall côté harnais. - `pnpm test:parallels:npm-update` - - Exécute le smoke natif de mise à jour d’installation empaquetée sur des invités Parallels. Chaque - plateforme sélectionnée installe d’abord le paquet baseline demandé, puis exécute + - Exécute le smoke de mise à jour d’installation packagée native sur des invités Parallels. Chaque + plateforme sélectionnée installe d’abord le package baseline demandé, puis exécute la commande `openclaw update` installée dans le même invité et vérifie la - version installée, le statut de mise à jour, la disponibilité du Gateway et un tour d’agent local. + version installée, l’état de mise à jour, la disponibilité du Gateway et un tour d’agent + local. - Utilisez `--platform macos`, `--platform windows` ou `--platform linux` pendant - l’itération sur un invité. Utilisez `--json` pour le chemin de l’artefact de résumé et - le statut par voie. - - La voie OpenAI utilise par défaut `openai/gpt-5.5` pour la preuve de tour d’agent live. - Passez `--model ` ou définissez + l’itération sur un seul invité. Utilisez `--json` pour le chemin de l’artefact de résumé et + l’état par voie. + - La voie OpenAI utilise `openai/gpt-5.5` pour la preuve de tour d’agent live par + défaut. Passez `--model ` ou définissez `OPENCLAW_PARALLELS_OPENAI_MODEL` lorsque vous validez volontairement un autre modèle OpenAI. - - Encapsulez les longues exécutions locales dans un timeout hôte afin que les blocages de transport - Parallels ne consomment pas le reste de la fenêtre de test : + - Encadrez les longues exécutions locales avec un timeout hôte afin que les blocages de transport Parallels ne puissent pas + consommer le reste de la fenêtre de test : ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Le script écrit des journaux de voie imbriqués sous `/tmp/openclaw-parallels-npm-update.*`. + - Le script écrit les journaux de voie imbriqués sous `/tmp/openclaw-parallels-npm-update.*`. Inspectez `windows-update.log`, `macos-update.log` ou `linux-update.log` avant de supposer que le wrapper externe est bloqué. - - La mise à jour Windows peut passer 10 à 15 minutes dans doctor post-mise à jour et le travail de - mise à jour de paquet sur un invité froid ; cela reste sain lorsque le journal de débogage npm + - La mise à jour Windows peut passer 10 à 15 minutes dans le doctor post-mise à jour et le travail de + mise à jour du package sur un invité froid ; cela reste sain lorsque le journal de débogage npm imbriqué progresse. - N’exécutez pas ce wrapper agrégé en parallèle avec les voies smoke Parallels - macOS, Windows ou Linux individuelles. Elles partagent l’état de VM et peuvent entrer en collision sur - la restauration d’instantané, la diffusion de paquet ou l’état du Gateway invité. - - La preuve post-mise à jour exécute la surface normale des plugins groupés, car - les façades de capacité comme la parole, la génération d’images et la compréhension - multimédia sont chargées via les API runtime groupées même lorsque le tour - d’agent lui-même ne vérifie qu’une simple réponse texte. + macOS, Windows ou Linux individuelles. Elles partagent l’état de VM et peuvent entrer en collision lors de + la restauration de snapshot, du service de package ou de l’état du Gateway invité. + - La preuve post-mise à jour exécute la surface normale des Plugins groupés, car + les façades de capacité telles que la parole, la génération d’images et la compréhension + média sont chargées via les API runtime groupées même lorsque le tour d’agent + lui-même ne vérifie qu’une simple réponse textuelle. - `pnpm openclaw qa aimock` - - Démarre uniquement le serveur de fournisseur AIMock local pour les tests smoke directs - du protocole. + - Démarre uniquement le serveur fournisseur AIMock local pour des tests smoke directs du protocole. - `pnpm openclaw qa matrix` - - Exécute la voie QA live Matrix contre un serveur domestique Tuwunel jetable adossé à Docker. Checkout source uniquement — les installations empaquetées ne livrent pas `qa-lab`. - - CLI complète, catalogue de profils/scénarios, variables d’environnement et disposition des artefacts : [QA Matrix](/fr/concepts/qa-matrix). + - Exécute la voie QA live Matrix contre un homeserver Tuwunel jetable adossé à Docker. Checkout source uniquement — les installations packagées n’expédient pas `qa-lab`. + - CLI complète, catalogue profil/scénario, variables d’env et disposition des artefacts : [QA Matrix](/fr/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Exécute la voie QA live Telegram contre un vrai groupe privé avec les jetons du bot pilote et du bot SUT provenant de l’environnement. - - Nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’id du groupe doit être l’id numérique du chat Telegram. - - Prend en charge `--credential-source convex` pour des identifiants groupés partagés. Utilisez le mode env par défaut, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour opter pour des baux groupés. + - Exécute la voie QA live Telegram contre un vrai groupe privé à l’aide des tokens des bots driver et SUT provenant de l’env. + - Nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’id du groupe doit être l’id de chat numérique Telegram. + - Prend en charge `--credential-source convex` pour les identifiants mutualisés partagés. Utilisez le mode env par défaut, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour opter pour les baux mutualisés. - Se termine avec un code non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque vous - voulez des artefacts sans code de sortie d’échec. - - Nécessite deux bots distincts dans le même groupe privé, le bot SUT exposant un nom d’utilisateur Telegram. - - Pour une observation bot-à-bot stable, activez Bot-to-Bot Communication Mode dans `@BotFather` pour les deux bots et assurez-vous que le bot pilote peut observer le trafic de bots du groupe. - - Écrit un rapport QA Telegram, un résumé et un artefact de messages observés sous `.artifacts/qa-e2e/...`. Les scénarios avec réponse incluent le RTT entre la requête d’envoi du pilote et la réponse SUT observée. + voulez obtenir les artefacts sans code de sortie en échec. + - Nécessite deux bots distincts dans le même groupe privé, avec le bot SUT exposant un nom d’utilisateur Telegram. + - Pour une observation stable de bot à bot, activez le mode de communication bot à bot dans `@BotFather` pour les deux bots et assurez-vous que le bot driver peut observer le trafic de bots du groupe. + - Écrit un rapport QA Telegram, un résumé et un artefact de messages observés sous `.artifacts/qa-e2e/...`. Les scénarios avec réponse incluent le RTT depuis la requête d’envoi du driver jusqu’à la réponse SUT observée. -Les voies de transport live partagent un contrat standard afin que les nouveaux transports ne divergent pas ; la matrice de couverture par voie se trouve dans [vue d’ensemble QA → Couverture du transport live](/fr/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` est la suite synthétique large et ne fait pas partie de cette matrice. +Les voies de transport live partagent un contrat standard afin que les nouveaux transports ne divergent pas ; la matrice de couverture par voie se trouve dans [vue d’ensemble QA → couverture de transport live](/fr/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` est la suite synthétique large et ne fait pas partie de cette matrice. ### Identifiants Telegram partagés via Convex (v1) Lorsque `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) est activé pour -`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie des heartbeats -pour ce bail pendant l’exécution de la voie, et libère le bail à l’arrêt. +`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie des Heartbeat +pour ce bail pendant l’exécution de la voie, puis libère le bail à l’arrêt. -Échafaudage du projet Convex de référence : +Scaffold de référence du projet Convex : - `qa/convex-credential-broker/` -Variables d’environnement requises : +Variables d’env requises : - `OPENCLAW_QA_CONVEX_SITE_URL` (par exemple `https://your-deployment.convex.site`) - Un secret pour le rôle sélectionné : - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` pour `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` pour `ci` -- Sélection du rôle d’identifiant : +- Sélection du rôle d’identifiants : - CLI : `--credential-role maintainer|ci` - - Valeur par défaut env : `OPENCLAW_QA_CREDENTIAL_ROLE` (par défaut `ci` en CI, sinon `maintainer`) + - Valeur env par défaut : `OPENCLAW_QA_CREDENTIAL_ROLE` (valeur par défaut `ci` en CI, `maintainer` sinon) -Variables d’environnement facultatives : +Variables d’env facultatives : -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (par défaut `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (par défaut `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (par défaut `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (par défaut `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (par défaut `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (valeur par défaut `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (valeur par défaut `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (valeur par défaut `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (valeur par défaut `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (valeur par défaut `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de trace facultatif) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` autorise les URL Convex `http://` en local loopback pour le développement local uniquement. `OPENCLAW_QA_CONVEX_SITE_URL` doit utiliser `https://` en fonctionnement normal. -Les commandes d’administration pour les mainteneurs (pool add/remove/list) exigent -spécifiquement `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Les commandes d’administration des mainteneurs (pool add/remove/list) nécessitent spécifiquement +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Assistants CLI pour les mainteneurs : @@ -358,10 +364,10 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Utilisez `doctor` avant les exécutions en conditions réelles pour vérifier l’URL du site Convex, les secrets du courtier, +Utilisez `doctor` avant les exécutions live pour vérifier l’URL du site Convex, les secrets du broker, le préfixe d’endpoint, le délai d’expiration HTTP et l’accessibilité admin/list sans afficher -les valeurs secrètes. Utilisez `--json` pour une sortie lisible par machine dans les scripts et les utilitaires -de CI. +les valeurs secrètes. Utilisez `--json` pour une sortie lisible par machine dans les scripts et les +utilitaires CI. Contrat d’endpoint par défaut (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`) : @@ -381,162 +387,161 @@ Contrat d’endpoint par défaut (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentia - `POST /admin/remove` (secret mainteneur uniquement) - Requête : `{ credentialId, actorId }` - Succès : `{ status: "ok", changed, credential }` - - Protection contre un bail actif : `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Protection de bail actif : `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (secret mainteneur uniquement) - Requête : `{ kind?, status?, includePayload?, limit? }` - Succès : `{ status: "ok", credentials, count }` -Forme du payload pour le type Telegram : +Forme du payload pour le kind Telegram : - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` doit être une chaîne d’identifiant de discussion Telegram numérique. +- `groupId` doit être une chaîne d’identifiant numérique de chat Telegram. - `admin/add` valide cette forme pour `kind: "telegram"` et rejette les payloads mal formés. -### Ajouter un canal à la QA +### Ajouter un canal à QA -L’architecture et les noms d’assistants de scénarios pour les nouveaux adaptateurs de canal se trouvent dans [Vue d’ensemble QA → Ajouter un canal](/fr/concepts/qa-e2e-automation#adding-a-channel). Le minimum requis : implémenter le lanceur de transport sur la couture d’hôte partagée `qa-lab`, déclarer `qaRunners` dans le manifeste du plugin, monter sous `openclaw qa ` et écrire les scénarios sous `qa/scenarios/`. +L’architecture et les noms d’assistants de scénario pour les nouveaux adaptateurs de canal se trouvent dans [Vue d’ensemble QA → Ajouter un canal](/fr/concepts/qa-e2e-automation#adding-a-channel). Le minimum requis : implémenter le runner de transport sur la seam d’hôte `qa-lab` partagée, déclarer `qaRunners` dans le manifeste du plugin, monter en tant que `openclaw qa ` et rédiger les scénarios sous `qa/scenarios/`. ## Suites de tests (ce qui s’exécute où) -Considérez les suites comme un « réalisme croissant » (et une instabilité/un coût croissants) : +Considérez les suites comme un « réalisme croissant » (avec une instabilité et un coût croissants) : ### Unitaires / intégration (par défaut) - Commande : `pnpm test` -- Config : les exécutions non ciblées utilisent l’ensemble de shards `vitest.full-*.config.ts` et peuvent développer des shards multiprojets en configs par projet pour la planification parallèle +- Config : les exécutions non ciblées utilisent l’ensemble de shards `vitest.full-*.config.ts` et peuvent développer les shards multiprojets en configs par projet pour la planification parallèle - Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts` et `test/**/*.test.ts` ; les tests unitaires UI s’exécutent dans le shard dédié `unit-ui` - Portée : - Tests unitaires purs - - Tests d’intégration in-process (authentification du Gateway, routage, outillage, analyse, configuration) - - Régressions déterministes pour les bogues connus + - Tests d’intégration in-process (authentification Gateway, routage, outils, analyse, config) + - Régressions déterministes pour des bogues connus - Attentes : - S’exécute en CI - Aucune vraie clé requise - Doit être rapide et stable - - Les tests du résolveur et du chargeur de surface publique doivent prouver le comportement de repli large de `api.js` et - `runtime-api.js` avec de minuscules fixtures de plugin générées, et non - les vraies API sources de plugins intégrés. Les chargements de vraies API de plugins appartiennent aux - suites de contrat/intégration possédées par les plugins. + - Les tests de résolveur et de chargeur de surface publique doivent prouver le comportement de repli large de `api.js` et + `runtime-api.js` avec de minuscules fixtures de plugin générées, pas avec + de vraies API source de plugin intégré. Les chargements réels d’API de plugin appartiennent aux + suites de contrat/intégration possédées par le plugin. - + - - `pnpm test` non ciblé exécute douze configs de shards plus petites (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d’un énorme processus natif de projet racine. Cela réduit le pic RSS sur les machines chargées et évite que le travail auto-reply/extension affame les suites sans rapport. - - `pnpm test --watch` utilise toujours le graphe de projets racine natif `vitest.config.ts`, car une boucle de surveillance multi-shard n’est pas pratique. - - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` acheminent d’abord les cibles explicites de fichiers/répertoires par des voies à portée limitée, de sorte que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite de payer le coût de démarrage complet du projet racine. - - `pnpm test:changed` développe par défaut les chemins git modifiés en voies à portée limitée peu coûteuses : modifications directes de tests, fichiers frères `*.test.ts`, mappages source explicites et dépendants locaux du graphe d’importation. Les modifications de config/setup/package ne lancent pas de tests larges, sauf si vous utilisez explicitement `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` est la barrière normale de vérification locale intelligente pour les travaux étroits. Elle classe le diff en core, tests core, extensions, tests d’extension, apps, docs, métadonnées de release, outillage Docker réel et outillage, puis exécute les commandes de typecheck, lint et garde correspondantes. Elle n’exécute pas les tests Vitest ; appelez `pnpm test:changed` ou `pnpm test ` explicite pour une preuve de test. Les augmentations de version limitées aux métadonnées de release exécutent des vérifications ciblées de version/config/dépendances racine, avec une garde qui rejette les changements de package en dehors du champ de version de premier niveau. - - Les modifications du harnais Docker ACP réel exécutent des vérifications ciblées : syntaxe shell pour les scripts d’authentification Docker réels et dry-run du planificateur Docker réel. Les changements de `package.json` ne sont inclus que lorsque le diff se limite à `scripts["test:docker:live-*"]` ; les modifications de dépendances, exports, version et autres surfaces de package utilisent toujours les gardes plus larges. - - Les tests unitaires légers en imports depuis les agents, commandes, plugins, assistants auto-reply, `plugin-sdk` et zones d’utilitaires purs similaires passent par la voie `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers avec état ou lourds en runtime restent sur les voies existantes. - - Certains fichiers sources d’assistants `plugin-sdk` et `commands` sélectionnés mappent également les exécutions en mode changed vers des tests frères explicites dans ces voies légères, de sorte que les modifications d’assistants évitent de relancer toute la suite lourde de ce répertoire. - - `auto-reply` dispose de buckets dédiés pour les assistants core de premier niveau, les tests d’intégration `reply.*` de premier niveau et le sous-arbre `src/auto-reply/reply/**`. La CI divise en plus le sous-arbre reply en shards agent-runner, dispatch et commands/state-routing afin qu’un bucket lourd en imports ne possède pas toute la queue Node. - - La CI normale PR/main ignore intentionnellement le balayage par lots des extensions et le shard `agentic-plugins` réservé aux releases. La Full Release Validation déclenche le workflow enfant séparé `Plugin Prerelease` pour ces suites lourdes en plugins/extensions sur les candidats de release. + - `pnpm test` non ciblé exécute douze configs de shard plus petites (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d’un unique énorme processus natif de projet racine. Cela réduit le RSS de pointe sur les machines chargées et évite que les travaux auto-reply/extension affament des suites non liées. + - `pnpm test --watch` utilise toujours le graphe de projet racine natif `vitest.config.ts`, car une boucle de surveillance multishard n’est pas pratique. + - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` acheminent d’abord les cibles explicites de fichier/répertoire par des lanes limitées, de sorte que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite de payer le coût de démarrage complet du projet racine. + - `pnpm test:changed` développe par défaut les chemins git modifiés en lanes limitées peu coûteuses : modifications directes de tests, fichiers frères `*.test.ts`, mappings source explicites et dépendants du graphe d’import local. Les modifications de config/setup/package ne lancent pas de tests larges, sauf si vous utilisez explicitement `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` est la porte de vérification locale intelligente normale pour le travail étroit. Elle classe le diff en core, tests core, extensions, tests d’extension, apps, docs, métadonnées de release, outillage Docker live et outillage, puis exécute les commandes de typecheck, lint et garde correspondantes. Elle n’exécute pas les tests Vitest ; appelez `pnpm test:changed` ou un `pnpm test ` explicite pour la preuve de test. Les montées de version limitées aux métadonnées de release exécutent des vérifications ciblées de version/config/dépendances racine, avec une garde qui rejette les changements de package en dehors du champ de version de premier niveau. + - Les modifications du harnais ACP Docker live exécutent des vérifications ciblées : syntaxe shell pour les scripts d’auth Docker live et dry-run du planificateur Docker live. Les changements de `package.json` ne sont inclus que lorsque le diff est limité à `scripts["test:docker:live-*"]` ; les modifications de dépendance, d’export, de version et d’autres surfaces de package utilisent toujours les gardes plus larges. + - Les tests unitaires légers en imports provenant des agents, commandes, plugins, assistants auto-reply, `plugin-sdk` et zones similaires d’utilitaires purs passent par la lane `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers avec état ou lourds en runtime restent sur les lanes existantes. + - Certains fichiers source d’assistants `plugin-sdk` et `commands` mappent aussi les exécutions en mode changed vers des tests frères explicites dans ces lanes légères, afin que les modifications d’assistants évitent de relancer toute la suite lourde de ce répertoire. + - `auto-reply` dispose de compartiments dédiés pour les assistants core de premier niveau, les tests d’intégration `reply.*` de premier niveau et le sous-arbre `src/auto-reply/reply/**`. La CI divise en plus le sous-arbre reply en shards agent-runner, dispatch et commands/state-routing afin qu’un compartiment lourd en imports ne possède pas toute la traîne Node. + - La CI normale PR/main ignore intentionnellement le balayage par lots des extensions et le shard `agentic-plugins` réservé aux releases. Full Release Validation déclenche le workflow enfant séparé `Plugin Prerelease` pour ces suites lourdes en plugins/extensions sur les candidats de release. - + - - Lorsque vous modifiez les entrées de découverte des outils de message ou le contexte runtime de Compaction, + - Lorsque vous modifiez les entrées de découverte de message-tool ou le contexte runtime de compaction, conservez les deux niveaux de couverture. - - Ajoutez des régressions d’assistants ciblées pour les frontières pures de routage et de normalisation. - - Gardez les suites d’intégration du lanceur intégré en bon état : + - Ajoutez des régressions d’assistants ciblées pour les limites pures de routage et de normalisation. + - Maintenez les suites d’intégration du runner intégré en bon état : `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` et `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ces suites vérifient que les identifiants à portée limitée et le comportement de Compaction passent toujours - par les vrais chemins `run.ts` / `compact.ts` ; les tests uniquement sur assistants ne sont + - Ces suites vérifient que les identifiants limités et le comportement de Compaction passent toujours + par les vrais chemins `run.ts` / `compact.ts` ; les tests limités aux assistants ne sont pas un substitut suffisant à ces chemins d’intégration. - + - La config Vitest de base utilise `threads` par défaut. - - La config Vitest partagée fixe `isolate: false` et utilise le - lanceur non isolé dans les projets racine, les configs e2e et les configs réelles. - - La voie UI racine conserve son setup `jsdom` et son optimiseur, mais s’exécute elle aussi sur le - lanceur partagé non isolé. + - La config Vitest partagée fixe `isolate: false` et utilise le runner + non isolé dans les projets racine, e2e et configs live. + - La lane UI racine conserve sa configuration `jsdom` et son optimiseur, mais s’exécute aussi sur le + runner non isolé partagé. - Chaque shard `pnpm test` hérite des mêmes valeurs par défaut `threads` + `isolate: false` depuis la config Vitest partagée. - - `scripts/run-vitest.mjs` ajoute `--no-maglev` par défaut aux processus Node - enfants de Vitest afin de réduire le renouvellement de compilation V8 pendant les grandes exécutions locales. - Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` pour comparer avec le comportement V8 - standard. + - `scripts/run-vitest.mjs` ajoute `--no-maglev` par défaut aux processus Node enfants de Vitest + afin de réduire le churn de compilation V8 pendant les grosses exécutions locales. + Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` pour comparer au comportement V8 standard. - - `pnpm changed:lanes` montre quelles voies architecturales un diff déclenche. - - Le hook pre-commit ne fait que le formatage. Il remet en staging les fichiers formatés et + - `pnpm changed:lanes` montre quelles lanes architecturales un diff déclenche. + - Le hook pre-commit ne fait que le formatage. Il remet en stage les fichiers formatés et n’exécute ni lint, ni typecheck, ni tests. - Exécutez explicitement `pnpm check:changed` avant la remise ou le push lorsque vous - avez besoin de la barrière de vérification locale intelligente. - - `pnpm test:changed` passe par défaut par des voies à portée limitée peu coûteuses. Utilisez + avez besoin de la porte de vérification locale intelligente. + - `pnpm test:changed` passe par défaut par des lanes limitées peu coûteuses. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque l’agent - décide qu’une modification de harnais, config, package ou contrat a vraiment besoin d’une couverture + décide qu’une modification de harnais, config, package ou contrat nécessite vraiment une couverture Vitest plus large. - `pnpm test:max` et `pnpm test:changed:max` conservent le même comportement de routage, - simplement avec une limite de workers plus élevée. - - L’auto-ajustement local des workers est intentionnellement conservateur et réduit la voilure - lorsque la charge moyenne de l’hôte est déjà élevée, de sorte que plusieurs exécutions - Vitest concurrentes causent moins de dommages par défaut. + simplement avec un plafond de workers plus élevé. + - L’auto-scaling local des workers est volontairement conservateur et recule + lorsque la moyenne de charge de l’hôte est déjà élevée, afin que plusieurs exécutions Vitest + concurrentes fassent moins de dégâts par défaut. - La config Vitest de base marque les projets/fichiers de config comme - `forceRerunTriggers` afin que les réexécutions en mode changed restent correctes lorsque le câblage - des tests change. - - La config garde `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes pris en charge ; - définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez - un emplacement de cache explicite pour le profilage direct. + `forceRerunTriggers` afin que les relances en mode changed restent correctes lorsque le câblage + de test change. + - La config garde `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes + pris en charge ; définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez + un emplacement de cache explicite unique pour le profilage direct. - + - - `pnpm test:perf:imports` active le rapport de durée des imports Vitest ainsi que - la sortie de détail des imports. + - `pnpm test:perf:imports` active le rapport de durée d’import Vitest ainsi que + la sortie de ventilation des imports. - `pnpm test:perf:imports:changed` limite la même vue de profilage aux fichiers modifiés depuis `origin/main`. - - Les données de temps des shards sont écrites dans `.artifacts/vitest-shard-timings.json`. - Les exécutions de config entière utilisent le chemin de config comme clé ; les shards CI à motif - d’inclusion ajoutent le nom du shard afin que les shards filtrés puissent être suivis + - Les données de timing des shards sont écrites dans `.artifacts/vitest-shard-timings.json`. + Les exécutions de config complète utilisent le chemin de config comme clé ; les shards CI + à motif d’inclusion ajoutent le nom du shard afin que les shards filtrés puissent être suivis séparément. - - Lorsqu’un test chaud passe encore la majorité de son temps dans les imports de démarrage, - gardez les dépendances lourdes derrière une couture locale étroite `*.runtime.ts` et - moquez directement cette couture au lieu d’importer en profondeur des assistants runtime juste - pour les passer à `vi.mock(...)`. + - Lorsqu’un test chaud passe encore la plupart de son temps dans les imports de démarrage, + gardez les dépendances lourdes derrière une seam locale étroite `*.runtime.ts` et + mockez cette seam directement au lieu de deep-importer des assistants runtime uniquement + pour les transmettre à `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` compare le - `test:changed` routé avec le chemin natif de projet racine pour ce diff commité - et affiche le temps mural ainsi que le RSS max macOS. - - `pnpm test:perf:changed:bench -- --worktree` benchmarke l’arbre de travail - sale actuel en routant la liste des fichiers modifiés via + `test:changed` routé au chemin natif de projet racine pour ce diff commité + et affiche le temps réel ainsi que le RSS max macOS. + - `pnpm test:perf:changed:bench -- --worktree` benchmarke l’arbre courant + sale en routant la liste des fichiers modifiés via `scripts/test-projects.mjs` et la config Vitest racine. - `pnpm test:perf:profile:main` écrit un profil CPU du thread principal pour - le démarrage de Vitest/Vite et le surcoût de transformation. - - `pnpm test:perf:profile:runner` écrit des profils CPU+heap du lanceur pour la - suite unitaire avec le parallélisme de fichiers désactivé. + le démarrage Vitest/Vite et le surcoût de transformation. + - `pnpm test:perf:profile:runner` écrit des profils CPU+heap du runner pour la + suite unitaire avec le parallélisme par fichier désactivé. -### Stabilité (Gateway) +### Stabilité (gateway) - Commande : `pnpm test:stability:gateway` -- Config : `vitest.gateway.config.ts`, forcée à un worker +- Config : `vitest.gateway.config.ts`, forcée à un seul worker - Portée : - - Démarre un vrai Gateway en local loopback avec les diagnostics activés par défaut - - Fait passer le churn synthétique de messages Gateway, de mémoire et de gros payloads par le chemin d’événements de diagnostic + - Démarre un vrai Gateway loopback avec les diagnostics activés par défaut + - Fait passer un churn synthétique de messages Gateway, mémoire et payloads volumineux par le chemin d’événements de diagnostic - Interroge `diagnostics.stability` via le RPC WS du Gateway - - Couvre les assistants de persistance du bundle de stabilité de diagnostic + - Couvre les assistants de persistance du bundle de stabilité des diagnostics - Vérifie que l’enregistreur reste borné, que les échantillons RSS synthétiques restent sous le budget de pression et que les profondeurs de file par session reviennent à zéro - Attentes : - Compatible CI et sans clé - - Voie étroite pour le suivi des régressions de stabilité, pas un substitut à la suite Gateway complète + - Lane étroite pour le suivi de régression de stabilité, pas un substitut à la suite Gateway complète ### E2E (smoke Gateway) - Commande : `pnpm test:e2e` -- Config : `vitest.e2e.config.ts` -- Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`, et tests E2E de plugins groupés sous `extensions/` +- Configuration : `vitest.e2e.config.ts` +- Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`, et tests E2E de Plugins groupés sous `extensions/` - Valeurs par défaut d’exécution : - Utilise les `threads` Vitest avec `isolate: false`, comme le reste du dépôt. - Utilise des workers adaptatifs (CI : jusqu’à 2, local : 1 par défaut). @@ -546,114 +551,116 @@ Considérez les suites comme un « réalisme croissant » (et une instabilité/u - `OPENCLAW_E2E_VERBOSE=1` pour réactiver la sortie console détaillée. - Portée : - Comportement de bout en bout du Gateway multi-instance - - Surfaces WebSocket/HTTP, appairage de nœuds et réseau plus lourd + - Surfaces WebSocket/HTTP, appairage de nœuds et mise en réseau plus lourde - Attentes : - - S’exécute en CI (lorsqu’activé dans le pipeline) - - Aucune vraie clé requise + - S’exécute dans la CI (lorsqu’activé dans le pipeline) + - Aucune clé réelle requise - Plus d’éléments mobiles que les tests unitaires (peut être plus lent) -### E2E : smoke du backend OpenShell +### E2E : test de fumée du backend OpenShell - Commande : `pnpm test:e2e:openshell` - Fichier : `extensions/openshell/src/backend.e2e.test.ts` - Portée : - Démarre un Gateway OpenShell isolé sur l’hôte via Docker - - Crée un sandbox à partir d’un Dockerfile local temporaire - - Exerce le backend OpenShell d’OpenClaw via un vrai `sandbox ssh-config` + exécution SSH - - Vérifie le comportement du système de fichiers canonique distant via le pont fs du sandbox + - Crée une sandbox depuis un Dockerfile local temporaire + - Exerce le backend OpenShell d’OpenClaw via une vraie configuration `sandbox ssh-config` + exécution SSH + - Vérifie le comportement du système de fichiers canonique distant via le pont fs de la sandbox - Attentes : - - Activation explicite uniquement ; ne fait pas partie de l’exécution par défaut de `pnpm test:e2e` - - Nécessite une CLI locale `openshell` ainsi qu’un démon Docker fonctionnel - - Utilise des `HOME` / `XDG_CONFIG_HOME` isolés, puis détruit le Gateway de test et le sandbox + - Activation explicite uniquement ; ne fait pas partie de l’exécution `pnpm test:e2e` par défaut + - Nécessite une CLI `openshell` locale ainsi qu’un démon Docker fonctionnel + - Utilise `HOME` / `XDG_CONFIG_HOME` isolés, puis détruit le Gateway de test et la sandbox - Surcharges utiles : - `OPENCLAW_E2E_OPENSHELL=1` pour activer le test lors de l’exécution manuelle de la suite e2e plus large - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI ou un script wrapper non par défaut + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI non par défaut ou un script wrapper -### Live (vrais fournisseurs + vrais modèles) +### Tests en conditions réelles (fournisseurs réels + modèles réels) - Commande : `pnpm test:live` -- Config : `vitest.live.config.ts` -- Fichiers : `src/**/*.live.test.ts`, `test/**/*.live.test.ts`, et tests live de plugins groupés sous `extensions/` -- Valeur par défaut : **activé** par `pnpm test:live` (définit `OPENCLAW_LIVE_TEST=1`) +- Configuration : `vitest.live.config.ts` +- Fichiers : `src/**/*.live.test.ts`, `test/**/*.live.test.ts`, et tests en conditions réelles de Plugins groupés sous `extensions/` +- Par défaut : **activé** par `pnpm test:live` (définit `OPENCLAW_LIVE_TEST=1`) - Portée : - - « Ce fournisseur/modèle fonctionne-t-il réellement _aujourd’hui_ avec de vrais identifiants ? » - - Détecter les changements de format de fournisseur, les particularités d’appel d’outils, les problèmes d’authentification et le comportement des limites de débit + - « Ce fournisseur/modèle fonctionne-t-il réellement _aujourd’hui_ avec de vraies informations d’identification ? » + - Détecter les changements de format fournisseur, les particularités d’appel d’outils, les problèmes d’authentification et le comportement des limites de débit - Attentes : - - Non stable en CI par conception (vrais réseaux, vraies politiques de fournisseurs, quotas, pannes) + - Non stable en CI par conception (réseaux réels, politiques réelles des fournisseurs, quotas, pannes) - Coûte de l’argent / utilise des limites de débit - - Préférer l’exécution de sous-ensembles restreints plutôt que « tout » -- Les exécutions live sourcent `~/.profile` pour récupérer les clés API manquantes. -- Par défaut, les exécutions live isolent toujours `HOME` et copient le matériel de config/auth dans un répertoire home de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai `~/.openclaw`. -- Définissez `OPENCLAW_LIVE_USE_REAL_HOME=1` uniquement lorsque vous avez intentionnellement besoin que les tests live utilisent votre vrai répertoire home. -- `pnpm test:live` utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression `[live] ...`, mais supprime l’avis supplémentaire `~/.profile` et rend muets les journaux d’amorçage du Gateway/le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer les journaux de démarrage complets. -- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` avec un format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou une surcharge par live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient en cas de réponses de limite de débit. -- Sortie de progression/Heartbeat : - - Les suites live émettent désormais des lignes de progression vers stderr afin que les longs appels fournisseur soient visiblement actifs même lorsque la capture console Vitest est silencieuse. - - `vitest.live.config.ts` désactive l’interception console de Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions live. - - Ajustez les Heartbeat de modèle direct avec `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajustez les Heartbeat de Gateway/sonde avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Préférer exécuter des sous-ensembles restreints plutôt que « tout » +- Les exécutions en conditions réelles sourcent `~/.profile` pour récupérer les clés API manquantes. +- Par défaut, les exécutions en conditions réelles isolent toujours `HOME` et copient les éléments de configuration/authentification dans un répertoire home de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai `~/.openclaw`. +- Définissez `OPENCLAW_LIVE_USE_REAL_HOME=1` uniquement lorsque vous avez volontairement besoin que les tests en conditions réelles utilisent votre vrai répertoire home. +- `pnpm test:live` utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression `[live] ...`, mais supprime l’avis supplémentaire `~/.profile` et met en sourdine les journaux d’amorçage du Gateway/le bavardage Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer l’intégralité des journaux de démarrage. +- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` au format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou une surcharge par exécution en conditions réelles via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient en cas de réponses de limite de débit. +- Sortie progression/Heartbeat : + - Les suites en conditions réelles émettent désormais des lignes de progression vers stderr afin que les longs appels fournisseur soient visiblement actifs même lorsque la capture console Vitest est silencieuse. + - `vitest.live.config.ts` désactive l’interception console Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions en conditions réelles. + - Ajustez les Heartbeats de modèle direct avec `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Ajustez les Heartbeats Gateway/sonde avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Quelle suite dois-je exécuter ? Utilisez ce tableau de décision : -- Modification de logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup changé) -- Modification du réseau Gateway / protocole WS / appairage : ajoutez `pnpm test:e2e` -- Débogage de « mon bot est hors service » / échecs propres à un fournisseur / appel d’outils : exécutez un `pnpm test:live` restreint +- Modification de logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié) +- Modification de la mise en réseau du Gateway / protocole WS / appairage : ajoutez `pnpm test:e2e` +- Débogage de « mon bot est indisponible » / échecs propres à un fournisseur / appel d’outils : exécutez un `pnpm test:live` restreint -## Tests live (touchant au réseau) +## Tests en conditions réelles (touchant le réseau) -Pour la matrice de modèles live, les smokes de backend CLI, les smokes ACP, le harnais de serveur d’application Codex et tous les tests live de fournisseurs média (Deepgram, BytePlus, ComfyUI, image, musique, vidéo, harnais média) — ainsi que la gestion des identifiants pour les exécutions live — consultez [Tester les suites live](/fr/help/testing-live). Pour la checklist dédiée de validation des mises à jour et des plugins, consultez [Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins). +Pour la matrice de modèles en conditions réelles, les tests de fumée du backend CLI, les tests de fumée ACP, le harnais de serveur d’application Codex et tous les tests en conditions réelles de fournisseurs média (Deepgram, BytePlus, ComfyUI, image, musique, vidéo, harnais média), ainsi que la gestion des informations d’identification pour les exécutions en conditions réelles, consultez +[Tester les suites en conditions réelles](/fr/help/testing-live). Pour la checklist dédiée de mise à jour et de validation de Plugin, consultez +[Tester les mises à jour et les Plugins](/fr/help/testing-updates-plugins). -## Exécuteurs Docker (vérifications facultatives « fonctionne sous Linux ») +## Runners Docker (vérifications facultatives « fonctionne sous Linux ») -Ces exécuteurs Docker se répartissent en deux catégories : +Ces runners Docker se répartissent en deux catégories : -- Exécuteurs de modèles live : `test:docker:live-models` et `test:docker:live-gateway` exécutent uniquement leur fichier live de clé de profil correspondant dans l’image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de config local et votre espace de travail (et en sourçant `~/.profile` s’il est monté). Les points d’entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`. -- Les exécuteurs Docker live utilisent par défaut un plafond de smoke plus réduit afin qu’un balayage Docker complet reste pratique : +- Runners de modèles en conditions réelles : `test:docker:live-models` et `test:docker:live-gateway` exécutent uniquement leur fichier en conditions réelles correspondant à la clé de profil dans l’image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de configuration local et votre espace de travail (et en sourçant `~/.profile` s’il est monté). Les points d’entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`. +- Les runners Docker en conditions réelles utilisent par défaut un plafond de test de fumée plus petit afin qu’un balayage Docker complet reste pratique : `test:docker:live-models` utilise par défaut `OPENCLAW_LIVE_MAX_MODELS=12`, et `test:docker:live-gateway` utilise par défaut `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, et - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Surchargez ces variables d’environnement lorsque vous + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d’environnement lorsque vous voulez explicitement l’analyse exhaustive plus large. -- `test:docker:all` construit l’image Docker live une seule fois via `test:docker:live-build`, empaquette OpenClaw une seule fois comme archive tar npm via `scripts/package-openclaw-for-docker.mjs`, puis construit/réutilise deux images `scripts/e2e/Dockerfile`. L’image nue est uniquement l’exécuteur Node/Git pour les lanes d’installation/mise à jour/dépendances de plugins ; ces lanes montent l’archive tar préconstruite. L’image fonctionnelle installe la même archive tar dans `/app` pour les lanes de fonctionnalité de l’application construite. 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` ; `scripts/test-docker-all.mjs` exécute le plan sélectionné. L’agrégat utilise un planificateur local pondéré : `OPENCLAW_DOCKER_ALL_PARALLELISM` contrôle les emplacements de processus, tandis que les plafonds de ressources empêchent les lanes live lourdes, npm-install et multi-services de toutes démarrer en même temps. Si une seule lane est plus lourde que les plafonds actifs, le planificateur peut quand même la démarrer lorsque le pool est vide, puis la laisse s’exécuter seule jusqu’à ce que de la capacité soit de nouveau disponible. Les valeurs par défaut sont 10 emplacements, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; ajustez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` uniquement lorsque l’hôte Docker dispose de plus de marge. L’exécuteur effectue un prévol Docker par défaut, supprime les conteneurs E2E OpenClaw obsolètes, imprime l’état toutes les 30 secondes, stocke les durées des lanes réussies dans `.artifacts/docker-tests/lane-timings.json`, et utilise ces durées pour démarrer les lanes plus longues en premier lors des exécutions ultérieures. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour imprimer le manifeste de lanes pondéré sans construire ni exécuter Docker, ou `node scripts/test-docker-all.mjs --plan-json` pour imprimer le plan CI pour les lanes sélectionnées, les besoins en package/image et les identifiants. -- `Package Acceptance` est la porte de package native GitHub pour « cette archive tar installable fonctionne-t-elle comme un produit ? » Elle résout un package candidat depuis `source=npm`, `source=ref`, `source=url` ou `source=artifact`, le téléverse comme `package-under-test`, puis exécute les lanes Docker E2E réutilisables contre cette archive tar exacte au lieu de réempaqueter la référence sélectionnée. Les profils sont ordonnés par ampleur : `smoke`, `package`, `product` et `full`. Consultez [Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins) pour le contrat package/mise à jour/plugin, la matrice de survivants de mise à niveau publiée, les valeurs par défaut de publication et le triage des échecs. -- Les vérifications de build et de publication exécutent `scripts/check-cli-bootstrap-imports.mjs` après tsdown. Le garde parcourt le graphe construit statique depuis `dist/entry.js` et `dist/cli/run-main.js` et échoue si le démarrage avant dispatch importe des dépendances de package telles que Commander, l’UI de prompt, undici ou la journalisation avant le dispatch de commande ; il maintient aussi le segment d’exécution Gateway groupé sous le budget et rejette les imports statiques de chemins Gateway froids connus. Le smoke CLI empaqueté couvre aussi l’aide racine, l’aide onboard, l’aide doctor, status, le schéma de config et une commande de liste de modèles. -- La compatibilité héritée de Package Acceptance est plafonnée à `2026.4.25` (`2026.4.25-beta.*` inclus). Jusqu’à cette limite, le harnais tolère uniquement les écarts de métadonnées de packages publiés : entrées d’inventaire QA privées omises, `gateway install --wrapper` manquant, fichiers de correctif manquants dans la fixture git dérivée de l’archive tar, `update.channel` persisté manquant, emplacements hérités d’enregistrements d’installation de plugins, persistance manquante des enregistrements d’installation de marketplace, et migration des métadonnées de config pendant `plugins update`. Pour les packages postérieurs au `2026.4.25`, ces chemins sont des échecs stricts. -- Exécuteurs de smoke conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix`, et `test:docker:config-reload` démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d’intégration de plus haut niveau. +- `test:docker:all` construit l’image Docker en conditions réelles une fois via `test:docker:live-build`, empaquette OpenClaw une fois comme archive npm via `scripts/package-openclaw-for-docker.mjs`, puis construit/réutilise deux images `scripts/e2e/Dockerfile`. L’image nue est seulement le runner Node/Git pour les voies installation/mise à jour/dépendance de Plugin ; ces voies montent l’archive préconstruite. L’image fonctionnelle installe la même archive dans `/app` pour les voies de fonctionnalité de l’application construite. Les définitions des 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é. L’agrégat utilise un planificateur local pondéré : `OPENCLAW_DOCKER_ALL_PARALLELISM` contrôle les emplacements de processus, tandis que les plafonds de ressources empêchent les voies lourdes en conditions réelles, d’installation npm et multiservice de démarrer toutes en même temps. Si une seule voie est plus lourde que les plafonds actifs, le planificateur peut tout de même la démarrer lorsque le pool est vide, puis la maintenir seule en cours d’exécution jusqu’à ce que de la capacité soit de nouveau disponible. Les valeurs par défaut sont 10 emplacements, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; ajustez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` uniquement lorsque l’hôte Docker dispose de plus de marge. Le runner effectue une pré-vérification Docker par défaut, supprime les conteneurs E2E OpenClaw obsolètes, affiche l’état toutes les 30 secondes, stocke les temps des voies réussies dans `.artifacts/docker-tests/lane-timings.json` et utilise ces durées pour démarrer d’abord les voies plus longues lors des exécutions ultérieures. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour afficher le manifeste pondéré des voies sans construire ni exécuter Docker, ou `node scripts/test-docker-all.mjs --plan-json` pour afficher le plan CI des voies sélectionnées, des besoins en package/image et des informations d’identification. +- `Package Acceptance` est le gate de package natif GitHub pour « cette archive installable fonctionne-t-elle comme un produit ? ». Il résout un package candidat depuis `source=npm`, `source=ref`, `source=url` ou `source=artifact`, le téléverse comme `package-under-test`, puis exécute les voies Docker E2E réutilisables contre cette archive exacte au lieu de réempaqueter la référence sélectionnée. Les profils sont ordonnés par étendue : `smoke`, `package`, `product` et `full`. Consultez [Tester les mises à jour et les Plugins](/fr/help/testing-updates-plugins) pour le contrat package/mise à jour/Plugin, la matrice de survie des mises à niveau publiées, les valeurs par défaut de publication et le triage des échecs. +- Les vérifications de build et de release exécutent `scripts/check-cli-bootstrap-imports.mjs` après tsdown. Le garde parcourt le graphe construit statique depuis `dist/entry.js` et `dist/cli/run-main.js` et échoue si le démarrage avant dispatch importe des dépendances de package telles que Commander, l’UI de prompt, undici ou la journalisation avant le dispatch de commande ; il maintient également le chunk d’exécution du Gateway groupé sous budget et rejette les imports statiques de chemins Gateway froids connus. Le test de fumée de la CLI empaquetée couvre également l’aide racine, l’aide d’onboarding, l’aide de doctor, l’état, le schéma de configuration et une commande de liste de modèles. +- La compatibilité héritée de Package Acceptance est plafonnée à `2026.4.25` (`2026.4.25-beta.*` inclus). Jusqu’à cette date limite, le harnais tolère uniquement les lacunes de métadonnées de packages expédiés : entrées d’inventaire QA privées omises, `gateway install --wrapper` manquant, fichiers de correctif manquants dans la fixture git dérivée de l’archive, `update.channel` persisté manquant, emplacements hérités des enregistrements d’installation de Plugin, persistance manquante des enregistrements d’installation de marketplace et migration des métadonnées de configuration pendant `plugins update`. Pour les packages après `2026.4.25`, ces chemins sont des échecs stricts. +- Runners de tests de fumée de conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix` et `test:docker:config-reload` démarrent un ou plusieurs conteneurs réels et vérifient des chemins d’intégration de plus haut niveau. -Les exécuteurs Docker de modèles live montent également en bind uniquement les répertoires home d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le home du conteneur avant l’exécution afin que l’OAuth de CLI externe puisse actualiser les jetons sans modifier le magasin d’authentification de l’hôte : +Les runners Docker de modèles en conditions réelles montent également en bind uniquement les répertoires home d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le home du conteneur avant l’exécution afin que l’OAuth de CLI externe puisse actualiser les jetons sans modifier le magasin d’authentification de l’hôte : - Modèles directs : `pnpm test:docker:live-models` (script : `scripts/test-live-models-docker.sh`) -- Smoke test de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh` ; couvre Claude, Codex et Gemini par défaut, avec une couverture stricte de Droid/OpenCode via `pnpm test:docker:live-acp-bind:droid` et `pnpm test:docker:live-acp-bind:opencode`) -- Smoke test du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) -- Smoke test du harnais serveur d’application Codex : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) +- Test smoke de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh` ; couvre Claude, Codex et Gemini par défaut, avec une couverture stricte de Droid/OpenCode via `pnpm test:docker:live-acp-bind:droid` et `pnpm test:docker:live-acp-bind:opencode`) +- Test smoke du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) +- Test smoke du harnais app-server Codex : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) - Gateway + agent de développement : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`) -- Smoke test d’observabilité : `pnpm qa:otel:smoke` est une voie privée de vérification depuis une copie de travail QA. Elle ne fait volontairement pas partie des voies de publication Docker des packages, car le tarball npm omet QA Lab. -- Smoke test live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`) -- Assistant d’intégration (TTY, échafaudage complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`) -- Smoke test d’intégration/canal/agent du tarball npm : `pnpm test:docker:npm-onboard-channel-agent` installe globalement le tarball OpenClaw empaqueté dans Docker, configure OpenAI via une intégration par référence d’environnement ainsi que Telegram par défaut, exécute doctor, puis exécute un tour d’agent OpenAI simulé. Réutilisez un tarball préconstruit avec `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignorez la reconstruction hôte avec `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, ou changez de canal avec `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` ou `OPENCLAW_NPM_ONBOARD_CHANNEL=slack`. -- Smoke test de changement de canal de mise à jour : `pnpm test:docker:update-channel-switch` installe globalement le tarball OpenClaw empaqueté dans Docker, passe du package `stable` à git `dev`, vérifie le canal persisté et le fonctionnement des Plugins après mise à jour, puis revient au package `stable` et vérifie l’état de mise à jour. -- Smoke test de survivance de mise à niveau : `pnpm test:docker:upgrade-survivor` installe le tarball OpenClaw empaqueté par-dessus une fixture sale d’ancien utilisateur avec agents, configuration de canal, listes d’autorisation de Plugins, état obsolète des dépendances de Plugins, et fichiers d’espace de travail/session existants. Il exécute la mise à jour du package puis doctor non interactif sans fournisseur live ni clés de canal, démarre ensuite un Gateway local loopback et vérifie la préservation de la configuration/de l’état ainsi que les budgets de démarrage/d’état. -- Smoke test de survivance de mise à niveau publiée : `pnpm test:docker:published-upgrade-survivor` installe `openclaw@latest` par défaut, alimente des fichiers réalistes d’utilisateur existant, configure cette base avec une recette de commande intégrée, valide la configuration obtenue, met à jour cette installation publiée vers le tarball candidat, exécute doctor non interactif, écrit `.artifacts/upgrade-survivor/summary.json`, puis démarre un Gateway local loopback et vérifie les intentions configurées, la préservation de l’état, le démarrage, `/healthz`, `/readyz` et les budgets d’état RPC. Remplacez une base avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, demandez au planificateur agrégé d’étendre des bases exactes avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` telles que `all-since-2026.4.23`, et étendez les fixtures en forme de problèmes avec `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` telles que `reported-issues` ; l’ensemble reported-issues inclut `configured-plugin-installs` pour la réparation automatique d’installation de Plugins OpenClaw externes. Package Acceptance les expose sous `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` et `published_upgrade_survivor_scenarios` ; Full Release Validation utilise la base latest par défaut dans le chemin bloquant et s’étend à all-since/reported-issues uniquement pour `run_release_soak=true` ou `release_profile=full`. -- Smoke test du contexte d’exécution de session : `pnpm test:docker:session-runtime-context` vérifie la persistance du transcript du contexte d’exécution masqué ainsi que la réparation par doctor des branches dupliquées affectées de réécriture de prompt. -- Smoke test d’installation globale Bun : `bash scripts/e2e/bun-global-install-smoke.sh` empaquette l’arborescence actuelle, l’installe avec `bun install -g` dans un répertoire personnel isolé, et vérifie que `openclaw infer image providers --json` renvoie les fournisseurs d’images intégrés au lieu de rester bloqué. Réutilisez un tarball préconstruit avec `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignorez la construction hôte avec `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, ou copiez `dist/` depuis une image Docker construite avec `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke test Docker de l’installateur : `bash scripts/test-install-sh-docker.sh` partage un seul cache npm entre ses conteneurs root, update et direct-npm. Le smoke test de mise à jour utilise par défaut npm `latest` comme base stable avant la mise à niveau vers le tarball candidat. Remplacez-la par `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` localement, ou avec l’entrée `update_baseline_version` du workflow Install Smoke sur GitHub. Les vérifications de l’installateur non-root conservent un cache npm isolé afin que les entrées de cache appartenant à root ne masquent pas le comportement d’installation locale utilisateur. Définissez `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` pour réutiliser le cache root/update/direct-npm lors des réexécutions locales. -- Install Smoke CI ignore la mise à jour globale direct-npm dupliquée avec `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` ; exécutez le script localement sans cette variable d’environnement lorsque la couverture directe `npm install -g` est nécessaire. -- Smoke test CLI de suppression d’agents avec espace de travail partagé : `pnpm test:docker:agents-delete-shared-workspace` (script : `scripts/e2e/agents-delete-shared-workspace-docker.sh`) construit par défaut l’image Dockerfile racine, alimente deux agents avec un espace de travail dans un répertoire personnel de conteneur isolé, exécute `agents delete --json`, et vérifie un JSON valide ainsi que le comportement de conservation de l’espace de travail. Réutilisez l’image install-smoke avec `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Réseau Gateway (deux conteneurs, auth WS + santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) -- Smoke test d’instantané CDP navigateur : `pnpm test:docker:browser-cdp-snapshot` (script : `scripts/e2e/browser-cdp-snapshot-docker.sh`) construit l’image E2E source plus une couche Chromium, démarre Chromium avec CDP brut, exécute `browser doctor --deep`, et vérifie que les instantanés de rôles CDP couvrent 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. -- Régression de raisonnement minimal OpenAI Responses web_search : `pnpm test:docker:openai-web-search-minimal` (script : `scripts/e2e/openai-web-search-minimal-docker.sh`) exécute un serveur OpenAI simulé via Gateway, vérifie que `web_search` fait passer `reasoning.effort` de `minimal` à `low`, puis force le rejet du schéma fournisseur et vérifie que le détail brut apparaît dans les journaux Gateway. -- Pont de canal MCP (Gateway alimenté + pont stdio + smoke test de trame de notification Claude brute) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) -- Outils MCP du bundle Pi (serveur MCP stdio réel + smoke test d’autorisation/refus du profil Pi intégré) : `pnpm test:docker:pi-bundle-mcp-tools` (script : `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Nettoyage Cron/sous-agent MCP (Gateway réel + arrêt du processus enfant MCP stdio après des exécutions cron isolées et de sous-agent ponctuel) : `pnpm test:docker:cron-mcp-cleanup` (script : `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke test d’installation/mise à jour pour chemin local, `file:`, registre npm avec dépendances hissées, références git mobiles, ClawHub kitchen-sink, mises à jour marketplace, et activation/inspection du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`) - Définissez `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` pour ignorer le bloc ClawHub, ou remplacez la paire package/runtime kitchen-sink par défaut avec `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` et `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sans `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, le test utilise un serveur de fixture ClawHub local hermétique. -- Smoke test de mise à jour inchangée de Plugin : `pnpm test:docker:plugin-update` (script : `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke test de matrice de cycle de vie Plugin : `pnpm test:docker:plugin-lifecycle-matrix` installe le tarball OpenClaw empaqueté dans un conteneur nu, installe un Plugin npm, active/désactive, le met à niveau et le rétrograde via un registre npm local, supprime le code installé, puis vérifie que la désinstallation supprime toujours l’état obsolète tout en journalisant les métriques RSS/CPU pour chaque phase du cycle de vie. -- Smoke test des métadonnées de rechargement de configuration : `pnpm test:docker:config-reload` (script : `scripts/e2e/config-reload-source-docker.sh`) -- Plugins : `pnpm test:docker:plugins` couvre le smoke test d’installation/mise à jour pour chemin local, `file:`, registre npm avec dépendances hissées, références git mobiles, fixtures ClawHub, mises à jour marketplace, et activation/inspection du bundle Claude. `pnpm test:docker:plugin-update` couvre le comportement de mise à jour inchangée pour les Plugins installés. `pnpm test:docker:plugin-lifecycle-matrix` couvre l’installation, l’activation, la désactivation, la mise à niveau, la rétrogradation et la désinstallation avec code manquant d’un Plugin npm avec suivi des ressources. +- Test smoke d’observabilité : `pnpm qa:otel:smoke` est une voie de vérification privée QA depuis une extraction source. Elle ne fait volontairement pas partie des voies de publication Docker de package, car l’archive tarball npm omet QA Lab. +- Test smoke live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`) +- Assistant d’onboarding (TTY, échafaudage complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`) +- Test smoke d’onboarding/canal/agent de l’archive tarball npm : `pnpm test:docker:npm-onboard-channel-agent` installe globalement dans Docker l’archive tarball OpenClaw packagée, configure OpenAI via un onboarding par référence d’environnement ainsi que Telegram par défaut, exécute doctor, puis exécute un tour d’agent OpenAI simulé. Réutilisez une archive tarball préconstruite avec `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignorez la reconstruction hôte avec `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, ou changez de canal avec `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` ou `OPENCLAW_NPM_ONBOARD_CHANNEL=slack`. +- Test smoke de changement de canal de mise à jour : `pnpm test:docker:update-channel-switch` installe globalement dans Docker l’archive tarball OpenClaw packagée, bascule du package `stable` vers git `dev`, vérifie le canal persistant et le fonctionnement du Plugin après mise à jour, puis rebascule vers le package `stable` et vérifie l’état de mise à jour. +- Test smoke de survie à la mise à niveau : `pnpm test:docker:upgrade-survivor` installe l’archive tarball OpenClaw packagée par-dessus un ancien jeu de données utilisateur modifié avec des agents, une configuration de canal, des listes d’autorisation de Plugin, un état obsolète de dépendances de Plugin et des fichiers d’espace de travail/session existants. Il exécute la mise à jour du package ainsi que doctor en mode non interactif sans clés de fournisseur live ni de canal, puis démarre un Gateway local loopback et vérifie la préservation de la configuration/de l’état ainsi que les budgets de démarrage/d’état. +- Test smoke publié de survie à la mise à niveau : `pnpm test:docker:published-upgrade-survivor` installe `openclaw@latest` par défaut, initialise des fichiers utilisateur existants réalistes, configure cette base avec une recette de commande intégrée, valide la configuration obtenue, met à jour cette installation publiée vers l’archive tarball candidate, exécute doctor en mode non interactif, écrit `.artifacts/upgrade-survivor/summary.json`, puis démarre un Gateway local loopback et vérifie les intentions configurées, la préservation de l’état, le démarrage, `/healthz`, `/readyz` et les budgets d’état RPC. Remplacez une base avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, demandez au planificateur agrégé d’étendre les bases locales exactes avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` comme `openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15`, et étendez les jeux de données de type issue avec `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` comme `reported-issues` ; l’ensemble reported-issues inclut `configured-plugin-installs` pour la réparation automatique des installations de Plugins OpenClaw externes. Package Acceptance expose ces éléments sous `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` et `published_upgrade_survivor_scenarios`, résout les jetons de base méta comme `last-stable-4` ou `all-since-2026.4.23`, et Full Release Validation étend la porte package release-soak à `last-stable-4 2026.4.23 2026.5.2 2026.4.15` plus `reported-issues`. +- Test smoke du contexte d’exécution de session : `pnpm test:docker:session-runtime-context` vérifie la persistance de la transcription du contexte d’exécution masqué ainsi que la réparation par doctor des branches dupliquées de réécriture de prompt concernées. +- Test smoke d’installation globale Bun : `bash scripts/e2e/bun-global-install-smoke.sh` empaquette l’arbre actuel, l’installe avec `bun install -g` dans un répertoire personnel isolé, et vérifie que `openclaw infer image providers --json` renvoie les fournisseurs d’images intégrés au lieu de rester bloqué. Réutilisez une archive tarball préconstruite avec `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignorez la construction hôte avec `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, ou copiez `dist/` depuis une image Docker construite avec `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Test smoke Docker de l’installateur : `bash scripts/test-install-sh-docker.sh` partage un même cache npm entre ses conteneurs root, update et direct-npm. Le test smoke de mise à jour utilise par défaut npm `latest` comme base stable avant la mise à niveau vers l’archive tarball candidate. Remplacez avec `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` localement, ou avec l’entrée `update_baseline_version` du workflow Install Smoke sur GitHub. Les vérifications de l’installateur non-root conservent un cache npm isolé afin que les entrées de cache appartenant à root ne masquent pas le comportement d’installation local à l’utilisateur. Définissez `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` pour réutiliser le cache root/update/direct-npm lors des réexécutions locales. +- Install Smoke CI ignore la mise à jour globale direct-npm dupliquée avec `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` ; exécutez le script localement sans cette variable d’environnement lorsque la couverture directe de `npm install -g` est nécessaire. +- Test smoke CLI de suppression d’agents avec espace de travail partagé : `pnpm test:docker:agents-delete-shared-workspace` (script : `scripts/e2e/agents-delete-shared-workspace-docker.sh`) construit l’image Dockerfile racine par défaut, initialise deux agents avec un espace de travail dans un répertoire personnel de conteneur isolé, exécute `agents delete --json`, puis vérifie un JSON valide ainsi que le comportement de conservation de l’espace de travail. Réutilisez l’image install-smoke avec `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Réseau Gateway (deux conteneurs, authentification WS + santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) +- Test smoke d’instantané CDP du navigateur : `pnpm test:docker:browser-cdp-snapshot` (script : `scripts/e2e/browser-cdp-snapshot-docker.sh`) construit l’image E2E source plus une couche Chromium, démarre Chromium avec CDP brut, exécute `browser doctor --deep`, et vérifie que les instantanés de rôle CDP couvrent les URL de liens, les éléments cliquables promus par curseur, les références d’iframe et les métadonnées de frame. +- Régression de raisonnement minimal OpenAI Responses web_search : `pnpm test:docker:openai-web-search-minimal` (script : `scripts/e2e/openai-web-search-minimal-docker.sh`) exécute un serveur OpenAI simulé via Gateway, vérifie que `web_search` élève `reasoning.effort` de `minimal` à `low`, puis force le rejet du schéma fournisseur et vérifie que le détail brut apparaît dans les journaux Gateway. +- Pont de canal MCP (Gateway initialisé + pont stdio + test smoke brut de trame de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) +- Outils MCP du bundle Pi (serveur MCP stdio réel + test smoke allow/deny du profil Pi intégré) : `pnpm test:docker:pi-bundle-mcp-tools` (script : `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Nettoyage MCP Cron/sous-agent (Gateway réel + démontage de processus enfant MCP stdio après des exécutions cron isolées et de sous-agent ponctuel) : `pnpm test:docker:cron-mcp-cleanup` (script : `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (test smoke d’installation/mise à jour pour chemin local, `file:`, registre npm avec dépendances remontées, références git mobiles, ClawHub kitchen-sink, mises à jour de marketplace et activation/inspection du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`) + Définissez `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` pour ignorer le bloc ClawHub, ou remplacez la paire package/runtime kitchen-sink par défaut avec `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` et `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sans `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, le test utilise un serveur de jeu de données ClawHub local hermétique. +- Test smoke de mise à jour inchangée de Plugin : `pnpm test:docker:plugin-update` (script : `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Test smoke de matrice de cycle de vie de Plugin : `pnpm test:docker:plugin-lifecycle-matrix` installe l’archive tarball OpenClaw packagée dans un conteneur nu, installe un Plugin npm, bascule activation/désactivation, le met à niveau puis le rétrograde via un registre npm local, supprime le code installé, puis vérifie que la désinstallation supprime toujours l’état obsolète tout en journalisant les métriques RSS/CPU pour chaque phase du cycle de vie. +- Test smoke des métadonnées de rechargement de configuration : `pnpm test:docker:config-reload` (script : `scripts/e2e/config-reload-source-docker.sh`) +- Plugins : `pnpm test:docker:plugins` couvre les tests smoke d’installation/mise à jour pour chemin local, `file:`, registre npm avec dépendances remontées, références git mobiles, jeux de données ClawHub, mises à jour de marketplace et activation/inspection du bundle Claude. `pnpm test:docker:plugin-update` couvre le comportement de mise à jour inchangée pour les Plugins installés. `pnpm test:docker:plugin-lifecycle-matrix` couvre l’installation, l’activation, la désactivation, la mise à niveau, la rétrogradation et la désinstallation en cas de code manquant d’un Plugin npm avec suivi des ressources. Pour préconstruire et réutiliser manuellement l’image fonctionnelle partagée : @@ -662,176 +669,176 @@ OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker: OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Les remplacements d’image propres à une suite, tels que `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, prévalent toujours lorsqu’ils sont définis. Lorsque `OPENCLAW_SKIP_DOCKER_BUILD=1` pointe vers une image partagée distante, les scripts la récupèrent si elle n’est pas déjà locale. Les tests Docker QR et installateur conservent leurs propres Dockerfiles, car ils valident le comportement package/installation plutôt que l’exécution de l’application construite partagée. +Les remplacements d’image propres à une suite comme `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` restent prioritaires lorsqu’ils sont définis. Lorsque `OPENCLAW_SKIP_DOCKER_BUILD=1` pointe vers une image partagée distante, les scripts la téléchargent si elle n’est pas déjà locale. Les tests Docker QR et installateur conservent leurs propres Dockerfiles, car ils valident le comportement de package/d’installation plutôt que l’exécution d’application construite partagée. -Les exécuteurs Docker de modèles en direct montent aussi la copie de travail actuelle en lecture seule et -la préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image +Les exécuteurs Docker pour modèles live montent aussi le checkout courant en lecture seule et +le préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image d’exécution légère tout en exécutant Vitest sur votre source/config locale exacte. -L’étape de préparation ignore les grands caches uniquement locaux et les sorties de compilation -d’applications comme `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires -`.build` locaux aux applications ou les répertoires de sortie Gradle, afin que les exécutions Docker -en direct ne passent pas plusieurs minutes à copier des artefacts propres à la machine. -Ils définissent aussi `OPENCLAW_SKIP_CHANNELS=1` afin que les sondes en direct du Gateway ne démarrent pas -de vrais workers de canaux Telegram/Discord/etc. dans le conteneur. +L’étape de préparation ignore les grands caches locaux uniquement et les sorties de build d’app, +comme `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires de sortie +`.build` propres aux apps ou Gradle, afin que les exécutions live Docker ne passent pas des minutes à copier +des artefacts spécifiques à la machine. +Ils définissent aussi `OPENCLAW_SKIP_CHANNELS=1` afin que les sondes live du gateway ne démarrent pas +de vrais workers de canal Telegram/Discord/etc. dans le conteneur. `test:docker:live-models` exécute toujours `pnpm test:live`, donc transmettez aussi -`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture -en direct du Gateway dans cette voie Docker. -`test:docker:openwebui` est un test de fumée de compatibilité de plus haut niveau : il démarre un -conteneur Gateway OpenClaw avec les points de terminaison HTTP compatibles avec OpenAI activés, -démarre un conteneur Open WebUI épinglé configuré pour ce Gateway, s’authentifie via +`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture live du gateway +de cette voie Docker. +`test:docker:openwebui` est un smoke test de compatibilité de plus haut niveau : il démarre un +conteneur de gateway OpenClaw avec les points de terminaison HTTP compatibles OpenAI activés, +démarre un conteneur Open WebUI épinglé contre ce gateway, se connecte via Open WebUI, vérifie que `/api/models` expose `openclaw/default`, puis envoie une vraie requête de chat via le proxy `/api/chat/completions` d’Open WebUI. -La première exécution peut être nettement plus lente, car Docker peut devoir récupérer l’image -Open WebUI et Open WebUI peut devoir terminer sa propre initialisation à froid. -Cette voie attend une clé de modèle en direct utilisable, et `OPENCLAW_PROFILE_FILE` +La première exécution peut être sensiblement plus lente, car Docker peut devoir récupérer l’image +Open WebUI et Open WebUI peut devoir terminer sa propre configuration de démarrage à froid. +Cette voie attend une clé de modèle live utilisable, et `OPENCLAW_PROFILE_FILE` (`~/.profile` par défaut) est le principal moyen de la fournir dans les exécutions Dockerisées. Les exécutions réussies affichent une petite charge utile JSON comme `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` est intentionnellement déterministe et n’a pas besoin d’un -vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway initialisé, -démarre un second conteneur qui lance `openclaw mcp serve`, puis vérifie la découverte -des conversations routées, les lectures de transcriptions, les métadonnées des pièces jointes, -le comportement de la file d’événements en direct, le routage des envois sortants, ainsi que les notifications de canal + -permission de style Claude sur le vrai pont MCP stdio. La vérification des notifications -inspecte directement les trames MCP stdio brutes afin que le test de fumée valide ce que le -pont émet réellement, et pas seulement ce qu’un SDK client particulier se trouve à exposer. -`test:docker:pi-bundle-mcp-tools` est déterministe et n’a pas besoin d’une clé de modèle -en direct. Il construit l’image Docker du dépôt, démarre un vrai serveur de sonde MCP stdio -dans le conteneur, matérialise ce serveur via l’exécution MCP du bundle Pi embarqué, +`test:docker:mcp-channels` est intentionnellement déterministe et ne nécessite pas de +vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway avec données initiales, +démarre un second conteneur qui lance `openclaw mcp serve`, puis +vérifie la découverte des conversations routées, la lecture des transcriptions, les métadonnées des pièces jointes, +le comportement de la file d’événements live, le routage des envois sortants, ainsi que les notifications de canal + +permission façon Claude via le vrai bridge MCP stdio. La vérification des notifications +inspecte directement les trames MCP stdio brutes, afin que le smoke valide ce que le +bridge émet réellement, et pas seulement ce qu’un SDK client précis expose par hasard. +`test:docker:pi-bundle-mcp-tools` est déterministe et ne nécessite pas de clé de modèle live. +Il construit l’image Docker du dépôt, démarre un vrai serveur de sonde MCP stdio +dans le conteneur, matérialise ce serveur via le runtime MCP du bundle Pi intégré, exécute l’outil, puis vérifie que `coding` et `messaging` conservent les outils -`bundle-mcp` tandis que `minimal` et `tools.deny: ["bundle-mcp"]` les filtrent. -`test:docker:cron-mcp-cleanup` est déterministe et n’a pas besoin d’une clé de modèle -en direct. Il démarre un Gateway initialisé avec un vrai serveur de sonde MCP stdio, exécute -un tour Cron isolé et un tour enfant ponctuel `/subagents spawn`, puis vérifie +`bundle-mcp`, tandis que `minimal` et `tools.deny: ["bundle-mcp"]` les filtrent. +`test:docker:cron-mcp-cleanup` est déterministe et ne nécessite pas de clé de modèle live. +Il démarre un Gateway avec données initiales et un vrai serveur de sonde MCP stdio, exécute un +tour cron isolé et un tour enfant ponctuel `/subagents spawn`, puis vérifie que le processus enfant MCP se termine après chaque exécution. -Test de fumée manuel ACP de fil en langage naturel (hors CI) : +Smoke manuel ACP de thread en langage naturel (hors CI) : - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conservez ce script pour les workflows de régression/débogage. Il peut être nécessaire à nouveau pour la validation du routage des fils ACP, donc ne le supprimez pas. +- Conservez ce script pour les workflows de régression/débogage. Il pourrait être à nouveau nécessaire pour la validation du routage de thread ACP ; ne le supprimez donc pas. Variables d’environnement utiles : - `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté sur `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté sur `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté sur `/home/node/.profile` et sourcé avant l’exécution des tests -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement sourcées depuis `OPENCLAW_PROFILE_FILE`, avec des répertoires temporaires de config/espace de travail et sans montages d’authentification CLI externes +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement sourcées depuis `OPENCLAW_PROFILE_FILE`, avec des répertoires de configuration/espace de travail temporaires et aucun montage d’authentification CLI externe - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour les installations CLI mises en cache dans Docker -- Les répertoires/fichiers d’authentification CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés dans `/home/node/...` avant le début des tests +- Les répertoires/fichiers d’authentification CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés dans `/home/node/...` avant le démarrage des tests - Répertoires par défaut : `.minimax` - Fichiers par défaut : `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Les exécutions restreintes par fournisseur ne montent que les répertoires/fichiers nécessaires déduits de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Remplacez manuellement avec `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, ou une liste séparée par des virgules comme `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Les exécutions limitées à un fournisseur ne montent que les répertoires/fichiers nécessaires déduits de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Remplacement manuel avec `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, ou une liste séparée par des virgules comme `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` pour restreindre l’exécution - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` pour filtrer les fournisseurs dans le conteneur -- `OPENCLAW_SKIP_DOCKER_BUILD=1` pour réutiliser une image `openclaw:local-live` existante pour les réexécutions qui n’ont pas besoin d’une reconstruction -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour s’assurer que les identifiants viennent du magasin de profils (et non de l’environnement) -- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par le Gateway pour le test de fumée Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer l’invite de vérification du nonce utilisée par le test de fumée Open WebUI -- `OPENWEBUI_IMAGE=...` pour remplacer l’étiquette d’image Open WebUI épinglée +- `OPENCLAW_SKIP_DOCKER_BUILD=1` pour réutiliser une image `openclaw:local-live` existante lors de réexécutions qui ne nécessitent pas de rebuild +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour garantir que les identifiants proviennent du magasin de profil (et non de l’environnement) +- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par le gateway pour le smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer le prompt de vérification par nonce utilisé par le smoke Open WebUI +- `OPENWEBUI_IMAGE=...` pour remplacer le tag d’image Open WebUI épinglé -## Contrôle d’intégrité de la documentation +## Vérification de cohérence des docs -Exécutez les vérifications de documentation après les modifications de documentation : `pnpm check:docs`. +Exécutez les vérifications de docs après les modifications de documentation : `pnpm check:docs`. Exécutez la validation complète des ancres Mintlify lorsque vous devez aussi vérifier les titres dans la page : `pnpm docs:check-links:anchors`. -## Régressions hors ligne (compatibles avec CI) +## Régression hors ligne (compatible CI) -Ce sont des régressions de « chaîne réelle » sans vrais fournisseurs : +Ce sont des régressions de « vrai pipeline » sans vrais fournisseurs : -- Appel d’outils du Gateway (OpenAI simulé, vrai Gateway + boucle d’agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistant du Gateway (WS `wizard.start`/`wizard.next`, écrit la config + authentification appliquée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") +- Appel d’outil Gateway (OpenAI simulé, vrai gateway + boucle agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistant Gateway (WS `wizard.start`/`wizard.next`, écrit la config + auth appliquée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") -## Évaluations de fiabilité des agents (Skills) +## Évaluations de fiabilité d’agent (Skills) -Nous avons déjà quelques tests compatibles avec CI qui se comportent comme des « évaluations de fiabilité des agents » : +Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité d’agent » : -- Appel d’outils simulé via le vrai Gateway + boucle d’agent (`src/gateway/gateway.test.ts`). +- Appel d’outil simulé via le vrai gateway + boucle agent (`src/gateway/gateway.test.ts`). - Flux d’assistant de bout en bout qui valident le câblage de session et les effets de configuration (`src/gateway/gateway.test.ts`). -Ce qui manque encore pour les Skills (voir [Skills](/fr/tools/skills)) : +Ce qui manque encore pour Skills (voir [Skills](/fr/tools/skills)) : -- **Décision :** lorsque des Skills sont listées dans l’invite, l’agent choisit-il la bonne Skill (ou évite-t-il celles qui ne sont pas pertinentes) ? +- **Décision :** lorsque des Skills sont listées dans le prompt, l’agent choisit-il la bonne Skills (ou évite-t-il celles qui ne sont pas pertinentes) ? - **Conformité :** l’agent lit-il `SKILL.md` avant utilisation et suit-il les étapes/arguments requis ? -- **Contrats de workflow :** scénarios à plusieurs tours qui vérifient l’ordre des outils, la conservation de l’historique de session et les limites du bac à sable. +- **Contrats de workflow :** scénarios multi-tours qui vérifient l’ordre des outils, la continuité de l’historique de session et les limites du bac à sable. -Les futures évaluations doivent d’abord rester déterministes : +Les futures évaluations doivent rester déterministes d’abord : -- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + leur ordre, les lectures de fichiers de Skills et le câblage de session. -- Une petite suite de scénarios centrés sur les Skills (utiliser ou éviter, contrôles de déclenchement, injection d’invite). -- Évaluations en direct facultatives (activation explicite, contrôlées par variables d’environnement) uniquement une fois la suite compatible avec CI en place. +- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + l’ordre, les lectures de fichiers de Skills et le câblage de session. +- Une petite suite de scénarios centrés sur Skills (utiliser vs éviter, garde-fous, injection de prompt). +- Des évaluations live optionnelles (opt-in, contrôlées par l’environnement) uniquement après la mise en place de la suite compatible CI. -## Tests de contrat (forme des plugins et des canaux) +## Tests de contrat (forme Plugin et canal) -Les tests de contrat vérifient que chaque plugin et chaque canal enregistré respecte son -contrat d’interface. Ils itèrent sur tous les plugins découverts et exécutent une suite -d’assertions de forme et de comportement. La voie unitaire `pnpm test` par défaut ignore intentionnellement -ces fichiers partagés de points d’intégration et de tests de fumée ; exécutez explicitement les commandes de contrat -lorsque vous touchez des surfaces partagées de canal ou de fournisseur. +Les tests de contrat vérifient que chaque Plugin et canal enregistré respecte son +contrat d’interface. Ils parcourent tous les Plugins découverts et exécutent une suite +d’assertions de forme et de comportement. La voie unitaire `pnpm test` par défaut +ignore intentionnellement ces fichiers partagés de smoke et de jonction ; exécutez explicitement +les commandes de contrat lorsque vous touchez des surfaces partagées de canal ou de fournisseur. ### Commandes - Tous les contrats : `pnpm test:contracts` -- Contrats de canaux uniquement : `pnpm test:contracts:channels` -- Contrats de fournisseurs uniquement : `pnpm test:contracts:plugins` +- Contrats de canal uniquement : `pnpm test:contracts:channels` +- Contrats de fournisseur uniquement : `pnpm test:contracts:plugins` -### Contrats des canaux +### Contrats de canal Situés dans `src/channels/plugins/contracts/*.contract.test.ts` : -- **plugin** - Forme de base du plugin (id, nom, capacités) -- **configuration** - Contrat de l’assistant de configuration -- **liaison de session** - Comportement de liaison de session -- **charge utile sortante** - Structure de charge utile des messages -- **entrant** - Gestion des messages entrants +- **plugin** - Forme de Plugin de base (id, nom, capacités) +- **setup** - Contrat de l’assistant de configuration +- **session-binding** - Comportement de liaison de session +- **outbound-payload** - Structure de charge utile de message +- **inbound** - Traitement des messages entrants - **actions** - Gestionnaires d’actions de canal -- **fils** - Gestion des identifiants de fil -- **annuaire** - API d’annuaire/liste -- **politique de groupe** - Application de la politique de groupe +- **threading** - Gestion des ID de thread +- **directory** - API d’annuaire/liste des participants +- **group-policy** - Application de la politique de groupe -### Contrats d’état des fournisseurs +### Contrats de statut des fournisseurs Situés dans `src/plugins/contracts/*.contract.test.ts`. -- **état** - Sondes d’état des canaux -- **registre** - Forme du registre des plugins +- **status** - Sondes de statut de canal +- **registry** - Forme du registre de Plugins -### Contrats des fournisseurs +### Contrats de fournisseur Situés dans `src/plugins/contracts/*.contract.test.ts` : -- **authentification** - Contrat de flux d’authentification -- **choix d’authentification** - Choix/sélection d’authentification -- **catalogue** - API de catalogue des modèles -- **découverte** - Découverte des plugins -- **chargeur** - Chargement des plugins -- **exécution** - Exécution du fournisseur -- **forme** - Forme/interface du plugin -- **assistant** - Assistant de configuration +- **auth** - Contrat de flux d’authentification +- **auth-choice** - Choix/sélection d’authentification +- **catalog** - API de catalogue de modèles +- **discovery** - Découverte de Plugin +- **loader** - Chargement de Plugin +- **runtime** - Runtime fournisseur +- **shape** - Forme/interface de Plugin +- **wizard** - Assistant de configuration -### Quand exécuter +### Quand les exécuter -- Après modification des exports ou sous-chemins de plugin-sdk -- Après ajout ou modification d’un plugin de canal ou de fournisseur -- Après refactorisation de l’enregistrement ou de la découverte des plugins +- Après avoir modifié les exports ou sous-chemins de plugin-sdk +- Après avoir ajouté ou modifié un Plugin de canal ou de fournisseur +- Après avoir refactorisé l’enregistrement ou la découverte de Plugins -Les tests de contrat s’exécutent dans CI et ne nécessitent pas de vraies clés API. +Les tests de contrat s’exécutent en CI et ne nécessitent pas de vraies clés API. -## Ajout de régressions (conseils) +## Ajouter des régressions (conseils) -Lorsque vous corrigez un problème de fournisseur/modèle découvert en direct : +Lorsque vous corrigez un problème de fournisseur/modèle découvert en live : -- Ajoutez si possible une régression compatible avec CI (fournisseur simulé/stub, ou capture de la transformation exacte de forme de requête) -- Si c’est intrinsèquement uniquement en direct (limites de débit, politiques d’authentification), gardez le test en direct restreint et à activation explicite via variables d’environnement -- Préférez cibler la plus petite couche qui détecte le bug : - - bug de conversion/relecture de requête fournisseur → test direct des modèles - - bug de session/historique/pipeline d’outils du Gateway → test de fumée en direct du Gateway ou test simulé du Gateway compatible avec CI -- Garde-fou de parcours SecretRef : - - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef à partir des métadonnées du registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec avec segments de parcours sont rejetés. - - Si vous ajoutez une nouvelle famille de cibles SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue intentionnellement sur les identifiants de cibles non classés afin que les nouvelles classes ne puissent pas être ignorées silencieusement. +- Ajoutez une régression compatible CI si possible (fournisseur mock/stub, ou capture de la transformation exacte de forme de requête) +- Si c’est intrinsèquement live uniquement (limites de débit, politiques d’authentification), gardez le test live ciblé et opt-in via des variables d’environnement +- Préférez cibler la plus petite couche qui attrape le bug : + - bug de conversion/relecture de requête fournisseur → test direct de modèles + - bug de pipeline session/historique/outil du gateway → smoke live gateway ou test mock gateway compatible CI +- Garde-fou de traversée SecretRef : + - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef depuis les métadonnées de registre (`listSecretTargetRegistryEntries()`), puis vérifie que les ids exec avec segment de traversée sont rejetés. + - Si vous ajoutez une nouvelle famille de cibles SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue intentionnellement sur les ids de cible non classifiés afin que les nouvelles classes ne puissent pas être ignorées silencieusement. ## Connexe -- [Tests en direct](/fr/help/testing-live) -- [Tests des mises à jour et des plugins](/fr/help/testing-updates-plugins) +- [Tester en live](/fr/help/testing-live) +- [Tester les mises à jour et les Plugins](/fr/help/testing-updates-plugins) - [CI](/fr/ci) diff --git a/docs/fr/platforms/windows.md b/docs/fr/platforms/windows.md index 5741d4a3c..3811823ae 100644 --- a/docs/fr/platforms/windows.md +++ b/docs/fr/platforms/windows.md @@ -1,78 +1,78 @@ --- read_when: - - Installer OpenClaw sur Windows + - Installation d’OpenClaw sur Windows - Choisir entre Windows natif et WSL2 - - À la recherche du statut de l’app compagnon Windows -summary: 'Prise en charge de Windows : parcours d’installation natifs et WSL2, daemon et limites actuelles' + - Recherche de l’état de l’application compagnon pour Windows +summary: 'Prise en charge de Windows : parcours d’installation natif et WSL2, démon et limitations actuelles' title: Windows x-i18n: - generated_at: "2026-04-24T07:21:51Z" - model: gpt-5.4 + generated_at: "2026-05-05T06:17:58Z" + model: gpt-5.5 provider: openai - source_hash: dc147a9da97ab911ba7529c2170526c50c86711efe6fdf4854e6e0370e4d64ea + source_hash: adf885747e3a897cb4ee57f6494805468d38c4595c0ab7582b063153a1134d18 source_path: platforms/windows.md - workflow: 15 + workflow: 16 --- -OpenClaw prend en charge à la fois **Windows natif** et **WSL2**. WSL2 est la voie la plus -stable et recommandée pour l’expérience complète — la CLI, le Gateway et +OpenClaw prend en charge à la fois **Windows natif** et **WSL2**. WSL2 est le chemin le plus +stable et recommandé pour l’expérience complète : la CLI, le Gateway et l’outillage s’exécutent dans Linux avec une compatibilité totale. Windows natif fonctionne pour -l’usage principal de la CLI et du Gateway, avec certaines limites indiquées ci-dessous. +l’utilisation de base de la CLI et du Gateway, avec certaines réserves indiquées ci-dessous. -Des apps compagnons natives pour Windows sont prévues. +Les applications compagnon Windows natives sont prévues. ## WSL2 (recommandé) - [Premiers pas](/fr/start/getting-started) (à utiliser dans WSL) - [Installation et mises à jour](/fr/install/updating) -- Guide officiel WSL2 (Microsoft) : [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) +- Guide officiel de WSL2 (Microsoft) : [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) -## Statut de Windows natif +## État de Windows natif -Les flux CLI natifs Windows s’améliorent, mais WSL2 reste la voie recommandée. +Les flux CLI Windows natifs s’améliorent, mais WSL2 reste le chemin recommandé. Ce qui fonctionne bien sur Windows natif aujourd’hui : -- installateur du site via `install.ps1` -- usage local de la CLI comme `openclaw --version`, `openclaw doctor`, et `openclaw plugins list --json` -- smoke embarqué local-agent/provider tel que : +- programme d’installation du site web via `install.ps1` +- utilisation locale de la CLI, comme `openclaw --version`, `openclaw doctor` et `openclaw plugins list --json` +- test de validation rapide de l’agent/fournisseur local intégré, comme : ```powershell openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK." ``` -Limites actuelles : +Réserves actuelles : -- `openclaw onboard --non-interactive` attend toujours un gateway local joignable sauf si vous passez `--skip-health` -- `openclaw onboard --non-interactive --install-daemon` et `openclaw gateway install` tentent d’abord les tâches planifiées Windows -- si la création de tâche planifiée est refusée, OpenClaw revient à un élément de connexion du dossier Startup par utilisateur et démarre immédiatement le gateway -- si `schtasks` lui-même se bloque ou cesse de répondre, OpenClaw abandonne désormais rapidement ce chemin et revient au repli au lieu de rester bloqué indéfiniment -- les tâches planifiées restent préférées lorsqu’elles sont disponibles car elles fournissent un meilleur état du superviseur +- `openclaw onboard --non-interactive` attend toujours un Gateway local accessible, sauf si vous passez `--skip-health` +- `openclaw onboard --non-interactive --install-daemon` et `openclaw gateway install` essaient d’abord les tâches planifiées Windows +- si la création de tâche planifiée est refusée, OpenClaw se rabat sur un élément de connexion par utilisateur dans le dossier de démarrage et démarre immédiatement le Gateway +- si `schtasks` lui-même se bloque ou cesse de répondre, OpenClaw abandonne désormais rapidement ce chemin et se rabat au lieu de rester suspendu indéfiniment +- les tâches planifiées restent privilégiées lorsqu’elles sont disponibles, car elles fournissent un meilleur état de supervision -Si vous voulez uniquement la CLI native, sans installation du service gateway, utilisez l’une de ces commandes : +Si vous voulez uniquement la CLI native, sans installation du service Gateway, utilisez l’une de ces commandes : ```powershell openclaw onboard --non-interactive --skip-health openclaw gateway run ``` -Si vous voulez un démarrage géré sur Windows natif : +Si vous voulez bien un démarrage géré sur Windows natif : ```powershell openclaw gateway install openclaw gateway status --json ``` -Si la création de tâche planifiée est bloquée, le mode de service de repli démarre quand même automatiquement après connexion via le dossier Startup de l’utilisateur courant. +Si la création de tâche planifiée est bloquée, le mode de service de secours démarre tout de même automatiquement après la connexion via le dossier de démarrage de l’utilisateur actuel. ## Gateway -- [Guide d’exploitation du Gateway](/fr/gateway) +- [Runbook Gateway](/fr/gateway) - [Configuration](/fr/gateway/configuration) ## Installation du service Gateway (CLI) -À l’intérieur de WSL2 : +Dans WSL2 : ``` openclaw onboard --install-daemon @@ -90,7 +90,7 @@ Ou : openclaw configure ``` -Sélectionnez **Gateway service** lorsque cela vous est demandé. +Sélectionnez **Service Gateway** lorsque l’invite s’affiche. Réparer/migrer : @@ -98,11 +98,12 @@ Réparer/migrer : openclaw doctor ``` -## Démarrage automatique du Gateway avant connexion Windows +## Démarrage automatique du Gateway avant la connexion Windows -Pour les configurations headless, assurez-vous que toute la chaîne de démarrage s’exécute même si personne ne se connecte à Windows. +Pour les configurations sans interface, assurez-vous que toute la chaîne de démarrage s’exécute même lorsque personne ne se connecte à +Windows. -### 1) Garder les services utilisateur actifs sans connexion +### 1) Maintenir les services utilisateur en cours d’exécution sans connexion Dans WSL : @@ -110,7 +111,7 @@ Dans WSL : sudo loginctl enable-linger "$(whoami)" ``` -### 2) Installer le service utilisateur Gateway OpenClaw +### 2) Installer le service utilisateur du Gateway OpenClaw Dans WSL : @@ -118,7 +119,7 @@ Dans WSL : openclaw gateway install ``` -### 3) Démarrer WSL automatiquement au boot Windows +### 3) Démarrer WSL automatiquement au démarrage de Windows Dans PowerShell en tant qu’administrateur : @@ -145,7 +146,7 @@ systemctl --user status openclaw-gateway.service --no-pager WSL possède son propre réseau virtuel. Si une autre machine doit atteindre un service s’exécutant **dans WSL** (SSH, un serveur TTS local ou le Gateway), vous devez -transférer un port Windows vers l’IP WSL courante. L’IP WSL change après les redémarrages, +transférer un port Windows vers l’IP WSL actuelle. L’IP WSL change après les redémarrages, vous devrez donc peut-être actualiser la règle de transfert. Exemple (PowerShell **en tant qu’administrateur**) : @@ -169,7 +170,7 @@ New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound ` -Protocol TCP -LocalPort $ListenPort -Action Allow ``` -Actualisez le portproxy après le redémarrage de WSL : +Actualisez le portproxy après les redémarrages de WSL : ```powershell netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null @@ -177,31 +178,31 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0. connectaddress=$WslIp connectport=$TargetPort | Out-Null ``` -Remarques : +Notes : -- Le SSH depuis une autre machine cible l’**IP de l’hôte Windows** (exemple : `ssh user@windows-host -p 2222`). -- Les nodes distants doivent pointer vers une URL Gateway **joignable** (pas `127.0.0.1`) ; utilisez +- SSH depuis une autre machine cible l’**IP de l’hôte Windows** (exemple : `ssh user@windows-host -p 2222`). +- Les nœuds distants doivent pointer vers une URL de Gateway **accessible** (pas `127.0.0.1`) ; utilisez `openclaw status --all` pour confirmer. -- Utilisez `listenaddress=0.0.0.0` pour l’accès LAN ; `127.0.0.1` le garde local uniquement. -- Si vous voulez automatiser cela, enregistrez une tâche planifiée pour exécuter l’étape +- Utilisez `listenaddress=0.0.0.0` pour l’accès LAN ; `127.0.0.1` le garde uniquement local. +- Si vous voulez que cela soit automatique, enregistrez une tâche planifiée pour exécuter l’étape d’actualisation à la connexion. ## Installation WSL2 étape par étape ### 1) Installer WSL2 + Ubuntu -Ouvrez PowerShell (Admin) : +Ouvrez PowerShell (administrateur) : ```powershell wsl --install -# Ou choisissez explicitement une distribution : +# Or pick a distro explicitly: wsl --list --online wsl --install -d Ubuntu-24.04 ``` Redémarrez si Windows le demande. -### 2) Activer systemd (requis pour l’installation du gateway) +### 2) Activer systemd (requis pour l’installation du Gateway) Dans votre terminal WSL : @@ -212,7 +213,7 @@ systemd=true EOF ``` -Puis, depuis PowerShell : +Puis depuis PowerShell : ```powershell wsl --shutdown @@ -226,7 +227,7 @@ systemctl --user status ### 3) Installer OpenClaw (dans WSL) -Pour une configuration normale initiale dans WSL, suivez le flux Linux Premiers pas : +Pour une configuration initiale normale dans WSL, suivez le flux Linux Premiers pas : ```bash git clone https://github.com/openclaw/openclaw.git @@ -237,24 +238,56 @@ pnpm ui:build pnpm openclaw onboard --install-daemon ``` -Si vous développez depuis les sources au lieu de faire un onboarding initial, utilisez la -boucle de développement source de [Setup](/fr/start/setup) : +Si vous développez depuis les sources au lieu d’effectuer une configuration initiale, utilisez la +boucle de développement source de [Configuration](/fr/start/setup) : ```bash pnpm install -# Premier lancement uniquement (ou après réinitialisation de la config/de l’espace de travail OpenClaw locaux) +# First run only (or after resetting local OpenClaw config/workspace) pnpm openclaw setup pnpm gateway:watch ``` Guide complet : [Premiers pas](/fr/start/getting-started) -## App compagnon Windows +## Application compagnon Windows -Nous n’avons pas encore d’app compagnon Windows. Les contributions sont les bienvenues si vous voulez -aider à la rendre possible. +Nous n’avons pas encore d’application compagnon Windows. Les contributions sont les bienvenues si vous voulez +aider à la concrétiser. -## Articles connexes +## Connectivité Git et GitHub (contributeurs) + +Certains réseaux bloquent ou limitent HTTPS vers GitHub. Si `git clone` échoue avec des délais d’attente +ou des réinitialisations de connexion, essayez un autre réseau, un VPN ou un proxy HTTP/HTTPS fourni par votre +organisation. + +Si `gh auth login` échoue pendant le flux d’appareil du navigateur (par exemple avec un délai d’attente +pour atteindre `github.com:443`), authentifiez-vous plutôt avec un jeton d’accès personnel : + +1. Créez un jeton avec au moins la portée `repo` (PAT classique) ou un accès + finement granulaire équivalent. +2. Dans PowerShell pour la session actuelle : + +```powershell +$env:GH_TOKEN="" +gh auth status +gh auth setup-git +``` + +3. Si `gh auth status` avertit que `read:org` est manquant, créez un jeton qui inclut + cette portée et réaffectez la variable : + +```powershell +$env:GH_TOKEN="" +gh auth status +``` + +`gh auth refresh -s read:org` s’applique uniquement lorsque vous vous êtes authentifié via `gh auth login` +et que vous avez des identifiants stockés à actualiser (pas lorsque vous utilisez `GH_TOKEN`). + +Ne commettez jamais de jetons et ne les collez jamais dans des issues ou des pull requests. + +## Connexe - [Vue d’ensemble de l’installation](/fr/install) - [Plateformes](/fr/platforms) diff --git a/docs/fr/plugins/reference/whatsapp.md b/docs/fr/plugins/reference/whatsapp.md index 7de2bc829..87905bdc8 100644 --- a/docs/fr/plugins/reference/whatsapp.md +++ b/docs/fr/plugins/reference/whatsapp.md @@ -1,13 +1,13 @@ --- read_when: - - Vous installez, configurez ou auditez le plugin WhatsApp -summary: Ajoute l’interface du canal WhatsApp pour envoyer et recevoir des messages OpenClaw. + - Vous installez, configurez ou auditez le Plugin WhatsApp +summary: Ajoute la surface de canal WhatsApp pour envoyer et recevoir des messages OpenClaw. title: Plugin WhatsApp x-i18n: - generated_at: "2026-05-03T07:14:37Z" + generated_at: "2026-05-05T06:18:18Z" model: gpt-5.5 provider: openai - source_hash: 3ff038ce3afd0285e5cfca9ca1b0e89deed582cff4f2e9c257f29a4848f397fa + source_hash: a0fa274f7e937894a070abd9307aa12eed17b27275bc7e5cfc432f8a41373c54 source_path: plugins/reference/whatsapp.md workflow: 16 --- @@ -19,11 +19,21 @@ Ajoute la surface de canal WhatsApp pour l’envoi et la réception de messages ## Distribution - Paquet : `@openclaw/whatsapp` -- Méthode d’installation : npm ; ClawHub +- Mode d’installation : npm ; ClawHub ## Surface -canaux : whatsapp +channels: whatsapp + +## Note d’installation sous Windows + +Sous Windows, le Plugin WhatsApp a besoin que Git soit dans le `PATH` pendant l’installation npm, car l’une de ses dépendances Baileys/libsignal est récupérée depuis une URL git. Installez Git for Windows, puis redémarrez le shell et relancez l’installation : + +```powershell +winget install --id Git.Git -e +``` + +Portable Git fonctionne également si son répertoire `bin` est dans le `PATH`. ## Documentation associée diff --git a/docs/fr/reference/RELEASING.md b/docs/fr/reference/RELEASING.md index 1e7f4bb61..b978e7c9f 100644 --- a/docs/fr/reference/RELEASING.md +++ b/docs/fr/reference/RELEASING.md @@ -1,50 +1,50 @@ --- read_when: - Recherche des définitions des canaux de publication publics - - Exécution de la validation de publication ou de l’acceptation de paquet - - Recherche de la nomenclature des versions et de la cadence -summary: Voies de publication, liste de contrôle de l’opérateur, boîtes de validation, nommage des versions et cadence + - Exécution de la validation de version ou de l’acceptation de package + - Recherche des conventions de nommage des versions et de la cadence +summary: Voies de publication, liste de contrôle opérateur, boîtes de validation, nommage des versions et cadence title: Politique de publication x-i18n: - generated_at: "2026-05-05T01:49:23Z" + generated_at: "2026-05-05T06:18:55Z" model: gpt-5.5 provider: openai - source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3 + source_hash: 9980265c30c6a6571db5512749ec173cca79ac70494fd09968add793be9717a5 source_path: reference/RELEASING.md workflow: 16 --- -OpenClaw comporte trois canaux de publication publics : +OpenClaw comporte trois canaux publics de publication : -- stable : publications étiquetées publiées sur npm `beta` par défaut, ou sur npm `latest` lorsqu’elles sont explicitement demandées -- beta : étiquettes de prépublication publiées sur npm `beta` -- dev : la tête mobile de `main` +- stable : publications étiquetées qui publient vers npm `beta` par défaut, ou vers npm `latest` lorsque cela est explicitement demandé +- beta : tags de préversion qui publient vers npm `beta` +- dev : tête mouvante de `main` ## Nommage des versions - Version de publication stable : `YYYY.M.D` - - Étiquette Git : `vYYYY.M.D` -- Version de publication corrective stable : `YYYY.M.D-N` - - Étiquette Git : `vYYYY.M.D-N` -- Version de prépublication beta : `YYYY.M.D-beta.N` - - Étiquette Git : `vYYYY.M.D-beta.N` -- Ne mettez pas de zéro initial au mois ni au jour + - Tag Git : `vYYYY.M.D` +- Version de correction stable : `YYYY.M.D-N` + - Tag Git : `vYYYY.M.D-N` +- Version de préversion bêta : `YYYY.M.D-beta.N` + - Tag Git : `vYYYY.M.D-beta.N` +- Ne pas ajouter de zéro initial au mois ni au jour - `latest` désigne la publication npm stable actuellement promue -- `beta` désigne la cible d’installation beta actuelle -- Les publications stables et correctives stables sont publiées sur npm `beta` par défaut ; les opérateurs de publication peuvent cibler explicitement `latest`, ou promouvoir plus tard une build beta validée +- `beta` désigne la cible actuelle d’installation bêta +- Les publications stables et les publications de correction stables publient vers npm `beta` par défaut ; les opérateurs de publication peuvent cibler explicitement `latest`, ou promouvoir ultérieurement une version bêta validée - Chaque publication stable d’OpenClaw livre ensemble le package npm et l’application macOS ; - les publications beta valident et publient normalement d’abord le chemin npm/package, avec - la build/signature/notarisation de l’app Mac réservée au stable sauf demande explicite + les publications bêta valident et publient normalement d’abord le chemin npm/package, la + compilation/signature/notarisation de l’application Mac étant réservée aux versions stables sauf demande explicite ## Cadence de publication -- Les publications avancent d’abord par la beta -- Le stable ne suit qu’après validation de la dernière beta -- Les mainteneurs découpent normalement les publications depuis une branche `release/YYYY.M.D` créée - depuis le `main` courant, afin que la validation et les correctifs de publication ne bloquent pas le nouveau +- Les publications passent d’abord par la bêta +- La version stable ne suit qu’après validation de la dernière bêta +- Les mainteneurs créent normalement les publications depuis une branche `release/YYYY.M.D` créée + à partir du `main` actuel, afin que la validation de publication et les correctifs ne bloquent pas le nouveau développement sur `main` -- Si une étiquette beta a été poussée ou publiée et nécessite un correctif, les mainteneurs découpent - l’étiquette `-beta.N` suivante au lieu de supprimer ou recréer l’ancienne étiquette beta +- Si un tag bêta a été poussé ou publié et nécessite un correctif, les mainteneurs créent + le tag `-beta.N` suivant au lieu de supprimer ou recréer l’ancien tag bêta - La procédure de publication détaillée, les approbations, les identifiants et les notes de récupération sont réservés aux mainteneurs @@ -54,130 +54,235 @@ Cette liste de contrôle décrit la forme publique du flux de publication. Les i la signature, la notarisation, la récupération des dist-tags et les détails de rollback d’urgence restent dans le runbook de publication réservé aux mainteneurs. -1. Partez du `main` courant : récupérez les dernières modifications, confirmez que le commit cible est poussé, - et confirmez que la CI actuelle de `main` est suffisamment verte pour créer une branche depuis celui-ci. -2. Réécrivez la section supérieure de `CHANGELOG.md` depuis l’historique réel des commits avec - `/changelog`, gardez des entrées orientées utilisateur, commitez-la, poussez-la, puis rebasez/récupérez +1. Partir du `main` actuel : récupérer la dernière version, confirmer que le commit cible est poussé, + et confirmer que la CI actuelle de `main` est suffisamment verte pour créer une branche à partir de celui-ci. +2. Réécrire la section supérieure de `CHANGELOG.md` à partir de l’historique réel des commits avec + `/changelog`, garder les entrées orientées utilisateur, la committer, la pousser, puis rebaser/récupérer une fois de plus avant de créer la branche. -3. Passez en revue les enregistrements de compatibilité de publication dans +3. Examiner les enregistrements de compatibilité de publication dans `src/plugins/compat/registry.ts` et - `src/commands/doctor/shared/deprecation-compat.ts`. Supprimez la compatibilité expirée - uniquement lorsque le chemin de mise à niveau reste couvert, ou consignez pourquoi elle est - intentionnellement conservée. -4. Créez `release/YYYY.M.D` depuis le `main` courant ; n’effectuez pas le travail normal de publication + `src/commands/doctor/shared/deprecation-compat.ts`. Supprimer la compatibilité expirée + uniquement lorsque le chemin de mise à niveau reste couvert, ou consigner pourquoi elle est + volontairement conservée. +4. Créer `release/YYYY.M.D` depuis le `main` actuel ; ne pas effectuer le travail normal de publication directement sur `main`. -5. Incrémentez chaque emplacement de version requis pour l’étiquette prévue, exécutez +5. Incrémenter chaque emplacement de version requis pour le tag prévu, exécuter `pnpm plugins:sync` afin que les packages Plugin publiables partagent la version de publication - et les métadonnées de compatibilité, puis exécutez le prévol déterministe local : + et les métadonnées de compatibilité, puis exécuter le prévol déterministe local : `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, et `pnpm release:check`. -6. Exécutez `OpenClaw NPM Release` avec `preflight_only=true`. Avant qu’une étiquette existe, - un SHA complet de branche de publication à 40 caractères est autorisé pour un prévol - de validation uniquement. Enregistrez le `preflight_run_id` réussi. -7. Lancez tous les tests de prépublication avec `Full Release Validation` pour la - branche de publication, l’étiquette ou le SHA complet du commit. C’est le seul point d’entrée manuel +6. Exécuter `OpenClaw NPM Release` avec `preflight_only=true`. Avant qu’un tag existe, + un SHA complet de 40 caractères de la branche de publication est autorisé pour le prévol de validation uniquement. + Enregistrer le `preflight_run_id` réussi. +7. Lancer tous les tests de prépublication avec `Full Release Validation` pour la + branche de publication, le tag ou le SHA complet du commit. C’est le seul point d’entrée manuel pour les quatre grandes boîtes de test de publication : Vitest, Docker, QA Lab et Package. -8. Si la validation échoue, corrigez sur la branche de publication et relancez le plus petit - fichier, canal, job de workflow, profil de package, fournisseur ou allowlist de modèles ayant échoué qui - prouve le correctif. Ne relancez l’ensemble complet que lorsque la surface modifiée rend +8. Si la validation échoue, corriger sur la branche de publication et relancer le plus petit + fichier, canal, job de workflow, profil de package, fournisseur ou liste d’autorisation de modèles en échec qui + prouve le correctif. Relancer l’ensemble complet uniquement lorsque la surface modifiée rend les preuves précédentes obsolètes. -9. Pour beta, étiquetez `vYYYY.M.D-beta.N`, puis exécutez `OpenClaw Release Publish` depuis +9. Pour la bêta, taguer `vYYYY.M.D-beta.N`, puis exécuter `OpenClaw Release Publish` depuis la branche `release/YYYY.M.D` correspondante. Il vérifie `pnpm plugins:sync:check`, - publie d’abord tous les packages Plugin publiables sur npm, publie ensuite le même - ensemble sur ClawHub sous forme de tarballs npm-pack ClawPack, puis promeut l’artefact - de prévol npm OpenClaw préparé avec le dist-tag correspondant. Après la publication, - exécutez l’acceptation de package post-publication + publie d’abord tous les packages Plugin publiables vers npm, publie ensuite le même + ensemble vers ClawHub sous forme de tarballs ClawPack npm-pack, puis promeut + l’artifact de prévol npm OpenClaw préparé avec le dist-tag correspondant. Après + publication, exécuter l’acceptation de package post-publication contre le package publié `openclaw@YYYY.M.D-beta.N` ou - `openclaw@beta`. Si une prépublication poussée ou publiée nécessite un correctif, - découpez le numéro de prépublication correspondant suivant ; ne supprimez pas et ne réécrivez pas l’ancienne - prépublication. -10. Pour stable, continuez uniquement après que la beta validée ou la release candidate dispose des - preuves de validation requises. La publication npm stable passe aussi par - `OpenClaw Release Publish`, en réutilisant l’artefact de prévol réussi via - `preflight_run_id` ; la préparation de la publication macOS stable exige aussi les - `.zip`, `.dmg`, `.dSYM.zip` packagés, ainsi que `appcast.xml` mis à jour sur `main`. -11. Après la publication, exécutez le vérificateur npm post-publication, l’E2E Telegram npm publié - autonome optionnel lorsque vous avez besoin d’une preuve de canal post-publication, - la promotion de dist-tag si nécessaire, les notes de publication/prépublication GitHub depuis la - section `CHANGELOG.md` correspondante complète, et les étapes d’annonce de publication. + `openclaw@beta`. Si une préversion poussée ou publiée nécessite un correctif, + créer le numéro de préversion correspondant suivant ; ne pas supprimer ni réécrire l’ancienne + préversion. +10. Pour la version stable, continuer uniquement après que la bêta validée ou la release candidate dispose des + preuves de validation requises. La publication npm stable passe également par + `OpenClaw Release Publish`, en réutilisant l’artifact de prévol réussi via + `preflight_run_id` ; l’état prêt pour la publication macOS stable exige également les + fichiers empaquetés `.zip`, `.dmg`, `.dSYM.zip`, et le fichier `appcast.xml` mis à jour sur `main`. +11. Après publication, exécuter le vérificateur npm post-publication, l’E2E Telegram npm publié autonome facultatif + lorsque vous avez besoin d’une preuve de canal post-publication, + la promotion des dist-tags si nécessaire, les notes de publication/préversion GitHub à partir de la + section complète correspondante de `CHANGELOG.md`, et les étapes d’annonce de publication. ## Prévol de publication -- Exécutez `pnpm check:test-types` avant le contrôle préliminaire de publication afin que le TypeScript des tests reste couvert en dehors de la porte locale plus rapide `pnpm check` -- Exécutez `pnpm check:architecture` avant le contrôle préliminaire de publication afin que les vérifications plus larges des cycles d’importation et des limites d’architecture soient au vert en dehors de la porte locale plus rapide -- Exécutez `pnpm build && pnpm ui:build` avant `pnpm release:check` afin que les artefacts de publication attendus `dist/*` et le bundle de l’interface utilisateur de contrôle existent pour l’étape de validation du paquet -- Exécutez `pnpm plugins:sync` après l’augmentation de version racine et avant le marquage. Il met à jour les versions des packages de plugins publiables, les métadonnées de compatibilité pair/API OpenClaw, les métadonnées de build et les ébauches de journaux des modifications des plugins afin qu’ils correspondent à la version de publication du cœur. `pnpm plugins:sync:check` est la garde de publication non mutante ; le workflow de publication échoue avant toute mutation du registre si cette étape a été oubliée. -- Exécutez le workflow manuel `Full Release Validation` avant l’approbation de la publication pour lancer toutes les boîtes de test de prépublication depuis un seul point d’entrée. Il accepte une branche, une étiquette ou un SHA de commit complet, déclenche manuellement `CI` et déclenche `OpenClaw Release Checks` pour la fumée d’installation, l’acceptation de package, les vérifications de package multiplateformes, la parité QA Lab, Matrix et les voies Telegram. Les exécutions stables/par défaut gardent les tests live/E2E exhaustifs et l’endurance du chemin de publication Docker derrière `run_release_soak=true` ; `release_profile=full` force l’activation de l’endurance. Avec `release_profile=full` et `rerun_group=all`, il exécute aussi l’E2E Telegram de package contre l’artefact `release-package-under-test` issu des vérifications de publication. Fournissez `npm_telegram_package_spec` après publication lorsque le même E2E Telegram doit aussi valider le package npm publié. Fournissez `package_acceptance_package_spec` après publication lorsque Package Acceptance doit exécuter sa matrice package/mise à jour contre le package npm livré au lieu de l’artefact construit depuis le SHA. Fournissez `evidence_package_spec` lorsque le rapport de preuve privé doit démontrer que la validation correspond à un package npm publié sans forcer l’E2E Telegram. Exemple : +- Exécutez `pnpm check:test-types` avant la vérification préliminaire de publication afin que le TypeScript des tests reste + couvert en dehors du garde-fou local plus rapide `pnpm check` +- Exécutez `pnpm check:architecture` avant la vérification préliminaire de publication afin que les vérifications plus larges des + cycles d’importation et des frontières d’architecture soient au vert en dehors du garde-fou local plus rapide +- Exécutez `pnpm build && pnpm ui:build` avant `pnpm release:check` afin que les artefacts de publication + `dist/*` attendus et le bundle de l’interface utilisateur de contrôle existent pour l’étape de validation + du paquet +- Exécutez `pnpm plugins:sync` après l’incrément de version racine et avant le taggage. Il + met à jour les versions des packages de plugins publiables, les métadonnées de compatibilité + pair/API OpenClaw, les métadonnées de build et les ébauches de changelog des plugins pour correspondre à la version de publication + du cœur. `pnpm plugins:sync:check` est le garde-fou de publication non mutant ; + le workflow de publication échoue avant toute mutation du registre si cette étape a été + oubliée. +- Exécutez le workflow manuel `Full Release Validation` avant l’approbation de la publication pour + lancer toutes les boîtes de test de prépublication depuis un seul point d’entrée. Il accepte une branche, + un tag ou un SHA de commit complet, déclenche manuellement `CI`, et déclenche + `OpenClaw Release Checks` pour le smoke test d’installation, l’acceptation de package, les vérifications de package + inter-OS, la parité QA Lab, Matrix et les voies Telegram. Les exécutions stables/par défaut + gardent les live/E2E exhaustifs et le soak du chemin de publication Docker derrière + `run_release_soak=true` ; `release_profile=full` force l’activation du soak. Avec + `release_profile=full` et `rerun_group=all`, il exécute aussi l’E2E Telegram du package + contre l’artefact `release-package-under-test` issu des vérifications de publication. + Fournissez `npm_telegram_package_spec` après publication lorsque le même + E2E Telegram doit aussi valider le package npm publié. Fournissez + `package_acceptance_package_spec` après publication lorsque Package Acceptance + doit exécuter sa matrice package/mise à jour contre le package npm livré au lieu + de l’artefact construit à partir du SHA. Fournissez + `evidence_package_spec` lorsque le rapport de preuve privé doit démontrer que la + validation correspond à un package npm publié sans forcer l’E2E Telegram. + Exemple : `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` -- Exécutez le workflow manuel `Package Acceptance` lorsque vous voulez une preuve par canal auxiliaire pour un candidat package pendant que le travail de publication continue. Utilisez `source=npm` pour `openclaw@beta`, `openclaw@latest` ou une version de publication exacte ; `source=ref` pour empaqueter une branche/étiquette/SHA `package_ref` de confiance avec le harnais `workflow_ref` actuel ; `source=url` pour une archive tar HTTPS avec un SHA-256 obligatoire ; ou `source=artifact` pour une archive tar téléversée par une autre exécution GitHub Actions. Le workflow résout le candidat vers `package-under-test`, réutilise le planificateur de publication Docker E2E contre cette archive tar et peut exécuter la QA Telegram contre la même archive tar avec `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Lorsque les voies Docker sélectionnées incluent `published-upgrade-survivor`, l’artefact de package est le candidat et `published_upgrade_survivor_baseline` sélectionne la base publiée. +- Exécutez le workflow manuel `Package Acceptance` lorsque vous voulez une preuve par canal auxiliaire + pour un candidat de package pendant que le travail de publication continue. Utilisez `source=npm` pour + `openclaw@beta`, `openclaw@latest` ou une version de publication exacte ; `source=ref` + pour empaqueter une branche/un tag/un SHA `package_ref` de confiance avec le harnais + `workflow_ref` actuel ; `source=url` pour une archive tarball HTTPS avec un + SHA-256 obligatoire ; ou `source=artifact` pour une archive tarball téléversée par une autre exécution + GitHub Actions. Le workflow résout le candidat vers + `package-under-test`, réutilise le planificateur de publication Docker E2E contre cette + archive tarball, et peut exécuter la QA Telegram contre la même archive avec + `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Lorsque les + voies Docker sélectionnées incluent `published-upgrade-survivor`, l’artefact de package + est le candidat et `published_upgrade_survivor_baseline` sélectionne + la référence publiée. `update-restart-auth` utilise le package candidat comme + CLI installé et comme package-under-test afin d’exercer le chemin de redémarrage géré + de la commande de mise à jour du candidat. Exemple : `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` Profils courants : - `smoke` : voies d’installation/canal/agent, réseau Gateway et rechargement de configuration - - `package` : voies natives d’artefact pour package/mise à jour/plugin sans OpenWebUI ni ClawHub live - - `product` : profil package plus canaux MCP, nettoyage cron/sous-agent, recherche web OpenAI et OpenWebUI - - `full` : segments du chemin de publication Docker avec OpenWebUI - - `custom` : sélection exacte de `docker_lanes` pour une réexécution ciblée -- Exécutez directement le workflow manuel `CI` lorsque vous avez seulement besoin d’une couverture CI normale complète pour le candidat de publication. Les déclenchements manuels de CI contournent le périmétrage des changements et forcent les shards Linux Node, les shards de plugins groupés, les contrats de canaux, la compatibilité Node 22, `check`, `check-additional`, la fumée de build, les vérifications de docs, les Skills Python, Windows, macOS, Android et les voies d’internationalisation de l’interface utilisateur de contrôle. + - `package` : voies package/mise à jour/redémarrage/plugin natives de l’artefact sans OpenWebUI ni ClawHub live + - `product` : profil package plus canaux MCP, nettoyage cron/sous-agent, + recherche web OpenAI et OpenWebUI + - `full` : fragments du chemin de publication Docker avec OpenWebUI + - `custom` : sélection exacte de `docker_lanes` pour une relance ciblée +- Exécutez directement le workflow manuel `CI` lorsque vous n’avez besoin que d’une couverture CI normale complète + pour le candidat de publication. Les déclenchements manuels de CI contournent la portée par changements + et forcent les shards Linux Node, les shards de plugins groupés, les contrats de canaux, + la compatibilité Node 22, `check`, `check-additional`, le smoke test de build, + les vérifications de docs, les Skills Python, Windows, macOS, Android et les voies i18n de l’interface utilisateur de contrôle. Exemple : `gh workflow run ci.yml --ref release/YYYY.M.D` -- Exécutez `pnpm qa:otel:smoke` lors de la validation de la télémétrie de publication. Il exerce QA-lab via un récepteur OTLP/HTTP local et vérifie les noms de spans de trace exportés, les attributs bornés et la rédaction du contenu/des identifiants sans nécessiter Opik, Langfuse ni un autre collecteur externe. -- Exécutez `pnpm release:check` avant chaque publication étiquetée -- Exécutez `OpenClaw Release Publish` pour la séquence de publication mutante après l’existence de l’étiquette. Déclenchez-le depuis `release/YYYY.M.D` (ou `main` lors de la publication d’une étiquette accessible depuis main), passez l’étiquette de publication et le `preflight_run_id` npm OpenClaw réussi, et conservez la portée de publication de plugins par défaut `all-publishable` sauf si vous exécutez délibérément une réparation ciblée. Le workflow sérialise la publication npm des plugins, la publication ClawHub des plugins et la publication npm OpenClaw afin que le package cœur ne soit pas publié avant ses plugins externalisés. -- Les vérifications de publication s’exécutent maintenant dans un workflow manuel séparé : +- Exécutez `pnpm qa:otel:smoke` lors de la validation de la télémétrie de publication. Cela exerce + QA-lab via un récepteur OTLP/HTTP local et vérifie les noms des spans de trace exportés, + les attributs bornés et la rédaction du contenu/des identifiants sans + nécessiter Opik, Langfuse ou un autre collecteur externe. +- Exécutez `pnpm release:check` avant chaque publication taggée +- Exécutez `OpenClaw Release Publish` pour la séquence de publication mutante après l’existence du + tag. Déclenchez-la depuis `release/YYYY.M.D` (ou `main` lors de la publication d’un + tag atteignable depuis main), transmettez le tag de publication et le `preflight_run_id` + npm OpenClaw réussi, et conservez la portée de publication des plugins par défaut + `all-publishable` sauf si vous exécutez délibérément une réparation ciblée. Le + workflow sérialise la publication npm des plugins, la publication ClawHub des plugins et la publication npm OpenClaw + afin que le package cœur ne soit pas publié avant ses plugins externalisés. +- Les vérifications de publication s’exécutent désormais dans un workflow manuel séparé : `OpenClaw Release Checks` -- `OpenClaw Release Checks` exécute aussi la voie de parité fictive QA Lab ainsi que le profil Matrix live rapide et la voie QA Telegram avant l’approbation de publication. Les voies live utilisent l’environnement `qa-live-shared` ; Telegram utilise aussi les baux d’identifiants Convex CI. Exécutez le workflow manuel `QA-Lab - All Lanes` avec `matrix_profile=all` et `matrix_shards=true` lorsque vous voulez l’inventaire complet des transports Matrix, des médias et de l’E2EE en parallèle. -- La validation d’exécution d’installation et de mise à niveau multiplateforme fait partie des workflows publics `OpenClaw Release Checks` et `Full Release Validation`, qui appellent directement le workflow réutilisable `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Cette séparation est intentionnelle : garder le véritable chemin de publication npm court, déterministe et centré sur les artefacts, tandis que les vérifications live plus lentes restent dans leur propre voie afin de ne pas retarder ni bloquer la publication -- Les vérifications de publication porteuses de secrets doivent être déclenchées via `Full Release -Validation` ou depuis la référence de workflow `main`/release afin que la logique du workflow et les secrets restent contrôlés -- `OpenClaw Release Checks` accepte une branche, une étiquette ou un SHA de commit complet tant que le commit résolu est accessible depuis une branche OpenClaw ou une étiquette de publication -- Le contrôle préliminaire de validation seule `OpenClaw NPM Release` accepte aussi le SHA de commit complet de 40 caractères de la branche de workflow actuelle sans exiger d’étiquette poussée -- Ce chemin SHA est réservé à la validation et ne peut pas être promu en véritable publication -- En mode SHA, le workflow synthétise `v` uniquement pour la vérification des métadonnées du package ; une véritable publication exige toujours une véritable étiquette de publication -- Les deux workflows gardent le véritable chemin de publication et de promotion sur les exécuteurs hébergés par GitHub, tandis que le chemin de validation non mutant peut utiliser les exécuteurs Linux Blacksmith plus grands +- `OpenClaw Release Checks` exécute aussi la voie de parité mock QA Lab plus le profil Matrix + live rapide et la voie QA Telegram avant l’approbation de publication. Les voies live + utilisent l’environnement `qa-live-shared` ; Telegram utilise aussi les baux d’identifiants + Convex CI. Exécutez le workflow manuel `QA-Lab - All Lanes` avec + `matrix_profile=all` et `matrix_shards=true` lorsque vous voulez l’inventaire complet Matrix + du transport, des médias et de l’E2EE en parallèle. +- La validation d’exécution d’installation et de mise à niveau inter-OS fait partie des workflows publics + `OpenClaw Release Checks` et `Full Release Validation`, qui appellent directement le + workflow réutilisable + `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` +- Cette séparation est intentionnelle : garder le véritable chemin de publication npm court, + déterministe et centré sur les artefacts, tandis que les vérifications live plus lentes restent dans leur + propre voie afin de ne pas retarder ni bloquer la publication +- Les vérifications de publication portant des secrets doivent être déclenchées via `Full Release +Validation` ou depuis la référence de workflow `main`/release afin que la logique de workflow et + les secrets restent contrôlés +- `OpenClaw Release Checks` accepte une branche, un tag ou un SHA de commit complet tant + que le commit résolu est atteignable depuis une branche OpenClaw ou un tag de publication +- La vérification préliminaire en mode validation seule de `OpenClaw NPM Release` accepte aussi le SHA de commit complet + de 40 caractères de la branche de workflow actuelle sans nécessiter de tag poussé +- Ce chemin SHA est uniquement destiné à la validation et ne peut pas être promu en véritable publication +- En mode SHA, le workflow synthétise `v` uniquement pour la + vérification des métadonnées de package ; la vraie publication nécessite toujours un vrai tag de publication +- Les deux workflows conservent le vrai chemin de publication et de promotion sur des runners + hébergés par GitHub, tandis que le chemin de validation non mutant peut utiliser les runners + Linux Blacksmith plus grands - Ce workflow exécute `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` en utilisant les secrets de workflow `OPENAI_API_KEY` et `ANTHROPIC_API_KEY` -- Le contrôle préliminaire de publication npm n’attend plus la voie séparée des vérifications de publication +- La vérification préliminaire de publication npm n’attend plus la voie de vérifications de publication séparée - Exécutez `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (ou l’étiquette bêta/correction correspondante) avant l’approbation + (ou le tag bêta/correctif correspondant) avant l’approbation - Après la publication npm, exécutez `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` - (ou la version bêta/correction correspondante) pour vérifier le chemin d’installation du registre publié dans un préfixe temporaire neuf + (ou la version bêta/correctif correspondante) pour vérifier le chemin d’installation du registre publié + dans un préfixe temporaire frais - Après une publication bêta, exécutez `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - pour vérifier l’intégration du package installé, la configuration Telegram et le véritable E2E Telegram contre le package npm publié en utilisant le pool partagé d’identifiants Telegram loués. Les exécutions ponctuelles locales des mainteneurs peuvent omettre les variables Convex et passer directement les trois identifiants d’environnement `OPENCLAW_QA_TELEGRAM_*`. -- Pour exécuter la fumée bêta complète après publication depuis une machine de mainteneur, utilisez `pnpm release:beta-smoke -- --beta betaN`. L’assistant exécute la validation Parallels de mise à jour npm/cible fraîche, déclenche `NPM Telegram Beta E2E`, interroge l’exécution exacte du workflow, télécharge l’artefact et affiche le rapport Telegram. -- Les mainteneurs peuvent exécuter la même vérification post-publication depuis GitHub Actions via le workflow manuel `NPM Telegram Beta E2E`. Il est volontairement uniquement manuel et ne s’exécute pas à chaque fusion. -- L’automatisation de publication des mainteneurs utilise maintenant le modèle contrôle préliminaire puis promotion : - - la véritable publication npm doit réussir un `preflight_run_id` npm réussi - - la véritable publication npm doit être déclenchée depuis la même branche `main` ou `release/YYYY.M.D` que l’exécution de contrôle préliminaire réussie - - les publications npm stables ciblent `beta` par défaut - - la publication npm stable peut cibler explicitement `latest` via l’entrée de workflow - - la mutation de dist-tag npm basée sur jeton vit maintenant dans `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` pour la sécurité, car `npm dist-tag add` a toujours besoin de `NPM_TOKEN` tandis que le dépôt public conserve une publication OIDC seule - - la publication publique `macOS Release` est uniquement de validation ; lorsqu’une étiquette n’existe que sur une branche de publication mais que le workflow est déclenché depuis `main`, définissez `public_release_branch=release/YYYY.M.D` - - la véritable publication mac privée doit réussir le `preflight_run_id` mac privé et `validate_run_id` - - les véritables chemins de publication promeuvent les artefacts préparés au lieu de les reconstruire à nouveau -- Pour les publications de correction stables comme `YYYY.M.D-N`, le vérificateur post-publication vérifie aussi le même chemin de mise à niveau à préfixe temporaire de `YYYY.M.D` vers `YYYY.M.D-N` afin que les corrections de publication ne puissent pas laisser silencieusement d’anciennes installations globales sur la charge utile stable de base -- Le contrôle préliminaire de publication npm échoue fermé sauf si l’archive tar inclut à la fois `dist/control-ui/index.html` et une charge utile non vide `dist/control-ui/assets/` afin de ne pas livrer à nouveau un tableau de bord de navigateur vide -- La vérification post-publication vérifie aussi que les points d’entrée des plugins publiés et les métadonnées de package sont présents dans l’agencement de registre installé. Une publication qui livre des charges utiles d’exécution de plugins manquantes échoue au vérificateur postpublication et ne peut pas être promue vers `latest`. -- `pnpm test:install:smoke` applique aussi le budget npm pack `unpackedSize` sur l’archive tar de mise à jour candidate, afin que l’e2e d’installation détecte le gonflement accidentel du paquet avant le chemin de publication -- Si le travail de publication a touché la planification CI, les manifestes de minutage des extensions ou les matrices de tests d’extensions, régénérez et révisez les sorties de matrice `plugin-prerelease-extension-shard` détenues par le planificateur depuis `.github/workflows/plugin-prerelease.yml` avant approbation afin que les notes de publication ne décrivent pas une disposition CI obsolète -- La préparation d’une publication stable macOS inclut aussi les surfaces du système de mise à jour : - - la publication GitHub doit finir avec les fichiers packagés `.zip`, `.dmg` et `.dSYM.zip` + pour vérifier l’onboarding du package installé, la configuration Telegram et le vrai E2E Telegram + contre le package npm publié en utilisant le pool partagé loué d’identifiants Telegram. + Les exécutions ponctuelles locales de mainteneurs peuvent omettre les variables Convex et transmettre directement les trois + identifiants d’environnement `OPENCLAW_QA_TELEGRAM_*`. +- Pour exécuter le smoke test bêta complet après publication depuis une machine de mainteneur, utilisez `pnpm release:beta-smoke -- --beta betaN`. L’assistant exécute la validation Parallels de mise à jour npm/cible fraîche, déclenche `NPM Telegram Beta E2E`, interroge l’exécution exacte du workflow, télécharge l’artefact et affiche le rapport Telegram. +- Les mainteneurs peuvent exécuter la même vérification après publication depuis GitHub Actions via le + workflow manuel `NPM Telegram Beta E2E`. Il est intentionnellement manuel uniquement et + ne s’exécute pas à chaque merge. +- L’automatisation de publication des mainteneurs utilise désormais préflight-puis-promotion : + - la vraie publication npm doit réussir un `preflight_run_id` npm + - la vraie publication npm doit être déclenchée depuis la même branche `main` ou + `release/YYYY.M.D` que l’exécution préliminaire réussie + - les publications npm stables ciblent par défaut `beta` + - la publication npm stable peut cibler explicitement `latest` via l’entrée du workflow + - la mutation de dist-tag npm basée sur jeton réside désormais dans + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` + pour des raisons de sécurité, car `npm dist-tag add` nécessite toujours `NPM_TOKEN` tandis que le + dépôt public conserve une publication OIDC uniquement + - le workflow public `macOS Release` est uniquement destiné à la validation ; lorsqu’un tag n’existe que sur une + branche de publication mais que le workflow est déclenché depuis `main`, définissez + `public_release_branch=release/YYYY.M.D` + - la vraie publication mac privée doit réussir les `preflight_run_id` et + `validate_run_id` mac privés + - les vrais chemins de publication promeuvent les artefacts préparés au lieu de les reconstruire + à nouveau +- Pour les publications correctives stables comme `YYYY.M.D-N`, le vérificateur après publication + vérifie aussi le même chemin de mise à niveau avec préfixe temporaire de `YYYY.M.D` vers `YYYY.M.D-N` + afin que les corrections de publication ne puissent pas laisser silencieusement les anciennes installations globales sur la + charge utile stable de base +- La vérification préliminaire de publication npm échoue de manière fermée sauf si l’archive tarball inclut à la fois + `dist/control-ui/index.html` et une charge utile non vide `dist/control-ui/assets/` + afin que nous ne livrions plus de tableau de bord navigateur vide +- La vérification après publication vérifie aussi que les points d’entrée des plugins publiés et + les métadonnées de package sont présents dans l’agencement de registre installé. Une publication qui + livre des charges utiles d’exécution de plugins manquantes échoue au vérificateur postpublish et + ne peut pas être promue vers `latest`. +- `pnpm test:install:smoke` impose aussi le budget npm pack `unpackedSize` sur + l’archive tarball de mise à jour candidate, afin que l’e2e de l’installateur détecte le gonflement accidentel du pack + avant le chemin de publication +- Si le travail de publication a touché la planification CI, les manifestes de timing des plugins ou + les matrices de tests de plugins, régénérez et révisez les sorties de matrice + `plugin-prerelease-extension-shard` détenues par le planificateur depuis + `.github/workflows/plugin-prerelease.yml` avant l’approbation afin que les notes de publication ne + décrivent pas une disposition CI obsolète +- La préparation d’une publication macOS stable inclut aussi les surfaces de mise à jour : + - la publication GitHub doit finir avec les packages `.zip`, `.dmg` et `.dSYM.zip` - `appcast.xml` sur `main` doit pointer vers le nouveau zip stable après publication - - l’application packagée doit conserver un identifiant de bundle non débogage, une URL de flux Sparkle non vide et un `CFBundleVersion` supérieur ou égal au plancher de build Sparkle canonique pour cette version de publication + - l’app packagée doit conserver un identifiant de bundle non debug, une URL de flux Sparkle + non vide et un `CFBundleVersion` égal ou supérieur au seuil de build Sparkle canonique + pour cette version de publication ## Boîtes de test de publication -`Full Release Validation` est la manière dont les opérateurs lancent tous les tests de prépublication depuis un seul point d’entrée. Pour une preuve sur commit épinglé sur une branche évoluant rapidement, utilisez l’assistant afin que chaque workflow enfant s’exécute depuis une branche temporaire fixée au SHA cible : +`Full Release Validation` est la manière dont les opérateurs lancent tous les tests de prépublication depuis +un seul point d’entrée. Pour une preuve de commit épinglé sur une branche qui évolue rapidement, utilisez +l’assistant afin que chaque workflow enfant s’exécute depuis une branche temporaire fixée au SHA cible : ```bash pnpm ci:full-release --sha ``` -L’assistant pousse `release-ci/-...`, déclenche `Full Release Validation` depuis cette branche avec `ref=`, vérifie que chaque `headSha` de workflow enfant correspond à la cible, puis supprime la branche temporaire. Cela évite de prouver accidentellement une exécution enfant plus récente de `main`. +L’assistant pousse `release-ci/-...`, déclenche `Full Release Validation` +depuis cette branche avec `ref=`, vérifie que chaque `headSha` de workflow enfant +correspond à la cible, puis supprime la branche temporaire. Cela évite de valider +par accident une exécution enfant plus récente de `main`. -Pour la validation d’une branche ou d’une étiquette de publication, exécutez-le depuis la référence de workflow `main` de confiance et passez la branche ou l’étiquette de publication comme `ref` : +Pour la validation d’une branche ou d’un tag de publication, exécutez-le depuis la référence de workflow `main` +de confiance et transmettez la branche ou le tag de publication comme `ref` : ```bash gh workflow run full-release-validation.yml \ @@ -189,53 +294,57 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -Le workflow résout la ref cible, déclenche manuellement `CI` avec -`target_ref=`, déclenche `OpenClaw Release Checks`, prépare un +Le workflow résout la réf cible, déclenche le `CI` manuel avec +`target_ref=`, déclenche les `OpenClaw Release Checks`, prépare un artefact parent `release-package-under-test` pour les vérifications orientées -package, et déclenche l’E2E Telegram package autonome lorsque `release_profile=full` avec -`rerun_group=all` ou lorsque `npm_telegram_package_spec` est défini. `OpenClaw Release -Checks` déploie ensuite les smokes d’installation, les vérifications de release inter-OS, la -couverture live/E2E du chemin de release Docker lorsque le soak est activé, Package Acceptance avec l’AQ du package Telegram, la parité QA Lab, Matrix live et Telegram live. Une exécution complète n’est acceptable que lorsque le +package, et déclenche le package Telegram E2E autonome quand `release_profile=full` avec +`rerun_group=all` ou quand `npm_telegram_package_spec` est défini. `OpenClaw Release +Checks` distribue ensuite la fumée d’installation, les vérifications de release +multi-OS, la couverture live/E2E Docker du chemin de release quand le soak est activé, Package Acceptance avec la QA du package Telegram, la parité QA Lab, Matrix live et Telegram live. Une exécution complète n’est acceptable que lorsque le résumé `Full Release Validation` -indique que `normal_ci` et `release_checks` ont réussi. En mode full/all, -l’enfant `npm_telegram` doit aussi réussir ; hors full/all, il est ignoré +affiche `normal_ci` et `release_checks` comme réussis. En mode full/all, +l’enfant `npm_telegram` doit aussi réussir ; en dehors de full/all, il est ignoré sauf si un `npm_telegram_package_spec` publié a été fourni. Le résumé final du vérificateur inclut des tableaux des jobs les plus lents pour chaque exécution enfant, afin que le responsable de release puisse voir le chemin critique actuel sans télécharger les journaux. -Consultez [Validation complète de release](/fr/reference/full-release-validation) pour la -matrice complète des étapes, les noms exacts des jobs de workflow, les différences entre profils stable et full, -les artefacts et les identifiants de relance ciblée. -Les workflows enfants sont déclenchés depuis la ref de confiance qui exécute `Full Release -Validation`, normalement `--ref main`, même lorsque la `ref` cible pointe vers une -branche ou une balise de release plus ancienne. Il n’existe pas d’entrée workflow-ref séparée pour Full Release Validation ; choisissez le harnais de confiance en choisissant la ref d’exécution du workflow. -N’utilisez pas `--ref main -f ref=` pour une preuve de commit exacte sur `main` mouvant ; +Voir [Validation complète de release](/fr/reference/full-release-validation) pour la +matrice complète des étapes, les noms exacts des jobs de workflow, les +différences entre profils stable et full, les artefacts et les poignées de relance ciblées. +Les workflows enfants sont déclenchés depuis la réf de confiance qui exécute `Full Release +Validation`, normalement `--ref main`, même quand la `ref` cible pointe vers une +branche ou une balise de release plus ancienne. Il n’existe pas d’entrée workflow-ref +distincte pour Full Release Validation ; choisissez le harnais de confiance en choisissant la réf d’exécution du workflow. +N’utilisez pas `--ref main -f ref=` pour une preuve de commit exact sur `main` mouvant ; les SHA de commit bruts ne peuvent pas être des refs de déclenchement de workflow, utilisez donc `pnpm ci:full-release --sha ` pour créer la branche temporaire épinglée. -Utilisez `release_profile` pour sélectionner l’étendue live/fournisseur : +Utilisez `release_profile` pour sélectionner l’étendue live/provider : -- `minimum` : chemin OpenAI/core live et Docker critique pour la release, le plus rapide -- `stable` : minimum plus couverture fournisseur/backend stable pour l’approbation de release -- `full` : stable plus large couverture consultative fournisseur/média +- `minimum` : chemin OpenAI/core live et Docker critique pour la release le plus rapide +- `stable` : minimum plus couverture provider/backend stable pour l’approbation de release +- `full` : stable plus large couverture consultative provider/médias -Utilisez `run_release_soak=true` avec `stable` lorsque les lanes bloquantes pour la release sont +Utilisez `run_release_soak=true` avec `stable` quand les lanes bloquantes pour la release sont vertes et que vous voulez le balayage exhaustif live/E2E, du chemin de release Docker et -des survivants de mise à niveau all-since-2026.4.23 avant promotion. `full` implique +borné de survie aux mises à niveau publiées avant la promotion. Ce balayage couvre +les quatre derniers packages stables plus les baselines épinglées `2026.4.23` et `2026.5.2` +plus une couverture plus ancienne `2026.4.15`, avec suppression des baselines dupliquées et +chaque baseline fragmentée dans son propre job de runner Docker. `full` implique `run_release_soak=true`. -`OpenClaw Release Checks` utilise la ref de workflow de confiance pour résoudre une seule fois la ref cible -comme `release-package-under-test` et réutilise cet artefact dans les vérifications inter-OS, -Package Acceptance et Docker du chemin de release lorsque le soak s’exécute. Cela garde +`OpenClaw Release Checks` utilise la réf de workflow de confiance pour résoudre une fois la réf +cible sous forme de `release-package-under-test` et réutilise cet artefact dans les vérifications multi-OS, +Package Acceptance et Docker de chemin de release quand le soak s’exécute. Cela garde toutes les machines orientées package sur les mêmes octets et évite les builds de package répétés. -Le smoke d’installation OpenAI inter-OS utilise `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsque la -variable repo/org est définie, sinon `openai/gpt-5.4`, car cette lane +La fumée d’installation OpenAI multi-OS utilise `OPENCLAW_CROSS_OS_OPENAI_MODEL` quand la +variable repo/org est définie, sinon `openai/gpt-5.4`, parce que cette lane prouve l’installation du package, l’onboarding, le démarrage du Gateway et un tour d’agent live -plutôt que de benchmarker le modèle par défaut le plus lent. La matrice live plus large des fournisseurs -reste l’endroit pour la couverture propre à chaque modèle. +plutôt que de mesurer le modèle par défaut le plus lent. La matrice live provider +plus large reste l’endroit prévu pour la couverture propre aux modèles. Utilisez ces variantes selon l’étape de release : ```bash -# Valider une branche candidate de release non publiée. +# Validate an unpublished release candidate branch. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ @@ -243,14 +352,14 @@ gh workflow run full-release-validation.yml \ -f mode=both \ -f release_profile=stable -# Valider un commit poussé exact. +# Validate an exact pushed commit. gh workflow run full-release-validation.yml \ --ref main \ -f ref=<40-char-sha> \ -f provider=openai \ -f mode=both -# Après la publication d’une bêta, ajouter l’E2E Telegram du package publié. +# After publishing a beta, add published-package Telegram E2E. gh workflow run full-release-validation.yml \ --ref main \ -f ref=release/YYYY.M.D \ @@ -262,42 +371,43 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -N’utilisez pas le parapluie complet comme première relance après un correctif ciblé. Si une machine -échoue, utilisez le workflow enfant échoué, le job, la lane Docker, le profil de package, le fournisseur -de modèle ou la lane QA pour la preuve suivante. Relancez le parapluie complet uniquement lorsque -le correctif a modifié l’orchestration de release partagée ou a rendu obsolètes les preuves antérieures de toutes les machines. -Le vérificateur final du parapluie revérifie les identifiants d’exécution de workflow enfant enregistrés ; -ainsi, après la relance réussie d’un workflow enfant, relancez uniquement le job parent échoué -`Verify full validation`. +N’utilisez pas le parapluie complet comme première relance après une correction ciblée. Si une machine +échoue, utilisez le workflow enfant, le job, la lane Docker, le profil de package, le provider +de modèle ou la lane QA en échec pour la preuve suivante. Relancez le parapluie complet seulement quand +la correction a modifié l’orchestration de release partagée ou a rendu obsolète la preuve +précédente de toutes les machines. Le vérificateur final du parapluie revérifie les identifiants +enregistrés des exécutions de workflow enfants ; ainsi, après la relance réussie d’un workflow enfant, +relancez uniquement le job parent `Verify full validation` en échec. -Pour une récupération bornée, passez `rerun_group` au parapluie. `all` est la véritable -exécution candidate de release, `ci` exécute seulement l’enfant CI normal, `plugin-prerelease` -exécute seulement l’enfant Plugin propre à la release, `release-checks` exécute chaque machine de release, -et les groupes de release plus étroits sont `install-smoke`, `cross-os`, +Pour une récupération bornée, passez `rerun_group` au parapluie. `all` est la vraie +exécution de release candidate, `ci` exécute seulement l’enfant CI normal, `plugin-prerelease` +exécute seulement l’enfant Plugin propre à la release, `release-checks` exécute chaque machine +de release, et les groupes de release plus étroits sont `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` et `npm-telegram`. Les relances ciblées `npm-telegram` nécessitent `npm_telegram_package_spec` ; les exécutions full/all -avec `release_profile=full` utilisent l’artefact de package release-checks. Les relances -inter-OS ciblées peuvent ajouter `cross_os_suite_filter=windows/packaged-upgrade` ou -un autre filtre OS/suite. Les échecs QA de release-checks sont consultatifs ; un échec uniquement QA -ne bloque pas la validation de release. +avec `release_profile=full` utilisent l’artefact de package des release-checks. Les relances +multi-OS ciblées peuvent ajouter `cross_os_suite_filter=windows/packaged-upgrade` ou +un autre filtre OS/suite. Les échecs QA des release-checks sont consultatifs ; un échec uniquement +QA ne bloque pas la validation de release. ### Vitest -La machine Vitest est le workflow enfant manuel `CI`. La CI manuelle contourne -intentionnellement le scoping des changements et force le graphe de tests normal pour le candidat de release : -shards Linux Node, shards de plugins groupés, contrats de canaux, compatibilité Node 22, -`check`, `check-additional`, smoke de build, vérifications docs, Skills Python, Windows, macOS, Android et i18n Control UI. +La machine Vitest est le workflow enfant `CI` manuel. Le CI manuel contourne +intentionnellement le périmètre des changements et force le graphe de tests normal pour la release +candidate : fragments Linux Node, fragments de plugins groupés, contrats de canaux, compatibilité Node 22, +`check`, `check-additional`, fumée de build, vérifications docs, Skills Python, Windows, macOS, Android et i18n Control UI. -Utilisez cette machine pour répondre à « l’arborescence source a-t-elle réussi la suite de tests normale complète ? » +Utilisez cette machine pour répondre à « l’arborescence source a-t-elle passé la suite de tests normale complète ? » Ce n’est pas la même chose que la validation produit du chemin de release. Preuves à conserver : -- résumé `Full Release Validation` indiquant l’URL de l’exécution `CI` déclenchée +- résumé `Full Release Validation` affichant l’URL de l’exécution `CI` déclenchée - exécution `CI` verte sur le SHA cible exact -- noms des shards échoués ou lents depuis les jobs CI lors de l’investigation de régressions -- artefacts de chronométrage Vitest tels que `.artifacts/vitest-shard-timings.json` lorsqu’une exécution nécessite une analyse des performances +- noms des fragments en échec ou lents depuis les jobs CI lors de l’investigation de régressions +- artefacts de temps Vitest comme `.artifacts/vitest-shard-timings.json` quand + une exécution nécessite une analyse de performance -Exécutez la CI manuelle directement uniquement lorsque la release nécessite une CI normale déterministe mais -pas les machines Docker, QA Lab, live, inter-OS ou package : +Exécutez le CI manuel directement uniquement quand la release nécessite un CI normal déterministe mais +pas les machines Docker, QA Lab, live, multi-OS ou package : ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -307,14 +417,14 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D La machine Docker vit dans `OpenClaw Release Checks` via `openclaw-live-and-e2e-checks-reusable.yml`, plus le workflow `install-smoke` -en mode release. Elle valide le candidat de release via des environnements Docker -packagés au lieu de se limiter aux tests au niveau source. +en mode release. Elle valide la release candidate via des environnements Docker +packagés plutôt que seulement des tests au niveau source. La couverture Docker de release inclut : -- smoke d’installation complet avec le smoke d’installation globale Bun lent activé -- préparation/réutilisation de l’image de smoke du Dockerfile racine par SHA cible, avec les jobs smoke QR, - root/gateway et installer/Bun exécutés comme shards install-smoke séparés +- fumée d’installation complète avec la fumée d’installation globale Bun lente activée +- préparation/réutilisation de l’image de fumée Dockerfile racine par SHA cible, avec les jobs de fumée QR, + root/gateway et installer/Bun s’exécutant comme fragments install-smoke séparés - lanes E2E du dépôt - morceaux Docker du chemin de release : `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, @@ -323,87 +433,92 @@ La couverture Docker de release inclut : `plugins-runtime-install-c`, `plugins-runtime-install-d`, `plugins-runtime-install-e`, `plugins-runtime-install-f`, `plugins-runtime-install-g` et `plugins-runtime-install-h` -- couverture OpenWebUI dans le morceau `plugins-runtime-services` lorsque demandée -- lanes divisées d’installation/désinstallation de plugins groupés +- couverture OpenWebUI dans le morceau `plugins-runtime-services` quand elle est demandée +- lanes d’installation/désinstallation de plugins groupés séparées `bundled-plugin-install-uninstall-0` à `bundled-plugin-install-uninstall-23` -- suites fournisseur live/E2E et couverture de modèle Docker live lorsque les vérifications de release +- suites provider live/E2E et couverture de modèles live Docker quand les vérifications de release incluent des suites live Utilisez les artefacts Docker avant de relancer. Le planificateur du chemin de release téléverse `.artifacts/docker-tests/` avec les journaux de lane, `summary.json`, `failures.json`, -les timings de phases, le JSON du plan du planificateur et les commandes de relance. Pour une récupération ciblée, -utilisez `docker_lanes=` sur le workflow réutilisable live/E2E au lieu de -relancer tous les morceaux de release. Les commandes de relance générées incluent les entrées -`package_artifact_run_id` précédentes et les images Docker préparées lorsqu’elles sont disponibles, afin qu’une -lane échouée puisse réutiliser la même archive tar et les mêmes images GHCR. +les durées de phase, le JSON du plan du planificateur et les commandes de relance. Pour une récupération ciblée, +utilisez `docker_lanes=` sur le workflow live/E2E réutilisable plutôt que +de relancer tous les morceaux de release. Les commandes de relance générées incluent le +`package_artifact_run_id` précédent et les entrées d’image Docker préparée quand elles sont disponibles, afin qu’une +lane en échec puisse réutiliser le même tarball et les mêmes images GHCR. ### QA Lab -La machine QA Lab fait aussi partie de `OpenClaw Release Checks`. C’est le gate de release -du comportement agentique et au niveau des canaux, séparé de Vitest et de la mécanique des packages Docker. +La machine QA Lab fait aussi partie de `OpenClaw Release Checks`. C’est la porte de release +du comportement agentique et au niveau des canaux, séparée de Vitest et de la mécanique +des packages Docker. La couverture QA Lab de release inclut : -- lane de parité mock comparant la lane candidate OpenAI à la référence Opus 4.6 - à l’aide du pack de parité agentique +- lane de parité simulée comparant la lane candidate OpenAI à la baseline Opus 4.6 + avec le pack de parité agentique - profil QA Matrix live rapide utilisant l’environnement `qa-live-shared` - lane QA Telegram live utilisant les baux d’identifiants Convex CI -- `pnpm qa:otel:smoke` lorsque la télémétrie de release nécessite une preuve locale explicite +- `pnpm qa:otel:smoke` quand la télémétrie de release nécessite une preuve locale explicite Utilisez cette machine pour répondre à « la release se comporte-t-elle correctement dans les scénarios QA et -les flux de canaux live ? » Conservez les URL d’artefacts pour les lanes parité, Matrix et Telegram -lors de l’approbation de la release. La couverture Matrix complète reste disponible sous forme d’exécution QA-Lab -fragmentée manuelle plutôt que comme lane critique de release par défaut. +les flux de canaux live ? » Conservez les URL d’artefacts pour les lanes de parité, Matrix et Telegram +lors de l’approbation de la release. La couverture Matrix complète reste disponible sous forme +d’exécution QA-Lab fragmentée manuelle plutôt que comme lane critique par défaut pour la release. ### Package -La machine Package est le gate de produit installable. Elle est appuyée par +La machine Package est la porte du produit installable. Elle s’appuie sur `Package Acceptance` et le résolveur `scripts/resolve-openclaw-package-candidate.mjs`. Le résolveur normalise un -candidat en archive tar `package-under-test` consommée par Docker E2E, valide +candidat dans le tarball `package-under-test` consommé par Docker E2E, valide l’inventaire du package, enregistre la version du package et le SHA-256, et garde la -ref du harnais de workflow séparée de la ref source du package. +réf du harnais de workflow séparée de la réf source du package. -Sources de candidats prises en charge : +Sources de candidat prises en charge : -- `source=npm` : `openclaw@beta`, `openclaw@latest` ou une version exacte de release OpenClaw -- `source=ref` : empaqueter une branche, balise ou SHA de commit complet `package_ref` de confiance +- `source=npm` : `openclaw@beta`, `openclaw@latest` ou une version de release OpenClaw exacte +- `source=ref` : packager une branche, une balise ou un SHA de commit complet `package_ref` de confiance avec le harnais `workflow_ref` sélectionné -- `source=url` : télécharger un `.tgz` HTTPS avec `package_sha256` obligatoire +- `source=url` : télécharger un `.tgz` HTTPS avec `package_sha256` requis - `source=artifact` : réutiliser un `.tgz` téléversé par une autre exécution GitHub Actions -`OpenClaw Release Checks` exécute Package Acceptance avec `source=artifact`, l’artefact de package release préparé, `suite_profile=custom`, -`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`, -`telegram_mode=mock-openai`. Package Acceptance garde la migration, la mise à jour, le nettoyage des dépendances de plugins obsolètes, les fixtures de plugins hors ligne, la mise à jour de plugins et l’AQ du package Telegram sur la même archive tar résolue. Les vérifications de release bloquantes utilisent la référence de package publié latest par défaut ; `run_release_soak=true` ou -`release_profile=full` étend à chaque référence stable publiée sur npm depuis -`2026.4.23` jusqu’à `latest`, plus les fixtures d’issues signalées. Utilisez +`OpenClaw Release Checks` exécute Package Acceptance avec `source=artifact`, l’artefact +de package de release préparé, `suite_profile=custom`, +`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor update-restart-auth plugins-offline plugin-update`, +`telegram_mode=mock-openai`. Package Acceptance conserve la migration, la mise à jour, +le redémarrage de mise à jour avec auth configurée, le nettoyage des dépendances de Plugin obsolètes, les fixtures de Plugin hors ligne, la mise à jour de Plugin et la QA du package Telegram contre le même tarball +résolu. Les vérifications de release bloquantes utilisent la baseline du dernier package publié par défaut ; +`run_release_soak=true` ou +`release_profile=full` s’étend à chaque baseline stable publiée sur npm depuis +`2026.4.23` jusqu’à `latest` plus les fixtures d’incidents signalés. Utilisez Package Acceptance avec `source=npm` pour un candidat déjà livré, ou -`source=ref`/`source=artifact` pour une archive tar npm locale adossée à un SHA avant -publication. C’est le remplacement natif GitHub -pour la majeure partie de la couverture package/mise à jour qui nécessitait auparavant -Parallels. Les vérifications de release inter-OS restent importantes pour l’onboarding, -l’installateur et le comportement propres aux OS, mais la validation produit package/mise à jour devrait +`source=ref`/`source=artifact` pour un tarball npm local adossé à un SHA avant +publication. C’est le remplacement natif GitHub de la majeure partie de la +couverture package/mise à jour qui nécessitait auparavant Parallels. Les vérifications de release multi-OS restent importantes pour l’onboarding, +l’installateur et le comportement propres aux OS, mais la validation produit package/mise à jour doit privilégier Package Acceptance. La checklist canonique pour la validation des mises à jour et des plugins est -[Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins). Utilisez-la pour -décider quelle lane locale, Docker, Package Acceptance ou release-check prouve un -changement d’installation/mise à jour de plugin, de nettoyage doctor ou de migration de package publié. +[Test des mises à jour et des plugins](/fr/help/testing-updates-plugins). Utilisez-la pour +décider quelle lane locale, Docker, Package Acceptance ou release-check prouve une +installation/mise à jour de Plugin, un nettoyage doctor ou un changement de migration de package publié. La migration exhaustive des mises à jour publiées depuis chaque package stable `2026.4.23+` est -un workflow manuel `Update Migration` séparé, qui ne fait pas partie de Full Release CI. +un workflow manuel `Update Migration` distinct, et non une partie de Full Release CI. -La tolérance historique de package-acceptance est volontairement limitée dans le temps. Les packages jusqu’à +La tolérance historique de l’acceptation de packages est volontairement limitée dans le temps. Les packages jusqu’à `2026.4.25` peuvent utiliser le chemin de compatibilité pour les lacunes de métadonnées déjà publiées -sur npm : entrées d’inventaire QA privées absentes de l’archive tar, absence de -`gateway install --wrapper`, fichiers de patch absents de la fixture git dérivée de l’archive tar, -absence de `update.channel` persisté, emplacements historiques des enregistrements d’installation de plugins, -absence de persistance des enregistrements d’installation de marketplace et migration des métadonnées de configuration -pendant `plugins update`. Le package publié `2026.4.26` peut avertir -pour les fichiers d’empreinte de métadonnées de build local déjà livrés. Les packages ultérieurs -doivent satisfaire les contrats de package modernes ; ces mêmes lacunes font échouer la validation de release. +sur npm : entrées d’inventaire QA privées absentes du tarball, absence de +`gateway install --wrapper`, fichiers de correctif absents du fixture git dérivé du tarball, absence de +`update.channel` persisté, emplacements historiques des enregistrements d’installation de Plugin, +absence de persistance des enregistrements d’installation de marketplace, et migration des métadonnées de +configuration pendant `plugins update`. Le package publié `2026.4.26` peut émettre un avertissement +pour les fichiers d’horodatage de métadonnées de build local qui avaient déjà été livrés. Les packages ultérieurs +doivent satisfaire les contrats de package modernes ; ces mêmes lacunes font échouer la validation de +publication. -Utilisez des profils Package Acceptance plus larges lorsque la question de release concerne un +Utilisez des profils Package Acceptance plus larges lorsque la question de publication concerne un package réellement installable : ```bash @@ -418,26 +533,26 @@ gh workflow run package-acceptance.yml \ Profils de package courants : -- `smoke` : voies rapides d'installation de package/canal/agent, réseau Gateway et - rechargement de configuration -- `package` : contrats d'installation/mise à jour/package de Plugin sans ClawHub en direct ; c'est la valeur par défaut - du contrôle de release +- `smoke` : voies rapides d’installation de package/canal/agent, réseau Gateway et rechargement de + configuration +- `package` : contrats d’installation/mise à jour/redémarrage/package de Plugin sans + ClawHub en direct ; c’est la valeur par défaut de la vérification de publication - `product` : `package` plus canaux MCP, nettoyage cron/sous-agent, recherche web OpenAI et OpenWebUI -- `full` : segments de chemin de release Docker avec OpenWebUI -- `custom` : liste exacte `docker_lanes` pour des relances ciblées +- `full` : segments du chemin de publication Docker avec OpenWebUI +- `custom` : liste exacte de `docker_lanes` pour des relances ciblées Pour une preuve Telegram de package candidat, activez `telegram_mode=mock-openai` ou -`telegram_mode=live-frontier` sur Package Acceptance. Le workflow transmet l'archive tar -`package-under-test` résolue à la voie Telegram ; le workflow Telegram autonome -accepte toujours une spécification npm publiée pour les contrôles après publication. +`telegram_mode=live-frontier` sur Package Acceptance. Le workflow transmet le tarball +`package-under-test` résolu dans la voie Telegram ; le workflow Telegram autonome +accepte toujours une spécification npm publiée pour les vérifications post-publication. ## Automatisation de publication de release -`OpenClaw Release Publish` est le point d'entrée de publication modifiant normal. Il -orchestre les workflows d'éditeur de confiance dans l'ordre requis par la release : +`OpenClaw Release Publish` est le point d’entrée normal de publication mutante. Il +orchestre les workflows d’éditeur de confiance dans l’ordre requis par la release : -1. Extraire le tag de release et résoudre son SHA de commit. +1. Extraire le tag de release et résoudre son commit SHA. 2. Vérifier que le tag est accessible depuis `main` ou `release/*`. 3. Exécuter `pnpm plugins:sync:check`. 4. Déclencher `Plugin NPM Release` avec `publish_scope=all-publishable` et @@ -477,29 +592,28 @@ gh workflow run openclaw-release-publish.yml \ ``` Utilisez les workflows de niveau inférieur `Plugin NPM Release` et `Plugin ClawHub Release` -uniquement pour des travaux de réparation ou de republication ciblés. Pour une réparation de Plugin sélectionné, transmettez +uniquement pour des travaux ciblés de réparation ou de republication. Pour une réparation de Plugin sélectionné, transmettez `plugin_publish_scope=selected` et `plugins=@openclaw/name` à `OpenClaw Release Publish`, ou déclenchez directement le workflow enfant lorsque le package OpenClaw ne doit pas être publié. ## Entrées du workflow NPM -`OpenClaw NPM Release` accepte ces entrées contrôlées par l'opérateur : +`OpenClaw NPM Release` accepte ces entrées contrôlées par l’opérateur : -- `tag` : tag de release requis tel que `v2026.4.2`, `v2026.4.2-1` ou - `v2026.4.2-beta.1` ; lorsque `preflight_only=true`, il peut aussi être le SHA de commit - complet de 40 caractères de la branche de workflow actuelle pour une pré-vérification - de validation uniquement -- `preflight_only` : `true` pour validation/build/package seulement, `false` pour le - vrai chemin de publication -- `preflight_run_id` : requis sur le vrai chemin de publication afin que le workflow réutilise - l'archive tar préparée par l'exécution de pré-vérification réussie +- `tag` : tag de release requis, comme `v2026.4.2`, `v2026.4.2-1` ou + `v2026.4.2-beta.1` ; lorsque `preflight_only=true`, il peut aussi s’agir du SHA de commit + complet de 40 caractères de la branche de workflow actuelle pour une prévalidation uniquement +- `preflight_only` : `true` pour validation/build/package uniquement, `false` pour le + véritable chemin de publication +- `preflight_run_id` : requis sur le véritable chemin de publication afin que le workflow réutilise + le tarball préparé depuis l’exécution de prévalidation réussie - `npm_dist_tag` : tag npm cible pour le chemin de publication ; vaut `beta` par défaut -`OpenClaw Release Publish` accepte ces entrées contrôlées par l'opérateur : +`OpenClaw Release Publish` accepte ces entrées contrôlées par l’opérateur : - `tag` : tag de release requis ; il doit déjà exister -- `preflight_run_id` : identifiant d'exécution de pré-vérification `OpenClaw NPM Release` réussie ; +- `preflight_run_id` : id d’exécution de prévalidation `OpenClaw NPM Release` réussie ; requis lorsque `publish_openclaw_npm=true` - `npm_dist_tag` : tag npm cible pour le package OpenClaw - `plugin_publish_scope` : vaut `all-publishable` par défaut ; utilisez `selected` uniquement @@ -507,42 +621,42 @@ package OpenClaw ne doit pas être publié. - `plugins` : noms de packages `@openclaw/*` séparés par des virgules lorsque `plugin_publish_scope=selected` - `publish_openclaw_npm` : vaut `true` par défaut ; définissez `false` uniquement lorsque vous utilisez le - workflow comme orchestrateur de réparation limitée aux Plugins + workflow comme orchestrateur de réparation limité aux Plugins -`OpenClaw Release Checks` accepte ces entrées contrôlées par l'opérateur : +`OpenClaw Release Checks` accepte ces entrées contrôlées par l’opérateur : -- `ref` : branche, tag ou SHA de commit complet à valider. Les contrôles avec secrets - exigent que le commit résolu soit accessible depuis une branche OpenClaw ou - un tag de release. -- `run_release_soak` : active le soak exhaustif en direct/E2E, chemin de release Docker et - survivor de mise à niveau all-since sur les contrôles de release stables/par défaut. Il est forcé +- `ref` : branche, tag ou SHA de commit complet à valider. Les vérifications portant des secrets + exigent que le commit résolu soit accessible depuis une branche OpenClaw ou un + tag de release. +- `run_release_soak` : activer le test d’endurance exhaustif en direct/E2E, chemin de publication Docker et + survivant de mise à niveau depuis toutes les versions sur les vérifications de release stable/par défaut. Il est forcé par `release_profile=full`. Règles : - Les tags stables et de correction peuvent publier vers `beta` ou `latest` -- Les tags de prérelease bêta peuvent publier uniquement vers `beta` -- Pour `OpenClaw NPM Release`, l'entrée SHA de commit complet n'est autorisée que lorsque +- Les tags de préversion bêta ne peuvent publier que vers `beta` +- Pour `OpenClaw NPM Release`, l’entrée SHA de commit complet est autorisée uniquement lorsque `preflight_only=true` - `OpenClaw Release Checks` et `Full Release Validation` sont toujours - en validation uniquement -- Le vrai chemin de publication doit utiliser le même `npm_dist_tag` que celui utilisé pendant la pré-vérification ; + uniquement de validation +- Le véritable chemin de publication doit utiliser le même `npm_dist_tag` que celui utilisé pendant la prévalidation ; le workflow vérifie ces métadonnées avant de poursuivre la publication ## Séquence de release npm stable -Lors de la création d'une release npm stable : +Lors de la préparation d’une release npm stable : 1. Exécutez `OpenClaw NPM Release` avec `preflight_only=true` - - Avant qu'un tag existe, vous pouvez utiliser le SHA de commit complet de la branche de workflow actuelle - pour une répétition de validation uniquement du workflow de pré-vérification -2. Choisissez `npm_dist_tag=beta` pour le flux normal bêta d'abord, ou `latest` uniquement + - Avant qu’un tag existe, vous pouvez utiliser le SHA de commit complet de la branche de workflow actuelle + pour une simulation à blanc de validation uniquement du workflow de prévalidation +2. Choisissez `npm_dist_tag=beta` pour le flux normal bêta d’abord, ou `latest` uniquement lorsque vous voulez intentionnellement une publication stable directe -3. Exécutez `Full Release Validation` sur la branche de release, le tag de release ou le SHA de commit complet - lorsque vous voulez la CI normale plus la couverture du cache de prompts en direct, Docker, QA Lab, +3. Exécutez `Full Release Validation` sur la branche de release, le tag de release ou le SHA de + commit complet lorsque vous voulez une CI normale plus une couverture cache de prompts en direct, Docker, QA Lab, Matrix et Telegram depuis un seul workflow manuel -4. Si vous n'avez intentionnellement besoin que du graphe de tests normal déterministe, exécutez plutôt le - workflow manuel `CI` sur la ref de release +4. Si vous n’avez intentionnellement besoin que du graphe de tests normal déterministe, exécutez le + workflow manuel `CI` sur la ref de release à la place 5. Enregistrez le `preflight_run_id` réussi 6. Exécutez `OpenClaw Release Publish` avec le même `tag`, le même `npm_dist_tag`, et le `preflight_run_id` enregistré ; il publie les Plugins externalisés vers npm @@ -551,20 +665,20 @@ Lors de la création d'une release npm stable : `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` pour promouvoir cette version stable de `beta` vers `latest` 8. Si la release a été intentionnellement publiée directement vers `latest` et que `beta` - doit suivre immédiatement le même build stable, utilisez ce même workflow privé - pour faire pointer les deux dist-tags vers la version stable, ou laissez sa synchronisation - d'auto-réparation planifiée déplacer `beta` plus tard + doit suivre immédiatement le même build stable, utilisez le même workflow privé + pour faire pointer les deux dist-tags vers la version stable, ou laissez sa synchronisation planifiée + d’auto-réparation déplacer `beta` plus tard -La mutation de dist-tag se trouve dans le dépôt privé pour des raisons de sécurité, car elle -requiert toujours `NPM_TOKEN`, tandis que le dépôt public conserve une publication uniquement OIDC. +La mutation du dist-tag réside dans le dépôt privé pour des raisons de sécurité, car elle nécessite encore +`NPM_TOKEN`, tandis que le dépôt public conserve une publication uniquement OIDC. -Cela garde à la fois le chemin de publication directe et le chemin de promotion bêta d'abord -documentés et visibles par l'opérateur. +Cela garde le chemin de publication directe et le chemin de promotion bêta d’abord à la fois +documentés et visibles pour l’opérateur. -Si un mainteneur doit revenir à l'authentification npm locale, exécutez toutes les commandes -CLI 1Password (`op`) uniquement dans une session tmux dédiée. N'appelez pas `op` -directement depuis le shell principal de l'agent ; le garder dans tmux rend les invites, -alertes et la gestion OTP observables et évite les alertes hôte répétées. +Si un mainteneur doit se rabattre sur l’authentification npm locale, exécutez toutes les commandes de la CLI +1Password (`op`) uniquement dans une session tmux dédiée. N’appelez pas `op` +directement depuis le shell principal de l’agent ; le garder dans tmux rend les prompts, +alertes et traitements OTP observables et empêche les alertes hôte répétées. ## Références publiques @@ -578,10 +692,10 @@ alertes et la gestion OTP observables et évite les alertes hôte répétées. - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Les mainteneurs utilisent la documentation de release privée dans +Les mainteneurs utilisent la documentation privée de release dans [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) pour le runbook réel. -## Connexe +## Associé -- [Canaux de release](/fr/install/development-channels) +- [Canaux de publication](/fr/install/development-channels) diff --git a/docs/fr/reference/test.md b/docs/fr/reference/test.md index e3cfc1950..21ce5ff40 100644 --- a/docs/fr/reference/test.md +++ b/docs/fr/reference/test.md @@ -4,60 +4,60 @@ read_when: summary: Comment exécuter les tests localement (vitest) et quand utiliser les modes force/couverture title: Tests x-i18n: - generated_at: "2026-05-05T01:49:26Z" + generated_at: "2026-05-05T06:18:37Z" model: gpt-5.5 provider: openai - source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605 + source_hash: cc31ab27a63607ec5134306a0129bd164e4235f26631da4f691f657adda70eed source_path: reference/test.md workflow: 16 --- -- Kit de test complet (suites, tests en direct, Docker) : [Tests](/fr/help/testing) -- Validation des mises à jour et des packages Plugin : [Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins) +- Kit de test complet (suites, live, Docker) : [Tests](/fr/help/testing) +- Validation des mises à jour et du package Plugin : [Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins) -- `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 cette commande lorsqu’une exécution précédente du Gateway 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 barrière 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` est false, la barrière mesure les fichiers chargés par la suite de couverture unitaire au lieu de traiter chaque fichier source de voie fractionnée comme non couvert. +- `pnpm test:force` : tue tout processus Gateway restant 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 ceci 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 seuil de couverture unitaire des fichiers chargés, pas 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, le seuil mesure les fichiers chargés par la suite de couverture unitaire au lieu de considérer chaque fichier source des lanes séparées 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 mappages source explicites et du graphe d’import local. Les changements larges/config/package sont ignorés sauf s’ils correspondent à des tests précis. +- `pnpm test:changed` : exécution bon marché et intelligente des tests modifiés. 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/config/package 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 du harnais de test/de la config/du package doit revenir au comportement plus large de tests modifiés de Vitest. -- `pnpm changed:lanes` : affiche les voies architecturales déclenchées par le diff par rapport à `origin/main`. -- `pnpm check:changed` : exécute la barrière de vérification intelligente des changements pour le diff par rapport à `origin/main`. Elle exécute les commandes de typecheck, lint et garde pour les voies architecturales concernées, mais n’exécute pas les tests Vitest. Utilisez `pnpm test:changed` ou `pnpm test ` explicite comme preuve de test. -- `pnpm test` : achemine les cibles explicites de fichiers/répertoires vers des voies Vitest ciblées. Les exécutions sans cible utilisent des groupes de fragments fixes et s’étendent aux configs feuilles pour l’exécution parallèle locale ; le groupe d’extensions s’étend toujours aux configs de fragments par extension au lieu d’un unique énorme processus de projet racine. -- Les exécutions du wrapper de test se terminent par un bref résumé `[test] passed|failed|skipped ... in ...`. La propre ligne de durée de 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 config, d’un espace de travail, d’un répertoire d’agent ou d’un magasin de profils d’auth isolé. -- Helpers 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 env CLI, d’une capture de logs et d’un nettoyage au même endroit. -- Helpers E2E Docker/Bash : les voies qui sourcent `scripts/lib/docker-e2e-image.sh` peuvent passer `docker_e2e_test_state_shell_b64