diff --git a/docs/fr/automation/tasks.md b/docs/fr/automation/tasks.md
index b09f3c14e..ce372e547 100644
--- a/docs/fr/automation/tasks.md
+++ b/docs/fr/automation/tasks.md
@@ -1,15 +1,15 @@
---
read_when:
- Inspection du travail en arrière-plan en cours ou récemment terminé
- - Débogage des échecs de livraison pour les exécutions d'agent détachées
- - Compréhension de la relation entre les exécutions en arrière-plan, les sessions, cron et heartbeat
+ - Débogage des échecs de livraison pour les exécutions d’agent détachées
+ - Comprendre comment les exécutions en arrière-plan sont liées aux sessions, aux tâches cron et au signal de pulsation
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-04-06T03:06:38Z"
+ generated_at: "2026-04-10T06:56:13Z"
model: gpt-5.4
provider: openai
- source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
+ source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
source_path: automation/tasks.md
workflow: 15
---
@@ -18,29 +18,25 @@ x-i18n:
> **Vous cherchez la planification ?** Consultez [Automatisation et tâches](/fr/automation) pour choisir le bon mécanisme. Cette page couvre le **suivi** du travail en arrière-plan, pas sa planification.
-Les tâches en arrière-plan suivent le travail qui s'exécute **en dehors de votre session de conversation principale** :
+Les tâches en arrière-plan suivent le travail qui s’exécute **en dehors de votre session de conversation principale** :
les exécutions ACP, les lancements de sous-agents, les exécutions de tâches cron isolées et les opérations initiées par la CLI.
-Les tâches ne remplacent **pas** les sessions, les tâches cron ou les heartbeat — elles constituent le **journal d'activité** qui enregistre 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 ou les signaux de pulsation — elles constituent le **journal d’activité** qui enregistre quel travail détaché a eu lieu, quand, et s’il a réussi.
-Toutes les exécutions d'agent ne créent pas une tâche. Les tours de heartbeat et le chat interactif normal n'en créent pas. Toutes les exécutions cron, tous les lancements ACP, tous les lancements de sous-agents et toutes les commandes d'agent CLI en créent.
+Toutes les exécutions d’agent ne créent pas une tâche. Les tours de signal de pulsation et le chat interactif normal n’en créent pas. Toutes les exécutions cron, tous les lancements ACP, tous les lancements de sous-agents et toutes les commandes d’agent via la CLI en créent.
-## En bref
+## TL;DR
-- Les tâches sont des **enregistrements**, pas des planificateurs — cron et heartbeat décident _quand_ le travail s'exécute, les tâches suivent _ce qui s'est passé_.
-- ACP, les sous-agents, toutes les tâches cron et les opérations CLI créent des tâches. Les tours de heartbeat n'en créent pas.
+- Les tâches sont des **enregistrements**, pas des planificateurs — cron et le signal de pulsation 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 de signal de pulsation 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 encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d'exécution propriétaire est encore actif.
-- L'achèvement est piloté par poussée : le travail détaché peut notifier directement ou réveiller
- la session demandeuse/le heartbeat lorsqu'il se termine, donc les boucles de
- sondage de statut ont généralement une mauvaise forme.
-- 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 le nettoyage final de comptabilisation.
-- La livraison des exécutions cron isolées supprime les réponses intermédiaires parentes obsolètes pendant que le
- travail de sous-agents descendants continue de s'écouler, et elle préfère la sortie finale descendante
- lorsqu'elle arrive avant la livraison.
-- Les notifications d'achèvement sont envoyées directement à un canal ou mises en file d'attente pour le prochain heartbeat.
+- Les tâches cron restent actives tant que l’environnement d’exécution cron possède encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d’exécution propriétaire est encore actif.
+- La fin d’exécution est pilotée par envoi : le travail détaché peut notifier directement ou réveiller la session/le signal de pulsation du demandeur lorsqu’il se termine, donc les boucles d’interrogation d’état sont généralement une mauvaise approche.
+- Les exécutions cron isolées et les fins d’exécution de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant le nettoyage final.
+- La livraison des exécutions cron isolées supprime les réponses intermédiaires parent obsolètes pendant que le travail des sous-agents descendants est encore en cours de vidage, et elle privilégie la sortie finale descendante lorsqu’elle arrive avant la livraison.
+- Les notifications de fin d’exécution sont livrées directement à un canal ou mises en file d’attente pour le prochain signal de pulsation.
- `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 supprimés.
@@ -50,17 +46,17 @@ Toutes les exécutions d'agent ne créent pas une tâche. Les tours de heartbeat
# Lister toutes les tâches (de la plus récente à la plus ancienne)
openclaw tasks list
-# Filtrer par environnement d'exécution ou statut
+# Filtrer par environnement d’exécution ou statut
openclaw tasks list --runtime acp
openclaw tasks list --status running
-# Afficher les détails d'une tâche spécifique (par ID, ID d'exécution ou clé de session)
+# Afficher les détails d’une tâche spécifique (par ID, ID d’exécution ou clé de session)
openclaw tasks show
-# Annuler une tâche en cours (tue la session enfant)
+# Annuler une tâche en cours d’exécution (tue la session enfant)
openclaw tasks cancel
-# Modifier la politique de notification pour une tâche
+# Modifier la politique de notification d’une tâche
openclaw tasks notify state_changes
# Exécuter un audit de santé
@@ -70,7 +66,7 @@ openclaw tasks audit
openclaw tasks maintenance
openclaw tasks maintenance --apply
-# Inspecter l'état de TaskFlow
+# Inspecter l’état de TaskFlow
openclaw tasks flow list
openclaw tasks flow show
openclaw tasks flow cancel
@@ -78,86 +74,84 @@ openclaw tasks flow cancel
## Ce qui crée une tâche
-| Source | Type d'exécution | Moment de création d'un enregistrement de tâche | Politique de notification par défaut |
-| ------------------------ | ---------------- | ------------------------------------------------------ | ------------------------------------ |
-| Exécutions ACP en arrière-plan | `acp` | Lancement d'une session enfant ACP | `done_only` |
-| Orchestration de 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 la gateway | `silent` |
-| Tâches média de l'agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
+| Source | Type d’environnement 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 ACP enfant | `done_only` |
+| Orchestration de 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` exécutées via la passerelle | `silent` |
+| Tâches média d’agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
-Les tâches cron de session principale utilisent `silent` comme politique de notification 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 elles sont plus visibles car elles s'exécutent dans leur propre session.
+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 sont plus visibles parce qu’elles s’exécutent dans leur propre session.
-Les exécutions `video_generate` adossées à une session utilisent également `silent` comme politique de notification. 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 la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les achèvements asynchrones de `music_generate` et `video_generate` essaient d'abord la livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
+Les exécutions `video_generate` adossées à une session utilisent également la politique de notification `silent`. Elles créent tout de même des enregistrements de tâche, mais la fin d’exécution est renvoyée à la session d’agent d’origine sous forme de réveil interne afin que l’agent puisse lui-même écrire le message de suivi et joindre la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les fins d’exécution asynchrones de `music_generate` et `video_generate` tentent d’abord une livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
-Tant qu'une tâche `video_generate` adossée à une session est encore active, l'outil agit aussi comme garde-fou : les appels répétés à `video_generate` dans cette même session renvoient le statut 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/statut côté agent.
+Tant qu’une tâche `video_generate` adossée à une session est encore active, l’outil sert aussi de garde-fou : des appels `video_generate` répétés dans cette même session renvoient le statut de la tâche active au lieu de démarrer une deuxième génération concurrente. Utilisez `action: "status"` si vous voulez une consultation explicite de progression/statut côté agent.
**Ce qui ne crée pas de tâches :**
-- Les tours de heartbeat — session principale ; voir [Heartbeat](/fr/gateway/heartbeat)
+- Les tours de signal de pulsation — session principale ; voir [Signal de pulsation](/fr/gateway/heartbeat)
- Les tours de chat interactif normaux
-- Les réponses directes à `/command`
+- Les réponses directes `/command`
-## Cycle de vie d'une tâche
+## Cycle de vie d’une tâche
```mermaid
stateDiagram-v2
[*] --> queued
- queued --> running : l'agent démarre
+ queued --> running : l’agent démarre
running --> succeeded : se termine correctement
running --> failed : erreur
- running --> timed_out : délai d'attente dépassé
- running --> cancelled : l'opérateur annule
+ running --> timed_out : délai dépassé
+ running --> cancelled : l’opérateur annule
queued --> lost : session disparue > 5 min
running --> lost : session disparue > 5 min
```
-| Statut | Ce qu'il signifie |
-| ----------- | -------------------------------------------------------------------------- |
-| `queued` | Créée, en attente du démarrage de l'agent |
-| `running` | Le tour de l'agent est en cours d'exécution |
-| `succeeded` | Terminée avec succès |
-| `failed` | Terminée avec une erreur |
-| `timed_out` | A dépassé le délai d'attente configuré |
-| `cancelled` | Arrêtée par l'opérateur via `openclaw tasks cancel` |
-| `lost` | L'environnement d'exécution a perdu l'état d'autorité de référence après un délai de grâce de 5 minutes |
+| Statut | Ce que cela signifie |
+| ----------- | ------------------------------------------------------------------------ |
+| `queued` | Créée, en attente du démarrage de l’agent |
+| `running` | Le tour de l’agent est en cours d’exécution |
+| `succeeded` | Terminée avec succès |
+| `failed` | Terminée avec une erreur |
+| `timed_out` | A dépassé le délai 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 |
-Les transitions se produisent automatiquement — lorsque l'exécution d'agent associée se termine, le statut de la tâche est mis à jour pour correspondre.
+Les transitions se produisent automatiquement — lorsque l’exécution d’agent associée se termine, le statut de la tâche est mis à jour pour correspondre.
-`lost` dépend de l'environnement d'exécution :
+`lost` dépend de l’environnement d’exécution :
-- Tâches ACP : les métadonnées de la session enfant ACP de référence ont disparu.
-- Tâches de sous-agent : la session enfant de référence a disparu du magasin de l'agent cible.
-- Tâches cron : l'environnement d'exécution cron ne suit plus la tâche comme active.
-- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent à la place le contexte d'exécution actif, donc des lignes persistantes de session canal/groupe/direct ne les maintiennent pas actives.
+- Tâches ACP : les métadonnées de la session ACP enfant de support ont disparu.
+- Tâches de sous-agents : 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.
+- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent à la place le contexte d’exécution actif, donc des lignes persistantes de session canal/groupe/direct ne les maintiennent pas actives.
## 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 en informe. Il existe deux chemins de livraison :
-**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message d'achèvement est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les achèvements de sous-agents, OpenClaw préserve aussi le routage lié de fil/sujet quand il est disponible et peut renseigner un `to` / compte manquant à partir de la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d'abandonner la livraison directe.
+**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message de fin d’exécution est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les fins d’exécution de sous-agents, OpenClaw préserve également le routage de fil/topic lié lorsqu’il est disponible et peut compléter un `to` / compte manquant à partir de la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d’abandonner la livraison directe.
-**Livraison mise en file d'attente dans la 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 dans la 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 signal de pulsation.
-L'achèvement d'une tâche déclenche un réveil immédiat du heartbeat afin que vous voyiez rapidement le résultat — vous n'avez pas besoin d'attendre le prochain tick planifié du heartbeat.
+La fin d’exécution d’une tâche déclenche un réveil immédiat du signal de pulsation afin que vous voyiez le résultat rapidement — vous n’avez pas à attendre le prochain tick planifié du signal de pulsation.
-Cela signifie que le flux de travail habituel est piloté par poussée : lancez le travail détaché une seule fois, puis laissez
-l'environnement d'exécution vous réveiller ou vous notifier à l'achèvement. Ne sondez l'état d'une tâche que lorsque vous
-avez besoin de débogage, d'intervention ou d'un audit explicite.
+Cela signifie que le flux habituel repose sur l’envoi : démarrez le travail détaché une seule fois, puis laissez l’environnement d’exécution vous réveiller ou vous notifier à la fin. Interrogez l’état des tâches seulement si 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 la quantité d’informations que vous recevez pour chaque tâche :
-| Politique | Ce qui est livré |
-| --------------------- | ------------------------------------------------------------------------- |
-| `done_only` (par défaut) | Uniquement l'état terminal (`succeeded`, `failed`, etc.) — **c'est la valeur par défaut** |
-| `state_changes` | Chaque transition d'état et chaque mise à jour de progression |
-| `silent` | Rien du tout |
+| Politique | Ce qui est livré |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `done_only` (par défaut) | Seulement l’état terminal (`succeeded`, `failed`, etc.) — **c’est la valeur par défaut** |
+| `state_changes` | Chaque transition d’état et chaque mise à jour de progression |
+| `silent` | Rien du tout |
-Modifiez la politique pendant l'exécution d'une tâche :
+Modifiez la politique pendant qu’une tâche est en cours d’exécution :
```bash
openclaw tasks notify state_changes
@@ -171,7 +165,7 @@ openclaw tasks notify state_changes
openclaw tasks list [--runtime ] [--status ] [--json]
```
-Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d'exécution, Session enfant, Résumé.
+Colonnes de sortie : ID de tâche, type, statut, livraison, ID d’exécution, session enfant, résumé.
### `tasks show`
@@ -179,7 +173,7 @@ Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d'exécution, Ses
openclaw tasks show
```
-Le jeton de recherche accepte un ID de tâche, un ID d'exécution ou une clé de session. Affiche l'enregistrement complet, y compris 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, y compris le minutage, l’état de livraison, l’erreur et le résumé terminal.
### `tasks cancel`
@@ -187,7 +181,7 @@ Le jeton de recherche accepte un ID de tâche, un ID d'exécution ou une clé de
openclaw tasks cancel
```
-Pour les tâches ACP et de sous-agent, cela tue la session enfant. Le statut passe à `cancelled` et une notification de livraison est envoyée.
+Pour les tâches ACP et de sous-agents, 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’environnement d’exécution enfant distinct). Le statut passe à `cancelled` et une notification de livraison est envoyée le cas échéant.
### `tasks notify`
@@ -201,16 +195,16 @@ openclaw tasks notify
openclaw tasks audit [--json]
```
-Fait remonter les problèmes opérationnels. Les résultats apparaissent aussi dans `openclaw status` lorsque des problèmes sont détectés.
+Fait remonter les problèmes opérationnels. Les constatations apparaissent également dans `openclaw status` lorsque des problèmes sont détectés.
-| Résultat | Gravité | Déclencheur |
+| Constatation | 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` | error | La propriété de tâche adossée à l'environnement d'exécution a disparu |
-| `delivery_failed` | warn | La livraison a échoué et la politique de notification n'est pas `silent` |
+| `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` | error | La propriété de tâche adossée à l’environnement d’exécution a disparu |
+| `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 la chronologie (par exemple terminée avant d'avoir commencé) |
+| `inconsistent_timestamps` | warn | Violation de chronologie (par exemple, fin avant démarrage) |
### `tasks maintenance`
@@ -219,22 +213,20 @@ openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
-Utilisez cette commande pour prévisualiser ou appliquer la réconciliation, l'horodatage de nettoyage et la suppression
-pour les tâches et l'état de Task Flow.
+Utilisez cette commande pour prévisualiser ou appliquer la réconciliation, l’horodatage du nettoyage et l’élagage des tâches ainsi que de l’état de Task Flow.
-La réconciliation dépend de l'environnement d'exécution :
+La réconciliation dépend de l’environnement d’exécution :
-- Les tâches ACP/sous-agent vérifient leur session enfant de référence.
-- Les tâches cron vérifient si l'environnement d'exécution cron possède encore la tâche.
-- 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-agents vérifient leur session enfant de support.
+- Les tâches cron vérifient si l’environnement d’exécution cron possède encore la tâche.
+- Les tâches CLI adossées au chat vérifient le contexte d’exécution actif propriétaire, et pas seulement la ligne de session de chat.
-Le nettoyage à l'achèvement dépend aussi de l'environnement d'exécution :
+Le nettoyage de fin d’exécution dépend aussi de l’environnement d’exécution :
-- L'achèvement d'un sous-agent ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage d'annonce ne continue.
-- L'achèvement d'une exécution cron isolée ferme au mieux les onglets/processus de navigateur suivis pour la session cron avant que l'exécution ne soit complètement démontée.
-- La livraison des exécutions cron isolées attend, si nécessaire, le suivi descendant des sous-agents et
- supprime le texte d'accusé de réception parent obsolète au lieu de l'annoncer.
-- La livraison de l'achèvement d'un sous-agent privilégie le dernier texte visible de l'assistant ; s'il est vide, elle revient à un texte assaini de dernier `tool`/`toolResult`, et les exécutions composées uniquement d'appels d'outil avec expiration de délai peuvent être réduites à un court résumé de progression partielle.
+- La fin d’exécution d’un sous-agent ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage de l’annonce se poursuive.
+- La fin d’exécution d’une tâche cron isolée ferme au mieux les onglets/processus de navigateur suivis pour la session cron avant que l’exécution ne soit complètement démontée.
+- La livraison d’une tâche cron isolée attend au besoin la fin du suivi des sous-agents descendants et supprime le texte d’accusé de réception parent obsolète au lieu de l’annoncer.
+- La livraison de fin d’exécution d’un sous-agent privilégie le dernier texte visible de l’assistant ; s’il est vide, elle se rabat sur le dernier texte `tool`/`toolResult` assaini, et les exécutions limitées à des appels d’outil ayant expiré peuvent être réduites à un court résumé de progression partielle.
- Les échecs de nettoyage ne masquent pas le véritable résultat de la tâche.
### `tasks flow list|show|cancel`
@@ -245,91 +237,90 @@ openclaw tasks flow show [--json]
openclaw tasks flow cancel
```
-Utilisez ces commandes lorsque l'élément qui vous intéresse est le Task Flow orchestrateur
-plutôt qu'un enregistrement individuel de tâche en arrière-plan.
+Utilisez ces commandes lorsque c’est le Task Flow orchestrateur qui vous intéresse plutôt qu’un enregistrement individuel de tâche en arrière-plan.
## Tableau des tâches de 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 l'environnement d'exécution, le statut, le minutage 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’environnement d’exécution, le statut, le minutage, ainsi que les détails de progression ou d’erreur.
-Lorsque la session actuelle n'a aucune tâche liée visible, `/tasks` revient aux comptages de tâches locales à l'agent
-afin que vous obteniez tout de même une vue d'ensemble sans divulguer les détails des autres sessions.
+Lorsque la session actuelle n’a aucune tâche liée visible, `/tasks` se rabat sur les comptes de tâches locaux à l’agent
+afin que vous conserviez une vue d’ensemble sans divulguer les détails d’autres sessions.
Pour le journal opérateur complet, utilisez la CLI : `openclaw tasks list`.
## Intégration au statut (pression des tâches)
-`openclaw status` inclut un résumé des tâches visible en un coup d'œil :
+`openclaw status` inclut un résumé des tâches visible en un coup d’œil :
```
Tasks: 3 queued · 2 running · 1 issues
```
-Le résumé signale :
+Le résumé indique :
- **active** — nombre de `queued` + `running`
- **failures** — nombre de `failed` + `timed_out` + `lost`
- **byRuntime** — répartition par `acp`, `subagent`, `cron`, `cli`
-`/status` comme l'outil `session_status` utilisent un instantané des tâches sensible au 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'aucun travail actif
-ne reste. Cela permet à la carte de statut de rester centré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 ne remontent que lorsqu’il ne reste plus aucun travail actif.
+Cela permet à la carte de statut de rester centrée sur ce qui compte maintenant.
## Stockage et maintenance
-### Emplacement des tâches
+### Où vivent les tâches
-Les enregistrements de tâche persistent dans SQLite à l'emplacement suivant :
+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 de la gateway et synchronise les écritures vers SQLite pour garantir la durabilité entre les redémarrages.
+Le registre est chargé en mémoire au démarrage de la passerelle et synchronise les écritures vers SQLite pour garantir la durabilité entre les redémarrages.
### Maintenance automatique
-Un nettoyeur s'exécute toutes les **60 secondes** et gère trois choses :
+Un balayage s’exécute toutes les **60 secondes** et gère trois éléments :
-1. **Réconciliation** — vérifie si les tâches actives ont toujours un état de référence faisant autorité dans l'environnement d'exécution. Les tâches ACP/sous-agent utilisent l'état de la session enfant, les tâches cron utilisent la propriété de tâche active, et les tâches CLI adossées au chat utilisent le contexte d'exécution propriétaire. Si cet état de référence a disparu depuis plus de 5 minutes, la tâche est marquée `lost`.
-2. **Horodatage de nettoyage** — définit un horodatage `cleanupAfter` sur les tâches terminales (`endedAt` + 7 jours).
-3. **Suppression** — supprime les enregistrements au-delà de leur date `cleanupAfter`.
+1. **Réconciliation** — vérifie si les tâches actives ont encore un support d’exécution faisant autorité. Les tâches ACP/sous-agents utilisent l’état de la session enfant, les tâches cron utilisent la possession de tâche active, et les tâches CLI adossées au chat utilisent le contexte d’exécution propriétaire. Si cet état de support a disparu pendant plus de 5 minutes, la tâche est marquée `lost`.
+2. **Horodatage du nettoyage** — définit un horodatage `cleanupAfter` sur les tâches terminales (`endedAt + 7 days`).
+3. **Élagage** — supprime les enregistrements ayant dépassé leur date `cleanupAfter`.
-**Rétention** : les enregistrements de tâche terminaux sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration nécessaire.
+**Rétention** : les enregistrements de tâches terminales sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration nécessaire.
-## Comment les tâches se rapportent aux autres systèmes
+## Comment les tâches sont liées aux autres systèmes
### 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 seul flux peut coordonner plusieurs tâches au cours de sa durée de vie en utilisant des modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements individuels de tâche 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 son cycle de vie à l’aide de modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements individuels de tâches et `openclaw tasks flow` pour inspecter le flux orchestrateur.
-Consultez [Task Flow](/fr/automation/taskflow) pour plus de détails.
+Voir [Task Flow](/fr/automation/taskflow) pour plus de détails.
### Tâches et cron
-Une **définition** de tâche cron se trouve dans `~/.openclaw/cron/jobs.json`. **Chaque** exécution cron crée un enregistrement de tâche — à la fois en session principale et en mode isolé. Les tâches cron de session principale utilisent par défaut la politique de notification `silent`, afin d'assurer le suivi sans générer de notifications.
+Une **définition** de tâche cron vit dans `~/.openclaw/cron/jobs.json`. **Chaque** exécution cron crée un enregistrement de tâche — à la fois pour la session principale et pour les exécutions isolées. Les tâches cron de session principale utilisent par défaut la politique de notification `silent`, de sorte qu’elles sont suivies sans générer de notifications.
-Consultez [Tâches cron](/fr/automation/cron-jobs).
+Voir [Tâches cron](/fr/automation/cron-jobs).
-### Tâches et heartbeat
+### Tâches et signal de pulsation
-Les exécutions heartbeat sont des tours de session principale — elles ne créent pas d'enregistrements de tâche. Lorsqu'une tâche se termine, elle peut déclencher un réveil du heartbeat afin que vous voyiez rapidement le résultat.
+Les exécutions du signal de pulsation sont des tours de session principale — elles ne créent pas d’enregistrements de tâche. Lorsqu’une tâche se termine, elle peut déclencher un réveil du signal de pulsation afin que vous voyiez rapidement le résultat.
-Consultez [Heartbeat](/fr/gateway/heartbeat).
+Voir [Signal de pulsation](/fr/gateway/heartbeat).
### 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 une couche de suivi d'activité au-dessus.
+Une tâche peut référencer une `childSessionKey` (où le travail s’exécute) et une `requesterSessionKey` (qui l’a démarré). Les sessions correspondent au contexte de conversation ; les tâches correspondent au suivi d’activité au-dessus de ce contexte.
-### Tâches et exécutions d'agent
+### Tâches et exécutions d’agent
-Le `runId` d'une tâche la relie à l'exécution d'agent qui effectue le travail. Les événements de cycle de vie de l'agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n'avez pas besoin de gérer manuellement le cycle de vie.
+Le `runId` d’une tâche renvoie à l’exécution d’agent qui effectue le travail. Les événements du cycle de vie de l’agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n’avez pas besoin de gérer manuellement le cycle de vie.
## Liens associés
-- [Automatisation et tâches](/fr/automation) — tous les mécanismes d'automatisation en un coup d'œil
+- [Automatisation et tâches](/fr/automation) — aperçu de tous les mécanismes d’automatisation
- [Task Flow](/fr/automation/taskflow) — orchestration de flux au-dessus des tâches
- [Tâches planifiées](/fr/automation/cron-jobs) — planification du travail en arrière-plan
-- [Heartbeat](/fr/gateway/heartbeat) — tours périodiques de la session principale
+- [Signal de pulsation](/fr/gateway/heartbeat) — tours périodiques de session principale
- [CLI : tâches](/cli/index#tasks) — référence des commandes CLI
diff --git a/docs/fr/concepts/active-memory.md b/docs/fr/concepts/active-memory.md
new file mode 100644
index 000000000..f2256b7f3
--- /dev/null
+++ b/docs/fr/concepts/active-memory.md
@@ -0,0 +1,612 @@
+---
+read_when:
+ - Vous voulez comprendre à quoi sert la mémoire active
+ - Vous voulez activer la mémoire active pour un agent conversationnel
+ - Vous voulez ajuster le comportement de la mémoire active sans l’activer partout
+summary: Un sous-agent de mémoire bloquante appartenant au plugin qui injecte la mémoire pertinente dans les sessions de chat interactives
+title: Mémoire active
+x-i18n:
+ generated_at: "2026-04-10T06:55:58Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
+ source_path: concepts/active-memory.md
+ workflow: 15
+---
+
+# Mémoire active
+
+La mémoire active est un sous-agent de mémoire bloquant optionnel appartenant au plugin, qui s’exécute
+avant la réponse principale pour les sessions conversationnelles admissibles.
+
+Elle existe parce que la plupart des systèmes de mémoire sont capables mais réactifs. Ils s’appuient sur
+l’agent principal pour décider quand rechercher dans la mémoire, ou sur l’utilisateur pour dire des choses
+comme « souviens-toi de ceci » ou « recherche dans la mémoire ». À ce moment-là, l’instant où la mémoire
+aurait rendu la réponse naturelle est déjà passé.
+
+La mémoire active donne au système une occasion limitée de faire remonter une mémoire pertinente
+avant que la réponse principale ne soit générée.
+
+## Collez ceci dans votre agent
+
+Collez ceci dans votre agent si vous voulez activer la mémoire active avec une
+configuration autonome et sûre par défaut :
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ enabled: true,
+ agents: ["main"],
+ allowedChatTypes: ["direct"],
+ modelFallbackPolicy: "default-remote",
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ persistTranscripts: false,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Cela active le plugin pour l’agent `main`, le limite par défaut aux sessions de
+type message direct, lui permet d’hériter d’abord du modèle de la session en cours, et
+autorise toujours le repli distant intégré si aucun modèle explicite ou hérité n’est disponible.
+
+Ensuite, redémarrez la passerelle :
+
+```bash
+node scripts/run-node.mjs gateway --profile dev
+```
+
+Pour l’inspecter en direct dans une conversation :
+
+```text
+/verbose on
+```
+
+## Activer la mémoire active
+
+La configuration la plus sûre consiste à :
+
+1. activer le plugin
+2. cibler un agent conversationnel
+3. garder la journalisation activée uniquement pendant l’ajustement
+
+Commencez avec ceci dans `openclaw.json` :
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ allowedChatTypes: ["direct"],
+ modelFallbackPolicy: "default-remote",
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ persistTranscripts: false,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Puis redémarrez la passerelle :
+
+```bash
+node scripts/run-node.mjs gateway --profile dev
+```
+
+Ce que cela signifie :
+
+- `plugins.entries.active-memory.enabled: true` active le plugin
+- `config.agents: ["main"]` active la mémoire active uniquement pour l’agent `main`
+- `config.allowedChatTypes: ["direct"]` limite par défaut la mémoire active aux sessions de type message direct
+- si `config.model` n’est pas défini, la mémoire active hérite d’abord du modèle de la session en cours
+- `config.modelFallbackPolicy: "default-remote"` conserve le repli distant intégré par défaut lorsqu’aucun modèle explicite ou hérité n’est disponible
+- `config.promptStyle: "balanced"` utilise le style d’invite généraliste par défaut pour le mode `recent`
+- la mémoire active ne s’exécute toujours que sur les sessions de chat persistantes interactives admissibles
+
+## Comment l’afficher
+
+La mémoire active injecte un contexte système caché pour le modèle. Elle n’expose pas
+les balises brutes `...` au client.
+
+## Bascule de session
+
+Utilisez la commande du plugin si vous souhaitez suspendre ou reprendre la mémoire active pour la
+session de chat en cours sans modifier la configuration :
+
+```text
+/active-memory status
+/active-memory off
+/active-memory on
+```
+
+Cela s’applique à la session. Cela ne modifie pas
+`plugins.entries.active-memory.enabled`, le ciblage des agents, ni les autres
+paramètres globaux.
+
+Si vous voulez que la commande écrive dans la configuration et suspendre ou reprendre la mémoire active pour
+toutes les sessions, utilisez la forme globale explicite :
+
+```text
+/active-memory status --global
+/active-memory off --global
+/active-memory on --global
+```
+
+La forme globale écrit dans `plugins.entries.active-memory.config.enabled`. Elle laisse
+`plugins.entries.active-memory.enabled` activé afin que la commande reste disponible pour
+réactiver la mémoire active plus tard.
+
+Si vous voulez voir ce que fait la mémoire active dans une session en direct, activez le mode verbeux
+pour cette session :
+
+```text
+/verbose on
+```
+
+Avec le mode verbeux activé, OpenClaw peut afficher :
+
+- une ligne d’état de la mémoire active telle que `Active Memory: ok 842ms recent 34 chars`
+- un résumé de débogage lisible tel que `Active Memory Debug: Lemon pepper wings with blue cheese.`
+
+Ces lignes proviennent du même passage de mémoire active qui alimente le contexte système
+caché, mais elles sont formatées pour les humains au lieu d’exposer un balisage brut de l’invite.
+
+Par défaut, la transcription du sous-agent de mémoire bloquant est temporaire et supprimée
+une fois l’exécution terminée.
+
+Exemple de déroulement :
+
+```text
+/verbose on
+what wings should i order?
+```
+
+Forme attendue de la réponse visible :
+
+```text
+...normal assistant reply...
+
+🧩 Active Memory: ok 842ms recent 34 chars
+🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
+```
+
+## Quand elle s’exécute
+
+La mémoire active utilise deux portes de contrôle :
+
+1. **Activation par configuration**
+ Le plugin doit être activé, et l’identifiant de l’agent courant doit apparaître dans
+ `plugins.entries.active-memory.config.agents`.
+2. **Admissibilité stricte à l’exécution**
+ Même lorsqu’elle est activée et ciblée, la mémoire active ne s’exécute que pour les
+ sessions de chat persistantes interactives admissibles.
+
+La règle réelle est :
+
+```text
+plugin enabled
++
+agent id targeted
++
+allowed chat type
++
+eligible interactive persistent chat session
+=
+active memory runs
+```
+
+Si l’un de ces éléments échoue, la mémoire active ne s’exécute pas.
+
+## Types de session
+
+`config.allowedChatTypes` contrôle quels types de conversations peuvent exécuter la mémoire active.
+
+La valeur par défaut est :
+
+```json5
+allowedChatTypes: ["direct"]
+```
+
+Cela signifie que la mémoire active s’exécute par défaut dans les sessions de type message direct, mais
+pas dans les sessions de groupe ou de canal, sauf si vous les activez explicitement.
+
+Exemples :
+
+```json5
+allowedChatTypes: ["direct"]
+```
+
+```json5
+allowedChatTypes: ["direct", "group"]
+```
+
+```json5
+allowedChatTypes: ["direct", "group", "channel"]
+```
+
+## Où elle s’exécute
+
+La mémoire active est une fonctionnalité d’enrichissement conversationnel, pas une
+fonctionnalité d’inférence à l’échelle de la plateforme.
+
+| Surface | Exécute la mémoire active ? |
+| ------------------------------------------------------------------- | ------------------------------------------------------- |
+| Sessions persistantes de chat dans l’interface de contrôle / chat web | Oui, si le plugin est activé et que l’agent est ciblé |
+| Autres sessions de canal interactives sur le même chemin de chat persistant | Oui, si le plugin est activé et que l’agent est ciblé |
+| Exécutions sans interface en une seule fois | Non |
+| Exécutions de pulsation / en arrière-plan | Non |
+| Chemins internes génériques `agent-command` | Non |
+| Exécution de sous-agents / d’assistants internes | Non |
+
+## Pourquoi l’utiliser
+
+Utilisez la mémoire active lorsque :
+
+- la session est persistante et destinée à l’utilisateur
+- l’agent dispose d’une mémoire à long terme pertinente à interroger
+- la continuité et la personnalisation comptent plus que le déterminisme brut de l’invite
+
+Elle fonctionne particulièrement bien pour :
+
+- les préférences stables
+- les habitudes récurrentes
+- le contexte utilisateur à long terme qui devrait remonter naturellement
+
+Elle convient mal à :
+
+- l’automatisation
+- les workers internes
+- les tâches d’API en une seule fois
+- les endroits où une personnalisation cachée serait surprenante
+
+## Comment cela fonctionne
+
+La structure à l’exécution est la suivante :
+
+```mermaid
+flowchart LR
+ U["User Message"] --> Q["Build Memory Query"]
+ Q --> R["Active Memory Blocking Memory Sub-Agent"]
+ R -->|NONE or empty| M["Main Reply"]
+ R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
+ I --> M["Main Reply"]
+```
+
+Le sous-agent de mémoire bloquant peut utiliser uniquement :
+
+- `memory_search`
+- `memory_get`
+
+Si la connexion est faible, il doit renvoyer `NONE`.
+
+## Modes de requête
+
+`config.queryMode` contrôle la quantité de conversation que voit le sous-agent de mémoire bloquant.
+
+## Styles d’invite
+
+`config.promptStyle` contrôle à quel point le sous-agent de mémoire bloquant est
+prompt ou strict lorsqu’il décide de renvoyer de la mémoire.
+
+Styles disponibles :
+
+- `balanced` : valeur par défaut généraliste pour le mode `recent`
+- `strict` : le moins prompt ; idéal lorsque vous voulez très peu de contamination par le contexte proche
+- `contextual` : le plus favorable à la continuité ; idéal lorsque l’historique de la conversation doit davantage compter
+- `recall-heavy` : plus enclin à faire remonter de la mémoire sur des correspondances plus faibles mais encore plausibles
+- `precision-heavy` : privilégie fortement `NONE` sauf si la correspondance est évidente
+- `preference-only` : optimisé pour les favoris, les habitudes, les routines, les goûts et les faits personnels récurrents
+
+Correspondance par défaut lorsque `config.promptStyle` n’est pas défini :
+
+```text
+message -> strict
+recent -> balanced
+full -> contextual
+```
+
+Si vous définissez `config.promptStyle` explicitement, cette valeur remplace la correspondance par défaut.
+
+Exemple :
+
+```json5
+promptStyle: "preference-only"
+```
+
+## Politique de repli du modèle
+
+Si `config.model` n’est pas défini, la mémoire active essaie de résoudre un modèle dans cet ordre :
+
+```text
+explicit plugin model
+-> current session model
+-> agent primary model
+-> optional built-in remote fallback
+```
+
+`config.modelFallbackPolicy` contrôle la dernière étape.
+
+Valeur par défaut :
+
+```json5
+modelFallbackPolicy: "default-remote"
+```
+
+Autre option :
+
+```json5
+modelFallbackPolicy: "resolved-only"
+```
+
+Utilisez `resolved-only` si vous voulez que la mémoire active ignore le rappel plutôt que de
+revenir au comportement distant intégré par défaut lorsqu’aucun modèle explicite ou hérité n’est
+disponible.
+
+## Mécanismes d’échappement avancés
+
+Ces options ne font intentionnellement pas partie de la configuration recommandée.
+
+`config.thinking` peut remplacer le niveau de réflexion du sous-agent de mémoire bloquant :
+
+```json5
+thinking: "medium"
+```
+
+Valeur par défaut :
+
+```json5
+thinking: "off"
+```
+
+Ne l’activez pas par défaut. La mémoire active s’exécute dans le chemin de réponse, donc un temps de
+réflexion supplémentaire augmente directement la latence visible par l’utilisateur.
+
+`config.promptAppend` ajoute des instructions opérateur supplémentaires après l’invite par défaut de la mémoire active
+et avant le contexte de conversation :
+
+```json5
+promptAppend: "Prefer stable long-term preferences over one-off events."
+```
+
+`config.promptOverride` remplace l’invite par défaut de la mémoire active. OpenClaw
+ajoute toujours ensuite le contexte de conversation :
+
+```json5
+promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
+```
+
+La personnalisation de l’invite n’est pas recommandée sauf si vous testez délibérément un
+contrat de rappel différent. L’invite par défaut est réglée pour renvoyer soit `NONE`,
+soit un contexte compact de faits utilisateur pour le modèle principal.
+
+### `message`
+
+Seul le dernier message utilisateur est envoyé.
+
+```text
+Latest user message only
+```
+
+À utiliser lorsque :
+
+- vous voulez le comportement le plus rapide
+- vous voulez le biais le plus fort vers le rappel de préférences stables
+- les tours de suivi n’ont pas besoin de contexte conversationnel
+
+Délai recommandé :
+
+- commencez autour de `3000` à `5000` ms
+
+### `recent`
+
+Le dernier message utilisateur plus une petite portion récente de la conversation sont envoyés.
+
+```text
+Recent conversation tail:
+user: ...
+assistant: ...
+user: ...
+
+Latest user message:
+...
+```
+
+À utiliser lorsque :
+
+- vous voulez un meilleur équilibre entre vitesse et ancrage conversationnel
+- les questions de suivi dépendent souvent des derniers tours
+
+Délai recommandé :
+
+- commencez autour de `15000` ms
+
+### `full`
+
+La conversation complète est envoyée au sous-agent de mémoire bloquant.
+
+```text
+Full conversation context:
+user: ...
+assistant: ...
+user: ...
+...
+```
+
+À utiliser lorsque :
+
+- la meilleure qualité de rappel compte plus que la latence
+- la conversation contient une mise en contexte importante loin plus haut dans le fil
+
+Délai recommandé :
+
+- augmentez-le sensiblement par rapport à `message` ou `recent`
+- commencez autour de `15000` ms ou plus selon la taille du fil
+
+En général, le délai d’attente doit augmenter avec la taille du contexte :
+
+```text
+message < recent < full
+```
+
+## Persistance de la transcription
+
+Les exécutions du sous-agent de mémoire bloquant de la mémoire active créent une véritable transcription `session.jsonl`
+pendant l’appel du sous-agent de mémoire bloquant.
+
+Par défaut, cette transcription est temporaire :
+
+- elle est écrite dans un répertoire temporaire
+- elle est utilisée uniquement pour l’exécution du sous-agent de mémoire bloquant
+- elle est supprimée immédiatement après la fin de l’exécution
+
+Si vous voulez conserver sur disque ces transcriptions du sous-agent de mémoire bloquant pour le débogage ou
+l’inspection, activez explicitement la persistance :
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ persistTranscripts: true,
+ transcriptDir: "active-memory",
+ },
+ },
+ },
+ },
+}
+```
+
+Lorsqu’elle est activée, la mémoire active stocke les transcriptions dans un répertoire distinct sous le
+dossier des sessions de l’agent cible, et non dans le chemin principal de transcription de la conversation
+utilisateur.
+
+La structure par défaut est conceptuellement :
+
+```text
+agents//sessions/active-memory/.jsonl
+```
+
+Vous pouvez modifier le sous-répertoire relatif avec `config.transcriptDir`.
+
+À utiliser avec précaution :
+
+- les transcriptions du sous-agent de mémoire bloquant peuvent s’accumuler rapidement sur les sessions très actives
+- le mode de requête `full` peut dupliquer une grande quantité de contexte de conversation
+- ces transcriptions contiennent un contexte d’invite caché et des mémoires rappelées
+
+## Configuration
+
+Toute la configuration de la mémoire active se trouve sous :
+
+```text
+plugins.entries.active-memory
+```
+
+Les champs les plus importants sont :
+
+| Key | Type | Meaning |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `enabled` | `boolean` | Active le plugin lui-même |
+| `config.agents` | `string[]` | Identifiants d’agent pouvant utiliser la mémoire active |
+| `config.model` | `string` | Référence de modèle optionnelle pour le sous-agent de mémoire bloquant ; lorsqu’elle n’est pas définie, la mémoire active utilise le modèle de la session en cours |
+| `config.queryMode` | `"message" \| "recent" \| "full"` | Contrôle la quantité de conversation que voit le sous-agent de mémoire bloquant |
+| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Contrôle à quel point le sous-agent de mémoire bloquant est prompt ou strict lorsqu’il décide de renvoyer de la mémoire |
+| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Remplacement avancé du niveau de réflexion pour le sous-agent de mémoire bloquant ; `off` par défaut pour la vitesse |
+| `config.promptOverride` | `string` | Remplacement avancé complet de l’invite ; non recommandé pour un usage normal |
+| `config.promptAppend` | `string` | Instructions supplémentaires avancées ajoutées à l’invite par défaut ou remplacée |
+| `config.timeoutMs` | `number` | Délai d’attente maximal strict pour le sous-agent de mémoire bloquant |
+| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé de la mémoire active |
+| `config.logging` | `boolean` | Émet des journaux de la mémoire active pendant l’ajustement |
+| `config.persistTranscripts` | `boolean` | Conserve sur disque les transcriptions du sous-agent de mémoire bloquant au lieu de supprimer les fichiers temporaires |
+| `config.transcriptDir` | `string` | Répertoire relatif des transcriptions du sous-agent de mémoire bloquant sous le dossier des sessions de l’agent |
+
+Champs de réglage utiles :
+
+| Key | Type | Meaning |
+| ----------------------------- | -------- | ------------------------------------------------------------- |
+| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé de la mémoire active |
+| `config.recentUserTurns` | `number` | Tours utilisateur précédents à inclure lorsque `queryMode` vaut `recent` |
+| `config.recentAssistantTurns` | `number` | Tours d’assistant précédents à inclure lorsque `queryMode` vaut `recent` |
+| `config.recentUserChars` | `number` | Nombre maximal de caractères par tour utilisateur récent |
+| `config.recentAssistantChars` | `number` | Nombre maximal de caractères par tour d’assistant récent |
+| `config.cacheTtlMs` | `number` | Réutilisation du cache pour les requêtes identiques répétées |
+
+## Configuration recommandée
+
+Commencez avec `recent`.
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Si vous voulez inspecter le comportement en direct pendant l’ajustement, utilisez `/verbose on` dans la
+session au lieu de chercher une commande de débogage active-memory distincte.
+
+Passez ensuite à :
+
+- `message` si vous voulez une latence plus faible
+- `full` si vous décidez qu’un contexte supplémentaire vaut un sous-agent de mémoire bloquant plus lent
+
+## Débogage
+
+Si la mémoire active n’apparaît pas là où vous l’attendez :
+
+1. Vérifiez que le plugin est activé dans `plugins.entries.active-memory.enabled`.
+2. Vérifiez que l’identifiant de l’agent courant figure dans `config.agents`.
+3. Vérifiez que vous testez via une session de chat persistante interactive.
+4. Activez `config.logging: true` et observez les journaux de la passerelle.
+5. Vérifiez que la recherche de mémoire fonctionne elle-même avec `openclaw memory status --deep`.
+
+Si les résultats mémoire sont bruyants, réduisez :
+
+- `maxSummaryChars`
+
+Si la mémoire active est trop lente :
+
+- réduisez `queryMode`
+- réduisez `timeoutMs`
+- réduisez le nombre de tours récents
+- réduisez les plafonds de caractères par tour
+
+## Pages associées
+
+- [Recherche en mémoire](/fr/concepts/memory-search)
+- [Référence de configuration de la mémoire](/fr/reference/memory-config)
+- [Configuration du SDK de plugin](/fr/plugins/sdk-setup)
diff --git a/docs/fr/concepts/memory-search.md b/docs/fr/concepts/memory-search.md
index bac252ea6..241f22655 100644
--- a/docs/fr/concepts/memory-search.md
+++ b/docs/fr/concepts/memory-search.md
@@ -1,102 +1,91 @@
---
read_when:
- Vous voulez comprendre comment `memory_search` fonctionne
- - Vous voulez choisir un fournisseur d'embeddings
- - Vous voulez ajuster la qualité de la recherche
-summary: Comment memory search trouve des notes pertinentes à l'aide des embeddings et de la récupération hybride
-title: Memory Search
+ - Vous voulez choisir un fournisseur d’embeddings
+ - Vous voulez ajuster la qualité de recherche
+summary: Comment la recherche mémoire trouve des notes pertinentes à l’aide des embeddings et de la récupération hybride
+title: Recherche mémoire
x-i18n:
- generated_at: "2026-04-06T03:06:26Z"
+ generated_at: "2026-04-10T06:55:55Z"
model: gpt-5.4
provider: openai
- source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
+ source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
source_path: concepts/memory-search.md
workflow: 15
---
-# Memory Search
+# Recherche mémoire
-`memory_search` trouve des notes pertinentes dans vos fichiers de mémoire, même lorsque
-la formulation diffère du texte d'origine. Il fonctionne en indexant la mémoire en petits
-fragments et en les recherchant à l'aide d'embeddings, de mots-clés, ou des deux.
+`memory_search` trouve des notes pertinentes dans vos fichiers de mémoire, même lorsque la formulation diffère du texte d’origine. Elle fonctionne en indexant la mémoire en petits fragments, puis en les recherchant à l’aide d’embeddings, de mots-clés, ou des deux.
## Démarrage rapide
-Si vous avez une clé API OpenAI, Gemini, Voyage ou Mistral configurée, memory
-search fonctionne automatiquement. Pour définir explicitement un fournisseur :
+Si vous avez une clé API OpenAI, Gemini, Voyage ou Mistral configurée, la recherche mémoire fonctionne automatiquement. Pour définir explicitement un fournisseur :
```json5
{
agents: {
defaults: {
memorySearch: {
- provider: "openai", // or "gemini", "local", "ollama", etc.
+ provider: "openai", // ou "gemini", "local", "ollama", etc.
},
},
},
}
```
-Pour des embeddings locaux sans clé API, utilisez `provider: "local"` (nécessite
-node-llama-cpp).
+Pour des embeddings locaux sans clé API, utilisez `provider: "local"` (nécessite `node-llama-cpp`).
## Fournisseurs pris en charge
-| Fournisseur | ID | Nécessite une clé API | Notes |
-| ----------- | --------- | --------------------- | ---------------------------------------------------- |
-| OpenAI | `openai` | Oui | Détection automatique, rapide |
-| Gemini | `gemini` | Oui | Prend en charge l'indexation d'images et d'audio |
-| Voyage | `voyage` | Oui | Détection automatique |
-| Mistral | `mistral` | Oui | Détection automatique |
-| Bedrock | `bedrock` | Non | Détection automatique lorsque la chaîne d'identifiants AWS est résolue |
-| Ollama | `ollama` | Non | Local, doit être défini explicitement |
-| Local | `local` | Non | Modèle GGUF, téléchargement d'environ 0,6 Go |
+| Fournisseur | ID | Nécessite une clé API | Notes |
+| ----------- | --------- | --------------------- | ------------------------------------------------------- |
+| OpenAI | `openai` | Oui | Détection automatique, rapide |
+| Gemini | `gemini` | Oui | Prend en charge l’indexation d’images et d’audio |
+| Voyage | `voyage` | Oui | Détection automatique |
+| Mistral | `mistral` | Oui | Détection automatique |
+| Bedrock | `bedrock` | Non | Détection automatique lorsque la chaîne d’identifiants AWS est résolue |
+| Ollama | `ollama` | Non | Local, doit être défini explicitement |
+| Local | `local` | Non | Modèle GGUF, téléchargement d’environ 0,6 Go |
-## Fonctionnement de la recherche
+## Comment la recherche fonctionne
-OpenClaw exécute deux parcours de récupération en parallèle et fusionne les résultats :
+OpenClaw exécute deux chemins de récupération en parallèle et fusionne les résultats :
```mermaid
flowchart LR
- Q["Query"] --> E["Embedding"]
- Q --> T["Tokenize"]
- E --> VS["Vector Search"]
- T --> BM["BM25 Search"]
- VS --> M["Weighted Merge"]
+ Q["Requête"] --> E["Embedding"]
+ Q --> T["Tokenisation"]
+ E --> VS["Recherche vectorielle"]
+ T --> BM["Recherche BM25"]
+ VS --> M["Fusion pondérée"]
BM --> M
- M --> R["Top Results"]
+ M --> R["Meilleurs résultats"]
```
-- **La recherche vectorielle** trouve des notes au sens similaire ("gateway host" correspond à
- "the machine running OpenClaw").
-- **La recherche par mots-clés BM25** trouve des correspondances exactes (ID, chaînes d'erreur, clés
- de configuration).
+- **Recherche vectorielle** trouve des notes au sens similaire (« gateway host » correspond à « la machine qui exécute OpenClaw »).
+- **Recherche par mots-clés BM25** trouve des correspondances exactes (ID, chaînes d’erreur, clés de configuration).
-Si un seul parcours est disponible (pas d'embeddings ou pas de FTS), l'autre s'exécute seul.
+Si un seul chemin est disponible (pas d’embeddings ou pas de FTS), l’autre s’exécute seul.
-## Améliorer la qualité de la recherche
+## Améliorer la qualité de recherche
Deux fonctionnalités facultatives aident lorsque vous avez un long historique de notes :
### Décroissance temporelle
-Les anciennes notes perdent progressivement du poids dans le classement afin que les informations récentes remontent en premier.
-Avec la demi-vie par défaut de 30 jours, une note du mois dernier obtient un score égal à 50 % de
-son poids d'origine. Les fichiers permanents comme `MEMORY.md` ne subissent jamais de décroissance.
+Les anciennes notes perdent progressivement du poids dans le classement, afin que les informations récentes remontent en premier. Avec la demi-vie par défaut de 30 jours, une note du mois dernier obtient 50 % de son poids d’origine. Les fichiers pérennes comme `MEMORY.md` ne subissent jamais de décroissance.
-Activez la décroissance temporelle si votre agent a des mois de notes quotidiennes et que des informations obsolètes
-continuent de dépasser le contexte récent dans le classement.
+Activez la décroissance temporelle si votre agent a des mois de notes quotidiennes et que des informations obsolètes continuent de dépasser le contexte récent dans le classement.
### MMR (diversité)
-Réduit les résultats redondants. Si cinq notes mentionnent toutes la même configuration de routeur, MMR
-garantit que les meilleurs résultats couvrent différents sujets au lieu de se répéter.
+Réduit les résultats redondants. Si cinq notes mentionnent toutes la même configuration de routeur, MMR garantit que les meilleurs résultats couvrent différents sujets au lieu de se répéter.
-Activez MMR si `memory_search` continue de renvoyer des extraits quasi dupliqués provenant
-de différentes notes quotidiennes.
+Activez MMR si `memory_search` continue de renvoyer des extraits presque dupliqués provenant de différentes notes quotidiennes.
### Activer les deux
@@ -120,30 +109,22 @@ de différentes notes quotidiennes.
## Mémoire multimodale
-Avec Gemini Embedding 2, vous pouvez indexer des images et des fichiers audio aux côtés du
-Markdown. Les requêtes de recherche restent du texte, mais elles correspondent au contenu visuel et audio.
-Consultez la [référence de configuration de la mémoire](/fr/reference/memory-config) pour la
-configuration.
+Avec Gemini Embedding 2, vous pouvez indexer des images et des fichiers audio en plus du Markdown. Les requêtes de recherche restent textuelles, mais elles sont mises en correspondance avec le contenu visuel et audio. Consultez la [référence de configuration de la mémoire](/fr/reference/memory-config) pour la configuration.
## Recherche dans la mémoire de session
-Vous pouvez éventuellement indexer les transcriptions de session afin que `memory_search` puisse rappeler
-des conversations antérieures. Cette fonctionnalité est optionnelle via
-`memorySearch.experimental.sessionMemory`. Consultez la
-[référence de configuration](/fr/reference/memory-config) pour plus de détails.
+Vous pouvez facultativement indexer les transcriptions de session afin que `memory_search` puisse rappeler des conversations antérieures. Cette fonctionnalité est activée sur opt-in via `memorySearch.experimental.sessionMemory`. Consultez la [référence de configuration](/fr/reference/memory-config) pour plus de détails.
## Dépannage
-**Aucun résultat ?** Exécutez `openclaw memory status` pour vérifier l'index. S'il est vide, exécutez
-`openclaw memory index --force`.
+**Aucun résultat ?** Exécutez `openclaw memory status` pour vérifier l’index. S’il est vide, exécutez `openclaw memory index --force`.
-**Seulement des correspondances par mots-clés ?** Il se peut que votre fournisseur d'embeddings ne soit pas configuré. Vérifiez
-`openclaw memory status --deep`.
+**Seulement des correspondances par mots-clés ?** Votre fournisseur d’embeddings n’est peut-être pas configuré. Vérifiez avec `openclaw memory status --deep`.
-**Texte CJK introuvable ?** Reconstruisez l'index FTS avec
-`openclaw memory index --force`.
+**Texte CJK introuvable ?** Reconstruisez l’index FTS avec `openclaw memory index --force`.
## Pour aller plus loin
-- [Memory](/fr/concepts/memory) -- disposition des fichiers, backends, outils
+- [Mémoire active](/fr/concepts/active-memory) -- mémoire de sous-agent pour les sessions de chat interactives
+- [Mémoire](/fr/concepts/memory) -- disposition des fichiers, backends, outils
- [Référence de configuration de la mémoire](/fr/reference/memory-config) -- tous les paramètres de configuration
diff --git a/docs/fr/concepts/qa-e2e-automation.md b/docs/fr/concepts/qa-e2e-automation.md
index d14a643e0..335732c8f 100644
--- a/docs/fr/concepts/qa-e2e-automation.md
+++ b/docs/fr/concepts/qa-e2e-automation.md
@@ -1,50 +1,50 @@
---
read_when:
- - Étendre qa-lab ou qa-channel
- - Ajouter des scénarios QA adossés au dépôt
- - Créer une automatisation QA plus réaliste autour du tableau de bord Gateway
-summary: Structure de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios de départ, et les rapports de protocole
-title: Automatisation QA E2E
+ - Extension de qa-lab ou qa-channel
+ - Ajout de scénarios QA adossés au dépôt
+ - Création d’une automatisation QA plus réaliste autour du tableau de bord Gateway
+summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, scénarios préconfigurés et rapports de protocole
+title: Automatisation QA de bout en bout
x-i18n:
- generated_at: "2026-04-09T01:27:44Z"
+ generated_at: "2026-04-10T06:55:57Z"
model: gpt-5.4
provider: openai
- source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
+ source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
-# Automatisation QA E2E
+# Automatisation QA de bout en bout
La pile QA privée est conçue pour exercer OpenClaw d’une manière plus réaliste,
-avec une forme proche d’un canal, qu’un simple test unitaire ne peut le faire.
+façonnée comme un canal, qu’un simple test unitaire ne peut le faire.
Éléments actuels :
-- `extensions/qa-channel` : canal de messages synthétique avec surfaces de MP, de canal, de fil,
+- `extensions/qa-channel` : canal de messages synthétique avec des surfaces de MP, de canal, de fil,
de réaction, de modification et de suppression.
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
injecter des messages entrants et exporter un rapport Markdown.
-- `qa/` : ressources de départ adossées au dépôt pour la tâche de lancement et les
- scénarios QA de base.
+- `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.
-Le flux opérateur QA actuel repose sur un site QA à deux volets :
+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.
-Lancez-le avec :
+Exécutez-le avec :
```bash
pnpm qa:lab:up
```
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 est resté bloqué.
+page QA Lab où un opérateur ou une boucle d’automatisation peut donner une
+mission QA à l’agent, observer le comportement réel du canal et consigner ce
+qui a fonctionné, échoué ou est resté bloqué.
-Pour une itération plus rapide sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois,
+Pour des itérations plus rapides sur l’interface de QA Lab sans reconstruire l’image Docker à chaque fois,
démarrez la pile avec un bundle QA Lab monté par liaison :
```bash
@@ -54,40 +54,56 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
-`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte par liaison
+`qa:lab:up:fast` maintient 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 modification, et le navigateur se recharge automatiquement lorsque le hachage des ressources QA Lab change.
+reconstruit ce bundle à chaque changement, et le navigateur se recharge automatiquement lorsque le hachage de ressource de QA Lab change.
-## Ressources de départ adossées au dépôt
+Pour une voie VM Linux jetable sans faire intervenir Docker dans le parcours QA, exécutez :
-Les ressources de départ se trouvent dans `qa/` :
+```bash
+pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
+```
+
+Cela démarre un invité Multipass vierge, installe les dépendances, construit OpenClaw
+dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le
+résumé vers `.artifacts/qa-e2e/...` sur l’hôte.
+Cela réutilise le même comportement de sélection de scénario que `qa suite` sur l’hôte.
+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é.
+
+## Amorçages adossés au dépôt
+
+Les ressources d’amorçage se trouvent dans `qa/` :
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
-Elles sont volontairement versionnées dans git afin que le plan QA soit visible à la fois pour les humains et pour l’agent. La liste de base doit rester suffisamment large pour couvrir :
+Elles sont volontairement conservées dans git afin que le plan QA soit visible à la fois pour les humains et pour
+l’agent. La liste de référence doit rester suffisamment large pour couvrir :
-- chat en MP et en canal
-- comportement des fils
-- cycle de vie des actions de message
-- rappels cron
-- rappel en mémoire
-- changement de modèle
-- transfert à un sous-agent
-- lecture du dépôt et de la documentation
+- les MP et les discussions de canal
+- le comportement des fils
+- le cycle de vie des actions sur les messages
+- les rappels cron
+- 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
## Rapports
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie observée du bus.
-Le rapport doit répondre aux questions suivantes :
+Le rapport doit répondre à :
- Ce qui a fonctionné
- Ce qui a échoué
- Ce qui est resté bloqué
-- Quels scénarios de suivi méritent d’être ajoutés
+- Quels scénarios de suivi valent la peine d’être ajoutés
-Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles réels
+Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles live
et rédigez un rapport Markdown évalué :
```bash
@@ -109,29 +125,29 @@ pnpm openclaw qa character-eval \
La commande exécute des processus enfants locaux de passerelle QA, pas Docker. Les
scénarios d’évaluation du caractère 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 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 des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
-un raisonnement `xhigh` de classer les exécutions selon leur naturel, leur ambiance et leur humour.
+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 des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
+un raisonnement `xhigh` de classer les exécutions selon le naturel, l’ambiance et l’humour.
Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours
-chaque transcription et le statut d’exécution, mais les références candidates sont remplacées par des
-étiquettes neutres comme `candidate-01` ; le rapport remappe les classements vers les références réelles après
+chaque transcription et statut d’exécution, mais les références candidates sont remplacées par des
+étiquettes neutres telles que `candidate-01` ; le rapport remappe les classements vers les références réelles après
l’analyse.
Les exécutions candidates utilisent par défaut le niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui
le prennent en charge. Remplacez un candidat spécifique inline avec
-`--model provider/model,thinking=`. `--thinking ` définit toujours un
-secours global, et l’ancien format `--model-thinking ` est
+`--model provider/model,thinking=`. `--thinking ` définit toujours une
+valeur de repli globale, et l’ancien format `--model-thinking ` est
conservé 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` inline lorsqu’un
+Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé là
+où le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` inline lorsqu’un
candidat unique ou un juge a besoin d’une dérogation. Passez `--fast` uniquement si 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 invites des juges précisent explicitement de
-ne pas classer selon la vitesse.
+enregistrées dans le rapport pour l’analyse comparative, mais les invites 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 la passerelle locale
-rendent l’exécution trop bruyante.
-Lorsqu’aucun `--model` candidat n’est passé, l’évaluation du caractère utilise par défaut
+`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression locale sur la passerelle
+rendent une exécution trop bruyante.
+Lorsqu’aucun candidat `--model` n’est passé, l’évaluation du caractère utilise par défaut
`openai/gpt-5.4`, `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
diff --git a/docs/fr/gateway/configuration-reference.md b/docs/fr/gateway/configuration-reference.md
index 1bb75a80e..66f057acb 100644
--- a/docs/fr/gateway/configuration-reference.md
+++ b/docs/fr/gateway/configuration-reference.md
@@ -1,14 +1,14 @@
---
read_when:
- - Vous avez besoin de la sémantique exacte au niveau des champs de configuration ou des valeurs par défaut
+ - Vous avez besoin de la sémantique exacte des champs de configuration ou des valeurs par défaut
- Vous validez des blocs de configuration de canal, de modèle, de passerelle ou d’outil
summary: Référence de configuration de la passerelle 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
title: Référence de configuration
x-i18n:
- generated_at: "2026-04-09T01:33:22Z"
+ generated_at: "2026-04-10T06:55:54Z"
model: gpt-5.4
provider: openai
- source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c
+ source_hash: c6aa34e3a9096c4dabef26b9cdfda4bd7693e16da43a88c1641cfad8ba1ec237
source_path: gateway/configuration-reference.md
workflow: 15
---
@@ -17,18 +17,18 @@ x-i18n:
Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâches, consultez [Configuration](/fr/gateway/configuration).
-Cette page couvre les principales surfaces de configuration d’OpenClaw et renvoie ailleurs lorsqu’un sous-système dispose de sa propre référence plus détaillée. Elle ne cherche **pas** à intégrer sur une seule page chaque catalogue de commandes appartenant à un canal/plugin ni chaque paramètre avancé de mémoire/QMD.
+Cette page couvre les principales surfaces de configuration d’OpenClaw et renvoie vers d’autres pages lorsqu’un sous-système possède sa propre référence plus détaillée. Elle **n’essaie pas** d’intégrer sur une seule page chaque catalogue de commandes appartenant à un canal/plugin ni chaque réglage avancé de mémoire/QMD.
Source de vérité du code :
-- `openclaw config schema` affiche le JSON Schema en direct utilisé pour la validation et l’interface utilisateur de contrôle, avec les métadonnées de bundle/plugin/canal fusionnées lorsqu’elles sont disponibles
-- `config.schema.lookup` renvoie un nœud de schéma délimité par chemin pour les outils d’exploration détaillée
-- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hash de référence de documentation de configuration par rapport à la surface de schéma actuelle
+- `openclaw config schema` affiche le schéma JSON actif utilisé pour la validation et l’interface Control UI, avec les métadonnées groupées/plugin/canal 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 des documents de configuration par rapport à la surface actuelle du schéma
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 + fournies en bundle
+- [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 rêverie 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 du canal/plugin propriétaire pour les surfaces de commandes spécifiques au canal
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.
@@ -39,32 +39,32 @@ Le format de configuration est **JSON5** (commentaires + virgules finales autori
Chaque canal démarre automatiquement lorsque sa section de configuration existe (sauf si `enabled: false`).
-### Accès DM et groupe
+### Accès aux messages privés et aux groupes
-Tous les canaux prennent en charge des politiques de DM et des politiques de groupe :
+Tous les canaux prennent en charge des politiques pour les messages privés et pour les groupes :
-| Politique DM | Comportement |
-| ------------------- | -------------------------------------------------------------- |
-| `pairing` (par défaut) | Les expéditeurs inconnus reçoivent un code d’association à usage unique ; le propriétaire doit approuver |
-| `allowlist` | Uniquement les expéditeurs dans `allowFrom` (ou le magasin d’autorisations associées) |
-| `open` | Autoriser tous les DM entrants (nécessite `allowFrom: ["*"]`) |
-| `disabled` | Ignorer tous les DM entrants |
+| Politique DM | Comportement |
+| -------------------- | -------------------------------------------------------------- |
+| `pairing` (par défaut) | Les expéditeurs inconnus reçoivent un code d’appairage à usage unique ; le propriétaire doit l’approuver |
+| `allowlist` | Seuls les expéditeurs dans `allowFrom` (ou le magasin d’autorisations appairées) |
+| `open` | Autoriser tous les messages privés entrants (nécessite `allowFrom: ["*"]`) |
+| `disabled` | Ignorer tous les messages privés entrants |
-| Politique de groupe | Comportement |
-| --------------------- | ----------------------------------------------------- |
-| `allowlist` (par défaut) | Uniquement les groupes correspondant à la liste d’autorisations configurée |
-| `open` | Contourner les listes d’autorisations de groupe (le filtrage par mention s’applique toujours) |
-| `disabled` | Bloquer tous les messages de groupe/salon |
+| Politique de groupe | Comportement |
+| ---------------------- | ----------------------------------------------------- |
+| `allowlist` (par défaut) | Seuls les groupes correspondant à la liste d’autorisations configurée |
+| `open` | Contourner les listes d’autorisations de groupe (le filtrage par mention s’applique toujours) |
+| `disabled` | Bloquer tous les messages de groupe/salon |
`channels.defaults.groupPolicy` définit la valeur par défaut lorsque `groupPolicy` d’un fournisseur n’est pas défini.
-Les codes d’association expirent après 1 heure. Les demandes d’association DM en attente sont limitées à **3 par canal**.
-Si un bloc fournisseur est complètement absent (`channels.` absent), la politique de groupe à l’exécution revient à `allowlist` (échec fermé) avec un avertissement au démarrage.
+Les codes d’appairage expirent après 1 heure. Les demandes d’appairage DM en attente sont limitées à **3 par canal**.
+Si un bloc fournisseur est entièrement absent (`channels.` absent), la politique de groupe d’exécution revient à `allowlist` (échec sécurisé) avec un avertissement au démarrage.
### Remplacements de modèle par canal
-Utilisez `channels.modelByChannel` pour épingler des identifiants de canal spécifiques à un modèle. Les valeurs acceptent `provider/model` ou des alias de modèles configurés. Le mappage de canal s’applique lorsqu’une session n’a pas déjà un remplacement de modèle (par exemple défini via `/model`).
+Utilisez `channels.modelByChannel` pour épingler des ID de canal spécifiques à un modèle. Les valeurs acceptent `provider/model` ou des alias de modèle configurés. Le mapping de canal s’applique lorsqu’une session n’a pas déjà de remplacement de modèle (par exemple défini via `/model`).
```json5
{
@@ -106,10 +106,10 @@ Utilisez `channels.defaults` pour le comportement partagé de politique de group
```
- `channels.defaults.groupPolicy` : politique de groupe de repli lorsqu’un `groupPolicy` au niveau fournisseur n’est pas défini.
-- `channels.defaults.contextVisibility` : mode de visibilité du contexte supplémentaire par défaut pour tous les canaux. Valeurs : `all` (par défaut, inclure tout le contexte cité/de fil/d’historique), `allowlist` (inclure uniquement le contexte provenant d’expéditeurs autorisés), `allowlist_quote` (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : `channels..contextVisibility`.
-- `channels.defaults.heartbeat.showOk` : inclure les états de canal sains dans la sortie heartbeat.
-- `channels.defaults.heartbeat.showAlerts` : inclure les états dégradés/en erreur dans la sortie heartbeat.
-- `channels.defaults.heartbeat.useIndicator` : afficher une sortie heartbeat compacte de type indicateur.
+- `channels.defaults.contextVisibility` : mode de visibilité du contexte supplémentaire par défaut pour tous les canaux. Valeurs : `all` (par défaut, inclure tout le contexte cité/de fil/d’historique), `allowlist` (inclure uniquement le contexte des expéditeurs autorisés), `allowlist_quote` (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : `channels..contextVisibility`.
+- `channels.defaults.heartbeat.showOk` : inclure les états de canal sains dans la sortie du heartbeat.
+- `channels.defaults.heartbeat.showAlerts` : inclure les états dégradés/en erreur dans la sortie du heartbeat.
+- `channels.defaults.heartbeat.useIndicator` : afficher une sortie de heartbeat compacte de type indicateur.
### WhatsApp
@@ -124,7 +124,7 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // blue ticks (false in self-chat mode)
+ sendReadReceipts: true, // coches bleues (false en mode auto-discussion)
groups: {
"*": { requireMention: true },
},
@@ -164,9 +164,9 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
}
```
-- Les commandes sortantes utilisent par défaut le compte `default` s’il existe ; sinon, le premier identifiant de compte configuré (trié).
-- Le champ facultatif `channels.whatsapp.defaultAccount` remplace cette sélection de compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
-- L’ancien répertoire d’authentification Baileys mono-compte est migré par `openclaw doctor` vers `whatsapp/default`.
+- Les commandes sortantes utilisent par défaut le compte `default` s’il est présent ; sinon, le premier ID de compte configuré (trié).
+- `channels.whatsapp.defaultAccount` facultatif remplace ce choix du compte par défaut lorsqu’il correspond à un ID de compte configuré.
+- L’ancien répertoire d’authentification Baileys à compte unique est migré par `openclaw doctor` vers `whatsapp/default`.
- Remplacements par compte : `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
@@ -225,13 +225,13 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
}
```
-- Jeton de bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier ordinaire uniquement ; les liens symboliques sont rejetés), avec `TELEGRAM_BOT_TOKEN` comme repli pour le compte par défaut.
-- Le champ facultatif `channels.telegram.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
-- Dans les configurations multi-comptes (2 identifiants de compte ou plus), définissez un compte par défaut explicite (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) pour éviter le routage de repli ; `openclaw doctor` émet un avertissement lorsque ce champ est absent ou invalide.
-- `configWrites: false` bloque les écritures de configuration initiées par Telegram (migrations d’identifiants de supergroupes, `/config set|unset`).
-- Les entrées de niveau supérieur `bindings[]` avec `type: "acp"` configurent des liaisons ACP persistantes pour les sujets de forum (utilisez le format canonique `chatId:topic:topicId` dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
-- Les aperçus de flux Telegram utilisent `sendMessage` + `editMessageText` (fonctionne dans les chats directs et de groupe).
-- Politique de retry : voir [Politique de retry](/fr/concepts/retry).
+- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier ordinaire uniquement ; les liens symboliques sont rejetés), avec `TELEGRAM_BOT_TOKEN` comme solution de repli pour le compte par défaut.
+- `channels.telegram.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
+- Dans les configurations multi-comptes (2 ID de compte ou plus), définissez un compte par défaut explicite (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) pour éviter le routage de repli ; `openclaw doctor` avertit lorsque cela est manquant ou invalide.
+- `configWrites: false` bloque les écritures de configuration initiées par Telegram (migrations d’ID de supergroupe, `/config set|unset`).
+- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les sujets de forum (utilisez le format canonique `chatId:topic:topicId` dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
+- Les aperçus de flux Telegram utilisent `sendMessage` + `editMessageText` (fonctionne dans les conversations directes et de groupe).
+- Politique de nouvelle tentative : voir [Politique de nouvelle tentative](/fr/concepts/retry).
### Discord
@@ -333,36 +333,36 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
}
```
-- Jeton : `channels.discord.token`, avec `DISCORD_BOT_TOKEN` comme repli pour le compte par défaut.
-- Les appels sortants directs qui fournissent un `token` Discord explicite utilisent ce jeton pour l’appel ; les paramètres de politique/retry du compte proviennent toujours du compte sélectionné dans l’instantané d’exécution actif.
-- Le champ facultatif `channels.discord.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
-- Utilisez `user:` (DM) ou `channel:` (canal de serveur) pour les cibles de livraison ; les identifiants numériques seuls sont rejetés.
-- Les slugs de serveurs sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom sous forme de slug (sans `#`). Préférez les identifiants de serveur.
-- Les messages rédigés par des bots sont ignorés par défaut. `allowBots: true` les active ; utilisez `allowBots: "mentions"` pour n’accepter que les messages de bot qui mentionnent le bot (les messages du bot lui-même restent filtrés).
-- `channels.discord.guilds..ignoreOtherMentions` (et les remplacements au niveau canal) supprime les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here).
+- Jeton : `channels.discord.token`, avec `DISCORD_BOT_TOKEN` comme solution de repli pour le compte par défaut.
+- Les appels sortants directs qui fournissent un `token` Discord explicite utilisent ce jeton pour l’appel ; les paramètres de nouvelle tentative/politique du compte proviennent toujours du compte sélectionné dans l’instantané d’exécution actif.
+- `channels.discord.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
+- Utilisez `user:` (DM) ou `channel:` (canal de serveur) pour les cibles de livraison ; les ID numériques seuls sont rejetés.
+- Les slugs de serveur sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom slugifié (sans `#`). Préférez les ID de serveur.
+- Les messages rédigés par des bots sont ignorés par défaut. `allowBots: true` les active ; utilisez `allowBots: "mentions"` pour n’accepter que les messages de bots qui mentionnent le bot (les propres messages restent filtrés).
+- `channels.discord.guilds..ignoreOtherMentions` (et les remplacements de canal) supprime les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here).
- `maxLinesPerMessage` (17 par défaut) découpe les messages hauts même lorsqu’ils font moins de 2000 caractères.
- `channels.discord.threadBindings` contrôle le routage lié aux fils Discord :
- - `enabled` : remplacement Discord pour les fonctionnalités de session liées aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` et livraison/routage liés)
+ - `enabled` : remplacement Discord pour les fonctionnalités de session liées aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, et la livraison/le routage liés)
- `idleHours` : remplacement Discord pour le retrait automatique du focus après inactivité, en heures (`0` désactive)
- `maxAgeHours` : remplacement Discord pour l’âge maximal strict, en heures (`0` désactive)
- - `spawnSubagentSessions` : option d’activation pour la création/liaison automatique de fils par `sessions_spawn({ thread: true })`
-- Les entrées de niveau supérieur `bindings[]` avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et fils (utilisez l’identifiant de canal/fil dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
-- `channels.discord.ui.components.accentColor` définit la couleur d’accentuation des conteneurs Discord components v2.
-- `channels.discord.voice` active les conversations dans les canaux vocaux Discord et les remplacements facultatifs d’auto-rejoindre + TTS.
+ - `spawnSubagentSessions` : option d’activation pour la création/liaison automatique de fil par `sessions_spawn({ thread: true })`
+- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et les fils (utilisez l’ID du canal/fil dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
+- `channels.discord.ui.components.accentColor` définit la couleur d’accentuation pour les conteneurs Discord components v2.
+- `channels.discord.voice` active les conversations dans les canaux vocaux Discord ainsi que les remplacements facultatifs d’auto-jonction + TTS.
- `channels.discord.voice.daveEncryption` et `channels.discord.voice.decryptionFailureTolerance` sont transmis aux options DAVE de `@discordjs/voice` (`true` et `24` par défaut).
-- OpenClaw tente aussi une récupération de réception vocale en quittant/rejoignant une session vocale après des échecs répétés de déchiffrement.
+- OpenClaw tente en outre une récupération de réception vocale en quittant puis en rejoignant à nouveau une session vocale après des échecs de déchiffrement répétés.
- `channels.discord.streaming` est la clé canonique du mode de flux. Les anciennes valeurs booléennes `streamMode` et `streaming` sont migrées automatiquement.
- `channels.discord.autoPresence` mappe la disponibilité d’exécution à la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et autorise des remplacements facultatifs du texte de statut.
-- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag modifiable (mode de compatibilité de secours).
-- `channels.discord.execApprovals` : livraison native sur Discord des approbations exec et autorisation des approbateurs.
- - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations exec s’activent lorsque les approbateurs peuvent être résolus depuis `approvers` ou `commands.ownerAllowFrom`.
- - `approvers` : identifiants d’utilisateurs Discord autorisés à approuver les demandes exec. Se replie sur `commands.ownerAllowFrom` lorsqu’omis.
- - `agentFilter` : liste facultative d’identifiants d’agents autorisés. Omettez pour transférer les approbations pour tous les agents.
+- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag modifiable (mode de compatibilité de dernier recours).
+- `channels.discord.execApprovals` : livraison native Discord des approbations d’exécution et autorisation des approbateurs.
+ - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations d’exécution s’activent lorsque des approbateurs peuvent être résolus depuis `approvers` ou `commands.ownerAllowFrom`.
+ - `approvers` : ID d’utilisateurs Discord autorisés à approuver des demandes d’exécution. Utilise `commands.ownerAllowFrom` comme solution de repli si omis.
+ - `agentFilter` : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents.
- `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex).
- - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut) envoie aux DM des approbateurs, `"channel"` envoie dans le canal d’origine, `"both"` envoie aux deux. Lorsque la cible inclut `"channel"`, les boutons ne sont utilisables que par les approbateurs résolus.
- - `cleanupAfterResolve` : lorsque `true`, supprime les DM d’approbation après approbation, refus ou expiration.
+ - `target` : emplacement d’envoi des invites d’approbation. `"dm"` (par défaut) les envoie aux DM des approbateurs, `"channel"` les envoie au canal d’origine, `"both"` les envoie aux deux. Lorsque la cible inclut `"channel"`, les boutons ne sont utilisables que par les approbateurs résolus.
+ - `cleanupAfterResolve` : lorsqu’il vaut `true`, supprime les DM d’approbation après approbation, refus ou expiration.
-**Modes de notification de réaction :** `off` (aucune), `own` (messages du bot, par défaut), `all` (tous les messages), `allowlist` (depuis `guilds..users` sur tous les messages).
+**Modes de notification de réaction :** `off` (aucun), `own` (messages du bot, par défaut), `all` (tous les messages), `allowlist` (depuis `guilds..users` sur tous les messages).
### Google Chat
@@ -393,11 +393,11 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
}
```
-- JSON de compte de service : en ligne (`serviceAccount`) ou basé sur fichier (`serviceAccountFile`).
-- SecretRef pour compte de service est également pris en charge (`serviceAccountRef`).
-- Variables d’environnement de repli : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
+- JSON du compte de service : en ligne (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`).
+- SecretRef du compte de service est également pris en charge (`serviceAccountRef`).
+- Solutions de repli d’environnement : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Utilisez `spaces/` ou `users/` pour les cibles de livraison.
-- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance par principal d’e-mail modifiable (mode de compatibilité de secours).
+- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance par principal e-mail modifiable (mode de compatibilité de dernier recours).
### Slack
@@ -464,35 +464,35 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar
}
```
-- Le **mode socket** nécessite `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le repli env du compte par défaut).
+- Le **mode socket** nécessite `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour la solution de repli d’environnement du compte par défaut).
- Le **mode HTTP** nécessite `botToken` plus `signingSecret` (à la racine ou par compte).
-- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes
- en clair ou des objets SecretRef.
-- Les instantanés de compte Slack exposent des champs de source/statut par identifiant, tels que
+- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes en texte brut
+ ou des objets SecretRef.
+- Les instantanés de compte Slack exposent des champs de source/état par identifiant comme
`botTokenSource`, `botTokenStatus`, `appTokenStatus` et, en mode HTTP,
`signingSecretStatus`. `configured_unavailable` signifie que le compte est
- configuré via SecretRef mais que le chemin actuel de commande/d’exécution n’a pas pu
- résoudre la valeur du secret.
+ configuré via SecretRef, mais que le chemin de commande/d’exécution actuel n’a pas pu
+ résoudre la valeur secrète.
- `configWrites: false` bloque les écritures de configuration initiées par Slack.
-- Le champ facultatif `channels.slack.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
+- `channels.slack.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
- `channels.slack.streaming.mode` est la clé canonique du mode de flux Slack. `channels.slack.streaming.nativeTransport` contrôle le transport de flux natif de Slack. Les anciennes valeurs `streamMode`, booléennes `streaming` et `nativeStreaming` sont migrées automatiquement.
- Utilisez `user:` (DM) ou `channel:` pour les cibles de livraison.
**Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`).
-**Isolation des sessions de fil :** `thread.historyScope` est par fil (par défaut) ou partagé sur le canal. `thread.inheritParent` copie la transcription du canal parent dans les nouveaux fils.
+**Isolation des sessions de fil :** `thread.historyScope` est par fil (par défaut) ou partagé à l’échelle du canal. `thread.inheritParent` copie la transcription du canal parent vers les nouveaux fils.
-- Le streaming natif Slack ainsi que le statut de fil Slack de style assistant « is typing... » nécessitent une cible de réponse dans un fil. Les DM de niveau supérieur restent hors fil par défaut ; ils utilisent donc `typingReaction` ou une livraison normale au lieu de l’aperçu de style fil.
+- Le flux natif Slack ainsi que l’état de fil Slack de type assistant « is typing... » nécessitent une cible de réponse dans un fil. Les DM de niveau supérieur restent hors fil par défaut ; ils utilisent donc `typingReaction` ou la livraison normale au lieu de l’aperçu de style fil.
- `typingReaction` ajoute une réaction temporaire au message Slack entrant pendant l’exécution d’une réponse, puis la supprime à la fin. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`.
-- `channels.slack.execApprovals` : livraison native Slack des approbations exec et autorisation des approbateurs. Même schéma que Discord : `enabled` (`true`/`false`/`"auto"`), `approvers` (identifiants d’utilisateurs Slack), `agentFilter`, `sessionFilter` et `target` (`"dm"`, `"channel"` ou `"both"`).
+- `channels.slack.execApprovals` : livraison native Slack des approbations d’exécution et autorisation des approbateurs. Même schéma que Discord : `enabled` (`true`/`false`/`"auto"`), `approvers` (ID d’utilisateurs Slack), `agentFilter`, `sessionFilter` et `target` (`"dm"`, `"channel"` ou `"both"`).
-| Groupe d’actions | Par défaut | Notes |
-| ---------------- | ---------- | ---------------------- |
+| Groupe d’actions | Par défaut | Remarques |
+| ---------------- | ---------- | ----------------------- |
| reactions | activé | Réagir + lister les réactions |
| messages | activé | Lire/envoyer/modifier/supprimer |
| pins | activé | Épingler/désépingler/lister |
-| memberInfo | activé | Informations de membre |
-| emojiList | activé | Liste des émojis personnalisés |
+| memberInfo | activé | Informations sur le membre |
+| emojiList | activé | Liste des emojis personnalisés |
### Mattermost
@@ -526,23 +526,23 @@ Mattermost est distribué comme plugin : `openclaw plugins install @openclaw/mat
}
```
-Modes de chat : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe déclencheur).
+Modes de chat : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe de déclenchement).
Lorsque les commandes natives Mattermost sont activées :
-- `commands.callbackPath` doit être un chemin (par exemple `/api/channels/mattermost/command`), pas une URL complète.
-- `commands.callbackUrl` doit résoudre vers le point de terminaison Gateway OpenClaw et être accessible depuis le serveur Mattermost.
+- `commands.callbackPath` doit être un chemin (par exemple `/api/channels/mattermost/command`), et non une URL complète.
+- `commands.callbackUrl` doit résoudre vers le point de terminaison de passerelle OpenClaw et être accessible depuis le serveur Mattermost.
- Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés
- par Mattermost lors de l’enregistrement de la commande slash. Si l’enregistrement échoue ou
- si aucune commande n’est activée, OpenClaw rejette les rappels avec
+ par Mattermost lors de l’enregistrement de la commande slash. Si l’enregistrement échoue ou si aucune
+ commande n’est activée, OpenClaw rejette les rappels avec
`Unauthorized: invalid command token.`
- Pour les hôtes de rappel privés/tailnet/internes, Mattermost peut exiger que
- `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/le domaine du rappel.
- Utilisez des valeurs d’hôte/domaine, pas des URL complètes.
-- `channels.mattermost.configWrites` : autoriser ou refuser les écritures de configuration initiées par Mattermost.
-- `channels.mattermost.requireMention` : exiger un `@mention` avant de répondre dans les canaux.
-- `channels.mattermost.groups..requireMention` : remplacement du filtrage par mention par canal (`"*"` pour la valeur par défaut).
-- Le champ facultatif `channels.mattermost.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
+ `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/domaine de rappel.
+ Utilisez des valeurs hôte/domaine, et non des URL complètes.
+- `channels.mattermost.configWrites` : autorise ou refuse les écritures de configuration initiées par Mattermost.
+- `channels.mattermost.requireMention` : exige une `@mention` avant de répondre dans les canaux.
+- `channels.mattermost.groups..requireMention` : remplacement par canal du filtrage par mention (`"*"` pour la valeur par défaut).
+- `channels.mattermost.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
### Signal
@@ -566,12 +566,12 @@ Lorsque les commandes natives Mattermost sont activées :
**Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`).
- `channels.signal.account` : épingle le démarrage du canal à une identité de compte Signal spécifique.
-- `channels.signal.configWrites` : autoriser ou refuser les écritures de configuration initiées par Signal.
-- Le champ facultatif `channels.signal.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
+- `channels.signal.configWrites` : autorise ou refuse les écritures de configuration initiées par Signal.
+- `channels.signal.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
### BlueBubbles
-BlueBubbles est le chemin iMessage recommandé (pris en charge par plugin, configuré sous `channels.bluebubbles`).
+BlueBubbles est le chemin recommandé pour iMessage (pris en charge par un plugin, configuré sous `channels.bluebubbles`).
```json5
{
@@ -586,14 +586,14 @@ BlueBubbles est le chemin iMessage recommandé (pris en charge par plugin, confi
}
```
-- Chemins de clés principales couverts ici : `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
-- Le champ facultatif `channels.bluebubbles.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
-- Les entrées de niveau supérieur `bindings[]` avec `type: "acp"` peuvent lier des conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle BlueBubbles ou une chaîne cible (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique partagée des champs : [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
+- Chemins de clés principaux couverts ici : `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
+- `channels.bluebubbles.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
+- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier des conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle BlueBubbles ou une chaîne cible (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique de champ partagée : [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
- La configuration complète du canal BlueBubbles est documentée dans [BlueBubbles](/fr/channels/bluebubbles).
### iMessage
-OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun daemon ni port requis.
+OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port n’est requis.
```json5
{
@@ -617,15 +617,15 @@ OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun daemon ni port requis.
}
```
-- Le champ facultatif `channels.imessage.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
+- `channels.imessage.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
- Nécessite un accès complet au disque pour la base de données Messages.
-- Préférez les cibles `chat_id:`. Utilisez `imsg chats --limit 20` pour lister les chats.
-- `cliPath` peut pointer vers un wrapper SSH ; définissez `remoteHost` (`host` ou `user@host`) pour la récupération des pièces jointes par SCP.
-- `attachmentRoots` et `remoteAttachmentRoots` limitent les chemins des pièces jointes entrantes (par défaut : `/Users/*/Library/Messages/Attachments`).
-- SCP utilise une vérification stricte de la clé d’hôte ; assurez-vous donc que la clé de l’hôte relais existe déjà dans `~/.ssh/known_hosts`.
-- `channels.imessage.configWrites` : autoriser ou refuser les écritures de configuration initiées par iMessage.
-- Les entrées de niveau supérieur `bindings[]` avec `type: "acp"` peuvent lier des conversations iMessage à des sessions ACP persistantes. Utilisez un handle normalisé ou une cible de chat explicite (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique partagée des champs : [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
+- Préférez les cibles `chat_id:`. Utilisez `imsg chats --limit 20` pour lister les conversations.
+- `cliPath` peut pointer vers un wrapper SSH ; définissez `remoteHost` (`host` ou `user@host`) pour la récupération SCP des pièces jointes.
+- `attachmentRoots` et `remoteAttachmentRoots` restreignent les chemins des pièces jointes entrantes (par défaut : `/Users/*/Library/Messages/Attachments`).
+- SCP utilise une vérification stricte des clés d’hôte ; assurez-vous donc que la clé d’hôte du relais existe déjà dans `~/.ssh/known_hosts`.
+- `channels.imessage.configWrites` : autorise ou refuse les écritures de configuration initiées par iMessage.
+- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier des conversations iMessage à des sessions ACP persistantes. Utilisez un handle normalisé ou une cible de conversation explicite (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique de champ partagée : [Agents ACP](/fr/tools/acp-agents#channel-specific-settings).
@@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix est pris en charge par extension et configuré sous `channels.matrix`.
+Matrix est pris en charge par une extension et configuré sous `channels.matrix`.
```json5
{
@@ -669,24 +669,24 @@ Matrix est pris en charge par extension et configuré sous `channels.matrix`.
```
- L’authentification par jeton utilise `accessToken` ; l’authentification par mot de passe utilise `userId` + `password`.
-- `channels.matrix.proxy` route le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`.
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette option réseau sont des contrôles indépendants.
+- `channels.matrix.proxy` achemine le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette activation réseau sont des contrôles indépendants.
- `channels.matrix.defaultAccount` sélectionne le compte préféré dans les configurations multi-comptes.
-- `channels.matrix.autoJoin` vaut `off` par défaut, donc les salons invités et les nouvelles invitations de type DM sont ignorés jusqu’à ce que vous définissiez `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`.
-- `channels.matrix.execApprovals` : livraison native Matrix des approbations exec et autorisation des approbateurs.
- - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations exec s’activent lorsque les approbateurs peuvent être résolus depuis `approvers` ou `commands.ownerAllowFrom`.
- - `approvers` : identifiants d’utilisateurs Matrix (par ex. `@owner:example.org`) autorisés à approuver les demandes exec.
- - `agentFilter` : liste facultative d’identifiants d’agents autorisés. Omettez pour transférer les approbations pour tous les agents.
+- `channels.matrix.autoJoin` vaut par défaut `off`, donc les salons invités et les nouvelles invitations de type DM sont ignorés jusqu’à ce que vous définissiez `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`.
+- `channels.matrix.execApprovals` : livraison native Matrix des approbations d’exécution et autorisation des approbateurs.
+ - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations d’exécution s’activent lorsque des approbateurs peuvent être résolus depuis `approvers` ou `commands.ownerAllowFrom`.
+ - `approvers` : ID d’utilisateurs Matrix (par ex. `@owner:example.org`) autorisés à approuver des demandes d’exécution.
+ - `agentFilter` : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents.
- `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex).
- - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`.
+ - `target` : emplacement d’envoi des invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`.
- Remplacements par compte : `channels.matrix.accounts..execApprovals`.
- `channels.matrix.dm.sessionScope` contrôle la manière dont les DM Matrix sont regroupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon DM.
-- Les sondes d’état Matrix et les recherches de répertoire en direct utilisent la même politique de proxy que le trafic d’exécution.
-- La configuration complète de Matrix, les règles de ciblage et les exemples de configuration sont documentés dans [Matrix](/fr/channels/matrix).
+- Les sondes d’état Matrix et les consultations de répertoire en direct utilisent la même politique de proxy que le trafic d’exécution.
+- La configuration complète de Matrix, les règles de ciblage et les exemples d’installation sont documentés dans [Matrix](/fr/channels/matrix).
### Microsoft Teams
-Microsoft Teams est pris en charge par extension et configuré sous `channels.msteams`.
+Microsoft Teams est pris en charge par une extension et configuré sous `channels.msteams`.
```json5
{
@@ -701,12 +701,12 @@ Microsoft Teams est pris en charge par extension et configuré sous `channels.ms
}
```
-- Chemins de clés principales couverts ici : `channels.msteams`, `channels.msteams.configWrites`.
+- Chemins de clés principaux couverts ici : `channels.msteams`, `channels.msteams.configWrites`.
- La configuration complète de Teams (identifiants, webhook, politique DM/groupe, remplacements par équipe/par canal) est documentée dans [Microsoft Teams](/fr/channels/msteams).
### IRC
-IRC est pris en charge par extension et configuré sous `channels.irc`.
+IRC est pris en charge par une extension et configuré sous `channels.irc`.
```json5
{
@@ -727,8 +727,8 @@ IRC est pris en charge par extension et configuré sous `channels.irc`.
}
```
-- Chemins de clés principales couverts ici : `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
-- Le champ facultatif `channels.irc.defaultAccount` remplace la sélection du compte par défaut lorsqu’il correspond à un identifiant de compte configuré.
+- Chemins de clés principaux couverts ici : `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
+- `channels.irc.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré.
- La configuration complète du canal IRC (hôte/port/TLS/canaux/listes d’autorisations/filtrage par mention) est documentée dans [IRC](/fr/channels/irc).
### Multi-compte (tous les canaux)
@@ -756,26 +756,26 @@ Exécutez plusieurs comptes par canal (chacun avec son propre `accountId`) :
- `default` est utilisé lorsque `accountId` est omis (CLI + routage).
- Les jetons d’environnement s’appliquent uniquement au compte **default**.
-- Les paramètres de base du canal s’appliquent à tous les comptes sauf remplacement par compte.
+- Les paramètres de canal de base s’appliquent à tous les comptes sauf remplacement par compte.
- Utilisez `bindings[].match.accountId` pour router chaque compte vers un agent différent.
-- Si vous ajoutez un compte non par défaut via `openclaw channels add` (ou l’intégration d’un canal) tout en étant encore sur une configuration de canal mono-compte au niveau supérieur, OpenClaw promeut d’abord les valeurs mono-compte de niveau supérieur limitées au compte dans la map de comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent dans `channels..accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante.
-- Les liaisons existantes uniquement au niveau canal (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons limitées à un compte restent facultatives.
-- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs mono-compte de niveau supérieur limitées au compte dans le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut conserver une cible nommée/par défaut existante correspondante.
+- Si vous ajoutez un compte non par défaut via `openclaw channels add` (ou l’intégration du canal) alors que vous utilisez encore une configuration de canal de niveau supérieur à compte unique, OpenClaw promeut d’abord les valeurs de niveau supérieur à compte unique limitées au compte dans la map de comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent vers `channels..accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante.
+- Les liaisons existantes limitées au canal (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons limitées au compte restent facultatives.
+- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs de niveau supérieur à compte unique limitées au compte vers le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante.
### Autres canaux d’extension
-De nombreux canaux d’extension sont configurés comme `channels.` et documentés dans leurs pages de canal dédiées (par exemple Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat et Twitch).
-Voir l’index complet des canaux : [Canaux](/fr/channels).
+De nombreux canaux d’extension sont configurés sous la forme `channels.` et documentés dans leurs pages de canal dédiées (par exemple Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat et Twitch).
+Consultez l’index complet des canaux : [Canaux](/fr/channels).
### Filtrage par mention dans les discussions de groupe
-Les messages de groupe exigent par défaut **une mention** (mention de métadonnées ou motifs regex sûrs). Cela s’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage.
+Par défaut, les messages de groupe **nécessitent une mention** (mention de métadonnées ou modèles regex sûrs). Cela s’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage.
**Types de mention :**
-- **Mentions de métadonnées** : @-mentions natives de la plateforme. Ignorées en mode self-chat WhatsApp.
-- **Motifs texte** : motifs regex sûrs dans `agents.list[].groupChat.mentionPatterns`. Les motifs invalides et les répétitions imbriquées non sûres sont ignorés.
-- Le filtrage par mention n’est appliqué que lorsque la détection est possible (mentions natives ou au moins un motif).
+- **Mentions de métadonnées** : @-mentions natives de la plateforme. Ignorées en mode auto-discussion WhatsApp.
+- **Modèles de texte** : modèles regex sûrs dans `agents.list[].groupChat.mentionPatterns`. Les modèles invalides et les répétitions imbriquées non sûres sont ignorés.
+- Le filtrage par mention n’est appliqué que lorsque la détection est possible (mentions natives ou au moins un modèle).
```json5
{
@@ -788,7 +788,7 @@ Les messages de groupe exigent par défaut **une mention** (mention de métadonn
}
```
-`messages.groupChat.historyLimit` définit la valeur globale par défaut. Les canaux peuvent remplacer avec `channels..historyLimit` (ou par compte). Définissez `0` pour désactiver.
+`messages.groupChat.historyLimit` définit la valeur globale par défaut. Les canaux peuvent la remplacer avec `channels..historyLimit` (ou par compte). Définissez `0` pour désactiver.
#### Limites d’historique des DM
@@ -805,13 +805,13 @@ Les messages de groupe exigent par défaut **une mention** (mention de métadonn
}
```
-Résolution : remplacement par DM → valeur par défaut du fournisseur → aucune limite (tout est conservé).
+Résolution : remplacement par DM → valeur par défaut du fournisseur → pas de limite (tout est conservé).
Pris en charge : `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
-#### Mode self-chat
+#### Mode auto-discussion
-Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ignore les @-mentions natives, répond uniquement aux motifs texte) :
+Incluez votre propre numéro dans `allowFrom` pour activer le mode auto-discussion (ignore les @-mentions natives, répond uniquement aux modèles de texte) :
```json5
{
@@ -861,32 +861,32 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ig
-- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + fournies en bundle, voir [Commandes Slash](/fr/tools/slash-commands).
-- Cette page est une **référence de clés de configuration**, pas le catalogue complet des commandes. Les commandes appartenant à un canal/plugin, telles que QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` et Talk `/voice`, sont documentées dans leurs pages de canal/plugin ainsi que dans [Commandes Slash](/fr/tools/slash-commands).
+- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + groupées, consultez [Commandes Slash](/fr/tools/slash-commands).
+- Cette page est une **référence des clés de configuration**, et non le catalogue complet des commandes. Les commandes appartenant à un canal/plugin telles que QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` et Talk `/voice` sont documentées dans leurs pages de canal/plugin ainsi que dans [Commandes Slash](/fr/tools/slash-commands).
- Les commandes texte doivent être des messages **autonomes** avec un `/` initial.
-- `native: "auto"` active les commandes natives pour Discord/Telegram, laisse Slack désactivé.
-- `nativeSkills: "auto"` active les commandes Skills natives pour Discord/Telegram, laisse Slack désactivé.
+- `native: "auto"` active les commandes natives pour Discord/Telegram, et laisse Slack désactivé.
+- `nativeSkills: "auto"` active les commandes de Skills natives pour Discord/Telegram, et laisse Slack désactivé.
- Remplacement par canal : `channels.discord.commands.native` (booléen ou `"auto"`). `false` efface les commandes précédemment enregistrées.
- Remplacez l’enregistrement natif des Skills par canal avec `channels..commands.nativeSkills`.
- `channels.telegram.customCommands` ajoute des entrées supplémentaires au menu du bot Telegram.
-- `bash: true` active `! ` pour le shell hôte. Nécessite `tools.elevated.enabled` et l’expéditeur dans `tools.elevated.allowFrom.`.
-- `config: true` active `/config` (lit/écrit `openclaw.json`). Pour les clients de passerelle `chat.send`, les écritures persistantes `/config set|unset` exigent également `operator.admin` ; le mode lecture seule `/config show` reste disponible pour les clients opérateur normaux avec portée d’écriture.
-- `mcp: true` active `/mcp` pour la configuration du serveur MCP gérée par OpenClaw sous `mcp.servers`.
-- `plugins: true` active `/plugins` pour la découverte, l’installation et les contrôles d’activation/désactivation des plugins.
+- `bash: true` active `! ` pour le shell hôte. Nécessite `tools.elevated.enabled` et que l’expéditeur soit dans `tools.elevated.allowFrom.`.
+- `config: true` active `/config` (lit/écrit `openclaw.json`). Pour les clients de passerelle `chat.send`, les écritures persistantes `/config set|unset` nécessitent également `operator.admin` ; le `/config show` en lecture seule reste disponible pour les clients opérateur normaux avec portée d’écriture.
+- `mcp: true` active `/mcp` pour la configuration des serveurs MCP gérés par OpenClaw sous `mcp.servers`.
+- `plugins: true` active `/plugins` pour la découverte, l’installation, et les contrôles d’activation/désactivation des plugins.
- `channels..configWrites` contrôle les mutations de configuration par canal (par défaut : true).
-- Pour les canaux multi-comptes, `channels..accounts..configWrites` contrôle également les écritures ciblant ce compte (par exemple `/allowlist --config --account ` ou `/config set channels..accounts....`).
-- `restart: false` désactive `/restart` et les actions de l’outil de redémarrage de passerelle. Par défaut : `true`.
+- Pour les canaux multi-comptes, `channels..accounts..configWrites` contrôle également les écritures qui ciblent ce compte (par exemple `/allowlist --config --account ` ou `/config set channels..accounts....`).
+- `restart: false` désactive `/restart` et les actions de l’outil de redémarrage de la passerelle. Par défaut : `true`.
- `ownerAllowFrom` est la liste d’autorisations explicite du propriétaire pour les commandes/outils réservés au propriétaire. Elle est distincte de `allowFrom`.
-- `ownerDisplay: "hash"` hache les identifiants du propriétaire dans le prompt système. Définissez `ownerDisplaySecret` pour contrôler le hachage.
-- `allowFrom` est par fournisseur. Lorsqu’il est défini, c’est la **seule** source d’autorisation (les listes d’autorisations/l’association du canal et `useAccessGroups` sont ignorés).
-- `useAccessGroups: false` permet aux commandes de contourner les politiques de groupe d’accès lorsque `allowFrom` n’est pas défini.
-- Carte de la documentation des commandes :
- - catalogue intégré + en bundle : [Commandes Slash](/fr/tools/slash-commands)
- - surfaces de commandes spécifiques aux canaux : [Canaux](/fr/channels)
+- `ownerDisplay: "hash"` hache les ID du propriétaire dans le prompt système. Définissez `ownerDisplaySecret` pour contrôler le hachage.
+- `allowFrom` est défini par fournisseur. Lorsqu’il est défini, c’est la **seule** source d’autorisation (les listes d’autorisations/appairages de canal et `useAccessGroups` sont ignorés).
+- `useAccessGroups: false` permet aux commandes de contourner les politiques de groupes d’accès lorsque `allowFrom` n’est pas défini.
+- Cartographie de la documentation des commandes :
+ - catalogue intégré + groupé : [Commandes Slash](/fr/tools/slash-commands)
+ - surfaces de commande spécifiques au canal : [Canaux](/fr/channels)
- commandes QQ Bot : [QQ Bot](/fr/channels/qqbot)
- - commandes d’association : [Association](/fr/channels/pairing)
- - commande card de LINE : [LINE](/fr/channels/line)
- - dreaming mémoire : [Dreaming](/fr/concepts/dreaming)
+ - commandes d’appairage : [Appairage](/fr/channels/pairing)
+ - commande de carte LINE : [LINE](/fr/channels/line)
+ - rêverie de la mémoire : [Rêverie](/fr/concepts/dreaming)
@@ -896,7 +896,7 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ig
### `agents.defaults.workspace`
-Valeur par défaut : `~/.openclaw/workspace`.
+Par défaut : `~/.openclaw/workspace`.
```json5
{
@@ -916,7 +916,7 @@ Racine de dépôt facultative affichée dans la ligne Runtime du prompt système
### `agents.defaults.skills`
-Liste d’autorisations Skills par défaut facultative pour les agents qui ne définissent pas
+Liste d’autorisations par défaut facultative des Skills pour les agents qui ne définissent pas
`agents.list[].skills`.
```json5
@@ -924,23 +924,23 @@ Liste d’autorisations Skills par défaut facultative pour les agents qui ne d
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // inherits github, weather
- { id: "docs", skills: ["docs-search"] }, // replaces defaults
- { id: "locked-down", skills: [] }, // no skills
+ { id: "writer" }, // hérite de github, weather
+ { id: "docs", skills: ["docs-search"] }, // remplace les valeurs par défaut
+ { id: "locked-down", skills: [] }, // aucun Skills
],
},
}
```
-- Omettez `agents.defaults.skills` pour des Skills sans restriction par défaut.
+- Omettez `agents.defaults.skills` pour des Skills non restreints par défaut.
- Omettez `agents.list[].skills` pour hériter des valeurs par défaut.
- Définissez `agents.list[].skills: []` pour aucun Skills.
-- Une liste `agents.list[].skills` non vide est l’ensemble final pour cet agent ; elle
+- Une liste non vide dans `agents.list[].skills` constitue l’ensemble final pour cet agent ; elle
n’est pas fusionnée avec les valeurs par défaut.
### `agents.defaults.skipBootstrap`
-Désactive la création automatique des fichiers bootstrap d’espace de travail (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
+Désactive la création automatique des fichiers bootstrap de l’espace de travail (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@@ -950,9 +950,9 @@ Désactive la création automatique des fichiers bootstrap d’espace de travail
### `agents.defaults.contextInjection`
-Contrôle quand les fichiers bootstrap d’espace de travail sont injectés dans le prompt système. Valeur par défaut : `"always"`.
+Contrôle quand les fichiers bootstrap de l’espace de travail sont injectés dans le prompt système. Par défaut : `"always"`.
-- `"continuation-skip"` : les tours de continuation sûrs (après une réponse de l’assistant terminée) ignorent la réinjection du bootstrap d’espace de travail, réduisant la taille du prompt. Les exécutions heartbeat et les nouvelles tentatives après compaction reconstruisent tout de même le contexte.
+- `"continuation-skip"` : les tours de continuation sûrs (après une réponse d’assistant terminée) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille du prompt. Les exécutions heartbeat et les nouvelles tentatives après compactage reconstruisent toujours le contexte.
```json5
{
@@ -962,7 +962,7 @@ Contrôle quand les fichiers bootstrap d’espace de travail sont injectés dans
### `agents.defaults.bootstrapMaxChars`
-Nombre maximal de caractères par fichier bootstrap d’espace de travail avant troncature. Valeur par défaut : `20000`.
+Nombre maximal de caractères par fichier bootstrap de l’espace de travail avant troncature. Par défaut : `20000`.
```json5
{
@@ -972,7 +972,7 @@ Nombre maximal de caractères par fichier bootstrap d’espace de travail avant
### `agents.defaults.bootstrapTotalMaxChars`
-Nombre maximal total de caractères injectés sur l’ensemble des fichiers bootstrap d’espace de travail. Valeur par défaut : `150000`.
+Nombre total maximal de caractères injectés sur l’ensemble des fichiers bootstrap de l’espace de travail. Par défaut : `150000`.
```json5
{
@@ -983,7 +983,7 @@ Nombre maximal total de caractères injectés sur l’ensemble des fichiers boot
### `agents.defaults.bootstrapPromptTruncationWarning`
Contrôle le texte d’avertissement visible par l’agent lorsque le contexte bootstrap est tronqué.
-Valeur par défaut : `"once"`.
+Par défaut : `"once"`.
- `"off"` : ne jamais injecter de texte d’avertissement dans le prompt système.
- `"once"` : injecter l’avertissement une fois par signature de troncature unique (recommandé).
@@ -997,10 +997,10 @@ Valeur par défaut : `"once"`.
### `agents.defaults.imageMaxDimensionPx`
-Taille maximale en pixels du côté le plus long des images dans les blocs image du transcript/de l’outil avant les appels fournisseur.
-Valeur par défaut : `1200`.
+Taille maximale en pixels du plus long côté d’une image dans les blocs image de transcription/outil avant les appels fournisseur.
+Par défaut : `1200`.
-Des valeurs plus faibles réduisent généralement l’usage de jetons de vision et la taille de la charge utile des requêtes pour les exécutions riches en captures d’écran.
+Des valeurs plus faibles réduisent généralement l’utilisation de jetons de vision et la taille de la charge utile des requêtes pour les exécutions riches en captures d’écran.
Des valeurs plus élevées préservent davantage de détails visuels.
```json5
@@ -1011,7 +1011,7 @@ Des valeurs plus élevées préservent davantage de détails visuels.
### `agents.defaults.userTimezone`
-Fuseau horaire pour le contexte du prompt système (pas les horodatages des messages). Se replie sur le fuseau horaire de l’hôte.
+Fuseau horaire pour le contexte du prompt système (pas pour les horodatages des messages). Utilise le fuseau horaire de l’hôte comme solution de repli.
```json5
{
@@ -1021,7 +1021,7 @@ Fuseau horaire pour le contexte du prompt système (pas les horodatages des mess
### `agents.defaults.timeFormat`
-Format de l’heure dans le prompt système. Valeur par défaut : `auto` (préférence du système).
+Format de l’heure dans le prompt système. Par défaut : `auto` (préférence du système d’exploitation).
```json5
{
@@ -1059,7 +1059,7 @@ Format de l’heure dans le prompt système. Valeur par défaut : `auto` (préf
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
- params: { cacheRetention: "long" }, // global default provider params
+ params: { cacheRetention: "long" }, // paramètres fournisseur globaux par défaut
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
thinkingDefault: "low",
@@ -1076,41 +1076,41 @@ Format de l’heure dans le prompt système. Valeur par défaut : `auto` (préf
- `model` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- La forme chaîne définit uniquement le modèle principal.
- - La forme objet définit le principal plus les modèles de basculement ordonnés.
+ - La forme objet définit le modèle principal ainsi que des modèles de bascule ordonnés.
- `imageModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- - Utilisé par le chemin de l’outil `image` comme configuration de modèle de vision.
- - Également utilisé comme routage de repli lorsque le modèle sélectionné/par défaut n’accepte pas d’entrée image.
+ - Utilisé par le chemin de l’outil `image` comme configuration de son modèle de vision.
+ - Également utilisé comme routage de repli lorsque le modèle sélectionné/par défaut ne peut pas accepter d’entrée image.
- `imageGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- Utilisé par la capacité partagée de génération d’images et toute future surface d’outil/plugin qui génère des images.
- - Valeurs typiques : `google/gemini-3.1-flash-image-preview` pour la génération d’images native Gemini, `fal/fal-ai/flux/dev` pour fal, ou `openai/gpt-image-1` pour OpenAI Images.
- - Si vous sélectionnez directement un fournisseur/modèle, configurez également l’authentification/la clé API du fournisseur correspondant (par exemple `GEMINI_API_KEY` ou `GOOGLE_API_KEY` pour `google/*`, `OPENAI_API_KEY` pour `openai/*`, `FAL_KEY` pour `fal/*`).
- - S’il est omis, `image_generate` peut tout de même inférer une valeur par défaut de fournisseur avec auth. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’images enregistrés restants selon l’ordre des identifiants de fournisseur.
+ - Valeurs typiques : `google/gemini-3.1-flash-image-preview` pour la génération d’images Gemini native, `fal/fal-ai/flux/dev` pour fal, ou `openai/gpt-image-1` pour OpenAI Images.
+ - Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant (par exemple `GEMINI_API_KEY` ou `GOOGLE_API_KEY` pour `google/*`, `OPENAI_API_KEY` pour `openai/*`, `FAL_KEY` pour `fal/*`).
+ - Si omis, `image_generate` peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération d’images enregistrés dans l’ordre des ID de provider.
- `musicGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- Utilisé par la capacité partagée de génération musicale et l’outil intégré `music_generate`.
- - Valeurs typiques : `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.5+`.
- - S’il est omis, `music_generate` peut tout de même inférer une valeur par défaut de fournisseur avec auth. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale enregistrés restants selon l’ordre des identifiants de fournisseur.
- - Si vous sélectionnez directement un fournisseur/modèle, configurez également l’authentification/la clé API du fournisseur correspondant.
+ - Valeurs typiques : `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, ou `minimax/music-2.5+`.
+ - Si omis, `music_generate` peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération musicale enregistrés dans l’ordre des ID de provider.
+ - Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant.
- `videoGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- Utilisé par la capacité partagée de génération vidéo et l’outil intégré `video_generate`.
- - Valeurs typiques : `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`.
- - S’il est omis, `video_generate` peut tout de même inférer une valeur par défaut de fournisseur avec auth. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération vidéo enregistrés restants selon l’ordre des identifiants de fournisseur.
- - Si vous sélectionnez directement un fournisseur/modèle, configurez également l’authentification/la clé API du fournisseur correspondant.
- - Le fournisseur groupé de génération vidéo Qwen prend en charge jusqu’à 1 vidéo de sortie, 1 image d’entrée, 4 vidéos d’entrée, une durée de 10 secondes, ainsi que les options de niveau fournisseur `size`, `aspectRatio`, `resolution`, `audio` et `watermark`.
+ - Valeurs typiques : `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, ou `qwen/wan2.7-r2v`.
+ - Si omis, `video_generate` peut tout de même déduire une valeur par défaut de provider avec authentification. Il essaie d’abord le provider par défaut actuel, puis les autres providers de génération vidéo enregistrés dans l’ordre des ID de provider.
+ - Si vous sélectionnez directement un provider/modèle, configurez également l’authentification/la clé API du provider correspondant.
+ - Le provider groupé de génération vidéo Qwen prend en charge jusqu’à 1 vidéo de sortie, 1 image d’entrée, 4 vidéos d’entrée, une durée de 10 secondes, ainsi que les options de niveau provider `size`, `aspectRatio`, `resolution`, `audio` et `watermark`.
- `pdfModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`).
- - Utilisé par l’outil `pdf` pour le routage de modèle.
- - S’il est omis, l’outil PDF se replie sur `imageModel`, puis sur le modèle résolu de session/par défaut.
-- `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas passé au moment de l’appel.
-- `pdfMaxPages` : nombre maximal de pages pris en compte par défaut par le mode de repli d’extraction dans l’outil `pdf`.
-- `verboseDefault` : niveau verbose par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Valeur par défaut : `"off"`.
-- `elevatedDefault` : niveau de sortie elevated par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"ask"`, `"full"`. Valeur par défaut : `"on"`.
-- `model.primary` : format `provider/model` (par ex. `openai/gpt-5.4`). Si vous omettez le fournisseur, OpenClaw essaie d’abord un alias, puis une correspondance unique de fournisseur configuré pour cet identifiant de modèle exact, et seulement ensuite se replie sur le fournisseur par défaut configuré (comportement de compatibilité déprécié, préférez donc `provider/model` explicite). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw se replie sur le premier fournisseur/modèle configuré au lieu d’exposer un modèle par défaut périmé supprimé.
-- `models` : catalogue et liste d’autorisations de modèles configurés pour `/model`. Chaque entrée peut inclure `alias` (raccourci) et `params` (spécifiques au fournisseur, par exemple `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
-- `params` : paramètres globaux par défaut du fournisseur appliqués à tous les modèles. À définir dans `agents.defaults.params` (par ex. `{ cacheRetention: "long" }`).
-- Priorité de fusion de `params` (configuration) : `agents.defaults.params` (base globale) est remplacé par `agents.defaults.models["provider/model"].params` (par modèle), puis `agents.list[].params` (identifiant d’agent correspondant) remplace par clé. Voir [Prompt Caching](/fr/reference/prompt-caching) pour plus de détails.
-- Les écrivains de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de repli) enregistrent la forme objet canonique et préservent les listes de repli existantes lorsque possible.
-- `maxConcurrent` : nombre maximal d’exécutions d’agents parallèles entre les sessions (chaque session reste sérialisée). Valeur par défaut : 4.
+ - Utilisé par l’outil `pdf` pour le routage du modèle.
+ - Si omis, l’outil PDF se replie sur `imageModel`, puis sur le modèle de session/par défaut résolu.
+- `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas transmis au moment de l’appel.
+- `pdfMaxPages` : nombre maximal de pages par défaut pris en compte par le mode de repli d’extraction dans l’outil `pdf`.
+- `verboseDefault` : niveau détaillé par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`.
+- `elevatedDefault` : niveau de sortie élevée par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"ask"`, `"full"`. Par défaut : `"on"`.
+- `model.primary` : format `provider/model` (par ex. `openai/gpt-5.4`). Si vous omettez le provider, OpenClaw essaie d’abord un alias, puis une correspondance unique de provider configuré pour cet ID de modèle exact, et seulement ensuite revient au provider par défaut configuré (comportement de compatibilité obsolète, donc préférez `provider/model` explicite). Si ce provider n’expose plus le modèle par défaut configuré, OpenClaw se replie sur le premier provider/modèle configuré au lieu d’exposer une valeur par défaut obsolète d’un provider supprimé.
+- `models` : catalogue de modèles configuré et liste d’autorisations pour `/model`. Chaque entrée peut inclure `alias` (raccourci) et `params` (spécifiques au provider, par exemple `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
+- `params` : paramètres provider globaux par défaut appliqués à tous les modèles. Définis dans `agents.defaults.params` (par ex. `{ cacheRetention: "long" }`).
+- Priorité de fusion de `params` (configuration) : `agents.defaults.params` (base globale) est remplacé par `agents.defaults.models["provider/model"].params` (par modèle), puis `agents.list[].params` (ID d’agent correspondant) remplace par clé. Consultez [Mise en cache des prompts](/fr/reference/prompt-caching) pour plus de détails.
+- Les outils d’écriture de configuration qui mutent ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de repli) enregistrent la forme objet canonique et préservent les listes de repli existantes lorsque c’est possible.
+- `maxConcurrent` : nombre maximal d’exécutions d’agent parallèles entre les sessions (chaque session reste sérialisée). Par défaut : 4.
-**Raccourcis d’alias intégrés** (s’appliquent uniquement lorsque le modèle est dans `agents.defaults.models`) :
+**Alias raccourcis intégrés** (s’appliquent uniquement lorsque le modèle est dans `agents.defaults.models`) :
| Alias | Modèle |
| ------------------- | -------------------------------------- |
@@ -1125,13 +1125,13 @@ Format de l’heure dans le prompt système. Valeur par défaut : `auto` (préf
Vos alias configurés ont toujours priorité sur les valeurs par défaut.
-Les modèles Z.AI GLM-4.x activent automatiquement le mode thinking à moins que vous définissiez `--thinking off` ou `agents.defaults.models["zai/"].params.thinking` vous-même.
-Les modèles Z.AI activent `tool_stream` par défaut pour le streaming des appels d’outils. Définissez `agents.defaults.models["zai/"].params.tool_stream` à `false` pour le désactiver.
-Les modèles Anthropic Claude 4.6 utilisent par défaut le thinking `adaptive` lorsqu’aucun niveau de thinking explicite n’est défini.
+Les modèles Z.AI GLM-4.x activent automatiquement le mode réflexion, sauf si vous définissez `--thinking off` ou si vous définissez vous-même `agents.defaults.models["zai/"].params.thinking`.
+Les modèles Z.AI activent `tool_stream` par défaut pour le streaming des appels d’outils. Définissez `agents.defaults.models["zai/"].params.tool_stream` sur `false` pour le désactiver.
+Les modèles Anthropic Claude 4.6 utilisent par défaut la réflexion `adaptive` lorsqu’aucun niveau de réflexion explicite n’est défini.
### `agents.defaults.cliBackends`
-Backends CLI facultatifs pour les exécutions de repli texte uniquement (sans appels d’outils). Utile comme secours lorsque les fournisseurs API échouent.
+Backends CLI facultatifs pour les exécutions de repli texte uniquement (sans appels d’outils). Utiles comme sauvegarde lorsque les providers d’API échouent.
```json5
{
@@ -1159,13 +1159,13 @@ Backends CLI facultatifs pour les exécutions de repli texte uniquement (sans ap
}
```
-- Les backends CLI sont d’abord orientés texte ; les outils sont toujours désactivés.
-- Sessions prises en charge lorsque `sessionArg` est défini.
-- Le passage d’images est pris en charge lorsque `imageArg` accepte des chemins de fichiers.
+- Les backends CLI sont orientés texte ; les outils sont toujours désactivés.
+- Les sessions sont prises en charge lorsque `sessionArg` est défini.
+- Le passage d’image est pris en charge lorsque `imageArg` accepte des chemins de fichier.
### `agents.defaults.systemPromptOverride`
-Remplace l’intégralité du prompt système assemblé par OpenClaw par une chaîne fixe. À définir au niveau par défaut (`agents.defaults.systemPromptOverride`) ou par agent (`agents.list[].systemPromptOverride`). Les valeurs par agent ont priorité ; une valeur vide ou composée uniquement d’espaces est ignorée. Utile pour des expériences contrôlées sur les prompts.
+Remplace l’intégralité du prompt système assemblé par OpenClaw par une chaîne fixe. À définir au niveau par défaut (`agents.defaults.systemPromptOverride`) ou par agent (`agents.list[].systemPromptOverride`). Les valeurs par agent ont priorité ; une valeur vide ou contenant uniquement des espaces est ignorée. Utile pour des expériences contrôlées sur les prompts.
```json5
{
@@ -1205,14 +1205,14 @@ Exécutions heartbeat périodiques.
}
```
-- `every` : chaîne de durée (ms/s/m/h). Valeur par défaut : `30m` (authentification par clé API) ou `1h` (authentification OAuth). Définissez `0m` pour désactiver.
-- `includeSystemPromptSection` : lorsque false, omet la section Heartbeat du prompt système et saute l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Valeur par défaut : `true`.
+- `every` : chaîne de durée (ms/s/m/h). Par défaut : `30m` (authentification par clé API) ou `1h` (authentification OAuth). Définissez `0m` pour désactiver.
+- `includeSystemPromptSection` : lorsque false, omet la section Heartbeat du prompt système et ignore l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Par défaut : `true`.
- `suppressToolErrorWarnings` : lorsque true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions heartbeat.
-- `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison vers une cible directe. `block` supprime la livraison vers une cible directe et émet `reason=dm-blocked`.
+- `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison à cible directe. `block` supprime la livraison à cible directe et émet `reason=dm-blocked`.
- `lightContext` : lorsque true, les exécutions heartbeat utilisent un contexte bootstrap léger et ne conservent que `HEARTBEAT.md` parmi les fichiers bootstrap de l’espace de travail.
-- `isolatedSession` : lorsque true, chaque exécution heartbeat s’effectue dans une nouvelle session sans historique de conversation antérieur. Même schéma d’isolation que le cron `sessionTarget: "isolated"`. Réduit le coût en jetons par heartbeat d’environ ~100K à ~2-5K jetons.
-- Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent quelconque définit `heartbeat`, **seuls ces agents** exécutent les heartbeats.
-- Les heartbeats exécutent des tours complets d’agent — des intervalles plus courts consomment davantage de jetons.
+- `isolatedSession` : lorsque true, chaque exécution heartbeat se fait dans une session fraîche sans historique de conversation préalable. Même schéma d’isolation que le cron `sessionTarget: "isolated"`. Réduit le coût en jetons par heartbeat d’environ 100K à environ 2-5K jetons.
+- Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent quelconque définit `heartbeat`, **seuls ces agents** exécutent des heartbeats.
+- Les heartbeats exécutent des tours d’agent complets — des intervalles plus courts consomment plus de jetons.
### `agents.defaults.compaction`
@@ -1242,19 +1242,19 @@ Exécutions heartbeat périodiques.
}
```
-- `mode` : `default` ou `safeguard` (résumé par blocs pour les historiques longs). Voir [Compaction](/fr/concepts/compaction).
-- `provider` : identifiant d’un plugin fournisseur de compaction enregistré. Lorsqu’il est défini, `summarize()` du fournisseur est appelée à la place du résumé LLM intégré. Replis sur l’implémentation intégrée en cas d’échec. Définir un fournisseur force `mode: "safeguard"`. Voir [Compaction](/fr/concepts/compaction).
-- `timeoutSeconds` : nombre maximal de secondes autorisées pour une opération de compaction unique avant qu’OpenClaw l’abandonne. Valeur par défaut : `900`.
-- `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` ajoute en préfixe des instructions intégrées de conservation des identifiants opaques pendant la synthèse de compaction.
-- `identifierInstructions` : texte facultatif personnalisé de préservation des identifiants utilisé lorsque `identifierPolicy=custom`.
-- `postCompactionSections` : noms facultatifs de sections H2/H3 de `AGENTS.md` à réinjecter après compaction. Valeur par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il est non défini ou explicitement défini à cette paire par défaut, les anciens en-têtes `Every Session`/`Safety` sont également acceptés comme repli hérité.
-- `model` : remplacement facultatif `provider/model-id` pour la synthèse de compaction uniquement. Utilisez-le lorsque la session principale doit conserver un modèle mais que les résumés de compaction doivent s’exécuter sur un autre ; lorsqu’il n’est pas défini, la compaction utilise le modèle principal de la session.
-- `notifyUser` : lorsque `true`, envoie une brève notification à l’utilisateur au début de la compaction (par exemple, « Compacting context... »). Désactivé par défaut pour garder la compaction silencieuse.
-- `memoryFlush` : tour agentique silencieux avant auto-compaction pour stocker des souvenirs durables. Ignoré lorsque l’espace de travail est en lecture seule.
+- `mode` : `default` ou `safeguard` (résumés par blocs pour les longs historiques). Voir [Compaction](/fr/concepts/compaction).
+- `provider` : ID d’un plugin provider de compaction enregistré. Lorsqu’il est défini, le `summarize()` du provider est appelé à la place du résumé LLM intégré. Revient à l’implémentation intégrée en cas d’échec. Définir un provider force `mode: "safeguard"`. Voir [Compaction](/fr/concepts/compaction).
+- `timeoutSeconds` : nombre maximal de secondes autorisé pour une seule opération de compaction avant qu’OpenClaw l’abandonne. Par défaut : `900`.
+- `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` ajoute en préambule les consignes intégrées de conservation des identifiants opaques pendant le résumé de compaction.
+- `identifierInstructions` : texte personnalisé facultatif de préservation des identifiants, utilisé lorsque `identifierPolicy=custom`.
+- `postCompactionSections` : noms facultatifs de sections H2/H3 de `AGENTS.md` à réinjecter après compaction. Par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il n’est pas défini ou qu’il est explicitement défini sur cette paire par défaut, les anciens titres `Every Session`/`Safety` sont également acceptés comme solution de repli héritée.
+- `model` : remplacement facultatif `provider/model-id` pour le résumé de compaction uniquement. Utilisez-le lorsque la session principale doit conserver un modèle mais que les résumés de compaction doivent s’exécuter sur un autre ; lorsqu’il n’est pas défini, la compaction utilise le modèle principal de la session.
+- `notifyUser` : lorsque `true`, envoie un bref avis à l’utilisateur au démarrage de la compaction (par exemple « Compactage du contexte... »). Désactivé par défaut pour garder la compaction silencieuse.
+- `memoryFlush` : tour agentique silencieux avant l’auto-compaction pour stocker des souvenirs durables. Ignoré lorsque l’espace de travail est en lecture seule.
### `agents.defaults.contextPruning`
-Élague les **anciens résultats d’outils** du contexte en mémoire avant l’envoi au LLM. Ne **modifie pas** l’historique de session sur disque.
+Élague les **anciens résultats d’outil** du contexte en mémoire avant l’envoi au LLM. **Ne modifie pas** l’historique de session sur disque.
```json5
{
@@ -1279,8 +1279,8 @@ Exécutions heartbeat périodiques.
- `mode: "cache-ttl"` active les passes d’élagage.
-- `ttl` contrôle la fréquence à laquelle l’élagage peut se réexécuter (après le dernier accès au cache).
-- L’élagage commence par réduire partiellement les résultats d’outils surdimensionnés, puis efface complètement les anciens résultats si nécessaire.
+- `ttl` contrôle à quelle fréquence l’élagage peut se réexécuter (après le dernier accès au cache).
+- L’élagage réduit d’abord partiellement les résultats d’outil surdimensionnés, puis efface complètement les résultats d’outil plus anciens si nécessaire.
**Réduction partielle** conserve le début + la fin et insère `...` au milieu.
@@ -1290,11 +1290,11 @@ Remarques :
- Les blocs image ne sont jamais réduits/effacés.
- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptes exacts de jetons.
-- Si le nombre de messages assistant est inférieur à `keepLastAssistants`, l’élagage est ignoré.
+- S’il existe moins de `keepLastAssistants` messages assistant, l’élagage est ignoré.
-Voir [Élagage de session](/fr/concepts/session-pruning) pour les détails de comportement.
+Consultez [Élagage de session](/fr/concepts/session-pruning) pour les détails du comportement.
### Streaming par blocs
@@ -1314,9 +1314,9 @@ Voir [Élagage de session](/fr/concepts/session-pruning) pour les détails de co
- Les canaux autres que Telegram nécessitent `*.blockStreaming: true` explicite pour activer les réponses par blocs.
- Remplacements par canal : `channels..blockStreamingCoalesce` (et variantes par compte). Signal/Slack/Discord/Google Chat utilisent par défaut `minChars: 1500`.
-- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500ms. Remplacement par agent : `agents.list[].humanDelay`.
+- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500 ms. Remplacement par agent : `agents.list[].humanDelay`.
-Voir [Streaming](/fr/concepts/streaming) pour le comportement + les détails de découpage.
+Consultez [Streaming](/fr/concepts/streaming) pour le comportement et les détails du découpage.
### Indicateurs de saisie
@@ -1331,16 +1331,16 @@ Voir [Streaming](/fr/concepts/streaming) pour le comportement + les détails de
}
```
-- Valeurs par défaut : `instant` pour les chats directs/mentions, `message` pour les discussions de groupe sans mention.
+- Valeurs par défaut : `instant` pour les conversations directes/mentions, `message` pour les discussions de groupe sans mention.
- Remplacements par session : `session.typingMode`, `session.typingIntervalSeconds`.
-Voir [Indicateurs de saisie](/fr/concepts/typing-indicators).
+Consultez [Indicateurs de saisie](/fr/concepts/typing-indicators).
### `agents.defaults.sandbox`
-Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sandboxing) pour le guide complet.
+Sandboxing facultatif pour l’agent intégré. Consultez [Sandboxing](/fr/gateway/sandboxing) pour le guide complet.
```json5
{
@@ -1439,20 +1439,20 @@ Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sa
**Backend :**
-- `docker` : runtime Docker local (par défaut)
-- `ssh` : runtime distant générique basé sur SSH
-- `openshell` : runtime OpenShell
+- `docker` : environnement Docker local (par défaut)
+- `ssh` : environnement distant générique via SSH
+- `openshell` : environnement OpenShell
-Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques au runtime sont déplacés dans
+Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques à l’environnement sont déplacés vers
`plugins.entries.openshell.config`.
**Configuration du backend SSH :**
- `target` : cible SSH au format `user@host[:port]`
-- `command` : commande client SSH (par défaut : `ssh`)
+- `command` : commande du client SSH (par défaut : `ssh`)
- `workspaceRoot` : racine distante absolue utilisée pour les espaces de travail par portée
- `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants transmis à OpenSSH
-- `identityData` / `certificateData` / `knownHostsData` : contenus inline ou SecretRefs que OpenClaw matérialise dans des fichiers temporaires à l’exécution
+- `identityData` / `certificateData` / `knownHostsData` : contenus en ligne ou SecretRefs qu’OpenClaw matérialise en fichiers temporaires à l’exécution
- `strictHostKeyChecking` / `updateHostKeys` : options de politique de clé d’hôte OpenSSH
**Priorité d’authentification SSH :**
@@ -1460,21 +1460,21 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques a
- `identityData` a priorité sur `identityFile`
- `certificateData` a priorité sur `certificateFile`
- `knownHostsData` a priorité sur `knownHostsFile`
-- Les valeurs `*Data` basées sur SecretRef sont résolues depuis l’instantané d’exécution des secrets actif avant le démarrage de la session sandbox
+- Les valeurs `*Data` basées sur SecretRef sont résolues à partir de l’instantané actif de l’environnement des secrets avant le démarrage de la session sandbox
**Comportement du backend SSH :**
- initialise l’espace de travail distant une fois après création ou recréation
-- conserve ensuite l’espace de travail SSH distant comme canonique
-- route `exec`, les outils de fichiers et les chemins médias via SSH
+- conserve ensuite l’espace de travail SSH distant comme référence canonique
+- achemine `exec`, les outils de fichier et les chemins média via SSH
- ne synchronise pas automatiquement les modifications distantes vers l’hôte
-- ne prend pas en charge les conteneurs de navigateur sandboxés
+- ne prend pas en charge les conteneurs de navigateur sandbox
**Accès à l’espace de travail :**
- `none` : espace de travail sandbox par portée sous `~/.openclaw/sandboxes`
-- `ro` : espace de travail sandbox à `/workspace`, espace de travail d’agent monté en lecture seule à `/agent`
-- `rw` : espace de travail d’agent monté en lecture/écriture à `/workspace`
+- `ro` : espace de travail sandbox dans `/workspace`, espace de travail agent monté en lecture seule dans `/agent`
+- `rw` : espace de travail agent monté en lecture/écriture dans `/workspace`
**Portée :**
@@ -1510,30 +1510,30 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques a
**Mode OpenShell :**
-- `mirror` : initialise le distant depuis le local avant exec, resynchronise vers le local après exec ; l’espace de travail local reste canonique
-- `remote` : initialise le distant une fois lors de la création du sandbox, puis conserve l’espace de travail distant comme canonique
+- `mirror` : initialise le distant à partir du local avant `exec`, resynchronise après `exec` ; l’espace de travail local reste canonique
+- `remote` : initialise le distant une fois à la création du sandbox, puis conserve l’espace de travail distant comme canonique
-En mode `remote`, les modifications locales sur l’hôte effectuées en dehors d’OpenClaw ne sont pas synchronisées automatiquement dans le sandbox après l’étape d’initialisation.
-Le transport utilise SSH vers le sandbox OpenShell, mais le plugin possède le cycle de vie du sandbox et la synchronisation miroir facultative.
+En mode `remote`, les modifications locales sur l’hôte effectuées en dehors d’OpenClaw ne sont pas automatiquement synchronisées dans le sandbox après l’étape d’initialisation.
+Le transport se fait via SSH vers le sandbox OpenShell, mais le plugin gère le cycle de vie du sandbox et la synchronisation miroir facultative.
-**`setupCommand`** s’exécute une fois après la création du conteneur (via `sh -lc`). Nécessite une sortie réseau, une racine inscriptible, un utilisateur root.
+**`setupCommand`** s’exécute une fois après la création du conteneur (via `sh -lc`). Nécessite une sortie réseau, une racine inscriptible et un utilisateur root.
**Les conteneurs utilisent par défaut `network: "none"`** — définissez `"bridge"` (ou un réseau bridge personnalisé) si l’agent a besoin d’un accès sortant.
`"host"` est bloqué. `"container:"` est bloqué par défaut sauf si vous définissez explicitement
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (mode de secours).
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (mode de dernier recours).
**Les pièces jointes entrantes** sont placées dans `media/inbound/*` dans l’espace de travail actif.
-**`docker.binds`** monte des répertoires hôtes supplémentaires ; les montages globaux et par agent sont fusionnés.
+**`docker.binds`** monte des répertoires hôte supplémentaires ; les montages globaux et par agent sont fusionnés.
**Navigateur sandboxé** (`sandbox.browser.enabled`) : Chromium + CDP dans un conteneur. L’URL noVNC est injectée dans le prompt système. Ne nécessite pas `browser.enabled` dans `openclaw.json`.
-L’accès observateur noVNC utilise l’authentification VNC par défaut et OpenClaw émet une URL à jeton de courte durée (au lieu d’exposer le mot de passe dans l’URL partagée).
+L’accès observateur noVNC utilise par défaut l’authentification VNC et OpenClaw émet une URL à jeton de courte durée (au lieu d’exposer le mot de passe dans l’URL partagée).
- `allowHostControl: false` (par défaut) empêche les sessions sandboxées de cibler le navigateur hôte.
- `network` vaut par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez `bridge` uniquement lorsque vous voulez explicitement une connectivité bridge globale.
-- `cdpSourceRange` peut éventuellement limiter l’entrée CDP au bord du conteneur à une plage CIDR (par exemple `172.21.0.1/32`).
-- `sandbox.browser.binds` monte des répertoires hôtes supplémentaires uniquement dans le conteneur de navigateur sandboxé. Lorsqu’il est défini (y compris `[]`), il remplace `docker.binds` pour le conteneur navigateur.
-- Les valeurs par défaut de lancement sont définies dans `scripts/sandbox-browser-entrypoint.sh` et réglées pour les hôtes de conteneur :
+- `cdpSourceRange` limite facultativement l’entrée CDP à la périphérie du conteneur à une plage CIDR (par exemple `172.21.0.1/32`).
+- `sandbox.browser.binds` monte des répertoires hôte supplémentaires uniquement dans le conteneur du navigateur sandbox. Lorsqu’il est défini (y compris `[]`), il remplace `docker.binds` pour le conteneur du navigateur.
+- Les valeurs de lancement par défaut sont définies dans `scripts/sandbox-browser-entrypoint.sh` et ajustées pour les hôtes conteneurisés :
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=`
- `--user-data-dir=${HOME}/.chrome`
@@ -1559,18 +1559,18 @@ L’accès observateur noVNC utilise l’authentification VNC par défaut et Ope
- `--renderer-process-limit=2` peut être modifié avec
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` ; définissez `0` pour utiliser la
limite de processus par défaut de Chromium.
- - plus `--no-sandbox` et `--disable-setuid-sandbox` lorsque `noSandbox` est activé.
- - Les valeurs par défaut sont la base de l’image du conteneur ; utilisez une image navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur.
+ - ainsi que `--no-sandbox` et `--disable-setuid-sandbox` lorsque `noSandbox` est activé.
+ - Les valeurs par défaut sont la base de l’image conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur.
-Le sandboxing du navigateur et `sandbox.docker.binds` sont réservés à Docker.
+Le sandboxing du navigateur et `sandbox.docker.binds` sont propres à Docker.
Construire les images :
```bash
-scripts/sandbox-setup.sh # main sandbox image
-scripts/sandbox-browser-setup.sh # optional browser image
+scripts/sandbox-setup.sh # image principale du sandbox
+scripts/sandbox-browser-setup.sh # image navigateur facultative
```
### `agents.list` (remplacements par agent)
@@ -1621,26 +1621,26 @@ scripts/sandbox-browser-setup.sh # optional browser image
}
```
-- `id` : identifiant d’agent stable (obligatoire).
-- `default` : lorsque plusieurs sont définis, le premier gagne (avertissement journalisé). Si aucun n’est défini, la première entrée de liste est la valeur par défaut.
-- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les replis globaux). Les tâches cron qui ne remplacent que `primary` héritent toujours des replis par défaut à moins que vous ne définissiez `fallbacks: []`.
+- `id` : ID d’agent stable (obligatoire).
+- `default` : lorsque plusieurs sont définis, le premier l’emporte (un avertissement est journalisé). Si aucun n’est défini, la première entrée de la liste est l’agent par défaut.
+- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les replis globaux). Les tâches cron qui ne remplacent que `primary` héritent toujours des replis par défaut, sauf si vous définissez `fallbacks: []`.
- `params` : paramètres de flux par agent fusionnés au-dessus de l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez-les pour des remplacements spécifiques à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles.
-- `skills` : liste d’autorisations Skills facultative par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsqu’il est défini ; une liste explicite remplace les valeurs par défaut au lieu de fusionner, et `[]` signifie aucun Skills.
-- `thinkingDefault` : niveau de thinking par défaut facultatif par agent (`off | minimal | low | medium | high | xhigh | adaptive`). Remplace `agents.defaults.thinkingDefault` pour cet agent lorsqu’aucun remplacement par message ou session n’est défini.
-- `reasoningDefault` : visibilité du raisonnement par défaut facultative par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement du raisonnement n’est défini par message ou session.
-- `fastModeDefault` : valeur par défaut facultative par agent pour le mode rapide (`true | false`). S’applique lorsqu’aucun remplacement du mode rapide n’est défini par message ou session.
-- `runtime` : descripteur de runtime facultatif par agent. Utilisez `type: "acp"` avec les valeurs par défaut `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions de harnais ACP.
+- `skills` : liste d’autorisations facultative des Skills par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsqu’elle est définie ; une liste explicite remplace les valeurs par défaut au lieu d’être fusionnée, et `[]` signifie aucun Skills.
+- `thinkingDefault` : niveau de réflexion facultatif par défaut par agent (`off | minimal | low | medium | high | xhigh | adaptive`). Remplace `agents.defaults.thinkingDefault` pour cet agent lorsqu’aucun remplacement par message ou par session n’est défini.
+- `reasoningDefault` : visibilité facultative du raisonnement par défaut par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement de raisonnement par message ou par session n’est défini.
+- `fastModeDefault` : valeur par défaut facultative par agent pour le mode rapide (`true | false`). S’applique lorsqu’aucun remplacement de mode rapide par message ou par session n’est défini.
+- `runtime` : descripteur d’exécution facultatif par agent. Utilisez `type: "acp"` avec les valeurs par défaut de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions de harnais ACP.
- `identity.avatar` : chemin relatif à l’espace de travail, URL `http(s)` ou URI `data:`.
-- `identity` déduit des valeurs par défaut : `ackReaction` depuis `emoji`, `mentionPatterns` depuis `name`/`emoji`.
-- `subagents.allowAgents` : liste d’autorisations des identifiants d’agent pour `sessions_spawn` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement).
-- Garde d’héritage sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans sandbox.
-- `subagents.requireAgentId` : lorsque true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection de profil explicite ; par défaut : false).
+- `identity` dérive des valeurs par défaut : `ackReaction` à partir de `emoji`, `mentionPatterns` à partir de `name`/`emoji`.
+- `subagents.allowAgents` : liste d’autorisations des ID d’agent pour `sessions_spawn` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement).
+- Garde-fou d’héritage du sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans sandbox.
+- `subagents.requireAgentId` : lorsqu’il vaut true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection de profil explicite ; par défaut : false).
---
## Routage multi-agent
-Exécutez plusieurs agents isolés à l’intérieur d’une seule Gateway. Voir [Multi-Agent](/fr/concepts/multi-agent).
+Exécutez plusieurs agents isolés dans une seule Gateway. Consultez [Multi-Agent](/fr/concepts/multi-agent).
```json5
{
@@ -1657,14 +1657,14 @@ Exécutez plusieurs agents isolés à l’intérieur d’une seule Gateway. Voir
}
```
-### Champs de correspondance de liaison
+### Champs de correspondance des liaisons
-- `type` (facultatif) : `route` pour le routage normal (l’absence de type vaut route), `acp` pour les liaisons de conversation ACP persistantes.
+- `type` (facultatif) : `route` pour le routage normal (type absent = route par défaut), `acp` pour les liaisons persistantes de conversation ACP.
- `match.channel` (obligatoire)
- `match.accountId` (facultatif ; `*` = n’importe quel compte ; omis = compte par défaut)
- `match.peer` (facultatif ; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (facultatif ; spécifique au canal)
-- `acp` (facultatif ; seulement pour les entrées `type: "acp"`) : `{ mode, label, cwd, backend }`
+- `acp` (facultatif ; uniquement pour les entrées `type: "acp"`) : `{ mode, label, cwd, backend }`
**Ordre de correspondance déterministe :**
@@ -1675,9 +1675,9 @@ Exécutez plusieurs agents isolés à l’intérieur d’une seule Gateway. Voir
5. `match.accountId: "*"` (à l’échelle du canal)
6. Agent par défaut
-Au sein de chaque niveau, la première entrée `bindings` correspondante l’emporte.
+Dans chaque niveau, la première entrée `bindings` correspondante l’emporte.
-Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre des niveaux de liaison de route ci-dessus.
+Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre de niveau de liaison de routage ci-dessus.
### Profils d’accès par agent
@@ -1699,7 +1699,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conver
-
+
```json5
{
@@ -1774,7 +1774,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conver
-Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour les détails de priorité.
+Consultez [Sandbox multi-agent et outils](/fr/tools/multi-agent-sandbox-tools) pour les détails de priorité.
---
@@ -1828,33 +1828,33 @@ Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour l
- **`scope`** : stratégie de regroupement de session de base pour les contextes de discussion de groupe.
- - `per-sender` (par défaut) : chaque expéditeur reçoit une session isolée dans un contexte de canal.
- - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsque le contexte partagé est souhaité).
+ - `per-sender` (par défaut) : chaque expéditeur obtient une session isolée dans un contexte de canal.
+ - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsqu’un contexte partagé est souhaité).
- **`dmScope`** : manière dont les DM sont regroupés.
- `main` : tous les DM partagent la session principale.
- - `per-peer` : isole par identifiant d’expéditeur sur les canaux.
- - `per-channel-peer` : isole par canal + expéditeur (recommandé pour les boîtes de réception multi-utilisateurs).
- - `per-account-channel-peer` : isole par compte + canal + expéditeur (recommandé pour le multi-compte).
-- **`identityLinks`** : mappe les identifiants canoniques vers des pairs préfixés par fournisseur pour le partage de session inter-canaux.
-- **`reset`** : politique principale de réinitialisation. `daily` réinitialise à `atHour` heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, la première expiration l’emporte.
-- **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien alias `dm` est accepté pour `direct`.
-- **`parentForkMaxTokens`** : nombre maximal de `totalTokens` de session parente autorisé lors de la création d’une session de fil forkée (par défaut `100000`).
- - Si `totalTokens` du parent est supérieur à cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription de la session parente.
- - Définissez `0` pour désactiver cette garde et toujours autoriser le fork parent.
-- **`mainKey`** : champ hérité. Le runtime utilise toujours `"main"` pour le compartiment principal de chat direct.
-- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse entre agents lors d’échanges inter-agents (entier, plage : `0`–`5`). `0` désactive l’enchaînement ping-pong.
+ - `per-peer` : isolation par ID d’expéditeur entre les canaux.
+ - `per-channel-peer` : isolation par canal + expéditeur (recommandé pour les boîtes de réception multi-utilisateurs).
+ - `per-account-channel-peer` : isolation par compte + canal + expéditeur (recommandé pour le multi-compte).
+- **`identityLinks`** : mappe les ID canoniques aux pairs préfixés par fournisseur pour le partage de session inter-canaux.
+- **`reset`** : politique de réinitialisation principale. `daily` réinitialise à `atHour` en heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte.
+- **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien `dm` est accepté comme alias de `direct`.
+- **`parentForkMaxTokens`** : nombre maximal de `totalTokens` de la session parente autorisé lors de la création d’une session de fil dérivée (par défaut `100000`).
+ - Si le `totalTokens` parent est supérieur à cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription parent.
+ - Définissez `0` pour désactiver cette protection et toujours autoriser la dérivation depuis le parent.
+- **`mainKey`** : champ hérité. L’exécution utilise toujours `"main"` pour le compartiment principal de discussion directe.
+- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse en retour entre agents lors des échanges agent-à-agent (entier, plage : `0`–`5`). `0` désactive l’enchaînement ping-pong.
- **`sendPolicy`** : correspondance par `channel`, `chatType` (`direct|group|channel`, avec l’ancien alias `dm`), `keyPrefix` ou `rawKeyPrefix`. Le premier refus l’emporte.
- **`maintenance`** : contrôles de nettoyage + rétention du magasin de sessions.
- `mode` : `warn` émet uniquement des avertissements ; `enforce` applique le nettoyage.
- `pruneAfter` : seuil d’ancienneté pour les entrées obsolètes (par défaut `30d`).
- `maxEntries` : nombre maximal d’entrées dans `sessions.json` (par défaut `500`).
- - `rotateBytes` : faire tourner `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`).
- - `resetArchiveRetention` : durée de rétention des archives de transcription `*.reset.`. Par défaut, reprend `pruneAfter` ; définissez `false` pour désactiver.
- - `maxDiskBytes` : budget disque facultatif pour le répertoire des sessions. En mode `warn`, il journalise des avertissements ; en mode `enforce`, il supprime d’abord les artefacts/sessions les plus anciens.
- - `highWaterBytes` : cible facultative après nettoyage du budget. Par défaut `80%` de `maxDiskBytes`.
-- **`threadBindings`** : valeurs par défaut globales pour les fonctionnalités de session liées aux fils.
+ - `rotateBytes` : fait tourner `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`).
+ - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Utilise par défaut `pruneAfter` ; définissez `false` pour désactiver.
+ - `maxDiskBytes` : budget disque facultatif du répertoire des sessions. En mode `warn`, il journalise des avertissements ; en mode `enforce`, il supprime d’abord les artefacts/sessions les plus anciens.
+ - `highWaterBytes` : cible facultative après nettoyage du budget. Utilise par défaut `80%` de `maxDiskBytes`.
+- **`threadBindings`** : valeurs globales par défaut pour les fonctionnalités de session liées aux fils.
- `enabled` : commutateur maître par défaut (les fournisseurs peuvent remplacer ; Discord utilise `channels.discord.threadBindings.enabled`)
- - `idleHours` : retrait automatique par défaut du focus après inactivité, en heures (`0` désactive ; les fournisseurs peuvent remplacer)
+ - `idleHours` : retrait automatique du focus par défaut après inactivité, en heures (`0` désactive ; les fournisseurs peuvent remplacer)
- `maxAgeHours` : âge maximal strict par défaut, en heures (`0` désactive ; les fournisseurs peuvent remplacer)
@@ -1895,34 +1895,34 @@ Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour l
Remplacements par canal/compte : `channels..responsePrefix`, `channels..accounts..responsePrefix`.
-Résolution (le plus spécifique gagne) : compte → canal → global. `""` désactive et arrête la cascade. `"auto"` dérive `[{identity.name}]`.
+Résolution (le plus spécifique l’emporte) : compte → canal → global. `""` désactive et arrête la cascade. `"auto"` dérive `[{identity.name}]`.
**Variables de modèle :**
-| Variable | Description | Exemple |
-| ----------------- | ---------------------- | --------------------------- |
-| `{model}` | Nom court du modèle | `claude-opus-4-6` |
+| Variable | Description | Exemple |
+| ----------------- | -------------------------- | --------------------------- |
+| `{model}` | Nom court du modèle | `claude-opus-4-6` |
| `{modelFull}` | Identifiant complet du modèle | `anthropic/claude-opus-4-6` |
-| `{provider}` | Nom du fournisseur | `anthropic` |
-| `{thinkingLevel}` | Niveau de thinking actuel | `high`, `low`, `off` |
-| `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) |
+| `{provider}` | Nom du provider | `anthropic` |
+| `{thinkingLevel}` | Niveau de réflexion actuel | `high`, `low`, `off` |
+| `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) |
-Les variables sont insensibles à la casse. `{think}` est un alias pour `{thinkingLevel}`.
+Les variables ne sont pas sensibles à la casse. `{think}` est un alias de `{thinkingLevel}`.
### Réaction d’accusé de réception
-- Par défaut : `identity.emoji` de l’agent actif, sinon `"👀"`. Définissez `""` pour désactiver.
+- Utilise par défaut `identity.emoji` de l’agent actif, sinon `"👀"`. Définissez `""` pour désactiver.
- Remplacements par canal : `channels..ackReaction`, `channels..accounts..ackReaction`.
-- Ordre de résolution : compte → canal → `messages.ackReaction` → repli d’identité.
+- Ordre de résolution : compte → canal → `messages.ackReaction` → repli identité.
- Portée : `group-mentions` (par défaut), `group-all`, `direct`, `all`.
-- `removeAckAfterReply` supprime l’accusé après la réponse sur Slack, Discord et Telegram.
-- `messages.statusReactions.enabled` active les réactions d’état du cycle de vie sur Slack, Discord et Telegram.
- Sur Slack et Discord, non défini conserve les réactions d’état activées lorsque les réactions d’accusé sont actives.
- Sur Telegram, définissez-le explicitement à `true` pour activer les réactions d’état du cycle de vie.
+- `removeAckAfterReply` : supprime l’accusé de réception après réponse sur Slack, Discord et Telegram.
+- `messages.statusReactions.enabled` : active les réactions d’état du cycle de vie sur Slack, Discord et Telegram.
+ Sur Slack et Discord, l’absence de valeur conserve les réactions d’état activées lorsque les réactions d’accusé de réception sont actives.
+ Sur Telegram, définissez explicitement cette valeur à `true` pour activer les réactions d’état du cycle de vie.
-### Anti-rebond entrant
+### Anti-rebond des messages entrants
-Regroupe les messages texte rapides du même expéditeur en un seul tour d’agent. Les médias/pièces jointes sont vidés immédiatement. Les commandes de contrôle contournent l’anti-rebond.
+Regroupe les messages texte rapides du même expéditeur en un seul tour d’agent. Les médias/pièces jointes déclenchent un envoi immédiat. Les commandes de contrôle contournent l’anti-rebond.
### TTS (synthèse vocale)
@@ -1967,9 +1967,9 @@ Regroupe les messages texte rapides du même expéditeur en un seul tour d’age
- `auto` contrôle le mode auto-TTS par défaut : `off`, `always`, `inbound` ou `tagged`. `/tts on|off` peut remplacer les préférences locales, et `/tts status` affiche l’état effectif.
- `summaryModel` remplace `agents.defaults.model.primary` pour le résumé automatique.
-- `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut `false` par défaut (activation explicite).
-- Les clés API se replient sur `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY`.
-- `openai.baseUrl` remplace le point de terminaison OpenAI TTS. L’ordre de résolution est : configuration, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`.
+- `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut par défaut `false` (activation explicite).
+- Les clés API utilisent comme solution de repli `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY`.
+- `openai.baseUrl` remplace le point de terminaison TTS OpenAI. L’ordre de résolution est : configuration, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`.
- Lorsque `openai.baseUrl` pointe vers un point de terminaison non OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix.
---
@@ -2000,13 +2000,13 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android).
}
```
-- `talk.provider` doit correspondre à une clé dans `talk.providers` lorsque plusieurs fournisseurs Talk sont configurés.
-- Les anciennes clés Talk plates (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sont uniquement conservées pour compatibilité et sont automatiquement migrées vers `talk.providers.`.
-- Les identifiants de voix se replient sur `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`.
-- `providers.*.apiKey` accepte des chaînes en clair ou des objets SecretRef.
-- Le repli `ELEVENLABS_API_KEY` ne s’applique que lorsqu’aucune clé API Talk n’est configurée.
+- `talk.provider` doit correspondre à une clé dans `talk.providers` lorsque plusieurs providers Talk sont configurés.
+- Les anciennes clés Talk plates (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) ne sont conservées que pour compatibilité et sont automatiquement migrées vers `talk.providers.`.
+- Les ID de voix utilisent comme solution de repli `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`.
+- `providers.*.apiKey` accepte des chaînes en texte brut ou des objets SecretRef.
+- La solution de repli `ELEVENLABS_API_KEY` s’applique uniquement lorsqu’aucune clé API Talk n’est configurée.
- `providers.*.voiceAliases` permet aux directives Talk d’utiliser des noms conviviaux.
-- `silenceTimeoutMs` contrôle le temps d’attente du mode Talk après le silence de l’utilisateur avant d’envoyer la transcription. Non défini, conserve la fenêtre de pause par défaut de la plateforme (`700 ms sur macOS et Android, 900 ms sur iOS`).
+- `silenceTimeoutMs` contrôle combien de temps le mode Talk attend après le silence de l’utilisateur avant d’envoyer la transcription. Si non défini, la fenêtre de pause par défaut de la plateforme est conservée (`700 ms sur macOS et Android, 900 ms sur iOS`).
---
@@ -2018,18 +2018,18 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android).
L’intégration locale définit par défaut les nouvelles configurations locales sur `tools.profile: "coding"` lorsqu’il n’est pas défini (les profils explicites existants sont conservés).
-| Profil | Inclut |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `minimal` | `session_status` uniquement |
+| Profil | Inclut |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal` | `session_status` uniquement |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
-| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
-| `full` | Aucune restriction (identique à non défini) |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
+| `full` | Aucune restriction (identique à non défini) |
### Groupes d’outils
-| Groupe | Outils |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` est accepté comme alias pour `exec`) |
+| Groupe | Outils |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `group:runtime` | `exec`, `process`, `code_execution` (`bash` est accepté comme alias de `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
@@ -2040,11 +2040,11 @@ L’intégration locale définit par défaut les nouvelles configurations locale
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
-| `group:openclaw` | Tous les outils intégrés (hors plugins fournisseur) |
+| `group:openclaw` | Tous les outils intégrés (exclut les plugins provider) |
### `tools.allow` / `tools.deny`
-Politique globale d’autorisation/refus des outils (le refus l’emporte). Insensible à la casse, prend en charge les jokers `*`. S’applique même lorsque le sandbox Docker est désactivé.
+Politique globale d’autorisation/interdiction des outils (l’interdiction l’emporte). Insensible à la casse, prend en charge les jokers `*`. S’applique même lorsque le sandbox Docker est désactivé.
```json5
{
@@ -2054,7 +2054,7 @@ Politique globale d’autorisation/refus des outils (le refus l’emporte). Inse
### `tools.byProvider`
-Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. Ordre : profil de base → profil fournisseur → autoriser/refuser.
+Restreint davantage les outils pour des providers ou modèles spécifiques. Ordre : profil de base → profil du provider → autorisation/interdiction.
```json5
{
@@ -2070,7 +2070,7 @@ Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. O
### `tools.elevated`
-Contrôle l’accès exec elevated en dehors du sandbox :
+Contrôle l’accès `exec` élevé en dehors du sandbox :
```json5
{
@@ -2087,8 +2087,8 @@ Contrôle l’accès exec elevated en dehors du sandbox :
```
- Le remplacement par agent (`agents.list[].tools.elevated`) ne peut que restreindre davantage.
-- `/elevated on|off|ask|full` stocke l’état par session ; les directives inline s’appliquent à un seul message.
-- L’`exec` elevated contourne le sandbox et utilise le chemin d’échappement configuré (`gateway` par défaut, ou `node` lorsque la cible exec est `node`).
+- `/elevated on|off|ask|full` stocke l’état par session ; les directives en ligne s’appliquent à un seul message.
+- `exec` élevé contourne le sandboxing et utilise le chemin d’échappement configuré (`gateway` par défaut, ou `node` lorsque la cible `exec` est `node`).
### `tools.exec`
@@ -2112,7 +2112,7 @@ Contrôle l’accès exec elevated en dehors du sandbox :
### `tools.loopDetection`
-Les vérifications de sécurité contre les boucles d’outils sont **désactivées par défaut**. Définissez `enabled: true` pour activer la détection.
+Les vérifications de sécurité des boucles d’outils sont **désactivées par défaut**. Définissez `enabled: true` pour activer la détection.
Les paramètres peuvent être définis globalement dans `tools.loopDetection` et remplacés par agent dans `agents.list[].tools.loopDetection`.
```json5
@@ -2134,13 +2134,13 @@ Les paramètres peuvent être définis globalement dans `tools.loopDetection` et
}
```
-- `historySize` : historique maximal d’appels d’outils conservé pour l’analyse des boucles.
-- `warningThreshold` : seuil des motifs répétés sans progrès pour les avertissements.
-- `criticalThreshold` : seuil plus élevé de répétition pour bloquer les boucles critiques.
-- `globalCircuitBreakerThreshold` : seuil d’arrêt dur pour toute exécution sans progrès.
-- `detectors.genericRepeat` : avertit lors d’appels répétés même outil/mêmes arguments.
-- `detectors.knownPollNoProgress` : avertit/bloque les outils de sondage connus (`process.poll`, `command_status`, etc.).
-- `detectors.pingPong` : avertit/bloque les motifs alternés par paire sans progrès.
+- `historySize` : historique maximal des appels d’outils conservé pour l’analyse des boucles.
+- `warningThreshold` : seuil de modèle répétitif sans progression pour les avertissements.
+- `criticalThreshold` : seuil répétitif plus élevé pour bloquer les boucles critiques.
+- `globalCircuitBreakerThreshold` : seuil d’arrêt dur pour toute exécution sans progression.
+- `detectors.genericRepeat` : avertit en cas d’appels répétés au même outil/avec les mêmes arguments.
+- `detectors.knownPollNoProgress` : avertit/bloque sur les outils de sondage connus (`process.poll`, `command_status`, etc.).
+- `detectors.pingPong` : avertit/bloque sur les modèles alternés sans progression en paire.
- Si `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, la validation échoue.
### `tools.web`
@@ -2207,32 +2207,32 @@ Configure la compréhension des médias entrants (image/audio/vidéo) :
}
```
-
+
-**Entrée fournisseur** (`type: "provider"` ou omis) :
+**Entrée provider** (`type: "provider"` ou omis) :
-- `provider` : identifiant de fournisseur API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
-- `model` : remplacement d’identifiant de modèle
+- `provider` : ID du provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
+- `model` : remplacement d’ID de modèle
- `profile` / `preferredProfile` : sélection de profil `auth-profiles.json`
**Entrée CLI** (`type: "cli"`) :
- `command` : exécutable à lancer
-- `args` : arguments avec modèles (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.)
+- `args` : arguments à modèles (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.)
**Champs communs :**
- `capabilities` : liste facultative (`image`, `audio`, `video`). Valeurs par défaut : `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language` : remplacements par entrée.
-- Les échecs se replient sur l’entrée suivante.
+- Les échecs passent à l’entrée suivante.
-L’authentification fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`.
+L’authentification du provider suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`.
-**Champs de complétion asynchrone :**
+**Champs d’exécution asynchrone :**
-- `asyncCompletion.directSend` : lorsque `true`, les tâches `music_generate`
- et `video_generate` asynchrones terminées essaient d’abord une livraison directe au canal. Valeur par défaut : `false`
- (ancien chemin de réveil de session demandeur / livraison par modèle).
+- `asyncCompletion.directSend` : lorsque `true`, les tâches terminées asynchrones `music_generate`
+ et `video_generate` essaient d’abord une livraison directe au canal. Par défaut : `false`
+ (ancien chemin de réveil de session du demandeur/livraison par modèle).
@@ -2253,7 +2253,7 @@ L’authentification fournisseur suit l’ordre standard : `auth-profiles.json`
Contrôle quelles sessions peuvent être ciblées par les outils de session (`sessions_list`, `sessions_history`, `sessions_send`).
-Valeur par défaut : `tree` (session actuelle + sessions générées par elle, comme les subagents).
+Par défaut : `tree` (session actuelle + sessions lancées par celle-ci, comme les sous-agents).
```json5
{
@@ -2269,14 +2269,14 @@ Valeur par défaut : `tree` (session actuelle + sessions générées par elle, c
Remarques :
- `self` : uniquement la clé de session actuelle.
-- `tree` : session actuelle + sessions générées par la session actuelle (subagents).
-- `agent` : toute session appartenant à l’identifiant d’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même identifiant d’agent).
+- `tree` : session actuelle + sessions lancées par la session actuelle (sous-agents).
+- `agent` : toute session appartenant à l’ID d’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même ID d’agent).
- `all` : toute session. Le ciblage inter-agents nécessite toujours `tools.agentToAgent`.
- Limitation sandbox : lorsque la session actuelle est sandboxée et que `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilité est forcée à `tree` même si `tools.sessions.visibility="all"`.
### `tools.sessions_spawn`
-Contrôle la prise en charge des pièces jointes inline pour `sessions_spawn`.
+Contrôle la prise en charge des pièces jointes en ligne pour `sessions_spawn`.
```json5
{
@@ -2296,16 +2296,16 @@ Contrôle la prise en charge des pièces jointes inline pour `sessions_spawn`.
Remarques :
-- Les pièces jointes ne sont prises en charge que pour `runtime: "subagent"`. Le runtime ACP les rejette.
+- Les pièces jointes ne sont prises en charge que pour `runtime: "subagent"`. L’exécution ACP les rejette.
- Les fichiers sont matérialisés dans l’espace de travail enfant sous `.openclaw/attachments//` avec un `.manifest.json`.
-- Le contenu des pièces jointes est automatiquement expurgé de la persistance du transcript.
-- Les entrées base64 sont validées avec des vérifications strictes d’alphabet/remplissage et une garde de taille avant décodage.
+- Le contenu des pièces jointes est automatiquement masqué dans la persistance de la transcription.
+- Les entrées base64 sont validées avec des vérifications strictes d’alphabet/remplissage et une protection de taille avant décodage.
- Les permissions de fichier sont `0700` pour les répertoires et `0600` pour les fichiers.
- Le nettoyage suit la politique `cleanup` : `delete` supprime toujours les pièces jointes ; `keep` ne les conserve que lorsque `retainOnSessionKeep: true`.
### `tools.experimental`
-Drapeaux d’outils intégrés expérimentaux. Désactivés par défaut sauf lorsqu’une règle d’auto-activation spécifique au runtime s’applique.
+Indicateurs d’outils intégrés expérimentaux. Désactivés par défaut sauf si une règle d’activation automatique spécifique à l’exécution s’applique.
```json5
{
@@ -2319,9 +2319,9 @@ Drapeaux d’outils intégrés expérimentaux. Désactivés par défaut sauf lor
Remarques :
-- `planTool` : active l’outil structuré expérimental `update_plan` pour le suivi des tâches non triviales en plusieurs étapes.
-- Valeur par défaut : `false` pour les fournisseurs non OpenAI. Les exécutions OpenAI et OpenAI Codex l’activent automatiquement lorsqu’il n’est pas défini ; définissez `false` pour désactiver cette activation automatique.
-- Lorsqu’il est activé, le prompt système ajoute aussi des conseils d’usage afin que le modèle ne l’utilise que pour un travail substantiel et conserve au plus une étape `in_progress`.
+- `planTool` : active l’outil structuré `update_plan` pour le suivi des travaux non triviaux à plusieurs étapes.
+- Par défaut : `false` pour les providers non OpenAI. Les exécutions OpenAI et OpenAI Codex l’activent automatiquement lorsqu’il n’est pas défini ; définissez `false` pour désactiver cette activation automatique.
+- Lorsqu’il est activé, le prompt système ajoute aussi des consignes d’utilisation afin que le modèle ne l’utilise que pour des travaux substantiels et conserve au plus une étape `in_progress`.
### `agents.defaults.subagents`
@@ -2342,15 +2342,15 @@ Remarques :
```
- `model` : modèle par défaut pour les sous-agents lancés. S’il est omis, les sous-agents héritent du modèle de l’appelant.
-- `allowAgents` : liste d’autorisations par défaut des identifiants d’agent cibles pour `sessions_spawn` lorsque l’agent demandeur ne définit pas son propre `subagents.allowAgents` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement).
-- `runTimeoutSeconds` : délai maximal par défaut (secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai.
+- `allowAgents` : liste d’autorisations par défaut des ID d’agent cibles pour `sessions_spawn` lorsque l’agent demandeur ne définit pas son propre `subagents.allowAgents` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement).
+- `runTimeoutSeconds` : délai d’expiration par défaut (secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai.
- Politique d’outils par sous-agent : `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
-## Fournisseurs personnalisés et base URLs
+## Providers personnalisés et URL de base
-OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs personnalisés via `models.providers` dans la configuration ou `~/.openclaw/agents//agent/models.json`.
+OpenClaw utilise le catalogue de modèles intégré. Ajoutez des providers personnalisés via `models.providers` dans la configuration ou `~/.openclaw/agents//agent/models.json`.
```json5
{
@@ -2379,49 +2379,50 @@ OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs pe
}
```
-- Utilisez `authHeader: true` + `headers` pour les besoins d’authentification personnalisés.
-- Remplacez la racine de configuration d’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, ancien alias de variable d’environnement).
-- Priorité de fusion pour les identifiants de fournisseur correspondants :
- - Les valeurs `baseUrl` d’agent `models.json` non vides ont priorité.
- - Les valeurs `apiKey` d’agent non vides n’ont priorité que lorsque ce fournisseur n’est pas géré par SecretRef dans le contexte actuel de configuration/profil d’authentification.
- - Les valeurs `apiKey` de fournisseur gérées par SecretRef sont rafraîchies à partir des marqueurs de source (`ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec) au lieu de persister les secrets résolus.
- - Les valeurs d’en-tête de fournisseur gérées par SecretRef sont rafraîchies à partir des marqueurs de source (`secretref-env:ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec).
- - Les `apiKey`/`baseUrl` d’agent vides ou absents se replient sur `models.providers` dans la configuration.
- - Les `contextWindow`/`maxTokens` de modèle correspondants utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue.
- - Les `contextTokens` de modèle correspondants préservent une limite d’exécution explicite lorsqu’elle est présente ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle.
- - Utilisez `models.mode: "replace"` lorsque vous voulez que la configuration réécrive complètement `models.json`.
- - La persistance des marqueurs est autoritaire sur la source : les marqueurs sont écrits depuis l’instantané de configuration source actif (avant résolution), et non depuis les valeurs de secret résolues à l’exécution.
+- Utilisez `authHeader: true` + `headers` pour des besoins d’authentification personnalisés.
+- Remplacez la racine de configuration de l’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, alias hérité de variable d’environnement).
+- Priorité de fusion pour les ID de provider correspondants :
+ - Les valeurs `baseUrl` non vides de `models.json` de l’agent l’emportent.
+ - Les valeurs `apiKey` non vides de l’agent l’emportent uniquement lorsque ce provider n’est pas géré par SecretRef dans le contexte actuel de configuration/profil d’authentification.
+ - Les valeurs `apiKey` de provider gérées par SecretRef sont actualisées à partir des marqueurs source (`ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec) au lieu de persister les secrets résolus.
+ - Les valeurs d’en-tête de provider gérées par SecretRef sont actualisées à partir des marqueurs source (`secretref-env:ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec).
+ - Les valeurs `apiKey`/`baseUrl` d’agent vides ou absentes se replient sur `models.providers` dans la configuration.
+ - Les valeurs `contextWindow`/`maxTokens` des modèles correspondants utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue.
+ - `contextTokens` des modèles correspondants conserve une limite d’exécution explicite lorsqu’elle est présente ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle.
+ - Utilisez `models.mode: "replace"` lorsque vous voulez que la configuration réécrive entièrement `models.json`.
+ - La persistance des marqueurs est gouvernée par la source : les marqueurs sont écrits à partir de l’instantané actif de la configuration source (pré-résolution), et non à partir des valeurs secrètes résolues à l’exécution.
-### Détails des champs fournisseur
+### Détails des champs de provider
-- `models.mode` : comportement du catalogue de fournisseurs (`merge` ou `replace`).
-- `models.providers` : map des fournisseurs personnalisés indexée par identifiant de fournisseur.
+- `models.mode` : comportement du catalogue de providers (`merge` ou `replace`).
+- `models.providers` : map de providers personnalisés indexée par ID de provider.
- `models.providers.*.api` : adaptateur de requête (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc.).
-- `models.providers.*.apiKey` : identifiant du fournisseur (préférez SecretRef/substitution env).
+- `models.providers.*.apiKey` : identifiant du provider (préférez SecretRef/la substitution via l’environnement).
- `models.providers.*.auth` : stratégie d’authentification (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.injectNumCtxForOpenAICompat` : pour Ollama + `openai-completions`, injecte `options.num_ctx` dans les requêtes (par défaut : `true`).
-- `models.providers.*.authHeader` : force le transport de l’identifiant dans l’en-tête `Authorization` lorsque nécessaire.
+- `models.providers.*.authHeader` : force le transport des identifiants dans l’en-tête `Authorization` lorsque nécessaire.
- `models.providers.*.baseUrl` : URL de base de l’API amont.
-- `models.providers.*.headers` : en-têtes statiques supplémentaires pour le routage proxy/tenant.
-- `models.providers.*.request` : remplacements de transport pour les requêtes HTTP des fournisseurs de modèles.
- - `request.headers` : en-têtes supplémentaires (fusionnés avec les valeurs par défaut du fournisseur). Les valeurs acceptent SecretRef.
- - `request.auth` : remplacement de stratégie d’authentification. Modes : `"provider-default"` (utiliser l’authentification intégrée du fournisseur), `"authorization-bearer"` (avec `token`), `"header"` (avec `headerName`, `value`, `prefix` facultatif).
- - `request.proxy` : remplacement de proxy HTTP. Modes : `"env-proxy"` (utiliser les variables d’environnement `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (avec `url`). Les deux modes acceptent un sous-objet `tls` facultatif.
+- `models.providers.*.headers` : en-têtes statiques supplémentaires pour le routage proxy/locataire.
+- `models.providers.*.request` : remplacements de transport pour les requêtes HTTP du provider de modèles.
+ - `request.headers` : en-têtes supplémentaires (fusionnés avec les valeurs par défaut du provider). Les valeurs acceptent SecretRef.
+ - `request.auth` : remplacement de stratégie d’authentification. Modes : `"provider-default"` (utilise l’authentification intégrée du provider), `"authorization-bearer"` (avec `token`), `"header"` (avec `headerName`, `value`, `prefix` facultatif).
+ - `request.proxy` : remplacement du proxy HTTP. Modes : `"env-proxy"` (utilise les variables d’environnement `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (avec `url`). Les deux modes acceptent un sous-objet facultatif `tls`.
- `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (acceptent tous SecretRef), `serverName`, `insecureSkipVerify`.
-- `models.providers.*.models` : entrées explicites du catalogue de modèles du fournisseur.
+ - `request.allowPrivateNetwork` : lorsque `true`, autorise HTTPS vers `baseUrl` lorsque DNS se résout vers des plages privées, CGNAT ou similaires, via la protection de récupération HTTP du provider (activation explicite par l’opérateur pour des points de terminaison compatibles OpenAI auto-hébergés de confiance). WebSocket utilise le même `request` pour les en-têtes/TLS, mais pas cette protection SSRF de récupération. Par défaut `false`.
+- `models.providers.*.models` : entrées explicites du catalogue de modèles du provider.
- `models.providers.*.models.*.contextWindow` : métadonnées de fenêtre de contexte native du modèle.
-- `models.providers.*.models.*.contextTokens` : limite de contexte d’exécution facultative. Utilisez-la lorsque vous voulez un budget de contexte effectif plus faible que la `contextWindow` native du modèle.
-- `models.providers.*.models.*.compat.supportsDeveloperRole` : indice facultatif de compatibilité. Pour `api: "openai-completions"` avec un `baseUrl` non vide non natif (hôte différent de `api.openai.com`), OpenClaw force cette valeur à `false` à l’exécution. Un `baseUrl` vide/omis conserve le comportement OpenAI par défaut.
-- `models.providers.*.models.*.compat.requiresStringContent` : indice facultatif de compatibilité pour les points de terminaison de chat compatibles OpenAI limités aux chaînes. Lorsque `true`, OpenClaw aplati les tableaux purement textuels `messages[].content` en chaînes simples avant d’envoyer la requête.
-- `plugins.entries.amazon-bedrock.config.discovery` : racine des paramètres d’auto-découverte Bedrock.
-- `plugins.entries.amazon-bedrock.config.discovery.enabled` : activer/désactiver la découverte implicite.
-- `plugins.entries.amazon-bedrock.config.discovery.region` : région AWS pour la découverte.
-- `plugins.entries.amazon-bedrock.config.discovery.providerFilter` : filtre facultatif d’identifiants de fournisseur pour une découverte ciblée.
-- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour l’actualisation de la découverte.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow` : fenêtre de contexte de repli pour les modèles découverts.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens` : nombre maximal de jetons de sortie de repli pour les modèles découverts.
+- `models.providers.*.models.*.contextTokens` : plafond de contexte d’exécution facultatif. Utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle.
+- `models.providers.*.models.*.compat.supportsDeveloperRole` : indice de compatibilité facultatif. Pour `api: "openai-completions"` avec un `baseUrl` non natif non vide (hôte différent de `api.openai.com`), OpenClaw force cette valeur à `false` à l’exécution. Un `baseUrl` vide/omis conserve le comportement OpenAI par défaut.
+- `models.providers.*.models.*.compat.requiresStringContent` : indice de compatibilité facultatif pour les points de terminaison de chat compatibles OpenAI limités aux chaînes. Lorsque `true`, OpenClaw aplatie les tableaux purement textuels `messages[].content` en chaînes simples avant d’envoyer la requête.
+- `plugins.entries.amazon-bedrock.config.discovery` : racine des paramètres d’auto-détection Bedrock.
+- `plugins.entries.amazon-bedrock.config.discovery.enabled` : active/désactive la détection implicite.
+- `plugins.entries.amazon-bedrock.config.discovery.region` : région AWS pour la détection.
+- `plugins.entries.amazon-bedrock.config.discovery.providerFilter` : filtre facultatif d’ID de provider pour une détection ciblée.
+- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour l’actualisation de la détection.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow` : fenêtre de contexte de repli pour les modèles détectés.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens` : nombre maximal de jetons de sortie de repli pour les modèles détectés.
-### Exemples de fournisseurs
+### Exemples de providers
@@ -2474,7 +2475,7 @@ Utilisez `cerebras/zai-glm-4.7` pour Cerebras ; `zai/glm-4.7` pour Z.AI direct.
}
```
-Définissez `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Utilisez des références `opencode/...` pour le catalogue Zen ou `opencode-go/...` pour le catalogue Go. Raccourci : `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`.
+Définissez `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Utilisez les références `opencode/...` pour le catalogue Zen ou les références `opencode-go/...` pour le catalogue Go. Raccourci : `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`.
@@ -2491,11 +2492,11 @@ Définissez `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Utilisez des référ
}
```
-Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont acceptés comme alias. Raccourci : `openclaw onboard --auth-choice zai-api-key`.
+Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont des alias acceptés. Raccourci : `openclaw onboard --auth-choice zai-api-key`.
- Point de terminaison général : `https://api.z.ai/api/paas/v4`
-- Point de terminaison de coding (par défaut) : `https://api.z.ai/api/coding/paas/v4`
-- Pour le point de terminaison général, définissez un fournisseur personnalisé avec remplacement de l’URL de base.
+- Point de terminaison de code (par défaut) : `https://api.z.ai/api/coding/paas/v4`
+- Pour le point de terminaison général, définissez un provider personnalisé avec le remplacement de l’URL de base.
@@ -2536,9 +2537,9 @@ Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont acceptés comme alias. Racc
Pour le point de terminaison Chine : `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`.
-Les points de terminaison Moonshot natifs annoncent une compatibilité d’usage du streaming sur le transport partagé
-`openai-completions`, et OpenClaw s’appuie sur les capacités de ce point de terminaison
-plutôt que sur le seul identifiant de fournisseur intégré.
+Les points de terminaison Moonshot natifs annoncent une compatibilité d’utilisation du streaming sur le transport partagé
+`openai-completions`, et OpenClaw s’appuie là-dessus selon les capacités du point de terminaison
+plutôt que sur le seul ID de provider intégré.
@@ -2556,7 +2557,7 @@ plutôt que sur le seul identifiant de fournisseur intégré.
}
```
-Compatible Anthropic, fournisseur intégré. Raccourci : `openclaw onboard --auth-choice kimi-code-api-key`.
+Compatible Anthropic, provider intégré. Raccourci : `openclaw onboard --auth-choice kimi-code-api-key`.
@@ -2638,9 +2639,9 @@ L’URL de base doit omettre `/v1` (le client Anthropic l’ajoute). Raccourci :
Définissez `MINIMAX_API_KEY`. Raccourcis :
`openclaw onboard --auth-choice minimax-global-api` ou
`openclaw onboard --auth-choice minimax-cn-api`.
-Le catalogue de modèles se limite par défaut à M2.7 uniquement.
-Sur le chemin de streaming compatible Anthropic, OpenClaw désactive par défaut le thinking MiniMax
-sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou
+Le catalogue de modèles utilise par défaut uniquement M2.7.
+Sur le chemin de streaming compatible Anthropic, OpenClaw désactive la réflexion MiniMax
+par défaut sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou
`params.fastMode: true` réécrit `MiniMax-M2.7` en
`MiniMax-M2.7-highspeed`.
@@ -2648,7 +2649,7 @@ sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou
-Voir [Modèles locaux](/fr/gateway/local-models). En résumé : exécutez un grand modèle local via l’API LM Studio Responses sur du matériel puissant ; conservez les modèles hébergés fusionnés pour le repli.
+Consultez [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand modèle local via l’API Responses de LM Studio sur du matériel puissant ; conservez les modèles hébergés fusionnés comme solution de repli.
@@ -2679,14 +2680,14 @@ Voir [Modèles locaux](/fr/gateway/local-models). En résumé : exécutez un gra
}
```
-- `allowBundled` : liste d’autorisations facultative pour les Skills groupés uniquement (les Skills gérés/de workspace ne sont pas affectés).
-- `load.extraDirs` : racines Skills partagées supplémentaires (priorité la plus basse).
+- `allowBundled` : liste d’autorisations facultative pour les Skills groupées uniquement (les Skills gérées/d’espace de travail ne sont pas affectées).
+- `load.extraDirs` : racines supplémentaires de Skills partagées (priorité la plus faible).
- `install.preferBrew` : lorsque true, préfère les installateurs Homebrew lorsque `brew` est
disponible avant de revenir à d’autres types d’installateur.
-- `install.nodeManager` : préférence de gestionnaire Node pour les spécifications `metadata.openclaw.install`
+- `install.nodeManager` : préférence d’installateur Node pour les spécifications `metadata.openclaw.install`
(`npm` | `pnpm` | `yarn` | `bun`).
-- `entries..enabled: false` désactive un Skills même s’il est groupé/installé.
-- `entries..apiKey` : champ pratique de clé API pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef).
+- `entries..enabled: false` désactive une skill même si elle est groupée/installée.
+- `entries..apiKey` : raccourci pratique pour les Skills qui déclarent une variable d’environnement principale (chaîne en texte brut ou objet SecretRef).
---
@@ -2714,43 +2715,43 @@ Voir [Modèles locaux](/fr/gateway/local-models). En résumé : exécutez un gra
}
```
-- Chargés depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, plus `plugins.load.paths`.
-- La découverte accepte les plugins OpenClaw natifs ainsi que les bundles Codex et Claude compatibles, y compris les bundles Claude sans manifeste au format de disposition par défaut.
-- **Les modifications de configuration nécessitent un redémarrage de la passerelle.**
-- `allow` : liste d’autorisations facultative (seuls les plugins listés se chargent). `deny` a priorité.
+- Chargés depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, ainsi que `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 avec disposition par défaut.
+- **Les changements de configuration nécessitent un redémarrage de la passerelle.**
+- `allow` : liste d’autorisations facultative (seuls les plugins listés sont chargés). `deny` l’emporte.
- `plugins.entries..apiKey` : champ pratique de clé API au niveau plugin (lorsqu’il est pris en charge par le plugin).
-- `plugins.entries..env` : map de variables d’environnement limitée au plugin.
-- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le cœur bloque `before_prompt_build` et ignore les champs modifiant le prompt des anciens `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..subagent.allowModelOverride` : faire explicitement confiance à ce plugin pour demander des remplacements `provider` et `model` par exécution pour des exécutions de sous-agents en arrière-plan.
-- `plugins.entries..subagent.allowedModels` : liste d’autorisations facultative de cibles canoniques `provider/model` pour les remplacements de sous-agent approuvés. Utilisez `"*"` uniquement si vous voulez intentionnellement autoriser n’importe quel modèle.
+- `plugins.entries..env` : map de variables d’environnement à portée plugin.
+- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le cœur bloque `before_prompt_build` et ignore les champs hérités modifiant le prompt depuis `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..subagent.allowModelOverride` : fait explicitement confiance à ce plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions de sous-agents en arrière-plan.
+- `plugins.entries..subagent.allowedModels` : liste d’autorisations facultative des cibles canoniques `provider/model` pour les remplacements de sous-agents approuvés. Utilisez `"*"` uniquement lorsque vous voulez délibérément autoriser n’importe quel modèle.
- `plugins.entries..config` : objet de configuration défini par le plugin (validé par le schéma du plugin OpenClaw natif lorsqu’il est disponible).
-- `plugins.entries.firecrawl.config.webFetch` : paramètres du fournisseur de récupération web Firecrawl.
- - `apiKey` : clé API Firecrawl (accepte SecretRef). Se replie sur `plugins.entries.firecrawl.config.webSearch.apiKey`, l’ancien `tools.web.fetch.firecrawl.apiKey`, ou la variable d’environnement `FIRECRAWL_API_KEY`.
+- `plugins.entries.firecrawl.config.webFetch` : paramètres du provider de récupération web Firecrawl.
+ - `apiKey` : clé API Firecrawl (accepte SecretRef). Utilise comme solution de repli `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`).
- - `onlyMainContent` : extraire uniquement le contenu principal des pages (par défaut : `true`).
+ - `onlyMainContent` : extrait 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 maximal de requête scrape en secondes (par défaut : `60`).
-- `plugins.entries.xai.config.xSearch` : paramètres de X Search xAI (recherche web Grok).
- - `enabled` : active 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 (expérimental). Voir [Dreaming](/fr/concepts/dreaming) pour les phases et seuils.
- - `enabled` : commutateur maître du dreaming (par défaut `false`).
- - `frequency` : cadence cron pour chaque balayage complet de dreaming (`"0 3 * * *"` par défaut).
+ - `timeoutSeconds` : délai d’expiration de la requête de scraping en secondes (par défaut : `60`).
+- `plugins.entries.xai.config.xSearch` : paramètres xAI X Search (recherche web Grok).
+ - `enabled` : active le provider X Search.
+ - `model` : modèle Grok à utiliser pour la recherche (par exemple `"grok-4-1-fast"`).
+- `plugins.entries.memory-core.config.dreaming` : paramètres de rêverie de la mémoire (expérimental). Consultez [Rêverie](/fr/concepts/dreaming) pour les phases et les seuils.
+ - `enabled` : commutateur maître de rêverie (par défaut `false`).
+ - `frequency` : cadence cron pour chaque balayage complet de rêverie (`"0 3 * * *"` par défaut).
- la politique de phase et les seuils sont des détails d’implémentation (pas des clés de configuration destinées aux utilisateurs).
-- La configuration mémoire complète se trouve dans [Référence de configuration de la mémoire](/fr/reference/memory-config) :
+- 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 bundle Claude activés peuvent aussi contribuer des valeurs Pi par défaut embarquées depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, pas comme correctifs bruts de configuration OpenClaw.
-- `plugins.slots.memory` : sélectionnez l’identifiant du plugin mémoire actif, ou `"none"` pour désactiver les plugins mémoire.
-- `plugins.slots.contextEngine` : sélectionnez l’identifiant du plugin moteur de contexte actif ; la valeur par défaut est `"legacy"` à moins que vous n’installiez et sélectionniez un autre moteur.
-- `plugins.installs` : métadonnées d’installation gérées par CLI utilisées par `openclaw plugins update`.
+- Les plugins bundle Claude activés peuvent également 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 patchs de configuration OpenClaw bruts.
+- `plugins.slots.memory` : choisissez l’ID du plugin mémoire actif, ou `"none"` pour désactiver les plugins mémoire.
+- `plugins.slots.contextEngine` : choisissez l’ID du plugin moteur de contexte actif ; vaut par défaut `"legacy"` sauf si vous installez et sélectionnez un autre moteur.
+- `plugins.installs` : métadonnées d’installation gérées par la CLI utilisées par `openclaw plugins update`.
- Inclut `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
- - Considérez `plugins.installs.*` comme un état géré ; préférez les commandes CLI aux modifications manuelles.
+ - Traitez `plugins.installs.*` comme un état géré ; préférez les commandes CLI aux modifications manuelles.
-Voir [Plugins](/fr/tools/plugin).
+Consultez [Plugins](/fr/tools/plugin).
---
@@ -2791,14 +2792,919 @@ Voir [Plugins](/fr/tools/plugin).
```
- `evaluateEnabled: false` désactive `act:evaluate` et `wait --fn`.
-- `ssrfPolicy.dangerouslyAllowPrivateNetwork` vaut par défaut `true` lorsqu’il n’est pas défini (modèle de réseau de confiance).
-- Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` pour une navigation Browser stricte limitée au réseau public.
-- En mode strict, les points de terminaison distants de profil CDP (`profiles.*.cdpUrl`) sont soumis au même blocage réseau privé lors des vérifications de portée/découverte.
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` vaut par défaut `true` lorsqu’il n’est pas défini (modèle réseau de confiance).
+- Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` pour une navigation navigateur strictement publique.
+- En mode strict, les points de terminaison distants du profil CDP (`profiles.*.cdpUrl`) sont soumis au même blocage de réseau privé lors des vérifications d’accessibilité/découverte.
- `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme ancien alias.
- En mode strict, utilisez `ssrfPolicy.hostnameAllowlist` et `ssrfPolicy.allowedHostnames` pour des exceptions explicites.
-- Les profils distants sont en mode attache uniquement (démarrer/arrêter/réinitialiser désactivé).
+- Les profils distants sont en mode attachement uniquement (démarrage/arrêt/réinitialisation désactivés).
- `profiles.*.cdpUrl` accepte `http://`, `https://`, `ws://` et `wss://`.
- Utilisez HTTP(S) lorsque vous voulez que OpenClaw découvre `/json/version` ; utilisez WS(S)
- lorsque votre fournisseur vous donne une URL WebSocket DevTools directe.
-- Les profils `existing-session` sont réservés à l’hôte et utilisent Chrome MCP au lieu de CDP.
-- Les profils `existing
\ No newline at end of file
+ Utilisez HTTP(S) lorsque vous voulez qu’OpenClaw découvre `/json/version` ; utilisez WS(S)
+ lorsque votre provider vous donne une URL WebSocket DevTools directe.
+- Les profils `existing-session` sont propres à l’hôte et utilisent Chrome MCP au lieu de CDP.
+- 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 actuelles du routage Chrome MCP :
+ actions basées sur snapshot/référence au lieu d’un ciblage par sélecteur CSS, hooks d’upload
+ d’un seul fichier, pas de remplacements de délai d’expiration de boîte de dialogue, pas de `wait --load networkidle`, ni
+ `responsebody`, export PDF, interception de téléchargement ou actions par lot.
+- Les profils locaux gérés `openclaw` attribuent automatiquement `cdpPort` et `cdpUrl` ; ne définissez
+ `cdpUrl` explicitement que pour un CDP distant.
+- Ordre d’auto-détection : navigateur par défaut s’il est basé sur Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
+- Service de contrôle : loopback uniquement (port dérivé de `gateway.port`, par défaut `18791`).
+- `extraArgs` ajoute des drapeaux de lancement supplémentaires au démarrage local de Chromium (par exemple
+ `--disable-gpu`, dimensionnement de fenêtre ou drapeaux de débogage).
+
+---
+
+## UI
+
+```json5
+{
+ ui: {
+ seamColor: "#FF4500",
+ assistant: {
+ name: "OpenClaw",
+ avatar: "CB", // emoji, short text, image URL, or data URI
+ },
+ },
+}
+```
+
+- `seamColor` : couleur d’accentuation pour le chrome UI des applications natives (teinte de bulle du mode Talk, etc.).
+- `assistant` : remplacement d’identité de l’interface Control UI. Utilise comme solution de repli l’identité de l’agent actif.
+
+---
+
+## Gateway
+
+```json5
+{
+ gateway: {
+ mode: "local", // local | remote
+ port: 18789,
+ bind: "loopback",
+ auth: {
+ mode: "token", // none | token | password | trusted-proxy
+ token: "your-token",
+ // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
+ // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
+ allowTailscale: true,
+ rateLimit: {
+ maxAttempts: 10,
+ windowMs: 60000,
+ lockoutMs: 300000,
+ exemptLoopback: true,
+ },
+ },
+ tailscale: {
+ mode: "off", // off | serve | funnel
+ resetOnExit: false,
+ },
+ controlUi: {
+ enabled: true,
+ basePath: "/openclaw",
+ // root: "dist/control-ui",
+ // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
+ // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
+ // allowInsecureAuth: false,
+ // dangerouslyDisableDeviceAuth: false,
+ },
+ remote: {
+ url: "ws://gateway.tailnet:18789",
+ transport: "ssh", // ssh | direct
+ token: "your-token",
+ // password: "your-password",
+ },
+ trustedProxies: ["10.0.0.1"],
+ // Optional. Default false.
+ allowRealIpFallback: false,
+ tools: {
+ // Additional /tools/invoke HTTP denies
+ deny: ["browser"],
+ // Remove tools from the default HTTP deny list
+ allow: ["gateway"],
+ },
+ push: {
+ apns: {
+ relay: {
+ baseUrl: "https://relay.example.com",
+ timeoutMs: 10000,
+ },
+ },
+ },
+ },
+}
+```
+
+
+
+- `mode` : `local` (exécuter la passerelle) ou `remote` (se connecter à une passerelle distante). La passerelle refuse de démarrer sauf si `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`.
+- **Anciens alias de bind** : 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`).
+- **Remarque Docker** : la valeur par défaut `loopback` écoute sur `127.0.0.1` dans le conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc la passerelle 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 liaisons non loopback exigent l’authentification de la passerelle. 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’intégration génère un jeton par défaut.
+- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés (y compris via SecretRef), 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 authentification. À utiliser uniquement pour des configurations loopback local loopback de confiance ; cette option n’est volontairement pas proposée par les invites d’intégration.
+- `gateway.auth.mode: "trusted-proxy"` : délègue l’authentification à un proxy inverse sensible à l’identité et fait confiance aux en-têtes d’identité provenant de `gateway.trustedProxies` (voir [Auth Trusted Proxy](/fr/gateway/trusted-proxy-auth)). Ce mode attend une source de proxy **non loopback** ; les proxies inverses loopback sur le même hôte ne satisfont pas l’authentification trusted-proxy.
+- `gateway.auth.allowTailscale` : lorsque `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’authentification de Control UI/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison API HTTP **n’utilisent pas** cette authentification par en-tête Tailscale ; ils suivent à la place le mode d’authentification HTTP normal de la passerelle. Ce flux sans jeton suppose que l’hôte de la passerelle est de confiance. Vaut par défaut `true` lorsque `tailscale.mode = "serve"`.
+- `gateway.auth.rateLimit` : limite facultative des échecs d’authentification. S’applique par IP client et par portée d’authentification (secret partagé et jeton d’appareil sont suivis indépendamment). Les tentatives bloquées renvoient `429` + `Retry-After`.
+ - Sur le chemin asynchrone Tailscale Serve de Control UI, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives concurrentes invalides du même client peuvent donc déclencher la limite dès la deuxième requête au lieu que les deux passent en course comme de simples échecs de correspondance.
+ - `gateway.auth.rateLimit.exemptLoopback` vaut par défaut `true` ; définissez `false` lorsque vous voulez délibérément limiter aussi le trafic localhost (pour des configurations de test ou des déploiements proxy stricts).
+- Les tentatives d’authentification WS d’origine navigateur sont toujours limitées avec exemption loopback désactivée (défense en profondeur contre les attaques par force brute localhost depuis le navigateur).
+- En loopback, ces verrouillages d’origine navigateur sont isolés par valeur `Origin`
+ normalisée, afin que des échecs répétés depuis une origine localhost n’entraînent pas automatiquement
+ le verrouillage d’une origine différente.
+- `tailscale.mode` : `serve` (tailnet uniquement, liaison loopback) ou `funnel` (public, nécessite une authentification).
+- `controlUi.allowedOrigins` : liste d’autorisations explicite des origines navigateur pour les connexions WebSocket Gateway. Requise lorsque des clients navigateur sont attendus depuis des origines non loopback.
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le repli d’origine via en-tête Host pour les déploiements qui s’appuient volontairement sur cette politique d’origine.
+- `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` : remplacement de dernier recours côté client qui autorise `ws://` en clair vers des IP de réseau privé de confiance ; par défaut, le texte en clair reste limité au loopback.
+- `gateway.remote.token` / `.password` sont des champs d’identifiants du client distant. Ils ne configurent pas à eux seuls l’authentification de la passerelle.
+- `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 reposant sur le relais vers la passerelle. Cette URL doit correspondre à l’URL du relais compilée dans le build iOS.
+- `gateway.push.apns.relay.timeoutMs` : délai d’expiration en millisecondes pour les envois passerelle-vers-relais. Par défaut : `10000`.
+- Les enregistrements basés sur le relais sont délégués à une identité de passerelle spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais, et transmet à la passerelle une autorisation d’envoi limitée à cet enregistrement. Une autre passerelle ne peut pas réutiliser cet enregistrement stocké.
+- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements temporaires via l’environnement 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.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. Conservez cette valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`.
+- `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages du moniteur de santé par canal/compte sur une heure glissante. Par défaut : `10`.
+- `channels..healthMonitor.enabled` : désactivation facultative par canal des redémarrages du moniteur de santé tout en gardant le moniteur global activé.
+- `channels..accounts..healthMonitor.enabled` : remplacement par compte pour les canaux multi-comptes. Lorsqu’il est défini, il a priorité sur le remplacement au niveau du canal.
+- Les chemins d’appel de passerelle locale 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 de manière sécurisée (aucune solution de repli distante ne masque cela).
+- `trustedProxies` : IP de proxy inverse qui terminent TLS ou injectent des en-têtes de client transféré. Listez uniquement des proxies que vous contrôlez. Les entrées loopback restent valides pour les configurations de détection locale/proxy sur le même hôte (par exemple Tailscale Serve ou un proxy inverse local), mais elles **ne** rendent **pas** les requêtes loopback admissibles à `gateway.auth.mode: "trusted-proxy"`.
+- `allowRealIpFallback` : lorsque `true`, la passerelle accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement d’échec sécurisé.
+- `gateway.tools.deny` : noms d’outils supplémentaires bloqués pour HTTP `POST /tools/invoke` (étend la liste d’interdiction par défaut).
+- `gateway.tools.allow` : supprime des noms d’outils de la liste d’interdiction HTTP par défaut.
+
+
+
+### Points de terminaison compatibles OpenAI
+
+- Chat Completions : désactivé par défaut. Activez-le avec `gateway.http.endpoints.chatCompletions.enabled: true`.
+- API Responses : `gateway.http.endpoints.responses.enabled`.
+- Renforcement des entrées URL pour Responses :
+ - `gateway.http.endpoints.responses.maxUrlParts`
+ - `gateway.http.endpoints.responses.files.urlAllowlist`
+ - `gateway.http.endpoints.responses.images.urlAllowlist`
+ Les listes d’autorisations 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 facultatif de renforcement des réponses :
+ - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour des origines HTTPS que vous contrôlez ; voir [Auth Trusted Proxy](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts))
+
+### Isolation multi-instance
+
+Exécutez plusieurs passerelles sur un même hôte avec des ports et répertoires d’état uniques :
+
+```bash
+OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
+OPENCLAW_STATE_DIR=~/.openclaw-a \
+openclaw gateway --port 19001
+```
+
+Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`).
+
+Consultez [Passerelles multiples](/fr/gateway/multiple-gateways).
+
+### `gateway.tls`
+
+```json5
+{
+ gateway: {
+ tls: {
+ enabled: false,
+ autoGenerate: false,
+ certPath: "/etc/openclaw/tls/server.crt",
+ keyPath: "/etc/openclaw/tls/server.key",
+ caPath: "/etc/openclaw/tls/ca-bundle.crt",
+ },
+ },
+}
+```
+
+- `enabled` : active la terminaison TLS au niveau de l’écouteur de la passerelle (HTTPS/WSS) (par défaut : `false`).
+- `autoGenerate` : génère automatiquement une paire locale certificat/clé auto-signée lorsque des fichiers explicites ne sont pas configurés ; usage local/dev uniquement.
+- `certPath` : chemin du système de fichiers vers le fichier certificat TLS.
+- `keyPath` : chemin du système de fichiers vers le fichier clé privée TLS ; conservez des permissions restreintes.
+- `caPath` : chemin facultatif du bundle CA pour la vérification client ou des chaînes de confiance personnalisées.
+
+### `gateway.reload`
+
+```json5
+{
+ gateway: {
+ reload: {
+ mode: "hybrid", // off | restart | hot | hybrid
+ debounceMs: 500,
+ deferralTimeoutMs: 300000,
+ },
+ },
+}
+```
+
+- `mode` : contrôle la manière dont les modifications de configuration sont appliquées à l’exécution.
+ - `"off"` : ignore les modifications en direct ; les changements nécessitent un redémarrage explicite.
+ - `"restart"` : redémarre toujours le processus de passerelle lors d’un changement de configuration.
+ - `"hot"` : applique les changements dans le processus sans redémarrage.
+ - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; revient à un redémarrage si nécessaire.
+- `debounceMs` : fenêtre d’anti-rebond en ms avant l’application des changements de configuration (entier non négatif).
+- `deferralTimeoutMs` : temps maximal en ms pour attendre la fin des opérations en cours avant de forcer un redémarrage (par défaut : `300000` = 5 minutes).
+
+---
+
+## Hooks
+
+```json5
+{
+ hooks: {
+ enabled: true,
+ token: "shared-secret",
+ path: "/hooks",
+ maxBodyBytes: 262144,
+ defaultSessionKey: "hook:ingress",
+ allowRequestSessionKey: false,
+ allowedSessionKeyPrefixes: ["hook:"],
+ allowedAgentIds: ["hooks", "main"],
+ presets: ["gmail"],
+ transformsDir: "~/.openclaw/hooks/transforms",
+ mappings: [
+ {
+ match: { path: "gmail" },
+ action: "agent",
+ agentId: "hooks",
+ wakeMode: "now",
+ name: "Gmail",
+ sessionKey: "hook:gmail:{{messages[0].id}}",
+ messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
+ deliver: true,
+ channel: "last",
+ model: "openai/gpt-5.4-mini",
+ },
+ ],
+ },
+}
+```
+
+Auth : `Authorization: Bearer ` ou `x-openclaw-token: `.
+Les jetons de hook dans la chaîne de requête sont rejetés.
+
+Remarques 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` ; réutiliser le jeton Gateway est rejeté.
+- `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié tel que `/hooks`.
+- Si `hooks.allowRequestSessionKey=true`, contraignez `hooks.allowedSessionKeyPrefixes` (par exemple `["hook:"]`).
+
+**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` depuis la charge utile de la requête n’est accepté que lorsque `hooks.allowRequestSessionKey=true` (par défaut : `false`).
+- `POST /hooks/` → résolu via `hooks.mappings`
+
+
+
+- `match.path` correspond au sous-chemin après `/hooks` (par ex. `/hooks/gmail` → `gmail`).
+- `match.source` correspond à un champ de la 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 renvoyant une action de hook.
+ - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et la traversée sont rejetés).
+- `agentId` route vers un agent spécifique ; les ID inconnus se replient sur l’agent par défaut.
+- `allowedAgentIds` : restreint le routage explicite (`*` ou omis = tout autoriser, `[]` = tout refuser).
+- `defaultSessionKey` : clé de session fixe facultative pour les exécutions d’agent hook sans `sessionKey` explicite.
+- `allowRequestSessionKey` : autorise les appelants `/hooks/agent` à définir `sessionKey` (par défaut : `false`).
+- `allowedSessionKeyPrefixes` : liste d’autorisations facultative de préfixes pour les valeurs explicites de `sessionKey` (requête + mapping), par ex. `["hook:"]`.
+- `deliver: true` envoie la réponse finale à un canal ; `channel` vaut par défaut `last`.
+- `model` remplace le LLM pour cette exécution de hook (doit être autorisé si un catalogue de modèles est défini).
+
+
+
+### Intégration Gmail
+
+```json5
+{
+ hooks: {
+ gmail: {
+ account: "openclaw@gmail.com",
+ topic: "projects//topics/gog-gmail-watch",
+ subscription: "gog-gmail-watch-push",
+ pushToken: "shared-push-token",
+ hookUrl: "http://127.0.0.1:18789/hooks/gmail",
+ includeBody: true,
+ maxBytes: 20000,
+ renewEveryMinutes: 720,
+ serve: { bind: "127.0.0.1", port: 8788, path: "/" },
+ tailscale: { mode: "funnel", path: "/gmail-pubsub" },
+ model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+ thinking: "off",
+ },
+ },
+}
+```
+
+- La Gateway démarre automatiquement `gog gmail watch serve` au démarrage lorsqu’il est configuré. Définissez `OPENCLAW_SKIP_GMAIL_WATCHER=1` pour le désactiver.
+- N’exécutez pas un `gog gmail watch serve` séparé en parallèle de la Gateway.
+
+---
+
+## Hôte Canvas
+
+```json5
+{
+ canvasHost: {
+ root: "~/.openclaw/workspace/canvas",
+ liveReload: true,
+ // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
+ },
+}
+```
+
+- Sert le HTML/CSS/JS modifiable par l’agent et A2UI sur HTTP sous le port Gateway :
+ - `http://:/__openclaw__/canvas/`
+ - `http://:/__openclaw__/a2ui/`
+- Local uniquement : conservez `gateway.bind: "loopback"` (par défaut).
+- Liaisons non loopback : les routes canvas nécessitent l’authentification Gateway (token/password/trusted-proxy), comme les autres surfaces HTTP Gateway.
+- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; après qu’un nœud est appairé et connecté, la Gateway annonce des URL de capacité limitées au nœud pour l’accès canvas/A2UI.
+- Les URL de capacité sont liées à la session WS active du nœud et expirent rapidement. Aucun repli basé sur IP n’est utilisé.
+- Injecte un client de rechargement à chaud dans le HTML servi.
+- Crée automatiquement un `index.html` de démarrage lorsqu’il est vide.
+- Sert également A2UI à `/__openclaw__/a2ui/`.
+- Les changements nécessitent un redémarrage de la passerelle.
+- Désactivez le rechargement à chaud pour les grands répertoires ou les erreurs `EMFILE`.
+
+---
+
+## Découverte
+
+### mDNS (Bonjour)
+
+```json5
+{
+ discovery: {
+ mdns: {
+ mode: "minimal", // minimal | full | off
+ },
+ },
+}
+```
+
+- `minimal` (par défaut) : omet `cliPath` + `sshPort` des enregistrements TXT.
+- `full` : inclut `cliPath` + `sshPort`.
+- Le nom d’hôte vaut par défaut `openclaw`. Remplacez-le avec `OPENCLAW_MDNS_HOSTNAME`.
+
+### Wide-area (DNS-SD)
+
+```json5
+{
+ discovery: {
+ wideArea: { enabled: true },
+ },
+}
+```
+
+Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour la découverte inter-réseaux, associez-la à un serveur DNS (CoreDNS recommandé) + le split DNS Tailscale.
+
+Installation : `openclaw dns setup --apply`.
+
+---
+
+## Environnement
+
+### `env` (variables d’environnement en ligne)
+
+```json5
+{
+ env: {
+ OPENROUTER_API_KEY: "sk-or-...",
+ vars: {
+ GROQ_API_KEY: "gsk-...",
+ },
+ shellEnv: {
+ enabled: true,
+ timeoutMs: 15000,
+ },
+ },
+}
+```
+
+- Les variables d’environnement en ligne ne sont appliquées que si l’environnement du processus ne contient pas déjà la clé.
+- Fichiers `.env` : `.env` du répertoire courant + `~/.openclaw/.env` (aucun des deux 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 l’ordre de priorité complet.
+
+### Substitution de variables d’environnement
+
+Référencez des variables d’environnement dans n’importe quelle chaîne de configuration avec `${VAR_NAME}` :
+
+```json5
+{
+ gateway: {
+ auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
+ },
+}
+```
+
+- Seuls les noms en majuscules sont pris en charge : `[A-Z_][A-Z0-9_]*`.
+- Les variables manquantes/vides déclenchent une erreur au chargement de la configuration.
+- Échappez avec `$${VAR}` pour obtenir un littéral `${VAR}`.
+- Fonctionne avec `$include`.
+
+---
+
+## Secrets
+
+Les références de secret sont additives : les valeurs en texte brut continuent de fonctionner.
+
+### `SecretRef`
+
+Utilisez une seule forme d’objet :
+
+```json5
+{ source: "env" | "file" | "exec", provider: "default", id: "..." }
+```
+
+Validation :
+
+- motif `provider` : `^[a-z][a-z0-9_-]{0,63}$`
+- motif `source: "env"` pour `id` : `^[A-Z][A-Z0-9_]{0,127}$`
+- `source: "file"` `id` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`)
+- motif `source: "exec"` pour `id` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
+- les `id` `source: "exec"` ne doivent pas contenir de segments de chemin `.` ou `..` séparés par `/` (par exemple `a/../b` est rejeté)
+
+### Surface d’identifiants prise en charge
+
+- Matrice canonique : [Surface d’identifiants SecretRef](/fr/reference/secretref-credential-surface)
+- `secrets apply` cible les chemins d’identifiants pris en charge dans `openclaw.json`.
+- Les références `auth-profiles.json` sont incluses dans la résolution à l’exécution et dans la couverture d’audit.
+
+### Configuration des providers de secrets
+
+```json5
+{
+ secrets: {
+ providers: {
+ default: { source: "env" }, // optional explicit env provider
+ filemain: {
+ source: "file",
+ path: "~/.openclaw/secrets.json",
+ mode: "json",
+ timeoutMs: 5000,
+ },
+ vault: {
+ source: "exec",
+ command: "/usr/local/bin/openclaw-vault-resolver",
+ passEnv: ["PATH", "VAULT_ADDR"],
+ },
+ },
+ defaults: {
+ env: "default",
+ file: "filemain",
+ exec: "vault",
+ },
+ },
+}
+```
+
+Remarques :
+
+- Le provider `file` prend en charge `mode: "json"` et `mode: "singleValue"` (`id` doit être `"value"` en mode singleValue).
+- Le provider `exec` exige un chemin `command` absolu et utilise des charges utiles de protocole sur stdin/stdout.
+- Par défaut, les chemins de commande symlink sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symlink tout en validant le chemin cible résolu.
+- Si `trustedDirs` est configuré, la vérification de répertoire de confiance s’applique au chemin cible résolu.
+- L’environnement enfant de `exec` est minimal par défaut ; transmettez explicitement les variables nécessaires 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 des surfaces activées font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec des diagnostics.
+
+---
+
+## Stockage de l’authentification
+
+```json5
+{
+ auth: {
+ profiles: {
+ "anthropic:default": { provider: "anthropic", mode: "api_key" },
+ "anthropic:work": { provider: "anthropic", mode: "api_key" },
+ "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
+ },
+ order: {
+ anthropic: ["anthropic:default", "anthropic:work"],
+ "openai-codex": ["openai-codex:personal"],
+ },
+ },
+}
+```
+
+- Les profils par agent sont stockés dans `/auth-profiles.json`.
+- `auth-profiles.json` prend en charge les références au niveau valeur (`keyRef` pour `api_key`, `tokenRef` pour `token`) pour les modes d’identifiants statiques.
+- Les profils en mode OAuth (`auth.profiles..mode = "oauth"`) ne prennent pas en charge les identifiants de profil d’authentification basés sur SecretRef.
+- Les identifiants statiques d’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont détectées.
+- Les anciennes importations OAuth proviennent de `~/.openclaw/credentials/oauth.json`.
+- Consultez [OAuth](/fr/concepts/oauth).
+- Comportement de l’exécution des secrets et outils `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets).
+
+### `auth.cooldowns`
+
+```json5
+{
+ auth: {
+ cooldowns: {
+ billingBackoffHours: 5,
+ billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
+ billingMaxHours: 24,
+ authPermanentBackoffMinutes: 10,
+ authPermanentMaxMinutes: 60,
+ failureWindowHours: 24,
+ overloadedProfileRotations: 1,
+ overloadedBackoffMs: 0,
+ rateLimitedProfileRotations: 1,
+ },
+ },
+}
+```
+
+- `billingBackoffHours` : temporisation 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 lié à la facturation peut
+ toujours arriver ici même sur des réponses `401`/`403`, mais les moteurs de correspondance de texte
+ spécifiques au provider restent limités au provider qui les possède (par exemple OpenRouter
+ `Key limit exceeded`). Les messages HTTP `402` de fenêtre d’utilisation ou de
+ limite de dépense organisation/espace de travail pouvant être réessayés restent dans le chemin
+ `rate_limit`.
+- `billingBackoffHoursByProvider` : remplacements facultatifs par provider pour les heures de temporisation liées à la facturation.
+- `billingMaxHours` : plafond en heures pour la croissance exponentielle de la temporisation liée à la facturation (par défaut : `24`).
+- `authPermanentBackoffMinutes` : temporisation de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`).
+- `authPermanentMaxMinutes` : plafond en minutes pour la croissance de la temporisation `auth_permanent` (par défaut : `60`).
+- `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de temporisation (par défaut : `24`).
+- `overloadedProfileRotations` : nombre maximal de rotations de profil d’authentification chez le même provider pour les erreurs de surcharge avant de passer au modèle de repli (par défaut : `1`). Les formes de provider occupé telles que `ModelNotReadyException` arrivent ici.
+- `overloadedBackoffMs` : délai fixe avant de réessayer une rotation de provider/profil surchargé (par défaut : `0`).
+- `rateLimitedProfileRotations` : nombre maximal de rotations de profil d’authentification chez le même provider pour les erreurs de limitation de débit avant de passer au modèle de repli (par défaut : `1`). Cette catégorie de limitation de débit inclut des textes de provider tels que `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`.
+
+---
+
+## Journalisation
+
+```json5
+{
+ logging: {
+ level: "info",
+ file: "/tmp/openclaw/openclaw.log",
+ consoleLevel: "info",
+ consoleStyle: "pretty", // pretty | compact | json
+ redactSensitive: "tools", // off | tools
+ redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
+ },
+}
+```
+
+- Fichier journal par défaut : `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
+- Définissez `logging.file` pour un chemin stable.
+- `consoleLevel` passe à `debug` avec `--verbose`.
+- `maxFileBytes` : taille maximale du fichier journal en octets avant suppression des écritures (entier positif ; par défaut : `524288000` = 500 Mo). Utilisez une rotation externe des journaux pour les déploiements de production.
+
+---
+
+## Diagnostics
+
+```json5
+{
+ diagnostics: {
+ enabled: true,
+ flags: ["telegram.*"],
+ stuckSessionWarnMs: 30000,
+
+ otel: {
+ enabled: false,
+ endpoint: "https://otel-collector.example.com:4318",
+ protocol: "http/protobuf", // http/protobuf | grpc
+ headers: { "x-tenant-id": "my-org" },
+ serviceName: "openclaw-gateway",
+ traces: true,
+ metrics: true,
+ logs: false,
+ sampleRate: 1.0,
+ flushIntervalMs: 5000,
+ },
+
+ cacheTrace: {
+ enabled: false,
+ filePath: "~/.openclaw/logs/cache-trace.jsonl",
+ includeMessages: true,
+ includePrompt: true,
+ includeSystem: true,
+ },
+ },
+}
+```
+
+- `enabled` : commutateur maître de la sortie d’instrumentation (par défaut : `true`).
+- `flags` : tableau de chaînes de drapeaux activant une sortie de journal ciblée (prend en charge des jokers comme `"telegram.*"` ou `"*"`).
+- `stuckSessionWarnMs` : seuil d’ancienneté en ms pour émettre des avertissements de session bloquée tant qu’une session reste à l’état de traitement.
+- `otel.enabled` : active le pipeline d’export OpenTelemetry (par défaut : `false`).
+- `otel.endpoint` : URL du collecteur pour l’export OTel.
+- `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, des métriques ou des journaux.
+- `otel.sampleRate` : taux d’échantillonnage des traces `0`–`1`.
+- `otel.flushIntervalMs` : intervalle périodique de vidage de télémétrie en ms.
+- `cacheTrace.enabled` : journalise les instantanés de trace du cache pour les exécutions intégrées (par défaut : `false`).
+- `cacheTrace.filePath` : chemin de sortie pour le JSONL de trace du cache (par défaut : `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem` : contrôle ce qui est inclus dans la sortie de trace du cache (tous à `true` par défaut).
+
+---
+
+## Mise à jour
+
+```json5
+{
+ update: {
+ channel: "stable", // stable | beta | dev
+ checkOnStart: true,
+
+ auto: {
+ enabled: false,
+ stableDelayHours: 6,
+ stableJitterHours: 12,
+ betaCheckIntervalHours: 1,
+ },
+ },
+}
+```
+
+- `channel` : canal de publication pour les installations npm/git — `"stable"`, `"beta"` ou `"dev"`.
+- `checkOnStart` : vérifie les mises à jour npm au démarrage de la passerelle (par défaut : `true`).
+- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de paquets (par défaut : `false`).
+- `auto.stableDelayHours` : délai minimal en heures avant application automatique sur le canal stable (par défaut : `6` ; max : `168`).
+- `auto.stableJitterHours` : fenêtre supplémentaire d’étalement du déploiement du canal stable en heures (par défaut : `12` ; max : `168`).
+- `auto.betaCheckIntervalHours` : fréquence d’exécution des vérifications du canal bêta en heures (par défaut : `1` ; max : `24`).
+
+---
+
+## ACP
+
+```json5
+{
+ acp: {
+ enabled: false,
+ dispatch: { enabled: true },
+ backend: "acpx",
+ defaultAgent: "main",
+ allowedAgents: ["main", "ops"],
+ maxConcurrentSessions: 10,
+
+ stream: {
+ coalesceIdleMs: 50,
+ maxChunkChars: 1000,
+ repeatSuppression: true,
+ deliveryMode: "live", // live | final_only
+ hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
+ maxOutputChars: 50000,
+ maxSessionUpdateChars: 500,
+ },
+
+ runtime: {
+ ttlMinutes: 30,
+ },
+ },
+}
+```
+
+- `enabled` : garde-fou global de fonctionnalité ACP (par défaut : `false`).
+- `dispatch.enabled` : garde-fou indépendant pour la distribution 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é).
+- `defaultAgent` : ID d’agent ACP de repli lorsque les lancements ne spécifient pas de cible explicite.
+- `allowedAgents` : liste d’autorisations des ID d’agent autorisés 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 veille en ms pour le texte diffusé.
+- `stream.maxChunkChars` : taille maximale d’un bloc avant division de la projection du bloc diffusé.
+- `stream.repeatSuppression` : supprime les lignes répétées d’état/d’outil par tour (par défaut : `true`).
+- `stream.deliveryMode` : `"live"` diffuse progressivement ; `"final_only"` met en 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 d’état/mise à jour ACP projetées.
+- `stream.tagVisibility` : enregistrement des noms de balises avec 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 éligibilité au nettoyage.
+- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement d’exécution ACP.
+
+---
+
+## CLI
+
+```json5
+{
+ cli: {
+ banner: {
+ taglineMode: "off", // random | default | off
+ },
+ },
+}
+```
+
+- `cli.banner.taglineMode` contrôle le style de slogan de la bannière :
+ - `"random"` (par défaut) : slogans rotatifs humoristiques/de saison.
+ - `"default"` : slogan neutre fixe (`All your chats, one OpenClaw.`).
+ - `"off"` : aucun texte de slogan (le titre/version de la bannière est toujours affiché).
+- Pour masquer toute la bannière (pas seulement les slogans), définissez la variable d’environnement `OPENCLAW_HIDE_BANNER=1`.
+
+---
+
+## Assistant
+
+Métadonnées écrites par les flux guidés d’installation de la CLI (`onboard`, `configure`, `doctor`) :
+
+```json5
+{
+ wizard: {
+ lastRunAt: "2026-01-01T00:00:00.000Z",
+ lastRunVersion: "2026.1.4",
+ lastRunCommit: "abc1234",
+ lastRunCommand: "configure",
+ lastRunMode: "local",
+ },
+}
+```
+
+---
+
+## Identité
+
+Consultez les champs d’identité de `agents.list` sous [Valeurs par défaut des agents](#agent-defaults).
+
+---
+
+## Bridge (hérité, supprimé)
+
+Les builds actuels n’incluent plus le bridge TCP. Les nœuds se connectent via le WebSocket Gateway. Les clés `bridge.*` ne font plus partie du schéma de configuration (la validation échoue tant qu’elles ne sont pas supprimées ; `openclaw doctor --fix` peut retirer les clés inconnues).
+
+
+
+```json
+{
+ "bridge": {
+ "enabled": true,
+ "port": 18790,
+ "bind": "tailnet",
+ "tls": {
+ "enabled": true,
+ "autoGenerate": true
+ }
+ }
+}
+```
+
+
+
+---
+
+## Cron
+
+```json5
+{
+ cron: {
+ enabled: true,
+ maxConcurrentRuns: 2,
+ webhook: "https://example.invalid/legacy", // solution de repli obsolète pour les tâches stockées notify:true
+ webhookToken: "replace-with-dedicated-token", // jeton bearer facultatif pour l’authentification webhook sortante
+ sessionRetention: "24h", // chaîne de durée ou false
+ runLog: {
+ maxBytes: "2mb", // 2_000_000 octets par défaut
+ keepLines: 2000, // 2000 par défaut
+ },
+ },
+}
+```
+
+- `sessionRetention` : durée de conservation des sessions d’exécution cron isolées terminées avant élagage depuis `sessions.json`. Contrôle également le nettoyage des transcriptions cron supprimées archivées. Par défaut : `24h` ; définissez `false` pour désactiver.
+- `runLog.maxBytes` : taille maximale par fichier journal d’exécution (`cron/runs/.jsonl`) avant élagage. Par défaut : `2_000_000` octets.
+- `runLog.keepLines` : lignes les plus récentes conservées lorsque l’élagage du journal d’exécution est déclenché. Par défaut : `2000`.
+- `webhookToken` : jeton bearer utilisé pour la livraison POST webhook cron (`delivery.mode = "webhook"`), si omis aucun en-tête d’authentification n’est envoyé.
+- `webhook` : URL webhook héritée obsolète de repli (http/https), utilisée uniquement pour les tâches stockées qui ont encore `notify: true`.
+
+### `cron.retry`
+
+```json5
+{
+ cron: {
+ retry: {
+ maxAttempts: 3,
+ backoffMs: [30000, 60000, 300000],
+ retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
+ },
+ },
+}
+```
+
+- `maxAttempts` : nombre maximal de nouvelles tentatives pour les tâches ponctuelles sur erreurs transitoires (par défaut : `3` ; plage : `0`–`10`).
+- `backoffMs` : tableau de délais de temporisation en ms pour chaque tentative de reprise (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées).
+- `retryOn` : types d’erreurs qui déclenchent des nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez-le 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.
+
+### `cron.failureAlert`
+
+```json5
+{
+ cron: {
+ failureAlert: {
+ enabled: false,
+ after: 3,
+ cooldownMs: 3600000,
+ mode: "announce",
+ accountId: "main",
+ },
+ },
+}
+```
+
+- `enabled` : active les alertes d’échec pour les tâches cron (par défaut : `false`).
+- `after` : nombre d’échecs consécutifs avant déclenchement d’une alerte (entier positif, min : `1`).
+- `cooldownMs` : nombre minimal de millisecondes entre des alertes répétées pour une même tâche (entier non négatif).
+- `mode` : mode de livraison — `"announce"` envoie via un message de canal ; `"webhook"` publie vers le webhook configuré.
+- `accountId` : ID facultatif de compte ou de canal pour limiter la livraison des alertes.
+
+### `cron.failureDestination`
+
+```json5
+{
+ cron: {
+ failureDestination: {
+ mode: "announce",
+ channel: "last",
+ to: "channel:C1234567890",
+ accountId: "main",
+ },
+ },
+}
+```
+
+- Destination par défaut des notifications d’échec cron pour l’ensemble des tâches.
+- `mode` : `"announce"` ou `"webhook"` ; vaut par défaut `"announce"` lorsqu’il y a suffisamment de données cibles.
+- `channel` : remplacement de canal pour la livraison announce. `"last"` réutilise le dernier canal de livraison connu.
+- `to` : cible announce explicite ou URL webhook. Requis pour le mode webhook.
+- `accountId` : remplacement facultatif de compte pour la livraison.
+- `delivery.failureDestination` par tâche remplace cette valeur globale par défaut.
+- Lorsqu’aucune destination d’échec globale ou par tâche n’est définie, les tâches qui livrent déjà via `announce` reviennent à cette cible announce 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 vaut `"webhook"`.
+
+Consultez [Tâches Cron](/fr/automation/cron-jobs). Les exécutions cron isolées sont suivies comme [tâches d’arrière-plan](/fr/automation/tasks).
+
+---
+
+## Variables de modèle média
+
+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 historique/enveloppes d’expéditeur) |
+| `{{BodyStripped}}` | Corps avec les mentions de groupe retirées |
+| `{{From}}` | Identifiant de l’expéditeur |
+| `{{To}}` | Identifiant de destination |
+| `{{MessageSid}}` | ID 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}}` | prompt média résolu 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}}` | indice de provider (whatsapp, telegram, discord, etc.) |
+
+---
+
+## Inclusions de configuration (`$include`)
+
+Divisez la configuration en plusieurs fichiers :
+
+```json5
+// ~/.openclaw/openclaw.json
+{
+ gateway: { port: 18789 },
+ agents: { $include: "./agents.json5" },
+ broadcast: {
+ $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
+ },
+}
+```
+
+**Comportement de fusion :**
+
+- Fichier unique : remplace l’objet contenant.
+- Tableau de fichiers : fusion profonde dans l’ordre (les derniers 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 niveau supérieur (`dirname` de `openclaw.json`). Les formes absolues/`../` sont autorisées uniquement si elles se résolvent toujours à l’intérieur de cette limite.
+- Erreurs : messages clairs pour les fichiers manquants, erreurs d’analyse et inclusions circulaires.
+
+---
+
+_Related: [Configuration](/fr/gateway/configuration) · [Configuration Examples](/fr/gateway/configuration-examples) · [Doctor](/fr/gateway/doctor)_
diff --git a/docs/fr/gateway/protocol.md b/docs/fr/gateway/protocol.md
index 1d3fa984e..f6080ad9f 100644
--- a/docs/fr/gateway/protocol.md
+++ b/docs/fr/gateway/protocol.md
@@ -1,34 +1,34 @@
---
read_when:
- - Implémentation ou mise à jour de clients WS de passerelle
- - Débogage des incompatibilités de protocole ou des échecs de connexion
- - Régénération du schéma/des modèles du protocole
-summary: 'Protocole WebSocket de la passerelle : handshake, trames, gestion des versions'
-title: Protocole de la passerelle
+ - Implémenter ou mettre à jour des clients WS de gateway
+ - Déboguer les incompatibilités de protocole ou les échecs de connexion
+ - Régénérer le schéma/les modèles du protocole
+summary: 'Protocole WebSocket Gateway : handshake, trames, gestion des versions'
+title: Protocole Gateway
x-i18n:
- generated_at: "2026-04-08T02:15:53Z"
+ generated_at: "2026-04-10T06:55:57Z"
model: gpt-5.4
provider: openai
- source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
+ source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f
source_path: gateway/protocol.md
workflow: 15
---
-# Protocole de la passerelle (WebSocket)
+# Protocole Gateway (WebSocket)
-Le protocole WS de la passerelle est le **plan de contrôle unique + transport de nœud** pour
+Le protocole WS Gateway est le **plan de contrôle unique + le transport de nœud** pour
OpenClaw. Tous les clients (CLI, interface web, app macOS, nœuds iOS/Android,
-nœuds sans interface) se connectent via WebSocket et déclarent leur **rôle** + **portée** au
-moment du handshake.
+nœuds headless) se connectent via WebSocket et déclarent leur **rôle** + leur **portée**
+au moment du handshake.
## Transport
-- WebSocket, trames texte avec charge utile JSON.
+- WebSocket, trames texte avec des payloads JSON.
- La première trame **doit** être une requête `connect`.
## Handshake (`connect`)
-Passerelle → Client (défi de pré-connexion) :
+Gateway → Client (défi pré-connexion) :
```json
{
@@ -38,7 +38,7 @@ Passerelle → Client (défi de pré-connexion) :
}
```
-Client → Passerelle :
+Client → Gateway :
```json
{
@@ -73,7 +73,7 @@ Client → Passerelle :
}
```
-Passerelle → Client :
+Gateway → Client :
```json
{
@@ -84,7 +84,7 @@ Passerelle → Client :
}
```
-Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
+Lorsqu’un token d’appareil est émis, `hello-ok` inclut également :
```json
{
@@ -96,7 +96,7 @@ Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
}
```
-Pendant un transfert d’amorçage approuvé, `hello-ok.auth` peut aussi inclure des
+Pendant le transfert de bootstrap approuvé, `hello-ok.auth` peut aussi inclure des
entrées de rôle supplémentaires bornées dans `deviceTokens` :
```json
@@ -116,12 +116,12 @@ entrées de rôle supplémentaires bornées dans `deviceTokens` :
}
```
-Pour le flux d’amorçage intégré nœud/opérateur, le jeton principal du nœud reste sur
-`scopes: []` et tout jeton opérateur transmis reste borné à la liste d’autorisation
-de l’opérateur d’amorçage (`operator.approvals`, `operator.read`,
-`operator.talk.secrets`, `operator.write`). Les vérifications de portée d’amorçage restent
-préfixées par rôle : les entrées opérateur satisfont uniquement les requêtes opérateur, et les rôles non opérateur
-ont toujours besoin de portées sous leur propre préfixe de rôle.
+Pour le flux de bootstrap intégré nœud/opérateur, le token principal du nœud reste avec
+`scopes: []` et tout token opérateur transmis reste borné à la liste d’autorisation de
+l’opérateur de bootstrap (`operator.approvals`, `operator.read`,
+`operator.talk.secrets`, `operator.write`). Les vérifications de portée de bootstrap restent
+préfixées par le rôle : les entrées opérateur ne satisfont que les requêtes opérateur, et les
+rôles non opérateur ont toujours besoin de portées sous leur propre préfixe de rôle.
### Exemple de nœud
@@ -158,7 +158,7 @@ ont toujours besoin de portées sous leur propre préfixe de rôle.
}
```
-## Format des trames
+## Encapsulation
- **Requête** : `{type:"req", id, method, params}`
- **Réponse** : `{type:"res", id, ok, payload|error}`
@@ -170,10 +170,10 @@ Les méthodes avec effets de bord nécessitent des **clés d’idempotence** (vo
### Rôles
-- `operator` = client du plan de contrôle (CLI/UI/automatisation).
+- `operator` = client de plan de contrôle (CLI/UI/automatisation).
- `node` = hôte de capacités (camera/screen/canvas/system.run).
-### Portées (opérateur)
+### Portées (`operator`)
Portées courantes :
@@ -187,293 +187,308 @@ Portées courantes :
`talk.config` avec `includeSecrets: true` nécessite `operator.talk.secrets`
(ou `operator.admin`).
-Les méthodes RPC de passerelle enregistrées par un plugin peuvent demander leur propre portée opérateur, mais
+Les méthodes RPC Gateway enregistrées par des plugins peuvent demander leur propre portée opérateur, mais
les préfixes d’administration cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) sont toujours résolus vers `operator.admin`.
La portée de méthode n’est que le premier filtre. Certaines commandes slash atteintes via
-`chat.send` appliquent des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes
-`/config set` et `/config unset` nécessitent `operator.admin`.
+`chat.send` appliquent des vérifications plus strictes au niveau de la commande en plus. Par
+exemple, les écritures persistantes `/config set` et `/config unset` nécessitent `operator.admin`.
-`node.pair.approve` a également une vérification de portée supplémentaire au moment de l’approbation en plus de la portée de méthode de base :
+`node.pair.approve` a également une vérification de portée supplémentaire au moment de l’approbation, en
+plus de la portée de méthode de base :
- requêtes sans commande : `operator.pairing`
-- requêtes avec des commandes de nœud autres que exec : `operator.pairing` + `operator.write`
+- requêtes avec des commandes de nœud hors exec : `operator.pairing` + `operator.write`
- requêtes qui incluent `system.run`, `system.run.prepare` ou `system.which` :
`operator.pairing` + `operator.admin`
-### `caps`/`commands`/`permissions` (nœud)
+### `caps`/`commands`/`permissions` (`node`)
-Les nœuds déclarent des revendications de capacité au moment de la connexion :
+Les nœuds déclarent des revendications de capacités au moment de la connexion :
- `caps` : catégories de capacités de haut niveau.
-- `commands` : liste d’autorisation de commandes pour l’invocation.
+- `commands` : liste d’autorisation des commandes pour `invoke`.
- `permissions` : bascules granulaires (par ex. `screen.record`, `camera.capture`).
-La passerelle les traite comme des **revendications** et applique les listes d’autorisation côté serveur.
+La Gateway traite celles-ci comme des **revendications** et applique des listes d’autorisation côté serveur.
## Présence
- `system-presence` renvoie des entrées indexées par identité d’appareil.
- Les entrées de présence incluent `deviceId`, `roles` et `scopes` afin que les interfaces puissent afficher une seule ligne par appareil
- même lorsqu’il se connecte à la fois comme **operator** et **node**.
+ même lorsqu’il se connecte à la fois comme **operator** et comme **node**.
-## Familles de méthodes RPC courantes
+## Familles courantes de méthodes RPC
Cette page n’est pas un dump complet généré, mais la surface WS publique est plus large
que les exemples de handshake/auth ci-dessus. Voici les principales familles de méthodes que la
-passerelle expose aujourd’hui.
+Gateway expose aujourd’hui.
`hello-ok.features.methods` est une liste de découverte conservatrice construite à partir de
-`src/gateway/server-methods-list.ts` plus les exports de méthodes de plugin/canal chargés.
-Traitez-la comme une découverte de fonctionnalités, et non comme un dump généré de tous les helpers appelables
+`src/gateway/server-methods-list.ts` plus les exports de méthodes de plugins/canaux chargés.
+Traitez-la comme un mécanisme de découverte de fonctionnalités, pas comme un dump généré de tous les helpers appelables
implémentés dans `src/gateway/server-methods/*.ts`.
### Système et identité
-- `health` renvoie l’instantané de santé de la passerelle mis en cache ou sondé fraîchement.
-- `status` renvoie le résumé de la passerelle de style `/status` ; les champs sensibles sont
+- `health` renvoie le snapshot d’état de santé de la gateway, en cache ou fraîchement sondé.
+- `status` renvoie le résumé de gateway au format `/status` ; les champs sensibles sont
inclus uniquement pour les clients opérateur avec portée admin.
-- `gateway.identity.get` renvoie l’identité d’appareil de la passerelle utilisée par les flux de relais et
- d’association.
-- `system-presence` renvoie l’instantané de présence actuel des appareils
- operator/node connectés.
+- `gateway.identity.get` renvoie l’identité d’appareil de la gateway utilisée par les flux de relais et
+ de pairing.
+- `system-presence` renvoie le snapshot de présence actuel pour les appareils
+ opérateur/nœud connectés.
- `system-event` ajoute un événement système et peut mettre à jour/diffuser le contexte
de présence.
-- `last-heartbeat` renvoie le dernier événement heartbeat persistant.
-- `set-heartbeats` active ou désactive le traitement des heartbeats sur la passerelle.
+- `last-heartbeat` renvoie le dernier événement heartbeat persisté.
+- `set-heartbeats` active ou désactive le traitement des heartbeats sur la gateway.
### Modèles et utilisation
-- `models.list` renvoie le catalogue de modèles autorisé à l’exécution.
-- `usage.status` renvoie les fenêtres d’utilisation fournisseur / résumés du quota restant.
-- `usage.cost` renvoie des résumés agrégés de coût d’utilisation pour une plage de dates.
+- `models.list` renvoie le catalogue des modèles autorisés à l’exécution.
+- `usage.status` renvoie des résumés des fenêtres d’utilisation des fournisseurs et du quota restant.
+- `usage.cost` renvoie des résumés agrégés des coûts d’utilisation pour une plage de dates.
- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour
l’espace de travail de l’agent par défaut actif.
- `sessions.usage` renvoie des résumés d’utilisation par session.
-- `sessions.usage.timeseries` renvoie des séries temporelles d’utilisation pour une session.
+- `sessions.usage.timeseries` renvoie une série temporelle d’utilisation pour une session.
- `sessions.usage.logs` renvoie les entrées du journal d’utilisation pour une session.
-### Canaux et helpers de connexion
+### Canaux et assistants de connexion
-- `channels.status` renvoie les résumés d’état des canaux/plugins intégrés + groupés.
+- `channels.status` renvoie des résumés d’état des canaux/plugins intégrés + fournis.
- `channels.logout` déconnecte un canal/compte spécifique là où le canal
prend en charge la déconnexion.
- `web.login.start` démarre un flux de connexion QR/web pour le fournisseur de canal web
actuel compatible QR.
-- `web.login.wait` attend que ce flux de connexion QR/web se termine et démarre le
+- `web.login.wait` attend la fin de ce flux de connexion QR/web et démarre le
canal en cas de succès.
- `push.test` envoie une notification push APNs de test à un nœud iOS enregistré.
- `voicewake.get` renvoie les déclencheurs de mot d’activation stockés.
-- `voicewake.set` met à jour les déclencheurs de mot d’activation et diffuse la modification.
+- `voicewake.set` met à jour les déclencheurs de mot d’activation et diffuse le changement.
### Messagerie et journaux
-- `send` est la RPC de livraison sortante directe pour les envois ciblés par canal/compte/fil
- hors du moteur de chat.
-- `logs.tail` renvoie la fin du journal de fichiers configuré de la passerelle avec contrôles de curseur/limite et
- de nombre maximal d’octets.
+- `send` est la RPC de livraison sortante directe pour les envois
+ ciblés par canal/compte/fil en dehors du moteur de chat.
+- `logs.tail` renvoie la fin du journal de fichiers configuré de la gateway avec des contrôles de curseur/limite et
+ d’octets maximum.
### Talk et TTS
-- `talk.config` renvoie la charge utile de configuration Talk effective ; `includeSecrets`
+- `talk.config` renvoie le payload de configuration Talk effectif ; `includeSecrets`
nécessite `operator.talk.secrets` (ou `operator.admin`).
-- `talk.mode` définit/diffuse l’état actuel du mode Talk pour les clients WebChat/Control UI.
+- `talk.mode` définit/diffuse l’état actuel du mode Talk pour les clients
+ WebChat/Control UI.
- `talk.speak` synthétise la parole via le fournisseur de parole Talk actif.
-- `tts.status` renvoie l’état d’activation TTS, le fournisseur actif, les fournisseurs de secours,
+- `tts.status` renvoie l’état d’activation de TTS, le fournisseur actif, les fournisseurs de repli,
et l’état de configuration du fournisseur.
-- `tts.providers` renvoie l’inventaire des fournisseurs TTS visibles.
-- `tts.enable` et `tts.disable` activent/désactivent l’état des préférences TTS.
+- `tts.providers` renvoie l’inventaire visible des fournisseurs TTS.
+- `tts.enable` et `tts.disable` activent ou désactivent l’état des préférences TTS.
- `tts.setProvider` met à jour le fournisseur TTS préféré.
-- `tts.convert` exécute une conversion ponctuelle de texte en parole.
+- `tts.convert` exécute une conversion texte-parole ponctuelle.
### Secrets, configuration, mise à jour et assistant
- `secrets.reload` résout à nouveau les SecretRefs actifs et remplace l’état des secrets à l’exécution
uniquement en cas de succès complet.
-- `secrets.resolve` résout les attributions de secrets ciblées par commande pour un ensemble commande/cible spécifique.
-- `config.get` renvoie l’instantané de configuration actuel et son hash.
-- `config.set` écrit une charge utile de configuration validée.
+- `secrets.resolve` résout les assignations de secrets ciblées par commande pour un ensemble spécifique
+ de commandes/cibles.
+- `config.get` renvoie le snapshot de configuration actuel et son hash.
+- `config.set` écrit un payload de configuration validé.
- `config.patch` fusionne une mise à jour partielle de configuration.
-- `config.apply` valide + remplace la charge utile complète de configuration.
-- `config.schema` renvoie la charge utile du schéma de configuration en direct utilisée par Control UI et
+- `config.apply` valide puis remplace le payload complet de configuration.
+- `config.schema` renvoie le payload du schéma de configuration live utilisé par Control UI et
les outils CLI : schéma, `uiHints`, version et métadonnées de génération, y compris
- les métadonnées de schéma des plugins + canaux lorsque le runtime peut les charger. Le schéma
+ les métadonnées de schéma de plugin + canal lorsque l’exécution peut les charger. Le schéma
inclut les métadonnées de champ `title` / `description` dérivées des mêmes libellés
- et textes d’aide utilisés par l’interface, y compris pour les branches imbriquées objet, joker, élément de tableau
- et composition `anyOf` / `oneOf` / `allOf` lorsqu’une documentation de champ correspondante
- existe.
-- `config.schema.lookup` renvoie une charge utile de recherche limitée à un chemin pour un chemin de configuration :
- chemin normalisé, nœud de schéma superficiel, hint correspondant + `hintPath`, et
+ et textes d’aide utilisés par l’UI, y compris pour les objets imbriqués, les jokers,
+ les éléments de tableau et les branches de composition `anyOf` / `oneOf` / `allOf` lorsque la
+ documentation de champ correspondante existe.
+- `config.schema.lookup` renvoie un payload de recherche limité à un chemin pour un chemin de configuration
+ : chemin normalisé, nœud de schéma superficiel, indice correspondant + `hintPath`, et
résumés immédiats des enfants pour l’exploration UI/CLI.
- - Les nœuds de schéma de recherche conservent la documentation destinée à l’utilisateur et les champs de validation courants :
+ - Les nœuds de schéma de recherche conservent la documentation orientée utilisateur et les champs de validation courants :
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
bornes numériques/chaînes/tableaux/objets, et indicateurs booléens comme
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
- - Les résumés enfants exposent `key`, le `path` normalisé, `type`, `required`,
- `hasChildren`, plus le `hint` / `hintPath` correspondant.
-- `update.run` exécute le flux de mise à jour de la passerelle et planifie un redémarrage uniquement lorsque
+ - Les résumés des enfants exposent `key`, le `path` normalisé, `type`, `required`,
+ `hasChildren`, ainsi que le `hint` / `hintPath` correspondant.
+- `update.run` exécute le flux de mise à jour de la gateway et planifie un redémarrage uniquement lorsque
la mise à jour elle-même a réussi.
- `wizard.start`, `wizard.next`, `wizard.status` et `wizard.cancel` exposent l’assistant
- d’onboarding via WS RPC.
+ d’onboarding via RPC WS.
-### Grandes familles existantes
+### Familles majeures existantes
-#### Helpers d’agent et d’espace de travail
+#### Assistants d’agent et d’espace de travail
- `agents.list` renvoie les entrées d’agent configurées.
- `agents.create`, `agents.update` et `agents.delete` gèrent les enregistrements d’agent et
- le câblage de l’espace de travail.
+ le raccordement de l’espace de travail.
- `agents.files.list`, `agents.files.get` et `agents.files.set` gèrent les
- fichiers d’espace de travail d’amorçage exposés pour un agent.
-- `agent.identity.get` renvoie l’identité effective de l’assistant pour un agent ou une
- session.
-- `agent.wait` attend qu’une exécution se termine et renvoie l’instantané terminal lorsqu’il est
+ fichiers de l’espace de travail de bootstrap exposés pour un agent.
+- `agent.identity.get` renvoie l’identité effective de l’assistant pour un agent ou
+ une session.
+- `agent.wait` attend la fin d’une exécution et renvoie le snapshot terminal lorsqu’il est
disponible.
#### Contrôle de session
- `sessions.list` renvoie l’index actuel des sessions.
-- `sessions.subscribe` et `sessions.unsubscribe` activent/désactivent les abonnements aux événements de changement de session
- pour le client WS actuel.
-- `sessions.messages.subscribe` et `sessions.messages.unsubscribe` activent/désactivent les
- abonnements aux événements de transcription/message pour une session.
-- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés de session spécifiques.
+- `sessions.subscribe` et `sessions.unsubscribe` activent ou désactivent les
+ abonnements aux événements de changement de session pour le client WS actuel.
+- `sessions.messages.subscribe` et `sessions.messages.unsubscribe` activent ou désactivent
+ les abonnements aux événements de transcription/message pour une session.
+- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés
+ de session spécifiques.
- `sessions.resolve` résout ou canonicalise une cible de session.
- `sessions.create` crée une nouvelle entrée de session.
- `sessions.send` envoie un message dans une session existante.
-- `sessions.steer` est la variante interrompre-et-réorienter pour une session active.
+- `sessions.steer` est la variante interruption-et-réorientation pour une session active.
- `sessions.abort` interrompt le travail actif pour une session.
- `sessions.patch` met à jour les métadonnées/remplacements de session.
- `sessions.reset`, `sessions.delete` et `sessions.compact` effectuent la
maintenance de session.
- `sessions.get` renvoie la ligne complète de session stockée.
-- l’exécution de chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
+- l’exécution du chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
`chat.inject`.
-- `chat.history` est normalisé pour l’affichage pour les clients UI : les balises de directive en ligne sont
- supprimées du texte visible, les charges utiles XML d’appel d’outil en texte brut (y compris
+- `chat.history` est normalisé pour l’affichage pour les clients UI : les balises de directive inline sont
+ supprimées du texte visible, les payloads XML d’appel d’outil en texte brut (y compris
`...`, `...`,
`...`, `...`, et
- les blocs d’appel d’outil tronqués) ainsi que les jetons de contrôle du modèle ASCII/pleine largeur divulgués
- sont supprimés, les lignes assistant composées uniquement de jetons silencieux telles que `NO_REPLY` /
- `no_reply` exact sont omises, et les lignes surdimensionnées peuvent être remplacées par des espaces réservés.
+ les blocs d’appel d’outil tronqués) ainsi que les jetons de contrôle de modèle ASCII/pleine largeur divulgués
+ sont supprimés, les lignes d’assistant ne contenant que des jetons silencieux, telles que `NO_REPLY` /
+ `no_reply` exacts, sont omises, et les lignes surdimensionnées peuvent être remplacées par des placeholders.
-#### Association d’appareil et jetons d’appareil
+#### Pairing d’appareils et tokens d’appareil
-- `device.pair.list` renvoie les appareils associés en attente et approuvés.
-- `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent
- les enregistrements d’association d’appareil.
-- `device.token.rotate` fait pivoter un jeton d’appareil associé dans les limites de rôle
- et de portée approuvées.
-- `device.token.revoke` révoque un jeton d’appareil associé.
+- `device.pair.list` renvoie les appareils pairés en attente et approuvés.
+- `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent les
+ enregistrements de pairing d’appareil.
+- `device.token.rotate` fait tourner un token d’appareil pairé dans les limites de son rôle
+ et de ses portées approuvés.
+- `device.token.revoke` révoque un token d’appareil pairé.
-#### Association de nœud, invocation et travail en attente
+#### Pairing de nœud, `invoke` et travail en attente
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
- `node.pair.reject` et `node.pair.verify` couvrent l’association de nœud et la
- vérification d’amorçage.
+ `node.pair.reject` et `node.pair.verify` couvrent le pairing de nœud et la
+ vérification du bootstrap.
- `node.list` et `node.describe` renvoient l’état des nœuds connus/connectés.
-- `node.rename` met à jour un libellé de nœud associé.
+- `node.rename` met à jour un libellé de nœud pairé.
- `node.invoke` transmet une commande à un nœud connecté.
-- `node.invoke.result` renvoie le résultat d’une requête d’invocation.
-- `node.event` transporte des événements provenant d’un nœud vers la passerelle.
-- `node.canvas.capability.refresh` rafraîchit les jetons de capacité canvas à portée limitée.
-- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente pour nœuds connectés.
-- `node.pending.enqueue` et `node.pending.drain` gèrent le travail en attente durable
+- `node.invoke.result` renvoie le résultat d’une requête `invoke`.
+- `node.event` transporte les événements d’origine nœud de retour vers la gateway.
+- `node.canvas.capability.refresh` rafraîchit les tokens de capacité canvas à portée limitée.
+- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente des nœuds connectés.
+- `node.pending.enqueue` et `node.pending.drain` gèrent le travail durable en attente
pour les nœuds hors ligne/déconnectés.
#### Familles d’approbation
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` et
- `exec.approval.resolve` couvrent les demandes ponctuelles d’approbation exec ainsi que la
+ `exec.approval.resolve` couvrent les requêtes d’approbation exec ponctuelles ainsi que la
recherche/relecture des approbations en attente.
- `exec.approval.waitDecision` attend une approbation exec en attente et renvoie
- la décision finale (ou `null` en cas de dépassement de délai).
-- `exec.approvals.get` et `exec.approvals.set` gèrent les instantanés de politique
- d’approbation exec de la passerelle.
-- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale exec
- du nœud via des commandes relais de nœud.
+ la décision finale (ou `null` en cas de délai d’attente).
+- `exec.approvals.get` et `exec.approvals.set` gèrent les snapshots de politique
+ d’approbation exec de la gateway.
+- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale de
+ d’approbation exec du nœud via des commandes de relais de nœud.
- `plugin.approval.request`, `plugin.approval.list`,
`plugin.approval.waitDecision` et `plugin.approval.resolve` couvrent
- les flux d’approbation définis par plugin.
+ les flux d’approbation définis par les plugins.
-#### Autres grandes familles
+#### Autres familles majeures
- automatisation :
- - `wake` planifie une injection immédiate ou au prochain heartbeat d’un texte de réveil
+ - `wake` planifie une injection de texte de réveil immédiate ou au prochain heartbeat
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
`cron.run`, `cron.runs`
-- skills/outils : `skills.*`, `tools.catalog`, `tools.effective`
+- Skills/outils : `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
### Familles d’événements courantes
- `chat` : mises à jour de chat UI telles que `chat.inject` et autres événements
- de chat uniquement liés à la transcription.
+ de chat limités à la transcription.
- `session.message` et `session.tool` : mises à jour de transcription/flux d’événements pour une
session abonnée.
- `sessions.changed` : l’index de session ou les métadonnées ont changé.
-- `presence` : mises à jour de l’instantané de présence système.
-- `tick` : événement périodique de keepalive / vivacité.
-- `health` : mise à jour de l’instantané de santé de la passerelle.
+- `presence` : mises à jour du snapshot de présence du système.
+- `tick` : événement périodique de keepalive / vitalité.
+- `health` : mise à jour du snapshot de santé de la gateway.
- `heartbeat` : mise à jour du flux d’événements heartbeat.
-- `cron` : événement de changement d’exécution/tâche cron.
-- `shutdown` : notification d’arrêt de la passerelle.
-- `node.pair.requested` / `node.pair.resolved` : cycle de vie de l’association de nœud.
+- `cron` : événement de changement d’exécution/de tâche cron.
+- `shutdown` : notification d’arrêt de la gateway.
+- `node.pair.requested` / `node.pair.resolved` : cycle de vie du pairing de nœud.
- `node.invoke.request` : diffusion de requête d’invocation de nœud.
-- `device.pair.requested` / `device.pair.resolved` : cycle de vie des appareils associés.
-- `voicewake.changed` : modification de la configuration des déclencheurs de mot d’activation.
-- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie
- d’approbation exec.
-- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie d’approbation
- de plugin.
+- `device.pair.requested` / `device.pair.resolved` : cycle de vie des appareils pairés.
+- `voicewake.changed` : la configuration des déclencheurs de mot d’activation a changé.
+- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie de
+ l’approbation exec.
+- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie de
+ l’approbation de plugin.
-### Méthodes helper pour les nœuds
+### Méthodes utilitaires de nœud
-- Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables
- de skill pour les vérifications d’auto-autorisation.
+- Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables de skill
+ pour les vérifications d’auto-autorisation.
-### Méthodes helper pour les opérateurs
+### Méthodes utilitaires d’opérateur
+- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire des commandes à l’exécution pour un agent.
+ - `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
+ - `scope` contrôle quelle surface la valeur `name` principale cible :
+ - `text` renvoie le jeton principal de commande texte sans le `/` initial
+ - `native` et le chemin par défaut `both` renvoient des noms natifs adaptés au fournisseur
+ lorsqu’ils sont disponibles
+ - `textAliases` contient des alias slash exacts tels que `/model` et `/m`.
+ - `nativeName` contient le nom de commande natif adapté au fournisseur lorsqu’il existe.
+ - `provider` est facultatif et n’affecte que le nommage natif ainsi que la disponibilité
+ des commandes natives de plugin.
+ - `includeArgs=false` omet les métadonnées d’arguments sérialisées de la réponse.
- Les opérateurs peuvent appeler `tools.catalog` (`operator.read`) pour récupérer le catalogue d’outils à l’exécution pour un
- agent. La réponse inclut des outils groupés et des métadonnées de provenance :
+ agent. La réponse inclut les outils groupés et les métadonnées de provenance :
- `source` : `core` ou `plugin`
- `pluginId` : propriétaire du plugin lorsque `source="plugin"`
- - `optional` : indique si un outil de plugin est optionnel
-- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire effectif des outils à l’exécution
+ - `optional` : si un outil de plugin est facultatif
+- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire d’outils effectivement actif à l’exécution
pour une session.
- `sessionKey` est requis.
- - La passerelle dérive le contexte d’exécution de confiance côté serveur à partir de la session au lieu d’accepter
+ - La gateway dérive le contexte d’exécution fiable côté serveur à partir de la session au lieu d’accepter
un contexte d’authentification ou de livraison fourni par l’appelant.
- - La réponse est limitée à la session et reflète ce que la conversation active peut utiliser immédiatement,
- y compris les outils cœur, plugin et canal.
-- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire
- visible des skills pour un agent.
- - `agentId` est optionnel ; omettez-le pour lire l’espace de travail de l’agent par défaut.
+ - La réponse est limitée à la session et reflète ce que la conversation active peut utiliser maintenant,
+ y compris les outils core, plugin et de canal.
+- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire visible des
+ Skills pour un agent.
+ - `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
- La réponse inclut l’éligibilité, les exigences manquantes, les vérifications de configuration et
- les options d’installation nettoyées sans exposer les valeurs brutes des secrets.
-- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour
- les métadonnées de découverte ClawHub.
+ les options d’installation nettoyées sans exposer les valeurs secrètes brutes.
+- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour les métadonnées
+ de découverte ClawHub.
- Les opérateurs peuvent appeler `skills.install` (`operator.admin`) dans deux modes :
- - mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
+ - Mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
dossier de skill dans le répertoire `skills/` de l’espace de travail de l’agent par défaut.
- - mode installateur de passerelle : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
- exécute une action `metadata.openclaw.install` déclarée sur l’hôte de la passerelle.
+ - Mode installateur Gateway : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
+ exécute une action déclarée `metadata.openclaw.install` sur l’hôte gateway.
- Les opérateurs peuvent appeler `skills.update` (`operator.admin`) dans deux modes :
- - le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
+ - Le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
l’espace de travail de l’agent par défaut.
- - le mode config modifie les valeurs `skills.entries.` telles que `enabled`,
+ - Le mode configuration patche les valeurs `skills.entries.` telles que `enabled`,
`apiKey` et `env`.
## Approbations exec
-- Lorsqu’une requête exec nécessite une approbation, la passerelle diffuse `exec.approval.requested`.
+- Lorsqu’une requête exec nécessite une approbation, la gateway diffuse `exec.approval.requested`.
- Les clients opérateur résolvent cela en appelant `exec.approval.resolve` (nécessite la portée `operator.approvals`).
- Pour `host=node`, `exec.approval.request` doit inclure `systemRunPlan` (`argv`/`cwd`/`rawCommand`/métadonnées de session canoniques). Les requêtes sans `systemRunPlan` sont rejetées.
-- Après approbation, les appels transmis `node.invoke system.run` réutilisent ce
- `systemRunPlan` canonique comme contexte faisant autorité pour la commande/le cwd/la session.
+- Après l’approbation, les appels `node.invoke system.run` transmis réutilisent ce
+ `systemRunPlan` canonique comme contexte autoritaire de commande/cwd/session.
- Si un appelant modifie `command`, `rawCommand`, `cwd`, `agentId` ou
- `sessionKey` entre la préparation et le transfert final approuvé de `system.run`, la
- passerelle rejette l’exécution au lieu de faire confiance à la charge utile modifiée.
+ `sessionKey` entre `prepare` et la transmission finale approuvée de `system.run`, la
+ gateway rejette l’exécution au lieu de faire confiance au payload modifié.
## Repli de livraison d’agent
@@ -485,108 +500,108 @@ implémentés dans `src/gateway/server-methods/*.ts`.
- `PROTOCOL_VERSION` se trouve dans `src/gateway/protocol/schema.ts`.
- Les clients envoient `minProtocol` + `maxProtocol` ; le serveur rejette les incompatibilités.
-- Les schémas + modèles sont générés à partir des définitions TypeBox :
+- Les schémas + modèles sont générés à partir de définitions TypeBox :
- `pnpm protocol:gen`
- `pnpm protocol:gen:swift`
- `pnpm protocol:check`
-## Auth
+## Authentification
-- L’authentification de passerelle par secret partagé utilise `connect.params.auth.token` ou
+- L’authentification gateway par secret partagé utilise `connect.params.auth.token` ou
`connect.params.auth.password`, selon le mode d’authentification configuré.
-- Les modes porteurs d’identité comme Tailscale Serve
- (`gateway.auth.allowTailscale: true`) ou le mode non-loopback
- `gateway.auth.mode: "trusted-proxy"` satisfont la vérification d’authentification de connexion à partir des
- en-têtes de requête au lieu de `connect.params.auth.*`.
-- Le mode d’entrée privée `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une entrée publique/non fiable.
-- Après l’association, la passerelle émet un **jeton d’appareil** limité au
- rôle + portées de la connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
+- Les modes porteurs d’identité tels que Tailscale Serve
+ (`gateway.auth.allowTailscale: true`) ou
+ `gateway.auth.mode: "trusted-proxy"` hors loopback satisfont la vérification d’authentification de connexion à partir
+ des en-têtes de requête au lieu de `connect.params.auth.*`.
+- Le mode d’entrée privée `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ;
+ n’exposez pas ce mode sur une entrée publique/non fiable.
+- Après le pairing, la Gateway émet un **token d’appareil** limité au rôle + aux portées
+ de la connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
persisté par le client pour les connexions futures.
- Les clients doivent persister le `hello-ok.auth.deviceToken` principal après toute
connexion réussie.
-- Une reconnexion avec ce jeton d’appareil **stocké** doit également réutiliser l’ensemble de portées approuvées stocké
- pour ce jeton. Cela préserve l’accès déjà accordé en lecture/sondage/état
- et évite que les reconnexions ne se réduisent silencieusement à une
- portée implicite plus étroite limitée à l’administration.
-- L’ordre de priorité normal de l’authentification de connexion est le suivant : jeton/mot de passe partagé explicite d’abord, puis
- `deviceToken` explicite, puis jeton stocké par appareil, puis jeton d’amorçage.
-- Les entrées supplémentaires `hello-ok.auth.deviceTokens` sont des jetons de transfert d’amorçage.
- Ne les persistez que lorsque la connexion a utilisé une authentification d’amorçage sur un transport de confiance
- tel que `wss://` ou loopback/association locale.
+- La reconnexion avec ce token d’appareil **stocké** doit également réutiliser l’ensemble de portées approuvées
+ stocké pour ce token. Cela préserve l’accès lecture/sonde/statut qui avait déjà été
+ accordé et évite de réduire silencieusement les reconnexions à une
+ portée implicite plus étroite réservée à l’admin.
+- L’ordre de priorité normal de l’authentification de connexion est d’abord le token/mot de passe partagé explicite, puis
+ le `deviceToken` explicite, puis le token par appareil stocké, puis le token de bootstrap.
+- Les entrées supplémentaires `hello-ok.auth.deviceTokens` sont des tokens de transfert de bootstrap.
+ Persistez-les uniquement lorsque la connexion a utilisé l’authentification bootstrap sur un transport fiable
+ tel que `wss://` ou loopback/pairing local.
- Si un client fournit un `deviceToken` **explicite** ou des `scopes` explicites, cet
- ensemble de portées demandé par l’appelant reste prioritaire ; les portées mises en cache ne sont réutilisées que
- lorsque le client réutilise le jeton stocké par appareil.
-- Les jetons d’appareil peuvent être tournés/révoqués via `device.token.rotate` et
+ ensemble de portées demandé par l’appelant reste autoritaire ; les portées en cache ne sont réutilisées que lorsque le client réutilise le token par appareil stocké.
+- Les tokens d’appareil peuvent être tournés/révoqués via `device.token.rotate` et
`device.token.revoke` (nécessite la portée `operator.pairing`).
-- L’émission/la rotation de jeton reste bornée à l’ensemble des rôles approuvés enregistré dans
- l’entrée d’association de cet appareil ; faire pivoter un jeton ne peut pas élargir l’appareil à un
- rôle que l’approbation d’association n’a jamais accordé.
-- Pour les sessions de jeton d’appareil associé, la gestion des appareils est limitée à soi-même sauf si
- l’appelant possède également `operator.admin` : les appelants non admin peuvent supprimer/révoquer/faire pivoter uniquement
- leur **propre** entrée d’appareil.
+- L’émission/la rotation de token reste limitée à l’ensemble de rôles approuvés enregistré dans
+ l’entrée de pairing de cet appareil ; la rotation d’un token ne peut pas étendre l’appareil à un
+ rôle que l’approbation de pairing n’a jamais accordé.
+- Pour les sessions de token d’appareil pairé, la gestion des appareils est limitée à soi-même sauf si l’appelant
+ possède aussi `operator.admin` : les appelants non admin ne peuvent supprimer/révoquer/faire tourner
+ que leur **propre** entrée d’appareil.
- `device.token.rotate` vérifie également l’ensemble de portées opérateur demandé par rapport aux
- portées de la session actuelle de l’appelant. Les appelants non admin ne peuvent pas faire pivoter un jeton vers
- un ensemble de portées opérateur plus large que celui qu’ils possèdent déjà.
-- Les échecs d’authentification incluent `error.details.code` ainsi que des indices de récupération :
+ portées actuelles de session de l’appelant. Les appelants non admin ne peuvent pas faire tourner un token vers
+ un ensemble de portées opérateur plus large que celui qu’ils détiennent déjà.
+- Les échecs d’authentification incluent `error.details.code` ainsi que des indications de récupération :
- `error.details.canRetryWithDeviceToken` (booléen)
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
- Comportement client pour `AUTH_TOKEN_MISMATCH` :
- - Les clients de confiance peuvent tenter une reprise bornée avec un jeton mis en cache par appareil.
- - Si cette reprise échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des indications d’action à l’opérateur.
+ - Les clients de confiance peuvent tenter une unique nouvelle tentative bornée avec un token par appareil en cache.
+ - Si cette nouvelle tentative échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des instructions d’action à l’opérateur.
-## Identité d’appareil + association
+## Identité d’appareil + pairing
- Les nœuds doivent inclure une identité d’appareil stable (`device.id`) dérivée de l’empreinte d’une
paire de clés.
-- Les passerelles émettent des jetons par appareil + rôle.
-- Des approbations d’association sont requises pour les nouveaux IDs d’appareil sauf si
- l’approbation automatique locale est activée.
-- L’approbation automatique d’association est centrée sur les connexions directes locales loopback.
-- OpenClaw dispose également d’un chemin restreint d’auto-connexion backend/conteneur-local pour
- des flux helper de secret partagé de confiance.
-- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’association et
+- Les gateways émettent des tokens par appareil + rôle.
+- Les approbations de pairing sont requises pour les nouveaux IDs d’appareil, sauf si
+ l’auto-approbation locale est activée.
+- L’auto-approbation de pairing est centrée sur les connexions directes de local loopback.
+- OpenClaw dispose également d’un chemin étroit d’auto-connexion backend/local au conteneur pour
+ des flux d’assistant de secret partagé approuvés.
+- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour le pairing et
nécessitent une approbation.
- Tous les clients WS doivent inclure l’identité `device` pendant `connect` (operator + node).
- Control UI peut l’omettre uniquement dans les modes suivants :
- - `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost uniquement.
+ Control UI ne peut l’omettre que dans ces modes :
+ - `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost-only.
- authentification opérateur Control UI réussie avec `gateway.auth.mode: "trusted-proxy"`.
- - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (mode de dernier recours, forte dégradation de sécurité).
-- Toutes les connexions doivent signer le nonce fourni par le serveur dans `connect.challenge`.
+ - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (bris de glace, grave dégradation de sécurité).
+- Toutes les connexions doivent signer le nonce `connect.challenge` fourni par le serveur.
### Diagnostics de migration de l’authentification d’appareil
-Pour les clients hérités qui utilisent encore le comportement de signature antérieur au défi, `connect` renvoie désormais
-des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec une valeur stable `error.details.reason`.
+Pour les clients hérités qui utilisent encore le comportement de signature antérieur au challenge, `connect` renvoie désormais
+des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec une valeur stable dans `error.details.reason`.
-Échecs de migration courants :
+Échecs courants de migration :
-| Message | details.code | details.reason | Signification |
-| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
-| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Le client a omis `device.nonce` (ou a envoyé une valeur vide). |
-| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Le client a signé avec un nonce obsolète/incorrect. |
-| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La charge utile de signature ne correspond pas à la charge utile v2. |
-| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est en dehors du décalage autorisé. |
+| Message | details.code | details.reason | Signification |
+| --------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- |
+| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Le client a omis `device.nonce` (ou l’a envoyé vide). |
+| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Le client a signé avec un nonce périmé/incorrect. |
+| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Le payload de signature ne correspond pas au payload v2. |
+| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est hors du décalage autorisé. |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` ne correspond pas à l’empreinte de la clé publique. |
-| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Le format/canonicalisation de la clé publique a échoué. |
+| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Le format / la canonicalisation de la clé publique a échoué. |
Cible de migration :
- Toujours attendre `connect.challenge`.
-- Signer la charge utile v2 qui inclut le nonce du serveur.
+- Signer le payload v2 qui inclut le nonce du serveur.
- Envoyer le même nonce dans `connect.params.device.nonce`.
-- La charge utile de signature préférée est `v3`, qui lie `platform` et `deviceFamily`
- en plus des champs device/client/role/scopes/token/nonce.
+- Le payload de signature préféré est `v3`, qui lie `platform` et `deviceFamily`
+ en plus des champs appareil/client/rôle/portées/token/nonce.
- Les signatures héritées `v2` restent acceptées pour compatibilité, mais l’épinglage des métadonnées
- des appareils associés continue de contrôler la politique de commande lors de la reconnexion.
+ d’appareil pairé contrôle toujours la politique de commande lors de la reconnexion.
## TLS + épinglage
- TLS est pris en charge pour les connexions WS.
-- Les clients peuvent éventuellement épingler l’empreinte du certificat de la passerelle (voir la configuration `gateway.tls`
- ainsi que `gateway.remote.tlsFingerprint` ou le CLI `--tls-fingerprint`).
+- Les clients peuvent éventuellement épingler l’empreinte du certificat gateway (voir la configuration `gateway.tls`
+ ainsi que `gateway.remote.tlsFingerprint` ou la CLI `--tls-fingerprint`).
## Portée
-Ce protocole expose l’**API complète de la passerelle** (état, canaux, modèles, chat,
+Ce protocole expose l’**API gateway complète** (état, canaux, modèles, chat,
agent, sessions, nœuds, approbations, etc.). La surface exacte est définie par les
schémas TypeBox dans `src/gateway/protocol/schema.ts`.
diff --git a/docs/fr/help/testing.md b/docs/fr/help/testing.md
index 051242e5f..357e55028 100644
--- a/docs/fr/help/testing.md
+++ b/docs/fr/help/testing.md
@@ -1,289 +1,311 @@
---
read_when:
- - Exécuter des tests localement ou en CI
- - Ajouter des régressions pour des bugs de modèle/fournisseur
- - Déboguer le comportement de la passerelle et de l'agent
-summary: 'Kit de test : suites unitaires/e2e/live, exécuteurs Docker et ce que couvre chaque test'
+ - Exécuter les tests en local ou dans la CI
+ - Ajouter des tests de régression pour les bugs de modèle/fournisseur
+ - Déboguer le comportement de la passerelle + de l’agent
+summary: 'Kit de test : suites unitaires/e2e/live, exécuteurs Docker, et ce que couvre chaque test'
title: Tests
x-i18n:
- generated_at: "2026-04-09T01:30:28Z"
+ generated_at: "2026-04-10T06:55:55Z"
model: gpt-5.4
provider: openai
- source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b
+ source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4
source_path: help/testing.md
workflow: 15
---
# Tests
-OpenClaw dispose de trois suites Vitest (unit/integration, e2e, live) et d'un petit ensemble d'exécuteurs Docker.
+OpenClaw dispose de trois suites Vitest (unités/intégration, e2e, live) et d’un petit ensemble d’exécuteurs Docker.
-Ce document est un guide « comment nous testons » :
+Cette documentation est un guide « comment nous testons » :
-- Ce que couvre chaque suite (et ce qu'elle ne couvre délibérément _pas_)
+- Ce que couvre chaque suite (et ce qu’elle ne couvre délibérément _pas_)
- Quelles commandes exécuter pour les workflows courants (local, avant push, débogage)
- Comment les tests live découvrent les identifiants et sélectionnent les modèles/fournisseurs
- Comment ajouter des régressions pour des problèmes réels de modèle/fournisseur
## Démarrage rapide
-La plupart des jours :
+La plupart du temps :
-- Barrière complète (attendue avant push) : `pnpm build && pnpm check && pnpm test`
-- Exécution plus rapide de la suite complète en local sur une machine confortable : `pnpm test:max`
-- Boucle watch Vitest directe : `pnpm test:watch`
-- Le ciblage direct de fichier route désormais aussi les chemins d'extension/canal : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
-- Site QA avec support Docker : `pnpm qa:lab:up`
+- Vérification complète (attendue avant un push) : `pnpm build && pnpm check && pnpm test`
+- Exécution locale plus rapide de la suite complète sur une machine bien dimensionnée : `pnpm test:max`
+- Boucle de surveillance Vitest directe : `pnpm test:watch`
+- Le ciblage direct de fichiers route désormais aussi les chemins d’extension/canal : `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- Préférez d’abord les exécutions ciblées lorsque vous itérez sur un seul échec.
+- Site QA adossé à Docker : `pnpm qa:lab:up`
+- Voie QA adossée à une VM Linux : `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
-Quand vous modifiez des tests ou souhaitez davantage de confiance :
+Lorsque vous modifiez des tests ou souhaitez plus de confiance :
-- Barrière de couverture : `pnpm test:coverage`
-- Suite E2E : `pnpm test:e2e`
+- Vérification de couverture : `pnpm test:coverage`
+- Suite E2E : `pnpm test:e2e`
-Lors du débogage de vrais fournisseurs/modèles (nécessite de vrais identifiants) :
+Lors du débogage de vrais fournisseurs/modèles (nécessite de vrais identifiants) :
-- Suite live (modèles + sondes d'outil/image de passerelle) : `pnpm test:live`
-- Cibler silencieusement un fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts`
+- Suite live (modèles + sondes d’outils/images de la passerelle) : `pnpm test:live`
+- Cibler silencieusement un seul fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts`
-Conseil : quand vous n'avez besoin que d'un seul cas en échec, préférez restreindre les tests live via les variables d'environnement de liste d'autorisation décrites ci-dessous.
+Astuce : lorsque vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous.
-## Suites de test (ce qui s'exécute où)
+## Exécuteurs spécifiques à la QA
-Considérez les suites comme « réalisme croissant » (et fragilité/coût croissants) :
+Ces commandes se trouvent à côté des suites de test principales lorsque vous avez besoin du réalisme de qa-lab :
-### Unit / integration (par défaut)
+- `pnpm openclaw qa suite`
+ - Exécute directement sur l’hôte des scénarios QA adossés au dépôt.
+- `pnpm openclaw qa suite --runner multipass`
+ - Exécute la même suite QA dans une VM Linux Multipass jetable.
+ - Conserve le même comportement de sélection de scénario que `qa suite` sur l’hôte.
+ - Réutilise les mêmes drapeaux de sélection de fournisseur/modèle que `qa suite`.
+ - Les exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour l’invité :
+ les clés de fournisseur basées sur l’environnement, le chemin de configuration du fournisseur live QA, et `CODEX_HOME`
+ lorsqu’il est présent.
+ - Les répertoires de sortie doivent rester sous la racine du dépôt afin que l’invité puisse réécrire à travers
+ l’espace de travail monté.
+ - Écrit le rapport et le résumé QA normaux ainsi que les journaux Multipass dans
+ `.artifacts/qa-e2e/...`.
+- `pnpm qa:lab:up`
+ - Démarre le site QA adossé à Docker pour un travail QA de type opérateur.
-- Commande : `pnpm test`
-- Config : dix exécutions séquentielles de fragments (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants
-- Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, et les tests node `ui` autorisés couverts par `vitest.unit.config.ts`
-- Portée :
+## Suites de test (ce qui s’exécute où)
+
+Considérez les suites comme ayant un « réalisme croissant » (et une instabilité/un coût croissants) :
+
+### Unité / intégration (par défaut)
+
+- Commande : `pnpm test`
+- Config : dix exécutions séquentielles par fragment (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants
+- Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, et les tests Node `ui` autorisés couverts par `vitest.unit.config.ts`
+- Portée :
- Tests unitaires purs
- - Tests d'intégration en processus (authentification de la passerelle, routage, outils, analyse, configuration)
- - Régressions déterministes pour des bugs connus
-- Attentes :
- - S'exécute en CI
+ - Tests d’intégration en processus (authentification de la passerelle, routage, outillage, parsing, configuration)
+ - Régressions déterministes pour les bogues connus
+- Attentes :
+ - S’exécute en CI
- Aucune vraie clé requise
- Doit être rapide et stable
-- Note sur les projets :
- - `pnpm test` sans ciblage exécute désormais onze configurations fragmentées plus petites (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d'un seul processus racine natif géant. Cela réduit le RSS maximal sur les machines chargées et évite que le travail `auto-reply`/extensions n'affame les suites sans rapport.
- - `pnpm test --watch` utilise toujours le graphe de projet racine natif `vitest.config.ts`, parce qu'une boucle watch multi-fragments n'est pas pratique.
- - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` routent d'abord les cibles explicites de fichier/répertoire via des voies ciblées, donc `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite de payer le coût de démarrage complet du projet racine.
- - `pnpm test:changed` développe les chemins git modifiés vers ces mêmes voies ciblées quand le diff ne touche que des fichiers source/test routables ; les modifications de config/setup reviennent toujours à la relance large du projet racine.
- - Certains tests `plugin-sdk` et `commands` passent aussi par des voies légères dédiées qui ignorent `test/setup-openclaw-runtime.ts` ; les fichiers avec état/lourds à l'exécution restent sur les voies existantes.
- - Certains fichiers source utilitaires `plugin-sdk` et `commands` associent aussi les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications d'utilitaires évitent de relancer toute la suite lourde du répertoire.
- - `auto-reply` dispose maintenant de trois compartiments dédiés : utilitaires core de premier niveau, tests d'intégration `reply.*` de premier niveau, et sous-arborescence `src/auto-reply/reply/**`. Cela garde le travail de harness reply le plus lourd hors des tests bon marché de statut/chunk/token.
-- Note sur l'exécuteur embarqué :
- - Lorsque vous modifiez les entrées de découverte d'outils de message ou le contexte d'exécution de compaction,
+- Remarque sur les projets :
+ - `pnpm test` sans ciblage exécute désormais onze petites configurations fragmentées (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) au lieu d’un seul énorme processus root-project natif. Cela réduit le pic de RSS sur les machines chargées et évite que le travail auto-reply/extension n’affame les suites non liées.
+ - `pnpm test --watch` utilise toujours le graphe de projets natif de `vitest.config.ts`, car une boucle de surveillance multi-fragments n’est pas pratique.
+ - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` routent d’abord les cibles explicites de fichier/répertoire à travers des voies ciblées, afin que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite le coût de démarrage complet du projet racine.
+ - `pnpm test:changed` développe les chemins Git modifiés dans les mêmes voies ciblées lorsque le diff ne touche que des fichiers source/test routables ; les modifications de configuration/setup reviennent toujours à une réexécution large du projet racine.
+ - Certains tests `plugin-sdk` et `commands` sont aussi routés via des voies légères dédiées qui ignorent `test/setup-openclaw-runtime.ts` ; les fichiers avec état ou lourds à l’exécution restent sur les voies existantes.
+ - Certains fichiers source d’aide `plugin-sdk` et `commands` mappent aussi les exécutions en mode changed vers des tests frères explicites dans ces voies légères, afin que les modifications d’aides évitent de relancer toute la suite lourde de ce répertoire.
+ - `auto-reply` dispose désormais de trois compartiments dédiés : aides core de haut niveau, tests d’intégration `reply.*` de haut niveau, et le sous-arbre `src/auto-reply/reply/**`. Cela garde le travail du harnais de réponse le plus lourd hors des tests économiques de statut/fragment/token.
+- Remarque sur l’exécuteur embarqué :
+ - Lorsque vous modifiez les entrées de découverte des outils de message ou le contexte d’exécution de compaction,
conservez les deux niveaux de couverture.
- - Ajoutez des régressions d'utilitaire ciblées pour les frontières pures de routage/normalisation.
- - Maintenez également en bon état les suites d'intégration de l'exécuteur embarqué :
+ - Ajoutez des régressions d’aide ciblées pour les limites pures de routage/normalisation.
+ - Gardez également saines les suites d’intégration de l’exécuteur embarqué :
`src/agents/pi-embedded-runner/compact.hooks.test.ts`,
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, et
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`.
- - Ces suites vérifient que les identifiants ciblés et le comportement de compaction passent toujours
- par les vrais chemins `run.ts` / `compact.ts` ; les tests uniquement utilitaires ne sont pas un
- substitut suffisant à ces chemins d'intégration.
-- Note sur le pool :
- - La configuration de base Vitest utilise désormais `threads` par défaut.
- - La configuration Vitest partagée fixe également `isolate: false` et utilise l'exécuteur non isolé sur les projets racine, les configs e2e et live.
- - La voie UI racine conserve sa configuration et son optimiseur `jsdom`, mais s'exécute maintenant aussi sur l'exécuteur partagé non isolé.
+ - Ces suites vérifient que les identifiants ciblés et le comportement de compaction continuent de transiter
+ par les vrais chemins `run.ts` / `compact.ts` ; les tests d’aide seuls ne constituent pas un substitut
+ suffisant à ces chemins d’intégration.
+- Remarque sur le pool :
+ - La configuration Vitest de base utilise désormais `threads` par défaut.
+ - La configuration Vitest partagée fixe aussi `isolate: false` et utilise l’exécuteur non isolé sur les projets root, e2e et live.
+ - La voie UI racine conserve sa configuration `jsdom` et son optimiseur, mais s’exécute maintenant aussi sur l’exécuteur partagé non isolé.
- Chaque fragment `pnpm test` hérite des mêmes valeurs par défaut `threads` + `isolate: false` depuis la configuration Vitest partagée.
- - Le lanceur partagé `scripts/run-vitest.mjs` ajoute désormais aussi `--no-maglev` par défaut pour les processus Node enfants de Vitest afin de réduire le churn de compilation V8 lors des grosses exécutions locales. Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si vous devez comparer avec le comportement V8 standard.
-- Note sur l'itération rapide locale :
+ - Le lanceur partagé `scripts/run-vitest.mjs` ajoute désormais aussi `--no-maglev` par défaut aux processus Node enfants de Vitest afin de réduire l’activité de compilation V8 lors des grandes exécutions locales. Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si vous devez comparer avec le comportement V8 standard.
+- Remarque sur l’itération locale rapide :
- `pnpm test:changed` passe par des voies ciblées lorsque les chemins modifiés correspondent clairement à une suite plus petite.
- `pnpm test:max` et `pnpm test:changed:max` conservent le même comportement de routage, simplement avec une limite de workers plus élevée.
- - L'auto-adaptation locale des workers est désormais volontairement conservatrice et recule aussi lorsque la charge moyenne de l'hôte est déjà élevée, de sorte que plusieurs exécutions Vitest concurrentes causent moins de dégâts par défaut.
- - La configuration de base Vitest marque les projets/fichiers de configuration comme `forceRerunTriggers` afin que les relances en mode changed restent correctes lorsque le câblage des tests change.
- - La config maintient `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes pris en charge ; définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez un emplacement de cache explicite pour le profilage direct.
-- Note de débogage des performances :
- - `pnpm test:perf:imports` active le rapport de durée d'import Vitest ainsi qu'une sortie de détail des imports.
- - `pnpm test:perf:imports:changed` limite cette même vue de profilage aux fichiers modifiés depuis `origin/main`.
-- `pnpm test:perf:changed:bench -- --ref ` compare `test:changed` routé au chemin natif du projet racine pour ce diff validé et affiche le temps mur à mur ainsi que le RSS maximal macOS.
-- `pnpm test:perf:changed:bench -- --worktree` mesure l'arbre sale courant en routant la liste des fichiers modifiés via `scripts/test-projects.mjs` et la config Vitest racine.
- - `pnpm test:perf:profile:main` écrit un profil CPU du thread principal pour les coûts de démarrage et de transformation de Vitest/Vite.
- - `pnpm test:perf:profile:runner` écrit des profils CPU+tas de l'exécuteur pour la suite unitaire avec le parallélisme des fichiers désactivé.
+ - L’auto-dimensionnement des workers en local est désormais volontairement conservateur et réduit aussi la voilure lorsque la charge moyenne de l’hôte est déjà élevée, afin que plusieurs exécutions Vitest concurrentes fassent moins de dégâts par défaut.
+ - La configuration Vitest de base marque les projets/fichiers de configuration comme `forceRerunTriggers` afin que les réexécutions en mode changed restent correctes lorsque le câblage des tests change.
+ - La configuration maintient `OPENCLAW_VITEST_FS_MODULE_CACHE` activé sur les hôtes pris en charge ; définissez `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si vous voulez un emplacement de cache explicite pour un profilage direct.
+- Remarque sur le débogage des performances :
+ - `pnpm test:perf:imports` active les rapports de durée d’import Vitest ainsi que la ventilation des imports.
+ - `pnpm test:perf:imports:changed` restreint la même vue de profilage aux fichiers modifiés depuis `origin/main`.
+- `pnpm test:perf:changed:bench -- --ref ` compare `test:changed` routé au chemin natif root-project pour ce diff validé et affiche le temps total ainsi que la RSS maximale macOS.
+- `pnpm test:perf:changed:bench -- --worktree` mesure l’arbre de travail courant non validé en routant la liste des fichiers modifiés via `scripts/test-projects.mjs` et la configuration Vitest racine.
+ - `pnpm test:perf:profile:main` écrit un profil CPU du thread principal pour le démarrage Vitest/Vite et la surcharge de transformation.
+ - `pnpm test:perf:profile:runner` écrit des profils CPU+heap de l’exécuteur pour la suite unitaire avec le parallélisme de fichiers désactivé.
### E2E (smoke de la passerelle)
-- Commande : `pnpm test:e2e`
-- Config : `vitest.e2e.config.ts`
-- Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`
-- Valeurs par défaut d'exécution :
- - Utilise Vitest `threads` avec `isolate: false`, en accord avec le reste du dépôt.
- - Utilise des workers adaptatifs (CI : jusqu'à 2, local : 1 par défaut).
- - S'exécute en mode silencieux par défaut pour réduire le coût des E/S console.
-- Remplacements utiles :
+- Commande : `pnpm test:e2e`
+- Config : `vitest.e2e.config.ts`
+- Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`
+- Valeurs d’exécution par défaut :
+ - Utilise Vitest `threads` avec `isolate: false`, comme le reste du dépôt.
+ - Utilise des workers adaptatifs (CI : jusqu’à 2, local : 1 par défaut).
+ - S’exécute en mode silencieux par défaut afin de réduire la surcharge d’E/S console.
+- Surcharges utiles :
- `OPENCLAW_E2E_WORKERS=` pour forcer le nombre de workers (plafonné à 16).
- - `OPENCLAW_E2E_VERBOSE=1` pour réactiver la sortie console détaillée.
-- Portée :
- - Comportement end-to-end de passerelle multi-instance
+ - `OPENCLAW_E2E_VERBOSE=1` pour réactiver une sortie console verbeuse.
+- Portée :
+ - Comportement end-to-end de la passerelle multi-instances
- Surfaces WebSocket/HTTP, appairage de nœuds et réseau plus lourd
-- Attentes :
- - S'exécute en CI (lorsqu'activé dans le pipeline)
+- Attentes :
+ - S’exécute en CI (lorsqu’activé dans le pipeline)
- Aucune vraie clé requise
- - Plus de pièces mobiles que les tests unitaires (peut être plus lent)
+ - Plus de composants mobiles que les tests unitaires (peut être plus lent)
-### E2E : smoke du backend OpenShell
+### E2E : smoke du backend OpenShell
-- Commande : `pnpm test:e2e:openshell`
-- Fichier : `test/openshell-sandbox.e2e.test.ts`
-- Portée :
- - Démarre une passerelle OpenShell isolée sur l'hôte via Docker
- - Crée un bac à sable à partir d'un Dockerfile local temporaire
- - Exerce le backend OpenShell d'OpenClaw sur de vrais `sandbox ssh-config` + exécution SSH
- - Vérifie le comportement du système de fichiers canonique à distance via le pont fs du bac à sable
-- Attentes :
- - Optionnel uniquement ; ne fait pas partie de l'exécution par défaut `pnpm test:e2e`
- - Nécessite un CLI local `openshell` ainsi qu'un démon Docker fonctionnel
- - Utilise des `HOME` / `XDG_CONFIG_HOME` isolés, puis détruit la passerelle de test et le bac à sable
-- Remplacements utiles :
- - `OPENCLAW_E2E_OPENSHELL=1` pour activer le test lors de l'exécution manuelle de la suite e2e plus large
- - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI ou script wrapper non par défaut
+- Commande : `pnpm test:e2e:openshell`
+- Fichier : `test/openshell-sandbox.e2e.test.ts`
+- Portée :
+ - Démarre une passerelle OpenShell isolée sur l’hôte via Docker
+ - Crée un bac à sable à partir d’un Dockerfile local temporaire
+ - Exerce le backend OpenShell d’OpenClaw via un vrai `sandbox ssh-config` + exécution SSH
+ - Vérifie le comportement canonique du système de fichiers distant via le pont fs du bac à sable
+- Attentes :
+ - Optionnel uniquement ; ne fait pas partie de l’exécution par défaut de `pnpm test:e2e`
+ - Requiert une CLI `openshell` locale ainsi qu’un démon Docker fonctionnel
+ - Utilise un `HOME` / `XDG_CONFIG_HOME` isolé, puis détruit la passerelle de test et le bac à sable
+- Surcharges utiles :
+ - `OPENCLAW_E2E_OPENSHELL=1` pour activer le test lors de l’exécution manuelle de la suite e2e plus large
+ - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` pour pointer vers un binaire CLI non par défaut ou un script wrapper
### Live (vrais fournisseurs + vrais modèles)
-- Commande : `pnpm test:live`
-- Config : `vitest.live.config.ts`
-- Fichiers : `src/**/*.live.test.ts`
-- Par défaut : **activé** par `pnpm test:live` (définit `OPENCLAW_LIVE_TEST=1`)
-- Portée :
- - « Est-ce que ce fournisseur/modèle fonctionne réellement _aujourd'hui_ avec de vrais identifiants ? »
- - Détecter les changements de format de fournisseur, les particularités d'appel d'outil, les problèmes d'authentification et le comportement des limites de débit
-- Attentes :
- - Pas stable en CI par nature (réseaux réels, politiques réelles des fournisseurs, quotas, pannes)
- - Coûte de l'argent / consomme des limites de débit
+- Commande : `pnpm test:live`
+- Config : `vitest.live.config.ts`
+- Fichiers : `src/**/*.live.test.ts`
+- Par défaut : **activé** par `pnpm test:live` (définit `OPENCLAW_LIVE_TEST=1`)
+- Portée :
+ - « Ce fournisseur/modèle fonctionne-t-il vraiment _aujourd’hui_ avec de vrais identifiants ? »
+ - Détecter les changements de format des fournisseurs, les particularités d’appel d’outils, les problèmes d’authentification et le comportement face aux limites de débit
+- Attentes :
+ - Pas stable en CI par conception (vrais réseaux, vraies politiques de fournisseur, quotas, pannes)
+ - Coûte de l’argent / consomme des limites de débit
- Préférez exécuter des sous-ensembles restreints plutôt que « tout »
-- Les exécutions live chargent `~/.profile` pour récupérer les clés API manquantes.
-- Par défaut, les exécutions live isolent toujours `HOME` et copient le matériel de config/auth dans un home de test temporaire afin que les fixtures unitaires ne puissent pas muter votre vrai `~/.openclaw`.
+- Les exécutions live sourcent `~/.profile` pour récupérer les clés API manquantes.
+- Par défaut, les exécutions live isolent toujours `HOME` et copient le matériel de configuration/authentification dans un répertoire home de test temporaire afin que les fixtures unitaires ne puissent pas modifier votre vrai `~/.openclaw`.
- Définissez `OPENCLAW_LIVE_USE_REAL_HOME=1` uniquement lorsque vous avez intentionnellement besoin que les tests live utilisent votre vrai répertoire home.
-- `pnpm test:live` utilise désormais un mode plus discret par défaut : il conserve la sortie de progression `[live] ...`, mais supprime l'avis supplémentaire `~/.profile` et coupe les logs de démarrage de la passerelle/le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez retrouver les logs de démarrage complets.
-- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` avec un format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou un remplacement par live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient en cas de réponses de limite de débit.
-- Sortie de progression/heartbeat :
- - Les suites live émettent désormais des lignes de progression vers stderr afin que les longs appels fournisseur restent visiblement actifs même lorsque la capture console de Vitest est silencieuse.
- - `vitest.live.config.ts` désactive l'interception console de Vitest afin que les lignes de progression fournisseur/passerelle soient diffusées immédiatement pendant les exécutions live.
- - Ajustez les heartbeats des modèles directs avec `OPENCLAW_LIVE_HEARTBEAT_MS`.
- - Ajustez les heartbeats de passerelle/sonde avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
+- `pnpm test:live` utilise désormais un mode plus silencieux par défaut : il conserve la sortie de progression `[live] ...`, mais supprime l’avis supplémentaire sur `~/.profile` et coupe les journaux de démarrage de la passerelle/le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous souhaitez retrouver tous les journaux de démarrage.
+- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` avec un format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou surcharge par live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient en cas de réponse de limite de débit.
+- Sortie de progression/pulsation :
+ - Les suites live émettent désormais des lignes de progression vers stderr afin que les longs appels fournisseur apparaissent comme actifs même lorsque la capture console Vitest est silencieuse.
+ - `vitest.live.config.ts` désactive l’interception console de Vitest afin que les lignes de progression fournisseur/passerelle soient diffusées immédiatement pendant les exécutions live.
+ - Ajustez les pulsations direct-model avec `OPENCLAW_LIVE_HEARTBEAT_MS`.
+ - Ajustez les pulsations gateway/probe avec `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
-## Quelle suite dois-je exécuter ?
+## Quelle suite dois-je exécuter ?
-Utilisez ce tableau de décision :
+Utilisez ce tableau de décision :
-- Modifier logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié)
-- Toucher au réseau de la passerelle / protocole WS / appairage : ajoutez `pnpm test:e2e`
-- Déboguer « mon bot est en panne » / échecs spécifiques au fournisseur / appel d'outil : exécutez un `pnpm test:live` restreint
+- Modification de logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié)
+- Retouche du réseau de la passerelle / du protocole WS / de l’appairage : ajoutez `pnpm test:e2e`
+- Débogage de « mon bot est en panne » / échecs spécifiques au fournisseur / appel d’outils : exécutez un `pnpm test:live` restreint
-## Live : balayage des capacités du nœud Android
+## Live : balayage des capacités de nœud Android
-- Test : `src/gateway/android-node.capabilities.live.test.ts`
-- Script : `pnpm android:test:integration`
-- Objectif : invoquer **chaque commande actuellement annoncée** par un nœud Android connecté et vérifier le comportement du contrat de commande.
-- Portée :
- - Précondition/configuration manuelle (la suite n'installe, n'exécute ni n'appaire l'application).
- - Validation `node.invoke` de la passerelle commande par commande pour le nœud Android sélectionné.
-- Préconfiguration requise :
+- Test : `src/gateway/android-node.capabilities.live.test.ts`
+- Script : `pnpm android:test:integration`
+- Objectif : invoquer **chaque commande actuellement annoncée** par un nœud Android connecté et vérifier le comportement du contrat de commande.
+- Portée :
+ - Configuration préalable/manuelle (la suite n’installe pas, n’exécute pas et n’appaire pas l’application).
+ - Validation `node.invoke` commande par commande de la passerelle pour le nœud Android sélectionné.
+- Préconfiguration requise :
- Application Android déjà connectée et appairée à la passerelle.
- Application maintenue au premier plan.
- - Autorisations/consentement de capture accordés pour les capacités que vous attendez voir réussir.
-- Remplacements de cible facultatifs :
+ - Permissions/consentement de capture accordés pour les capacités que vous attendez comme réussies.
+- Surcharges de cible facultatives :
- `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`.
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
-- Détails complets de configuration Android : [Android App](/fr/platforms/android)
+- Détails complets de la configuration Android : [Application Android](/fr/platforms/android)
-## Live : smoke de modèle (clés de profil)
+## Live : smoke des modèles (clés de profil)
-Les tests live sont divisés en deux couches afin que nous puissions isoler les échecs :
+Les tests live sont divisés en deux couches afin que nous puissions isoler les échecs :
-- « Modèle direct » nous indique si le fournisseur/modèle peut répondre tout court avec la clé donnée.
-- « Smoke de passerelle » nous indique si le pipeline complet passerelle+agent fonctionne pour ce modèle (sessions, historique, outils, politique de bac à sable, etc.).
+- « Modèle direct » nous indique si le fournisseur/modèle peut répondre tout court avec la clé donnée.
+- « Smoke de la passerelle » nous indique si le pipeline complet passerelle+agent fonctionne pour ce modèle (sessions, historique, outils, politique de bac à sable, etc.).
-### Couche 1 : complétion de modèle directe (sans passerelle)
+### Couche 1 : complétion directe du modèle (sans passerelle)
-- Test : `src/agents/models.profiles.live.test.ts`
-- Objectif :
+- Test : `src/agents/models.profiles.live.test.ts`
+- Objectif :
- Énumérer les modèles découverts
- Utiliser `getApiKeyForModel` pour sélectionner les modèles pour lesquels vous avez des identifiants
- Exécuter une petite complétion par modèle (et des régressions ciblées si nécessaire)
-- Comment l'activer :
+- Comment l’activer :
- `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement)
-- Définissez `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) pour réellement exécuter cette suite ; sinon elle est ignorée afin de garder `pnpm test:live` centré sur le smoke de passerelle
-- Comment sélectionner les modèles :
- - `OPENCLAW_LIVE_MODELS=modern` pour exécuter la liste d'autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
- - `OPENCLAW_LIVE_MODELS=all` est un alias de la liste d'autorisation moderne
- - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (liste d'autorisation séparée par des virgules)
- - Les balayages modern/all utilisent par défaut un plafond organisé à fort signal ; définissez `OPENCLAW_LIVE_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit.
-- Comment sélectionner les fournisseurs :
- - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (liste d'autorisation séparée par des virgules)
-- D'où viennent les clés :
- - Par défaut : magasin de profils et variables d'environnement de secours
- - Définissez `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour imposer **uniquement** le magasin de profils
-- Pourquoi cela existe :
- - Sépare « l'API fournisseur est cassée / la clé est invalide » de « le pipeline d'agent de la passerelle est cassé »
- - Contient de petites régressions isolées (exemple : rejeu de raisonnement OpenAI Responses/Codex Responses + flux d'appels d'outils)
+- Définissez `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) pour réellement exécuter cette suite ; sinon elle est ignorée afin de garder `pnpm test:live` centré sur le smoke de la passerelle
+- Comment sélectionner les modèles :
+ - `OPENCLAW_LIVE_MODELS=modern` pour exécuter la liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
+ - `OPENCLAW_LIVE_MODELS=all` est un alias de la liste d’autorisation moderne
+ - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (liste d’autorisation séparée par des virgules)
+ - Les balayages modern/all utilisent par défaut une limite de haute valeur signalée soigneusement choisie ; définissez `OPENCLAW_LIVE_MAX_MODELS=0` pour un balayage moderne exhaustif ou une valeur positive pour une limite plus petite.
+- Comment sélectionner les fournisseurs :
+ - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (liste d’autorisation séparée par des virgules)
+- D’où viennent les clés :
+ - Par défaut : stockage de profils et replis env
+ - Définissez `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour imposer **uniquement le stockage de profils**
+- Pourquoi cela existe :
+ - Sépare « l’API du fournisseur est cassée / la clé est invalide » de « le pipeline d’agent de la passerelle est cassé »
+ - Contient de petites régressions isolées (exemple : rejouabilité du raisonnement OpenAI Responses/Codex Responses + flux d’appel d’outils)
-### Couche 2 : smoke passerelle + agent dev (ce que fait réellement "@openclaw")
+### Couche 2 : smoke de la passerelle + de l’agent dev (ce que fait réellement « @openclaw »)
-- Test : `src/gateway/gateway-models.profiles.live.test.ts`
-- Objectif :
+- Test : `src/gateway/gateway-models.profiles.live.test.ts`
+- Objectif :
- Démarrer une passerelle en processus
- - Créer/mettre à jour une session `agent:dev:*` (remplacement de modèle à chaque exécution)
- - Itérer sur les modèles avec clés et vérifier :
- - réponse « significative » (sans outils)
- - un vrai appel d'outil fonctionne (sonde de lecture)
- - des sondes d'outil supplémentaires facultatives fonctionnent (sonde exec+read)
- - les chemins de régression OpenAI (appel d'outil seul → suivi) continuent de fonctionner
-- Détails des sondes (pour pouvoir expliquer rapidement les échecs) :
- - sonde `read` : le test écrit un fichier nonce dans l'espace de travail et demande à l'agent de le `read` et de renvoyer le nonce.
- - sonde `exec+read` : le test demande à l'agent de `exec` l'écriture d'un nonce dans un fichier temporaire, puis de le `read`.
- - sonde d'image : le test joint un PNG généré (chat + code aléatoire) et attend que le modèle renvoie `cat `.
- - Référence d'implémentation : `src/gateway/gateway-models.profiles.live.test.ts` et `src/gateway/live-image-probe.ts`.
-- Comment l'activer :
+ - Créer/patcher une session `agent:dev:*` (surcharge de modèle par exécution)
+ - Itérer sur les modèles avec identifiants et vérifier :
+ - une réponse « significative » (sans outils)
+ - qu’une vraie invocation d’outil fonctionne (sonde de lecture)
+ - des sondes d’outils facultatives supplémentaires (sonde exec+read)
+ - que les chemins de régression OpenAI (appel d’outil seul → suivi) continuent de fonctionner
+- Détails des sondes (afin que vous puissiez expliquer rapidement les échecs) :
+ - sonde `read` : le test écrit un fichier nonce dans l’espace de travail et demande à l’agent de le `read` puis de renvoyer le nonce.
+ - sonde `exec+read` : le test demande à l’agent d’écrire un nonce via `exec` dans un fichier temporaire, puis de le `read`.
+ - sonde image : le test joint un PNG généré (chat + code aléatoire) et s’attend à ce que le modèle renvoie `cat `.
+ - Référence d’implémentation : `src/gateway/gateway-models.profiles.live.test.ts` et `src/gateway/live-image-probe.ts`.
+- Comment l’activer :
- `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement)
-- Comment sélectionner les modèles :
- - Par défaut : liste d'autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
- - `OPENCLAW_LIVE_GATEWAY_MODELS=all` est un alias de la liste d'autorisation moderne
- - Ou définissez `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou liste séparée par des virgules) pour restreindre
- - Les balayages modern/all de passerelle utilisent par défaut un plafond organisé à fort signal ; définissez `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus petit.
-- Comment sélectionner les fournisseurs (évitez « tout OpenRouter ») :
- - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (liste d'autorisation séparée par des virgules)
-- Les sondes d'outil + d'image sont toujours activées dans ce test live :
+- Comment sélectionner les modèles :
+ - Par défaut : liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
+ - `OPENCLAW_LIVE_GATEWAY_MODELS=all` est un alias de la liste d’autorisation moderne
+ - Ou définissez `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou une liste séparée par des virgules) pour restreindre
+ - Les balayages de passerelle modern/all utilisent par défaut une limite de haute valeur signalée soigneusement choisie ; définissez `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` pour un balayage moderne exhaustif ou une valeur positive pour une limite plus petite.
+- Comment sélectionner les fournisseurs (éviter « tout OpenRouter ») :
+ - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (liste d’autorisation séparée par des virgules)
+- Les sondes d’outils + d’image sont toujours activées dans ce test live :
- sonde `read` + sonde `exec+read` (stress sur les outils)
- - la sonde d'image s'exécute lorsque le modèle annonce la prise en charge des entrées image
- - Flux (haut niveau) :
- - Le test génère un petit PNG avec « CAT » + code aléatoire (`src/gateway/live-image-probe.ts`)
- - L'envoie via `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
- - La passerelle analyse les pièces jointes en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- - L'agent embarqué transmet au modèle un message utilisateur multimodal
- - Vérification : la réponse contient `cat` + le code (tolérance OCR : erreurs mineures autorisées)
+ - la sonde image s’exécute lorsque le modèle annonce la prise en charge des entrées image
+ - Flux (vue d’ensemble) :
+ - Le test génère un petit PNG avec « CAT » + un code aléatoire (`src/gateway/live-image-probe.ts`)
+ - L’envoie via `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
+ - La passerelle analyse les pièces jointes dans `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
+ - L’agent embarqué transmet un message utilisateur multimodal au modèle
+ - Vérification : la réponse contient `cat` + le code (tolérance OCR : erreurs mineures autorisées)
-Conseil : pour voir ce que vous pouvez tester sur votre machine (et les identifiants exacts `provider/model`), exécutez :
+Astuce : pour voir ce que vous pouvez tester sur votre machine (et les identifiants exacts `provider/model`), exécutez :
```bash
openclaw models list
openclaw models list --json
```
-## Live : smoke du backend CLI (Claude, Codex, Gemini ou autres CLI locaux)
+## Live : smoke du backend CLI (Claude, Codex, Gemini ou autres CLI locales)
-- Test : `src/gateway/gateway-cli-backend.live.test.ts`
-- Objectif : valider le pipeline Gateway + agent à l'aide d'un backend CLI local, sans toucher à votre configuration par défaut.
-- Les valeurs par défaut de smoke spécifiques au backend se trouvent avec la définition `cli-backend.ts` de l'extension propriétaire.
-- Activer :
+- Test : `src/gateway/gateway-cli-backend.live.test.ts`
+- Objectif : valider le pipeline Gateway + agent à l’aide d’un backend CLI local, sans toucher à votre configuration par défaut.
+- Les valeurs par défaut du smoke spécifiques au backend se trouvent dans la définition `cli-backend.ts` de l’extension propriétaire.
+- Activer :
- `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
-- Valeurs par défaut :
- - Fournisseur/modèle par défaut : `claude-cli/claude-sonnet-4-6`
- - Le comportement commande/args/image provient des métadonnées du plugin backend CLI propriétaire.
-- Remplacements (facultatifs) :
+- Valeurs par défaut :
+ - Fournisseur/modèle par défaut : `claude-cli/claude-sonnet-4-6`
+ - Le comportement de commande/arguments/image provient des métadonnées du plugin backend CLI propriétaire.
+- Surcharges (facultatives) :
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` pour envoyer une vraie pièce jointe image (les chemins sont injectés dans le prompt).
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` pour transmettre les chemins de fichiers image comme args CLI au lieu de l'injection dans le prompt.
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) pour contrôler la manière dont les args image sont transmis lorsque `IMAGE_ARG` est défini.
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` pour envoyer une vraie pièce jointe image (les chemins sont injectés dans l’invite).
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` pour transmettre les chemins des fichiers image comme arguments CLI au lieu de l’injection dans l’invite.
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) pour contrôler la façon dont les arguments image sont transmis lorsque `IMAGE_ARG` est défini.
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` pour envoyer un second tour et valider le flux de reprise.
- - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` pour désactiver la sonde par défaut de continuité de même session Claude Sonnet -> Opus (définissez-la à `1` pour l'activer de force lorsque le modèle sélectionné prend en charge une cible de changement).
+ - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` pour désactiver la sonde de continuité par défaut Claude Sonnet -> Opus dans la même session (définissez à `1` pour la forcer lorsque le modèle sélectionné prend en charge une cible de bascule).
-Exemple :
+Exemple :
```bash
OPENCLAW_LIVE_CLI_BACKEND=1 \
@@ -291,13 +313,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
```
-Recette Docker :
+Recette Docker :
```bash
pnpm test:docker:live-cli-backend
```
-Recettes Docker à fournisseur unique :
+Recettes Docker mono-fournisseur :
```bash
pnpm test:docker:live-cli-backend:claude
@@ -305,41 +327,41 @@ pnpm test:docker:live-cli-backend:codex
pnpm test:docker:live-cli-backend:gemini
```
-Remarques :
+Remarques :
-- L'exécuteur Docker se trouve dans `scripts/test-live-cli-backend-docker.sh`.
-- Il exécute le smoke live de backend CLI dans l'image Docker du dépôt en tant qu'utilisateur non root `node`.
-- Il résout les métadonnées de smoke CLI à partir de l'extension propriétaire, puis installe le paquet CLI Linux correspondant (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) dans un préfixe accessible en écriture mis en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`).
-- Le smoke live de backend CLI exerce maintenant le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d'image, puis appel d'outil MCP `cron` vérifié via le CLI de la passerelle.
-- Le smoke par défaut de Claude met aussi à jour la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d'une note antérieure.
+- L’exécuteur Docker se trouve dans `scripts/test-live-cli-backend-docker.sh`.
+- Il exécute le smoke live du backend CLI dans l’image Docker du dépôt en tant qu’utilisateur non root `node`.
+- Il résout les métadonnées du smoke CLI depuis l’extension propriétaire, puis installe le paquet CLI Linux correspondant (`@anthropic-ai/claude-code`, `@openai/codex`, ou `@google/gemini-cli`) dans un préfixe accessible en écriture et mis en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`).
+- Le smoke live du backend CLI exerce désormais le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d’image, puis appel d’outil MCP `cron` vérifié via la CLI de la passerelle.
+- Le smoke par défaut de Claude patche aussi la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d’une note antérieure.
-## Live : smoke de liaison ACP (`/acp spawn ... --bind here`)
+## Live : smoke de liaison ACP (`/acp spawn ... --bind here`)
-- Test : `src/gateway/gateway-acp-bind.live.test.ts`
-- Objectif : valider le vrai flux de liaison de conversation ACP avec un agent ACP live :
+- Test : `src/gateway/gateway-acp-bind.live.test.ts`
+- Objectif : valider le vrai flux de liaison de conversation ACP avec un agent ACP live :
- envoyer `/acp spawn --bind here`
- - lier sur place une conversation synthétique de canal de message
+ - lier sur place une conversation synthétique de canal de messages
- envoyer un suivi normal sur cette même conversation
- vérifier que le suivi arrive dans la transcription de session ACP liée
-- Activer :
+- Activer :
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
-- Valeurs par défaut :
- - Agents ACP dans Docker : `claude,codex,gemini`
- - Agent ACP pour `pnpm test:live ...` direct : `claude`
- - Canal synthétique : contexte de conversation de type message privé Slack
- - Backend ACP : `acpx`
-- Remplacements :
+- Valeurs par défaut :
+ - Agents ACP dans Docker : `claude,codex,gemini`
+ - Agent ACP pour `pnpm test:live ...` direct : `claude`
+ - Canal synthétique : contexte de conversation de type message privé Slack
+ - Backend ACP : `acpx`
+- Surcharges :
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini`
- `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
- `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'`
-- Remarques :
- - Cette voie utilise la surface `chat.send` de la passerelle avec des champs de route d'origine synthétiques réservés aux admins afin que les tests puissent attacher un contexte de canal de message sans prétendre livrer à l'extérieur.
- - Lorsque `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` n'est pas défini, le test utilise le registre d'agents intégré du plugin embarqué `acpx` pour l'agent de harness ACP sélectionné.
+- Remarques :
+ - Cette voie utilise la surface `chat.send` de la passerelle avec des champs synthétiques de route d’origine réservés à l’admin afin que les tests puissent attacher un contexte de canal de messages sans prétendre livrer quoi que ce soit vers l’extérieur.
+ - Lorsque `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` n’est pas défini, le test utilise le registre d’agents intégré du plugin `acpx` embarqué pour l’agent de harnais ACP sélectionné.
-Exemple :
+Exemple :
```bash
OPENCLAW_LIVE_ACP_BIND=1 \
@@ -347,13 +369,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \
pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
```
-Recette Docker :
+Recette Docker :
```bash
pnpm test:docker:live-acp-bind
```
-Recettes Docker à agent unique :
+Recettes Docker mono-agent :
```bash
pnpm test:docker:live-acp-bind:claude
@@ -361,400 +383,400 @@ pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini
```
-Remarques Docker :
+Remarques Docker :
-- L'exécuteur Docker se trouve dans `scripts/test-live-acp-bind-docker.sh`.
-- Par défaut, il exécute le smoke de liaison ACP sur tous les agents CLI live pris en charge en séquence : `claude`, `codex`, puis `gemini`.
-- Utilisez `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` pour restreindre la matrice.
-- Il charge `~/.profile`, prépare le matériel d'auth CLI correspondant dans le conteneur, installe `acpx` dans un préfixe npm accessible en écriture, puis installe le CLI live demandé (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) s'il manque.
-- À l'intérieur de Docker, l'exécuteur définit `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` afin qu'acpx conserve pour le CLI de harness enfant les variables d'environnement fournisseur issues du profil chargé.
+- L’exécuteur Docker se trouve dans `scripts/test-live-acp-bind-docker.sh`.
+- Par défaut, il exécute le smoke de liaison ACP sur tous les agents CLI live pris en charge en séquence : `claude`, `codex`, puis `gemini`.
+- Utilisez `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` pour restreindre la matrice.
+- Il source `~/.profile`, prépare le matériel d’authentification CLI correspondant dans le conteneur, installe `acpx` dans un préfixe npm accessible en écriture, puis installe la CLI live demandée (`@anthropic-ai/claude-code`, `@openai/codex`, ou `@google/gemini-cli`) si elle manque.
+- À l’intérieur de Docker, l’exécuteur définit `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` afin que acpx conserve les variables d’environnement du fournisseur du profil sourcé disponibles pour la CLI de harnais enfant.
### Recettes live recommandées
-Des listes d'autorisation étroites et explicites sont les plus rapides et les moins fragiles :
+Des listes d’autorisation étroites et explicites sont les plus rapides et les moins instables :
-- Modèle unique, direct (sans passerelle) :
+- Modèle unique, direct (sans passerelle) :
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
-- Modèle unique, smoke de passerelle :
+- Modèle unique, smoke de la passerelle :
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-- Appel d'outil sur plusieurs fournisseurs :
+- Appel d’outils sur plusieurs fournisseurs :
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-- Focus Google (clé API Gemini + Antigravity) :
- - Gemini (clé API) : `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- - Antigravity (OAuth) : `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+- Focus Google (clé API Gemini + Antigravity) :
+ - Gemini (clé API) : `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+ - Antigravity (OAuth) : `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-Remarques :
+Remarques :
-- `google/...` utilise l'API Gemini (clé API).
-- `google-antigravity/...` utilise le pont OAuth Antigravity (point de terminaison d'agent de style Cloud Code Assist).
-- `google-gemini-cli/...` utilise le CLI Gemini local sur votre machine (authentification distincte + particularités des outils).
-- API Gemini vs CLI Gemini :
- - API : OpenClaw appelle l'API Gemini hébergée de Google via HTTP (clé API / authentification de profil) ; c'est ce que la plupart des utilisateurs veulent dire par « Gemini ».
- - CLI : OpenClaw exécute un binaire local `gemini` ; il a sa propre authentification et peut se comporter différemment (streaming/prise en charge des outils/décalage de version).
+- `google/...` utilise l’API Gemini (clé API).
+- `google-antigravity/...` utilise le pont OAuth Antigravity (point de terminaison d’agent de type Cloud Code Assist).
+- `google-gemini-cli/...` utilise la CLI Gemini locale sur votre machine (authentification distincte + particularités d’outillage).
+- API Gemini vs CLI Gemini :
+ - API : OpenClaw appelle l’API Gemini hébergée par Google via HTTP (authentification par clé API / profil) ; c’est ce que la plupart des utilisateurs entendent par « Gemini ».
+ - CLI : OpenClaw exécute un binaire local `gemini` ; il possède sa propre authentification et peut se comporter différemment (streaming/prise en charge des outils/décalage de version).
-## Live : matrice de modèles (ce que nous couvrons)
+## Live : matrice de modèles (ce que nous couvrons)
-Il n'existe pas de « liste de modèles CI » fixe (live est optionnel), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement avec clés.
+Il n’existe pas de « liste de modèles CI » fixe (le live est optionnel), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement avec des clés.
-### Ensemble smoke moderne (appel d'outil + image)
+### Ensemble smoke moderne (appel d’outils + image)
-Il s'agit de l'exécution « modèles courants » que nous attendons de voir fonctionner :
+Il s’agit de l’exécution « modèles courants » que nous attendons de voir fonctionner en continu :
-- OpenAI (hors Codex) : `openai/gpt-5.4` (facultatif : `openai/gpt-5.4-mini`)
-- OpenAI Codex : `openai-codex/gpt-5.4`
-- Anthropic : `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`)
-- Google (API Gemini) : `google/gemini-3.1-pro-preview` et `google/gemini-3-flash-preview` (évitez les anciens modèles Gemini 2.x)
-- Google (Antigravity) : `google-antigravity/claude-opus-4-6-thinking` et `google-antigravity/gemini-3-flash`
-- Z.AI (GLM) : `zai/glm-4.7`
-- MiniMax : `minimax/MiniMax-M2.7`
+- OpenAI (hors Codex) : `openai/gpt-5.4` (facultatif : `openai/gpt-5.4-mini`)
+- OpenAI Codex : `openai-codex/gpt-5.4`
+- Anthropic : `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`)
+- Google (API Gemini) : `google/gemini-3.1-pro-preview` et `google/gemini-3-flash-preview` (éviter les anciens modèles Gemini 2.x)
+- Google (Antigravity) : `google-antigravity/claude-opus-4-6-thinking` et `google-antigravity/gemini-3-flash`
+- Z.AI (GLM) : `zai/glm-4.7`
+- MiniMax : `minimax/MiniMax-M2.7`
-Exécuter le smoke de passerelle avec outils + image :
+Exécutez le smoke de la passerelle avec outils + image :
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-### Référence : appel d'outil (Read + Exec facultatif)
+### Référence de base : appel d’outils (Read + Exec facultatif)
-Choisissez-en au moins un par famille de fournisseurs :
+Choisissez-en au moins un par famille de fournisseurs :
-- OpenAI : `openai/gpt-5.4` (ou `openai/gpt-5.4-mini`)
-- Anthropic : `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`)
-- Google : `google/gemini-3-flash-preview` (ou `google/gemini-3.1-pro-preview`)
-- Z.AI (GLM) : `zai/glm-4.7`
-- MiniMax : `minimax/MiniMax-M2.7`
+- OpenAI : `openai/gpt-5.4` (ou `openai/gpt-5.4-mini`)
+- Anthropic : `anthropic/claude-opus-4-6` (ou `anthropic/claude-sonnet-4-6`)
+- Google : `google/gemini-3-flash-preview` (ou `google/gemini-3.1-pro-preview`)
+- Z.AI (GLM) : `zai/glm-4.7`
+- MiniMax : `minimax/MiniMax-M2.7`
-Couverture supplémentaire facultative (agréable à avoir) :
+Couverture supplémentaire facultative (appréciable) :
-- xAI : `xai/grok-4` (ou la dernière version disponible)
-- Mistral : `mistral/`… (choisissez un modèle compatible « tools » que vous avez activé)
-- Cerebras : `cerebras/`… (si vous y avez accès)
-- LM Studio : `lmstudio/`… (local ; l'appel d'outil dépend du mode API)
+- xAI : `xai/grok-4` (ou la dernière version disponible)
+- Mistral : `mistral/`… (choisissez un modèle compatible « tools » que vous avez activé)
+- Cerebras : `cerebras/`… (si vous y avez accès)
+- LM Studio : `lmstudio/`… (local ; l’appel d’outils dépend du mode API)
-### Vision : envoi d'image (pièce jointe → message multimodal)
+### Vision : envoi d’image (pièce jointe → message multimodal)
-Incluez au moins un modèle compatible image dans `OPENCLAW_LIVE_GATEWAY_MODELS` (variants compatibles vision de Claude/Gemini/OpenAI, etc.) pour exercer la sonde d'image.
+Incluez au moins un modèle compatible image dans `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes OpenAI compatibles vision, etc.) pour exercer la sonde image.
### Agrégateurs / passerelles alternatives
-Si vous avez des clés activées, nous prenons aussi en charge les tests via :
+Si vous avez activé les clés, nous prenons aussi en charge des tests via :
-- OpenRouter : `openrouter/...` (des centaines de modèles ; utilisez `openclaw models scan` pour trouver des candidats compatibles outil+image)
-- OpenCode : `opencode/...` pour Zen et `opencode-go/...` pour Go (auth via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
+- OpenRouter : `openrouter/...` (des centaines de modèles ; utilisez `openclaw models scan` pour trouver des candidats compatibles outils+image)
+- OpenCode : `opencode/...` pour Zen et `opencode-go/...` pour Go (authentification via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
-Autres fournisseurs que vous pouvez inclure dans la matrice live (si vous avez les identifiants/la config) :
+Autres fournisseurs que vous pouvez inclure dans la matrice live (si vous avez les identifiants/la configuration) :
-- Intégrés : `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
-- Via `models.providers` (points de terminaison personnalisés) : `minimax` (cloud/API), plus tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)
+- Intégrés : `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
+- Via `models.providers` (points de terminaison personnalisés) : `minimax` (cloud/API), plus tout proxy compatible OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)
-Conseil : n'essayez pas de coder en dur « tous les modèles » dans la documentation. La liste faisant autorité est celle que `discoverModels(...)` renvoie sur votre machine + les clés disponibles.
+Astuce : n’essayez pas de coder en dur « tous les modèles » dans la documentation. La liste faisant autorité est celle que renvoie `discoverModels(...)` sur votre machine + les clés disponibles.
-## Identifiants (ne jamais valider dans git)
+## Identifiants (ne jamais commit)
-Les tests live découvrent les identifiants de la même manière que le CLI. Conséquences pratiques :
+Les tests live découvrent les identifiants de la même manière que la CLI. Conséquences pratiques :
-- Si le CLI fonctionne, les tests live devraient trouver les mêmes clés.
-- Si un test live indique « aucun identifiant », déboguez-le comme vous débogueriez `openclaw models list` / la sélection de modèle.
+- Si la CLI fonctionne, les tests live devraient trouver les mêmes clés.
+- Si un test live dit « aucun identifiant », déboguez-le comme vous débogueriez `openclaw models list` / la sélection de modèle.
-- Profils d'authentification par agent : `~/.openclaw/agents//agent/auth-profiles.json` (c'est ce que signifient les « clés de profil » dans les tests live)
-- Config : `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`)
-- Ancien répertoire d'état : `~/.openclaw/credentials/` (copié dans le home live préparé lorsqu'il est présent, mais pas dans le magasin principal de clés de profil)
-- Les exécutions live locales copient par défaut la config active, les fichiers `auth-profiles.json` par agent, l'ancien `credentials/` et les répertoires d'auth CLI externes pris en charge dans un home de test temporaire ; les homes live préparés ignorent `workspace/` et `sandboxes/`, et les remplacements de chemin `agents.*.workspace` / `agentDir` sont supprimés afin que les sondes restent hors de votre véritable espace de travail hôte.
+- Profils d’authentification par agent : `~/.openclaw/agents//agent/auth-profiles.json` (c’est ce que signifient les « clés de profil » dans les tests live)
+- Configuration : `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`)
+- Répertoire d’état hérité : `~/.openclaw/credentials/` (copié dans le home live préparé lorsqu’il est présent, mais pas dans le stockage principal de clés de profil)
+- Les exécutions locales live copient par défaut la configuration active, les fichiers `auth-profiles.json` par agent, `credentials/` hérité et les répertoires d’authentification de CLI externes pris en charge dans un home de test temporaire ; les homes live préparés ignorent `workspace/` et `sandboxes/`, et les surcharges de chemin `agents.*.workspace` / `agentDir` sont supprimées afin que les sondes restent en dehors de votre véritable espace de travail hôte.
-Si vous voulez vous appuyer sur des clés d'environnement (par ex. exportées dans votre `~/.profile`), exécutez les tests locaux après `source ~/.profile`, ou utilisez les exécuteurs Docker ci-dessous (ils peuvent monter `~/.profile` dans le conteneur).
+Si vous voulez vous appuyer sur des clés env (par exemple exportées dans votre `~/.profile`), exécutez les tests locaux après `source ~/.profile`, ou utilisez les exécuteurs Docker ci-dessous (ils peuvent monter `~/.profile` dans le conteneur).
## Live Deepgram (transcription audio)
-- Test : `src/media-understanding/providers/deepgram/audio.live.test.ts`
-- Activer : `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
+- Test : `src/media-understanding/providers/deepgram/audio.live.test.ts`
+- Activer : `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
-## Live du plan de codage BytePlus
+## Live BytePlus coding plan
-- Test : `src/agents/byteplus.live.test.ts`
-- Activer : `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
-- Remplacement de modèle facultatif : `BYTEPLUS_CODING_MODEL=ark-code-latest`
+- Test : `src/agents/byteplus.live.test.ts`
+- Activer : `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
+- Surcharge de modèle facultative : `BYTEPLUS_CODING_MODEL=ark-code-latest`
-## Live des médias de workflow ComfyUI
+## Live média de workflow ComfyUI
-- Test : `extensions/comfy/comfy.live.test.ts`
-- Activer : `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
-- Portée :
+- Test : `extensions/comfy/comfy.live.test.ts`
+- Activer : `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
+- Portée :
- Exerce les chemins groupés comfy image, vidéo et `music_generate`
- - Ignore chaque capacité à moins que `models.providers.comfy.` ne soit configuré
- - Utile après avoir modifié l'envoi de workflow comfy, le polling, les téléchargements ou l'enregistrement de plugin
+ - Ignore chaque capacité sauf si `models.providers.comfy.` est configuré
+ - Utile après des modifications de soumission de workflow comfy, polling, téléchargements ou enregistrement du plugin
-## Live de génération d'image
+## Live génération d’images
-- Test : `src/image-generation/runtime.live.test.ts`
-- Commande : `pnpm test:live src/image-generation/runtime.live.test.ts`
-- Harness : `pnpm test:live:media image`
-- Portée :
- - Énumère chaque plugin fournisseur de génération d'image enregistré
- - Charge les variables d'environnement fournisseur manquantes depuis votre shell de connexion (`~/.profile`) avant le sondage
- - Utilise par défaut les clés API live/env avant les profils d'auth stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
- - Ignore les fournisseurs sans auth/profil/modèle utilisable
- - Exécute les variantes standard de génération d'image via la capacité d'exécution partagée :
+- Test : `src/image-generation/runtime.live.test.ts`
+- Commande : `pnpm test:live src/image-generation/runtime.live.test.ts`
+- Harnais : `pnpm test:live:media image`
+- Portée :
+ - Énumère chaque plugin de fournisseur de génération d’images enregistré
+ - Charge les variables d’environnement de fournisseur manquantes depuis votre shell de connexion (`~/.profile`) avant la sonde
+ - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
+ - Ignore les fournisseurs sans authentification/profil/modèle utilisable
+ - Exécute les variantes standard de génération d’images via la capacité runtime partagée :
- `google:flash-generate`
- `google:pro-generate`
- `google:pro-edit`
- `openai:default-generate`
-- Fournisseurs groupés actuellement couverts :
+- Fournisseurs groupés actuellement couverts :
- `openai`
- `google`
-- Restriction facultative :
+- Restriction facultative :
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"`
-- Comportement d'authentification facultatif :
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l'authentification par magasin de profils et ignorer les remplacements uniquement env
+- Comportement d’authentification facultatif :
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le stockage de profils et ignorer les surcharges uniquement env
-## Live de génération musicale
+## Live génération de musique
-- Test : `extensions/music-generation-providers.live.test.ts`
-- Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
-- Harness : `pnpm test:live:media music`
-- Portée :
- - Exerce le chemin partagé du fournisseur groupé de génération musicale
+- Test : `extensions/music-generation-providers.live.test.ts`
+- Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
+- Harnais : `pnpm test:live:media music`
+- Portée :
+ - Exerce le chemin groupé partagé de fournisseur de génération de musique
- Couvre actuellement Google et MiniMax
- - Charge les variables d'environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant le sondage
- - Utilise par défaut les clés API live/env avant les profils d'auth stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
- - Ignore les fournisseurs sans auth/profil/modèle utilisable
- - Exécute les deux modes d'exécution déclarés lorsqu'ils sont disponibles :
- - `generate` avec entrée basée uniquement sur le prompt
+ - Charge les variables d’environnement de fournisseur depuis votre shell de connexion (`~/.profile`) avant la sonde
+ - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
+ - Ignore les fournisseurs sans authentification/profil/modèle utilisable
+ - Exécute les deux modes runtime déclarés lorsqu’ils sont disponibles :
+ - `generate` avec une entrée uniquement invite
- `edit` lorsque le fournisseur déclare `capabilities.edit.enabled`
- - Couverture actuelle de la voie partagée :
- - `google` : `generate`, `edit`
- - `minimax` : `generate`
- - `comfy` : fichier live Comfy séparé, pas ce balayage partagé
-- Restriction facultative :
+ - Couverture actuelle de la voie partagée :
+ - `google` : `generate`, `edit`
+ - `minimax` : `generate`
+ - `comfy` : fichier live Comfy séparé, pas ce balayage partagé
+- Restriction facultative :
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
-- Comportement d'authentification facultatif :
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l'authentification par magasin de profils et ignorer les remplacements uniquement env
+- Comportement d’authentification facultatif :
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le stockage de profils et ignorer les surcharges uniquement env
-## Live de génération vidéo
+## Live génération de vidéos
-- Test : `extensions/video-generation-providers.live.test.ts`
-- Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
-- Harness : `pnpm test:live:media video`
-- Portée :
- - Exerce le chemin partagé du fournisseur groupé de génération vidéo
- - Charge les variables d'environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant le sondage
- - Utilise par défaut les clés API live/env avant les profils d'auth stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
- - Ignore les fournisseurs sans auth/profil/modèle utilisable
- - Exécute les deux modes d'exécution déclarés lorsqu'ils sont disponibles :
- - `generate` avec entrée basée uniquement sur le prompt
- - `imageToVideo` lorsque le fournisseur déclare `capabilities.imageToVideo.enabled` et que le fournisseur/modèle sélectionné accepte en balayage partagé une entrée image locale adossée à un buffer
- - `videoToVideo` lorsque le fournisseur déclare `capabilities.videoToVideo.enabled` et que le fournisseur/modèle sélectionné accepte en balayage partagé une entrée vidéo locale adossée à un buffer
- - Fournisseurs `imageToVideo` actuellement déclarés mais ignorés dans le balayage partagé :
- - `vydra` parce que `veo3` groupé est texte uniquement et que `kling` groupé exige une URL d'image distante
- - Couverture Vydra spécifique au fournisseur :
+- Test : `extensions/video-generation-providers.live.test.ts`
+- Activer : `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
+- Harnais : `pnpm test:live:media video`
+- Portée :
+ - Exerce le chemin groupé partagé de fournisseur de génération de vidéos
+ - Charge les variables d’environnement de fournisseur depuis votre shell de connexion (`~/.profile`) avant la sonde
+ - Utilise par défaut les clés API live/env avant les profils d’authentification stockés, afin que des clés de test obsolètes dans `auth-profiles.json` ne masquent pas les vrais identifiants du shell
+ - Ignore les fournisseurs sans authentification/profil/modèle utilisable
+ - Exécute les deux modes runtime déclarés lorsqu’ils sont disponibles :
+ - `generate` avec une entrée uniquement invite
+ - `imageToVideo` lorsque le fournisseur déclare `capabilities.imageToVideo.enabled` et que le fournisseur/modèle sélectionné accepte une entrée image locale adossée à un buffer dans le balayage partagé
+ - `videoToVideo` lorsque le fournisseur déclare `capabilities.videoToVideo.enabled` et que le fournisseur/modèle sélectionné accepte une entrée vidéo locale adossée à un buffer dans le balayage partagé
+ - Fournisseurs `imageToVideo` actuellement déclarés mais ignorés dans le balayage partagé :
+ - `vydra` car le `veo3` groupé est uniquement texte et le `kling` groupé exige une URL d’image distante
+ - Couverture Vydra spécifique au fournisseur :
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- - ce fichier exécute `veo3` en texte-vers-vidéo plus une voie `kling` qui utilise par défaut une fixture d'URL d'image distante
- - Couverture live actuelle `videoToVideo` :
+ - ce fichier exécute `veo3` en texte-vers-vidéo ainsi qu’une voie `kling` qui utilise par défaut une fixture d’URL d’image distante
+ - Couverture live actuelle `videoToVideo` :
- `runway` uniquement lorsque le modèle sélectionné est `runway/gen4_aleph`
- - Fournisseurs `videoToVideo` actuellement déclarés mais ignorés dans le balayage partagé :
- - `alibaba`, `qwen`, `xai` parce que ces chemins exigent actuellement des URL de référence distantes `http(s)` / MP4
- - `google` parce que la voie partagée actuelle Gemini/Veo utilise une entrée locale adossée à un buffer et que ce chemin n'est pas accepté dans le balayage partagé
- - `openai` parce que la voie partagée actuelle ne garantit pas l'accès spécifique à l'organisation pour l'inpainting/remix vidéo
-- Restriction facultative :
+ - Fournisseurs `videoToVideo` actuellement déclarés mais ignorés dans le balayage partagé :
+ - `alibaba`, `qwen`, `xai` car ces chemins exigent actuellement des URL de référence distantes `http(s)` / MP4
+ - `google` car la voie Gemini/Veo partagée actuelle utilise une entrée locale adossée à un buffer et ce chemin n’est pas accepté dans le balayage partagé
+ - `openai` car la voie partagée actuelle ne garantit pas l’accès spécifique à l’organisation pour l’inpainting/remix vidéo
+- Restriction facultative :
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
-- Comportement d'authentification facultatif :
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l'authentification par magasin de profils et ignorer les remplacements uniquement env
+- Comportement d’authentification facultatif :
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification via le stockage de profils et ignorer les surcharges uniquement env
-## Harness live média
+## Harnais live média
-- Commande : `pnpm test:live:media`
-- Objectif :
- - Exécute les suites live partagées image, musique et vidéo via un point d'entrée natif du dépôt
- - Charge automatiquement les variables d'environnement fournisseur manquantes depuis `~/.profile`
- - Restreint automatiquement chaque suite aux fournisseurs qui disposent actuellement d'une authentification utilisable par défaut
- - Réutilise `scripts/test-live.mjs`, afin que le comportement heartbeat et mode silencieux reste cohérent
-- Exemples :
+- Commande : `pnpm test:live:media`
+- Objectif :
+ - Exécute les suites live partagées image, musique et vidéo via un point d’entrée natif du dépôt unique
+ - Charge automatiquement les variables d’environnement de fournisseur manquantes depuis `~/.profile`
+ - Restreint automatiquement chaque suite aux fournisseurs qui disposent actuellement d’une authentification exploitable par défaut
+ - Réutilise `scripts/test-live.mjs`, afin que le comportement de pulsation et de mode silencieux reste cohérent
+- Exemples :
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`
- `pnpm test:live:media video --video-providers openai,runway --all-providers`
- `pnpm test:live:media music --quiet`
-## Exécuteurs Docker (vérifications facultatives « fonctionne sous Linux »)
+## Exécuteurs Docker (vérifications facultatives « fonctionne sous Linux »)
-Ces exécuteurs Docker se divisent en deux catégories :
+Ces exécuteurs Docker se divisent en deux catégories :
-- Exécuteurs live-model : `test:docker:live-models` et `test:docker:live-gateway` n'exécutent que leur fichier live de clés de profil correspondant à l'intérieur de l'image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de config local et votre espace de travail (et en chargeant `~/.profile` s'il est monté). Les points d'entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`.
-- Les exécuteurs live Docker utilisent par défaut un plafond de smoke plus petit pour qu'un balayage Docker complet reste pratique :
+- Exécuteurs live-model : `test:docker:live-models` et `test:docker:live-gateway` n’exécutent que leur fichier live à clés de profil correspondant dans l’image Docker du dépôt (`src/agents/models.profiles.live.test.ts` et `src/gateway/gateway-models.profiles.live.test.ts`), en montant votre répertoire de configuration local et votre espace de travail (et en sourçant `~/.profile` s’il est monté). Les points d’entrée locaux correspondants sont `test:live:models-profiles` et `test:live:gateway-profiles`.
+- Les exécuteurs Docker live utilisent par défaut une limite smoke plus petite afin qu’un balayage Docker complet reste pratique :
`test:docker:live-models` utilise par défaut `OPENCLAW_LIVE_MAX_MODELS=12`, et
`test:docker:live-gateway` utilise par défaut `OPENCLAW_LIVE_GATEWAY_SMOKE=1`,
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`,
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, et
- `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d'environnement lorsque vous
- voulez explicitement l'analyse exhaustive plus large.
-- `test:docker:all` construit l'image Docker live une fois via `test:docker:live-build`, puis la réutilise pour les deux voies Docker live.
-- Exécuteurs de smoke conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` et `test:docker:plugins` démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d'intégration de plus haut niveau.
+ `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d’environnement lorsque vous
+ souhaitez explicitement le balayage exhaustif plus large.
+- `test:docker:all` construit une seule fois l’image Docker live via `test:docker:live-build`, puis la réutilise pour les deux voies Docker live.
+- Exécuteurs smoke de conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, et `test:docker:plugins` démarrent un ou plusieurs conteneurs réels et vérifient des chemins d’intégration de plus haut niveau.
-Les exécuteurs Docker live-model montent aussi seulement les homes d'auth CLI nécessaires (ou tous ceux pris en charge lorsque l'exécution n'est pas restreinte), puis les copient dans le home du conteneur avant l'exécution afin que l'OAuth des CLI externes puisse actualiser les jetons sans muter le magasin d'auth de l'hôte :
+Les exécuteurs Docker live-model montent aussi en bind uniquement les homes d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le home du conteneur avant l’exécution afin que l’OAuth de CLI externe puisse rafraîchir les jetons sans modifier le stockage d’authentification de l’hôte :
-- Modèles directs : `pnpm test:docker:live-models` (script : `scripts/test-live-models-docker.sh`)
-- Smoke de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`)
-- Smoke du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`)
-- Passerelle + agent dev : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`)
-- Smoke live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`)
-- Assistant d'onboarding (TTY, scaffolding complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`)
-- Réseau de passerelle (deux conteneurs, auth WS + état de santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`)
-- Pont de canal MCP (Gateway initialisée + pont stdio + smoke brut du cadre de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`)
-- Plugins (smoke d'installation + alias `/plugin` + sémantique de redémarrage du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`)
+- Modèles directs : `pnpm test:docker:live-models` (script : `scripts/test-live-models-docker.sh`)
+- Smoke de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`)
+- Smoke du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`)
+- Passerelle + agent dev : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`)
+- Smoke live Open WebUI : `pnpm test:docker:openwebui` (script : `scripts/e2e/openwebui-docker.sh`)
+- Assistant d’onboarding (TTY, scaffolding complet) : `pnpm test:docker:onboard` (script : `scripts/e2e/onboard-docker.sh`)
+- Réseau de passerelle (deux conteneurs, auth WS + health) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`)
+- Pont de canal MCP (Gateway préinitialisée + pont stdio + smoke de trame de notification Claude brute) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`)
+- Plugins (smoke d’installation + alias `/plugin` + sémantique de redémarrage du bundle Claude) : `pnpm test:docker:plugins` (script : `scripts/e2e/plugins-docker.sh`)
-Les exécuteurs Docker live-model montent aussi la checkout actuelle en lecture seule et
-la préparent dans un répertoire de travail temporaire à l'intérieur du conteneur. Cela garde l'image d'exécution
-légère tout en exécutant Vitest sur votre source/config locale exacte.
-L'étape de préparation ignore les gros caches uniquement locaux et les sorties de build d'application comme
-`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires de sortie locaux `.build` ou
-Gradle, afin que les exécutions live Docker ne passent pas des minutes à copier
+Les exécuteurs Docker live-model montent aussi en bind l’extraction courante en lecture seule et
+la préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela maintient
+la minceur de l’image d’exécution tout en exécutant Vitest sur votre code/configuration locale exacte.
+L’étape de préparation ignore les gros caches locaux et sorties de build d’application comme
+`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, et les répertoires de sortie `.build` ou
+Gradle propres aux applications afin que les exécutions Docker live ne passent pas des minutes à copier
des artefacts spécifiques à la machine.
Ils définissent aussi `OPENCLAW_SKIP_CHANNELS=1` afin que les sondes live de passerelle ne démarrent pas
-de vrais workers de canal Telegram/Discord/etc. dans le conteneur.
+de vrais workers de canal Telegram/Discord/etc. à l’intérieur du conteneur.
`test:docker:live-models` exécute toujours `pnpm test:live`, donc transmettez aussi
-`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture live
-de passerelle de cette voie Docker.
-`test:docker:openwebui` est un smoke de compatibilité de plus haut niveau : il démarre un
+`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture
+live de la passerelle de cette voie Docker.
+`test:docker:openwebui` est un smoke de compatibilité de plus haut niveau : il démarre un
conteneur de passerelle OpenClaw avec les points de terminaison HTTP compatibles OpenAI activés,
démarre un conteneur Open WebUI épinglé contre cette passerelle, se connecte via
Open WebUI, vérifie que `/api/models` expose `openclaw/default`, puis envoie une
-vraie requête de chat via le proxy `/api/chat/completions` d'Open WebUI.
-La première exécution peut être sensiblement plus lente car Docker peut devoir récupérer l'image
-Open WebUI et Open WebUI peut devoir terminer sa propre initialisation à froid.
-Cette voie attend une clé de modèle live utilisable, et `OPENCLAW_PROFILE_FILE`
-(`~/.profile` par défaut) est le moyen principal de la fournir dans les exécutions Docker.
+vraie requête de chat via le proxy `/api/chat/completions` d’Open WebUI.
+La première exécution peut être sensiblement plus lente car Docker peut devoir récupérer l’image
+Open WebUI et Open WebUI peut devoir terminer sa propre configuration de démarrage à froid.
+Cette voie attend une clé de modèle live exploitable, et `OPENCLAW_PROFILE_FILE`
+(`~/.profile` par défaut) est le moyen principal de la fournir dans les exécutions Dockerisées.
Les exécutions réussies affichent une petite charge utile JSON comme `{ "ok": true, "model":
"openclaw/default", ... }`.
-`test:docker:mcp-channels` est volontairement déterministe et n'a pas besoin d'un
-vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway
-initialisé, lance un second conteneur qui exécute `openclaw mcp serve`, puis
-vérifie la découverte des conversations routées, les lectures de transcription, les métadonnées de pièce jointe,
-le comportement de la file d'événements live, le routage des envois sortants, et les notifications
-de canal + autorisation de style Claude sur le vrai pont MCP stdio. La vérification des notifications
-inspecte directement les cadres MCP stdio bruts afin que le smoke valide ce que le
-pont émet réellement, et non simplement ce qu'un SDK client particulier choisit d'exposer.
+`test:docker:mcp-channels` est volontairement déterministe et ne nécessite pas
+de vrai compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway
+préinitialisé, démarre un second conteneur qui lance `openclaw mcp serve`, puis
+vérifie la découverte de conversations routées, les lectures de transcriptions, les métadonnées
+de pièces jointes, le comportement de la file d’événements live, le routage d’envoi sortant, ainsi que
+les notifications de canal + d’autorisation de type Claude sur le vrai pont stdio MCP. La vérification des notifications
+inspecte directement les trames MCP stdio brutes afin que le smoke valide ce que le pont émet réellement,
+et non seulement ce qu’un SDK client donné expose par hasard.
-Smoke manuel ACP en langage courant (pas CI) :
+Smoke manuel ACP de fil en langage naturel (pas en CI) :
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...`
-- Conservez ce script pour les workflows de régression/débogage. Il pourra être à nouveau nécessaire pour la validation du routage de thread ACP, donc ne le supprimez pas.
+- Conservez ce script pour les workflows de régression/débogage. Il pourra être de nouveau nécessaire pour la validation du routage de fil ACP, donc ne le supprimez pas.
-Variables d'environnement utiles :
+Variables d’environnement utiles :
-- `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté vers `/home/node/.openclaw`
-- `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté vers `/home/node/.openclaw/workspace`
-- `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté vers `/home/node/.profile` et chargé avant l'exécution des tests
-- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté vers `/home/node/.npm-global` pour les installations CLI mises en cache dans Docker
-- Les répertoires/fichiers d'auth CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés dans `/home/node/...` avant le démarrage des tests
- - Répertoires par défaut : `.minimax`
- - Fichiers par défaut : `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
- - Les exécutions restreintes à un fournisseur ne montent que les répertoires/fichiers nécessaires déduits à partir de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
- - Remplacement manuel avec `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, ou une liste séparée par des virgules comme `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
-- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` pour restreindre l'exécution
+- `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté sur `/home/node/.openclaw`
+- `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté sur `/home/node/.openclaw/workspace`
+- `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté sur `/home/node/.profile` et sourcé avant l’exécution des tests
+- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour des installations CLI mises en cache dans Docker
+- Les répertoires/fichiers d’authentification de CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés dans `/home/node/...` avant le démarrage des tests
+ - Répertoires par défaut : `.minimax`
+ - Fichiers par défaut : `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
+ - Les exécutions restreintes à un fournisseur ne montent que les répertoires/fichiers nécessaires déduits depuis `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
+ - Remplacez manuellement avec `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, ou une liste séparée par des virgules comme `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
+- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` pour restreindre l’exécution
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` pour filtrer les fournisseurs dans le conteneur
-- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour garantir que les identifiants proviennent du magasin de profils (pas de l'env)
+- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour garantir que les identifiants proviennent du stockage de profils (pas de env)
- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par la passerelle pour le smoke Open WebUI
-- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer le prompt de vérification du nonce utilisé par le smoke Open WebUI
-- `OPENWEBUI_IMAGE=...` pour remplacer la balise d'image Open WebUI épinglée
+- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer l’invite de vérification du nonce utilisée par le smoke Open WebUI
+- `OPENWEBUI_IMAGE=...` pour remplacer le tag d’image Open WebUI épinglé
-## Vérification de la documentation
+## Vérification rapide de la documentation
-Exécutez les vérifications de docs après modification de la documentation : `pnpm check:docs`.
-Exécutez la validation complète des ancres Mintlify lorsque vous avez aussi besoin de vérifications des titres dans la page : `pnpm docs:check-links:anchors`.
+Exécutez les vérifications de documentation après des modifications de docs : `pnpm check:docs`.
+Exécutez la validation complète des ancres Mintlify lorsque vous avez aussi besoin de vérifier les titres dans la page : `pnpm docs:check-links:anchors`.
-## Régression hors ligne (sans danger pour la CI)
+## Régression hors ligne (compatible CI)
-Il s'agit de régressions de « vrai pipeline » sans vrais fournisseurs :
+Il s’agit de régressions de « vrai pipeline » sans vrais fournisseurs :
-- Appel d'outil de passerelle (OpenAI simulé, vraie boucle passerelle + agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop")
-- Assistant de passerelle (WS `wizard.start`/`wizard.next`, écrit config + auth imposée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config")
+- Appel d’outils de la passerelle (OpenAI simulé, vraie boucle passerelle + agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop")
+- Assistant de la passerelle (WS `wizard.start`/`wizard.next`, écrit config + auth imposées) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config")
-## Évaluations de fiabilité des agents (Skills)
+## Évaluations de fiabilité de l’agent (Skills)
-Nous avons déjà quelques tests sans danger pour la CI qui se comportent comme des « évaluations de fiabilité des agents » :
+Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité de l’agent » :
-- Appel d'outil simulé via la vraie boucle passerelle + agent (`src/gateway/gateway.test.ts`).
-- Flux d'assistant de bout en bout qui valident le câblage de session et les effets de configuration (`src/gateway/gateway.test.ts`).
+- Appel d’outils simulé via la vraie boucle passerelle + agent (`src/gateway/gateway.test.ts`).
+- Flux d’assistant end-to-end qui valident le câblage de session et les effets de configuration (`src/gateway/gateway.test.ts`).
-Ce qui manque encore pour les Skills (voir [Skills](/fr/tools/skills)) :
+Ce qui manque encore pour les Skills (voir [Skills](/fr/tools/skills)) :
-- **Prise de décision :** lorsque les skills sont listées dans le prompt, l'agent choisit-il la bonne skill (ou évite-t-il les skills non pertinentes) ?
-- **Conformité :** l'agent lit-il `SKILL.md` avant utilisation et suit-il les étapes/args requis ?
-- **Contrats de workflow :** scénarios multi-tours qui vérifient l'ordre des outils, le report de l'historique de session et les limites du bac à sable.
+- **Prise de décision :** lorsque des Skills sont listées dans l’invite, l’agent choisit-il la bonne Skill (ou évite-t-il celles qui sont hors sujet) ?
+- **Conformité :** l’agent lit-il `SKILL.md` avant utilisation et suit-il les étapes/arguments requis ?
+- **Contrats de workflow :** scénarios multi-tours qui vérifient l’ordre des outils, la conservation de l’historique de session et les limites du bac à sable.
-Les futures évaluations doivent d'abord rester déterministes :
+Les futures évaluations doivent d’abord rester déterministes :
-- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d'outils + leur ordre, les lectures de fichiers skill et le câblage des sessions.
-- Une petite suite de scénarios centrés sur les skills (utiliser vs éviter, barrières, injection de prompt).
-- Des évaluations live facultatives (optionnelles, contrôlées par env) uniquement après la mise en place de la suite sans danger pour la CI.
+- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + leur ordre, les lectures de fichiers de Skill et le câblage de session.
+- Une petite suite de scénarios centrés sur les Skills (utiliser vs éviter, gating, injection d’invite).
+- Des évaluations live facultatives (opt-in, contrôlées par env) uniquement après la mise en place de la suite compatible CI.
## Tests de contrat (forme des plugins et des canaux)
-Les tests de contrat vérifient que chaque plugin et canal enregistré respecte son
-contrat d'interface. Ils itèrent sur tous les plugins découverts et exécutent une suite de
+Les tests de contrat vérifient que chaque plugin et canal enregistré est conforme à son
+contrat d’interface. Ils itèrent sur tous les plugins découverts et exécutent une suite de
vérifications de forme et de comportement. La voie unitaire par défaut `pnpm test`
-ignore volontairement ces fichiers de smoke et de couture partagée ; exécutez les commandes de contrat explicitement
-lorsque vous touchez à des surfaces partagées de canal ou de fournisseur.
+ignore volontairement ces fichiers de jonction partagée et de smoke ; exécutez les commandes de contrat explicitement
+lorsque vous modifiez des surfaces partagées de canal ou de fournisseur.
### Commandes
-- Tous les contrats : `pnpm test:contracts`
-- Contrats de canaux uniquement : `pnpm test:contracts:channels`
-- Contrats de fournisseurs uniquement : `pnpm test:contracts:plugins`
+- Tous les contrats : `pnpm test:contracts`
+- Contrats de canal uniquement : `pnpm test:contracts:channels`
+- Contrats de fournisseur uniquement : `pnpm test:contracts:plugins`
-### Contrats de canaux
+### Contrats de canal
-Situés dans `src/channels/plugins/contracts/*.contract.test.ts` :
+Situés dans `src/channels/plugins/contracts/*.contract.test.ts` :
- **plugin** - Forme de base du plugin (id, nom, capacités)
-- **setup** - Contrat de l'assistant de configuration
+- **setup** - Contrat de l’assistant de configuration
- **session-binding** - Comportement de liaison de session
-- **outbound-payload** - Structure de charge utile du message
+- **outbound-payload** - Structure de la charge utile du message
- **inbound** - Gestion des messages entrants
-- **actions** - Gestionnaires d'actions du canal
-- **threading** - Gestion des ID de fil
-- **directory** - API d'annuaire/de registre
+- **actions** - Gestionnaires d’actions de canal
+- **threading** - Gestion des identifiants de fil
+- **directory** - API de répertoire/liste
- **group-policy** - Application de la politique de groupe
-### Contrats d'état des fournisseurs
+### Contrats d’état des fournisseurs
Situés dans `src/plugins/contracts/*.contract.test.ts`.
-- **status** - Sondes d'état des canaux
+- **status** - Sondes d’état de canal
- **registry** - Forme du registre de plugins
-### Contrats des fournisseurs
+### Contrats de fournisseur
-Situés dans `src/plugins/contracts/*.contract.test.ts` :
+Situés dans `src/plugins/contracts/*.contract.test.ts` :
-- **auth** - Contrat du flux d'authentification
-- **auth-choice** - Choix/sélection de l'authentification
+- **auth** - Contrat de flux d’authentification
+- **auth-choice** - Choix/sélection d’authentification
- **catalog** - API du catalogue de modèles
-- **discovery** - Découverte de plugins
-- **loader** - Chargement de plugins
-- **runtime** - Exécution du fournisseur
+- **discovery** - Découverte des plugins
+- **loader** - Chargement des plugins
+- **runtime** - Runtime du fournisseur
- **shape** - Forme/interface du plugin
- **wizard** - Assistant de configuration
### Quand les exécuter
-- Après avoir modifié des exports ou sous-chemins `plugin-sdk`
-- Après avoir ajouté ou modifié un plugin de canal ou de fournisseur
-- Après avoir refactorisé l'enregistrement ou la découverte des plugins
+- Après modification des exports ou sous-chemins plugin-sdk
+- Après ajout ou modification d’un plugin de canal ou de fournisseur
+- Après refactorisation de l’enregistrement ou de la découverte des plugins
-Les tests de contrat s'exécutent en CI et ne nécessitent pas de vraies clés API.
+Les tests de contrat s’exécutent en CI et ne nécessitent pas de vraies clés API.
-## Ajouter des régressions (guide)
+## Ajouter des régressions (recommandations)
-Lorsque vous corrigez un problème de fournisseur/modèle découvert en live :
+Lorsque vous corrigez un problème de fournisseur/modèle découvert en live :
-- Ajoutez si possible une régression sans danger pour la CI (simuler/stubber le fournisseur, ou capturer la transformation exacte de forme de requête)
-- Si le problème est intrinsèquement live-only (limites de débit, politiques d'auth), gardez le test live étroit et optionnel via des variables d'environnement
-- Préférez cibler la plus petite couche qui détecte le bug :
- - bug de conversion/rejeu de requête fournisseur → test de modèles directs
- - bug du pipeline session/historique/outils de la passerelle → smoke live de passerelle ou test mock de passerelle sans danger pour la CI
-- Garde-fou sur la traversée SecretRef :
- - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef à partir des métadonnées du registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec de segment de traversée sont rejetés.
- - Si vous ajoutez une nouvelle famille de cibles SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue volontairement sur les identifiants de cible non classifiés afin que de nouvelles classes ne puissent pas être ignorées silencieusement.
+- Ajoutez si possible une régression compatible CI (fournisseur simulé/stub, ou capture de la transformation exacte de la forme de requête)
+- Si le problème est intrinsèquement live uniquement (limites de débit, politiques d’authentification), gardez le test live étroit et opt-in via des variables d’environnement
+- Préférez cibler la plus petite couche qui détecte le bogue :
+ - bogue de conversion/relecture de requête fournisseur → test de modèles directs
+ - bogue de pipeline de session/historique/outils de la passerelle → smoke live de la passerelle ou test mock de passerelle compatible CI
+- Garde-fou de parcours SecretRef :
+ - `src/secrets/exec-secret-ref-id-parity.test.ts` dérive une cible échantillonnée par classe SecretRef à partir des métadonnées du registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec de segments de parcours sont rejetés.
+ - Si vous ajoutez une nouvelle famille de cibles SecretRef `includeInPlan` dans `src/secrets/target-registry-data.ts`, mettez à jour `classifyTargetClass` dans ce test. Le test échoue volontairement sur les identifiants de cible non classifiés afin que les nouvelles classes ne puissent pas être ignorées silencieusement.
diff --git a/docs/fr/reference/memory-config.md b/docs/fr/reference/memory-config.md
index 3252141ca..ba44c5f24 100644
--- a/docs/fr/reference/memory-config.md
+++ b/docs/fr/reference/memory-config.md
@@ -1,41 +1,51 @@
---
read_when:
- - Vous souhaitez configurer les fournisseurs de recherche mémoire ou les modèles d’embeddings
+ - Vous souhaitez configurer des fournisseurs de recherche en mémoire ou des modèles d’embeddings
- Vous souhaitez configurer le backend QMD
- Vous souhaitez ajuster la recherche hybride, le MMR ou la décroissance temporelle
- - Vous souhaitez activer l’indexation mémoire multimodale
-summary: Tous les paramètres de configuration pour la recherche mémoire, les fournisseurs d’embeddings, QMD, la recherche hybride et l’indexation multimodale
+ - Vous souhaitez activer l’indexation de mémoire multimodale
+summary: Tous les paramètres de configuration pour la recherche en mémoire, les fournisseurs d’embeddings, QMD, la recherche hybride et l’indexation multimodale
title: Référence de configuration de la mémoire
x-i18n:
- generated_at: "2026-04-06T03:13:33Z"
+ generated_at: "2026-04-10T06:56:10Z"
model: gpt-5.4
provider: openai
- source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
+ source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
source_path: reference/memory-config.md
workflow: 15
---
# Référence de configuration de la mémoire
-Cette page répertorie tous les paramètres de configuration de la recherche mémoire d’OpenClaw. Pour des aperçus conceptuels, voir :
+Cette page répertorie tous les paramètres de configuration pour la recherche en mémoire d’OpenClaw. Pour des aperçus conceptuels, voir :
- [Vue d’ensemble de la mémoire](/fr/concepts/memory) -- fonctionnement de la mémoire
- [Moteur intégré](/fr/concepts/memory-builtin) -- backend SQLite par défaut
- [Moteur QMD](/fr/concepts/memory-qmd) -- sidecar local-first
-- [Recherche mémoire](/fr/concepts/memory-search) -- pipeline de recherche et réglages
+- [Recherche en mémoire](/fr/concepts/memory-search) -- pipeline de recherche et ajustement
+- [Mémoire active](/fr/concepts/active-memory) -- activer le sous-agent de mémoire pour les sessions interactives
-Tous les paramètres de recherche mémoire se trouvent sous `agents.defaults.memorySearch` dans `openclaw.json`, sauf indication contraire.
+Tous les paramètres de recherche en mémoire se trouvent sous `agents.defaults.memorySearch` dans `openclaw.json`, sauf indication contraire.
+
+Si vous recherchez le bouton de fonctionnalité **mémoire active** et la configuration du sous-agent, ils se trouvent sous `plugins.entries.active-memory` au lieu de `memorySearch`.
+
+La mémoire active utilise un modèle à deux conditions :
+
+1. le plugin doit être activé et cibler l’ID de l’agent actuel
+2. la requête doit être une session de chat interactive persistante éligible
+
+Voir [Mémoire active](/fr/concepts/active-memory) pour le modèle d’activation, la configuration gérée par le plugin, la persistance des transcriptions et le modèle de déploiement sûr.
---
## Sélection du fournisseur
-| Key | Type | Default | Description |
-| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- |
-| `provider` | `string` | détection automatique | ID de l’adaptateur d’embeddings : `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
-| `model` | `string` | défaut du fournisseur | Nom du modèle d’embeddings |
-| `fallback` | `string` | `"none"` | ID de l’adaptateur de secours lorsque le primaire échoue |
-| `enabled` | `boolean` | `true` | Activer ou désactiver la recherche mémoire |
+| Clé | Type | Par défaut | Description |
+| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------------- |
+| `provider` | `string` | détecté automatiquement | ID de l’adaptateur d’embeddings : `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
+| `model` | `string` | valeur par défaut du fournisseur | Nom du modèle d’embeddings |
+| `fallback` | `string` | `"none"` | ID de l’adaptateur de secours en cas d’échec du principal |
+| `enabled` | `boolean` | `true` | Activer ou désactiver la recherche en mémoire |
### Ordre de détection automatique
@@ -48,33 +58,33 @@ Lorsque `provider` n’est pas défini, OpenClaw sélectionne le premier disponi
5. `mistral` -- si une clé Mistral peut être résolue.
6. `bedrock` -- si la chaîne d’identifiants AWS SDK est résolue (rôle d’instance, clés d’accès, profil, SSO, identité web ou configuration partagée).
-`ollama` est pris en charge, mais n’est pas détecté automatiquement (définissez-le explicitement).
+`ollama` est pris en charge mais n’est pas détecté automatiquement (définissez-le explicitement).
-### Résolution de clé API
+### Résolution des clés API
-Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut de l’AWS SDK (rôles d’instance, SSO, clés d’accès).
+Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut du SDK AWS (rôles d’instance, SSO, clés d’accès).
-| Provider | Env var | Config key |
-| -------- | ------------------------------ | --------------------------------- |
-| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
-| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
-| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
-| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
-| Bedrock | chaîne d’identifiants AWS | Aucune clé API nécessaire |
-| Ollama | `OLLAMA_API_KEY` (espace réservé) | -- |
+| Fournisseur | Variable d’environnement | Clé de configuration |
+| ----------- | ------------------------------ | --------------------------------- |
+| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
+| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
+| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
+| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
+| Bedrock | chaîne d’identifiants AWS | Aucune clé API nécessaire |
+| Ollama | `OLLAMA_API_KEY` (espace réservé) | -- |
-Codex OAuth couvre uniquement le chat/les complétions et ne satisfait pas les requêtes d’embeddings.
+L’authentification OAuth de Codex couvre uniquement le chat/les complétions et ne satisfait pas les requêtes d’embeddings.
---
-## Configuration des endpoints distants
+## Configuration des points de terminaison distants
-Pour des endpoints compatibles OpenAI personnalisés ou pour remplacer les valeurs par défaut du fournisseur :
+Pour des points de terminaison personnalisés compatibles OpenAI ou pour remplacer les valeurs par défaut du fournisseur :
-| Key | Type | Description |
-| ---------------- | -------- | -------------------------------------------------- |
-| `remote.baseUrl` | `string` | URL de base API personnalisée |
-| `remote.apiKey` | `string` | Remplacer la clé API |
+| Clé | Type | Description |
+| ---------------- | -------- | ------------------------------------------------ |
+| `remote.baseUrl` | `string` | URL de base de l’API personnalisée |
+| `remote.apiKey` | `string` | Remplacer la clé API |
| `remote.headers` | `object` | En-têtes HTTP supplémentaires (fusionnés avec les valeurs par défaut du fournisseur) |
```json5
@@ -98,20 +108,20 @@ Pour des endpoints compatibles OpenAI personnalisés ou pour remplacer les valeu
## Configuration spécifique à Gemini
-| Key | Type | Default | Description |
-| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
-| `model` | `string` | `gemini-embedding-001` | Prend aussi en charge `gemini-embedding-2-preview` |
-| `outputDimensionality` | `number` | `3072` | Pour Embedding 2 : 768, 1536 ou 3072 |
+| Clé | Type | Par défaut | Description |
+| ---------------------- | -------- | --------------------- | ------------------------------------------ |
+| `model` | `string` | `gemini-embedding-001` | Prend également en charge `gemini-embedding-2-preview` |
+| `outputDimensionality` | `number` | `3072` | Pour Embedding 2 : 768, 1536 ou 3072 |
-Modifier le modèle ou `outputDimensionality` déclenche une réindexation complète automatique.
+La modification du modèle ou de `outputDimensionality` déclenche automatiquement une réindexation complète.
---
## Configuration des embeddings Bedrock
-Bedrock utilise la chaîne d’identifiants par défaut de l’AWS SDK -- aucune clé API nécessaire.
+Bedrock utilise la chaîne d’identifiants par défaut du SDK AWS -- aucune clé API n’est nécessaire.
Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock, définissez simplement le fournisseur et le modèle :
```json5
@@ -127,41 +137,41 @@ Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock
}
```
-| Key | Type | Default | Description |
-| ---------------------- | -------- | ------------------------------ | ------------------------------- |
-| `model` | `string` | `amazon.titan-embed-text-v2:0` | Tout ID de modèle d’embeddings Bedrock |
-| `outputDimensionality` | `number` | valeur par défaut du modèle | Pour Titan V2 : 256, 512 ou 1024 |
+| Clé | Type | Par défaut | Description |
+| ---------------------- | -------- | ----------------------------- | ------------------------------------ |
+| `model` | `string` | `amazon.titan-embed-text-v2:0` | Tout ID de modèle d’embeddings Bedrock |
+| `outputDimensionality` | `number` | valeur par défaut du modèle | Pour Titan V2 : 256, 512 ou 1024 |
### Modèles pris en charge
-Les modèles suivants sont pris en charge (avec détection de famille et valeurs dimensionnelles par défaut) :
+Les modèles suivants sont pris en charge (avec détection de famille et dimensions par défaut) :
-| Model ID | Provider | Default Dims | Configurable Dims |
-| ------------------------------------------ | ---------- | ------------ | -------------------- |
-| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
-| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
-| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
-| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
-| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
-| `cohere.embed-english-v3` | Cohere | 1024 | -- |
-| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
-| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
-| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
-| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
+| ID du modèle | Fournisseur | Dimensions par défaut | Dimensions configurables |
+| ------------------------------------------- | ----------- | --------------------- | ------------------------ |
+| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
+| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
+| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
+| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
+| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
+| `cohere.embed-english-v3` | Cohere | 1024 | -- |
+| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
+| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
+| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
+| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
-Les variantes suffixées par débit (par exemple `amazon.titan-embed-text-v1:2:8k`) héritent de la configuration du modèle de base.
+Les variantes avec suffixe de débit (par exemple, `amazon.titan-embed-text-v1:2:8k`) héritent de la configuration du modèle de base.
### Authentification
-L’authentification Bedrock utilise l’ordre de résolution standard des identifiants de l’AWS SDK :
+L’authentification Bedrock utilise l’ordre standard de résolution des identifiants du SDK AWS :
1. Variables d’environnement (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
-2. Cache de jetons SSO
+2. Cache des jetons SSO
3. Identifiants de jeton d’identité web
4. Fichiers partagés d’identifiants et de configuration
5. Identifiants de métadonnées ECS ou EC2
-La région est résolue à partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, du `baseUrl` du fournisseur `amazon-bedrock`, ou prend par défaut `us-east-1`.
+La région est résolue à partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, du `baseUrl` du fournisseur `amazon-bedrock`, ou utilise par défaut `us-east-1`.
### Autorisations IAM
@@ -185,42 +195,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
## Configuration des embeddings locaux
-| Key | Type | Default | Description |
-| --------------------- | -------- | ---------------------- | ------------------------------- |
-| `local.modelPath` | `string` | téléchargement automatique | Chemin vers le fichier modèle GGUF |
+| Clé | Type | Par défaut | Description |
+| --------------------- | -------- | ---------------------- | ------------------------------------- |
+| `local.modelPath` | `string` | téléchargé automatiquement | Chemin vers le fichier de modèle GGUF |
| `local.modelCacheDir` | `string` | valeur par défaut de node-llama-cpp | Répertoire de cache pour les modèles téléchargés |
-Modèle par défaut : `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 Go, téléchargé automatiquement).
+Modèle par défaut : `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, téléchargé automatiquement).
Nécessite une build native : `pnpm approve-builds` puis `pnpm rebuild node-llama-cpp`.
---
## Configuration de la recherche hybride
-Tous sous `memorySearch.query.hybrid` :
+Le tout sous `memorySearch.query.hybrid` :
-| Key | Type | Default | Description |
-| --------------------- | --------- | ------- | ---------------------------------- |
-| `enabled` | `boolean` | `true` | Activer la recherche hybride BM25 + vectorielle |
-| `vectorWeight` | `number` | `0.7` | Poids des scores vectoriels (0-1) |
-| `textWeight` | `number` | `0.3` | Poids des scores BM25 (0-1) |
-| `candidateMultiplier` | `number` | `4` | Multiplicateur de taille du pool de candidats |
+| Clé | Type | Par défaut | Description |
+| --------------------- | --------- | ---------- | ---------------------------------------- |
+| `enabled` | `boolean` | `true` | Activer la recherche hybride BM25 + vectorielle |
+| `vectorWeight` | `number` | `0.7` | Poids des scores vectoriels (0-1) |
+| `textWeight` | `number` | `0.3` | Poids des scores BM25 (0-1) |
+| `candidateMultiplier` | `number` | `4` | Multiplicateur de taille du pool de candidats |
### MMR (diversité)
-| Key | Type | Default | Description |
-| ------------- | --------- | ------- | ------------------------------------ |
-| `mmr.enabled` | `boolean` | `false` | Activer le reclassement MMR |
-| `mmr.lambda` | `number` | `0.7` | 0 = diversité maximale, 1 = pertinence maximale |
+| Clé | Type | Par défaut | Description |
+| ------------- | --------- | ---------- | ------------------------------------------- |
+| `mmr.enabled` | `boolean` | `false` | Activer le reranking MMR |
+| `mmr.lambda` | `number` | `0.7` | 0 = diversité maximale, 1 = pertinence maximale |
### Décroissance temporelle (récence)
-| Key | Type | Default | Description |
-| ---------------------------- | --------- | ------- | ------------------------- |
-| `temporalDecay.enabled` | `boolean` | `false` | Activer le boost de récence |
-| `temporalDecay.halfLifeDays` | `number` | `30` | Le score est divisé par deux tous les N jours |
+| Clé | Type | Par défaut | Description |
+| ---------------------------- | --------- | ---------- | ----------------------------------- |
+| `temporalDecay.enabled` | `boolean` | `false` | Activer le boost de récence |
+| `temporalDecay.halfLifeDays` | `number` | `30` | Le score est divisé par deux tous les N jours |
-Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subissent jamais de décroissance.
+Les fichiers persistants (`MEMORY.md`, fichiers non datés dans `memory/`) ne subissent jamais de décroissance.
### Exemple complet
@@ -245,10 +255,10 @@ Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subi
---
-## Chemins mémoire supplémentaires
+## Chemins de mémoire supplémentaires
-| Key | Type | Description |
-| ------------ | ---------- | ---------------------------------------- |
+| Clé | Type | Description |
+| ------------ | ---------- | -------------------------------------------- |
| `extraPaths` | `string[]` | Répertoires ou fichiers supplémentaires à indexer |
```json5
@@ -266,13 +276,9 @@ Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subi
Les chemins peuvent être absolus ou relatifs à l’espace de travail. Les répertoires sont analysés récursivement à la recherche de fichiers `.md`. La gestion des liens symboliques dépend du backend actif :
le moteur intégré ignore les liens symboliques, tandis que QMD suit le comportement du scanner QMD sous-jacent.
-Pour la recherche de transcriptions inter-agents à portée d’agent, utilisez
-`agents.list[].memorySearch.qmd.extraCollections` au lieu de `memory.qmd.paths`.
-Ces collections supplémentaires suivent la même forme `{ path, name, pattern? }`, mais
-elles sont fusionnées par agent et peuvent conserver des noms partagés explicites lorsque le chemin
-pointe en dehors de l’espace de travail actuel.
-Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et
-`memorySearch.qmd.extraCollections`, QMD conserve la première entrée et ignore le doublon.
+Pour la recherche de transcriptions inter-agents à portée d’agent, utilisez `agents.list[].memorySearch.qmd.extraCollections` au lieu de `memory.qmd.paths`.
+Ces collections supplémentaires suivent la même forme `{ path, name, pattern? }`, mais elles sont fusionnées par agent et peuvent conserver des noms partagés explicites lorsque le chemin pointe en dehors de l’espace de travail actuel.
+Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et dans `memorySearch.qmd.extraCollections`, QMD conserve la première entrée et ignore le doublon.
---
@@ -280,13 +286,13 @@ Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et
Indexez les images et l’audio en plus du Markdown à l’aide de Gemini Embedding 2 :
-| Key | Type | Default | Description |
-| ------------------------- | ---------- | ---------- | -------------------------------------- |
-| `multimodal.enabled` | `boolean` | `false` | Activer l’indexation multimodale |
-| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
-| `multimodal.maxFileBytes` | `number` | `10000000` | Taille maximale de fichier pour l’indexation |
+| Clé | Type | Par défaut | Description |
+| ------------------------- | ---------- | ---------- | ------------------------------------------- |
+| `multimodal.enabled` | `boolean` | `false` | Activer l’indexation multimodale |
+| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
+| `multimodal.maxFileBytes` | `number` | `10000000` | Taille maximale des fichiers pour l’indexation |
-S’applique uniquement aux fichiers dans `extraPaths`. Les racines mémoire par défaut restent limitées au Markdown.
+S’applique uniquement aux fichiers dans `extraPaths`. Les racines de mémoire par défaut restent limitées au Markdown.
Nécessite `gemini-embedding-2-preview`. `fallback` doit être `"none"`.
Formats pris en charge : `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
@@ -294,119 +300,109 @@ Formats pris en charge : `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.he
---
-## Cache d’embeddings
+## Cache des embeddings
-| Key | Type | Default | Description |
-| ------------------ | --------- | ------- | -------------------------------- |
-| `cache.enabled` | `boolean` | `false` | Mettre en cache les embeddings de segments dans SQLite |
-| `cache.maxEntries` | `number` | `50000` | Nombre maximal d’embeddings en cache |
+| Clé | Type | Par défaut | Description |
+| ------------------ | --------- | ---------- | ---------------------------------------- |
+| `cache.enabled` | `boolean` | `false` | Mettre en cache les embeddings de fragments dans SQLite |
+| `cache.maxEntries` | `number` | `50000` | Nombre maximal d’embeddings mis en cache |
-Empêche de réintégrer les textes inchangés lors de la réindexation ou des mises à jour de transcriptions.
+Empêche de recalculer les embeddings d’un texte inchangé lors d’une réindexation ou de mises à jour de transcriptions.
---
-## Indexation par lots
+## Indexation par lot
-| Key | Type | Default | Description |
-| ----------------------------- | --------- | ------- | -------------------------- |
-| `remote.batch.enabled` | `boolean` | `false` | Activer l’API d’embeddings par lots |
-| `remote.batch.concurrency` | `number` | `2` | Tâches par lots parallèles |
-| `remote.batch.wait` | `boolean` | `true` | Attendre la fin du lot |
-| `remote.batch.pollIntervalMs` | `number` | -- | Intervalle d’interrogation |
-| `remote.batch.timeoutMinutes` | `number` | -- | Délai d’expiration du lot |
+| Clé | Type | Par défaut | Description |
+| ----------------------------- | --------- | ---------- | -------------------------------- |
+| `remote.batch.enabled` | `boolean` | `false` | Activer l’API d’embeddings par lot |
+| `remote.batch.concurrency` | `number` | `2` | Tâches par lot parallèles |
+| `remote.batch.wait` | `boolean` | `true` | Attendre la fin du lot |
+| `remote.batch.pollIntervalMs` | `number` | -- | Intervalle d’interrogation |
+| `remote.batch.timeoutMinutes` | `number` | -- | Délai d’expiration du lot |
-Disponible pour `openai`, `gemini` et `voyage`. Les lots OpenAI sont généralement
-les plus rapides et les moins chers pour les remplissages initiaux volumineux.
+Disponible pour `openai`, `gemini` et `voyage`. Le traitement par lot OpenAI est généralement le plus rapide et le moins cher pour les gros remplissages rétroactifs.
---
-## Recherche mémoire de session (expérimental)
+## Recherche en mémoire de session (expérimental)
Indexez les transcriptions de session et exposez-les via `memory_search` :
-| Key | Type | Default | Description |
-| ----------------------------- | ---------- | ------------ | --------------------------------------- |
-| `experimental.sessionMemory` | `boolean` | `false` | Activer l’indexation des sessions |
-| `sources` | `string[]` | `["memory"]` | Ajoutez `"sessions"` pour inclure les transcriptions |
-| `sync.sessions.deltaBytes` | `number` | `100000` | Seuil en octets pour la réindexation |
-| `sync.sessions.deltaMessages` | `number` | `50` | Seuil en messages pour la réindexation |
+| Clé | Type | Par défaut | Description |
+| ----------------------------- | ---------- | ------------ | -------------------------------------------- |
+| `experimental.sessionMemory` | `boolean` | `false` | Activer l’indexation des sessions |
+| `sources` | `string[]` | `["memory"]` | Ajouter `"sessions"` pour inclure les transcriptions |
+| `sync.sessions.deltaBytes` | `number` | `100000` | Seuil en octets pour la réindexation |
+| `sync.sessions.deltaMessages` | `number` | `50` | Seuil en messages pour la réindexation |
-L’indexation des sessions est opt-in et s’exécute de façon asynchrone. Les résultats peuvent être légèrement
-obsolètes. Les journaux de session se trouvent sur le disque, traitez donc l’accès au système de fichiers comme frontière de confiance.
+L’indexation des sessions est optionnelle et s’exécute de façon asynchrone. Les résultats peuvent être légèrement obsolètes. Les journaux de session sont stockés sur le disque, considérez donc l’accès au système de fichiers comme la frontière de confiance.
---
## Accélération vectorielle SQLite (sqlite-vec)
-| Key | Type | Default | Description |
-| ---------------------------- | --------- | ------- | --------------------------------- |
-| `store.vector.enabled` | `boolean` | `true` | Utiliser sqlite-vec pour les requêtes vectorielles |
-| `store.vector.extensionPath` | `string` | intégré | Remplacer le chemin sqlite-vec |
+| Clé | Type | Par défaut | Description |
+| ---------------------------- | --------- | ---------- | ------------------------------------------ |
+| `store.vector.enabled` | `boolean` | `true` | Utiliser sqlite-vec pour les requêtes vectorielles |
+| `store.vector.extensionPath` | `string` | intégré | Remplacer le chemin de sqlite-vec |
-Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la
-similarité cosinus en processus.
+Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la similarité cosinus en processus.
---
## Stockage de l’index
-| Key | Type | Default | Description |
-| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
+| Clé | Type | Par défaut | Description |
+| --------------------- | -------- | ------------------------------------- | ------------------------------------------------ |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Emplacement de l’index (prend en charge le jeton `{agentId}`) |
-| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` ou `trigram`) |
+| `store.fts.tokenizer` | `string` | `unicode61` | Tokeniseur FTS5 (`unicode61` ou `trigram`) |
---
## Configuration du backend QMD
-Définissez `memory.backend = "qmd"` pour l’activer. Tous les paramètres QMD se trouvent sous
-`memory.qmd` :
+Définissez `memory.backend = "qmd"` pour l’activer. Tous les paramètres QMD se trouvent sous `memory.qmd` :
-| Key | Type | Default | Description |
-| ------------------------ | --------- | -------- | -------------------------------------------- |
-| `command` | `string` | `qmd` | Chemin de l’exécutable QMD |
-| `searchMode` | `string` | `search` | Commande de recherche : `search`, `vsearch`, `query` |
-| `includeDefaultMemory` | `boolean` | `true` | Indexer automatiquement `MEMORY.md` + `memory/**/*.md` |
-| `paths[]` | `array` | -- | Chemins supplémentaires : `{ name, path, pattern? }` |
-| `sessions.enabled` | `boolean` | `false` | Indexer les transcriptions de session |
-| `sessions.retentionDays` | `number` | -- | Rétention des transcriptions |
-| `sessions.exportDir` | `string` | -- | Répertoire d’exportation |
+| Clé | Type | Par défaut | Description |
+| ------------------------ | --------- | ---------- | ------------------------------------------------ |
+| `command` | `string` | `qmd` | Chemin de l’exécutable QMD |
+| `searchMode` | `string` | `search` | Commande de recherche : `search`, `vsearch`, `query` |
+| `includeDefaultMemory` | `boolean` | `true` | Indexer automatiquement `MEMORY.md` + `memory/**/*.md` |
+| `paths[]` | `array` | -- | Chemins supplémentaires : `{ name, path, pattern? }` |
+| `sessions.enabled` | `boolean` | `false` | Indexer les transcriptions de session |
+| `sessions.retentionDays` | `number` | -- | Rétention des transcriptions |
+| `sessions.exportDir` | `string` | -- | Répertoire d’exportation |
-OpenClaw privilégie la collection QMD actuelle et les formes de requête MCP, mais conserve
-la compatibilité avec les anciennes versions de QMD en revenant si nécessaire aux indicateurs de collection hérités `--mask`
-et aux anciens noms d’outils MCP.
+OpenClaw privilégie les formes actuelles de collection QMD et de requête MCP, mais maintient les anciennes versions de QMD fonctionnelles en revenant si nécessaire aux indicateurs de collection hérités `--mask` et aux anciens noms d’outils MCP.
-Les remplacements de modèle QMD restent du côté QMD, pas dans la configuration OpenClaw. Si vous devez
-remplacer globalement les modèles de QMD, définissez des variables d’environnement telles que
-`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` et `QMD_GENERATE_MODEL` dans l’environnement d’exécution
-de la passerelle.
+Les remplacements de modèle QMD restent du côté de QMD, pas dans la configuration d’OpenClaw. Si vous devez remplacer globalement les modèles de QMD, définissez des variables d’environnement telles que `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` et `QMD_GENERATE_MODEL` dans l’environnement d’exécution de la passerelle.
-### Planning de mise à jour
+### Planification des mises à jour
-| Key | Type | Default | Description |
-| ------------------------- | --------- | ------- | ------------------------------------- |
-| `update.interval` | `string` | `5m` | Intervalle de rafraîchissement |
-| `update.debounceMs` | `number` | `15000` | Anti-rebond des changements de fichiers |
-| `update.onBoot` | `boolean` | `true` | Rafraîchir au démarrage |
-| `update.waitForBootSync` | `boolean` | `false` | Bloquer le démarrage jusqu’à la fin du rafraîchissement |
-| `update.embedInterval` | `string` | -- | Cadence d’embedding distincte |
-| `update.commandTimeoutMs` | `number` | -- | Délai d’expiration des commandes QMD |
-| `update.updateTimeoutMs` | `number` | -- | Délai d’expiration des opérations de mise à jour QMD |
-| `update.embedTimeoutMs` | `number` | -- | Délai d’expiration des opérations d’embedding QMD |
+| Clé | Type | Par défaut | Description |
+| ------------------------- | --------- | ---------- | -------------------------------------------- |
+| `update.interval` | `string` | `5m` | Intervalle d’actualisation |
+| `update.debounceMs` | `number` | `15000` | Antirebond des changements de fichiers |
+| `update.onBoot` | `boolean` | `true` | Actualiser au démarrage |
+| `update.waitForBootSync` | `boolean` | `false` | Bloquer le démarrage jusqu’à la fin de l’actualisation |
+| `update.embedInterval` | `string` | -- | Cadence d’embedding distincte |
+| `update.commandTimeoutMs` | `number` | -- | Délai d’expiration pour les commandes QMD |
+| `update.updateTimeoutMs` | `number` | -- | Délai d’expiration pour les opérations de mise à jour QMD |
+| `update.embedTimeoutMs` | `number` | -- | Délai d’expiration pour les opérations d’embedding QMD |
### Limites
-| Key | Type | Default | Description |
-| ------------------------- | -------- | ------- | -------------------------- |
-| `limits.maxResults` | `number` | `6` | Nombre maximal de résultats de recherche |
-| `limits.maxSnippetChars` | `number` | -- | Limiter la longueur des extraits |
-| `limits.maxInjectedChars` | `number` | -- | Limiter le total des caractères injectés |
-| `limits.timeoutMs` | `number` | `4000` | Délai d’expiration de la recherche |
+| Clé | Type | Par défaut | Description |
+| ------------------------- | -------- | ---------- | ------------------------------- |
+| `limits.maxResults` | `number` | `6` | Nombre maximal de résultats de recherche |
+| `limits.maxSnippetChars` | `number` | -- | Limiter la longueur des extraits |
+| `limits.maxInjectedChars` | `number` | -- | Limiter le total de caractères injectés |
+| `limits.timeoutMs` | `number` | `4000` | Délai d’expiration de la recherche |
### Portée
-Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que
-[`session.sendPolicy`](/fr/gateway/configuration-reference#session) :
+Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que [`session.sendPolicy`](/fr/gateway/configuration-reference#session) :
```json5
{
@@ -421,20 +417,20 @@ Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Mê
}
```
-Par défaut, DM uniquement. `match.keyPrefix` correspond à la clé de session normalisée ;
+La valeur par défaut est DM-only. `match.keyPrefix` correspond à la clé de session normalisée ;
`match.rawKeyPrefix` correspond à la clé brute, y compris `agent::`.
### Citations
`memory.citations` s’applique à tous les backends :
-| Value | Behavior |
+| Valeur | Comportement |
| ---------------- | --------------------------------------------------- |
-| `auto` (par défaut) | Inclure un pied de page `Source: ` dans les extraits |
-| `on` | Toujours inclure le pied de page |
-| `off` | Omettre le pied de page (le chemin est tout de même transmis à l’agent en interne) |
+| `auto` (par défaut) | Inclure un pied de page `Source: ` dans les extraits |
+| `on` | Toujours inclure le pied de page |
+| `off` | Omettre le pied de page (le chemin est toujours transmis à l’agent en interne) |
-### Exemple QMD complet
+### Exemple complet QMD
```json5
{
@@ -459,20 +455,18 @@ Par défaut, DM uniquement. `match.keyPrefix` correspond à la clé de session n
## Dreaming (expérimental)
-Dreaming se configure sous `plugins.entries.memory-core.config.dreaming`,
-et non sous `agents.defaults.memorySearch`.
+Dreaming est configuré sous `plugins.entries.memory-core.config.dreaming`, et non sous `agents.defaults.memorySearch`.
-Dreaming s’exécute comme un balayage planifié unique et utilise en interne des phases light/deep/REM comme
-détail d’implémentation.
+Dreaming s’exécute comme un balayage planifié unique et utilise des phases internes léger/profond/REM comme détail d’implémentation.
Pour le comportement conceptuel et les commandes slash, voir [Dreaming](/fr/concepts/dreaming).
### Paramètres utilisateur
-| Key | Type | Default | Description |
-| ----------- | --------- | ----------- | ------------------------------------------------- |
-| `enabled` | `boolean` | `false` | Activer ou désactiver entièrement Dreaming |
-| `frequency` | `string` | `0 3 * * *` | Cadence cron facultative pour le balayage complet de Dreaming |
+| Clé | Type | Par défaut | Description |
+| ----------- | --------- | ----------- | ---------------------------------------------------- |
+| `enabled` | `boolean` | `false` | Activer ou désactiver complètement dreaming |
+| `frequency` | `string` | `0 3 * * *` | Cadence cron optionnelle pour le balayage complet de dreaming |
### Exemple
@@ -496,5 +490,5 @@ Pour le comportement conceptuel et les commandes slash, voir [Dreaming](/fr/conc
Remarques :
- Dreaming écrit l’état machine dans `memory/.dreams/`.
-- Dreaming écrit une sortie narrative lisible par l’humain dans `DREAMS.md` (ou le fichier existant `dreams.md`).
-- La stratégie des phases light/deep/REM et les seuils sont des comportements internes, pas une configuration destinée à l’utilisateur.
+- Dreaming écrit une sortie narrative lisible par un humain dans `DREAMS.md` (ou `dreams.md` existant).
+- La stratégie de phase léger/profond/REM et les seuils sont des comportements internes, pas une configuration destinée à l’utilisateur.
diff --git a/docs/fr/tools/browser.md b/docs/fr/tools/browser.md
index be8c13f73..5320cc958 100644
--- a/docs/fr/tools/browser.md
+++ b/docs/fr/tools/browser.md
@@ -1,41 +1,38 @@
---
read_when:
- - Ajout d'une automatisation de navigateur contrôlée par l'agent
- - Débogage pour comprendre pourquoi openclaw interfère avec votre propre Chrome
- - Implémentation des paramètres et du cycle de vie du navigateur dans l'application macOS
-summary: Service intégré de contrôle du navigateur + commandes d'action
+ - Ajout de l’automatisation du navigateur contrôlée par l’agent
+ - Débogage des raisons pour lesquelles openclaw interfère avec votre propre Chrome
+ - Implémentation des paramètres et du cycle de vie du navigateur dans l’app macOS
+summary: Service de contrôle du navigateur intégré + commandes d’action
title: Navigateur (géré par OpenClaw)
x-i18n:
- generated_at: "2026-04-05T12:57:11Z"
+ generated_at: "2026-04-10T06:56:21Z"
model: gpt-5.4
provider: openai
- source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
+ source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
source_path: tools/browser.md
workflow: 15
---
# Navigateur (géré par openclaw)
-OpenClaw peut exécuter un **profil Chrome/Brave/Edge/Chromium dédié** contrôlé par l'agent.
-Il est isolé de votre navigateur personnel et est géré par un petit service local
-de contrôle à l'intérieur du Gateway (loopback uniquement).
+OpenClaw peut exécuter un **profil Chrome/Brave/Edge/Chromium dédié** que l’agent contrôle. Il est isolé de votre navigateur personnel et est géré via un petit service de contrôle local à l’intérieur de la Gateway (loopback uniquement).
-Vue débutant :
+Vue débutant :
-- Considérez-le comme un **navigateur séparé, réservé à l'agent**.
+- Voyez-le comme un **navigateur séparé, réservé à l’agent**.
- Le profil `openclaw` ne touche **pas** à votre profil de navigateur personnel.
-- L'agent peut **ouvrir des onglets, lire des pages, cliquer et saisir** dans un environnement sûr.
-- Le profil intégré `user` se connecte à votre véritable session Chrome connectée via Chrome MCP.
+- L’agent peut **ouvrir des onglets, lire des pages, cliquer et saisir du texte** dans un espace sûr.
+- Le profil `user` intégré se rattache à votre vraie session Chrome connectée via Chrome MCP.
## Ce que vous obtenez
- Un profil de navigateur séparé nommé **openclaw** (accent orange par défaut).
-- Contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
-- Actions de l'agent (cliquer/saisir/faire glisser/sélectionner), snapshots, captures d'écran, PDF.
-- Prise en charge facultative de plusieurs profils (`openclaw`, `work`, `remote`, ...).
+- Un contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
+- Des actions d’agent (cliquer/saisir/faire glisser/sélectionner), des instantanés, des captures d’écran, des PDF.
+- Une prise en charge facultative de plusieurs profils (`openclaw`, `work`, `remote`, ...).
-Ce navigateur n'est **pas** votre navigateur principal au quotidien. C'est une surface sûre et isolée pour
-l'automatisation et la vérification par l'agent.
+Ce navigateur n’est **pas** votre navigateur principal au quotidien. C’est une surface sûre et isolée pour l’automatisation et la vérification par l’agent.
## Démarrage rapide
@@ -46,17 +43,13 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
-Si vous obtenez « Browser disabled », activez-le dans la configuration (voir ci-dessous) et redémarrez le
-Gateway.
+Si vous obtenez « Browser disabled », activez-le dans la configuration (voir ci-dessous) et redémarrez la Gateway.
-Si `openclaw browser` a complètement disparu, ou si l'agent indique que l'outil de navigateur
-n'est pas disponible, passez à [Commande ou outil de navigateur manquant](/tools/browser#missing-browser-command-or-tool).
+Si `openclaw browser` a entièrement disparu, ou si l’agent indique que l’outil de navigateur est indisponible, passez à [Commande ou outil de navigateur manquant](/fr/tools/browser#missing-browser-command-or-tool).
-## Contrôle du plugin
+## Contrôle des plugins
-L'outil `browser` par défaut est désormais un plugin intégré livré activé par
-défaut. Cela signifie que vous pouvez le désactiver ou le remplacer sans supprimer le reste du
-système de plugins d'OpenClaw :
+L’outil `browser` par défaut est maintenant un plugin groupé livré activé par défaut. Cela signifie que vous pouvez le désactiver ou le remplacer sans supprimer le reste du système de plugins d’OpenClaw :
```json5
{
@@ -70,33 +63,22 @@ système de plugins d'OpenClaw :
}
```
-Désactivez le plugin intégré avant d'installer un autre plugin qui fournit le
-même nom d'outil `browser`. L'expérience de navigateur par défaut nécessite les deux éléments suivants :
+Désactivez le plugin groupé avant d’installer un autre plugin qui fournit le même nom d’outil `browser`. L’expérience de navigateur par défaut nécessite les deux :
- `plugins.entries.browser.enabled` non désactivé
- `browser.enabled=true`
-Si vous désactivez uniquement le plugin, la CLI de navigateur intégrée (`openclaw browser`),
-la méthode gateway (`browser.request`), l'outil de l'agent et le service de contrôle du navigateur par défaut
-disparaissent tous ensemble. Votre configuration `browser.*` reste intacte pour qu'un
-plugin de remplacement puisse la réutiliser.
+Si vous désactivez uniquement le plugin, la CLI de navigateur groupée (`openclaw browser`), la méthode Gateway (`browser.request`), l’outil d’agent et le service de contrôle du navigateur par défaut disparaissent tous ensemble. Votre configuration `browser.*` reste intacte afin qu’un plugin de remplacement puisse la réutiliser.
-Le plugin de navigateur intégré possède désormais aussi l'implémentation d'exécution du navigateur.
-Le cœur ne conserve que les helpers partagés du Plugin SDK ainsi que des réexportations de compatibilité pour les
-anciens chemins d'importation internes. En pratique, supprimer ou remplacer le package du plugin de navigateur
-supprime l'ensemble des fonctionnalités du navigateur au lieu de laisser derrière lui un second runtime
-appartenant au cœur.
+Le plugin de navigateur groupé possède désormais aussi l’implémentation d’exécution du navigateur. Le noyau ne conserve que les assistants partagés du Plugin SDK ainsi que des réexportations de compatibilité pour les anciens chemins d’importation internes. En pratique, supprimer ou remplacer le package du plugin de navigateur supprime l’ensemble des fonctionnalités du navigateur au lieu de laisser derrière lui un second runtime appartenant au noyau.
-Les modifications de configuration du navigateur nécessitent toujours un redémarrage du Gateway afin que le plugin intégré
-puisse réenregistrer son service de navigateur avec les nouveaux paramètres.
+Les changements de configuration du navigateur nécessitent toujours un redémarrage de la Gateway afin que le plugin groupé puisse réenregistrer son service de navigateur avec les nouveaux paramètres.
## Commande ou outil de navigateur manquant
-Si `openclaw browser` devient soudainement une commande inconnue après une mise à niveau, ou
-si l'agent signale que l'outil de navigateur est manquant, la cause la plus fréquente est une liste
-`plugins.allow` restrictive qui n'inclut pas `browser`.
+Si `openclaw browser` devient soudainement une commande inconnue après une mise à niveau, ou si l’agent signale que l’outil de navigateur est manquant, la cause la plus fréquente est une liste `plugins.allow` restrictive qui n’inclut pas `browser`.
-Exemple de configuration cassée :
+Exemple de configuration défectueuse :
```json5
{
@@ -106,7 +88,7 @@ Exemple de configuration cassée :
}
```
-Corrigez cela en ajoutant `browser` à la liste d'autorisation des plugins :
+Corrigez cela en ajoutant `browser` à la liste d’autorisation des plugins :
```json5
{
@@ -116,30 +98,28 @@ Corrigez cela en ajoutant `browser` à la liste d'autorisation des plugins :
}
```
-Remarques importantes :
+Remarques importantes :
- `browser.enabled=true` ne suffit pas à lui seul lorsque `plugins.allow` est défini.
- `plugins.entries.browser.enabled=true` ne suffit pas non plus à lui seul lorsque `plugins.allow` est défini.
-- `tools.alsoAllow: ["browser"]` ne charge **pas** le plugin de navigateur intégré. Cela ajuste seulement la politique des outils une fois le plugin déjà chargé.
-- Si vous n'avez pas besoin d'une liste d'autorisation restrictive pour les plugins, supprimer `plugins.allow` rétablit aussi le comportement par défaut du navigateur intégré.
+- `tools.alsoAllow: ["browser"]` ne charge **pas** le plugin de navigateur groupé. Il ajuste uniquement la politique des outils une fois le plugin déjà chargé.
+- Si vous n’avez pas besoin d’une liste d’autorisation de plugins restrictive, supprimer `plugins.allow` rétablit également le comportement par défaut du navigateur groupé.
-Symptômes typiques :
+Symptômes typiques :
- `openclaw browser` est une commande inconnue.
- `browser.request` est manquant.
-- L'agent signale que l'outil de navigateur est indisponible ou manquant.
+- L’agent indique que l’outil de navigateur est indisponible ou manquant.
-## Profils : `openclaw` vs `user`
+## Profils : `openclaw` vs `user`
-- `openclaw` : navigateur géré et isolé (aucune extension requise).
-- `user` : profil intégré de connexion Chrome MCP à votre **véritable Chrome connecté**
- session.
+- `openclaw` : navigateur géré et isolé (aucune extension requise).
+- `user` : profil de rattachement Chrome MCP intégré pour votre **vraie session Chrome connectée**.
-Pour les appels d'outil de navigateur de l'agent :
+Pour les appels d’outil de navigateur de l’agent :
-- Par défaut : utilisez le navigateur isolé `openclaw`.
-- Préférez `profile="user"` lorsque les sessions déjà connectées comptent et que l'utilisateur
- est devant l'ordinateur pour cliquer/approuver toute invite de connexion.
+- Par défaut : utilisez le navigateur isolé `openclaw`.
+- Préférez `profile="user"` lorsque des sessions déjà connectées sont importantes et que l’utilisateur est devant l’ordinateur pour cliquer/approuver toute invite de rattachement.
- `profile` est la surcharge explicite lorsque vous voulez un mode de navigateur spécifique.
Définissez `browser.defaultProfile: "openclaw"` si vous voulez le mode géré par défaut.
@@ -151,16 +131,16 @@ Les paramètres du navigateur se trouvent dans `~/.openclaw/openclaw.json`.
```json5
{
browser: {
- enabled: true, // default: true
+ enabled: true, // défaut : true
ssrfPolicy: {
- dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
- // allowPrivateNetwork: true, // legacy alias
+ dangerouslyAllowPrivateNetwork: true, // mode réseau de confiance par défaut
+ // allowPrivateNetwork: true, // alias hérité
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
- // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
- remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
- remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
+ // cdpUrl: "http://127.0.0.1:18792", // surcharge héritée pour profil unique
+ remoteCdpTimeoutMs: 1500, // délai d’expiration HTTP CDP distant (ms)
+ remoteCdpHandshakeTimeoutMs: 3000, // délai d’expiration de la négociation WebSocket CDP distante (ms)
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@@ -187,36 +167,30 @@ Les paramètres du navigateur se trouvent dans `~/.openclaw/openclaw.json`.
}
```
-Remarques :
+Remarques :
-- Le service de contrôle du navigateur se lie au loopback sur un port dérivé de `gateway.port`
- (par défaut : `18791`, soit gateway + 2).
-- Si vous surchargez le port du Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
- les ports de navigateur dérivés se décalent pour rester dans la même « famille ».
-- `cdpUrl` utilise par défaut le port CDP local géré lorsqu'il n'est pas défini.
-- `remoteCdpTimeoutMs` s'applique aux vérifications d'accessibilité CDP distantes (non loopback).
-- `remoteCdpHandshakeTimeoutMs` s'applique aux vérifications d'accessibilité de handshake WebSocket CDP distantes.
-- La navigation/l'ouverture d'onglet du navigateur est protégée contre la SSRF avant la navigation et revérifiée au mieux sur l'URL finale `http(s)` après la navigation.
+- Le service de contrôle du navigateur se lie à loopback sur un port dérivé de `gateway.port` (par défaut : `18791`, soit gateway + 2).
+- Si vous redéfinissez le port de la Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`), les ports dérivés du navigateur se décalent pour rester dans la même « famille ».
+- `cdpUrl` prend par défaut le port CDP local géré lorsqu’il n’est pas défini.
+- `remoteCdpTimeoutMs` s’applique aux vérifications d’accessibilité CDP distantes (hors loopback).
+- `remoteCdpHandshakeTimeoutMs` s’applique aux vérifications d’accessibilité de négociation WebSocket CDP distantes.
+- La navigation/ouverture d’onglets du navigateur est protégée contre la SSRF avant la navigation et revérifiée au mieux sur l’URL finale `http(s)` après navigation.
- En mode SSRF strict, la découverte/les sondes de point de terminaison CDP distant (`cdpUrl`, y compris les recherches `/json/version`) sont également vérifiées.
-- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` vaut `true` par défaut (modèle de réseau de confiance). Définissez-le sur `false` pour une navigation stricte sur l'Internet public uniquement.
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` vaut `true` par défaut (modèle réseau de confiance). Définissez-le sur `false` pour une navigation stricte réservée au réseau public.
- `browser.ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias hérité pour compatibilité.
-- `attachOnly: true` signifie « ne jamais lancer un navigateur local ; s'y attacher uniquement s'il est déjà en cours d'exécution ».
-- `color` + `color` par profil teintent l'interface du navigateur afin que vous puissiez voir quel profil est actif.
-- Le profil par défaut est `openclaw` (navigateur autonome géré par OpenClaw). Utilisez `defaultProfile: "user"` pour opter pour le navigateur connecté de l'utilisateur.
-- Ordre de détection automatique : navigateur système par défaut s'il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
-- Les profils locaux `openclaw` attribuent automatiquement `cdpPort`/`cdpUrl` — définissez-les uniquement pour le CDP distant.
-- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu du CDP brut. Ne
- définissez pas `cdpUrl` pour ce driver.
-- Définissez `browser.profiles..userDataDir` lorsqu'un profil existing-session
- doit se connecter à un profil utilisateur Chromium non par défaut tel que Brave ou Edge.
+- `attachOnly: true` signifie « ne jamais lancer un navigateur local ; uniquement s’y rattacher s’il est déjà en cours d’exécution ».
+- `color` + `color` par profil teintent l’interface du navigateur afin que vous puissiez voir quel profil est actif.
+- Le profil par défaut est `openclaw` (navigateur autonome géré par OpenClaw). Utilisez `defaultProfile: "user"` pour choisir le navigateur utilisateur connecté.
+- Ordre d’auto-détection : navigateur système par défaut s’il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
+- Les profils `openclaw` locaux attribuent automatiquement `cdpPort`/`cdpUrl` — ne définissez ces valeurs que pour le CDP distant.
+- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu du CDP brut. Ne définissez pas `cdpUrl` pour ce pilote.
+- Définissez `browser.profiles..userDataDir` lorsqu’un profil existing-session doit se rattacher à un profil utilisateur Chromium non par défaut, tel que Brave ou Edge.
## Utiliser Brave (ou un autre navigateur basé sur Chromium)
-Si votre navigateur **système par défaut** est basé sur Chromium (Chrome/Brave/Edge/etc),
-OpenClaw l'utilise automatiquement. Définissez `browser.executablePath` pour surcharger
-la détection automatique :
+Si votre navigateur **par défaut du système** est basé sur Chromium (Chrome/Brave/Edge/etc.), OpenClaw l’utilise automatiquement. Définissez `browser.executablePath` pour surcharger l’auto-détection :
-Exemple CLI :
+Exemple CLI :
```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
@@ -245,55 +219,43 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
}
```
-## Contrôle local vs distant
+## Contrôle local ou distant
-- **Contrôle local (par défaut) :** le Gateway démarre le service de contrôle loopback et peut lancer un navigateur local.
-- **Contrôle distant (hôte de nœud) :** exécutez un hôte de nœud sur la machine qui possède le navigateur ; le Gateway y proxifie les actions du navigateur.
-- **CDP distant :** définissez `browser.profiles..cdpUrl` (ou `browser.cdpUrl`) pour
- vous connecter à un navigateur distant basé sur Chromium. Dans ce cas, OpenClaw ne lancera pas de navigateur local.
+- **Contrôle local (par défaut) :** la Gateway démarre le service de contrôle loopback et peut lancer un navigateur local.
+- **Contrôle distant (hôte de nœud) :** exécutez un hôte de nœud sur la machine qui possède le navigateur ; la Gateway lui transmet les actions du navigateur.
+- **CDP distant :** définissez `browser.profiles..cdpUrl` (ou `browser.cdpUrl`) pour vous rattacher à un navigateur distant basé sur Chromium. Dans ce cas, OpenClaw ne lancera pas de navigateur local.
-Le comportement à l'arrêt diffère selon le mode du profil :
+Le comportement à l’arrêt diffère selon le mode de profil :
-- profils locaux gérés : `openclaw browser stop` arrête le processus du navigateur que
- OpenClaw a lancé
-- profils attach-only et CDP distant : `openclaw browser stop` ferme la session de
- contrôle active et libère les surcharges d'émulation Playwright/CDP (viewport,
- schéma de couleurs, langue, fuseau horaire, mode hors ligne et état similaire), même
- si aucun processus de navigateur n'a été lancé par OpenClaw
+- profils locaux gérés : `openclaw browser stop` arrête le processus de navigateur lancé par OpenClaw
+- profils en mode rattachement uniquement et profils CDP distants : `openclaw browser stop` ferme la session de contrôle active et libère les surcharges d’émulation Playwright/CDP (viewport, schéma de couleurs, paramètres régionaux, fuseau horaire, mode hors ligne et état similaire), même si aucun processus de navigateur n’a été lancé par OpenClaw
-Les URL CDP distantes peuvent inclure une authentification :
+Les URL CDP distantes peuvent inclure une authentification :
- Jetons de requête (par ex. `https://provider.example?token=`)
- Authentification HTTP Basic (par ex. `https://user:pass@provider.example`)
-OpenClaw conserve l'authentification lors des appels aux points de terminaison `/json/*` et lors de la connexion
-au WebSocket CDP. Préférez les variables d'environnement ou les gestionnaires de secrets pour les
-jetons au lieu de les commit dans les fichiers de configuration.
+OpenClaw préserve l’authentification lors des appels aux points de terminaison `/json/*` et lors de la connexion au WebSocket CDP. Préférez les variables d’environnement ou les gestionnaires de secrets pour les jetons au lieu de les valider dans des fichiers de configuration.
-## Proxy de navigateur de nœud (zéro configuration par défaut)
+## Proxy de navigateur de nœud (valeur par défaut sans configuration)
-Si vous exécutez un **hôte de nœud** sur la machine qui possède votre navigateur, OpenClaw peut
-acheminer automatiquement les appels d'outil de navigateur vers ce nœud sans configuration supplémentaire du navigateur.
-C'est le chemin par défaut pour les gateways distants.
+Si vous exécutez un **hôte de nœud** sur la machine qui possède votre navigateur, OpenClaw peut acheminer automatiquement les appels d’outil du navigateur vers ce nœud sans configuration de navigateur supplémentaire. Il s’agit du chemin par défaut pour les gateways distantes.
-Remarques :
+Remarques :
-- L'hôte de nœud expose son serveur local de contrôle du navigateur via une **commande proxy**.
-- Les profils proviennent de la propre configuration `browser.profiles` du nœud (identique au local).
-- `nodeHost.browserProxy.allowProfiles` est facultatif. Laissez-le vide pour le comportement hérité/par défaut : tous les profils configurés restent accessibles via le proxy, y compris les routes de création/suppression de profils.
-- Si vous définissez `nodeHost.browserProxy.allowProfiles`, OpenClaw le traite comme une limite de moindre privilège : seuls les profils de la liste d'autorisation peuvent être ciblés, et les routes persistantes de création/suppression de profils sont bloquées sur la surface proxy.
-- Désactivez-le si vous n'en voulez pas :
- - Sur le nœud : `nodeHost.browserProxy.enabled=false`
- - Sur le gateway : `gateway.nodes.browser.mode="off"`
+- L’hôte de nœud expose son serveur local de contrôle du navigateur via une **commande proxy**.
+- Les profils proviennent de la propre configuration `browser.profiles` du nœud (identique au mode local).
+- `nodeHost.browserProxy.allowProfiles` est facultatif. Laissez-le vide pour le comportement hérité/par défaut : tous les profils configurés restent accessibles via le proxy, y compris les routes de création/suppression de profil.
+- Si vous définissez `nodeHost.browserProxy.allowProfiles`, OpenClaw le traite comme une limite de moindre privilège : seuls les profils autorisés peuvent être ciblés, et les routes persistantes de création/suppression de profil sont bloquées sur la surface du proxy.
+- Désactivez-le si vous n’en voulez pas :
+ - Sur le nœud : `nodeHost.browserProxy.enabled=false`
+ - Sur la gateway : `gateway.nodes.browser.mode="off"`
## Browserless (CDP distant hébergé)
-[Browserless](https://browserless.io) est un service Chromium hébergé qui expose
-des URL de connexion CDP via HTTPS et WebSocket. OpenClaw peut utiliser l'une ou l'autre forme, mais
-pour un profil de navigateur distant, l'option la plus simple est l'URL WebSocket directe
-de la documentation de connexion de Browserless.
+[Browserless](https://browserless.io) est un service Chromium hébergé qui expose des URL de connexion CDP via HTTPS et WebSocket. OpenClaw peut utiliser l’une ou l’autre forme, mais pour un profil de navigateur distant, l’option la plus simple est l’URL WebSocket directe provenant de la documentation de connexion de Browserless.
-Exemple :
+Exemple :
```json5
{
@@ -312,32 +274,22 @@ Exemple :
}
```
-Remarques :
+Remarques :
-- Remplacez `` par votre véritable jeton Browserless.
+- Remplacez `` par votre vrai jeton Browserless.
- Choisissez le point de terminaison régional correspondant à votre compte Browserless (voir leur documentation).
-- Si Browserless vous fournit une URL de base HTTPS, vous pouvez soit la convertir en
- `wss://` pour une connexion CDP directe, soit conserver l'URL HTTPS et laisser OpenClaw
- découvrir `/json/version`.
+- Si Browserless vous fournit une URL de base HTTPS, vous pouvez soit la convertir en `wss://` pour une connexion CDP directe, soit conserver l’URL HTTPS et laisser OpenClaw découvrir `/json/version`.
-## Providers CDP WebSocket directs
+## Fournisseurs CDP WebSocket directs
-Certains services de navigateur hébergés exposent un point de terminaison **WebSocket direct** plutôt que
-la découverte CDP standard basée sur HTTP (`/json/version`). OpenClaw prend en charge les deux :
+Certains services de navigateur hébergés exposent un point de terminaison **WebSocket direct** plutôt que la découverte CDP standard basée sur HTTP (`/json/version`). OpenClaw prend en charge les deux :
-- **Points de terminaison HTTP(S)** — OpenClaw appelle `/json/version` pour découvrir l'URL
- du débogueur WebSocket, puis s'y connecte.
-- **Points de terminaison WebSocket** (`ws://` / `wss://`) — OpenClaw s'y connecte directement,
- en ignorant `/json/version`. Utilisez cela pour des services comme
- [Browserless](https://browserless.io),
- [Browserbase](https://www.browserbase.com), ou tout provider qui vous fournit une
- URL WebSocket.
+- **Points de terminaison HTTP(S)** — OpenClaw appelle `/json/version` pour découvrir l’URL WebSocket du débogueur, puis s’y connecte.
+- **Points de terminaison WebSocket** (`ws://` / `wss://`) — OpenClaw se connecte directement, en ignorant `/json/version`. Utilisez cela pour des services comme [Browserless](https://browserless.io), [Browserbase](https://www.browserbase.com), ou tout fournisseur qui vous donne une URL WebSocket.
### Browserbase
-[Browserbase](https://www.browserbase.com) est une plateforme cloud pour exécuter des
-navigateurs headless avec résolution intégrée de CAPTCHA, mode furtif et proxies
-résidentiels.
+[Browserbase](https://www.browserbase.com) est une plateforme cloud permettant d’exécuter des navigateurs headless avec résolution de CAPTCHA intégrée, mode furtif et proxys résidentiels.
```json5
{
@@ -356,82 +308,69 @@ résidentiels.
}
```
-Remarques :
+Remarques :
-- [Inscrivez-vous](https://www.browserbase.com/sign-up) et copiez votre **clé API**
- depuis le [tableau de bord Overview](https://www.browserbase.com/overview).
-- Remplacez `` par votre véritable clé API Browserbase.
-- Browserbase crée automatiquement une session de navigateur à la connexion WebSocket, donc aucune
- étape manuelle de création de session n'est nécessaire.
-- Le niveau gratuit autorise une session simultanée et une heure de navigateur par mois.
- Consultez les [tarifs](https://www.browserbase.com/pricing) pour les limites des forfaits payants.
-- Consultez la [documentation Browserbase](https://docs.browserbase.com) pour la
- référence API complète, les guides SDK et les exemples d'intégration.
+- [Inscrivez-vous](https://www.browserbase.com/sign-up) et copiez votre **clé API** depuis le [tableau de bord Overview](https://www.browserbase.com/overview).
+- Remplacez `` par votre vraie clé API Browserbase.
+- Browserbase crée automatiquement une session de navigateur lors de la connexion WebSocket, donc aucune étape manuelle de création de session n’est nécessaire.
+- L’offre gratuite autorise une session simultanée et une heure de navigateur par mois. Consultez les [tarifs](https://www.browserbase.com/pricing) pour les limites des offres payantes.
+- Consultez la [documentation Browserbase](https://docs.browserbase.com) pour la référence API complète, les guides SDK et des exemples d’intégration.
## Sécurité
-Idées clés :
+Idées clés :
-- Le contrôle du navigateur est limité au loopback ; l'accès passe par l'authentification du Gateway ou l'appairage de nœud.
-- L'API HTTP autonome de navigateur en loopback utilise **uniquement une authentification à secret partagé** :
- authentification bearer par jeton gateway, `x-openclaw-password`, ou authentification HTTP Basic avec le
- mot de passe gateway configuré.
-- Les en-têtes d'identité Tailscale Serve et `gateway.auth.mode: "trusted-proxy"` n'authentifient
- **pas** cette API autonome de navigateur en loopback.
-- Si le contrôle du navigateur est activé et qu'aucune authentification à secret partagé n'est configurée, OpenClaw
- génère automatiquement `gateway.auth.token` au démarrage et le persiste dans la configuration.
-- OpenClaw ne génère **pas** automatiquement ce jeton lorsque `gateway.auth.mode` vaut déjà
- `password`, `none` ou `trusted-proxy`.
-- Conservez le Gateway et tous les hôtes de nœud sur un réseau privé (Tailscale) ; évitez toute exposition publique.
-- Traitez les URL/jetons CDP distants comme des secrets ; préférez les variables d'environnement ou un gestionnaire de secrets.
+- Le contrôle du navigateur est limité à loopback ; l’accès passe par l’authentification de la Gateway ou l’appairage de nœud.
+- L’API HTTP autonome du navigateur sur loopback utilise **uniquement une authentification par secret partagé** : authentification Bearer par jeton Gateway, `x-openclaw-password`, ou authentification HTTP Basic avec le mot de passe Gateway configuré.
+- Les en-têtes d’identité Tailscale Serve et `gateway.auth.mode: "trusted-proxy"` **n’authentifient pas** cette API autonome du navigateur sur loopback.
+- Si le contrôle du navigateur est activé et qu’aucune authentification par secret partagé n’est configurée, OpenClaw génère automatiquement `gateway.auth.token` au démarrage et le conserve dans la configuration.
+- OpenClaw ne génère **pas** automatiquement ce jeton lorsque `gateway.auth.mode` est déjà `password`, `none` ou `trusted-proxy`.
+- Conservez la Gateway et tous les hôtes de nœud sur un réseau privé (Tailscale) ; évitez l’exposition publique.
+- Traitez les URL/jetons CDP distants comme des secrets ; préférez les variables d’environnement ou un gestionnaire de secrets.
-Conseils pour le CDP distant :
+Conseils pour le CDP distant :
-- Préférez des points de terminaison chiffrés (HTTPS ou WSS) et des jetons de courte durée de vie lorsque c'est possible.
-- Évitez d'intégrer directement des jetons de longue durée dans les fichiers de configuration.
+- Préférez des points de terminaison chiffrés (HTTPS ou WSS) et des jetons de courte durée lorsque c’est possible.
+- Évitez d’intégrer directement des jetons de longue durée dans les fichiers de configuration.
-## Profils (multi-navigateurs)
+## Profils (multi-navigateur)
-OpenClaw prend en charge plusieurs profils nommés (configurations de routage). Les profils peuvent être :
+OpenClaw prend en charge plusieurs profils nommés (configurations de routage). Les profils peuvent être :
-- **gérés par openclaw** : une instance dédiée de navigateur basé sur Chromium avec son propre répertoire de données utilisateur + port CDP
-- **distant** : une URL CDP explicite (navigateur basé sur Chromium exécuté ailleurs)
-- **session existante** : votre profil Chrome existant via auto-connexion Chrome DevTools MCP
+- **gérés par openclaw** : une instance de navigateur dédiée basée sur Chromium avec son propre répertoire de données utilisateur + port CDP
+- **distants** : une URL CDP explicite (navigateur basé sur Chromium exécuté ailleurs)
+- **session existante** : votre profil Chrome existant via l’auto-connexion Chrome DevTools MCP
-Par défaut :
+Valeurs par défaut :
-- Le profil `openclaw` est créé automatiquement s'il est absent.
-- Le profil `user` est intégré pour la connexion existing-session via Chrome MCP.
-- Les profils existing-session sont opt-in au-delà de `user` ; créez-les avec `--driver existing-session`.
-- Les ports CDP locaux sont alloués dans la plage **18800–18899** par défaut.
+- Le profil `openclaw` est créé automatiquement s’il manque.
+- Le profil `user` est intégré pour le rattachement existing-session de Chrome MCP.
+- Les profils existing-session sont activés sur opt-in au-delà de `user` ; créez-les avec `--driver existing-session`.
+- Les ports CDP locaux sont alloués par défaut dans la plage **18800–18899**.
- Supprimer un profil déplace son répertoire de données local vers la corbeille.
-Tous les points de terminaison de contrôle acceptent `?profile=` ; la CLI utilise `--browser-profile`.
+Tous les points de terminaison de contrôle acceptent `?profile=` ; la CLI utilise `--browser-profile`.
## Existing-session via Chrome DevTools MCP
-OpenClaw peut également se connecter à un profil de navigateur basé sur Chromium en cours d'exécution via le
-serveur officiel Chrome DevTools MCP. Cela réutilise les onglets et l'état de connexion
-déjà ouverts dans ce profil de navigateur.
+OpenClaw peut aussi se rattacher à un profil de navigateur basé sur Chromium en cours d’exécution via le serveur officiel Chrome DevTools MCP. Cela réutilise les onglets et l’état de connexion déjà ouverts dans ce profil de navigateur.
-Références officielles de contexte et de configuration :
+Références officielles de contexte et de configuration :
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
-- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+- [README de Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
-Profil intégré :
+Profil intégré :
- `user`
-Facultatif : créez votre propre profil existing-session personnalisé si vous voulez un
-nom, une couleur ou un répertoire de données du navigateur différents.
+Facultatif : créez votre propre profil existing-session personnalisé si vous voulez un nom, une couleur ou un répertoire de données de navigateur différent.
-Comportement par défaut :
+Comportement par défaut :
-- Le profil intégré `user` utilise l'auto-connexion Chrome MCP, qui cible le
- profil local Google Chrome par défaut.
+- Le profil `user` intégré utilise l’auto-connexion Chrome MCP, qui cible le profil local Google Chrome par défaut.
-Utilisez `userDataDir` pour Brave, Edge, Chromium ou un profil Chrome non par défaut :
+Utilisez `userDataDir` pour Brave, Edge, Chromium, ou un profil Chrome non par défaut :
```json5
{
@@ -448,19 +387,19 @@ Utilisez `userDataDir` pour Brave, Edge, Chromium ou un profil Chrome non par d
}
```
-Ensuite, dans le navigateur correspondant :
+Ensuite, dans le navigateur correspondant :
-1. Ouvrez la page d'inspection de ce navigateur pour le débogage à distance.
+1. Ouvrez la page d’inspection de ce navigateur pour le débogage à distance.
2. Activez le débogage à distance.
-3. Laissez le navigateur ouvert et approuvez l'invite de connexion quand OpenClaw s'y attache.
+3. Laissez le navigateur en cours d’exécution et approuvez l’invite de connexion lorsque OpenClaw s’y rattache.
-Pages d'inspection courantes :
+Pages d’inspection courantes :
-- Chrome : `chrome://inspect/#remote-debugging`
-- Brave : `brave://inspect/#remote-debugging`
-- Edge : `edge://inspect/#remote-debugging`
+- Chrome : `chrome://inspect/#remote-debugging`
+- Brave : `brave://inspect/#remote-debugging`
+- Edge : `edge://inspect/#remote-debugging`
-Test rapide de connexion en direct :
+Test de fumée de rattachement en direct :
```bash
openclaw browser --browser-profile user start
@@ -469,72 +408,57 @@ openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
-À quoi ressemble le succès :
+À quoi ressemble une réussite :
- `status` affiche `driver: existing-session`
- `status` affiche `transport: chrome-mcp`
- `status` affiche `running: true`
-- `tabs` liste les onglets déjà ouverts dans votre navigateur
-- `snapshot` renvoie des refs à partir de l'onglet actif sélectionné
+- `tabs` liste vos onglets de navigateur déjà ouverts
+- `snapshot` renvoie des refs depuis l’onglet actif sélectionné
-Ce qu'il faut vérifier si la connexion ne fonctionne pas :
+Que vérifier si le rattachement ne fonctionne pas :
- le navigateur cible basé sur Chromium est en version `144+`
-- le débogage à distance est activé dans la page d'inspection de ce navigateur
-- le navigateur a affiché l'invite de consentement à la connexion et vous l'avez acceptée
-- `openclaw doctor` migre l'ancienne configuration de navigateur basée sur extension et vérifie que
- Chrome est installé localement pour les profils d'auto-connexion par défaut, mais il ne peut pas
- activer pour vous le débogage à distance côté navigateur
+- le débogage à distance est activé dans la page d’inspection de ce navigateur
+- le navigateur a affiché l’invite de consentement au rattachement et vous l’avez acceptée
+- `openclaw doctor` migre l’ancienne configuration de navigateur basée sur une extension et vérifie que Chrome est installé localement pour les profils d’auto-connexion par défaut, mais il ne peut pas activer le débogage à distance côté navigateur à votre place
-Utilisation par l'agent :
+Utilisation par l’agent :
-- Utilisez `profile="user"` lorsque vous avez besoin de l'état du navigateur connecté de l'utilisateur.
-- Si vous utilisez un profil existing-session personnalisé, passez ce nom de profil explicite.
-- Choisissez ce mode uniquement lorsque l'utilisateur est devant l'ordinateur pour approuver l'invite
- de connexion.
-- le Gateway ou l'hôte de nœud peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
+- Utilisez `profile="user"` lorsque vous avez besoin de l’état du navigateur connecté de l’utilisateur.
+- Si vous utilisez un profil existing-session personnalisé, indiquez ce nom de profil explicitement.
+- Choisissez ce mode uniquement lorsque l’utilisateur est devant l’ordinateur pour approuver l’invite de rattachement.
+- la Gateway ou l’hôte de nœud peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
-Remarques :
+Remarques :
-- Cette voie est plus risquée que le profil isolé `openclaw` car elle peut
- agir dans votre session de navigateur connectée.
-- OpenClaw ne lance pas le navigateur pour ce driver ; il se connecte uniquement à une
- session existante.
-- OpenClaw utilise ici le flux officiel `--autoConnect` de Chrome DevTools MCP. Si
- `userDataDir` est défini, OpenClaw le transmet pour cibler ce répertoire
- explicite de données utilisateur Chromium.
-- Les captures d'écran existing-session prennent en charge les captures de page et les captures d'élément `--ref`
- à partir des snapshots, mais pas les sélecteurs CSS `--element`.
-- Les captures d'écran de page existing-session fonctionnent sans Playwright via Chrome MCP.
- Les captures d'élément basées sur des refs (`--ref`) y fonctionnent aussi, mais `--full-page`
- ne peut pas être combiné avec `--ref` ou `--element`.
-- Les actions existing-session restent plus limitées que la voie du navigateur géré :
- - `click`, `type`, `hover`, `scrollIntoView`, `drag` et `select` nécessitent
- des refs de snapshot au lieu de sélecteurs CSS
+- Ce chemin est plus risqué que le profil isolé `openclaw`, car il peut agir dans votre session de navigateur connectée.
+- OpenClaw ne lance pas le navigateur pour ce pilote ; il se rattache uniquement à une session existante.
+- OpenClaw utilise ici le flux officiel Chrome DevTools MCP `--autoConnect`. Si `userDataDir` est défini, OpenClaw le transmet pour cibler explicitement ce répertoire de données utilisateur Chromium.
+- Les captures d’écran existing-session prennent en charge les captures de page et les captures d’élément `--ref` à partir des instantanés, mais pas les sélecteurs CSS `--element`.
+- Les captures d’écran de page existing-session fonctionnent sans Playwright via Chrome MCP. Les captures d’élément basées sur des refs (`--ref`) y fonctionnent également, mais `--full-page` ne peut pas être combiné avec `--ref` ou `--element`.
+- Les actions existing-session restent plus limitées que le chemin du navigateur géré :
+ - `click`, `type`, `hover`, `scrollIntoView`, `drag` et `select` nécessitent des refs d’instantané au lieu de sélecteurs CSS
- `click` est limité au bouton gauche (pas de surcharge de bouton ni de modificateurs)
- - `type` ne prend pas en charge `slowly=true` ; utilisez `fill` ou `press`
+ - `type` ne prend pas en charge `slowly=true` ; utilisez `fill` ou `press`
- `press` ne prend pas en charge `delayMs`
- - `hover`, `scrollIntoView`, `drag`, `select`, `fill` et `evaluate` ne
- prennent pas en charge les surcharges de délai d'attente par appel
- - `select` ne prend actuellement en charge qu'une seule valeur
-- `wait --url` en existing-session prend en charge les motifs exacts, de sous-chaîne et glob
- comme les autres drivers de navigateur. `wait --load networkidle` n'est pas encore pris en charge.
-- Les hooks d'upload existing-session nécessitent `ref` ou `inputRef`, prennent en charge un seul fichier à la fois, et ne prennent pas en charge le ciblage CSS `element`.
-- Les hooks de boîte de dialogue existing-session ne prennent pas en charge les surcharges de délai d'attente.
-- Certaines fonctionnalités nécessitent toujours la voie du navigateur géré, notamment les
- actions par lots, l'export PDF, l'interception de téléchargement et `responsebody`.
-- Existing-session est local à l'hôte. Si Chrome se trouve sur une autre machine ou dans un
- autre espace de noms réseau, utilisez plutôt le CDP distant ou un hôte de nœud.
+ - `hover`, `scrollIntoView`, `drag`, `select`, `fill` et `evaluate` ne prennent pas en charge les surcharges de délai d’expiration par appel
+ - `select` ne prend actuellement en charge qu’une seule valeur
+- `wait --url` en existing-session prend en charge les motifs exacts, de sous-chaîne et glob, comme les autres pilotes de navigateur. `wait --load networkidle` n’est pas encore pris en charge.
+- Les hooks d’envoi de fichiers existing-session nécessitent `ref` ou `inputRef`, prennent en charge un seul fichier à la fois, et ne prennent pas en charge le ciblage CSS `element`.
+- Les hooks de boîte de dialogue existing-session ne prennent pas en charge les surcharges de délai d’expiration.
+- Certaines fonctionnalités nécessitent encore le chemin du navigateur géré, notamment les actions par lots, l’export PDF, l’interception des téléchargements et `responsebody`.
+- Existing-session est local à l’hôte. Si Chrome se trouve sur une autre machine ou dans un autre espace de noms réseau, utilisez plutôt le CDP distant ou un hôte de nœud.
-## Garanties d'isolation
+## Garanties d’isolation
-- **Répertoire de données utilisateur dédié** : ne touche jamais à votre profil de navigateur personnel.
-- **Ports dédiés** : évite `9222` pour prévenir les collisions avec les workflows de développement.
-- **Contrôle déterministe des onglets** : cible les onglets par `targetId`, pas par « dernier onglet ».
+- **Répertoire de données utilisateur dédié** : ne touche jamais à votre profil de navigateur personnel.
+- **Ports dédiés** : évite `9222` afin d’empêcher les collisions avec les flux de développement.
+- **Contrôle déterministe des onglets** : cible les onglets par `targetId`, pas par « dernier onglet ».
## Sélection du navigateur
-Lors du lancement local, OpenClaw choisit le premier disponible :
+Lors d’un lancement local, OpenClaw choisit le premier disponible :
1. Chrome
2. Brave
@@ -544,105 +468,111 @@ Lors du lancement local, OpenClaw choisit le premier disponible :
Vous pouvez surcharger cela avec `browser.executablePath`.
-Plateformes :
+Plateformes :
-- macOS : vérifie `/Applications` et `~/Applications`.
-- Linux : recherche `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
-- Windows : vérifie les emplacements d'installation courants.
+- macOS : vérifie `/Applications` et `~/Applications`.
+- Linux : recherche `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
+- Windows : vérifie les emplacements d’installation courants.
-## API de contrôle (facultatif)
+## API de contrôle (facultative)
-Pour les intégrations locales uniquement, le Gateway expose une petite API HTTP loopback :
+Pour les intégrations locales uniquement, la Gateway expose une petite API HTTP loopback :
-- État/démarrage/arrêt : `GET /`, `POST /start`, `POST /stop`
-- Onglets : `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
-- Snapshot/capture d'écran : `GET /snapshot`, `POST /screenshot`
-- Actions : `POST /navigate`, `POST /act`
-- Hooks : `POST /hooks/file-chooser`, `POST /hooks/dialog`
-- Téléchargements : `POST /download`, `POST /wait/download`
-- Débogage : `GET /console`, `POST /pdf`
-- Débogage : `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
-- Réseau : `POST /response/body`
-- État : `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`
-- État : `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
-- Paramètres : `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
+- Statut/démarrage/arrêt : `GET /`, `POST /start`, `POST /stop`
+- Onglets : `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
+- Instantané/capture d’écran : `GET /snapshot`, `POST /screenshot`
+- Actions : `POST /navigate`, `POST /act`
+- Hooks : `POST /hooks/file-chooser`, `POST /hooks/dialog`
+- Téléchargements : `POST /download`, `POST /wait/download`
+- Débogage : `GET /console`, `POST /pdf`
+- Débogage : `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`
+- Réseau : `POST /response/body`
+- État : `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`
+- État : `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
+- Paramètres : `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
Tous les points de terminaison acceptent `?profile=`.
-Si l'authentification gateway à secret partagé est configurée, les routes HTTP du navigateur exigent aussi une authentification :
+Si une authentification Gateway par secret partagé est configurée, les routes HTTP du navigateur exigent également une authentification :
- `Authorization: Bearer `
- `x-openclaw-password: ` ou authentification HTTP Basic avec ce mot de passe
-Remarques :
+Remarques :
-- Cette API autonome de navigateur en loopback ne consomme **pas** les en-têtes d'identité trusted-proxy ou
- Tailscale Serve.
-- Si `gateway.auth.mode` vaut `none` ou `trusted-proxy`, ces routes de navigateur en loopback
- n'héritent pas de ces modes porteurs d'identité ; gardez-les limitées au loopback.
+- Cette API autonome du navigateur sur loopback ne consomme **pas** les en-têtes d’identité trusted-proxy ni Tailscale Serve.
+- Si `gateway.auth.mode` est `none` ou `trusted-proxy`, ces routes de navigateur sur loopback n’héritent pas de ces modes porteurs d’identité ; gardez-les limitées à loopback.
+
+### Contrat d’erreur `/act`
+
+`POST /act` utilise une réponse d’erreur structurée pour la validation au niveau de la route et les échecs de politique :
+
+```json
+{ "error": "", "code": "ACT_*" }
+```
+
+Valeurs `code` actuelles :
+
+- `ACT_KIND_REQUIRED` (HTTP 400) : `kind` est manquant ou non reconnu.
+- `ACT_INVALID_REQUEST` (HTTP 400) : la charge utile d’action a échoué lors de la normalisation ou de la validation.
+- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400) : `selector` a été utilisé avec un type d’action non pris en charge.
+- `ACT_EVALUATE_DISABLED` (HTTP 403) : `evaluate` (ou `wait --fn`) est désactivé par la configuration.
+- `ACT_TARGET_ID_MISMATCH` (HTTP 403) : `targetId` de niveau supérieur ou en lot est en conflit avec la cible de la requête.
+- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501) : l’action n’est pas prise en charge pour les profils existing-session.
+
+D’autres échecs d’exécution peuvent encore renvoyer `{ "error": "" }` sans champ `code`.
### Exigence Playwright
-Certaines fonctionnalités (navigate/act/AI snapshot/role snapshot, captures d'écran d'élément,
-PDF) nécessitent Playwright. Si Playwright n'est pas installé, ces points de terminaison renvoient
-une erreur 501 explicite.
+Certaines fonctionnalités (navigate/act/AI snapshot/role snapshot, captures d’écran d’élément, PDF) nécessitent Playwright. Si Playwright n’est pas installé, ces points de terminaison renvoient une erreur 501 claire.
-Ce qui fonctionne encore sans Playwright :
+Ce qui fonctionne encore sans Playwright :
-- Snapshots ARIA
-- Captures d'écran de page pour le navigateur géré `openclaw` lorsqu'un WebSocket CDP
- par onglet est disponible
-- Captures d'écran de page pour les profils `existing-session` / Chrome MCP
-- Captures d'écran existing-session basées sur `--ref` à partir de la sortie de snapshot
+- instantanés ARIA
+- captures d’écran de page pour le navigateur géré `openclaw` lorsqu’un WebSocket CDP par onglet est disponible
+- captures d’écran de page pour les profils `existing-session` / Chrome MCP
+- captures d’écran existing-session basées sur `--ref` à partir de la sortie d’instantané
-Ce qui nécessite toujours Playwright :
+Ce qui nécessite encore Playwright :
- `navigate`
- `act`
-- AI snapshots / role snapshots
-- Captures d'écran d'élément par sélecteur CSS (`--element`)
-- Export PDF complet du navigateur
+- instantanés AI / instantanés de rôle
+- captures d’écran d’élément avec sélecteur CSS (`--element`)
+- export PDF complet du navigateur
-Les captures d'écran d'élément rejettent également `--full-page` ; la route renvoie `fullPage is
-not supported for element screenshots`.
+Les captures d’écran d’élément rejettent également `--full-page` ; la route renvoie `fullPage is not supported for element screenshots`.
-Si vous voyez `Playwright is not available in this gateway build`, installez le package complet
-Playwright (pas `playwright-core`) et redémarrez le gateway, ou réinstallez
-OpenClaw avec la prise en charge du navigateur.
+Si vous voyez `Playwright is not available in this gateway build`, installez le package Playwright complet (pas `playwright-core`) et redémarrez la gateway, ou réinstallez OpenClaw avec la prise en charge du navigateur.
#### Installation de Playwright dans Docker
-Si votre Gateway s'exécute dans Docker, évitez `npx playwright` (conflits d'override npm).
-Utilisez plutôt la CLI intégrée :
+Si votre Gateway s’exécute dans Docker, évitez `npx playwright` (conflits avec les surcharges npm). Utilisez plutôt la CLI groupée :
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
-Pour conserver les téléchargements de navigateurs, définissez `PLAYWRIGHT_BROWSERS_PATH` (par exemple,
-`/home/node/.cache/ms-playwright`) et assurez-vous que `/home/node` est conservé via
-`OPENCLAW_HOME_VOLUME` ou un montage bind. Voir [Docker](/fr/install/docker).
+Pour conserver les téléchargements de navigateur, définissez `PLAYWRIGHT_BROWSERS_PATH` (par exemple, `/home/node/.cache/ms-playwright`) et assurez-vous que `/home/node` est conservé via `OPENCLAW_HOME_VOLUME` ou un bind mount. Consultez [Docker](/fr/install/docker).
-## Fonctionnement (interne)
+## Comment cela fonctionne (interne)
-Flux de haut niveau :
+Flux de haut niveau :
-- Un petit **serveur de contrôle** accepte les requêtes HTTP.
-- Il se connecte aux navigateurs basés sur Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
-- Pour les actions avancées (click/type/snapshot/PDF), il utilise **Playwright** au-dessus
- de CDP.
+- Un petit **serveur de contrôle** accepte des requêtes HTTP.
+- Il se connecte à des navigateurs basés sur Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
+- Pour les actions avancées (clic/saisie/instantané/PDF), il utilise **Playwright** au-dessus de CDP.
- Lorsque Playwright est absent, seules les opérations sans Playwright sont disponibles.
-Cette conception maintient l'agent sur une interface stable et déterministe tout en vous permettant
-de changer de navigateurs et de profils locaux/distants.
+Cette conception maintient l’agent sur une interface stable et déterministe tout en vous permettant de changer de navigateur local/distant et de profils.
## Référence rapide CLI
Toutes les commandes acceptent `--browser-profile ` pour cibler un profil spécifique.
-Toutes les commandes acceptent également `--json` pour une sortie lisible par machine (payloads stables).
+Toutes les commandes acceptent aussi `--json` pour une sortie lisible par machine (charges utiles stables).
-Bases :
+Bases :
- `openclaw browser status`
- `openclaw browser start`
@@ -656,7 +586,7 @@ Bases :
- `openclaw browser focus abcd1234`
- `openclaw browser close abcd1234`
-Inspection :
+Inspection :
- `openclaw browser screenshot`
- `openclaw browser screenshot --full-page`
@@ -671,18 +601,15 @@ Inspection :
- `openclaw browser snapshot --frame "iframe#main" --interactive`
- `openclaw browser console --level error`
-Remarque sur le cycle de vie :
+Remarque sur le cycle de vie :
-- Pour les profils attach-only et CDP distants, `openclaw browser stop` reste la
- bonne commande de nettoyage après les tests. Elle ferme la session de contrôle active et
- efface les surcharges temporaires d'émulation au lieu de tuer le navigateur
- sous-jacent.
+- Pour les profils en mode rattachement uniquement et CDP distants, `openclaw browser stop` reste la bonne commande de nettoyage après les tests. Elle ferme la session de contrôle active et efface les surcharges d’émulation temporaires au lieu de tuer le navigateur sous-jacent.
- `openclaw browser errors --clear`
- `openclaw browser requests --filter api --clear`
- `openclaw browser pdf`
- `openclaw browser responsebody "**/api" --max-chars 5000`
-Actions :
+Actions :
- `openclaw browser navigate https://example.com`
- `openclaw browser resize 1280 720`
@@ -706,7 +633,7 @@ Actions :
- `openclaw browser trace start`
- `openclaw browser trace stop`
-État :
+État :
- `openclaw browser cookies`
- `openclaw browser cookies set session abc123 --url "https://example.com"`
@@ -725,62 +652,61 @@ Actions :
- `openclaw browser set locale en-US`
- `openclaw browser set device "iPhone 14"`
-Remarques :
+Remarques :
-- `upload` et `dialog` sont des appels **d'armement** ; exécutez-les avant le click/la pression
- qui déclenche le sélecteur/la boîte de dialogue.
-- Les chemins de sortie de téléchargement et de trace sont limités aux racines temporaires OpenClaw :
- - traces : `/tmp/openclaw` (repli : `${os.tmpdir()}/openclaw`)
- - téléchargements : `/tmp/openclaw/downloads` (repli : `${os.tmpdir()}/openclaw/downloads`)
-- Les chemins d'upload sont limités à une racine temporaire d'uploads OpenClaw :
- - uploads : `/tmp/openclaw/uploads` (repli : `${os.tmpdir()}/openclaw/uploads`)
+- `upload` et `dialog` sont des appels d’**armement** ; exécutez-les avant le clic/la touche qui déclenche le sélecteur de fichier/la boîte de dialogue.
+- Les chemins de sortie pour les téléchargements et les traces sont limités aux racines temporaires d’OpenClaw :
+ - traces : `/tmp/openclaw` (repli : `${os.tmpdir()}/openclaw`)
+ - téléchargements : `/tmp/openclaw/downloads` (repli : `${os.tmpdir()}/openclaw/downloads`)
+- Les chemins d’envoi sont limités à une racine temporaire d’uploads OpenClaw :
+ - uploads : `/tmp/openclaw/uploads` (repli : `${os.tmpdir()}/openclaw/uploads`)
- `upload` peut aussi définir directement des entrées de fichier via `--input-ref` ou `--element`.
-- `snapshot` :
- - `--format ai` (par défaut lorsque Playwright est installé) : renvoie un AI snapshot avec des refs numériques (`aria-ref=""`).
- - `--format aria` : renvoie l'arbre d'accessibilité (sans refs ; inspection uniquement).
- - `--efficient` (ou `--mode efficient`) : preset compact de role snapshot (interactive + compact + depth + maxChars réduit).
- - Valeur par défaut de configuration (outil/CLI uniquement) : définissez `browser.snapshotDefaults.mode: "efficient"` pour utiliser des snapshots efficaces lorsque l'appelant ne passe pas de mode (voir [Configuration du Gateway](/fr/gateway/configuration-reference#browser)).
- - Les options de role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forcent un snapshot basé sur les rôles avec des refs comme `ref=e12`.
- - `--frame "