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

chore(i18n): refresh fr translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 06:21:30 +00:00
parent 928636fa07
commit 788cb0ba2c
22 changed files with 3455 additions and 3223 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

209
docs/fr/automation/tasks.md
View File

@ -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
---
<Note>
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.
</Note>
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.
<Note>
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.
</Note>
## 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` |
<AccordionGroup>
<Accordion title="Valeurs de notification par défaut pour Cron et les médias">
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.
<Accordion title="Valeurs par défaut de notification pour Cron et les médias">
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é.
</Accordion>
<Accordion title="Garde-fou de concurrence de video_generate">
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.
<Accordion title="Garde-fou video_generate concurrent">
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.
</Accordion>
<Accordion title="Ce qui ne crée pas de tâches">
- 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`
</Accordion>
</AccordionGroup>
## 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.
<Tip>
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é.
</Tip>
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 <lookup> state_changes
@ -192,7 +192,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <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é.
</Accordion>
<Accordion title="tasks show">
@ -200,7 +200,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
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.
</Accordion>
<Accordion title="tasks cancel">
@ -208,7 +208,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
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.
</Accordion>
<Accordion title="tasks notify">
@ -223,14 +223,14 @@ openclaw tasks notify <lookup> 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é) |
</Accordion>
<Accordion title="maintenance des tâches">
@ -239,47 +239,47 @@ openclaw tasks notify <lookup> 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.
</Accordion>
<Accordion title="tasks flow list | show | cancel">
<Accordion title="lister | afficher | annuler le flux de tâches">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
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.
</Accordion>
</AccordionGroup>
## 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 :
<Steps>
<Step title="Réconciliation">
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`.
</Step>
<Step title="Réparation de session ACP">
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.
<Step title="Réparation des sessions ACP">
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.
</Step>
<Step title="Horodatage de nettoyage">
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.
<Step title="Horodatage du nettoyage">
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.
</Step>
<Step title="Élagage">
Supprime les enregistrements après leur date `cleanupAfter`.
Supprime les enregistrements dont la date `cleanupAfter` est dépassée.
</Step>
</Steps>
<Note>
**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.
</Note>
## Relation des tâches avec les autres systèmes
<AccordionGroup>
<Accordion title="Tâches et Task Flow">
[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.
</Accordion>
<Accordion title="Tâches et cron">
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).
</Accordion>
<Accordion title="Tâches et Heartbeat">
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).
</Accordion>
<Accordion title="Tâches et sessions">
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.
</Accordion>
<Accordion title="Tâches et exécutions d'agent">
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.
<Accordion title="Tâches et exécutions d’agent">
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.
</Accordion>
</AccordionGroup>
## 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

467
docs/fr/channels/telegram.md
View File

@ -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.
<CardGroup cols={3}>
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
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.
</Card>
<Card title="Dépannage des canaux" icon="wrench" href="/fr/channels/troubleshooting">
Diagnostics intercanaux et guides de réparation.
Diagnostics multicanaux et guides de réparation.
</Card>
<Card title="Configuration du Gateway" icon="settings" href="/fr/gateway/configuration">
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
<Steps>
<Step title="Créer le jeton du bot dans BotFather">
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.
</Step>
<Step title="Configurer le jeton et la politique de messages privés">
<Step title="Configurer le jeton et la politique de MP">
```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.
</Step>
<Step title="Démarrer le Gateway et approuver le premier message privé">
<Step title="Démarrer le Gateway et approuver le premier MP">
```bash
openclaw gateway
@ -69,26 +69,26 @@ openclaw pairing approve telegram <CODE>
</Step>
<Step title="Ajouter le bot à un groupe">
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.
</Step>
</Steps>
<Note>
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.
</Note>
## Paramètres côté Telegram
<AccordionGroup>
<Accordion title="Mode confidentialité et visibilité des groupes">
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.
</Accordion>
@ -101,8 +101,8 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu
<Accordion title="Options BotFather utiles">
- `/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
</Accordion>
</AccordionGroup>
@ -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
<Tabs>
<Tab title="Politique de messages privés">
<Tab title="Politique de MP">
`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:<your user id>`.
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:<your user id>`.
### 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<bot_token>/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<bot_token>/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<bot_token>/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.
</Warning>
@ -224,10 +224,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
<Tab title="Comportement des mentions">
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<bot_token>/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<bot_token>/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<bot_token>/getUpdates"
</Tab>
</Tabs>
## 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:<threadId>` 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.<chatId>.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:<threadId>` 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.<chatId>.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<bot_token>/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<bot_token>/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<bot_token>/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<bot_token>/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.
<Note>
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.
</Note>
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
</Accordion>
@ -370,7 +371,7 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/getUpdates"
</Accordion>
<Accordion title="Commandes natives et commandes personnalisées">
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<bot_token>/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<TOKEN>`. `apiRoot` doit être uniquement la racine de l’API Bot, et `openclaw doctor --fix` supprime un suffixe accidentel `/bot<TOKEN>`.
- `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<TOKEN>`. `apiRoot` doit être uniquement la racine de la Bot API, et `openclaw doctor --fix` supprime un `/bot<TOKEN>` 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 <requestId>` 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).
</Accordion>
<Accordion title="Boutons intégrés">
Configurez la portée du clavier intégré:
<Accordion title="Boutons en ligne">
Configurez la portée du clavier en ligne :
```json5
{
@ -455,7 +456,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Remplacement par compte:
Remplacement par compte :
```json5
{
@ -473,7 +474,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Portées:
Portées :
- `off`
- `dm`
@ -483,7 +484,7 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/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: <value>`
</Accordion>
<Accordion title="Actions de message Telegram pour agents et automatisation">
Les actions d’outil Telegram incluent:
<Accordion title="Actions de message Telegram pour les agents et l’automatisation">
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)
</Accordion>
<Accordion title="Balises de fils de réponse">
Telegram prend en charge les balises explicites de fil de réponse dans la sortie générée:
<Accordion title="Balises de fil de réponse">
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:<id>]]` 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.
</Accordion>
<Accordion title="Sujets de forum et comportement des fils">
Supergroupes de forum:
Supergroupes de forum :
- les clés de session de sujet ajoutent `:topic:<threadId>`
- 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.<chatId>.topics.<threadId>`
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<bot_token>/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 <agent> --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 <agent> --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.<chatId>.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.<chatId>.threadReplies` pour un DM.
</Accordion>
@ -601,10 +602,10 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/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<bot_token>/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<bot_token>/getUpdates"
}
```
Action d’envoi de sticker :
Envoyer une action de sticker :
```json5
{
@ -683,7 +684,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Rechercher des stickers en cache :
Rechercher des stickers mis en cache :
```json5
{
@ -697,47 +698,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Notifications de réactions">
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`.
</Accordion>
<Accordion title="Réactions d’accusé de réception">
`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.<accountId>.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.
</Accordion>
<Accordion title="Écritures de configuration depuis les événements et commandes Telegram">
<Accordion title="Écritures de configuration depuis des événements et commandes Telegram">
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<bot_token>/getUpdates"
</Accordion>
<Accordion title="Long polling ou Webhook">
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`).
<Accordion title="Long polling vs webhook">
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.
</Accordion>
<Accordion title="Limites, nouvelle tentative et cibles CLI">
- 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["<user_id>"].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 \
</Accordion>
<Accordion title="Approbations exec dans Telegram">
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
<AccordionGroup>
<Accordion title="Le bot ne répond pas aux messages de groupe sans mention">
- 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`.
</Accordion>
@ -887,42 +888,42 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
<Accordion title="Le bot ne voit aucun message de groupe">
- 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
</Accordion>
<Accordion title="Les commandes fonctionnent partiellement ou pas du tout">
- 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`
</Accordion>
<Accordion title="Le démarrage signale un jeton non autorisé">
- `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.<id>.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.<id>.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.
</Accordion>
<Accordion title="Instabilité du polling ou du réseau">
<Accordion title="Polling ou instabilité réseau">
- 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://<user>:<password>@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.<accountId>.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.
<Warning>
`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.
</Warning>
- 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
</Accordion>
</AccordionGroup>
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).
<Accordion title="Champs Telegram à fort signal">
<Accordion title="Champs Telegram à signal fort">
- 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<TOKEN>`)
- Webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- racine d'API personnalisée : `apiRoot` (racine de l'API Bot uniquement ; n'incluez pas `/bot<TOKEN>`)
- 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
</Accordion>
<Note>
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.*`.
</Note>
## Associé
## Connexe
<CardGroup cols={2}>
<Card title="Jumelage" icon="link" href="/fr/channels/pairing">
Jumelez un utilisateur Telegram au Gateway.
<Card title="Appariement" icon="link" href="/fr/channels/pairing">
Appariez un utilisateur Telegram au Gateway.
</Card>
<Card title="Groupes" icon="users" href="/fr/channels/groups">
Comportement des listes d’autorisation de groupes et de sujets.
Comportement de liste d'autorisation des groupes et des sujets.
</Card>
<Card title="Routage des canaux" icon="route" href="/fr/channels/channel-routing">
Routez les messages entrants vers les agents.
Routez les messages entrants vers des agents.
</Card>
<Card title="Sécurité" icon="shield" href="/fr/gateway/security">
Modèle de menace et durcissement.
</Card>
<Card title="Routage multi-agent" icon="sitemap" href="/fr/concepts/multi-agent">
Associez les groupes et les sujets aux agents.
Associez des groupes et des sujets à des agents.
</Card>
<Card title="Dépannage" icon="wrench" href="/fr/channels/troubleshooting">
Diagnostics inter-canaux.

318
docs/fr/channels/whatsapp.md
View File

@ -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`.
<CardGroup cols={3}>
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
La politique par défaut pour les messages directs consiste à utiliser l’appairage pour les expéditeurs inconnus.
<Card title="Pairing" icon="link" href="/fr/channels/pairing">
La politique de MP par défaut est l’appairage pour les expéditeurs inconnus.
</Card>
<Card title="Dépannage des canaux" icon="wrench" href="/fr/channels/troubleshooting">
Diagnostics et guides de réparation intercanaux.
<Card title="Channel troubleshooting" icon="wrench" href="/fr/channels/troubleshooting">
Diagnostics intercanaux et procédures de réparation.
</Card>
<Card title="Configuration du Gateway" icon="settings" href="/fr/gateway/configuration">
<Card title="Gateway configuration" icon="settings" href="/fr/gateway/configuration">
Modèles et exemples complets de configuration de canal.
</Card>
</CardGroup>
@ -48,7 +58,7 @@ exacte uniquement lorsque vous avez besoin d’une installation reproductible.
## Configuration rapide
<Steps>
<Step title="Configurer la politique d’accès WhatsApp">
<Step title="Configure WhatsApp access policy">
```json5
{
@ -65,19 +75,19 @@ exacte uniquement lorsque vous avez besoin d’une installation reproductible.
</Step>
<Step title="Lier WhatsApp (QR)">
<Step title="Link WhatsApp (QR)">
```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
</Step>
<Step title="Démarrer le Gateway">
<Step title="Start the gateway">
```bash
openclaw gateway
@ -94,7 +104,7 @@ openclaw gateway
</Step>
<Step title="Approuver la première demande d’appairage (si le mode d’appairage est utilisé)">
<Step title="Approve first pairing request (if using pairing mode)">
```bash
openclaw pairing list whatsapp
@ -107,18 +117,18 @@ openclaw pairing approve whatsapp <CODE>
</Steps>
<Note>
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.)
</Note>
## Modèles de déploiement
<AccordionGroup>
<Accordion title="Numéro dédié (recommandé)">
<Accordion title="Dedicated number (recommended)">
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
</Accordion>
<Accordion title="Solution de repli avec numéro personnel">
L’intégration prend en charge le mode numéro personnel et écrit une base compatible avec les messages à soi-même :
<Accordion title="Personal-number fallback">
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`.
</Accordion>
<Accordion title="Portée du canal uniquement WhatsApp Web">
Le canal de plateforme de messagerie est basé sur WhatsApp Web (`Baileys`) dans l’architecture actuelle des canaux OpenClaw.
<Accordion title="WhatsApp Web-only channel scope">
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.
</Accordion>
</AccordionGroup>
## 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 `@+<digits>` et `@<digits>` 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 `@+<digits>` et `@<digits>` 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:<agentId>:whatsapp:group:<jid>`).
- 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:<agentId>:whatsapp:channel:<jid>`) 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:<agentId>:whatsapp:channel:<jid>`) 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
<Tabs>
<Tab title="Politique de DM">
`channels.whatsapp.dmPolicy` contrôle l’accès aux discussions directes :
<Tab title="DM policy">
`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.<id>.dmPolicy` (et `allowFrom`) ont priorité sur les valeurs par défaut au niveau du canal pour ce compte.
Remplacement multicomptes : `channels.whatsapp.accounts.<id>.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é)
</Tab>
<Tab title="Politique de groupe + listes d’autorisation">
<Tab title="Group policy + allowlists">
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.
</Tab>
<Tab title="Mentions + /activation">
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.
</Tab>
</Tabs>
## 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
<AccordionGroup>
<Accordion title="Enveloppe entrante + contexte de réponse">
<Accordion title="Inbound envelope + reply context">
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
`<media:image>`.
</Accordion>
<Accordion title="Espaces réservés de médias et extraction de localisation/contact">
Les messages entrants contenant uniquement des médias sont normalisés avec des espaces réservés tels que :
<Accordion title="Media placeholders and location/contact extraction">
Les messages entrants ne contenant que des médias sont normalisés avec des espaces réservés tels que :
- `<media:image>`
- `<media:video>`
@ -320,15 +331,15 @@ Lorsque le numéro personnel lié est également présent dans `allowFrom`, les
- `<media:sticker>`
Les notes vocales de groupe autorisées sont transcrites avant le filtrage par mention lorsque le
corps est uniquement `<media:audio>`, 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 `<media:audio>`, 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.
</Accordion>
<Accordion title="Injection de l’historique de groupe en attente">
<Accordion title="Pending group history injection">
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.
</Accordion>
</AccordionGroup>
## Livraison, segmentation et médias
## Livraison, découpage et médias
<AccordionGroup>
<Accordion title="Segmentation du texte">
- limite de segment par défaut : `channels.whatsapp.textChunkLimit = 4000`
<Accordion title="Découpage du texte">
- 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
</Accordion>
<Accordion title="Comportement des médias sortants">
- 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
</Accordion>
@ -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.<accountId>.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
</Accordion>
</AccordionGroup>
## 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.<id>.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.<id>.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
<AccordionGroup>
<Accordion title="Sélection de compte et valeurs par défaut">
<Accordion title="Sélection du compte et valeurs par défaut">
- 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
</Accordion>
@ -499,16 +510,16 @@ Notes de comportement :
<Accordion title="Chemins des identifiants et compatibilité héritée">
- chemin d’authentification actuel : `~/.openclaw/credentials/whatsapp/<accountId>/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
</Accordion>
<Accordion title="Comportement de déconnexion">
`openclaw channels logout --channel whatsapp [--account <id>]` 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.
</Accordion>
</AccordionGroup>
@ -527,7 +538,7 @@ Notes de comportement :
<Accordion title="Non lié (QR requis)">
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 :
<Accordion title="Lié mais déconnecté / boucle de reconnexion">
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`.
</Accordion>
<Accordion title="La connexion QR expire derrière un proxy">
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`.
</Accordion>
@ -596,25 +596,25 @@ Notes de comportement :
<Accordion title="La réponse apparaît dans la transcription mais pas dans WhatsApp">
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`.
</Accordion>
<Accordion title="Messages de groupe ignorés de façon inattendue">
<Accordion title="Messages de groupe ignorés de manière inattendue">
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
</Accordion>
<Accordion title="Avertissement d’exécution Bun">
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.
</Accordion>
</AccordionGroup>
@ -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["<groupId>"].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["<groupId>"].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["<peerId>"].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["<peerId>"].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`.
<Note>
`dms` reste le compartiment léger de remplacement d’historique par DM (`dms.<id>.historyLimit`). Les remplacements de prompt vivent sous `direct`.
`dms` reste le bucket léger de remplacement d’historique par DM (`dms.<id>.historyLimit`). Les remplacements d’invites se trouvent sous `direct`.
</Note>
**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.<id>.enabled`, `accounts.<id>.authDir`, substitutions au niveau du compte
- multi-compte : `accounts.<id>.enabled`, `accounts.<id>.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.<id>.historyLimit`
- prompts : `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
- invites : `groups.<id>.systemPrompt`, `groups["*"].systemPrompt`, `direct.<id>.systemPrompt`, `direct["*"].systemPrompt`
## Associé
## Connexe
- [Appairage](/fr/channels/pairing)
- [Groupes](/fr/channels/groups)

422
docs/fr/ci.md
View File

@ -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=<branch-or-sha>
## 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/<tested-ref>/<run-id>-<attempt>/<lane>/`. Le pointeur actuel de la ref testée est écrit sous `openclaw-performance/<tested-ref>/latest-<lane>.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/<tested-ref>/<run-id>-<attempt>/<lane>/`. Le pointeur actuel de la ref testée est écrit comme `openclaw-performance/<tested-ref>/latest-<lane>.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=<sha>` :
```bash
pnpm ci:full-release --sha <full-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/<sha>-...` 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/<sha>-...` 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:<sha>` 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:<sha>` 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 <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # 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 <tbx_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 <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
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 <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_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 <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.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 <cbx_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 <cbx_id>`.
## Connexe
## Associé
- [Vue d’ensemble de l’installation](/fr/install)
- [Canaux de développement](/fr/install/development-channels)

97
docs/fr/cli/cron.md
View File

@ -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.
<Tip>
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
<AccordionGroup>
<Accordion title="Clés de session">
- `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:<id>` épingle une clé de session persistante explicite.
</Accordion>
<Accordion title="Sémantique des sessions isolées">
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.
</Accordion>
</AccordionGroup>
## Livraison
`openclaw cron list` et `openclaw cron show <job-id>` 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 <job-id>` 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.
<Note>
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`.
</Note>
### 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.
<Note>
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.
</Note>
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 <job-id> --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 <job-id> --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 <job-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 <job-id>` pour suivre le résultat final.
<Note>
`openclaw cron run <job-id>` force l’exécution par défaut. Utilisez `--due` pour conserver l’ancien comportement « exécuter seulement si dû ».
`openclaw cron run <job-id>` force l’exécution par défaut. Utilisez `--due` pour conserver l’ancien comportement « exécuter uniquement si l’échéance est atteinte ».
</Note>
## 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.
</Warning>
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/<jobId>.jsonl`.
## Migration d’anciennes tâches
## Migration des anciennes tâches
<Note>
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é.
</Note>
## 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 <job-id> --announce --channel telegram --to "123456789"
@ -178,13 +178,13 @@ Désactiver la livraison pour une tâche isolée :
openclaw cron edit <job-id> --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 <job-id> --light-context
```
Annoncer sur un canal spécifique :
Annoncer vers un canal spécifique :
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
@ -196,7 +196,7 @@ Annoncer vers un sujet de forum Telegram :
openclaw cron edit <job-id> --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 <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-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 <id>` 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 <job-id> --session current
openclaw cron edit <job-id> --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 <id>` 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 <id>` à la création pour épingler un agent spécifique.
Ajustements de livraison :

43
docs/fr/cli/status.md
View File

@ -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)

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

@ -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.<id>.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.<id>.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.<id>.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.<id>.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

335
docs/fr/concepts/mantis.md
View File

@ -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 <cbx_...>` ou `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` réutilise un desktop préchauffé.
- `--browser-url <url>` change la page ouverte dans le navigateur visible.
- `--html-file <path>` 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 <path>` 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 <cbx_...>` réexécute contre une machine où un opérateur s’est déjà connecté à Slack Web via VNC.
- `--lease-id <cbx_...>` 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 <url>` ouvre une URL Slack Web spécifique. Sans celle-ci, Mantis dérive `https://app.slack.com/client/<team>/<channel>` depuis `auth.test` de Slack lorsque le jeton du bot SUT est disponible.
- `--slack-channel-id <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 <url>` ouvre une URL Slack Web spécifique. Sans cela, Mantis dérive `https://app.slack.com/client/<team>/<channel>` depuis `auth.test` de Slack lorsque le jeton du bot SUT est disponible.
- `--slack-channel-id <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.
| <inline screenshot> | <inline screenshot> |
```
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 ?

421
docs/fr/concepts/qa-e2e-automation.md
View File

@ -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 <subcommand>`. 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 <subcommand>`. 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-<timestamp>/`.
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-<timestamp>/`.
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 <cbx_...>` 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 <cbx_...>` 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 <count>` 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 <count>` 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 <id>` | — | Exécute uniquement ce scénario. Répétable. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 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 <path>` | `process.cwd()` | Racine du dépôt lors d’un appel depuis un cwd neutre. |
| `--sut-account <id>` | `sut` | Id de compte temporaire dans la configuration du Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` hérité fonctionne toujours). |
| `--model <ref>` / `--alt-model <ref>` | 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\|convex>` | `env` | Voir [Pool d’identifiants Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` en CI, `maintainer` sinon | Rôle utilisé lorsque `--credential-source convex`. |
| Indicateur | Par défaut | Description |
| ------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Exécuter uniquement ce scénario. Répétable. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | 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 <path>` | `process.cwd()` | Racine du dépôt lors de l’appel depuis un cwd neutre. |
| `--sut-account <id>` | `sut` | Identifiant de compte temporaire dans la configuration Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` hérité fonctionne toujours). |
| `--model <ref>` / `--alt-model <ref>` | 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\|convex>` | `env` | Voir [pool d’identifiants Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `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/<theme>/*.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 <runner>` 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 <runner>` 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 <runner>` 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 <runner>` 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=<level>`. `--thinking <level>` définit toujours une
solution de repli globale, et l’ancienne forme `--model-thinking <provider/model=level>`
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=<level>`. `--thinking <level>` définit toujours un repli global, et l’ancienne forme `--model-thinking <provider/model=level>` 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)

574
docs/fr/gateway/configuration-reference.md
View File

@ -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.<skillKey>.enabled: false` désactive une Skill même si elle est incluse/installée.
- `entries.<skillKey>.apiKey` : raccourci pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef).
- `entries.<skillKey>.enabled: false` désactive une Skill même si elle est groupée/installée.
- `entries.<skillKey>.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`, `<workspace>/.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.<id>.apiKey` : champ pratique de clé API au niveau du plugin (lorsqu’il est pris en charge par le plugin).
- `plugins.entries.<id>.env` : carte de variables d’environnement limitée au plugin.
- `plugins.entries.<id>.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.<id>.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.<id>.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.<id>.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.<id>.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.<id>` 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.<id>.apiKey` : champ pratique de clé API au niveau du Plugin (lorsque pris en charge par le Plugin).
- `plugins.entries.<id>.env` : carte de variables d’environnement limitée au Plugin.
- `plugins.entries.<id>.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.<id>.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.<id>.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.<id>.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.<id>.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.<id>` 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.<name>.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).
<Accordion title="Gateway field details">
- `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.<provider>.healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur de santé tout en gardant le moniteur global activé.
- `channels.<provider>.accounts.<accountId>.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.<provider>.healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur de santé tout en conservant le moniteur global activé.
- `channels.<provider>.accounts.<accountId>.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.
</Accordion>
@ -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 <name>` (utilise `~/.openclaw-<name>`).
Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + le port `19001`), `--profile <name>` (utilise `~/.openclaw-<name>`).
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 <token>` ou `x-openclaw-token: <token>`.
Authentification : `Authorization: Bearer <token>` ou `x-openclaw-token: <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/<name>` → 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`.
<Accordion title="Mapping details">
- `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).
</Accordion>
@ -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://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__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 `<agentDir>/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.<id>.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.<id>.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).
<Accordion title="Configuration du pont héritée (référence historique)">
<Accordion title="Configuration du pont hérité (référence historique)">
```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/<jobId>.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/<jobId>.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

291
docs/fr/gateway/opentelemetry.md
View File

@ -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
```
<Note>
`protocol` ne prend actuellement en charge que `http/protobuf`. `grpc` est ignoré.
`protocol` prend actuellement en charge uniquement `http/protobuf`. `grpc` est ignoré.
</Note>
## 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.*`

260
docs/fr/help/testing-updates-plugins.md
View File

@ -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.

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

File diff suppressed because it is too large Load Diff

139
docs/fr/platforms/windows.md
View File

@ -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="<your-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="<your-token-with-repo-and-read:org>"
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)

22
docs/fr/plugins/reference/whatsapp.md
View File

@ -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

666
docs/fr/reference/RELEASING.md
View File

@ -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<package.json version>` 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<package.json version>` 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 <full-sha>
```
L’assistant pousse `release-ci/<sha>-...`, déclenche `Full Release Validation` depuis cette branche avec `ref=<sha>`, 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/<sha>-...`, déclenche `Full Release Validation`
depuis cette branche avec `ref=<sha>`, 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=<release-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=<release-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=<sha>` 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=<sha>` 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 <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=<lane[,lane]>` 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=<lane[,lane]>` 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)

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

@ -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 <target>` 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 <label> <scenario>` dans le conteneur et le décoder avec `scripts/lib/openclaw-e2e-instance.sh` ; les scripts multi-home peuvent passer `docker_e2e_test_state_function_b64` et appeler `openclaw_test_state_create <label> <scenario>` dans chaque flux. Les appelants de plus bas niveau peuvent utiliser `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` pour un extrait shell dans le conteneur, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` pour un fichier env hôte sourçable. Le `--` avant `create` empêche les runtimes Node récents de traiter `--env-file` comme un flag Node. Les voies Docker/Bash qui lancent un Gateway peuvent sourcer `scripts/lib/openclaw-e2e-instance.sh` dans le conteneur pour la résolution du point d’entrée, le démarrage OpenAI simulé, le lancement Gateway au premier plan/en arrière-plan, les probes de disponibilité, l’export d’env d’état, les dumps de logs et le nettoyage des processus.
- Les exécutions de fragments complètes, d’extensions et à motif d’inclusion mettent à jour les données de temps locales dans `.artifacts/vitest-shard-timings.json` ; les exécutions ultérieures de config entière utilisent ces temps pour équilibrer les fragments lents et rapides. Les fragments CI à motif d’inclusion ajoutent le nom du fragment à la clé de temps, ce qui garde les temps de fragments filtrés visibles sans remplacer les données de temps de config entière. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artéfact de temps local.
- Certains fichiers de test `plugin-sdk` et `commands` passent désormais par des voies légères dédiées qui ne conservent que `test/setup.ts`, en laissant les cas lourds en runtime sur leurs voies existantes.
- Les fichiers source avec des tests frères correspondent à ce frère avant de revenir à des globs de répertoire plus larges. Les modifications de helpers sous `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` et `src/plugins/contracts` utilisent un graphe d’import local pour exécuter les tests importeurs au lieu d’exécuter largement chaque fragment lorsque le chemin de dépendance est précis.
- `auto-reply` se divise désormais aussi en trois configs dédiées (`core`, `top-level`, `reply`) afin que le harnais de réponse ne domine pas les tests plus légers de statut/token/helper au niveau supérieur.
- `pnpm changed:lanes` : affiche les lanes architecturales déclenchées par le diff par rapport à `origin/main`.
- `pnpm check:changed` : exécute le seuil intelligent de vérification des modifications pour le diff par rapport à `origin/main`. Il exécute les commandes de typecheck, de lint et de garde pour les lanes architecturales affectées, mais n’exécute pas les tests Vitest. Utilisez `pnpm test:changed` ou `pnpm test <target>` explicite pour une preuve par les tests.
- `pnpm test` : route les cibles explicites fichier/répertoire via des lanes Vitest ciblées. Les exécutions sans cible utilisent des groupes de shards fixes et s’étendent aux configs feuilles pour l’exécution parallèle locale ; le groupe d’extensions s’étend toujours aux configs de shards par extension plutôt qu’à un seul énorme processus de projet racine.
- Les exécutions du wrapper de test se terminent par un court résumé `[test] passed|failed|skipped ... in ...`. La ligne de durée propre à Vitest reste le détail par shard.
- É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 agent ou d’un magasin de profils d’authentification isolés.
- 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 environnement CLI, de la capture des logs et du nettoyage au même endroit.
- Helpers E2E Docker/Bash : les lanes qui sourcent `scripts/lib/docker-e2e-image.sh` peuvent passer `docker_e2e_test_state_shell_b64 <label> <scenario>` dans le conteneur et le décoder avec `scripts/lib/openclaw-e2e-instance.sh` ; les scripts multi-home peuvent passer `docker_e2e_test_state_function_b64` et appeler `openclaw_test_state_create <label> <scenario>` dans chaque flux. Les appelants de plus bas niveau peuvent utiliser `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` pour un extrait shell dans le conteneur, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` pour un fichier d’environnement hôte sourçable. Le `--` avant `create` empêche les runtimes Node plus récents de traiter `--env-file` comme un flag Node. Les lanes Docker/Bash qui lancent un Gateway peuvent sourcer `scripts/lib/openclaw-e2e-instance.sh` dans le conteneur pour la résolution de l’entrypoint, le démarrage OpenAI simulé, le lancement Gateway au premier plan/en arrière-plan, les sondes de disponibilité, l’export de l’environnement d’état, les dumps de logs et le nettoyage des processus.
- Les exécutions de shards complètes, d’extensions et à motif d’inclusion mettent à jour les données de timings locales dans `.artifacts/vitest-shard-timings.json` ; les exécutions ultérieures de configs complètes utilisent ces timings pour équilibrer les shards lents et rapides. Les shards CI à motif d’inclusion ajoutent le nom du shard à la clé de timing, ce qui garde les timings de shards filtrés visibles sans remplacer les données de timing de config complète. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artefact de timing local.
- Certains fichiers de test `plugin-sdk` et `commands` sont désormais routés via des lanes légères dédiées qui ne conservent que `test/setup.ts`, en laissant les cas lourds en runtime sur leurs lanes existantes.
- Les fichiers source avec tests frères correspondent d’abord à ce frère avant de revenir à des globs de répertoire plus larges. Les modifications de helpers sous `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` et `src/plugins/contracts` utilisent un graphe d’import local pour exécuter les tests importeurs au lieu de lancer largement tous les shards lorsque le chemin de dépendance est précis.
- `auto-reply` est maintenant aussi séparé en trois configs dédiées (`core`, `top-level`, `reply`) afin que le harnais de réponse ne domine pas les tests plus légers de statut/token/helpers de premier niveau.
- La config Vitest de base utilise désormais par défaut `pool: "threads"` et `isolate: false`, avec le runner non isolé partagé activé dans les configs du dépôt.
- `pnpm test:channels` exécute `vitest.channels.config.ts`.
- `pnpm test:extensions` et `pnpm test extensions` exécutent tous les fragments d’extensions/plugins. Les plugins de canaux lourds, le plugin de navigateur et OpenAI s’exécutent comme fragments dédiés ; les autres groupes de plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une voie de plugin groupé.
- `pnpm test:perf:imports` : active les rapports de durée d’import Vitest et de ventilation des imports, tout en continuant à utiliser le routage de voies ciblées pour les cibles explicites de fichiers/répertoires.
- `pnpm test:perf:imports:changed` : même profilage d’import, mais uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` compare les performances du chemin routé en mode changed avec l’exécution native du projet racine pour le même diff git commité.
- `pnpm test:perf:changed:bench -- --worktree` compare les performances de l’ensemble de changements de l’arbre de travail actuel sans commit préalable.
- `pnpm test:perf:profile:main` : écrit un profil CPU pour le thread principal Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner` : écrit des profils CPU + heap pour le runner unitaire (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute chaque config feuille Vitest de suite complète en série et écrit des données de durée groupées ainsi que des artéfacts JSON/log par config. Le Test Performance Agent l’utilise comme baseline avant de tenter des corrections de tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après une modification axée sur les performances.
- `pnpm test:extensions` et `pnpm test extensions` exécutent tous les shards d’extensions/plugins. Les plugins de canaux lourds, le plugin navigateur et OpenAI s’exécutent comme des shards dédiés ; les autres groupes de plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une lane d’un seul plugin groupé.
- `pnpm test:perf:imports` : active le reporting de durée d’import et de répartition des imports Vitest, tout en utilisant encore le routage par lane ciblée pour les cibles explicites fichier/répertoire.
- `pnpm test:perf:imports:changed` : même profilage des imports, mais uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` compare en benchmark le chemin routé en mode modifié à l’exécution native du projet racine pour le même diff git committé.
- `pnpm test:perf:changed:bench -- --worktree` compare en benchmark l’ensemble de modifications de l’arbre de travail actuel sans commit préalable.
- `pnpm test:perf:profile:main` : écrit un profil CPU pour le thread principal de Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner` : écrit des profils CPU + tas pour le runner unitaire (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute en série chaque config feuille Vitest de suite complète et écrit les données de durée groupées ainsi que les artefacts JSON/log par config. Le Test Performance Agent l’utilise comme référence avant de tenter des correctifs de tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après une modification axée sur la performance.
- Intégration Gateway : activation explicite via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e` : exécute les tests smoke Gateway end-to-end (appariement multi-instance WS/HTTP/node). Par défaut, utilise `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des logs verbeux.
- `pnpm test:live` : exécute les tests live de fournisseurs (minimax/zai). Nécessite des clés API et `LIVE=1` (ou `*_LIVE_TEST=1` spécifique au fournisseur) pour ne pas être ignoré.
- `pnpm test:docker:all` : construit l’image de test live partagée, empaquette OpenClaw une fois comme tarball npm, construit/réutilise une image runner Node/Git minimale ainsi qu’une image fonctionnelle qui installe ce tarball dans `/app`, puis exécute les voies smoke Docker avec `OPENCLAW_SKIP_DOCKER_BUILD=1` via un ordonnanceur pondéré. L’image minimale (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) est utilisée pour les voies d’installation/mise à jour/dépendance de plugin ; ces voies montent le tarball préconstruit au lieu d’utiliser des sources de dépôt copiées. L’image fonctionnelle (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) est utilisée pour les voies de fonctionnalité normale de l’application construite. `scripts/package-openclaw-for-docker.mjs` est l’unique packer de package local/CI et valide le tarball ainsi que `dist/postinstall-inventory.json` avant que Docker ne le consomme. Les définitions de voies Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs` ; la logique du planificateur se trouve dans `scripts/lib/docker-e2e-plan.mjs` ; `scripts/test-docker-all.mjs` exécute le plan sélectionné. `node scripts/test-docker-all.mjs --plan-json` émet le plan CI détenu par l’ordonnanceur pour les voies sélectionnées, les types d’images, les besoins en package/image live, les scénarios d’état et les vérifications d’identifiants sans construire ni exécuter Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` contrôle les slots de processus et vaut 10 par défaut ; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` contrôle le pool de fin sensible aux fournisseurs et vaut 10 par défaut. Les plafonds de voies lourdes valent par défaut `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; les plafonds de fournisseurs valent par défaut une voie lourde par fournisseur via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` et `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Utilisez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` pour les hôtes plus grands. Si une voie dépasse le poids effectif ou le plafond de ressources sur un hôte à faible parallélisme, elle peut quand même démarrer depuis un pool vide et s’exécutera seule jusqu’à libérer la capacité. Les démarrages de voies sont espacés de 2 secondes par défaut afin d’éviter des tempêtes de création du daemon Docker local ; surchargez avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Le runner pré-vérifie Docker par défaut, nettoie les conteneurs E2E OpenClaw obsolètes, émet le statut des voies actives toutes les 30 secondes, partage les caches d’outils CLI de fournisseurs entre les voies compatibles, réessaie une fois par défaut les échecs transitoires de fournisseurs live (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) et stocke les temps de voies dans `.artifacts/docker-tests/lane-timings.json` pour un tri du plus long au plus court lors des exécutions ultérieures. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour imprimer le manifeste des voies sans exécuter Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` pour ajuster la sortie de statut, ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` pour désactiver la réutilisation des temps. Utilisez `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` pour les voies déterministes/locales uniquement ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` pour les voies de fournisseurs live uniquement ; les alias de package sont `pnpm test:docker:local:all` et `pnpm test:docker:live:all`. Le mode live-only fusionne les voies live principales et de fin dans un seul pool du plus long au plus court afin que les buckets de fournisseurs puissent regrouper le travail Claude, Codex et Gemini. Le runner cesse de planifier de nouvelles voies groupées après le premier échec sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque voie dispose d’un timeout de secours de 120 minutes surchargeable avec `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` ; certaines voies live/de fin sélectionnées utilisent des plafonds par voie plus stricts. Les commandes de configuration Docker de backend CLI ont leur propre timeout via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (par défaut 180). Les logs par voie, `summary.json`, `failures.json` et les temps de phase sont écrits sous `.artifacts/docker-tests/<run-id>/` ; utilisez `pnpm test:docker:timings <summary.json>` pour inspecter les voies lentes et `pnpm test:docker:rerun <run-id|summary.json|failures.json>` pour imprimer des commandes de réexécution ciblées peu coûteuses.
- `pnpm test:docker:browser-cdp-snapshot` : construit un conteneur E2E source basé sur Chromium, démarre un CDP brut ainsi qu’un Gateway isolé, exécute `browser doctor --deep` et vérifie que les instantanés de rôles CDP incluent les URL de liens, les éléments cliquables promus par le curseur, les refs d’iframe et les métadonnées de frame.
- Les probes Docker live de backend CLI peuvent être exécutées comme voies ciblées, par exemple `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude et Gemini ont des alias `:resume` et `:mcp` correspondants.
- `pnpm test:docker:openwebui` : démarre OpenClaw + Open WebUI dockerisés, se connecte via Open WebUI, vérifie `/api/models`, puis exécute un vrai chat proxifié via `/api/chat/completions`. Nécessite une clé de modèle live utilisable (par exemple OpenAI dans `~/.profile`), récupère une image Open WebUI externe et n’est pas censé être stable en CI comme les suites unitaires/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway prérempli et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte des conversations routées, les lectures de transcripts, les métadonnées de pièces jointes, le comportement de file d’événements live, le routage des envois sortants et les notifications de canal + permission au style Claude via le vrai pont stdio. L’assertion de notification Claude lit directement les frames MCP stdio brutes afin que le smoke reflète ce que le pont émet réellement.
- `pnpm test:docker:upgrade-survivor` : installe le tarball OpenClaw empaqueté sur un fixture d’ancien utilisateur non vierge, exécute la mise à jour du package ainsi que `doctor` en mode non interactif sans clés de fournisseur ou de canal live, puis démarre un Gateway en boucle locale et vérifie que les agents, la configuration des canaux, les listes d’autorisation de plugins, les fichiers d’espace de travail/de session, l’état obsolète des dépendances de plugins héritées, le démarrage et l’état RPC survivent.
- `pnpm test:docker:published-upgrade-survivor` : installe `openclaw@latest` par défaut, injecte des fichiers réalistes d’utilisateur existant sans clés de fournisseur ou de canal live, configure cette base avec une recette de commande `openclaw config set` intégrée, met à jour cette installation publiée vers le tarball OpenClaw empaqueté, exécute `doctor` en mode non interactif, écrit `.artifacts/upgrade-survivor/summary.json`, puis démarre un Gateway en boucle locale et vérifie que les intents configurés, les fichiers d’espace de travail/de session, la configuration obsolète des plugins et l’état hérité des dépendances, le démarrage, `/healthz`, `/readyz` et l’état RPC survivent ou sont réparés proprement. Remplacez une base avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, développez une matrice exacte avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` comme `all-since-2026.4.23`, ou ajoutez des fixtures de scénario avec `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` ; l’ensemble `reported-issues` inclut `configured-plugin-installs` pour vérifier que les plugins OpenClaw externes configurés s’installent automatiquement pendant la mise à niveau, et `stale-source-plugin-shadow` pour empêcher les ombres de plugins source uniquement de casser le démarrage. Package Acceptance les expose sous les noms `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` et `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration` : exécute le harness `published-upgrade survivor` dans le scénario `plugin-deps-cleanup`, qui met fortement l’accent sur le nettoyage, en commençant à `openclaw@2026.4.23` par défaut. Le workflow séparé `Update Migration` développe cette voie avec `baselines=all-since-2026.4.23` afin que chaque package stable publié à partir de `.23` soit mis à jour vers le candidat et prouve le nettoyage des dépendances des plugins configurés en dehors de Full Release CI.
- `pnpm test:docker:plugins` : exécute un smoke test d’installation/mise à jour pour le chemin local, `file:`, les packages de registre npm avec dépendances hissées, les références git mobiles, les fixtures ClawHub, les mises à jour du marketplace et l’activation/l’inspection du bundle Claude.
- `pnpm test:e2e` : exécute les smoke tests Gateway de bout en bout (appariement multi-instance WS/HTTP/node). Utilise par défaut `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des logs verbeux.
- `pnpm test:live` : exécute les tests live de fournisseurs (minimax/zai). Nécessite des clés API et `LIVE=1` (ou `*_LIVE_TEST=1` spécifique au fournisseur) pour ne plus être ignoré.
- `pnpm test:docker:all` : construit l’image de test live partagée, package OpenClaw une fois comme tarball npm, construit/réutilise une image runner Node/Git nue ainsi qu’une image fonctionnelle qui installe ce tarball dans `/app`, puis exécute les lanes de smoke Docker avec `OPENCLAW_SKIP_DOCKER_BUILD=1` via un ordonnanceur pondéré. L’image nue (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) est utilisée pour les lanes d’installation/mise à jour/dépendances de plugin ; ces lanes montent le tarball préconstruit au lieu d’utiliser les sources du dépôt copiées. L’image fonctionnelle (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) est utilisée pour les lanes normales de fonctionnalité d’application construite. `scripts/package-openclaw-for-docker.mjs` est l’unique packager de package local/CI et valide le tarball ainsi que `dist/postinstall-inventory.json` avant consommation par Docker. Les définitions de lanes Docker vivent dans `scripts/lib/docker-e2e-scenarios.mjs` ; la logique du planificateur vit dans `scripts/lib/docker-e2e-plan.mjs` ; `scripts/test-docker-all.mjs` exécute le plan sélectionné. `node scripts/test-docker-all.mjs --plan-json` émet le plan CI possédé par l’ordonnanceur pour les lanes sélectionnées, les types d’images, les besoins package/image live, les scénarios d’état et les vérifications d’identifiants, sans construire ni exécuter Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` contrôle les slots de processus et vaut 10 par défaut ; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` contrôle le pool de queue sensible aux fournisseurs et vaut 10 par défaut. Les plafonds des lanes lourdes valent par défaut `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` et `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7` ; les plafonds de fournisseurs valent par défaut une lane lourde par fournisseur via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` et `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Utilisez `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` pour des hôtes plus grands. Si une lane dépasse le plafond effectif de poids ou de ressources sur un hôte à faible parallélisme, elle peut quand même démarrer depuis un pool vide et s’exécutera seule jusqu’à libérer de la capacité. Les démarrages de lanes sont espacés de 2 secondes par défaut pour éviter les tempêtes de création du démon Docker local ; remplacez avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Le runner effectue par défaut des vérifications préalables Docker, nettoie les conteneurs E2E OpenClaw obsolètes, émet l’état des lanes actives toutes les 30 secondes, partage les caches d’outils CLI de fournisseurs entre lanes compatibles, réessaie par défaut une fois les échecs transitoires de fournisseurs live (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) et stocke les timings de lanes dans `.artifacts/docker-tests/lane-timings.json` pour un ordre du plus long au plus court lors des exécutions ultérieures. Utilisez `OPENCLAW_DOCKER_ALL_DRY_RUN=1` pour afficher le manifeste des lanes sans exécuter Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` pour ajuster la sortie d’état, ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` pour désactiver la réutilisation des timings. Utilisez `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` pour les lanes déterministes/locales uniquement ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` pour les lanes de fournisseurs live uniquement ; les alias de package sont `pnpm test:docker:local:all` et `pnpm test:docker:live:all`. Le mode live-only fusionne les lanes live principales et de queue dans un pool unique du plus long au plus court afin que les compartiments de fournisseurs puissent regrouper le travail Claude, Codex et Gemini. Le runner cesse de planifier de nouvelles lanes groupées après le premier échec sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque lane dispose d’un timeout de repli de 120 minutes, remplaçable avec `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` ; certaines lanes live/de queue sélectionnées utilisent des plafonds par lane plus stricts. Les commandes de configuration Docker du backend CLI ont leur propre timeout via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (par défaut 180). Les logs par lane, `summary.json`, `failures.json` et les timings de phase sont écrits sous `.artifacts/docker-tests/<run-id>/` ; utilisez `pnpm test:docker:timings <summary.json>` pour inspecter les lanes lentes et `pnpm test:docker:rerun <run-id|summary.json|failures.json>` pour afficher des commandes de relance ciblées bon marché.
- `pnpm test:docker:browser-cdp-snapshot` : construit un conteneur E2E source adossé à Chromium, démarre CDP brut ainsi qu’un Gateway isolé, exécute `browser doctor --deep`, et vérifie que les instantanés de rôle CDP incluent les URL de liens, les éléments cliquables promus par le curseur, les références d’iframe et les métadonnées de frame.
- Les sondes Docker live du backend CLI peuvent être exécutées comme lanes ciblées, par exemple `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude et Gemini disposent d’alias `:resume` et `:mcp` correspondants.
- `pnpm test:docker:openwebui` : démarre OpenClaw + Open WebUI dockerisés, se connecte via Open WebUI, vérifie `/api/models`, puis exécute un vrai chat proxifié via `/api/chat/completions`. Nécessite une clé de modèle live utilisable (par exemple OpenAI dans `~/.profile`), télécharge une image Open WebUI externe et n’est pas censé être stable en CI comme les suites unitaires/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway prérempli et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte des conversations routées, les lectures de transcripts, les métadonnées de pièces jointes, le comportement de la file d’événements live, le routage des envois sortants et les notifications de canal + permission de style Claude sur le vrai pont stdio. L’assertion de notification Claude lit directement les trames MCP stdio brutes afin que le smoke reflète ce que le pont émet réellement.
- `pnpm test:docker:upgrade-survivor` : installe l’archive tar OpenClaw empaquetée par-dessus un fixture d’ancien utilisateur non nettoyé, exécute la mise à jour du paquet ainsi que doctor en mode non interactif sans clés de fournisseur ou de canal live, puis démarre un Gateway en loopback et vérifie que les agents, la configuration des canaux, les listes d’autorisation de Plugin, les fichiers d’espace de travail/session, l’état obsolète des dépendances de Plugin héritées, le démarrage et l’état RPC survivent.
- `pnpm test:docker:published-upgrade-survivor` : installe `openclaw@latest` par défaut, prépare des fichiers réalistes d’utilisateur existant sans clés de fournisseur ou de canal live, configure cette base avec une recette de commande `openclaw config set` intégrée, met à jour cette installation publiée vers l’archive tar OpenClaw empaquetée, exécute doctor en mode non interactif, écrit `.artifacts/upgrade-survivor/summary.json`, puis démarre un Gateway en loopback et vérifie que les intents configurés, les fichiers d’espace de travail/session, la configuration de Plugin obsolète et l’état des dépendances héritées, le démarrage, `/healthz`, `/readyz` et l’état RPC survivent ou se réparent proprement. Remplacez une base avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, étendez une matrice locale exacte avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` comme `openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15`, ou ajoutez des fixtures de scénario avec `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` ; l’ensemble reported-issues inclut `configured-plugin-installs` pour vérifier que les plugins OpenClaw externes configurés s’installent automatiquement pendant la mise à niveau et `stale-source-plugin-shadow` pour empêcher les ombres de Plugin uniquement source de casser le démarrage. Package Acceptance expose ces options sous forme de `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` et `published_upgrade_survivor_scenarios`, et résout les jetons de base méta tels que `last-stable-4` ou `all-since-2026.4.23` avant de transmettre les spécifications exactes de paquet aux lanes Docker.
- `pnpm test:docker:update-migration` : exécute le harnais published-upgrade survivor dans le scénario `plugin-deps-cleanup`, qui privilégie fortement le nettoyage, en commençant à `openclaw@2026.4.23` par défaut. Le workflow distinct `Update Migration` étend cette lane avec `baselines=all-since-2026.4.23` afin que chaque paquet stable publié depuis `.23` mette à jour vers le candidat et prouve le nettoyage des dépendances de Plugin configurées en dehors de Full Release CI.
- `pnpm test:docker:plugins` : exécute un smoke test d’installation/mise à jour pour les chemins locaux, `file:`, les paquets de registre npm avec dépendances hissées, les refs git mobiles, les fixtures ClawHub, les mises à jour marketplace et l’activation/inspection du bundle Claude.
## Contrôle PR local
## Gate PR local
Pour les vérifications locales de fusion/contrôle de PR, exécutez :
Pour les vérifications locales de landing/gate de PR, exécutez :
- `pnpm check:changed`
- `pnpm check`
@ -66,7 +66,7 @@ Pour les vérifications locales de fusion/contrôle de PR, exécutez :
- `pnpm test`
- `pnpm check:docs`
Si `pnpm test` échoue de façon intermittente sur un hôte chargé, relancez-le une fois avant de considérer cela comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les hôtes à mémoire contrainte, utilisez :
Si `pnpm test` échoue de façon intermittente sur un hôte chargé, relancez-le une fois avant de considérer cela comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les hôtes limités en mémoire, utilisez :
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -78,13 +78,13 @@ Script : [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/ma
Utilisation :
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Env facultatif : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Invite par défaut : “Répondez par un seul mot : ok. Sans ponctuation ni texte supplémentaire.”
- Env optionnel : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt par défaut : « Réponds avec un seul mot : ok. Pas de ponctuation ni de texte supplémentaire. »
Dernière exécution (2025-12-31, 20 exécutions) :
- médiane minimax 1279 ms (min 1114, max 2431)
- médiane opus 2454 ms (min 1224, max 3170)
- minimax médiane 1279 ms (min 1114, max 2431)
- opus médiane 2454 ms (min 1224, max 3170)
## Banc de démarrage CLI
@ -114,12 +114,12 @@ Préréglages :
- `real` : `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all` : les deux préréglages
La sortie inclut `sampleCount`, la moyenne, p50, p95, min/max, la distribution des codes de sortie/signaux, ainsi que des résumés du RSS maximal pour chaque commande. Les options facultatives `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 pour chaque exécution afin que le chronométrage et la capture de profils utilisent le même harnais.
La sortie inclut `sampleCount`, avg, p50, p95, min/max, la distribution exit-code/signal et les résumés RSS max pour chaque commande. Les options `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 pour chaque exécution, afin que le chronométrage et la capture de profils utilisent le même harnais.
Conventions des sorties enregistrées :
Conventions de sortie enregistrée :
- `pnpm test:startup:bench:smoke` écrit l’artefact de smoke ciblé dans `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` écrit l’artefact de la suite complète dans `.artifacts/cli-startup-bench-all.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:save` écrit l’artefact de suite complète dans `.artifacts/cli-startup-bench-all.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:update` actualise le fixture de référence archivé dans `test/fixtures/cli-startup-bench.json` avec `runs=5` et `warmup=1`
Fixture archivé :
@ -130,7 +130,7 @@ Fixture archivé :
## E2E d’onboarding (Docker)
Docker est facultatif ; ceci n’est nécessaire que pour les smoke tests d’onboarding conteneurisés.
Docker est optionnel ; ceci n’est nécessaire que pour les smoke tests d’onboarding conteneurisés.
Flux complet de démarrage à froid dans un conteneur Linux propre :
@ -138,18 +138,18 @@ Flux complet de démarrage à froid dans un conteneur Linux propre :
scripts/e2e/onboard-docker.sh
```
Ce script pilote l’assistant interactif via un pseudo-tty, vérifie les fichiers de configuration/d’espace de travail/de session, puis démarre le Gateway et exécute `openclaw health`.
Ce script pilote l’assistant interactif via un pseudo-tty, vérifie les fichiers de configuration, d’espace de travail et de session, puis démarre le Gateway et exécute `openclaw health`.
## Smoke d’import QR (Docker)
Garantit que l’assistant d’exécution QR maintenu se charge sous les runtimes Docker Node pris en charge (Node 24 par défaut, Node 22 compatible) :
Garantit que l’auxiliaire d’exécution QR maintenu se charge sous les runtimes Docker Node pris en charge (Node 24 par défaut, Node 22 compatible) :
```bash
pnpm test:docker:qr
```
## Liens connexes
## Associé
- [Tests](/fr/help/testing)
- [Tests en direct](/fr/help/testing-live)
- [Tests live](/fr/help/testing-live)
- [Tests des mises à jour et des plugins](/fr/help/testing-updates-plugins)

114
docs/fr/tools/media-overview.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Recherche d’un aperçu des capacités multimédias d’OpenClaw
- Vous cherchez un aperçu des capacités multimédias d’OpenClaw
- Choisir le fournisseur de médias à configurer
- Comprendre le fonctionnement de la génération asynchrone de médias
sidebarTitle: Media overview
summary: Aperçu des capacités d’image, de vidéo, de musique, de parole et de compréhension des médias
title: Présentation des médias
summary: Fonctionnalités d’image, de vidéo, de musique, de parole et de compréhension des médias en un coup d’œil
title: Vue d’ensemble des médias
x-i18n:
generated_at: "2026-05-05T01:50:55Z"
generated_at: "2026-05-05T06:19:02Z"
model: gpt-5.5
provider: openai
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_hash: fd02d4418fe294fda5f1437dd3a07c4aeb4de3b46a1b70bfe36914bc27123cc4
source_path: tools/media-overview.md
workflow: 16
---
OpenClaw génère des images, des vidéos et de la musique, comprend les médias entrants
(images, audio, vidéo) et énonce les réponses à voix haute avec la synthèse vocale. Toutes
(images, audio, vidéo) et prononce les réponses à voix haute avec la synthèse vocale. Toutes
les capacités multimédias sont pilotées par des outils : l’agent décide quand les utiliser en fonction
de la conversation, et chaque outil n’apparaît que lorsqu’au moins un fournisseur sous-jacent
est configuré.
@ -24,35 +24,35 @@ est configuré.
## Capacités
<CardGroup cols={2}>
<Card title="Image generation" href="/fr/tools/image-generation" icon="image">
Créez et modifiez des images à partir d’invites textuelles ou d’images de référence via
`image_generate`. Synchrone — se termine dans le flux de la réponse.
<Card title="Génération d’images" href="/fr/tools/image-generation" icon="image">
Créez et modifiez des images à partir de prompts textuels ou d’images de référence via
`image_generate`. Synchrone — se termine directement dans la réponse.
</Card>
<Card title="Video generation" href="/fr/tools/video-generation" icon="video">
<Card title="Génération de vidéos" href="/fr/tools/video-generation" icon="video">
Texte-vers-vidéo, image-vers-vidéo et vidéo-vers-vidéo via `video_generate`.
Asynchrone — s’exécute en arrière-plan et publie le résultat lorsqu’il est prêt.
</Card>
<Card title="Music generation" href="/fr/tools/music-generation" icon="music">
<Card title="Génération de musique" href="/fr/tools/music-generation" icon="music">
Générez de la musique ou des pistes audio via `music_generate`. Asynchrone sur les
fournisseurs partagés ; le chemin de workflow ComfyUI s’exécute de manière synchrone.
</Card>
<Card title="Text-to-speech" href="/fr/tools/tts" icon="microphone">
<Card title="Synthèse vocale" href="/fr/tools/tts" icon="microphone">
Convertissez les réponses sortantes en audio parlé via l’outil `tts` et la configuration
`messages.tts`. Synchrone.
</Card>
<Card title="Media understanding" href="/fr/nodes/media-understanding" icon="eye">
Résumez les images, l’audio et la vidéo entrants à l’aide de fournisseurs de modèles
compatibles avec la vision et de plugins dédiés à la compréhension des médias.
<Card title="Compréhension multimédia" href="/fr/nodes/media-understanding" icon="eye">
Résumez les images, l’audio et les vidéos entrants à l’aide de fournisseurs de modèles
capables de vision et de plugins dédiés à la compréhension multimédia.
</Card>
<Card title="Speech-to-text" href="/fr/nodes/audio" icon="ear-listen">
Transcrivez les messages vocaux entrants via des fournisseurs STT par lots ou STT
<Card title="Reconnaissance vocale" href="/fr/nodes/audio" icon="ear-listen">
Transcrivez les messages vocaux entrants via des fournisseurs de STT par lot ou de STT
en streaming pour Voice Call.
</Card>
</CardGroup>
## Matrice des capacités des fournisseurs
| Fournisseur | Image | Vidéo | Musique | TTS | STT | Voix en temps réel | Compréhension des médias |
| Fournisseur | Image | Vidéo | Musique | TTS | STT | Voix en temps réel | Compréhension multimédia |
| ----------- | :---: | :---: | :-----: | :-: | :-: | :----------------: | :----------------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
@ -78,74 +78,76 @@ est configuré.
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
La compréhension des médias utilise tout modèle compatible avec la vision ou l’audio enregistré
dans votre configuration de fournisseur. La matrice ci-dessus liste les fournisseurs avec une prise en charge
dédiée de la compréhension des médias ; la plupart des fournisseurs de LLM multimodaux (Anthropic, Google,
OpenAI, etc.) peuvent aussi comprendre les médias entrants lorsqu’ils sont configurés comme modèle de
La compréhension multimédia utilise tout modèle capable de vision ou d’audio enregistré
dans votre configuration de fournisseur. La matrice ci-dessus liste les fournisseurs disposant d’une prise en charge dédiée
de la compréhension multimédia ; la plupart des fournisseurs de LLM multimodaux (Anthropic, Google,
OpenAI, etc.) peuvent également comprendre les médias entrants lorsqu’ils sont configurés comme modèle de
réponse actif.
</Note>
## Asynchrone ou synchrone
| Capacité | Mode | Pourquoi |
| ---------------- | ------------ | ----------------------------------------------------------------- |
| Image | Synchrone | Les réponses du fournisseur arrivent en quelques secondes ; se termine dans le flux de la réponse. |
| Synthèse vocale | Synchrone | Les réponses du fournisseur arrivent en quelques secondes ; jointes à l’audio de la réponse. |
| Vidéo | Asynchrone | Le traitement par le fournisseur prend de 30 s à plusieurs minutes. |
| Musique (partagée) | Asynchrone | Même caractéristique de traitement fournisseur que la vidéo. |
| Musique (ComfyUI) | Synchrone | Le workflow local s’exécute en ligne contre le serveur ComfyUI configuré. |
| Capacité | Mode | Pourquoi |
| --------------- | ------------ | -------------------------------------------------------------------------------------------------- |
| Image | Synchrone | Les réponses du fournisseur reviennent en quelques secondes ; se termine directement dans la réponse. |
| Synthèse vocale | Synchrone | Les réponses du fournisseur reviennent en quelques secondes ; jointes à l’audio de la réponse. |
| Vidéo | Asynchrone | Le traitement par le fournisseur prend de 30 s à plusieurs minutes ; les files lentes peuvent aller jusqu’au délai d’expiration configuré. |
| Musique (partagée) | Asynchrone | Même caractéristique de traitement par le fournisseur que pour la vidéo. |
| Musique (ComfyUI) | Synchrone | Le workflow local s’exécute directement sur le serveur ComfyUI configuré. |
Pour les outils asynchrones, OpenClaw soumet la demande au fournisseur, renvoie immédiatement un identifiant
de tâche et suit le job dans le registre des tâches. L’agent continue de répondre
aux autres messages pendant l’exécution du job. Lorsque le fournisseur termine,
OpenClaw réveille l’agent avec les chemins des médias générés afin qu’il puisse prévenir
Pour les outils asynchrones, OpenClaw soumet la demande au fournisseur, renvoie immédiatement un identifiant de tâche
et suit le travail dans le registre des tâches. L’agent continue
de répondre aux autres messages pendant que le travail s’exécute. Lorsque le fournisseur a terminé,
OpenClaw réveille l’agent avec les chemins des médias générés afin qu’il puisse informer
l’utilisateur et, lorsque la politique de livraison de la source l’exige, relayer le résultat via
l’outil de message.
l’outil de message. Pour les routes de groupe/canal qui utilisent uniquement l’outil de message, OpenClaw considère
l’absence de preuve de livraison par l’outil de message comme une tentative d’achèvement échouée et envoie
le média généré de secours directement au canal d’origine.
## Speech-to-text et Voice Call
## Reconnaissance vocale et Voice Call
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio et xAI peuvent tous transcrire
l’audio entrant via le chemin par lots `tools.media.audio` lorsqu’ils sont configurés.
Les plugins de canal qui prévalident une note vocale pour le filtrage des mentions ou l’analyse
des commandes marquent la pièce jointe transcrite sur le contexte entrant, afin que la passe partagée
de compréhension des médias réutilise cette transcription au lieu d’effectuer un second appel
l’audio entrant via le chemin par lot `tools.media.audio` lorsqu’ils sont configurés.
Les plugins de canal qui précontrôlent une note vocale pour le filtrage des mentions ou l’analyse des commandes
marquent la pièce jointe transcrite sur le contexte entrant, afin que la passe partagée de
compréhension multimédia réutilise cette transcription au lieu de lancer un second appel
STT pour le même audio.
Deepgram, ElevenLabs, Mistral, OpenAI et xAI enregistrent également des fournisseurs STT
en streaming pour Voice Call, afin que l’audio téléphonique en direct puisse être transmis au fournisseur
sélectionné sans attendre un enregistrement terminé.
Deepgram, ElevenLabs, Mistral, OpenAI et xAI enregistrent également des fournisseurs de STT
en streaming pour Voice Call, afin que l’audio téléphonique en direct puisse être transmis au fournisseur sélectionné
sans attendre un enregistrement terminé.
## Correspondances des fournisseurs (comment les fournisseurs se répartissent entre les surfaces)
## Correspondances des fournisseurs (répartition des vendeurs entre les surfaces)
<AccordionGroup>
<Accordion title="Google">
Surfaces image, vidéo, musique, TTS par lots, voix en temps réel côté backend et
compréhension des médias.
Surfaces d’image, de vidéo, de musique, de TTS par lot, de voix temps réel côté backend et de
compréhension multimédia.
</Accordion>
<Accordion title="OpenAI">
Surfaces image, vidéo, TTS par lots, STT par lots, STT en streaming pour Voice Call, voix
en temps réel côté backend et embeddings de mémoire.
Surfaces d’image, de vidéo, de TTS par lot, de STT par lot, de STT en streaming pour Voice Call, de voix
temps réel côté backend et d’embeddings de mémoire.
</Accordion>
<Accordion title="DeepInfra">
Surfaces routage chat/modèle, génération/édition d’images, texte-vers-vidéo, TTS par lots,
STT par lots, compréhension des médias image et embeddings de mémoire.
Les modèles natifs DeepInfra de rerank/classification/détection d’objets ne sont pas
enregistrés tant qu’OpenClaw ne dispose pas de contrats de fournisseur dédiés pour ces
Routage chat/modèle, génération/modification d’images, texte-vers-vidéo, TTS par lot,
STT par lot, compréhension multimédia d’images et surfaces d’embeddings de mémoire.
Les modèles de rerank/classification/détection d’objets natifs de DeepInfra ne sont pas
enregistrés tant qu’OpenClaw ne dispose pas de contrats fournisseur dédiés à ces
catégories.
</Accordion>
<Accordion title="xAI">
Image, vidéo, recherche, exécution de code, TTS par lots, STT par lots et STT en streaming pour Voice
Call. La voix en temps réel xAI est une capacité amont, mais elle n’est
pas enregistrée dans OpenClaw tant que le contrat partagé de voix en temps réel ne peut pas
Image, vidéo, recherche, exécution de code, TTS par lot, STT par lot et STT en streaming pour Voice
Call. La voix en temps réel de xAI est une capacité amont, mais elle n’est
pas enregistrée dans OpenClaw tant que le contrat partagé de voix temps réel ne peut pas
la représenter.
</Accordion>
</AccordionGroup>
## Connexe
## Associés
- [Génération d’images](/fr/tools/image-generation)
- [Génération de vidéos](/fr/tools/video-generation)
- [Génération de musique](/fr/tools/music-generation)
- [Synthèse vocale](/fr/tools/tts)
- [Compréhension des médias](/fr/nodes/media-understanding)
- [Compréhension multimédia](/fr/nodes/media-understanding)
- [Nœuds audio](/fr/nodes/audio)

167
docs/fr/tools/music-generation.md
View File

@ -1,47 +1,38 @@
---
read_when:
- Générer de la musique ou de l’audio avec l’agent
- Configuration des fournisseurs et modèles de génération musicale
- Générer de la musique ou de l’audio via l’agent
- Configuration des fournisseurs et des modèles de génération musicale
- Comprendre les paramètres de l’outil music_generate
sidebarTitle: Music generation
summary: Générer de la musique via music_generate avec les flux de travail Google Lyria, MiniMax et ComfyUI
summary: Générer de la musique avec music_generate dans les flux de travail Google Lyria, MiniMax et ComfyUI
title: Génération de musique
x-i18n:
generated_at: "2026-05-05T01:51:10Z"
generated_at: "2026-05-05T06:19:03Z"
model: gpt-5.5
provider: openai
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_hash: f5e74aa7d43ffe00adb6d6c170d36dbc107f2baf0069243733c5dd6e4582175a
source_path: tools/music-generation.md
workflow: 16
---
L’outil `music_generate` permet à l’agent de créer de la musique ou de l’audio via la
capacité partagée de génération musicale avec les fournisseurs configurés — Google,
MiniMax et ComfyUI configuré par workflow aujourd’hui.
L’outil `music_generate` permet à l’agent de créer de la musique ou de l’audio via la fonctionnalité partagée de génération musicale avec des fournisseurs configurés : Google, MiniMax et, aujourd’hui, ComfyUI configuré par workflow.
Pour les exécutions d’agent adossées à une session, OpenClaw démarre la génération musicale comme une
tâche d’arrière-plan, la suit dans le registre des tâches, puis réveille à nouveau l’agent
quand la piste est prête afin que l’agent puisse informer l’utilisateur et joindre l’audio
finalisé. Dans les discussions de groupe/canal qui utilisent une diffusion visible
uniquement via l’outil de messagerie, l’agent relaie le résultat via l’outil de messagerie.
Pour les exécutions d’agent adossées à une session, OpenClaw démarre la génération musicale comme une tâche en arrière-plan, la suit dans le registre des tâches, puis réveille de nouveau l’agent lorsque la piste est prête afin qu’il puisse prévenir l’utilisateur et joindre l’audio terminé. Dans les discussions de groupe/canal qui utilisent une livraison visible uniquement par l’outil de message, l’agent relaie le résultat via l’outil de message. Si l’agent de complétion écrit uniquement une réponse finale privée, OpenClaw utilise en recours un envoi direct au canal avec le média généré. Le réveil de complétion avertit explicitement l’agent que les réponses finales normales sont privées dans ces routes.
<Note>
L’outil partagé intégré n’apparaît que lorsqu’au moins un fournisseur de génération musicale
est disponible. Si vous ne voyez pas `music_generate` dans les outils de votre agent,
configurez `agents.defaults.musicGenerationModel` ou définissez une clé d’API de
fournisseur.
L’outil partagé intégré apparaît uniquement lorsqu’au moins un fournisseur de génération musicale est disponible. Si vous ne voyez pas `music_generate` dans les outils de votre agent, configurez `agents.defaults.musicGenerationModel` ou définissez une clé d’API de fournisseur.
</Note>
## Démarrage rapide
<Tabs>
<Tab title="Shared provider-backed">
<Tab title="Adossé à un fournisseur partagé">
<Steps>
<Step title="Configure auth">
Définissez une clé d’API pour au moins un fournisseur — par exemple
<Step title="Configurer l’authentification">
Définissez une clé d’API pour au moins un fournisseur, par exemple
`GEMINI_API_KEY` ou `MINIMAX_API_KEY`.
</Step>
<Step title="Pick a default model (optional)">
<Step title="Choisir un modèle par défaut (facultatif)">
```json5
{
agents: {
@ -54,30 +45,30 @@ fournisseur.
}
```
</Step>
<Step title="Ask the agent">
_"Generate an upbeat synthpop track about a night drive through a
neon city."_
<Step title="Demander à l’agent">
_« Génère une piste synthpop entraînante sur une virée de nuit dans une
ville néon. »_
L’agent appelle automatiquement `music_generate`. Aucune liste d’autorisation
d’outils n’est nécessaire.
L’agent appelle `music_generate` automatiquement. Aucune liste
d’autorisation d’outil n’est nécessaire.
</Step>
</Steps>
Pour les contextes synchrones directs sans exécution d’agent adossée à une session,
l’outil intégré bascule tout de même vers la génération en ligne et renvoie
l’outil intégré utilise toujours en recours une génération en ligne et renvoie
le chemin du média final dans le résultat de l’outil.
</Tab>
<Tab title="ComfyUI workflow">
<Tab title="Workflow ComfyUI">
<Steps>
<Step title="Configure the workflow">
<Step title="Configurer le workflow">
Configurez `plugins.entries.comfy.config.music` avec un workflow
JSON et des nœuds d’invite/sortie.
JSON et des nœuds de prompt/sortie.
</Step>
<Step title="Cloud auth (optional)">
<Step title="Authentification cloud (facultative)">
Pour Comfy Cloud, définissez `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`.
</Step>
<Step title="Call the tool">
<Step title="Appeler l’outil">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -86,7 +77,7 @@ fournisseur.
</Tab>
</Tabs>
Exemples d’invites :
Exemples de prompts :
```text
Generate a cinematic piano track with soft strings and no vocals.
@ -98,13 +89,13 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## Fournisseurs pris en charge
| Fournisseur | Modèle par défaut | Entrées de référence | Contrôles pris en charge | Auth |
| Fournisseur | Modèle par défaut | Entrées de référence | Contrôles pris en charge | Authentification |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Jusqu’à 1 image | Musique ou audio définis par workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| ComfyUI | `workflow` | Jusqu’à 1 image | Musique ou audio défini par le workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Jusqu’à 10 images | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Aucune | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` ou OAuth MiniMax |
### Matrice de capacités
### Matrice des fonctionnalités
Le contrat de mode explicite utilisé par `music_generate`, les tests de contrat et le
balayage live partagé :
@ -115,14 +106,14 @@ balayage live partagé :
| Google | ✓ | ✓ | 10 images | `generate`, `edit` |
| MiniMax | ✓ | — | Aucune | `generate` |
Utilisez `action: "list"` pour inspecter les fournisseurs et modèles partagés disponibles à
Utilisez `action: "list"` pour inspecter les fournisseurs partagés et modèles disponibles à
l’exécution :
```text
/tool music_generate action=list
```
Utilisez `action: "status"` pour inspecter la tâche musicale active adossée à une session :
Utilisez `action: "status"` pour inspecter la tâche musicale active adossée à la session :
```text
/tool music_generate action=status
@ -137,20 +128,20 @@ Exemple de génération directe :
## Paramètres de l’outil
<ParamField path="prompt" type="string" required>
Invite de génération musicale. Obligatoire pour `action: "generate"`.
Prompt de génération musicale. Obligatoire pour `action: "generate"`.
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` renvoie la tâche de session actuelle ; `"list"` inspecte les fournisseurs.
</ParamField>
<ParamField path="model" type="string">
Remplacement du fournisseur/modèle (par exemple `google/lyria-3-pro-preview`,
Remplacement du fournisseur/modèle (par ex. `google/lyria-3-pro-preview`,
`comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
Paroles facultatives lorsque le fournisseur prend en charge une entrée explicite de paroles.
Paroles facultatives lorsque le fournisseur prend en charge l’entrée explicite de paroles.
</ParamField>
<ParamField path="instrumental" type="boolean">
Demande une sortie uniquement instrumentale lorsque le fournisseur la prend en charge.
Demander une sortie uniquement instrumentale lorsque le fournisseur la prend en charge.
</ParamField>
<ParamField path="image" type="string">
Chemin ou URL d’une seule image de référence.
@ -168,45 +159,30 @@ Exemple de génération directe :
<ParamField path="timeoutMs" type="number">Délai d’expiration facultatif de la requête fournisseur en millisecondes. Les valeurs inférieures à 10000ms sont relevées à 10000ms et signalées dans le résultat de l’outil.</ParamField>
<Note>
Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw valide tout de même les
limites strictes, comme le nombre d’entrées, avant la soumission. Lorsqu’un fournisseur prend en charge
la durée mais utilise un maximum plus court que la valeur demandée, OpenClaw
ramène la durée à la valeur prise en charge la plus proche. Les indications facultatives vraiment non prises en charge
sont ignorées avec un avertissement lorsque le fournisseur ou le modèle sélectionné ne peut pas les honorer.
Les résultats d’outil indiquent les paramètres appliqués ; `details.normalization`
capture toute correspondance entre la demande et l’application.
Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw valide tout de même les limites strictes, comme le nombre d’entrées, avant l’envoi. Lorsqu’un fournisseur prend en charge la durée mais utilise un maximum plus court que la valeur demandée, OpenClaw limite à la durée prise en charge la plus proche. Les indications facultatives réellement non prises en charge sont ignorées avec un avertissement lorsque le fournisseur ou le modèle sélectionné ne peut pas les respecter. Les résultats d’outil signalent les paramètres appliqués ; `details.normalization` capture toute correspondance entre la valeur demandée et la valeur appliquée.
</Note>
## Comportement asynchrone
La génération musicale adossée à une session s’exécute comme une tâche d’arrière-plan :
La génération musicale adossée à une session s’exécute comme une tâche en arrière-plan :
- **Tâche d’arrière-plan :** `music_generate` crée une tâche d’arrière-plan, renvoie
immédiatement une réponse de démarrage/tâche, puis publie la piste finalisée plus tard dans
un message d’agent de suivi.
- **Prévention des doublons :** tant qu’une tâche est `queued` ou `running`, les appels
`music_generate` ultérieurs dans la même session renvoient le statut de la tâche au lieu de
démarrer une autre génération. Utilisez `action: "status"` pour vérifier explicitement.
- **Consultation du statut :** `openclaw tasks list` ou `openclaw tasks show <taskId>`
inspecte les statuts en file d’attente, en cours d’exécution et terminaux.
- **Réveil à la fin :** OpenClaw réinjecte un événement interne de fin
dans la même session afin que le modèle puisse rédiger lui-même le suivi destiné à l’utilisateur.
- **Indication d’invite :** les tours utilisateur/manuels ultérieurs dans la même session reçoivent une petite
indication d’exécution lorsqu’une tâche musicale est déjà en cours, afin que le modèle
n’appelle pas aveuglément `music_generate` à nouveau.
- **Repli sans session :** les contextes directs/locaux sans vraie session d’agent
s’exécutent en ligne et renvoient le résultat audio final dans le même tour.
- **Tâche en arrière-plan :** `music_generate` crée une tâche en arrière-plan, renvoie immédiatement une réponse de démarrage/tâche et publie plus tard la piste terminée dans un message de suivi de l’agent.
- **Prévention des doublons :** tant qu’une tâche est `queued` ou `running`, les appels ultérieurs à `music_generate` dans la même session renvoient l’état de la tâche au lieu de démarrer une autre génération. Utilisez `action: "status"` pour vérifier explicitement.
- **Consultation de l’état :** `openclaw tasks list` ou `openclaw tasks show <taskId>` inspecte les états en attente, en cours et terminaux.
- **Réveil de complétion :** OpenClaw injecte un événement de complétion interne dans la même session afin que le modèle puisse écrire lui-même le suivi destiné à l’utilisateur.
- **Indication de prompt :** les tours utilisateur/manuels ultérieurs dans la même session reçoivent une petite indication d’exécution lorsqu’une tâche musicale est déjà en cours, afin que le modèle n’appelle pas aveuglément `music_generate` de nouveau.
- **Recours sans session :** les contextes directs/locaux sans véritable session d’agent s’exécutent en ligne et renvoient le résultat audio final dans le même tour.
### Cycle de vie des tâches
| État | Signification |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | Tâche créée, en attente d’acceptation par le fournisseur. |
| `running` | Le fournisseur traite la demande (généralement de 30 secondes à 3 minutes selon le fournisseur et la durée). |
| `running` | Le fournisseur traite la tâche (généralement 30 secondes à 3 minutes selon le fournisseur et la durée). |
| `succeeded` | Piste prête ; l’agent se réveille et la publie dans la conversation. |
| `failed` | Erreur ou délai d’expiration du fournisseur ; l’agent se réveille avec les détails de l’erreur. |
Vérifiez le statut depuis la CLI :
Vérifiez l’état depuis la CLI :
```bash
openclaw tasks list
@ -235,15 +211,15 @@ openclaw tasks cancel <taskId>
OpenClaw essaie les fournisseurs dans cet ordre :
1. Paramètre `model` de l’appel d’outil (si l’agent en précise un).
1. Paramètre `model` de l’appel d’outil (si l’agent en spécifie un).
2. `musicGenerationModel.primary` depuis la configuration.
3. `musicGenerationModel.fallbacks` dans l’ordre.
4. Détection automatique utilisant uniquement les valeurs par défaut des fournisseurs adossés à l’authentification :
4. Détection automatique utilisant uniquement les valeurs par défaut des fournisseurs appuyées par l’authentification :
- fournisseur par défaut actuel en premier ;
- autres fournisseurs de génération musicale enregistrés dans l’ordre de leur identifiant de fournisseur.
- autres fournisseurs de génération musicale enregistrés par ordre d’identifiant de fournisseur.
Si un fournisseur échoue, le candidat suivant est essayé automatiquement. S’ils
échouent tous, l’erreur inclut les détails de chaque tentative.
Si un fournisseur échoue, le candidat suivant est essayé automatiquement. Si tous
échouent, l’erreur inclut les détails de chaque tentative.
Définissez `agents.defaults.mediaGenerationAutoProviderFallback: false` pour utiliser uniquement
les entrées explicites `model`, `primary` et `fallbacks`.
@ -252,42 +228,41 @@ les entrées explicites `model`, `primary` et `fallbacks`.
<AccordionGroup>
<Accordion title="ComfyUI">
Piloté par workflow et dépend du graphe configuré ainsi que du mappage des nœuds
pour les champs d’invite/sortie. Le plugin `comfy` intégré se branche sur
l’outil partagé `music_generate` via le registre des fournisseurs de
génération musicale.
Piloté par le workflow et dépend du graphe configuré ainsi que du mappage des nœuds
pour les champs d’invite/de sortie. Le plugin `comfy` fourni s’intègre à l’outil
partagé `music_generate` via le registre des fournisseurs de génération musicale.
</Accordion>
<Accordion title="Google (Lyria 3)">
Utilise la génération par lot Lyria 3. Le flux intégré actuel prend en charge
l’invite, un texte de paroles facultatif et des images de référence facultatives.
Utilise la génération par lots de Lyria 3. Le flux fourni actuel prend en charge
l’invite, le texte de paroles facultatif et les images de référence facultatives.
</Accordion>
<Accordion title="MiniMax">
Utilise l’endpoint par lot `music_generation`. Prend en charge l’invite, les
paroles facultatives, le mode instrumental, le pilotage de durée et la sortie mp3 via
l’authentification par clé d’API `minimax` ou OAuth `minimax-portal`.
Utilise le point de terminaison par lots `music_generation`. Prend en charge l’invite, les
paroles facultatives, le mode instrumental, le pilotage de la durée et la sortie mp3 via
l’authentification par clé API `minimax` ou OAuth `minimax-portal`.
</Accordion>
</AccordionGroup>
## Choisir le bon chemin
- **Adossé à un fournisseur partagé** lorsque vous voulez la sélection de modèle, le basculement
de fournisseur et le flux intégré asynchrone de tâche/statut.
- **Appuyé par un fournisseur partagé** lorsque vous voulez la sélection de modèle, le basculement
entre fournisseurs et le flux asynchrone intégré de tâches/états.
- **Chemin Plugin (ComfyUI)** lorsque vous avez besoin d’un graphe de workflow personnalisé ou d’un
fournisseur qui ne fait pas partie de la capacité musicale intégrée partagée.
fournisseur qui ne fait pas partie de la capacité musicale partagée fournie.
Si vous déboguez un comportement propre à ComfyUI, consultez
[ComfyUI](/fr/providers/comfy). Si vous déboguez un comportement de fournisseur partagé,
[ComfyUI](/fr/providers/comfy). Si vous déboguez le comportement d’un fournisseur partagé,
commencez par [Google (Gemini)](/fr/providers/google) ou
[MiniMax](/fr/providers/minimax).
## Modes de capacité des fournisseurs
Le contrat partagé de génération musicale prend en charge des déclarations de mode explicites :
Le contrat partagé de génération musicale prend en charge les déclarations de mode explicites :
- `generate` pour la génération uniquement par invite.
- `generate` pour la génération à partir d’une invite seule.
- `edit` lorsque la requête inclut une ou plusieurs images de référence.
Les nouvelles implémentations de fournisseurs doivent privilégier des blocs de mode explicites :
Les nouvelles implémentations de fournisseurs doivent préférer les blocs de mode explicites :
```typescript
capabilities: {
@ -313,7 +288,7 @@ de manière déterministe.
## Tests live
Couverture live à activer explicitement pour les fournisseurs intégrés partagés :
Couverture live à activation explicite pour les fournisseurs partagés inclus :
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -326,26 +301,26 @@ pnpm test:live:media music
```
Ce fichier live charge les variables d’environnement de fournisseur manquantes depuis `~/.profile`, préfère
par défaut les clés d’API live/env aux profils d’authentification stockés, et exécute à la fois
la couverture `generate` et la couverture `edit` déclarée lorsque le fournisseur active le mode
par défaut les clés API live/env aux profils d’authentification stockés, et exécute la couverture
`generate` ainsi que la couverture `edit` déclarée lorsque le fournisseur active le mode
édition. Couverture actuelle :
- `google` : `generate` plus `edit`
- `minimax` : `generate` uniquement
- `comfy` : couverture live Comfy séparée, pas le balayage partagé des fournisseurs
- `comfy` : couverture live Comfy distincte, pas le balayage partagé des fournisseurs
Couverture live à activer explicitement pour le chemin musical ComfyUI intégré :
Couverture live facultative pour le parcours musical ComfyUI intégré :
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Le fichier live de Comfy couvre également les workflows d’image et de vidéo Comfy lorsque ces
Le fichier live Comfy couvre également les flux de travail d’image et de vidéo comfy lorsque ces
sections sont configurées.
## Connexe
## Articles connexes
- [Tâches en arrière-plan](/fr/automation/tasks) — suivi des tâches pour les exécutions détachées de `music_generate`
- [Tâches en arrière-plan](/fr/automation/tasks) — suivi des tâches pour les exécutions `music_generate` détachées
- [ComfyUI](/fr/providers/comfy)
- [Référence de configuration](/fr/gateway/config-agents#agent-defaults) — configuration `musicGenerationModel`
- [Google (Gemini)](/fr/providers/google)

332
docs/fr/tools/slash-commands.md
View File

@ -1,47 +1,47 @@
---
read_when:
- Utiliser ou configurer les commandes de chat
- Utilisation ou configuration des commandes de chat
- Débogage du routage des commandes ou des autorisations
sidebarTitle: Slash commands
summary: 'Commandes slash : texte ou natives, configuration et commandes prises en charge'
title: Commandes slash
x-i18n:
generated_at: "2026-05-04T02:26:46Z"
generated_at: "2026-05-05T06:19:19Z"
model: gpt-5.5
provider: openai
source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84
source_hash: 8a0234bd94cafe242fc692a5b9d457047e483e2a434cc92ab26046e6ddec55ce
source_path: tools/slash-commands.md
workflow: 16
---
Les commandes sont gérées par le Gateway. La plupart des commandes doivent être envoyées comme un message **autonome** qui commence par `/`. La commande de chat bash réservée à l’hôte utilise `! <cmd>` (avec `/bash <cmd>` comme alias).
Commands are handled by the Gateway. Most commands must be sent as a **standalone** message that starts with `/`. The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
Lorsqu’une conversation ou un fil est lié à une session ACP, le texte de suivi normal est routé vers ce harnais ACP. Les commandes de gestion du Gateway restent locales : `/acp ...` atteint toujours le gestionnaire de commandes ACP d’OpenClaw, et `/status` ainsi que `/unfocus` restent locaux chaque fois que la gestion des commandes est activée pour la surface.
When a conversation or thread is bound to an ACP session, normal follow-up text routes to that ACP harness. Gateway management commands still stay local: `/acp ...` always reaches the OpenClaw ACP command handler, and `/status` plus `/unfocus` stay local whenever command handling is enabled for the surface.
Il existe deux systèmes liés :
There are two related systems:
<AccordionGroup>
<Accordion title="Commandes">
Messages `/...` autonomes.
<Accordion title="Commands">
Standalone `/...` messages.
</Accordion>
<Accordion title="Directives">
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- Les directives sont retirées du message avant que le modèle ne le voie.
- Dans les messages de chat normaux (qui ne contiennent pas uniquement des directives), elles sont traitées comme des « indices en ligne » et ne conservent **pas** les paramètres de session.
- Dans les messages contenant uniquement des directives (le message ne contient que des directives), elles sont conservées dans la session et reçoivent une réponse d’accusé de réception.
- Les directives ne sont appliquées que pour les **expéditeurs autorisés**. Si `commands.allowFrom` est défini, c’est la seule liste d’autorisation utilisée ; sinon, l’autorisation vient des listes d’autorisation/appairage du canal plus `commands.useAccessGroups`. Les expéditeurs non autorisés voient les directives traitées comme du texte brut.
- Directives are stripped from the message before the model sees it.
- In normal chat messages (not directive-only), they are treated as "inline hints" and do **not** persist session settings.
- In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
- Directives are only applied for **authorized senders**. If `commands.allowFrom` is set, it is the only allowlist used; otherwise authorization comes from channel allowlists/pairing plus `commands.useAccessGroups`. Unauthorized senders see directives treated as plain text.
</Accordion>
<Accordion title="Raccourcis en ligne">
Expéditeurs présents sur liste d’autorisation/autorisés uniquement : `/help`, `/commands`, `/status`, `/whoami` (`/id`).
<Accordion title="Inline shortcuts">
Allowlisted/authorized senders only: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
Ils s’exécutent immédiatement, sont retirés avant que le modèle ne voie le message, et le texte restant continue dans le flux normal.
They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
</Accordion>
</AccordionGroup>
## Configuration
## Config
```json5
{
@ -69,238 +69,238 @@ Il existe deux systèmes liés :
```
<ParamField path="commands.text" type="boolean" default="true">
Active l’analyse de `/...` dans les messages de chat. Sur les surfaces sans commandes natives (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), les commandes textuelles fonctionnent toujours même si vous définissez cette valeur sur `false`.
Enables parsing `/...` in chat messages. On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), text commands still work even if you set this to `false`.
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
Enregistre les commandes natives. Automatique : activé pour Discord/Telegram ; désactivé pour Slack (jusqu’à ce que vous ajoutiez des commandes slash) ; ignoré pour les fournisseurs sans prise en charge native. Définissez `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` pour remplacer par fournisseur (booléen ou `"auto"`). Sur Discord, `false` ignore l’enregistrement et le nettoyage des commandes slash au démarrage ; les commandes précédemment enregistrées peuvent rester visibles jusqu’à ce que vous les supprimiez de l’application Discord. Les commandes Slack sont gérées dans l’application Slack et ne sont pas supprimées automatiquement.
Registers native commands. Auto: on for Discord/Telegram; off for Slack (until you add slash commands); ignored for providers without native support. Set `channels.discord.commands.native`, `channels.telegram.commands.native`, or `channels.slack.commands.native` to override per provider (bool or `"auto"`). On Discord, `false` skips slash-command registration and cleanup during startup; previously registered commands may remain visible until you remove them from the Discord app. Slack commands are managed in the Slack app and are not removed automatically.
</ParamField>
Sur Discord, les spécifications de commandes natives peuvent inclure `descriptionLocalizations`, qu’OpenClaw publie comme `description_localizations` Discord et inclut dans les comparaisons de rapprochement.
On Discord, native command specs may include `descriptionLocalizations`, which OpenClaw publishes as Discord `description_localizations` and includes in reconcile comparisons.
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
Enregistre nativement les commandes **skill** lorsque c’est pris en charge. Automatique : activé pour Discord/Telegram ; désactivé pour Slack (Slack nécessite de créer une commande slash par skill). Définissez `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` pour remplacer par fournisseur (booléen ou `"auto"`).
Registers **skill** commands natively when supported. Auto: on for Discord/Telegram; off for Slack (Slack requires creating a slash command per skill). Set `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, or `channels.slack.commands.nativeSkills` to override per provider (bool or `"auto"`).
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
Active `! <cmd>` pour exécuter des commandes shell de l’hôte (`/bash <cmd>` est un alias ; nécessite les listes d’autorisation `tools.elevated`).
Enables `! <cmd>` to run host shell commands (`/bash <cmd>` is an alias; requires `tools.elevated` allowlists).
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
Contrôle combien de temps bash attend avant de passer en mode arrière-plan (`0` lance immédiatement en arrière-plan).
Controls how long bash waits before switching to background mode (`0` backgrounds immediately).
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
Active `/config` (lit/écrit `openclaw.json`).
Enables `/config` (reads/writes `openclaw.json`).
</ParamField>
<ParamField path="commands.mcp" type="boolean" default="false">
Active `/mcp` (lit/écrit la configuration MCP gérée par OpenClaw sous `mcp.servers`).
Enables `/mcp` (reads/writes OpenClaw-managed MCP config under `mcp.servers`).
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
Active `/plugins` (découverte/état des plugins plus contrôles d’installation et d’activation/désactivation).
Enables `/plugins` (plugin discovery/status plus install + enable/disable controls).
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
Active `/debug` (remplacements uniquement à l’exécution).
Enables `/debug` (runtime-only overrides).
</ParamField>
<ParamField path="commands.restart" type="boolean" default="true">
Active `/restart` plus les actions d’outil de redémarrage du gateway.
Enables `/restart` plus gateway restart tool actions.
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
Définit la liste d’autorisation explicite du propriétaire pour les surfaces de commandes/outils réservées au propriétaire. Il s’agit du compte opérateur humain qui peut approuver les actions dangereuses et exécuter des commandes telles que `/diagnostics`, `/export-trajectory` et `/config`. Elle est distincte de `commands.allowFrom` et de l’accès par appairage en DM.
Sets the explicit owner allowlist for owner-only command/tool surfaces. This is the human operator account that can approve dangerous actions and run commands such as `/diagnostics`, `/export-trajectory`, and `/config`. It is separate from `commands.allowFrom` and from DM pairing access.
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
Par canal : impose que les commandes réservées au propriétaire nécessitent **l’identité du propriétaire** pour s’exécuter sur cette surface. Lorsque la valeur est `true`, l’expéditeur doit soit correspondre à un candidat propriétaire résolu (par exemple une entrée dans `commands.ownerAllowFrom` ou des métadonnées de propriétaire natives du fournisseur), soit disposer de la portée interne `operator.admin` sur un canal de messages interne. Une entrée générique dans `allowFrom` du canal, ou une liste de candidats propriétaires vide/non résolue, n’est **pas** suffisante — les commandes réservées au propriétaire échouent fermées sur ce canal. Laissez cette option désactivée si vous voulez que les commandes réservées au propriétaire soient limitées uniquement par `ownerAllowFrom` et les listes d’autorisation de commandes standard.
Per-channel: makes owner-only commands require **owner identity** to run on that surface. When `true`, the sender must either match a resolved owner candidate (for example an entry in `commands.ownerAllowFrom` or provider-native owner metadata) or hold internal `operator.admin` scope on an internal message channel. A wildcard entry in channel `allowFrom`, or an empty/unresolved owner-candidate list, is **not** sufficient — owner-only commands fail closed on that channel. Leave this off if you want owner-only commands gated only by `ownerAllowFrom` and the standard command allowlists.
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
Contrôle la façon dont les identifiants de propriétaire apparaissent dans l’invite système.
Controls how owner ids appear in the system prompt.
</ParamField>
<ParamField path="commands.ownerDisplaySecret" type="string">
Définit éventuellement le secret HMAC utilisé lorsque `commands.ownerDisplay="hash"`.
Optionally sets the HMAC secret used when `commands.ownerDisplay="hash"`.
</ParamField>
<ParamField path="commands.allowFrom" type="object">
Liste d’autorisation par fournisseur pour l’autorisation des commandes. Lorsqu’elle est configurée, elle est la seule source d’autorisation pour les commandes et les directives (les listes d’autorisation/appairage du canal et `commands.useAccessGroups` sont ignorés). Utilisez `"*"` comme valeur globale par défaut ; les clés propres au fournisseur la remplacent.
Per-provider allowlist for command authorization. When configured, it is the only authorization source for commands and directives (channel allowlists/pairing and `commands.useAccessGroups` are ignored). Use `"*"` for a global default; provider-specific keys override it.
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
Applique les listes d’autorisation/politiques pour les commandes lorsque `commands.allowFrom` n’est pas défini.
Enforces allowlists/policies for commands when `commands.allowFrom` is not set.
</ParamField>
## Liste des commandes
## Command list
Source de vérité actuelle :
Current source-of-truth:
- les commandes intégrées au noyau proviennent de `src/auto-reply/commands-registry.shared.ts`
- les commandes dock générées proviennent de `src/auto-reply/commands-registry.data.ts`
- les commandes plugin proviennent des appels plugin `registerCommand()`
- la disponibilité réelle sur votre gateway dépend toujours des indicateurs de configuration, de la surface du canal et des plugins installés/activés
- core built-ins come from `src/auto-reply/commands-registry.shared.ts`
- generated dock commands come from `src/auto-reply/commands-registry.data.ts`
- plugin commands come from plugin `registerCommand()` calls
- actual availability on your gateway still depends on config flags, channel surface, and installed/enabled plugins
### Commandes intégrées au noyau
### Core built-in commands
<AccordionGroup>
<Accordion title="Sessions et exécutions">
- `/new [model]` démarre une nouvelle session ; `/reset` est l’alias de réinitialisation.
- Control UI intercepte `/new` saisi pour créer une nouvelle session de tableau de bord et y basculer ; `/reset` saisi exécute toujours la réinitialisation sur place du Gateway.
- `/reset soft [message]` conserve la transcription actuelle, supprime les identifiants de session du backend CLI réutilisés et relance sur place le chargement du démarrage/de l’invite système.
- `/compact [instructions]` compacte le contexte de session. Voir [Compaction](/fr/concepts/compaction).
- `/stop` interrompt l’exécution actuelle.
- `/session idle <duration|off>` et `/session max-age <duration|off>` gèrent l’expiration de la liaison de fil.
- `/export-session [path]` exporte la session actuelle en HTML. Alias : `/export`.
- `/export-trajectory [path]` demande une approbation d’exécution, puis exporte un [lot de trajectoire](/fr/tools/trajectory) JSONL pour la session actuelle. Utilisez-le lorsque vous avez besoin de la chronologie des invites, des outils et de la transcription pour une session OpenClaw. Dans les chats de groupe, l’invite d’approbation et le résultat d’exportation sont envoyés au propriétaire en privé. Alias : `/trajectory`.
<Accordion title="Sessions and runs">
- `/new [model]` starts a new session; `/reset` is the reset alias.
- Control UI intercepts typed `/new` to create and switch to a fresh dashboard session; typed `/reset` still runs the Gateway's in-place reset.
- `/reset soft [message]` keeps the current transcript, drops reused CLI backend session ids, and reruns startup/system-prompt loading in-place.
- `/compact [instructions]` compacts the session context. See [Compaction](/fr/concepts/compaction).
- `/stop` aborts the current run.
- `/session idle <duration|off>` and `/session max-age <duration|off>` manage thread-binding expiry.
- `/export-session [path]` exports the current session to HTML. Alias: `/export`.
- `/export-trajectory [path]` asks for exec approval, then exports a JSONL [trajectory bundle](/fr/tools/trajectory) for the current session. Use it when you need the prompt, tool, and transcript timeline for one OpenClaw session. In group chats, the approval prompt and export result go to the owner privately. Alias: `/trajectory`.
</Accordion>
<Accordion title="Contrôles du modèle et de l’exécution">
- `/think <level>` définit le niveau de réflexion. Les options proviennent du profil fournisseur du modèle actif ; les niveaux courants sont `off`, `minimal`, `low`, `medium` et `high`, avec des niveaux personnalisés tels que `xhigh`, `adaptive`, `max`, ou le binaire `on` uniquement lorsqu’ils sont pris en charge. Alias : `/thinking`, `/t`.
- `/verbose on|off|full` active ou désactive la sortie détaillée. Alias : `/v`.
- `/trace on|off` active ou désactive la sortie de trace plugin pour la session actuelle.
- `/fast [status|on|off]` affiche ou définit le mode rapide.
- `/reasoning [on|off|stream]` active ou désactive la visibilité du raisonnement. Alias : `/reason`.
- `/elevated [on|off|ask|full]` active ou désactive le mode élevé. Alias : `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` affiche ou définit les valeurs par défaut d’exécution.
- `/model [name|#|status]` affiche ou définit le modèle.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` liste les fournisseurs configurés/disponibles avec authentification ou les modèles d’un fournisseur ; ajoutez `all` pour parcourir le catalogue complet de ce fournisseur.
- `/queue <mode>` gère le comportement de la file (`steer`, ancien `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) plus des options comme `debounce:0.5s cap:25 drop:summarize` ; `/queue default` ou `/queue reset` efface le remplacement de session. Voir [File de commandes](/fr/concepts/queue) et [File de pilotage](/fr/concepts/queue-steering).
- `/steer <message>` injecte des consignes dans l’exécution active pour la session actuelle, indépendamment du mode `/queue`. Cela ne démarre pas une nouvelle exécution lorsque la session est inactive. Alias : `/tell`. Voir [Piloter](/fr/tools/steer).
<Accordion title="Model and run controls">
- `/think <level>` sets the thinking level. Options come from the active model's provider profile; common levels are `off`, `minimal`, `low`, `medium`, and `high`, with custom levels such as `xhigh`, `adaptive`, `max`, or binary `on` only where supported. Aliases: `/thinking`, `/t`.
- `/verbose on|off|full` toggles verbose output. Alias: `/v`.
- `/trace on|off` toggles plugin trace output for the current session.
- `/fast [status|on|off]` shows or sets fast mode.
- `/reasoning [on|off|stream]` toggles reasoning visibility. Alias: `/reason`.
- `/elevated [on|off|ask|full]` toggles elevated mode. Alias: `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` shows or sets exec defaults.
- `/model [name|#|status]` shows or sets the model.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lists configured/auth-available providers or models for a provider; add `all` to browse that provider's full catalog.
- `/queue <mode>` manages queue behavior (`steer`, legacy `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) plus options like `debounce:0.5s cap:25 drop:summarize`; `/queue default` or `/queue reset` clears the session override. See [Command queue](/fr/concepts/queue) and [Steering queue](/fr/concepts/queue-steering).
- `/steer <message>` injects guidance into the active run for the current session, independent of `/queue` mode. It does not start a new run when the session is idle. Alias: `/tell`. See [Steer](/fr/tools/steer).
</Accordion>
<Accordion title="Découverte et état">
- `/help` affiche le résumé d’aide court.
- `/commands` affiche le catalogue de commandes généré.
- `/tools [compact|verbose]` affiche ce que l’agent actuel peut utiliser maintenant.
- `/status` affiche l’état d’exécution/d’exécution runtime, y compris les libellés `Execution`/`Runtime` et l’utilisation/quota du fournisseur lorsqu’ils sont disponibles.
- `/diagnostics [note]` est le flux de rapport de support réservé au propriétaire pour les bugs du Gateway et les exécutions du harnais Codex. Il demande une approbation d’exécution explicite à chaque fois avant d’exécuter `openclaw gateway diagnostics export --json` ; n’approuvez pas les diagnostics avec une règle d’autorisation globale. Après approbation, il envoie un rapport prêt à coller avec le chemin du lot local, le résumé du manifeste, les notes de confidentialité et les identifiants de session pertinents. Dans les chats de groupe, l’invite d’approbation et le rapport sont envoyés au propriétaire en privé. Lorsque la session active utilise le harnais OpenAI Codex, la même approbation envoie également les retours Codex pertinents aux serveurs OpenAI, et la réponse terminée liste les identifiants de session OpenClaw, les identifiants de fil Codex et les commandes `codex resume <thread-id>`. Voir [Exportation des diagnostics](/fr/gateway/diagnostics).
- `/crestodian <request>` exécute l’assistant de configuration et de réparation Crestodian depuis un DM propriétaire.
- `/tasks` liste les tâches en arrière-plan actives/récentes pour la session actuelle.
- `/context [list|detail|json]` explique comment le contexte est assemblé.
- `/whoami` affiche votre identifiant d’expéditeur. Alias : `/id`.
- `/usage off|tokens|full|cost` contrôle le pied de page d’utilisation par réponse ou imprime un résumé local des coûts.
<Accordion title="Discovery and status">
- `/help` shows the short help summary.
- `/commands` shows the generated command catalog.
- `/tools [compact|verbose]` shows what the current agent can use right now.
- `/status` shows execution/runtime status, Gateway and system uptime, plus provider usage/quota when available.
- `/diagnostics [note]` is the owner-only support-report flow for Gateway bugs and Codex harness runs. It asks for explicit exec approval every time before running `openclaw gateway diagnostics export --json`; do not approve diagnostics with an allow-all rule. After approval, it sends a pasteable report with the local bundle path, manifest summary, privacy notes, and relevant session ids. In group chats, the approval prompt and report go to the owner privately. When the active session uses the OpenAI Codex harness, the same approval also sends relevant Codex feedback to OpenAI servers and the completed reply lists the OpenClaw session ids, Codex thread ids, and `codex resume <thread-id>` commands. See [Diagnostics Export](/fr/gateway/diagnostics).
- `/crestodian <request>` runs the Crestodian setup and repair helper from an owner DM.
- `/tasks` lists active/recent background tasks for the current session.
- `/context [list|detail|json]` explains how context is assembled.
- `/whoami` shows your sender id. Alias: `/id`.
- `/usage off|tokens|full|cost` controls the per-response usage footer or prints a local cost summary.
</Accordion>
<Accordion title="Skills, listes d’autorisation, approbations">
- `/skill <name> [input]` exécute un skill par nom.
- `/allowlist [list|add|remove] ...` gère les entrées de liste d’autorisation. Texte uniquement.
- `/approve <id> <decision>` résout les invites d’approbation d’exécution.
- `/btw <question>` pose une question secondaire sans modifier le contexte futur de la session. Alias : `/side`. Voir [BTW](/fr/tools/btw).
<Accordion title="Skills, allowlists, approvals">
- `/skill <name> [input]` runs a skill by name.
- `/allowlist [list|add|remove] ...` manages allowlist entries. Text-only.
- `/approve <id> <decision>` resolves exec approval prompts.
- `/btw <question>` asks a side question without changing future session context. Alias: `/side`. See [BTW](/fr/tools/btw).
</Accordion>
<Accordion title="Sous-agents et ACP">
- `/subagents list|kill|log|info|send|steer|spawn` gère les exécutions de sous-agents pour la session actuelle.
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gère les sessions ACP et les options d’exécution.
- `/focus <target>` lie le fil Discord actuel ou le sujet/la conversation Telegram à une cible de session.
- `/unfocus` supprime la liaison actuelle.
- `/focus <target>` associe le fil Discord actuel ou le sujet/la conversation Telegram à une cible de session.
- `/unfocus` supprime l’association actuelle.
- `/agents` liste les agents liés au fil pour la session actuelle.
- `/kill <id|#|all>` interrompt un sous-agent en cours d’exécution ou tous les sous-agents.
- `/subagents steer <id|#> <message>` envoie des instructions à un sous-agent en cours d’exécution. Voir [Piloter](/fr/tools/steer).
- `/kill <id|#|all>` interrompt un sous-agent en cours d’exécution, ou tous.
- `/subagents steer <id|#> <message>` envoie une directive à un sous-agent en cours d’exécution. Voir [Orienter](/fr/tools/steer).
</Accordion>
<Accordion title="Écritures réservées au propriétaire et administration">
- `/config show|get|set|unset` lit ou écrit `openclaw.json`. Réservé au propriétaire. Nécessite `commands.config: true`.
- `/mcp show|get|set|unset` lit ou écrit la configuration de serveur MCP gérée par OpenClaw sous `mcp.servers`. Réservé au propriétaire. Nécessite `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspecte ou modifie l’état des plugins. `/plugin` est un alias. Les écritures sont réservées au propriétaire. Nécessite `commands.plugins: true`.
- `/debug show|set|unset|reset` gère les remplacements de configuration valables uniquement à l’exécution. Réservé au propriétaire. Nécessite `commands.debug: true`.
- `/restart` redémarre OpenClaw lorsque cette option est activée. Par défaut : activé ; définissez `commands.restart: false` pour la désactiver.
- `/mcp show|get|set|unset` lit ou écrit la configuration des serveurs MCP gérés par OpenClaw sous `mcp.servers`. Réservé au propriétaire. Nécessite `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspecte ou modifie l’état des plugins. `/plugin` est un alias. Écritures réservées au propriétaire. Nécessite `commands.plugins: true`.
- `/debug show|set|unset|reset` gère les remplacements de configuration uniquement à l’exécution. Réservé au propriétaire. Nécessite `commands.debug: true`.
- `/restart` redémarre OpenClaw lorsque cette option est activée. Par défaut : activé ; définissez `commands.restart: false` pour le désactiver.
- `/send on|off|inherit` définit la politique d’envoi. Réservé au propriétaire.
</Accordion>
<Accordion title="Voix, TTS, contrôle du canal">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` contrôle TTS. Voir [TTS](/fr/tools/tts).
- `/activation mention|always` définit le mode d’activation de groupe.
- `/bash <command>` exécute une commande shell sur l’hôte. Texte uniquement. Alias : `! <command>`. Nécessite `commands.bash: true` plus les listes d’autorisation `tools.elevated`.
- `/bash <command>` exécute une commande shell hôte. Texte uniquement. Alias : `! <command>`. Nécessite `commands.bash: true` ainsi que les listes d’autorisation `tools.elevated`.
- `!poll [sessionId]` vérifie une tâche bash en arrière-plan.
- `!stop [sessionId]` arrête une tâche bash en arrière-plan.
</Accordion>
</AccordionGroup>
### Commandes de dock générées
### Commandes d’ancrage générées
Les commandes de dock basculent la route de réponse de la session actuelle vers un autre
Les commandes d’ancrage basculent la route de réponse de la session actuelle vers un autre
canal lié. Voir [Ancrage de canal](/fr/concepts/channel-docking) pour la configuration,
des exemples et le dépannage.
Les commandes de dock sont générées à partir des plugins de canal prenant en charge les commandes natives. Ensemble intégré actuel :
Les commandes d’ancrage sont générées à partir de plugins de canal prenant en charge les commandes natives. Ensemble actuellement intégré :
- `/dock-discord` (alias : `/dock_discord`)
- `/dock-mattermost` (alias : `/dock_mattermost`)
- `/dock-slack` (alias : `/dock_slack`)
- `/dock-telegram` (alias : `/dock_telegram`)
Utilisez les commandes de dock depuis une conversation directe pour basculer la route de réponse de la session actuelle vers un autre canal lié. L’agent conserve le même contexte de session, mais les réponses futures pour cette session sont envoyées au pair de canal sélectionné.
Utilisez les commandes d’ancrage depuis une conversation directe pour basculer la route de réponse de la session actuelle vers un autre canal lié. L’agent conserve le même contexte de session, mais les réponses futures de cette session sont transmises au pair de canal sélectionné.
Les commandes de dock nécessitent `session.identityLinks`. L’expéditeur source et le pair cible doivent appartenir au même groupe d’identité, par exemple `["telegram:123", "discord:456"]`. Si un utilisateur Telegram avec l’identifiant `123` envoie `/dock_discord`, OpenClaw stocke `lastChannel: "discord"` et `lastTo: "456"` sur la session active. Si l’expéditeur n’est pas lié à un pair Discord, la commande répond avec une indication de configuration au lieu de basculer vers la conversation normale.
Les commandes d’ancrage nécessitent `session.identityLinks`. L’expéditeur source et le pair cible doivent se trouver dans le même groupe d’identité, par exemple `["telegram:123", "discord:456"]`. Si un utilisateur Telegram avec l’id `123` envoie `/dock_discord`, OpenClaw stocke `lastChannel: "discord"` et `lastTo: "456"` sur la session active. Si l’expéditeur n’est lié à aucun pair Discord, la commande répond avec une indication de configuration au lieu de revenir à la discussion normale.
L’ancrage modifie uniquement la route de session active. Il ne crée pas de comptes de canal, n’accorde pas d’accès, ne contourne pas les listes d’autorisation de canal et ne déplace pas l’historique de transcription vers une autre session. Utilisez `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou une autre commande de dock générée pour changer de nouveau la route.
L’ancrage modifie uniquement la route de session active. Il ne crée pas de comptes de canal, n’accorde pas d’accès, ne contourne pas les listes d’autorisation de canal et ne déplace pas l’historique de transcription vers une autre session. Utilisez `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou une autre commande d’ancrage générée pour changer à nouveau de route.
### Commandes des plugins intégrés
### Commandes de plugins intégrés
Les plugins intégrés peuvent ajouter davantage de commandes slash. Commandes intégrées actuelles dans ce dépôt :
Les plugins intégrés peuvent ajouter davantage de commandes slash. Commandes actuellement intégrées dans ce dépôt :
- `/dreaming [on|off|status|help]` active ou désactive Dreaming de mémoire. Voir [Dreaming](/fr/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gère le flux d’association/configuration d’appareil. Voir [Association](/fr/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arme temporairement les commandes de nœud téléphone à haut risque.
- `/voice status|list [limit]|set <voiceId|name>` gère la configuration de voix Talk. Sur Discord, le nom de commande native est `/talkvoice`.
- `/dreaming [on|off|status|help]` active ou désactive le Dreaming de mémoire. Voir [Dreaming](/fr/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gère le flux d’appairage/de configuration de l’appareil. Voir [Appairage](/fr/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arme temporairement les commandes de nœud de téléphone à haut risque.
- `/voice status|list [limit]|set <voiceId|name>` gère la configuration de voix Talk. Sur Discord, le nom de commande natif est `/talkvoice`.
- `/card ...` envoie des préréglages de cartes enrichies LINE. Voir [LINE](/fr/channels/line).
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspecte et contrôle le harnais de serveur d’application Codex intégré. Voir [Harnais Codex](/fr/plugins/codex-harness).
- Commandes réservées à QQBot :
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspecte et contrôle le harnais de serveur d’app Codex intégré. Voir [Harnais Codex](/fr/plugins/codex-harness).
- Commandes propres à QQBot :
- `/bot-ping`
- `/bot-version`
- `/bot-help`
- `/bot-upgrade`
- `/bot-logs`
### Commandes de Skills dynamiques
### Commandes dynamiques de Skills
Les Skills invocables par l’utilisateur sont également exposées comme commandes slash :
- `/skill <name> [input]` fonctionne toujours comme point d’entrée générique.
- Les Skills peuvent également apparaître comme commandes directes, par exemple `/prose`, lorsque la Skill/le Plugin les enregistre.
- L’enregistrement des commandes de Skill natives est contrôlé par `commands.nativeSkills` et `channels.<provider>.commands.nativeSkills`.
- Les spécifications de commande peuvent fournir `descriptionLocalizations` pour les surfaces natives prenant en charge les descriptions localisées, y compris Discord.
- Les Skills peuvent aussi apparaître comme commandes directes telles que `/prose` lorsque la compétence/le plugin les enregistre.
- L’enregistrement natif des commandes de Skills est contrôlé par `commands.nativeSkills` et `channels.<provider>.commands.nativeSkills`.
- Les spécifications de commande peuvent fournir `descriptionLocalizations` pour les surfaces natives qui prennent en charge les descriptions localisées, y compris Discord.
<AccordionGroup>
<Accordion title="Notes sur les arguments et l’analyseur">
- Les commandes acceptent un `:` facultatif entre la commande et les arguments (par ex. `/think: high`, `/send: on`, `/help:`).
- Les commandes acceptent un `:` facultatif entre la commande et les arguments (par exemple `/think: high`, `/send: on`, `/help:`).
- `/new <model>` accepte un alias de modèle, `provider/model` ou un nom de fournisseur (correspondance approximative) ; en l’absence de correspondance, le texte est traité comme le corps du message.
- Pour une ventilation complète de l’utilisation par fournisseur, utilisez `openclaw status --usage`.
- Pour une répartition complète de l’utilisation par fournisseur, utilisez `openclaw status --usage`.
- `/allowlist add|remove` nécessite `commands.config=true` et respecte `configWrites` du canal.
- Dans les canaux multicomptes, `/allowlist --account <id>` ciblant la configuration et `/config set channels.<provider>.accounts.<id>...` respectent également `configWrites` du compte cible.
- `/usage` contrôle le pied de page d’utilisation par réponse ; `/usage cost` affiche un récapitulatif local des coûts à partir des journaux de session OpenClaw.
- Dans les canaux multi-comptes, `/allowlist --account <id>` ciblé sur la configuration et `/config set channels.<provider>.accounts.<id>...` respectent aussi `configWrites` du compte cible.
- `/usage` contrôle le pied de page d’utilisation par réponse ; `/usage cost` affiche un résumé local des coûts à partir des journaux de session OpenClaw.
- `/restart` est activé par défaut ; définissez `commands.restart: false` pour le désactiver.
- `/plugins install <spec>` accepte les mêmes spécifications de Plugin que `openclaw plugins install` : chemin/archive local(e), package npm, `git:<repo>` ou `clawhub:<pkg>`, puis demande un redémarrage du Gateway, car les modules sources du Plugin ont changé.
- `/plugins install <spec>` accepte les mêmes spécifications de Plugin que `openclaw plugins install` : chemin/archive local, package npm, `git:<repo>` ou `clawhub:<pkg>`, puis demande un redémarrage du Gateway, car les modules source du Plugin ont changé.
- `/plugins enable|disable` met à jour la configuration du Plugin et déclenche le rechargement des plugins du Gateway pour les nouveaux tours d’agent.
</Accordion>
<Accordion title="Comportement propre au canal">
- Commande native réservée à Discord : `/vc join|leave|status` contrôle les canaux vocaux (non disponible sous forme de texte). `join` nécessite une guilde et un canal vocal/scène sélectionné. Nécessite `channels.discord.voice` et les commandes natives.
- Les commandes de liaison de fil Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) nécessitent l’activation effective des liaisons de fil (`session.threadBindings.enabled` et/ou `channels.discord.threadBindings.enabled`).
- Référence des commandes ACP et comportement à l’exécution : [Agents ACP](/fr/tools/acp-agents).
- Commande native propre à Discord : `/vc join|leave|status` contrôle les canaux vocaux (non disponible sous forme de texte). `join` nécessite un serveur et un canal vocal/de scène sélectionné. Nécessite `channels.discord.voice` et les commandes natives.
- Les commandes Discord de liaison aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) nécessitent l’activation effective des liaisons de fil (`session.threadBindings.enabled` et/ou `channels.discord.threadBindings.enabled`).
- Référence des commandes ACP et comportement d’exécution : [agents ACP](/fr/tools/acp-agents).
</Accordion>
<Accordion title="Sécurité verbose / trace / fast / reasoning">
- `/verbose` est destiné au débogage et à une visibilité accrue ; gardez-le **désactivé** en usage normal.
- `/trace` est plus restreint que `/verbose` : il révèle uniquement les lignes de trace/débogage appartenant au Plugin et laisse désactivé le bavardage verbeux normal des outils.
- `/fast on|off` conserve un remplacement de session. Utilisez l’option `inherit` de l’interface Sessions pour l’effacer et revenir aux valeurs par défaut de configuration.
- `/fast` dépend du fournisseur : OpenAI/OpenAI Codex le mappe vers `service_tier=priority` sur les points de terminaison Responses natifs, tandis que les requêtes Anthropic publiques directes, y compris le trafic authentifié par OAuth envoyé à `api.anthropic.com`, le mappent vers `service_tier=auto` ou `standard_only`. Voir [OpenAI](/fr/providers/openai) et [Anthropic](/fr/providers/anthropic).
- Les résumés d’échec d’outil restent affichés lorsqu’ils sont pertinents, mais le texte détaillé de l’échec n’est inclus que lorsque `/verbose` vaut `on` ou `full`.
- `/reasoning`, `/verbose` et `/trace` sont risqués dans les contextes de groupe : ils peuvent révéler un raisonnement interne, une sortie d’outil ou des diagnostics de Plugin que vous n’aviez pas l’intention d’exposer. Préférez les laisser désactivés, surtout dans les conversations de groupe.
- `/verbose` est destiné au débogage et à une visibilité supplémentaire ; gardez-le **désactivé** en utilisation normale.
- `/trace` est plus restreint que `/verbose` : il révèle uniquement les lignes de trace/débogage appartenant aux plugins et garde désactivé le bavardage verbose normal des outils.
- `/fast on|off` conserve un remplacement de session. Utilisez l’option `inherit` de l’interface Sessions pour l’effacer et revenir aux valeurs par défaut de la configuration.
- `/fast` est propre au fournisseur : OpenAI/OpenAI Codex le mappe à `service_tier=priority` sur les points de terminaison Responses natifs, tandis que les requêtes Anthropic publiques directes, y compris le trafic authentifié par OAuth envoyé à `api.anthropic.com`, le mappent à `service_tier=auto` ou `standard_only`. Voir [OpenAI](/fr/providers/openai) et [Anthropic](/fr/providers/anthropic).
- Les résumés d’échec des outils restent affichés lorsqu’ils sont pertinents, mais le texte détaillé de l’échec n’est inclus que lorsque `/verbose` vaut `on` ou `full`.
- `/reasoning`, `/verbose` et `/trace` sont risqués dans les contextes de groupe : ils peuvent révéler un raisonnement interne, une sortie d’outil ou des diagnostics de Plugin que vous n’aviez pas l’intention d’exposer. Préférez les laisser désactivés, en particulier dans les discussions de groupe.
</Accordion>
<Accordion title="Changement de modèle">
- `/model` conserve immédiatement le nouveau modèle de session.
- Si l’agent est inactif, la prochaine exécution l’utilise tout de suite.
- Si une exécution est déjà active, OpenClaw marque un changement à chaud comme en attente et ne redémarre dans le nouveau modèle qu’à un point de nouvelle tentative propre.
- Si l’activité d’outil ou la sortie de réponse a déjà commencé, le changement en attente peut rester en file jusqu’à une opportunité de nouvelle tentative ultérieure ou jusqu’au prochain tour utilisateur.
- Dans la TUI locale, `/crestodian [request]` revient de la TUI d’agent normale à Crestodian. C’est distinct du mode de secours des canaux de messages et cela n’accorde pas d’autorité de configuration à distance.
- Si l’agent est inactif, la prochaine exécution l’utilise immédiatement.
- Si une exécution est déjà active, OpenClaw marque un changement en direct comme en attente et ne redémarre dans le nouveau modèle qu’à un point de nouvelle tentative propre.
- Si l’activité des outils ou la sortie de réponse a déjà commencé, le changement en attente peut rester en file jusqu’à une occasion de nouvelle tentative ultérieure ou jusqu’au prochain tour utilisateur.
- Dans la TUI locale, `/crestodian [request]` revient de la TUI d’agent normale à Crestodian. C’est distinct du mode de secours des canaux de message et cela n’accorde pas d’autorité distante sur la configuration.
</Accordion>
<Accordion title="Chemin rapide et raccourcis en ligne">
- **Chemin rapide :** les messages contenant uniquement une commande provenant d’expéditeurs autorisés sont traités immédiatement (contournement de la file + du modèle).
- **Garde par mention de groupe :** les messages contenant uniquement une commande provenant d’expéditeurs autorisés contournent les exigences de mention.
- **Raccourcis en ligne (expéditeurs autorisés uniquement) :** certaines commandes fonctionnent également lorsqu’elles sont intégrées dans un message normal et sont supprimées avant que le modèle voie le texte restant.
<Accordion title="Chemin rapide et raccourcis intégrés">
- **Chemin rapide :** les messages contenant uniquement une commande envoyés par des expéditeurs sur liste d’autorisation sont traités immédiatement (contournement de la file + modèle).
- **Garde par mention de groupe :** les messages contenant uniquement une commande envoyés par des expéditeurs sur liste d’autorisation contournent les exigences de mention.
- **Raccourcis intégrés (expéditeurs sur liste d’autorisation uniquement) :** certaines commandes fonctionnent aussi lorsqu’elles sont intégrées dans un message normal et sont supprimées avant que le modèle voie le texte restant.
- Exemple : `hey /status` déclenche une réponse d’état, et le texte restant poursuit le flux normal.
- Actuellement : `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- Les messages non autorisés contenant uniquement une commande sont ignorés silencieusement, et les jetons `/...` en ligne sont traités comme du texte brut.
- Les messages non autorisés contenant uniquement une commande sont ignorés silencieusement, et les jetons `/...` intégrés sont traités comme du texte brut.
</Accordion>
<Accordion title="Commandes de Skills et arguments natifs">
- **Commandes de Skills :** les Skills `user-invocable` sont exposées comme commandes slash. Les noms sont normalisés en `a-z0-9_` (32 caractères max) ; les collisions reçoivent des suffixes numériques (par ex. `_2`).
- **Commandes de Skills :** les Skills `user-invocable` sont exposées comme commandes slash. Les noms sont assainis en `a-z0-9_` (32 caractères max) ; les collisions reçoivent des suffixes numériques (par exemple `_2`).
- `/skill <name> [input]` exécute une Skill par nom (utile lorsque les limites des commandes natives empêchent les commandes par Skill).
- Par défaut, les commandes de Skill sont transmises au modèle comme une requête normale.
- Les Skills peuvent éventuellement déclarer `command-dispatch: tool` pour acheminer la commande directement vers un outil (déterministe, sans modèle).
- Par défaut, les commandes de Skills sont transmises au modèle comme une requête normale.
- Les Skills peuvent éventuellement déclarer `command-dispatch: tool` pour router la commande directement vers un outil (déterministe, sans modèle).
- Exemple : `/prose` (Plugin OpenProse) — voir [OpenProse](/fr/prose).
- **Arguments de commande native :** Discord utilise la saisie semi-automatique pour les options dynamiques (et des menus de boutons lorsque vous omettez des arguments requis). Telegram et Slack affichent un menu de boutons lorsqu’une commande prend en charge des choix et que vous omettez l’argument. Les choix dynamiques sont résolus par rapport au modèle de session cible, de sorte que les options propres au modèle, comme les niveaux `/think`, suivent le remplacement `/model` de cette session.
- **Arguments de commande natifs :** Discord utilise l’autocomplétion pour les options dynamiques (et des menus de boutons lorsque vous omettez des arguments requis). Telegram et Slack affichent un menu de boutons lorsqu’une commande prend en charge des choix et que vous omettez l’argument. Les choix dynamiques sont résolus par rapport au modèle de session cible ; les options propres au modèle, telles que les niveaux `/think`, suivent donc le remplacement `/model` de cette session.
</Accordion>
</AccordionGroup>
@ -312,18 +312,18 @@ Les Skills invocables par l’utilisateur sont également exposées comme comman
- `/tools` par défaut est compact et optimisé pour un balayage rapide.
- `/tools verbose` ajoute de courtes descriptions.
- Les surfaces de commandes natives qui prennent en charge les arguments exposent le même commutateur de mode que `compact|verbose`.
- Les résultats sont propres à la session ; changer d’agent, de canal, de fil, d’autorisation d’expéditeur ou de modèle peut donc modifier la sortie.
- `/tools` inclut les outils réellement accessibles à l’exécution, y compris les outils de base, les outils de plugins connectés et les outils appartenant au canal.
- Les résultats sont limités à la session ; changer d’agent, de canal, de fil, d’autorisation d’expéditeur ou de modèle peut donc modifier la sortie.
- `/tools` inclut les outils réellement accessibles à l’exécution, y compris les outils du cœur, les outils de plugins connectés et les outils appartenant au canal.
Pour modifier les profils et les remplacements, utilisez le panneau Tools de l’interface Control UI ou les surfaces de configuration/catalogue, au lieu de traiter `/tools` comme un catalogue statique.
Pour modifier les profils et les remplacements, utilisez le panneau Outils de l’interface de contrôle ou les surfaces de configuration/catalogue au lieu de traiter `/tools` comme un catalogue statique.
## Surfaces d’utilisation (ce qui s’affiche où)
- **Utilisation/quota du fournisseur** (exemple : « Claude 80 % restants ») apparaît dans `/status` pour le fournisseur de modèle actuel lorsque le suivi de l’utilisation est activé. OpenClaw normalise les fenêtres des fournisseurs en `% restant` ; pour MiniMax, les champs de pourcentage indiquant uniquement le restant sont inversés avant l’affichage, et les réponses `model_remains` privilégient l’entrée du modèle de chat plus une étiquette d’abonnement marquée par modèle.
- **Lignes de jetons/cache** dans `/status` peuvent se replier sur la dernière entrée d’utilisation de transcript lorsque l’instantané de session en direct est peu fourni. Les valeurs en direct non nulles existantes restent prioritaires, et le repli sur le transcript peut aussi récupérer l’étiquette du modèle d’exécution actif ainsi qu’un total plus élevé orienté prompt lorsque les totaux stockés sont absents ou plus petits.
- **Exécution vs runtime :** `/status` indique `Execution` pour le chemin de sandbox effectif et `Runtime` pour ce qui exécute réellement la session : `OpenClaw Pi Default`, `OpenAI Codex`, un backend CLI ou un backend ACP.
- **Jetons/coût par réponse** est contrôlé par `/usage off|tokens|full` (ajouté aux réponses normales).
- `/model status` concerne les **modèles/authentification/points de terminaison**, pas l’utilisation.
- **Utilisation/quota du fournisseur** (exemple : "Claude 80% left") apparaît dans `/status` pour le fournisseur de modèle actuel lorsque le suivi de l’utilisation est activé. OpenClaw normalise les fenêtres fournisseur en `% left` ; pour MiniMax, les champs de pourcentage indiquant uniquement le reste sont inversés avant l’affichage, et les réponses `model_remains` privilégient l’entrée du modèle de chat plus une étiquette de forfait marquée par modèle.
- **Lignes de tokens/cache** dans `/status` peuvent se rabattre sur la dernière entrée d’utilisation de la transcription lorsque l’instantané de session en direct est pauvre. Les valeurs en direct non nulles existantes restent prioritaires, et le repli sur la transcription peut aussi récupérer l’étiquette du modèle d’exécution actif ainsi qu’un total plus grand orienté prompt lorsque les totaux stockés sont absents ou plus petits.
- **Exécution vs Runtime :** `/status` signale `Execution` pour le chemin de sandbox effectif et `Runtime` pour ce qui exécute réellement la session : `OpenClaw Pi Default`, `OpenAI Codex`, un backend CLI ou un backend ACP.
- **Tokens/coût par réponse** est contrôlé par `/usage off|tokens|full` (ajouté aux réponses normales).
- `/model status` concerne les **modèles/l’authentification/les endpoints**, pas l’utilisation.
## Sélection de modèle (`/model`)
@ -340,16 +340,16 @@ Exemples :
/model status
```
Notes :
Remarques :
- `/model` et `/model list` affichent un sélecteur compact et numéroté (famille de modèles + fournisseurs disponibles).
- Sur Discord, `/model` et `/models` ouvrent un sélecteur interactif avec des listes déroulantes de fournisseur et de modèle, plus une étape Envoyer.
- `/model` et `/model list` affichent un sélecteur compact numéroté (famille de modèles + fournisseurs disponibles).
- Sur Discord, `/model` et `/models` ouvrent un sélecteur interactif avec des menus déroulants de fournisseur et de modèle, plus une étape Submit.
- `/model <#>` sélectionne depuis ce sélecteur (et privilégie le fournisseur actuel lorsque c’est possible).
- `/model status` affiche la vue détaillée, y compris le point de terminaison du fournisseur configuré (`baseUrl`) et le mode d’API (`api`) lorsqu’ils sont disponibles.
- `/model status` affiche la vue détaillée, y compris l’endpoint du fournisseur configuré (`baseUrl`) et le mode API (`api`) lorsqu’ils sont disponibles.
## Overrides de débogage
## Remplacements de débogage
`/debug` vous permet de définir des overrides de configuration **uniquement pour le runtime** (mémoire, pas disque). Réservé au propriétaire. Désactivé par défaut ; activez avec `commands.debug: true`.
`/debug` vous permet de définir des remplacements de configuration **uniquement à l’exécution** (mémoire, pas disque). Réservé au propriétaire. Désactivé par défaut ; activez avec `commands.debug: true`.
Exemples :
@ -362,12 +362,12 @@ Exemples :
```
<Note>
Les overrides s’appliquent immédiatement aux nouvelles lectures de configuration, mais ne sont **pas** écrits dans `openclaw.json`. Utilisez `/debug reset` pour effacer tous les overrides et revenir à la configuration sur disque.
Les remplacements s’appliquent immédiatement aux nouvelles lectures de configuration, mais n’écrivent **pas** dans `openclaw.json`. Utilisez `/debug reset` pour effacer tous les remplacements et revenir à la configuration sur disque.
</Note>
## Sortie de trace Plugin
`/trace` vous permet d’activer ou de désactiver les **lignes de trace/débogage des plugins limitées à la session** sans activer le mode verbeux complet.
`/trace` vous permet d’activer ou de désactiver des **lignes de trace/débogage Plugin limitées à la session** sans activer le mode verbeux complet.
Exemples :
@ -377,14 +377,14 @@ Exemples :
/trace off
```
Notes :
Remarques :
- `/trace` sans argument affiche l’état actuel de la trace de session.
- `/trace on` active les lignes de trace des plugins pour la session actuelle.
- `/trace` sans argument affiche l’état de trace actuel de la session.
- `/trace on` active les lignes de trace Plugin pour la session actuelle.
- `/trace off` les désactive à nouveau.
- Les lignes de trace des plugins peuvent apparaître dans `/status` et sous forme de message de diagnostic de suivi après la réponse normale de l’assistant.
- `/trace` ne remplace pas `/debug` ; `/debug` gère toujours les overrides de configuration uniquement pour le runtime.
- `/trace` ne remplace pas `/verbose` ; la sortie verbeuse normale des outils/statuts relève toujours de `/verbose`.
- Les lignes de trace Plugin peuvent apparaître dans `/status` et comme message de diagnostic de suivi après la réponse normale de l’assistant.
- `/trace` ne remplace pas `/debug` ; `/debug` gère toujours les remplacements de configuration uniquement à l’exécution.
- `/trace` ne remplace pas `/verbose` ; la sortie verbeuse normale des outils/états relève toujours de `/verbose`.
## Mises à jour de configuration
@ -401,7 +401,7 @@ Exemples :
```
<Note>
La configuration est validée avant écriture ; les changements invalides sont rejetés. Les mises à jour `/config` persistent après les redémarrages.
La configuration est validée avant l’écriture ; les modifications invalides sont rejetées. Les mises à jour `/config` persistent entre les redémarrages.
</Note>
## Mises à jour MCP
@ -418,12 +418,12 @@ Exemples :
```
<Note>
`/mcp` stocke la configuration dans la configuration OpenClaw, pas dans les paramètres de projet détenus par Pi. Les adaptateurs runtime décident quels transports sont réellement exécutables.
`/mcp` stocke la configuration dans la configuration OpenClaw, pas dans les paramètres de projet appartenant à Pi. Les adaptateurs d’exécution décident quels transports sont réellement exécutables.
</Note>
## Mises à jour des plugins
## Mises à jour Plugin
`/plugins` permet aux opérateurs d’inspecter les plugins découverts et de basculer leur activation dans la configuration. Les flux en lecture seule peuvent utiliser `/plugin` comme alias. Désactivé par défaut ; activez avec `commands.plugins: true`.
`/plugins` permet aux opérateurs d’inspecter les Plugins découverts et d’activer ou désactiver leur activation dans la configuration. Les flux en lecture seule peuvent utiliser `/plugin` comme alias. Désactivé par défaut ; activez avec `commands.plugins: true`.
Exemples :
@ -436,10 +436,10 @@ Exemples :
```
<Note>
- `/plugins list` et `/plugins show` utilisent la découverte réelle des plugins dans l’espace de travail actuel plus la configuration sur disque.
- `/plugins list` et `/plugins show` utilisent la vraie découverte de Plugins sur l’espace de travail actuel plus la configuration sur disque.
- `/plugins install` installe depuis ClawHub, npm, git, des répertoires locaux et des archives.
- `/plugins enable|disable` met uniquement à jour la configuration des plugins ; il n’installe ni ne désinstalle les plugins.
- Les changements d’activation et de désactivation rechargent à chaud les surfaces runtime des plugins du Gateway pour les nouveaux tours d’agent ; l’installation demande un redémarrage du Gateway, car les modules source des plugins ont changé.
- `/plugins enable|disable` met uniquement à jour la configuration Plugin ; cela n’installe ni ne désinstalle les Plugins.
- Les changements d’activation et de désactivation rechargent à chaud les surfaces d’exécution Plugin du Gateway pour les nouveaux tours d’agent ; l’installation demande un redémarrage du Gateway parce que les modules sources Plugin ont changé.
</Note>
@ -447,7 +447,7 @@ Exemples :
<AccordionGroup>
<Accordion title="Sessions par surface">
- **Commandes textuelles** s’exécutent dans la session de chat normale (les messages privés partagent `main`, les groupes ont leur propre session).
- **Commandes texte** s’exécutent dans la session de chat normale (les DM partagent `main`, les groupes ont leur propre session).
- **Commandes natives** utilisent des sessions isolées :
- Discord : `agent:<agentId>:discord:slash:<userId>`
- Slack : `agent:<agentId>:slack:slash:<userId>` (préfixe configurable via `channels.slack.slashCommand.sessionPrefix`)
@ -458,7 +458,7 @@ Exemples :
<Accordion title="Spécificités Slack">
`channels.slack.slashCommand` reste pris en charge pour une seule commande de style `/openclaw`. Si vous activez `commands.native`, vous devez créer une commande slash Slack par commande intégrée (mêmes noms que `/help`). Les menus d’arguments de commande pour Slack sont fournis sous forme de boutons Block Kit éphémères.
Exception native Slack : enregistrez `/agentstatus` (pas `/status`) car Slack réserve `/status`. Le texte `/status` fonctionne toujours dans les messages Slack.
Exception native Slack : enregistrez `/agentstatus` (pas `/status`) parce que Slack réserve `/status`. Le texte `/status` fonctionne toujours dans les messages Slack.
</Accordion>
</AccordionGroup>
@ -471,9 +471,9 @@ Contrairement au chat normal :
- elle utilise la session actuelle comme contexte d’arrière-plan,
- elle s’exécute comme un appel ponctuel séparé **sans outil**,
- elle ne modifie pas le contexte futur de la session,
- elle n’est pas écrite dans l’historique du transcript,
- elle est fournie comme résultat secondaire en direct au lieu d’un message d’assistant normal.
- elle ne modifie pas le futur contexte de session,
- elle n’est pas écrite dans l’historique de transcription,
- elle est fournie comme résultat secondaire en direct plutôt que comme message d’assistant normal.
Cela rend `/btw` utile lorsque vous voulez une clarification temporaire pendant que la tâche principale continue.
@ -484,7 +484,7 @@ Exemple :
/side what changed while the main run continued?
```
Consultez [Questions secondaires BTW](/fr/tools/btw) pour le comportement complet et les détails de l’UX client.
Voir [Questions secondaires BTW](/fr/tools/btw) pour le comportement complet et les détails d’UX client.
## Connexe

406
docs/fr/tools/video-generation.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Générer des vidéos via l’agent
- Génération de vidéos via l’agent
- Configuration des fournisseurs et des modèles de génération vidéo
- Comprendre les paramètres de l’outil video_generate
sidebarTitle: Video generation
summary: Générez des vidéos via video_generate à partir de références textuelles, d’images ou de vidéos sur 16 moteurs de fournisseurs.
title: Génération de vidéo
summary: Générez des vidéos via video_generate à partir de références textuelles, d’images ou de vidéos sur 16 backends de fournisseurs
title: Génération de vidéos
x-i18n:
generated_at: "2026-05-05T01:51:24Z"
generated_at: "2026-05-05T06:19:40Z"
model: gpt-5.5
provider: openai
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_hash: a86a820cc9f27baf4b17954d7ded7c2b7ff9eb456e7e75c3b2e7a7653cd675fd
source_path: tools/video-generation.md
workflow: 16
---
Les agents OpenClaw peuvent générer des vidéos à partir de prompts textuels, d’images de référence ou de
vidéos existantes. Seize backends fournisseurs sont pris en charge, chacun avec
différentes options de modèles, modes d’entrée et ensembles de fonctionnalités. L’agent choisit
automatiquement le bon fournisseur en fonction de votre configuration et des clés API
Les agents OpenClaw peuvent générer des vidéos à partir d’invites textuelles, d’images de référence ou de
vidéos existantes. Seize backends de fournisseurs sont pris en charge, chacun avec
différentes options de modèles, différents modes d’entrée et différents ensembles de fonctionnalités. L’agent choisit le
bon fournisseur automatiquement selon votre configuration et les clés d’API
disponibles.
<Note>
L’outil `video_generate` apparaît uniquement lorsqu’au moins un fournisseur de génération
vidéo est disponible. Si vous ne le voyez pas dans les outils de votre agent, définissez une
clé API de fournisseur ou configurez `agents.defaults.videoGenerationModel`.
clé d’API de fournisseur ou configurez `agents.defaults.videoGenerationModel`.
</Note>
OpenClaw traite la génération vidéo comme trois modes d’exécution :
OpenClaw traite la génération vidéo selon trois modes d’exécution :
- `generate` — requêtes texte-vers-vidéo sans média de référence.
- `imageToVideo` — la requête inclut une ou plusieurs images de référence.
- `videoToVideo` — la requête inclut une ou plusieurs vidéos de référence.
Les fournisseurs peuvent prendre en charge n’importe quel sous-ensemble de ces modes. L’outil valide le
mode actif avant l’envoi et indique les modes pris en charge dans `action=list`.
mode actif avant l’envoi et signale les modes pris en charge dans `action=list`.
## Démarrage rapide
<Steps>
<Step title="Configurer l’authentification">
Définissez une clé API pour n’importe quel fournisseur pris en charge :
Définissez une clé d’API pour n’importe quel fournisseur pris en charge :
```bash
export GEMINI_API_KEY="your-key"
@ -53,10 +53,10 @@ mode actif avant l’envoi et indique les modes pris en charge dans `action=list
```
</Step>
<Step title="Demander à l’agent">
> Générez une vidéo cinématographique de 5 secondes montrant un homard sympathique surfant au coucher du soleil.
> Générez une vidéo cinématographique de 5 secondes d’un homard amical qui surfe au coucher du soleil.
L’agent appelle `video_generate` automatiquement. Aucune liste d’autorisation d’outil
n’est nécessaire.
L’agent appelle `video_generate` automatiquement. Aucune liste d’autorisation
d’outil n’est nécessaire.
</Step>
</Steps>
@ -66,37 +66,37 @@ mode actif avant l’envoi et indique les modes pris en charge dans `action=list
La génération vidéo est asynchrone. Lorsque l’agent appelle `video_generate` dans une
session :
1. OpenClaw soumet la requête au fournisseur et renvoie immédiatement un identifiant de tâche.
2. Le fournisseur traite la tâche en arrière-plan (généralement de 30 secondes à 5 minutes selon le fournisseur et la résolution).
3. Lorsque la vidéo est prête, OpenClaw réveille la même session avec un événement interne de fin d’exécution.
1. OpenClaw envoie la requête au fournisseur et renvoie immédiatement un identifiant de tâche.
2. Le fournisseur traite la tâche en arrière-plan (généralement de 30 secondes à plusieurs minutes selon le fournisseur et la résolution ; les fournisseurs lents adossés à une file d’attente peuvent s’exécuter jusqu’au délai d’expiration configuré).
3. Lorsque la vidéo est prête, OpenClaw réveille la même session avec un événement interne d’achèvement.
4. L’agent informe l’utilisateur et joint la vidéo terminée. Dans les discussions de groupe/canal
qui utilisent une livraison visible uniquement via l’outil de messagerie, l’agent relaie le
résultat par l’outil de messagerie au lieu de laisser OpenClaw le publier directement.
qui utilisent une livraison visible uniquement via l’outil de message, l’agent relaie le
résultat via l’outil de message au lieu qu’OpenClaw le publie directement.
Lorsqu’une tâche est en cours, les appels `video_generate` en double dans la même
Pendant qu’une tâche est en cours, les appels `video_generate` en double dans la même
session renvoient l’état actuel de la tâche au lieu de démarrer une autre
génération. Utilisez `openclaw tasks list` ou `openclaw tasks show <taskId>` pour
vérifier la progression depuis la CLI.
En dehors des exécutions d’agent adossées à une session (par exemple, les appels directs d’outils),
l’outil revient à la génération en ligne et renvoie le chemin du média final
l’outil revient à la génération en ligne et renvoie le chemin final du média
dans le même tour.
Les fichiers vidéo générés sont enregistrés dans le stockage média géré par OpenClaw lorsque
le fournisseur renvoie des octets. La limite d’enregistrement par défaut des vidéos générées suit
Les fichiers vidéo générés sont enregistrés dans le stockage multimédia géré par OpenClaw lorsque
le fournisseur renvoie des octets. Le plafond d’enregistrement par défaut des vidéos générées suit
la limite des médias vidéo, et `agents.defaults.mediaMaxMb` l’augmente pour
les rendus plus volumineux. Lorsqu’un fournisseur renvoie aussi une URL de sortie hébergée, OpenClaw
les rendus plus volumineux. Lorsqu’un fournisseur renvoie également une URL de sortie hébergée, OpenClaw
peut livrer cette URL au lieu de faire échouer la tâche si la persistance locale
rejette un fichier trop volumineux.
### Cycle de vie des tâches
### Cycle de vie d’une tâche
| État | Signification |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `queued` | Tâche créée, en attente d’acceptation par le fournisseur. |
| `running` | Le fournisseur traite la tâche (généralement de 30 secondes à 5 minutes selon le fournisseur et la résolution). |
| `succeeded` | Vidéo prête ; l’agent se réveille et la publie dans la conversation. |
| `failed` | Erreur ou expiration de délai du fournisseur ; l’agent se réveille avec les détails de l’erreur. |
| État | Signification |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `queued` | Tâche créée, en attente d’acceptation par le fournisseur. |
| `running` | Le fournisseur traite la tâche (généralement de 30 secondes à plusieurs minutes selon le fournisseur et la résolution). |
| `succeeded` | Vidéo prête ; l’agent se réveille et la publie dans la conversation. |
| `failed` | Erreur du fournisseur ou délai d’expiration ; l’agent se réveille avec les détails de l’erreur. |
Vérifiez l’état depuis la CLI :
@ -107,36 +107,36 @@ openclaw tasks cancel <taskId>
```
Si une tâche vidéo est déjà `queued` ou `running` pour la session actuelle,
`video_generate` renvoie l’état de la tâche existante au lieu d’en démarrer une
nouvelle. Utilisez `action: "status"` pour vérifier explicitement sans déclencher une nouvelle
`video_generate` renvoie l’état de la tâche existante au lieu d’en démarrer une nouvelle.
Utilisez `action: "status"` pour vérifier explicitement sans déclencher une nouvelle
génération.
## Fournisseurs pris en charge
| Fournisseur | Modèle par défaut | Texte | Réf. image | Réf. vidéo | Authentification |
| --------------------- | ------------------------------- | :---: | --------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Oui (URL distante) | Oui (URL distante) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Jusqu’à 2 images (modèles I2V uniquement ; première + dernière image) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Jusqu’à 2 images (première + dernière image via le rôle) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Jusqu’à 9 images de référence | Jusqu’à 3 vidéos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 image | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 image ; jusqu’à 9 avec Seedance reference-to-video | Jusqu’à 3 vidéos avec Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 image | 1 vidéo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 image | — | `MINIMAX_API_KEY` ou MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 image | 1 vidéo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Jusqu’à 4 images (première/dernière image ou références) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Oui (URL distante) | Oui (URL distante) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 image | 1 vidéo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 image | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 image (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 image de première frame ou jusqu’à 7 `reference_image`s | 1 vidéo | `XAI_API_KEY` |
| Fournisseur | Modèle par défaut | Texte | Réf. image | Réf. vidéo | Authentification |
| --------------------- | --------------------------------- | :---: | --------------------------------------------------- | --------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Oui (URL distante) | Oui (URL distante) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Jusqu’à 2 images (modèles I2V uniquement ; première + dernière image) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Jusqu’à 2 images (première + dernière image via le rôle) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Jusqu’à 9 images de référence | Jusqu’à 3 vidéos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 image | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 image ; jusqu’à 9 avec Seedance reference-to-video | Jusqu’à 3 vidéos avec Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 image | 1 vidéo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 image | — | `MINIMAX_API_KEY` ou OAuth MiniMax |
| OpenAI | `sora-2` | ✓ | 1 image | 1 vidéo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Jusqu’à 4 images (première/dernière image ou références) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Oui (URL distante) | Oui (URL distante) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 image | 1 vidéo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 image | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 image (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 image de première image ou jusqu’à 7 `reference_image`s | 1 vidéo | `XAI_API_KEY` |
Certains fournisseurs acceptent des variables d’environnement de clé API supplémentaires ou alternatives. Consultez
Certains fournisseurs acceptent des variables d’environnement de clé d’API supplémentaires ou alternatives. Consultez
les [pages des fournisseurs](#related) individuelles pour plus de détails.
Exécutez `video_generate action=list` pour inspecter les fournisseurs, modèles et
modes d’exécution disponibles au moment de l’exécution.
Exécutez `video_generate action=list` pour inspecter les fournisseurs, les modèles et
les modes d’exécution disponibles au moment de l’exécution.
### Matrice des capacités
@ -145,167 +145,166 @@ le balayage live partagé :
| Fournisseur | `generate` | `imageToVideo` | `videoToVideo` | Voies live partagées aujourd’hui |
| ----------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré car ce fournisseur nécessite des URL vidéo `http(s)` distantes |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré parce que ce fournisseur nécessite des URL vidéo `http(s)` distantes |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Non inclus dans le balayage partagé ; la couverture propre aux workflows se trouve dans les tests Comfy |
| DeepInfra | ✓ | — | — | `generate` ; les schémas vidéo DeepInfra natifs sont texte-vers-vidéo dans le contrat groupé |
| ComfyUI | ✓ | ✓ | — | Non inclus dans le balayage partagé ; la couverture propre au workflow réside avec les tests Comfy |
| DeepInfra | ✓ | — | — | `generate` ; les schémas vidéo DeepInfra natifs sont texte-vers-vidéo dans le contrat intégré |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` uniquement lors de l’utilisation de Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré car le balayage Gemini/Veo actuel adossé à un tampon n’accepte pas cette entrée |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré parce que le balayage Gemini/Veo actuel adossé à des tampons n’accepte pas cette entrée |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré car ce chemin d’organisation/d’entrée nécessite actuellement un accès inpaint/remix côté fournisseur |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré parce que cette organisation/ce chemin d’entrée nécessite actuellement un accès inpaint/remix côté fournisseur |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré car ce fournisseur nécessite des URL vidéo `http(s)` distantes |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré parce que ce fournisseur nécessite des URL vidéo `http(s)` distantes |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` s’exécute uniquement lorsque le modèle sélectionné est `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate` ; `imageToVideo` partagé ignoré car le `veo3` groupé est texte uniquement et le `kling` groupé nécessite une URL d’image distante |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré car ce fournisseur nécessite actuellement une URL MP4 distante |
| Vydra | ✓ | ✓ | — | `generate` ; `imageToVideo` partagé ignoré parce que `veo3` intégré est texte uniquement et que `kling` intégré nécessite une URL d’image distante |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo` ; `videoToVideo` ignoré parce que ce fournisseur nécessite actuellement une URL MP4 distante |
## Paramètres de l’outil
### Obligatoire
### Requis
<ParamField path="prompt" type="string" required>
Description textuelle de la vidéo à générer. Obligatoire pour `action: "generate"`.
Description textuelle de la vidéo à générer. Requis pour `action: "generate"`.
</ParamField>
### Entrées de contenu
<ParamField path="image" type="string">Image de référence unique (chemin ou URL).</ParamField>
<ParamField path="images" type="string[]">Plusieurs images de référence (jusqu’à 9).</ParamField>
<ParamField path="images" type="string[]">Images de référence multiples (jusqu'à 9).</ParamField>
<ParamField path="imageRoles" type="string[]">
Indications de rôle optionnelles par position, parallèles à la liste d’images combinée.
Indications facultatives de rôle par position, parallèles à la liste d'images combinée.
Valeurs canoniques : `first_frame`, `last_frame`, `reference_image`.
</ParamField>
<ParamField path="video" type="string">Vidéo de référence unique (chemin ou URL).</ParamField>
<ParamField path="videos" type="string[]">Plusieurs vidéos de référence (jusqu’à 4).</ParamField>
<ParamField path="videos" type="string[]">Vidéos de référence multiples (jusqu'à 4).</ParamField>
<ParamField path="videoRoles" type="string[]">
Indications de rôle optionnelles par position, parallèles à la liste de vidéos combinée.
Indications facultatives de rôle par position, parallèles à la liste de vidéos combinée.
Valeur canonique : `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
Audio de référence unique (chemin ou URL). Utilisé pour la musique de fond ou comme
Audio de référence unique (chemin ou URL). Utilisé pour la musique de fond ou la
référence vocale lorsque le fournisseur prend en charge les entrées audio.
</ParamField>
<ParamField path="audioRefs" type="string[]">Plusieurs audios de référence (jusqu’à 3).</ParamField>
<ParamField path="audioRefs" type="string[]">Audios de référence multiples (jusqu'à 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
Indications de rôle optionnelles par position, parallèles à la liste audio combinée.
Indications facultatives de rôle par position, parallèles à la liste audio combinée.
Valeur canonique : `reference_audio`.
</ParamField>
<Note>
Les indications de rôle sont transmises telles quelles au fournisseur. Les valeurs canoniques proviennent de
l’union `VideoGenerationAssetRole`, mais les fournisseurs peuvent accepter des chaînes
de rôle supplémentaires. Les tableaux `*Roles` ne doivent pas contenir plus d’entrées que la
liste de références correspondante ; les erreurs de décalage d’une position échouent avec une erreur claire.
Utilisez une chaîne vide pour laisser un emplacement non défini. Pour xAI, définissez chaque rôle d’image sur
`reference_image` pour utiliser son mode de génération `reference_images` ; omettez le
rôle ou utilisez `first_frame` pour une image-vers-vidéo avec une seule image.
Les indications de rôle sont transmises au fournisseur telles quelles. Les valeurs canoniques proviennent de
l'union `VideoGenerationAssetRole`, mais les fournisseurs peuvent accepter d'autres
chaînes de rôle. Les tableaux `*Roles` ne doivent pas comporter plus d'entrées que la
liste de références correspondante ; les erreurs de décalage d'une position échouent avec un message clair.
Utilisez une chaîne vide pour laisser un emplacement non défini. Pour xAI, définissez chaque rôle d'image sur
`reference_image` afin d'utiliser son mode de génération `reference_images` ; omettez le
rôle ou utilisez `first_frame` pour la conversion image-vers-vidéo à image unique.
</Note>
### Contrôles de style
<ParamField path="aspectRatio" type="string">
`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` ou `adaptive`.
Indication de rapport d'aspect telle que `1:1`, `16:9`, `9:16`, `adaptive`, ou une valeur propre au fournisseur. OpenClaw normalise ou ignore les valeurs non prises en charge selon le fournisseur.
</ParamField>
<ParamField path="resolution" type="string">`480P`, `720P`, `768P` ou `1080P`.</ParamField>
<ParamField path="resolution" type="string">Indication de résolution telle que `480P`, `720P`, `768P`, `1080P`, `4K`, ou une valeur propre au fournisseur. OpenClaw normalise ou ignore les valeurs non prises en charge selon le fournisseur.</ParamField>
<ParamField path="durationSeconds" type="number">
Durée cible en secondes (arrondie à la valeur prise en charge la plus proche par le fournisseur).
Durée cible en secondes (arrondie à la valeur prise en charge la plus proche du fournisseur).
</ParamField>
<ParamField path="size" type="string">Indication de taille lorsque le fournisseur la prend en charge.</ParamField>
<ParamField path="audio" type="boolean">
Active l’audio généré dans la sortie lorsque c’est pris en charge. Distinct de `audioRef*` (entrées).
Active l'audio généré dans la sortie lorsque cela est pris en charge. Distinct de `audioRef*` (entrées).
</ParamField>
<ParamField path="watermark" type="boolean">Active ou désactive le filigrane du fournisseur lorsque c’est pris en charge.</ParamField>
<ParamField path="watermark" type="boolean">Active ou désactive le filigrane du fournisseur lorsque cela est pris en charge.</ParamField>
`adaptive` est une sentinelle propre au fournisseur : elle est transmise telle quelle aux
fournisseurs qui déclarent `adaptive` dans leurs capacités (par exemple, BytePlus
Seedance l’utilise pour détecter automatiquement le ratio à partir des dimensions
de l’image d’entrée). Les fournisseurs qui ne la déclarent pas exposent la valeur via
`details.ignoredOverrides` dans le résultat de l’outil afin que l’abandon soit visible.
Seedance l'utilise pour détecter automatiquement le rapport à partir des dimensions
de l'image d'entrée). Les fournisseurs qui ne la déclarent pas exposent la valeur via
`details.ignoredOverrides` dans le résultat de l'outil afin que l'abandon soit visible.
### Avancé
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` renvoie la tâche de session actuelle ; `"list"` inspecte les fournisseurs.
</ParamField>
<ParamField path="model" type="string">Remplacement du fournisseur/modèle (par exemple `runway/gen4.5`).</ParamField>
<ParamField path="model" type="string">Remplacement de fournisseur/modèle (par exemple `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">Indication de nom de fichier de sortie.</ParamField>
<ParamField path="timeoutMs" type="number">Délai d’expiration optionnel de la requête fournisseur, en millisecondes.</ParamField>
<ParamField path="timeoutMs" type="number">Délai d'expiration facultatif de l'opération du fournisseur, en millisecondes.</ParamField>
<ParamField path="providerOptions" type="object">
Options propres au fournisseur sous forme d’objet JSON (par exemple `{"seed": 42, "draft": true}`).
Options propres au fournisseur sous forme d'objet JSON (par exemple `{"seed": 42, "draft": true}`).
Les fournisseurs qui déclarent un schéma typé valident les clés et les types ; les clés
inconnues ou les incompatibilités ignorent le candidat pendant le repli. Les fournisseurs sans
inconnues ou les incompatibilités ignorent le candidat pendant le fallback. Les fournisseurs sans
schéma déclaré reçoivent les options telles quelles. Exécutez `video_generate action=list`
pour voir ce que chaque fournisseur accepte.
</ParamField>
<Note>
Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw normalise la durée à
la valeur prise en charge la plus proche par le fournisseur, et remappe les indications de géométrie traduites
comme taille-vers-ratio d’aspect lorsqu’un fournisseur de repli expose une surface de contrôle
différente. Les remplacements réellement non pris en charge sont ignorés au mieux
et signalés comme avertissements dans le résultat de l’outil. Les limites strictes de capacité
(comme un trop grand nombre d’entrées de référence) échouent avant la soumission. Les résultats de l’outil
Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw normalise la durée sur
la valeur prise en charge par le fournisseur la plus proche, et remappe les indications de géométrie traduites
comme la taille vers le rapport d'aspect lorsqu'un fournisseur de fallback expose une surface de contrôle
différente. Les remplacements réellement non pris en charge sont ignorés dans la mesure du possible
et signalés comme avertissements dans le résultat de l'outil. Les limites strictes de capacité
(comme un nombre excessif d'entrées de référence) échouent avant la soumission. Les résultats de l'outil
signalent les paramètres appliqués ; `details.normalization` capture toute traduction
demandée-vers-appliquée.
</Note>
Les entrées de référence sélectionnent le mode d’exécution :
Les entrées de référence sélectionnent le mode d'exécution :
- Aucun média de référence → `generate`
- Toute référence image → `imageToVideo`
- Toute référence d'image → `imageToVideo`
- Toute référence vidéo → `videoToVideo`
- Les entrées audio de référence **ne** changent pas le mode résolu ; elles s’appliquent
- Les entrées audio de référence **ne** modifient **pas** le mode résolu ; elles s'appliquent
par-dessus le mode sélectionné par les références image/vidéo, et fonctionnent uniquement
avec les fournisseurs qui déclarent `maxInputAudios`.
Les références mixtes image et vidéo ne constituent pas une surface de capacité partagée stable.
Préférez un seul type de référence par requête.
#### Repli et options typées
#### Fallback et options typées
Certaines vérifications de capacité sont appliquées au niveau de la couche de repli plutôt qu’à la
frontière de l’outil, de sorte qu’une requête dépassant les limites du fournisseur principal peut
toujours s’exécuter sur un repli capable :
Certaines vérifications de capacité sont appliquées à la couche de fallback plutôt qu'à la
frontière de l'outil, de sorte qu'une requête dépassant les limites du fournisseur principal peut
tout de même s'exécuter sur un fallback capable :
- Le candidat actif ne déclarant aucun `maxInputAudios` (ou `0`) est ignoré lorsque
- Un candidat actif ne déclarant aucun `maxInputAudios` (ou `0`) est ignoré lorsque
la requête contient des références audio ; le candidat suivant est essayé.
- Le `maxDurationSeconds` du candidat actif est inférieur au `durationSeconds` demandé
sans liste `supportedDurationSeconds` déclarée → ignoré.
- La requête contient `providerOptions` et le candidat actif déclare explicitement
un schéma `providerOptions` typé → ignoré si les clés fournies ne sont
pas dans le schéma ou si les types de valeurs ne correspondent pas. Les fournisseurs sans
schéma déclaré reçoivent les options telles quelles (transmission
rétrocompatible). Un fournisseur peut refuser toutes les options fournisseur en
déclarant un schéma vide (`capabilities.providerOptions: {}`), ce qui
provoque le même saut qu’une incompatibilité de type.
un schéma `providerOptions` typé → ignoré si les clés fournies ne figurent
pas dans le schéma ou si les types de valeur ne correspondent pas. Les fournisseurs sans
schéma déclaré reçoivent les options telles quelles (transmission rétrocompatible).
Un fournisseur peut refuser toutes les options de fournisseur en déclarant un schéma vide
(`capabilities.providerOptions: {}`), ce qui provoque le même saut qu'une incompatibilité de type.
La première raison d’ignorance dans une requête est journalisée au niveau `warn` afin que les opérateurs voient quand
leur fournisseur principal a été contourné ; les ignorances suivantes sont journalisées au niveau `debug` pour
garder les longues chaînes de repli silencieuses. Si chaque candidat est ignoré, l’erreur
agrégée inclut la raison d’ignorance pour chacun.
La première raison d'ignorance dans une requête est journalisée au niveau `warn` afin que les opérateurs voient quand
leur fournisseur principal a été écarté ; les ignorances suivantes sont journalisées au niveau `debug` afin de
garder les longues chaînes de fallback silencieuses. Si chaque candidat est ignoré, l'erreur
agrégée inclut la raison d'ignorance pour chacun.
## Actions
| Action | Ce qu’elle fait |
| Action | Ce qu'elle fait |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | Par défaut. Crée une vidéo à partir du prompt fourni et des entrées de référence optionnelles. |
| `status` | Vérifie l’état de la tâche vidéo en cours pour la session actuelle sans lancer une autre génération. |
| `list` | Affiche les fournisseurs, modèles et leurs capacités disponibles. |
| `generate` | Par défaut. Crée une vidéo à partir du prompt donné et des entrées de référence facultatives. |
| `status` | Vérifie l'état de la tâche vidéo en cours pour la session actuelle sans démarrer une autre génération. |
| `list` | Affiche les fournisseurs, les modèles et leurs capacités disponibles. |
## Sélection du modèle
OpenClaw résout le modèle dans cet ordre :
1. **Paramètre d’outil `model`** — si l’agent en spécifie un dans l’appel.
1. **Paramètre d'outil `model`** — si l'agent en spécifie un dans l'appel.
2. **`videoGenerationModel.primary`** depuis la configuration.
3. **`videoGenerationModel.fallbacks`** dans l’ordre.
4. **Détection automatique** — fournisseurs disposant d’une authentification valide, en commençant par le
fournisseur par défaut actuel, puis les fournisseurs restants dans l’ordre
3. **`videoGenerationModel.fallbacks`** dans l'ordre.
4. **Détection automatique** — fournisseurs disposant d'une authentification valide, en commençant par le
fournisseur par défaut actuel, puis les fournisseurs restants dans l'ordre
alphabétique.
Si un fournisseur échoue, le candidat suivant est essayé automatiquement. Si tous les
candidats échouent, l’erreur inclut les détails de chaque tentative.
candidats échouent, l'erreur inclut les détails de chaque tentative.
Définissez `agents.defaults.mediaGenerationAutoProviderFallback: false` pour utiliser
uniquement les entrées explicites `model`, `primary` et `fallbacks`.
@ -327,21 +326,21 @@ uniquement les entrées explicites `model`, `primary` et `fallbacks`.
<AccordionGroup>
<Accordion title="Alibaba">
Utilise le point de terminaison asynchrone DashScope / Model Studio. Les images et
vidéos de référence doivent être des URL distantes `http(s)`.
Utilise l'endpoint asynchrone DashScope / Model Studio. Les images et
vidéos de référence doivent être des URL `http(s)` distantes.
</Accordion>
<Accordion title="BytePlus (1.0)">
ID fournisseur : `byteplus`.
ID du fournisseur : `byteplus`.
Modèles : `seedance-1-0-pro-250528` (par défaut),
`seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`,
`seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
Les modèles T2V (`*-t2v-*`) n’acceptent pas les entrées image ; les modèles I2V et
Les modèles T2V (`*-t2v-*`) n'acceptent pas les entrées image ; les modèles I2V et
les modèles généraux `*-pro-*` prennent en charge une seule image de référence (première
image). Passez l’image positionnellement ou définissez `role: "first_frame"`.
image). Passez l'image positionnellement ou définissez `role: "first_frame"`.
Les ID de modèle T2V sont automatiquement basculés vers la variante I2V
correspondante lorsqu’une image est fournie.
correspondante lorsqu'une image est fournie.
Clés `providerOptions` prises en charge : `seed` (nombre), `draft` (booléen —
force 480p), `camera_fixed` (booléen).
@ -349,93 +348,102 @@ uniquement les entrées explicites `model`, `primary` et `fallbacks`.
</Accordion>
<Accordion title="BytePlus Seedance 1.5">
Nécessite le Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
ID fournisseur : `byteplus-seedance15`. Modèle :
ID du fournisseur : `byteplus-seedance15`. Modèle :
`seedance-1-5-pro-251215`.
Utilise l’API unifiée `content[]`. Prend en charge au plus 2 images d’entrée
(`first_frame` + `last_frame`). Toutes les entrées doivent être des URL distantes `https://`.
Définissez `role: "first_frame"` / `"last_frame"` sur chaque image, ou
Utilise l'API unifiée `content[]`. Prend en charge au maximum 2 images d'entrée
(`first_frame` + `last_frame`). Toutes les entrées doivent être des URL `https://`
distantes. Définissez `role: "first_frame"` / `"last_frame"` sur chaque image, ou
passez les images positionnellement.
`aspectRatio: "adaptive"` détecte automatiquement le ratio à partir de l’image d’entrée.
`aspectRatio: "adaptive"` détecte automatiquement le rapport à partir de l'image d'entrée.
`audio: true` correspond à `generate_audio`. `providerOptions.seed`
(nombre) est transmis.
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
Nécessite le Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
ID fournisseur : `byteplus-seedance2`. Modèles :
ID du fournisseur : `byteplus-seedance2`. Modèles :
`dreamina-seedance-2-0-260128`,
`dreamina-seedance-2-0-fast-260128`.
Utilise l’API unifiée `content[]`. Prend en charge jusqu’à 9 images de référence,
3 vidéos de référence et 3 audios de référence. Toutes les entrées doivent être des URL distantes
`https://`. Définissez `role` sur chaque ressource — valeurs prises en charge :
Utilise l'API unifiée `content[]`. Prend en charge jusqu'à 9 images de référence,
3 vidéos de référence et 3 audios de référence. Toutes les entrées doivent être des URL
`https://` distantes. Définissez `role` sur chaque ressource — valeurs prises en charge :
`"first_frame"`, `"last_frame"`, `"reference_image"`,
`"reference_video"`, `"reference_audio"`.
`aspectRatio: "adaptive"` détecte automatiquement le ratio à partir de l’image d’entrée.
`aspectRatio: "adaptive"` détecte automatiquement le rapport à partir de l'image d'entrée.
`audio: true` correspond à `generate_audio`. `providerOptions.seed`
(nombre) est transmis.
</Accordion>
<Accordion title="ComfyUI">
Exécution locale ou cloud pilotée par workflow. Prend en charge texte-vers-vidéo et
image-vers-vidéo via le graphe configuré.
Exécution locale ou dans le cloud pilotée par des workflows. Prend en
charge le texte vers vidéo et l’image vers vidéo via le graphe configuré.
</Accordion>
<Accordion title="fal">
Utilise un flux basé sur une file d’attente pour les tâches longues. La plupart des modèles vidéo fal
acceptent une seule référence image. Les modèles référence-vers-vidéo Seedance 2.0
acceptent jusqu’à 9 images, 3 vidéos et 3 références audio, avec
au plus 12 fichiers de référence au total.
Utilise un flux adossé à une file d’attente pour les tâches longues.
OpenClaw attend jusqu’à 20 minutes par défaut avant de considérer une
tâche de file d’attente fal en cours comme expirée. La plupart des modèles
vidéo fal acceptent une seule référence d’image. Les modèles Seedance 2.0
référence vers vidéo acceptent jusqu’à 9 images, 3 vidéos et 3 références
audio, avec au plus 12 fichiers de référence au total.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Prend en charge une référence image ou une référence vidéo.
Prend en charge une référence d’image ou une référence vidéo. Les requêtes
d’audio généré sont ignorées avec un avertissement sur le chemin de l’API
Gemini, car cette API rejette le paramètre `generateAudio` pour la
génération vidéo Veo actuelle.
</Accordion>
<Accordion title="MiniMax">
Référence image unique uniquement.
Une seule référence d’image. MiniMax accepte les résolutions `768P` et
`1080P` ; les requêtes comme `720P` sont normalisées vers la valeur prise
en charge la plus proche avant l’envoi.
</Accordion>
<Accordion title="OpenAI">
Seul le remplacement `size` est transmis. Les autres remplacements de style
(`aspectRatio`, `resolution`, `audio`, `watermark`) sont ignorés avec
un avertissement.
Seule la substitution `size` est transmise. Les autres substitutions de
style (`aspectRatio`, `resolution`, `audio`, `watermark`) sont ignorées
avec un avertissement.
</Accordion>
<Accordion title="OpenRouter">
Utilise l’API asynchrone `/videos` d’OpenRouter. OpenClaw soumet la
tâche, interroge `polling_url` et télécharge soit `unsigned_urls`, soit le
point de terminaison de contenu de tâche documenté. Le défaut groupé `google/veo-3.1-fast`
annonce des durées de 4/6/8 secondes, des résolutions `720P`/`1080P` et des
ratios d’aspect `16:9`/`9:16`.
tâche, interroge `polling_url`, puis télécharge soit `unsigned_urls`, soit
l’endpoint de contenu de tâche documenté. La valeur par défaut groupée
`google/veo-3.1-fast` annonce des durées de 4/6/8 secondes, des résolutions
`720P`/`1080P` et des formats d’image `16:9`/`9:16`.
</Accordion>
<Accordion title="Qwen">
Même backend DashScope qu’Alibaba. Les entrées de référence doivent être des URL distantes
`http(s)` ; les fichiers locaux sont rejetés en amont.
Même backend DashScope qu’Alibaba. Les entrées de référence doivent être
des URL distantes `http(s)` ; les fichiers locaux sont rejetés d’emblée.
</Accordion>
<Accordion title="Runway">
Prend en charge les fichiers locaux via des URI de données. Vidéo-vers-vidéo nécessite
`runway/gen4_aleph`. Les exécutions texte uniquement exposent les ratios d’aspect
`16:9` et `9:16`.
Prend en charge les fichiers locaux via des URI de données. Le vidéo vers
vidéo nécessite `runway/gen4_aleph`. Les exécutions texte seul exposent les
formats d’image `16:9` et `9:16`.
</Accordion>
<Accordion title="Together">
Référence image unique uniquement.
Une seule référence d’image.
</Accordion>
<Accordion title="Vydra">
Utilise directement `https://www.vydra.ai/api/v1` pour éviter les redirections
qui supprimeraient l’authentification. `veo3` est fourni uniquement pour texte-vers-vidéo ; `kling` nécessite
une URL d’image distante.
Utilise directement `https://www.vydra.ai/api/v1` pour éviter les
redirections qui abandonnent l’authentification. `veo3` est groupé en
texte vers vidéo uniquement ; `kling` nécessite une URL d’image distante.
</Accordion>
<Accordion title="xAI">
Prend en charge texte-vers-vidéo, image-vers-vidéo avec une seule image de première trame, jusqu’à 7
entrées `reference_image` via les `reference_images` de xAI, ainsi que les flux distants
de modification/extension de vidéo.
Prend en charge le texte vers vidéo, l’image vers vidéo avec une seule
image de première frame, jusqu’à 7 entrées `reference_image` via
`reference_images` de xAI, ainsi que les flux distants de modification et
d’extension vidéo.
</Accordion>
</AccordionGroup>
## Modes de capacité des fournisseurs
## Modes de capacités des fournisseurs
Le contrat partagé de génération vidéo prend en charge des capacités propres à chaque mode
au lieu de simples limites agrégées plates. Les nouvelles implémentations de fournisseurs
devraient privilégier des blocs de mode explicites :
Le contrat partagé de génération vidéo prend en charge les capacités propres
au mode plutôt que de simples limites agrégées plates. Les nouvelles
implémentations de fournisseurs doivent privilégier des blocs de mode
explicites :
```typescript
capabilities: {
@ -460,19 +468,21 @@ capabilities: {
}
```
Les champs agrégés plats tels que `maxInputImages` et `maxInputVideos` ne sont
**pas** suffisants pour annoncer la prise en charge du mode de transformation. Les fournisseurs devraient
déclarer explicitement `generate`, `imageToVideo` et `videoToVideo` afin que les tests en direct,
les tests de contrat et l’outil partagé `video_generate` puissent valider
la prise en charge des modes de manière déterministe.
Les champs agrégés plats comme `maxInputImages` et `maxInputVideos` ne
suffisent **pas** pour annoncer la prise en charge des modes de transformation.
Les fournisseurs doivent déclarer explicitement `generate`, `imageToVideo` et
`videoToVideo` afin que les tests live, les tests de contrat et l’outil partagé
`video_generate` puissent valider la prise en charge des modes de manière
déterministe.
Lorsqu’un modèle d’un fournisseur prend en charge davantage d’entrées de référence que les
autres, utilisez `maxInputImagesByModel`, `maxInputVideosByModel` ou
`maxInputAudiosByModel` au lieu d’augmenter la limite globale du mode.
Lorsqu’un modèle d’un fournisseur prend en charge plus largement les entrées de
référence que les autres, utilisez `maxInputImagesByModel`,
`maxInputVideosByModel` ou `maxInputAudiosByModel` au lieu d’augmenter la
limite à l’échelle du mode.
## Tests en direct
## Tests live
Couverture en direct facultative pour les fournisseurs partagés intégrés :
Couverture live opt-in pour les fournisseurs groupés partagés :
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -484,35 +494,39 @@ Wrapper du dépôt :
pnpm test:live:media video
```
Ce fichier en direct charge les variables d’environnement manquantes des fournisseurs depuis `~/.profile`, privilégie
par défaut les clés d’API en direct/d’environnement avant les profils d’authentification stockés, et exécute un
test de fumée sûr pour la publication par défaut :
Ce fichier live charge les variables d’environnement de fournisseur manquantes
depuis `~/.profile`, privilégie par défaut les clés d’API live/env avant les
profils d’authentification stockés, et exécute par défaut un smoke test sûr
pour les releases :
- `generate` pour chaque fournisseur non FAL de la passe.
- `generate` pour chaque fournisseur non-FAL de la passe.
- Prompt de homard d’une seconde.
- Limite d’opérations par fournisseur depuis
- Plafond d’opération par fournisseur depuis
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` par défaut).
FAL est facultatif, car la latence de file d’attente côté fournisseur peut dominer le temps de publication :
FAL est opt-in, car la latence de file d’attente côté fournisseur peut dominer
le temps de release :
```bash
pnpm test:live:media video --video-providers fal
```
Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi les
modes de transformation déclarés que la passe partagée peut exercer en toute sécurité avec des médias locaux :
Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi
les modes de transformation déclarés que la passe partagée peut exercer en
sécurité avec des médias locaux :
- `imageToVideo` lorsque `capabilities.imageToVideo.enabled`.
- `videoToVideo` lorsque `capabilities.videoToVideo.enabled` et que le
fournisseur/modèle accepte une entrée vidéo locale adossée à un tampon dans la passe
partagée.
fournisseur/modèle accepte l’entrée vidéo locale adossée à un buffer dans la
passe partagée.
Aujourd’hui, la voie en direct partagée `videoToVideo` couvre `runway` uniquement lorsque vous
sélectionnez `runway/gen4_aleph`.
Aujourd’hui, la voie live partagée `videoToVideo` couvre `runway` uniquement
lorsque vous sélectionnez `runway/gen4_aleph`.
## Configuration
Définissez le modèle de génération vidéo par défaut dans votre configuration OpenClaw :
Définissez le modèle de génération vidéo par défaut dans votre configuration
OpenClaw :
```json5
{
@ -533,7 +547,7 @@ Ou via la CLI :
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
```
## Connexe
## Liens associés
- [Alibaba Model Studio](/fr/providers/alibaba)
- [Tâches en arrière-plan](/fr/automation/tasks) — suivi des tâches pour la génération vidéo asynchrone

290
docs/fr/web/control-ui.md
View File

@ -1,48 +1,48 @@
---
read_when:
- Vous voulez utiliser le Gateway depuis un navigateur
- Vous souhaitez utiliser le Gateway depuis un navigateur
- Vous voulez un accès au Tailnet sans tunnels SSH
sidebarTitle: Control UI
summary: Interface de contrôle dans le navigateur pour le Gateway (discussion, nœuds, configuration)
summary: Interface de contrôle basée sur le navigateur pour le Gateway (chat, nœuds, configuration)
title: Interface de contrôle
x-i18n:
generated_at: "2026-05-04T09:37:07Z"
generated_at: "2026-05-05T06:19:51Z"
model: gpt-5.5
provider: openai
source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de
source_hash: d249559d26ef8d257a14b104a797442e9fbb67a8ab31c7fcc9eaa4127f29c933
source_path: web/control-ui.md
workflow: 16
---
L’interface utilisateur de contrôle est une petite application monopage **Vite + Lit** servie par le Gateway:
L’interface de contrôle est une petite application monopage **Vite + Lit** servie par le Gateway :
- par défaut: `http://<host>:18789/`
- préfixe facultatif: définissez `gateway.controlUi.basePath` (par ex. `/openclaw`)
- par défaut : `http://<host>:18789/`
- préfixe facultatif : définissez `gateway.controlUi.basePath` (par exemple `/openclaw`)
Elle communique **directement avec le WebSocket du Gateway** sur le même port.
## Ouverture rapide (locale)
Si le Gateway est en cours d’exécution sur le même ordinateur, ouvrez:
Si le Gateway fonctionne sur le même ordinateur, ouvrez :
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (ou [http://localhost:18789/](http://localhost:18789/))
Si la page ne se charge pas, démarrez d’abord le Gateway: `openclaw gateway`.
Si la page ne se charge pas, démarrez d’abord le Gateway : `openclaw gateway`.
L’authentification est fournie pendant la négociation WebSocket via:
L’authentification est fournie pendant la négociation WebSocket via :
- `connect.params.auth.token`
- `connect.params.auth.password`
- les en-têtes d’identité Tailscale Serve lorsque `gateway.auth.allowTailscale: true`
- les en-têtes d’identité de proxy de confiance lorsque `gateway.auth.mode: "trusted-proxy"`
- les en-têtes d’identité Tailscale Serve quand `gateway.auth.allowTailscale: true`
- les en-têtes d’identité de proxy de confiance quand `gateway.auth.mode: "trusted-proxy"`
Le panneau des paramètres du tableau de bord conserve un jeton pour la session de l’onglet de navigateur actuel et l’URL de Gateway sélectionnée; les mots de passe ne sont pas conservés. L’onboarding génère généralement un jeton de Gateway pour l’authentification par secret partagé lors de la première connexion, mais l’authentification par mot de passe fonctionne aussi lorsque `gateway.auth.mode` vaut `"password"`.
Le panneau des paramètres du tableau de bord conserve un jeton pour la session d’onglet de navigateur actuelle et l’URL de gateway sélectionnée ; les mots de passe ne sont pas persistés. L’onboarding génère généralement un jeton de gateway pour l’authentification par secret partagé à la première connexion, mais l’authentification par mot de passe fonctionne aussi quand `gateway.auth.mode` vaut `"password"`.
## Appairage d’appareil (première connexion)
Lorsque vous vous connectez à l’interface utilisateur de contrôle depuis un nouveau navigateur ou appareil, le Gateway exige généralement une **approbation d’appairage unique**. Il s’agit d’une mesure de sécurité destinée à empêcher les accès non autorisés.
Lorsque vous vous connectez à l’interface de contrôle depuis un nouveau navigateur ou appareil, le Gateway exige généralement une **approbation d’appairage unique**. Il s’agit d’une mesure de sécurité pour empêcher les accès non autorisés.
**Ce que vous verrez:** "déconnecté (1008): appairage requis"
**Ce que vous verrez :** "disconnected (1008): pairing required"
<Steps>
<Step title="Lister les demandes en attente">
@ -57,97 +57,97 @@ Lorsque vous vous connectez à l’interface utilisateur de contrôle depuis un
</Step>
</Steps>
Si le navigateur retente l’appairage avec des détails d’authentification modifiés (rôle/portées/clé publique), la demande en attente précédente est remplacée et un nouveau `requestId` est créé. Réexécutez `openclaw devices list` avant l’approbation.
Si le navigateur retente l’appairage avec des détails d’authentification modifiés (rôle/portées/clé publique), la demande en attente précédente est remplacée et un nouveau `requestId` est créé. Relancez `openclaw devices list` avant l’approbation.
Si le navigateur est déjà appairé et que vous le faites passer d’un accès en lecture à un accès en écriture/admin, cela est traité comme une montée d’approbation, et non comme une reconnexion silencieuse. OpenClaw conserve l’ancienne approbation active, bloque la reconnexion plus étendue et vous demande d’approuver explicitement le nouvel ensemble de portées.
Si le navigateur est déjà appairé et que vous le faites passer d’un accès en lecture à un accès en écriture/admin, cela est traité comme une mise à niveau d’approbation, et non comme une reconnexion silencieuse. OpenClaw conserve l’ancienne approbation active, bloque la reconnexion plus large et vous demande d’approuver explicitement le nouveau jeu de portées.
Une fois approuvé, l’appareil est mémorisé et ne nécessitera pas de nouvelle approbation, sauf si vous le révoquez avec `openclaw devices revoke --device <id> --role <role>`. Consultez [CLI des appareils](/fr/cli/devices) pour la rotation et la révocation des jetons.
Une fois approuvé, l’appareil est mémorisé et ne demandera plus de nouvelle approbation, sauf si vous le révoquez avec `openclaw devices revoke --device <id> --role <role>`. Consultez [CLI des appareils](/fr/cli/devices) pour la rotation et la révocation des jetons.
<Note>
- Les connexions directes depuis un navigateur en local loopback (`127.0.0.1` / `localhost`) sont approuvées automatiquement.
- Tailscale Serve peut éviter l’aller-retour d’appairage pour les sessions opérateur de l’interface utilisateur de contrôle lorsque `gateway.auth.allowTailscale: true`, que l’identité Tailscale est vérifiée et que le navigateur présente son identité d’appareil.
- Tailscale Serve peut éviter l’aller-retour d’appairage pour les sessions d’opérateur de l’interface de contrôle quand `gateway.auth.allowTailscale: true`, que l’identité Tailscale est vérifiée et que le navigateur présente son identité d’appareil.
- Les liaisons Tailnet directes, les connexions de navigateur sur le LAN et les profils de navigateur sans identité d’appareil nécessitent toujours une approbation explicite.
- Chaque profil de navigateur génère un ID d’appareil unique; changer de navigateur ou effacer les données du navigateur nécessitera donc un nouvel appairage.
- Chaque profil de navigateur génère un ID d’appareil unique ; changer de navigateur ou effacer les données du navigateur nécessitera donc un nouvel appairage.
</Note>
## Identité personnelle (locale au navigateur)
L’interface utilisateur de contrôle prend en charge une identité personnelle propre à chaque navigateur (nom d’affichage et avatar) attachée aux messages sortants pour l’attribution dans les sessions partagées. Elle réside dans le stockage du navigateur, est limitée au profil de navigateur actuel et n’est pas synchronisée avec d’autres appareils ni conservée côté serveur au-delà des métadonnées normales d’auteur de transcription sur les messages que vous envoyez réellement. Effacer les données du site ou changer de navigateur la réinitialise à vide.
L’interface de contrôle prend en charge une identité personnelle par navigateur (nom d’affichage et avatar) jointe aux messages sortants pour l’attribution dans les sessions partagées. Elle vit dans le stockage du navigateur, est limitée au profil de navigateur actuel et n’est pas synchronisée avec d’autres appareils ni persistée côté serveur au-delà des métadonnées normales d’auteur de transcription sur les messages que vous envoyez réellement. Effacer les données du site ou changer de navigateur la réinitialise à vide.
Le même modèle local au navigateur s’applique au remplacement de l’avatar de l’assistant. Les avatars d’assistant téléversés se superposent à l’identité résolue par le gateway uniquement dans le navigateur local et ne transitent jamais par `config.patch`. Le champ de configuration partagé `ui.assistant.avatar` reste disponible pour les clients non UI qui écrivent directement dans ce champ (par exemple les gateways scriptés ou les tableaux de bord personnalisés).
Le même modèle local au navigateur s’applique au remplacement de l’avatar de l’assistant. Les avatars d’assistant téléversés se superposent à l’identité résolue par le gateway uniquement dans le navigateur local et ne font jamais d’aller-retour via `config.patch`. Le champ de configuration partagé `ui.assistant.avatar` reste disponible pour les clients non-UI qui écrivent directement le champ (comme des gateways scriptés ou des tableaux de bord personnalisés).
## Point de terminaison de configuration d’exécution
L’interface utilisateur de contrôle récupère ses paramètres d’exécution depuis `/__openclaw/control-ui-config.json`. Ce point de terminaison est protégé par la même authentification de gateway que le reste de la surface HTTP: les navigateurs non authentifiés ne peuvent pas le récupérer, et une récupération réussie nécessite soit un jeton/mot de passe de gateway déjà valide, soit une identité Tailscale Serve, soit une identité de proxy de confiance.
L’interface de contrôle récupère ses paramètres d’exécution depuis `/__openclaw/control-ui-config.json`. Ce point de terminaison est protégé par la même authentification de gateway que le reste de la surface HTTP : les navigateurs non authentifiés ne peuvent pas le récupérer, et une récupération réussie exige soit un jeton/mot de passe de gateway déjà valide, soit une identité Tailscale Serve, soit une identité de proxy de confiance.
## Prise en charge des langues
## Prise en charge linguistique
L’interface utilisateur de contrôle peut se localiser au premier chargement selon la langue de votre navigateur. Pour la remplacer plus tard, ouvrez **Vue d’ensemble -> Accès Gateway -> Langue**. Le sélecteur de langue se trouve dans la carte Accès Gateway, pas sous Apparence.
L’interface de contrôle peut se localiser au premier chargement selon la locale de votre navigateur. Pour la modifier plus tard, ouvrez **Vue d’ensemble -> Accès au Gateway -> Langue**. Le sélecteur de locale se trouve dans la carte Accès au Gateway, pas sous Apparence.
- Langues prises en charge: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
- Les traductions autres que l’anglais sont chargées paresseusement dans le navigateur.
- La langue sélectionnée est enregistrée dans le stockage du navigateur et réutilisée lors des visites ultérieures.
- Les clés de traduction manquantes reviennent à l’anglais.
- Locales prises en charge : `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
- Les traductions non anglaises sont chargées paresseusement dans le navigateur.
- La locale sélectionnée est enregistrée dans le stockage du navigateur et réutilisée lors des visites suivantes.
- Les clés de traduction manquantes se rabattent sur l’anglais.
Les traductions de la documentation sont générées pour le même ensemble de langues non anglaises, mais le sélecteur de langue Mintlify intégré au site de documentation est limité aux codes de langue acceptés par Mintlify. La documentation en thaï (`th`) et en persan (`fa`) est tout de même générée dans le dépôt de publication; elle peut ne pas apparaître dans ce sélecteur tant que Mintlify ne prend pas en charge ces codes.
Les traductions de la documentation sont générées pour le même ensemble de locales non anglaises, mais le sélecteur de langue Mintlify intégré au site de documentation est limité aux codes de locale acceptés par Mintlify. Les docs en thaï (`th`) et en persan (`fa`) sont toujours générées dans le dépôt de publication ; elles peuvent ne pas apparaître dans ce sélecteur tant que Mintlify ne prend pas en charge ces codes.
## Thèmes d’apparence
Le panneau Apparence conserve les thèmes intégrés Claw, Knot et Dash, plus un emplacement d’import tweakcn local au navigateur. Pour importer un thème, ouvrez [l’éditeur tweakcn](https://tweakcn.com/editor/theme), choisissez ou créez un thème, cliquez sur **Partager**, puis collez le lien du thème copié dans Apparence. L’importateur accepte aussi les URL de registre `https://tweakcn.com/r/themes/<id>`, les URL d’éditeur comme `https://tweakcn.com/editor/theme?theme=amethyst-haze`, les chemins relatifs `/themes/<id>`, les ID de thème bruts et les noms de thème par défaut tels que `amethyst-haze`.
Le panneau Apparence conserve les thèmes intégrés Claw, Knot et Dash, ainsi qu’un emplacement d’import tweakcn local au navigateur. Pour importer un thème, ouvrez [l’éditeur tweakcn](https://tweakcn.com/editor/theme), choisissez ou créez un thème, cliquez sur **Partager**, puis collez le lien de thème copié dans Apparence. L’importateur accepte aussi les URL de registre `https://tweakcn.com/r/themes/<id>`, les URL d’éditeur comme `https://tweakcn.com/editor/theme?theme=amethyst-haze`, les chemins relatifs `/themes/<id>`, les ID de thème bruts et les noms de thème par défaut comme `amethyst-haze`.
Les thèmes importés sont stockés uniquement dans le profil de navigateur actuel. Ils ne sont pas écrits dans la configuration du gateway et ne se synchronisent pas entre les appareils. Remplacer le thème importé met à jour l’unique emplacement local; l’effacer rétablit le thème actif sur Claw si le thème importé était sélectionné.
Les thèmes importés sont stockés uniquement dans le profil de navigateur actuel. Ils ne sont pas écrits dans la configuration du gateway et ne se synchronisent pas entre les appareils. Remplacer le thème importé met à jour l’unique emplacement local ; l’effacer rebascule le thème actif sur Claw si le thème importé était sélectionné.
## Ce qu’elle peut faire (aujourd’hui)
<AccordionGroup>
<Accordion title="Chat et parole">
- Discutez avec le modèle via le WS du Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- Parlez au moyen de sessions temps réel dans le navigateur. OpenAI utilise WebRTC directement, Google Live utilise un jeton de navigateur à usage unique contraint via WebSocket, et les Plugins vocaux temps réel uniquement backend utilisent le transport relais du Gateway. Le relais conserve les identifiants fournisseur sur le Gateway pendant que le navigateur diffuse le PCM du microphone via les RPC `talk.realtime.relay*` et renvoie les appels d’outil `openclaw_agent_consult` via `chat.send` pour le plus grand modèle OpenClaw configuré.
- Diffusez les appels d’outil + les cartes de sortie d’outil en direct dans Chat (événements d’agent).
<Accordion title="Chat et conversation vocale">
- Discuter avec le modèle via le WS du Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
- Parler via des sessions temps réel dans le navigateur. OpenAI utilise WebRTC direct, Google Live utilise un jeton de navigateur contraint à usage unique sur WebSocket, et les plugins de voix temps réel côté backend uniquement utilisent le transport relais du Gateway. Le relais conserve les identifiants du fournisseur sur le Gateway pendant que le navigateur diffuse le PCM du microphone via les RPC `talk.realtime.relay*` et renvoie les appels d’outil `openclaw_agent_consult` via `chat.send` pour le modèle OpenClaw configuré plus grand.
- Diffuser les appels d’outils + les cartes de sortie d’outil en direct dans Chat (événements d’agent).
</Accordion>
<Accordion title="Canaux, instances, sessions, rêves">
- Canaux: statut des canaux intégrés et des canaux Plugin groupés/externes, connexion par QR code et configuration par canal (`channels.status`, `web.login.*`, `config.patch`).
- Instances: liste de présence + actualisation (`system-presence`).
- Sessions: liste + remplacements par session du modèle, de la réflexion, du mode rapide, du mode verbeux, de la trace et du raisonnement (`sessions.list`, `sessions.patch`).
- Rêves: statut Dreaming, bascule d’activation/désactivation et lecteur de journal des rêves (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
- Canaux : état des canaux intégrés ainsi que des canaux de plugins groupés/externes, connexion par QR et configuration par canal (`channels.status`, `web.login.*`, `config.patch`).
- Instances : liste de présence + actualisation (`system-presence`).
- Sessions : liste + remplacements par session pour modèle/thinking/rapide/verbeux/trace/reasoning (`sessions.list`, `sessions.patch`).
- Rêves : état de dreaming, bouton activer/désactiver et lecteur de journal Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
</Accordion>
<Accordion title="Cron, Skills, nœuds, approbations exec">
- Tâches Cron: lister/ajouter/modifier/exécuter/activer/désactiver + historique d’exécution (`cron.*`).
- Skills: statut, activer/désactiver, installer, mises à jour de clé d’API (`skills.*`).
- Nœuds: liste + capacités (`node.list`).
- Approbations exec: modifier les listes d’autorisation du gateway ou des nœuds + politique de demande pour `exec host=gateway/node` (`exec.approvals.*`).
- Tâches Cron : liste/ajout/modification/exécution/activation/désactivation + historique d’exécution (`cron.*`).
- Skills : état, activation/désactivation, installation, mises à jour de clés API (`skills.*`).
- Nœuds : liste + capacités (`node.list`).
- Approbations exec : modifier les listes d’autorisation du gateway ou des nœuds + politique de demande pour `exec host=gateway/node` (`exec.approvals.*`).
</Accordion>
<Accordion title="Configuration">
- Afficher/modifier `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
- Appliquer + redémarrer avec validation (`config.apply`) et réveiller la dernière session active.
- Les écritures incluent une protection par hachage de base pour éviter d’écraser des modifications concurrentes.
- Les écritures (`config.set`/`config.apply`/`config.patch`) effectuent une prévalidation de la résolution des SecretRef actifs pour les références présentes dans la charge utile de configuration soumise; les références actives soumises non résolues sont rejetées avant l’écriture.
- Schéma + rendu de formulaire (`config.schema` / `config.schema.lookup`, y compris les champs `title` / `description`, les indices d’interface correspondants, les résumés d’enfants immédiats, les métadonnées de documentation sur les nœuds imbriqués objet/joker/tableau/composition, ainsi que les schémas Plugin + canal lorsqu’ils sont disponibles); l’éditeur JSON brut n’est disponible que lorsque l’instantané permet un aller-retour brut sûr.
- Si un instantané ne peut pas effectuer un aller-retour sûr du texte brut, l’interface utilisateur de contrôle force le mode Formulaire et désactive le mode Brut pour cet instantané.
- Dans l’éditeur JSON brut, "Réinitialiser à l’enregistrement" préserve la forme rédigée en brut (formatage, commentaires, disposition `$include`) au lieu de restituer un instantané aplati, afin que les modifications externes survivent à une réinitialisation lorsque l’instantané peut effectuer un aller-retour sûr.
- Les valeurs d’objet SecretRef structurées sont rendues en lecture seule dans les champs texte du formulaire afin d’éviter toute corruption accidentelle d’objet en chaîne.
- Les écritures (`config.set`/`config.apply`/`config.patch`) pré-vérifient la résolution active des SecretRef pour les refs présentes dans la charge utile de configuration soumise ; les refs actives soumises non résolues sont rejetées avant l’écriture.
- Rendu du schéma + formulaire (`config.schema` / `config.schema.lookup`, incluant les champs `title` / `description`, les indices UI correspondants, les résumés d’enfants immédiats, les métadonnées de docs sur les nœuds objet imbriqué/joker/tableau/composition, ainsi que les schémas de plugin + canal lorsqu’ils sont disponibles) ; l’éditeur JSON brut n’est disponible que lorsque l’instantané permet un aller-retour brut sûr.
- Si un instantané ne peut pas faire un aller-retour de texte brut en toute sécurité, l’interface de contrôle force le mode Formulaire et désactive le mode Brut pour cet instantané.
- Le bouton "Reset to saved" de l’éditeur JSON brut préserve la forme rédigée en brut (mise en forme, commentaires, disposition `$include`) au lieu de restituer un instantané aplati ; les modifications externes survivent donc à une réinitialisation quand l’instantané peut faire un aller-retour sûr.
- Les valeurs d’objet SecretRef structurées sont rendues en lecture seule dans les champs de texte de formulaire afin d’éviter une corruption accidentelle d’objet en chaîne.
</Accordion>
<Accordion title="Débogage, journaux, mise à jour">
- Débogage: instantanés de statut/santé/modèles + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`).
- Le journal d’événements inclut les temps d’actualisation/RPC de l’interface utilisateur de contrôle ainsi que les entrées de réactivité du navigateur pour les longues images d’animation ou les tâches longues lorsque le navigateur expose ces types d’entrées PerformanceObserver.
- Journaux: suivi en direct des journaux de fichiers du gateway avec filtre/export (`logs.tail`).
- Mise à jour: exécuter une mise à jour package/git + redémarrage (`update.run`) avec un rapport de redémarrage, puis interroger `update.status` après la reconnexion pour vérifier la version du gateway en cours d’exécution.
- Débogage : instantanés d’état/santé/modèles + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`).
- Le journal d’événements inclut les timings d’actualisation/RPC de l’interface de contrôle ainsi que les entrées de réactivité du navigateur pour les longues images d’animation ou les tâches longues lorsque le navigateur expose ces types d’entrées PerformanceObserver.
- Journaux : suivi en direct des journaux de fichiers du gateway avec filtre/export (`logs.tail`).
- Mise à jour : exécuter une mise à jour package/git + redémarrage (`update.run`) avec un rapport de redémarrage, puis interroger `update.status` après la reconnexion pour vérifier la version du gateway en cours d’exécution.
</Accordion>
<Accordion title="Notes du panneau des tâches Cron">
- Pour les tâches isolées, la diffusion est par défaut l’annonce d’un résumé. Vous pouvez passer à aucune si vous voulez des exécutions purement internes.
- Les champs canal/cible apparaissent lorsque l’annonce est sélectionnée.
- Le mode Webhook utilise `delivery.mode = "webhook"` avec `delivery.to` défini sur une URL Webhook HTTP(S) valide.
- Pour les tâches de session principale, les modes de diffusion webhook et aucune sont disponibles.
- Les contrôles d’édition avancés incluent suppression après exécution, effacer le remplacement d’agent, options cron exactes/échelonnées, remplacements du modèle/de la réflexion de l’agent, et bascules de diffusion au mieux.
- La validation du formulaire est intégrée avec des erreurs au niveau des champs; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
- Définissez `cron.webhookToken` pour envoyer un jeton porteur dédié; s’il est omis, le webhook est envoyé sans en-tête d’authentification.
- Repli obsolète: les anciennes tâches stockées avec `notify: true` peuvent toujours utiliser `cron.webhook` jusqu’à migration.
- Pour les tâches isolées, la livraison utilise par défaut l’annonce du résumé. Vous pouvez choisir aucune si vous voulez des exécutions uniquement internes.
- Les champs canal/cible apparaissent quand l’annonce est sélectionnée.
- Le mode Webhook utilise `delivery.mode = "webhook"` avec `delivery.to` défini sur une URL de webhook HTTP(S) valide.
- Pour les tâches de session principale, les modes de livraison webhook et aucune sont disponibles.
- Les contrôles de modification avancés incluent supprimer après exécution, effacer le remplacement d’agent, options cron exact/stagger, remplacements du modèle/thinking de l’agent et bascules de livraison au mieux.
- La validation du formulaire est intégrée avec des erreurs au niveau des champs ; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
- Définissez `cron.webhookToken` pour envoyer un jeton bearer dédié ; s’il est omis, le webhook est envoyé sans en-tête d’authentification.
- Solution de repli obsolète : les anciennes tâches stockées avec `notify: true` peuvent toujours utiliser `cron.webhook` jusqu’à migration.
</Accordion>
</AccordionGroup>
@ -156,65 +156,65 @@ Les thèmes importés sont stockés uniquement dans le profil de navigateur actu
<AccordionGroup>
<Accordion title="Sémantique d’envoi et d’historique">
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via les événements `chat`.
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via des événements `chat`.
- Les téléversements de chat acceptent les images ainsi que les fichiers non vidéo. Les images conservent le chemin d’image natif ; les autres fichiers sont stockés comme médias gérés et affichés dans l’historique sous forme de liens de pièces jointes.
- Un renvoi avec le même `idempotencyKey` retourne `{ status: "in_flight" }` pendant l’exécution, et `{ status: "ok" }` après l’achèvement.
- Les réponses `chat.history` sont limitées en taille pour la sécurité de l’interface utilisateur. Quand les entrées de transcription sont trop volumineuses, le Gateway peut tronquer les longs champs de texte, omettre les blocs de métadonnées lourds et remplacer les messages surdimensionnés par un espace réservé (`[chat.history omitted: message too large]`).
- Les images de l’assistant/générées sont conservées comme références de médias gérés et resservies via des URL de médias authentifiées du Gateway, afin que les rechargements ne dépendent pas du maintien de charges utiles d’images brutes en base64 dans la réponse d’historique du chat.
- `chat.history` supprime aussi du texte visible de l’assistant les balises de directives inline uniquement destinées à l’affichage (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), les charges utiles XML d’appels d’outils en texte brut (y compris `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, et les blocs d’appels d’outils tronqués), ainsi que les tokens de contrôle de modèle ASCII/pleine chasse qui ont fuité, et omet les entrées de l’assistant dont tout le texte visible est uniquement le token silencieux exact `NO_REPLY` / `no_reply`.
- Pendant un envoi actif et l’actualisation finale de l’historique, la vue de chat garde visibles les messages utilisateur/assistant optimistes locaux si `chat.history` renvoie brièvement un instantané plus ancien ; la transcription canonique remplace ces messages locaux une fois que l’historique du Gateway a rattrapé son retard.
- Les événements `chat` en direct représentent l’état de livraison, tandis que `chat.history` est reconstruit à partir de la transcription durable de la session. Après les événements finaux d’outils, l’interface de contrôle recharge l’historique et ne fusionne qu’une petite queue optimiste ; la limite de transcription est documentée dans [WebChat](/fr/web/webchat).
- `chat.inject` ajoute une note de l’assistant à la transcription de session et diffuse un événement `chat` pour les mises à jour uniquement destinées à l’interface utilisateur (aucune exécution d’agent, aucune livraison de canal).
- Un nouvel envoi avec le même `idempotencyKey` renvoie `{ status: "in_flight" }` pendant l’exécution, puis `{ status: "ok" }` une fois terminé.
- Les réponses de `chat.history` sont limitées en taille pour la sécurité de l’interface utilisateur. Lorsque les entrées de transcription sont trop volumineuses, le Gateway peut tronquer les champs de texte longs, omettre les blocs de métadonnées lourds et remplacer les messages surdimensionnés par un espace réservé (`[chat.history omitted: message too large]`).
- Les images de l’assistant/générées sont conservées comme références de médias gérés et renvoyées via des URL média authentifiées du Gateway, de sorte que les rechargements ne dépendent pas de la présence de charges utiles d’image base64 brutes dans la réponse d’historique du chat.
- Lors du rendu de `chat.history`, l’interface Control UI supprime du texte visible de l’assistant les balises de directives en ligne uniquement destinées à l’affichage (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), les charges utiles XML d’appels d’outils en texte brut (notamment `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` et les blocs d’appels d’outils tronqués), ainsi que les jetons de contrôle de modèle ASCII/pleine chasse divulgués, et omet les entrées de l’assistant dont tout le texte visible est uniquement le jeton silencieux exact `NO_REPLY` / `no_reply` ou le jeton d’accusé de réception Heartbeat `HEARTBEAT_OK`.
- Pendant un envoi actif et l’actualisation finale de l’historique, la vue de chat garde visibles les messages utilisateur/assistant locaux optimistes si `chat.history` renvoie brièvement un instantané plus ancien ; la transcription canonique remplace ces messages locaux une fois que l’historique du Gateway est à jour.
- Les événements `chat` en direct représentent l’état de livraison, tandis que `chat.history` est reconstruit à partir de la transcription durable de session. Après les événements finaux d’outil, l’interface Control UI recharge l’historique et fusionne seulement une petite fin optimiste ; la limite de transcription est documentée dans [WebChat](/fr/web/webchat).
- `chat.inject` ajoute une note d’assistant à la transcription de session et diffuse un événement `chat` pour les mises à jour uniquement destinées à l’interface utilisateur (aucune exécution d’agent, aucune livraison de canal).
- L’en-tête du chat affiche le filtre d’agent avant le sélecteur de session, et le sélecteur de session est limité à l’agent sélectionné. Changer d’agent affiche uniquement les sessions liées à cet agent et revient à la session principale de cet agent lorsqu’il n’a pas encore de sessions de tableau de bord enregistrées.
- Sur les largeurs de bureau, les contrôles de chat restent sur une ligne compacte et se replient lors du défilement vers le bas de la transcription ; faire défiler vers le haut, revenir au début ou atteindre le bas restaure les contrôles.
- Les messages consécutifs dupliqués contenant uniquement du texte sont rendus comme une seule bulle avec un badge de nombre. Les messages qui contiennent des images, des pièces jointes, une sortie d’outil ou des aperçus de canvas ne sont pas regroupés.
- Les sélecteurs de modèle et de raisonnement de l’en-tête du chat corrigent immédiatement la session active via `sessions.patch` ; ce sont des remplacements persistants de session, pas des options d’envoi limitées à un seul tour.
- Saisir `/new` dans l’interface de contrôle crée et bascule vers la même nouvelle session de tableau de bord que Nouveau chat. Saisir `/reset` conserve la réinitialisation explicite en place du Gateway pour la session actuelle.
- Le sélecteur de modèle du chat demande la vue de modèle configurée du Gateway. Si `agents.defaults.models` est présent, cette liste autorisée pilote le sélecteur. Sinon, le sélecteur affiche les entrées explicites `models.providers.*.models` ainsi que les fournisseurs avec une authentification utilisable. Le catalogue complet reste disponible via le RPC de débogage `models.list` avec `view: "all"`.
- Quand les rapports récents d’utilisation de session du Gateway indiquent une forte pression de contexte, la zone du composeur de chat affiche un avis de contexte et, aux niveaux de Compaction recommandés, un bouton compact qui exécute le chemin normal de Compaction de session. Les instantanés de tokens périmés sont masqués jusqu’à ce que le Gateway signale à nouveau une utilisation récente.
- Sur les largeurs de bureau, les contrôles de chat restent sur une seule ligne compacte et se replient lors du défilement vers le bas de la transcription ; faire défiler vers le haut, revenir en haut ou atteindre le bas restaure les contrôles.
- Les messages consécutifs en double contenant uniquement du texte sont rendus comme une seule bulle avec un badge de compteur. Les messages qui contiennent des images, des pièces jointes, une sortie d’outil ou des aperçus de canevas ne sont pas regroupés.
- Les sélecteurs de modèle et de réflexion dans l’en-tête du chat corrigent immédiatement la session active via `sessions.patch` ; ce sont des remplacements persistants de session, pas des options d’envoi limitées à un seul tour.
- Saisir `/new` dans l’interface Control UI crée et sélectionne la même nouvelle session de tableau de bord que New Chat. Saisir `/reset` conserve la réinitialisation explicite sur place du Gateway pour la session actuelle.
- Le sélecteur de modèle du chat demande la vue de modèles configurée du Gateway. Si `agents.defaults.models` est présent, cette liste d’autorisation pilote le sélecteur. Sinon, le sélecteur affiche les entrées explicites `models.providers.*.models` ainsi que les fournisseurs avec une authentification utilisable. Le catalogue complet reste disponible via le RPC de débogage `models.list` avec `view: "all"`.
- Lorsque les rapports d’utilisation de session frais du Gateway indiquent une forte pression de contexte, la zone du compositeur de chat affiche un avis de contexte et, aux niveaux de compaction recommandés, un bouton compact qui exécute le chemin normal de compaction de session. Les instantanés de jetons obsolètes sont masqués jusqu’à ce que le Gateway signale de nouveau une utilisation fraîche.
</Accordion>
<Accordion title="Mode conversation (temps réel du navigateur)">
Le mode conversation utilise un fournisseur vocal temps réel enregistré. Configurez OpenAI avec `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, ou configurez Google avec `talk.provider: "google"` plus `talk.providers.google.apiKey` ; la configuration du fournisseur temps réel Voice Call peut toujours être réutilisée comme solution de repli. Le navigateur ne reçoit jamais de clé API standard de fournisseur. OpenAI reçoit un secret client Realtime éphémère pour WebRTC. Google Live reçoit un token d’authentification Live API contraint à usage unique pour une session WebSocket de navigateur, avec les instructions et déclarations d’outils verrouillées dans le token par le Gateway. Les fournisseurs qui exposent uniquement un pont temps réel backend passent par le transport relais du Gateway, afin que les identifiants et les sockets fournisseur restent côté serveur pendant que l’audio du navigateur transite par des RPC authentifiés du Gateway. Le prompt de session Realtime est assemblé par le Gateway ; `talk.realtime.session` n’accepte pas les remplacements d’instructions fournis par l’appelant.
<Accordion title="Mode conversation (temps réel dans le navigateur)">
Le mode conversation utilise un fournisseur vocal temps réel enregistré. Configurez OpenAI avec `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, ou configurez Google avec `talk.provider: "google"` plus `talk.providers.google.apiKey` ; la configuration de fournisseur temps réel Voice Call peut toujours être réutilisée comme solution de repli. Le navigateur ne reçoit jamais de clé d’API de fournisseur standard. OpenAI reçoit un secret client Realtime éphémère pour WebRTC. Google Live reçoit un jeton d’authentification Live API contraint à usage unique pour une session WebSocket de navigateur, avec les instructions et déclarations d’outils verrouillées dans le jeton par le Gateway. Les fournisseurs qui n’exposent qu’un pont temps réel côté serveur passent par le transport relais du Gateway, de sorte que les identifiants et les sockets fournisseur restent côté serveur tandis que l’audio du navigateur transite par des RPC authentifiés du Gateway. Le prompt de session Realtime est assemblé par le Gateway ; `talk.realtime.session` n’accepte pas les remplacements d’instructions fournis par l’appelant.
Dans le composeur de chat, le contrôle de conversation est le bouton en forme d’ondes à côté du bouton de dictée au microphone. Quand la conversation démarre, la ligne d’état du composeur affiche `Connecting Talk...`, puis `Talk live` pendant que l’audio est connecté, ou `Asking OpenClaw...` pendant qu’un appel d’outil temps réel consulte le modèle plus grand configuré via `chat.send`.
Dans le compositeur de chat, le contrôle Conversation est le bouton à ondes à côté du bouton de dictée au microphone. Lorsque Conversation démarre, la ligne d’état du compositeur affiche `Connecting Talk...`, puis `Talk live` pendant que l’audio est connecté, ou `Asking OpenClaw...` pendant qu’un appel d’outil temps réel consulte le modèle plus grand configuré via `chat.send`.
Smoke live mainteneur : `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` vérifie l’échange SDP WebRTC navigateur d’OpenAI, la configuration WebSocket navigateur à token contraint Google Live, et l’adaptateur navigateur de relais Gateway avec un média de microphone factice. La commande imprime uniquement l’état du fournisseur et ne journalise aucun secret.
Smoke test en direct pour mainteneur : `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` vérifie l’échange SDP WebRTC du navigateur OpenAI, la configuration WebSocket de navigateur avec jeton contraint Google Live, et l’adaptateur navigateur de relais Gateway avec de faux médias de microphone. La commande affiche uniquement l’état du fournisseur et ne journalise aucun secret.
</Accordion>
<Accordion title="Arrêt et abandon">
- Cliquez sur **Arrêter** (appelle `chat.abort`).
- Pendant qu’une exécution est active, les suivis normaux sont mis en file d’attente. Cliquez sur **Orienter** sur un message en file d’attente pour injecter ce suivi dans le tour en cours.
- Cliquez sur **Stop** (appelle `chat.abort`).
- Pendant qu’une exécution est active, les suivis normaux sont mis en file d’attente. Cliquez sur **Steer** sur un message en file d’attente pour injecter ce suivi dans le tour en cours.
- Saisissez `/stop` (ou des phrases d’abandon autonomes comme `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) pour abandonner hors bande.
- `chat.abort` prend en charge `{ sessionKey }` (sans `runId`) pour abandonner toutes les exécutions actives de cette session.
</Accordion>
<Accordion title="Conservation partielle après abandon">
- Quand une exécution est abandonnée, le texte partiel de l’assistant peut encore être affiché dans l’interface utilisateur.
- Lorsqu’une exécution est abandonnée, le texte partiel de l’assistant peut toujours être affiché dans l’interface utilisateur.
- Le Gateway conserve le texte partiel abandonné de l’assistant dans l’historique de transcription lorsqu’une sortie mise en tampon existe.
- Les entrées conservées incluent des métadonnées d’abandon afin que les consommateurs de transcription puissent distinguer les fragments partiels d’abandon de la sortie d’achèvement normale.
- Les entrées conservées incluent des métadonnées d’abandon afin que les consommateurs de transcription puissent distinguer les fragments partiels abandonnés de la sortie de complétion normale.
</Accordion>
</AccordionGroup>
## Installation PWA et Web Push
L’interface de contrôle fournit un `manifest.webmanifest` et un service worker, afin que les navigateurs modernes puissent l’installer comme PWA autonome. Web Push permet au Gateway de réveiller la PWA installée avec des notifications même lorsque l’onglet ou la fenêtre du navigateur n’est pas ouvert.
L’interface Control UI fournit un `manifest.webmanifest` et un service worker, afin que les navigateurs modernes puissent l’installer comme PWA autonome. Web Push permet au Gateway de réveiller la PWA installée avec des notifications même lorsque l’onglet ou la fenêtre du navigateur n’est pas ouvert.
| Surface | Ce que cela fait |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest` | Manifeste PWA. Les navigateurs proposent « Installer l’application » une fois qu’il est accessible. |
| `ui/public/manifest.webmanifest` | Manifeste PWA. Les navigateurs proposent "Install app" une fois qu’il est accessible. |
| `ui/public/sw.js` | Service worker qui gère les événements `push` et les clics sur les notifications. |
| `push/vapid-keys.json` (sous le répertoire d’état OpenClaw) | Paire de clés VAPID générée automatiquement utilisée pour signer les charges utiles Web Push. |
| `push/web-push-subscriptions.json` | Points de terminaison d’abonnements navigateur persistés. |
| `push/vapid-keys.json` (sous le répertoire d’état OpenClaw) | Paire de clés VAPID générée automatiquement, utilisée pour signer les charges utiles Web Push. |
| `push/web-push-subscriptions.json` | Points de terminaison d’abonnement de navigateur persistés. |
Remplacez la paire de clés VAPID via les variables d’environnement sur le processus Gateway lorsque vous voulez épingler des clés (pour les déploiements multi-hôtes, la rotation des secrets ou les tests) :
Remplacez la paire de clés VAPID via des variables d’environnement sur le processus Gateway lorsque vous voulez épingler les clés (pour les déploiements multi-hôtes, la rotation de secrets ou les tests) :
- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT` (par défaut `mailto:openclaw@localhost`)
L’interface de contrôle utilise ces méthodes Gateway limitées par portée pour enregistrer et tester les abonnements navigateur :
L’interface Control UI utilise ces méthodes Gateway limitées par portée pour enregistrer et tester les abonnements de navigateur :
- `push.web.vapidPublicKey` — récupère la clé publique VAPID active.
- `push.web.subscribe` — enregistre un `endpoint` plus `keys.p256dh`/`keys.auth`.
@ -222,22 +222,22 @@ L’interface de contrôle utilise ces méthodes Gateway limitées par portée p
- `push.web.test` — envoie une notification de test à l’abonnement de l’appelant.
<Note>
Web Push est indépendant du chemin de relais APNS iOS (voir [Configuration](/fr/gateway/configuration) pour le push adossé à un relais) et de la méthode `push.test` existante, qui ciblent l’appairage mobile natif.
Web Push est indépendant du chemin de relais iOS APNS (voir [Configuration](/fr/gateway/configuration) pour le push adossé à un relais) et de la méthode `push.test` existante, qui ciblent l’appairage mobile natif.
</Note>
## Intégrations hébergées
Les messages de l’assistant peuvent afficher du contenu web hébergé inline avec le shortcode `[embed ...]`. La stratégie sandbox de l’iframe est contrôlée par `gateway.controlUi.embedSandbox` :
Les messages de l’assistant peuvent afficher du contenu web hébergé en ligne avec le shortcode `[embed ...]`. La politique de sandbox iframe est contrôlée par `gateway.controlUi.embedSandbox` :
<Tabs>
<Tab title="strict">
Désactive l’exécution de scripts dans les intégrations hébergées.
Désactive l’exécution de scripts à l’intérieur des intégrations hébergées.
</Tab>
<Tab title="scripts (default)">
Autorise les intégrations interactives tout en conservant l’isolation d’origine ; c’est la valeur par défaut et elle suffit généralement pour les jeux/widgets de navigateur autonomes.
</Tab>
<Tab title="trusted">
Ajoute `allow-same-origin` en plus de `allow-scripts` pour les documents du même site qui ont intentionnellement besoin de privilèges plus forts.
Ajoute `allow-same-origin` en plus de `allow-scripts` pour les documents du même site qui ont intentionnellement besoin de privilèges plus élevés.
</Tab>
</Tabs>
@ -254,14 +254,14 @@ Exemple :
```
<Warning>
Utilisez `trusted` uniquement lorsque le document intégré a réellement besoin d’un comportement de même origine. Pour la plupart des jeux générés par agent et des canvas interactifs, `scripts` est le choix le plus sûr.
Utilisez `trusted` uniquement lorsque le document intégré a réellement besoin d’un comportement même origine. Pour la plupart des jeux générés par agent et des canevas interactifs, `scripts` est le choix le plus sûr.
</Warning>
Les URL d’intégration externes absolues `http(s)` restent bloquées par défaut. Si vous voulez intentionnellement que `[embed url="https://..."]` charge des pages tierces, définissez `gateway.controlUi.allowExternalEmbedUrls: true`.
## Largeur des messages de chat
Les messages de chat groupés utilisent une largeur maximale lisible par défaut. Les déploiements sur écrans larges peuvent la remplacer sans corriger le CSS groupé en définissant `gateway.controlUi.chatMessageMaxWidth` :
Les messages de chat groupés utilisent une largeur maximale lisible par défaut. Les déploiements sur écrans larges peuvent la remplacer sans modifier le CSS groupé en définissant `gateway.controlUi.chatMessageMaxWidth` :
```json5
{
@ -273,13 +273,13 @@ Les messages de chat groupés utilisent une largeur maximale lisible par défaut
}
```
La valeur est validée avant d’atteindre le navigateur. Les valeurs prises en charge incluent les longueurs simples et les pourcentages comme `960px` ou `82%`, ainsi que les expressions de largeur contraintes `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` et `fit-content(...)`.
La valeur est validée avant d’atteindre le navigateur. Les valeurs prises en charge incluent les longueurs et pourcentages simples comme `960px` ou `82%`, ainsi que les expressions de largeur contraintes `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` et `fit-content(...)`.
## Accès tailnet (recommandé)
<Tabs>
<Tab title="Tailscale Serve intégré (préféré)">
Gardez le Gateway sur local loopback et laissez Tailscale Serve le proxyfier avec HTTPS :
<Tab title="Integrated Tailscale Serve (preferred)">
Gardez le Gateway sur local loopback et laissez Tailscale Serve le proxifier en HTTPS :
```bash
openclaw gateway --tailscale serve
@ -289,46 +289,46 @@ La valeur est validée avant d’atteindre le navigateur. Les valeurs prises en
- `https://<magicdns>/` (ou votre `gateway.controlUi.basePath` configuré)
Par défaut, les requêtes Control UI/WebSocket Serve peuvent s’authentifier via les en-têtes d’identité Tailscale (`tailscale-user-login`) lorsque `gateway.auth.allowTailscale` vaut `true`. OpenClaw vérifie l’identité en résolvant l’adresse `x-forwarded-for` avec `tailscale whois` et en la faisant correspondre à l’en-tête, et n’accepte ces requêtes que lorsqu’elles atteignent le local loopback avec les en-têtes `x-forwarded-*` de Tailscale. Pour les sessions opérateur de l’interface de contrôle avec identité d’appareil navigateur, ce chemin Serve vérifié ignore aussi l’aller-retour d’appairage d’appareil ; les navigateurs sans appareil et les connexions avec rôle de nœud suivent toujours les vérifications d’appareil normales. Définissez `gateway.auth.allowTailscale: false` si vous voulez exiger des identifiants explicites par secret partagé même pour le trafic Serve. Utilisez ensuite `gateway.auth.mode: "token"` ou `"password"`.
Par défaut, les requêtes Control UI/WebSocket Serve peuvent s’authentifier via les en-têtes d’identité Tailscale (`tailscale-user-login`) lorsque `gateway.auth.allowTailscale` vaut `true`. OpenClaw vérifie l’identité en résolvant l’adresse `x-forwarded-for` avec `tailscale whois` et en la faisant correspondre à l’en-tête, et n’accepte ces requêtes que lorsqu’elles arrivent sur local loopback avec les en-têtes `x-forwarded-*` de Tailscale. Pour les sessions opérateur Control UI avec identité d’appareil de navigateur, ce chemin Serve vérifié saute aussi l’aller-retour d’appairage d’appareil ; les navigateurs sans appareil et les connexions de rôle nœud suivent toujours les vérifications d’appareil normales. Définissez `gateway.auth.allowTailscale: false` si vous voulez exiger des identifiants explicites à secret partagé même pour le trafic Serve. Utilisez ensuite `gateway.auth.mode: "token"` ou `"password"`.
Pour ce chemin d’identité Serve asynchrone, les tentatives d’authentification échouées pour la même IP cliente et la même portée d’authentification sont sérialisées avant les écritures de limitation de débit. Des nouvelles tentatives incorrectes concurrentes depuis le même navigateur peuvent donc afficher `retry later` sur la deuxième requête au lieu de deux simples non-correspondances en concurrence parallèle.
Pour ce chemin d’identité Serve asynchrone, les tentatives d’authentification échouées pour la même IP cliente et la même portée d’authentification sont sérialisées avant les écritures de limitation de débit. Des nouvelles tentatives incorrectes simultanées depuis le même navigateur peuvent donc afficher `retry later` sur la deuxième requête au lieu de deux simples incompatibilités en concurrence parallèle.
<Warning>
L’authentification Serve sans token suppose que l’hôte gateway est approuvé. Si du code local non approuvé peut s’exécuter sur cet hôte, exigez une authentification par token/mot de passe.
L’authentification Serve sans jeton suppose que l’hôte du gateway est fiable. Si du code local non fiable peut s’exécuter sur cet hôte, exigez une authentification par jeton/mot de passe.
</Warning>
</Tab>
<Tab title="Lier au tailnet + token">
<Tab title="Bind to tailnet + token">
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
Ouvrez ensuite :
Ouvrez :
- `http://<tailscale-ip>:18789/` (ou votre `gateway.controlUi.basePath` configuré)
Collez le secret partagé correspondant dans les paramètres de l’interface utilisateur (envoyé comme `connect.params.auth.token` ou `connect.params.auth.password`).
Collez le secret partagé correspondant dans les paramètres de l’UI (envoyé comme `connect.params.auth.token` ou `connect.params.auth.password`).
</Tab>
</Tabs>
## HTTP non sécurisé
Si vous ouvrez le tableau de bord en HTTP simple (`http://<lan-ip>` ou `http://<tailscale-ip>`), le navigateur s’exécute dans un **contexte non sécurisé** et bloque WebCrypto. Par défaut, OpenClaw **bloque** les connexions à Control UI sans identité d’appareil.
Si vous ouvrez le tableau de bord en HTTP simple (`http://<lan-ip>` ou `http://<tailscale-ip>`), le navigateur s’exécute dans un **contexte non sécurisé** et bloque WebCrypto. Par défaut, OpenClaw **bloque** les connexions de l’UI de contrôle sans identité d’appareil.
Exceptions documentées :
- compatibilité HTTP non sécurisé limitée à localhost avec `gateway.controlUi.allowInsecureAuth=true`
- authentification Control UI opérateur réussie via `gateway.auth.mode: "trusted-proxy"`
- authentification réussie de l’opérateur dans l’UI de contrôle via `gateway.auth.mode: "trusted-proxy"`
- option d’urgence `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Correction recommandée :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’interface utilisateur localement :
**Correctif recommandé :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’UI localement :
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (sur l’hôte du gateway)
<AccordionGroup>
<Accordion title="Comportement du commutateur d’authentification non sécurisée">
<Accordion title="Comportement de l’option d’authentification non sécurisée">
```json5
{
gateway: {
@ -339,11 +339,11 @@ Exceptions documentées :
}
```
`allowInsecureAuth` est uniquement un commutateur de compatibilité locale :
`allowInsecureAuth` est uniquement une option de compatibilité locale :
- Il permet aux sessions Control UI localhost de continuer sans identité d’appareil dans des contextes HTTP non sécurisés.
- Il ne contourne pas les vérifications d’appairage.
- Il n’assouplit pas les exigences d’identité d’appareil distant (non-localhost).
- Elle permet aux sessions localhost de l’UI de contrôle de continuer sans identité d’appareil dans les contextes HTTP non sécurisés.
- Elle ne contourne pas les vérifications d’appairage.
- Elle n’assouplit pas les exigences d’identité d’appareil distant (non-localhost).
</Accordion>
<Accordion title="Urgence uniquement">
@ -358,14 +358,14 @@ Exceptions documentées :
```
<Warning>
`dangerouslyDisableDeviceAuth` désactive les vérifications d’identité d’appareil de Control UI et constitue une forte dégradation de la sécurité. Rétablissez rapidement la configuration après une utilisation d’urgence.
`dangerouslyDisableDeviceAuth` désactive les vérifications d’identité d’appareil de l’UI de contrôle et constitue une dégradation de sécurité majeure. Rétablissez rapidement la configuration après une utilisation d’urgence.
</Warning>
</Accordion>
<Accordion title="Note sur le proxy de confiance">
- Une authentification trusted-proxy réussie peut autoriser des sessions Control UI **opérateur** sans identité d’appareil.
- Cela ne s’étend **pas** aux sessions Control UI avec rôle de node.
- Les proxies inverses loopback sur le même hôte ne satisfont toujours pas l’authentification trusted-proxy ; consultez [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth).
- Une authentification trusted-proxy réussie peut autoriser des sessions **opérateur** de l’UI de contrôle sans identité d’appareil.
- Cela ne s’étend **pas** aux sessions de l’UI de contrôle avec rôle de nœud.
- Les proxys inverses loopback sur le même hôte ne satisfont toujours pas l’authentification trusted-proxy ; consultez [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth).
</Accordion>
</AccordionGroup>
@ -374,38 +374,38 @@ Consultez [Tailscale](/fr/gateway/tailscale) pour des conseils de configuration
## Politique de sécurité du contenu
Control UI est livré avec une politique `img-src` stricte : seuls les éléments **same-origin**, les URL `data:` et les URL `blob:` générées localement sont autorisés. Les URL d’image distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et ne déclenchent pas de requêtes réseau.
L’UI de contrôle est fournie avec une politique `img-src` stricte : seuls les éléments **same-origin**, les URL `data:` et les URL `blob:` générées localement sont autorisés. Les URL d’images distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et ne déclenchent aucune récupération réseau.
Ce que cela signifie en pratique :
- Les avatars et images servis sous des chemins relatifs (par exemple `/avatars/<id>`) s’affichent toujours, y compris les routes d’avatar authentifiées que l’interface utilisateur récupère et convertit en URL `blob:` locales.
- Les avatars et images servis sous des chemins relatifs (par exemple `/avatars/<id>`) s’affichent toujours, y compris les routes d’avatars authentifiées que l’UI récupère et convertit en URL `blob:` locales.
- Les URL `data:image/...` en ligne s’affichent toujours (utile pour les charges utiles intégrées au protocole).
- Les URL `blob:` locales créées par Control UI s’affichent toujours.
- Les URL d’avatar distantes émises par les métadonnées de canal sont supprimées par les assistants d’avatar de Control UI et remplacées par le logo/badge intégré, afin qu’un canal compromis ou malveillant ne puisse pas forcer des récupérations d’images distantes arbitraires depuis le navigateur d’un opérateur.
- Les URL `blob:` locales créées par l’UI de contrôle s’affichent toujours.
- Les URL d’avatars distantes émises par les métadonnées de canal sont supprimées par les assistants d’avatar de l’UI de contrôle et remplacées par le logo/badge intégré ; ainsi, un canal compromis ou malveillant ne peut pas forcer des récupérations arbitraires d’images distantes depuis le navigateur d’un opérateur.
Vous n’avez rien à modifier pour obtenir ce comportement : il est toujours activé et n’est pas configurable.
Vous n’avez rien à modifier pour obtenir ce comportement — il est toujours activé et n’est pas configurable.
## Authentification de la route d’avatar
Lorsque l’authentification Gateway est configurée, le point de terminaison d’avatar de Control UI exige le même jeton Gateway que le reste de l’API :
Lorsque l’authentification du gateway est configurée, le point de terminaison d’avatar de l’UI de contrôle exige le même jeton de gateway que le reste de l’API :
- `GET /avatar/<agentId>` renvoie l’image d’avatar uniquement aux appelants authentifiés. `GET /avatar/<agentId>?meta=1` renvoie les métadonnées d’avatar selon la même règle.
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme la route sœur assistant-media). Cela empêche la route d’avatar de divulguer l’identité de l’agent sur des hôtes par ailleurs protégés.
- Control UI transmet lui-même le jeton Gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URL blob authentifiées afin que l’image s’affiche toujours dans les tableaux de bord.
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme pour la route sœur des médias d’assistant). Cela empêche la route d’avatar de divulguer l’identité d’un agent sur des hôtes qui sont autrement protégés.
- L’UI de contrôle elle-même transmet le jeton de gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URL blob authentifiées afin que l’image s’affiche toujours dans les tableaux de bord.
Si vous désactivez l’authentification Gateway (non recommandé sur les hôtes partagés), la route d’avatar devient également non authentifiée, comme le reste du Gateway.
Si vous désactivez l’authentification du gateway (déconseillé sur les hôtes partagés), la route d’avatar devient elle aussi non authentifiée, conformément au reste du gateway.
## Authentification de la route média de l’assistant
## Authentification de la route des médias d’assistant
Lorsque l’authentification Gateway est configurée, les aperçus de médias locaux de l’assistant utilisent une route en deux étapes :
Lorsque l’authentification du gateway est configurée, les aperçus de médias locaux de l’assistant utilisent une route en deux étapes :
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` exige l’authentification opérateur Control UI normale. Le navigateur envoie le jeton Gateway comme en-tête bearer lors de la vérification de disponibilité.
- Les réponses de métadonnées réussies incluent un `mediaTicket` de courte durée, limité à ce chemin source exact.
- Les URL d’image, d’audio, de vidéo et de document rendues par le navigateur utilisent `mediaTicket=<ticket>` au lieu du jeton ou du mot de passe Gateway actif. Le ticket expire rapidement et ne peut pas autoriser une autre source.
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` exige l’authentification opérateur normale de l’UI de contrôle. Le navigateur envoie le jeton de gateway comme en-tête bearer lors de la vérification de disponibilité.
- Les réponses de métadonnées réussies incluent un `mediaTicket` de courte durée limité à ce chemin source exact.
- Les URL d’images, d’audio, de vidéo et de documents rendues par le navigateur utilisent `mediaTicket=<ticket>` au lieu du jeton ou mot de passe de gateway actif. Le ticket expire rapidement et ne peut pas autoriser une autre source.
Cela permet au rendu média normal de rester compatible avec les éléments multimédias natifs du navigateur sans placer d’identifiants Gateway réutilisables dans des URL média visibles.
Cela maintient la compatibilité du rendu normal des médias avec les éléments multimédias natifs du navigateur, sans placer d’identifiants réutilisables du gateway dans des URL de médias visibles.
## Construire l’interface utilisateur
## Construire l’UI
Le Gateway sert les fichiers statiques depuis `dist/control-ui`. Construisez-les avec :
@ -413,7 +413,7 @@ Le Gateway sert les fichiers statiques depuis `dist/control-ui`. Construisez-les
pnpm ui:build
```
Base absolue facultative (lorsque vous voulez des URL d’assets fixes) :
Base absolue facultative (lorsque vous voulez des URL de ressources fixes) :
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -425,14 +425,14 @@ Pour le développement local (serveur de développement séparé) :
pnpm ui:dev
```
Pointez ensuite l’interface utilisateur vers votre URL WS du Gateway (par ex. `ws://127.0.0.1:18789`).
Pointez ensuite l’UI vers votre URL WS de Gateway (par exemple `ws://127.0.0.1:18789`).
## Débogage/tests : serveur de développement + Gateway distant
Control UI est composé de fichiers statiques ; la cible WebSocket est configurable et peut différer de l’origine HTTP. C’est pratique lorsque vous voulez utiliser le serveur de développement Vite localement alors que le Gateway s’exécute ailleurs.
L’UI de contrôle est constituée de fichiers statiques ; la cible WebSocket est configurable et peut être différente de l’origine HTTP. C’est pratique lorsque vous voulez utiliser le serveur de développement Vite localement, tandis que le Gateway s’exécute ailleurs.
<Steps>
<Step title="Démarrer le serveur de développement de l’interface utilisateur">
<Step title="Démarrer le serveur de développement de l’UI">
```bash
pnpm ui:dev
```
@ -455,14 +455,14 @@ Control UI est composé de fichiers statiques ; la cible WebSocket est configura
<Accordion title="Notes">
- `gatewayUrl` est stocké dans localStorage après le chargement, puis supprimé de l’URL.
- Si vous transmettez un point de terminaison complet `ws://` ou `wss://` via `gatewayUrl`, encodez en URL la valeur de `gatewayUrl` afin que le navigateur analyse correctement la chaîne de requête.
- `token` doit être transmis via le fragment d’URL (`#token=...`) chaque fois que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites dans les journaux de requêtes et le Referer. Les paramètres de requête hérités `?token=` sont toujours importés une fois pour compatibilité, mais uniquement comme solution de repli, et sont supprimés immédiatement après le bootstrap.
- `password` est conservé en mémoire uniquement.
- Lorsque `gatewayUrl` est défini, l’interface utilisateur ne se rabat pas sur les identifiants de configuration ou d’environnement. Fournissez explicitement `token` (ou `password`). L’absence d’identifiants explicites est une erreur.
- `token` doit être transmis via le fragment d’URL (`#token=...`) chaque fois que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites dans les journaux de requêtes et le Referer. Les anciens paramètres de requête `?token=` sont toujours importés une fois pour compatibilité, mais uniquement comme solution de secours, et sont supprimés immédiatement après l’amorçage.
- `password` est conservé uniquement en mémoire.
- Lorsque `gatewayUrl` est défini, l’UI ne se rabat pas sur les identifiants de configuration ou d’environnement. Fournissez explicitement `token` (ou `password`). L’absence d’identifiants explicites est une erreur.
- Utilisez `wss://` lorsque le Gateway est derrière TLS (Tailscale Serve, proxy HTTPS, etc.).
- `gatewayUrl` n’est accepté que dans une fenêtre de premier niveau (non intégrée) afin d’empêcher le clickjacking.
- Les déploiements Control UI non-loopback doivent définir explicitement `gateway.controlUi.allowedOrigins` (origines complètes). Cela inclut les configurations de développement distantes.
- Le démarrage du Gateway peut préremplir des origines locales telles que `http://localhost:<port>` et `http://127.0.0.1:<port>` à partir de l’adresse et du port effectifs liés à l’exécution, mais les origines de navigateurs distants nécessitent toujours des entrées explicites.
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]` sauf pour des tests locaux strictement contrôlés. Cela signifie autoriser toute origine de navigateur, et non « correspondre à l’hôte que j’utilise ».
- Les déploiements non-loopback de l’UI de contrôle doivent définir explicitement `gateway.controlUi.allowedOrigins` (origines complètes). Cela inclut les configurations de développement distantes.
- Le démarrage du Gateway peut initialiser des origines locales comme `http://localhost:<port>` et `http://127.0.0.1:<port>` à partir du bind et du port effectifs à l’exécution, mais les origines de navigateur distantes nécessitent toujours des entrées explicites.
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]`, sauf pour des tests locaux très contrôlés. Cela signifie autoriser toute origine de navigateur, et non « faire correspondre l’hôte que j’utilise ».
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` active le mode de repli d’origine basé sur l’en-tête Host, mais c’est un mode de sécurité dangereux.
</Accordion>
@ -484,7 +484,7 @@ Détails de configuration de l’accès distant : [Accès distant](/fr/gateway/r
## Connexe
- [Tableau de bord](/fr/web/dashboard) — tableau de bord Gateway
- [Contrôles de santé](/fr/gateway/health) — surveillance de l’état du gateway
- [Tableau de bord](/fr/web/dashboard) — tableau de bord du gateway
- [Vérifications d’état](/fr/gateway/health) — surveillance de l’état du gateway
- [TUI](/fr/web/tui) — interface utilisateur de terminal
- [WebChat](/fr/web/webchat) — interface de chat basée sur le navigateur
- [WebChat](/fr/web/webchat) — interface de discussion basée sur le navigateur