From 45fbe3855bfe8e13031f3a87a84ebcef1f96dc9f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 18 Apr 2026 06:50:42 +0000 Subject: [PATCH] chore(i18n): refresh fr translations --- docs/fr/concepts/agent-workspace.md | 140 ++- docs/fr/concepts/context.md | 172 +-- docs/fr/concepts/qa-e2e-automation.md | 215 ++-- docs/fr/concepts/system-prompt.md | 149 ++- docs/fr/gateway/configuration-reference.md | 1256 ++++++++++---------- docs/fr/gateway/protocol.md | 486 ++++---- docs/fr/help/testing.md | 1078 +++++++++-------- docs/fr/platforms/macos.md | 180 +-- docs/fr/plugins/sdk-channel-plugins.md | 395 +++--- docs/fr/plugins/sdk-overview.md | 575 ++++----- docs/fr/refactor/qa.md | 226 ++-- 11 files changed, 2440 insertions(+), 2432 deletions(-) diff --git a/docs/fr/concepts/agent-workspace.md b/docs/fr/concepts/agent-workspace.md index 3534c55bf..0cbbd2657 100644 --- a/docs/fr/concepts/agent-workspace.md +++ b/docs/fr/concepts/agent-workspace.md @@ -1,39 +1,39 @@ --- read_when: - - Vous devez expliquer l’espace de travail de l’agent ou son organisation de fichiers + - Vous devez expliquer l’espace de travail de l’agent ou la disposition de ses fichiers - Vous souhaitez sauvegarder ou migrer un espace de travail d’agent -summary: 'Espace de travail de l’agent : emplacement, organisation et stratégie de sauvegarde' +summary: 'Espace de travail de l’agent : emplacement, disposition et stratégie de sauvegarde' title: Espace de travail de l’agent x-i18n: - generated_at: "2026-04-05T12:39:36Z" + generated_at: "2026-04-18T06:43:35Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- # Espace de travail de l’agent -L’espace de travail est le foyer de l’agent. C’est le seul répertoire de travail utilisé pour -les outils de fichiers et pour le contexte de l’espace de travail. Gardez-le privé et traitez-le comme de la mémoire. +L’espace de travail est la maison de l’agent. C’est le seul répertoire de travail utilisé pour +les outils de fichiers et pour le contexte d’espace de travail. Gardez-le privé et traitez-le comme une mémoire. -Ceci est distinct de `~/.openclaw/`, qui stocke la configuration, les identifiants et +Cela est distinct de `~/.openclaw/`, qui stocke la configuration, les identifiants et les sessions. -**Important :** l’espace de travail est le **cwd par défaut**, pas un sandbox strict. Les outils +**Important :** l’espace de travail est le **cwd par défaut**, et non un sandbox strict. Les outils résolvent les chemins relatifs par rapport à l’espace de travail, mais les chemins absolus peuvent toujours atteindre d’autres emplacements sur l’hôte sauf si le sandboxing est activé. Si vous avez besoin d’isolation, utilisez -[`agents.defaults.sandbox`](/gateway/sandboxing) (et/ou une configuration de sandbox par agent). +[`agents.defaults.sandbox`](/fr/gateway/sandboxing) (et/ou une configuration de sandbox par agent). Lorsque le sandboxing est activé et que `workspaceAccess` n’est pas `"rw"`, les outils opèrent dans un espace de travail sandbox sous `~/.openclaw/sandboxes`, et non dans votre espace de travail hôte. ## Emplacement par défaut - Par défaut : `~/.openclaw/workspace` -- Si `OPENCLAW_PROFILE` est défini et n’est pas `"default"`, l’emplacement par défaut devient +- Si `OPENCLAW_PROFILE` est défini et n’est pas `"default"`, la valeur par défaut devient `~/.openclaw/workspace-`. -- Remplacez-le dans `~/.openclaw/openclaw.json` : +- Remplacement dans `~/.openclaw/openclaw.json` : ```json5 { @@ -43,106 +43,104 @@ dans un espace de travail sandbox sous `~/.openclaw/sandboxes`, et non dans votr } ``` -`openclaw onboard`, `openclaw configure` ou `openclaw setup` créeront -l’espace de travail et initialiseront les fichiers bootstrap s’ils sont absents. -Les copies d’amorçage du sandbox n’acceptent que les fichiers ordinaires dans l’espace de travail ; les alias -de lien symbolique/lien physique qui se résolvent en dehors de l’espace de travail source sont ignorés. +`openclaw onboard`, `openclaw configure` ou `openclaw setup` créera l’espace de travail +et initialisera les fichiers d’amorçage s’ils sont absents. +Les copies de seed du sandbox n’acceptent que les fichiers réguliers situés dans l’espace de travail ; les +alias symlink/hardlink qui se résolvent en dehors de l’espace de travail source sont ignorés. -Si vous gérez déjà vous-même les fichiers de l’espace de travail, vous pouvez désactiver la création -des fichiers bootstrap : +Si vous gérez déjà vous-même les fichiers de l’espace de travail, vous pouvez désactiver la création des fichiers d’amorçage : ```json5 { agent: { skipBootstrap: true } } ``` -## Dossiers supplémentaires d’espace de travail +## Dossiers d’espace de travail supplémentaires -Les anciennes installations ont pu créer `~/openclaw`. Conserver plusieurs répertoires -d’espace de travail peut provoquer des dérives d’authentification ou d’état difficiles à comprendre, car un seul +Les anciennes installations peuvent avoir créé `~/openclaw`. Conserver plusieurs répertoires d’espace de travail +peut provoquer une dérive confuse de l’authentification ou de l’état, car un seul espace de travail est actif à la fois. -**Recommandation :** gardez un seul espace de travail actif. Si vous n’utilisez plus les -dossiers supplémentaires, archivez-les ou placez-les dans la Corbeille (par exemple `trash ~/openclaw`). -Si vous conservez volontairement plusieurs espaces de travail, assurez-vous que -`agents.defaults.workspace` pointe vers l’espace de travail actif. +**Recommandation :** conservez un seul espace de travail actif. Si vous n’utilisez plus les +dossiers supplémentaires, archivez-les ou déplacez-les vers la corbeille (par exemple `trash ~/openclaw`). +Si vous conservez intentionnellement plusieurs espaces de travail, assurez-vous que +`agents.defaults.workspace` pointe vers celui qui est actif. -`openclaw doctor` affiche un avertissement lorsqu’il détecte des répertoires d’espace de travail supplémentaires. +`openclaw doctor` avertit lorsqu’il détecte des répertoires d’espace de travail supplémentaires. ## Carte des fichiers de l’espace de travail (signification de chaque fichier) Voici les fichiers standard qu’OpenClaw attend dans l’espace de travail : - `AGENTS.md` - - Instructions de fonctionnement pour l’agent et façon dont il doit utiliser la mémoire. + - Instructions de fonctionnement pour l’agent et la manière dont il doit utiliser la mémoire. - Chargé au début de chaque session. - - Bon emplacement pour les règles, priorités et détails sur « comment se comporter ». + - Bon emplacement pour les règles, les priorités et les détails sur « comment se comporter ». - `SOUL.md` - Persona, ton et limites. - Chargé à chaque session. - - Guide : [Guide de personnalité SOUL.md](/concepts/soul) + - Guide : [Guide de personnalité SOUL.md](/fr/concepts/soul) - `USER.md` - Qui est l’utilisateur et comment s’adresser à lui. - Chargé à chaque session. - `IDENTITY.md` - - Le nom, le style et l’emoji de l’agent. - - Créé/mis à jour pendant le rituel bootstrap. + - Le nom de l’agent, son style et son emoji. + - Créé/mis à jour pendant le rituel d’amorçage. - `TOOLS.md` - - Notes sur vos outils locaux et conventions. - - Ne contrôle pas la disponibilité des outils ; ne sert que de guide. + - Notes sur vos outils locaux et vos conventions. + - Ne contrôle pas la disponibilité des outils ; il sert uniquement de guide. - `HEARTBEAT.md` - - Petite checklist facultative pour les exécutions heartbeat. - - Gardez-la courte pour éviter de gaspiller des jetons. + - Petite checklist facultative pour les exécutions Heartbeat. + - Gardez-la courte pour éviter de brûler des tokens. - `BOOT.md` - - Checklist de démarrage facultative exécutée au redémarrage de gateway lorsque les hooks internes sont activés. + - Checklist de démarrage facultative exécutée au redémarrage de la Gateway lorsque les hooks internes sont activés. - Gardez-la courte ; utilisez l’outil de message pour les envois sortants. - `BOOTSTRAP.md` - - Rituel unique de première exécution. - - Créé uniquement pour un espace de travail entièrement nouveau. + - Rituel unique du premier lancement. + - Créé uniquement pour un espace de travail entièrement neuf. - Supprimez-le une fois le rituel terminé. - `memory/YYYY-MM-DD.md` - - Journal mémoire quotidien (un fichier par jour). - - Il est recommandé de lire aujourd’hui + hier au démarrage de la session. + - Journal de mémoire quotidien (un fichier par jour). + - Il est recommandé de lire celui d’aujourd’hui + celui d’hier au démarrage de la session. - `MEMORY.md` (facultatif) - Mémoire long terme organisée. - - À charger uniquement dans la session principale privée (pas dans les contextes partagés/de groupe). + - À charger uniquement dans la session principale et privée (pas dans les contextes partagés/de groupe). -Voir [Mémoire](/concepts/memory) pour le flux de travail et la purge mémoire automatique. +Consultez [Memory](/fr/concepts/memory) pour le workflow et le vidage automatique de la mémoire. - `skills/` (facultatif) - Skills spécifiques à l’espace de travail. - - Emplacement de Skills à la plus haute priorité pour cet espace de travail. - - Remplace les Skills d’agent de projet, les Skills d’agent personnels, les Skills gérés, les Skills intégrés et `skills.load.extraDirs` en cas de collision de noms. + - Emplacement de Skills à la priorité la plus élevée pour cet espace de travail. + - Remplace les skills d’agent du projet, les skills d’agent personnels, les skills gérés, les skills intégrés et `skills.load.extraDirs` lorsque les noms entrent en conflit. - `canvas/` (facultatif) - - Fichiers UI canvas pour les affichages de nœud (par exemple `canvas/index.html`). + - Fichiers d’interface Canvas pour les affichages de nœud (par exemple `canvas/index.html`). -Si un fichier bootstrap est absent, OpenClaw injecte un marqueur « fichier manquant » dans -la session et continue. Les gros fichiers bootstrap sont tronqués lors de l’injection ; -ajustez les limites avec `agents.defaults.bootstrapMaxChars` (par défaut : 20000) et -`agents.defaults.bootstrapTotalMaxChars` (par défaut : 150000). -`openclaw setup` peut recréer les valeurs par défaut manquantes sans écraser les -fichiers existants. +Si un fichier d’amorçage est manquant, OpenClaw injecte un marqueur « fichier manquant » dans +la session et continue. Les grands fichiers d’amorçage sont tronqués lors de l’injection ; +ajustez les limites avec `agents.defaults.bootstrapMaxChars` (par défaut : 12000) et +`agents.defaults.bootstrapTotalMaxChars` (par défaut : 60000). +`openclaw setup` peut recréer les valeurs par défaut manquantes sans écraser les fichiers existants. ## Ce qui n’est PAS dans l’espace de travail -Ces éléments se trouvent sous `~/.openclaw/` et ne doivent PAS être validés dans le dépôt de l’espace de travail : +Ces éléments se trouvent sous `~/.openclaw/` et ne doivent PAS être commités dans le dépôt de l’espace de travail : - `~/.openclaw/openclaw.json` (configuration) -- `~/.openclaw/agents//agent/auth-profiles.json` (profils d’authentification de modèle : OAuth + clés API) -- `~/.openclaw/credentials/` (état du canal/fournisseur plus données d’importation OAuth héritées) +- `~/.openclaw/agents//agent/auth-profiles.json` (profils d’authentification des modèles : OAuth + clés API) +- `~/.openclaw/credentials/` (état des canaux/providers ainsi que données d’import OAuth héritées) - `~/.openclaw/agents//sessions/` (transcriptions de session + métadonnées) - `~/.openclaw/skills/` (Skills gérés) -Si vous devez migrer des sessions ou la configuration, copiez-les séparément et gardez-les +Si vous devez migrer des sessions ou la configuration, copiez-les séparément et conservez-les hors du contrôle de version. ## Sauvegarde Git (recommandée, privée) @@ -150,12 +148,12 @@ hors du contrôle de version. Traitez l’espace de travail comme une mémoire privée. Placez-le dans un dépôt git **privé** afin qu’il soit sauvegardé et récupérable. -Exécutez ces étapes sur la machine où gateway s’exécute (c’est là que -l’espace de travail se trouve). +Exécutez ces étapes sur la machine où la Gateway s’exécute (c’est là que se trouve +l’espace de travail). ### 1) Initialiser le dépôt -Si git est installé, les nouveaux espaces de travail sont initialisés automatiquement. Si cet +Si git est installé, les espaces de travail neufs sont initialisés automatiquement. Si cet espace de travail n’est pas déjà un dépôt, exécutez : ```bash @@ -165,7 +163,7 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add agent workspace" ``` -### 2) Ajouter un remote privé (options adaptées aux débutants) +### 2) Ajouter un remote privé (options simples pour débutants) Option A : interface web GitHub @@ -209,18 +207,18 @@ git commit -m "Update memory" git push ``` -## Ne validez pas de secrets +## Ne commitez pas de secrets Même dans un dépôt privé, évitez de stocker des secrets dans l’espace de travail : -- Clés API, jetons OAuth, mots de passe ou identifiants privés. +- Clés API, tokens OAuth, mots de passe ou identifiants privés. - Tout ce qui se trouve sous `~/.openclaw/`. -- Dumps bruts de chats ou pièces jointes sensibles. +- Dumps bruts de discussions ou pièces jointes sensibles. -Si vous devez stocker des références sensibles, utilisez des espaces réservés et conservez le vrai +Si vous devez stocker des références sensibles, utilisez des placeholders et conservez le vrai secret ailleurs (gestionnaire de mots de passe, variables d’environnement ou `~/.openclaw/`). -Exemple de départ pour `.gitignore` : +Exemple de `.gitignore` recommandé : ```gitignore .DS_Store @@ -235,19 +233,19 @@ Exemple de départ pour `.gitignore` : 1. Clonez le dépôt vers le chemin souhaité (par défaut `~/.openclaw/workspace`). 2. Définissez `agents.defaults.workspace` sur ce chemin dans `~/.openclaw/openclaw.json`. 3. Exécutez `openclaw setup --workspace ` pour initialiser les fichiers manquants. -4. Si vous avez besoin des sessions, copiez `~/.openclaw/agents//sessions/` depuis l’ - ancienne machine séparément. +4. Si vous avez besoin des sessions, copiez `~/.openclaw/agents//sessions/` depuis l’ancienne + machine séparément. ## Notes avancées -- Le routage multi-agent peut utiliser différents espaces de travail par agent. Voir - [Routage des canaux](/channels/channel-routing) pour la configuration du routage. +- Le routage multi-agent peut utiliser des espaces de travail différents par agent. Consultez + [Routage des canaux](/fr/channels/channel-routing) pour la configuration du routage. - Si `agents.defaults.sandbox` est activé, les sessions non principales peuvent utiliser des espaces de travail sandbox par session sous `agents.defaults.sandbox.workspaceRoot`. ## Liens associés -- [Ordres permanents](/automation/standing-orders) — instructions persistantes dans les fichiers d’espace de travail -- [Heartbeat](/gateway/heartbeat) — fichier d’espace de travail HEARTBEAT.md -- [Session](/concepts/session) — chemins de stockage des sessions -- [Sandboxing](/gateway/sandboxing) — accès à l’espace de travail dans les environnements sandboxés +- [Standing Orders](/fr/automation/standing-orders) — instructions persistantes dans les fichiers de l’espace de travail +- [Heartbeat](/fr/gateway/heartbeat) — fichier d’espace de travail HEARTBEAT.md +- [Session](/fr/concepts/session) — chemins de stockage des sessions +- [Sandboxing](/fr/gateway/sandboxing) — accès à l’espace de travail dans les environnements sandboxés diff --git a/docs/fr/concepts/context.md b/docs/fr/concepts/context.md index 65f3e2c63..a804c5604 100644 --- a/docs/fr/concepts/context.md +++ b/docs/fr/concepts/context.md @@ -1,40 +1,40 @@ --- read_when: - - Vous voulez comprendre ce que signifie « contexte » dans OpenClaw - - Vous déboguez pourquoi le modèle « sait » quelque chose (ou l’a oublié) + - Vous voulez comprendre ce que signifie « contexte » dans OpenClaw + - Vous déboguez pourquoi le modèle « sait » quelque chose (ou l’a oublié) - Vous souhaitez réduire la surcharge de contexte (/context, /status, /compact) -summary: 'Contexte : ce que le modèle voit, comment il est construit et comment l’inspecter' +summary: 'Contexte : ce que voit le modèle, comment il est construit et comment l’inspecter' title: Contexte x-i18n: - generated_at: "2026-04-12T23:28:13Z" + generated_at: "2026-04-18T06:43:36Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- # Contexte -Le « contexte » correspond à **tout ce qu’OpenClaw envoie au modèle pour une exécution**. Il est limité par la **fenêtre de contexte** du modèle (limite de jetons). +Le « contexte » est **tout ce que OpenClaw envoie au modèle pour une exécution**. Il est limité par la **fenêtre de contexte** du modèle (limite de tokens). -Modèle mental pour débuter : +Modèle mental pour débutants : -- **Prompt système** (construit par OpenClaw) : règles, outils, liste des Skills, heure/exécution, et fichiers d’espace de travail injectés. -- **Historique de conversation** : vos messages + les messages de l’assistant pour cette session. -- **Appels/résultats d’outils + pièces jointes** : sortie de commande, lectures de fichiers, images/audio, etc. +- **Prompt système** (construit par OpenClaw) : règles, outils, liste des Skills, heure/exécution, et fichiers d’espace de travail injectés. +- **Historique de conversation** : vos messages + les messages de l’assistant pour cette session. +- **Appels/résultats d’outils + pièces jointes** : sortie de commandes, lectures de fichiers, images/audio, etc. -Le contexte _n’est pas la même chose_ que la « mémoire » : la mémoire peut être stockée sur disque et rechargée plus tard ; le contexte est ce qui se trouve dans la fenêtre actuelle du modèle. +Le contexte n’est _pas la même chose_ que la « mémoire » : la mémoire peut être stockée sur disque et rechargée plus tard ; le contexte est ce qui se trouve dans la fenêtre actuelle du modèle. ## Démarrage rapide (inspecter le contexte) -- `/status` → vue rapide « à quel point ma fenêtre est-elle remplie ? » + paramètres de session. +- `/status` → vue rapide « à quel point ma fenêtre est-elle remplie ? » + paramètres de session. - `/context list` → ce qui est injecté + tailles approximatives (par fichier + totaux). -- `/context detail` → ventilation plus approfondie : par fichier, tailles des schémas d’outils, tailles des entrées de Skills et taille du prompt système. +- `/context detail` → ventilation plus approfondie : par fichier, tailles des schémas d’outils, tailles des entrées de Skills, et taille du prompt système. - `/usage tokens` → ajoute un pied de page d’utilisation par réponse aux réponses normales. - `/compact` → résume l’historique plus ancien dans une entrée compacte pour libérer de l’espace dans la fenêtre. -Voir aussi : [Commandes slash](/fr/tools/slash-commands), [Utilisation des jetons et coûts](/fr/reference/token-use), [Compaction](/fr/concepts/compaction). +Voir aussi : [Commandes slash](/fr/tools/slash-commands), [Utilisation des tokens et coûts](/fr/reference/token-use), [Compaction](/fr/concepts/compaction). ## Exemple de sortie @@ -44,27 +44,27 @@ Les valeurs varient selon le modèle, le fournisseur, la politique d’outils et ``` 🧠 Ventilation du contexte -Workspace: -Bootstrap max/file: 20,000 chars -Sandbox: mode=non-main sandboxed=false -System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) +Espace de travail : +Bootstrap max/fichier : 12,000 caractères +Sandbox : mode=non-main sandboxed=false +Prompt système (exécution) : 38,412 caractères (~9,603 tok) (Contexte du projet 23,901 caractères (~5,976 tok)) -Injected workspace files: -- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) -- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) -- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) -- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) -- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) -- HEARTBEAT.md: MISSING | raw 0 | injected 0 -- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) +Fichiers de l’espace de travail injectés : +- AGENTS.md: OK | brut 1,742 caractères (~436 tok) | injecté 1,742 caractères (~436 tok) +- SOUL.md: OK | brut 912 caractères (~228 tok) | injecté 912 caractères (~228 tok) +- TOOLS.md: TRONQUÉ | brut 54,210 caractères (~13,553 tok) | injecté 20,962 caractères (~5,241 tok) +- IDENTITY.md: OK | brut 211 caractères (~53 tok) | injecté 211 caractères (~53 tok) +- USER.md: OK | brut 388 caractères (~97 tok) | injecté 388 caractères (~97 tok) +- HEARTBEAT.md: ABSENT | brut 0 | injecté 0 +- BOOTSTRAP.md: OK | brut 0 caractères (~0 tok) | injecté 0 caractères (~0 tok) -Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) -Tools: read, edit, write, exec, process, browser, message, sessions_send, … -Tool list (system prompt text): 1,032 chars (~258 tok) -Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) -Tools: (same as above) +Liste des Skills (texte du prompt système) : 2,184 caractères (~546 tok) (12 Skills) +Outils : read, edit, write, exec, process, browser, message, sessions_send, … +Liste des outils (texte du prompt système) : 1,032 caractères (~258 tok) +Schémas d’outils (JSON) : 31,988 caractères (~7,997 tok) (comptent dans le contexte ; non affichés comme texte) +Outils : (identiques ci-dessus) -Session tokens (cached): 14,250 total / ctx=32,000 +Tokens de session (en cache) : 14,250 au total / ctx=32,000 ``` ### `/context detail` @@ -72,44 +72,44 @@ Session tokens (cached): 14,250 total / ctx=32,000 ``` 🧠 Ventilation du contexte (détaillée) … -Top skills (prompt entry size): -- frontend-design: 412 chars (~103 tok) -- oracle: 401 chars (~101 tok) -… (+10 more skills) +Principaux Skills (taille d’entrée du prompt) : +- frontend-design: 412 caractères (~103 tok) +- oracle: 401 caractères (~101 tok) +… (+10 autres Skills) -Top tools (schema size): -- browser: 9,812 chars (~2,453 tok) -- exec: 6,240 chars (~1,560 tok) -… (+N more tools) +Principaux outils (taille du schéma) : +- browser: 9,812 caractères (~2,453 tok) +- exec: 6,240 caractères (~1,560 tok) +… (+N autres outils) ``` ## Ce qui compte dans la fenêtre de contexte -Tout ce que le modèle reçoit compte, y compris : +Tout ce que le modèle reçoit compte, y compris : -- Le prompt système (toutes les sections). -- L’historique de conversation. -- Les appels d’outils + les résultats d’outils. -- Les pièces jointes/transcriptions (images/audio/fichiers). -- Les résumés de compaction et les artefacts d’élagage. -- Les « wrappers » du fournisseur ou en-têtes masqués (non visibles, mais quand même comptés). +- Prompt système (toutes les sections). +- Historique de conversation. +- Appels d’outils + résultats d’outils. +- Pièces jointes/transcriptions (images/audio/fichiers). +- Résumés de Compaction et artefacts d’élagage. +- « Wrappers » du fournisseur ou en-têtes cachés (non visibles, mais tout de même comptés). ## Comment OpenClaw construit le prompt système -Le prompt système est **géré par OpenClaw** et reconstruit à chaque exécution. Il inclut : +Le prompt système appartient à **OpenClaw** et est reconstruit à chaque exécution. Il inclut : -- La liste des outils + de courtes descriptions. -- La liste des Skills (métadonnées uniquement ; voir ci-dessous). -- L’emplacement de l’espace de travail. -- L’heure (UTC + heure utilisateur convertie si configurée). -- Les métadonnées d’exécution (hôte/OS/modèle/réflexion). -- Les fichiers bootstrap injectés de l’espace de travail sous **Contexte du projet**. +- Liste des outils + courtes descriptions. +- Liste des Skills (métadonnées uniquement ; voir ci-dessous). +- Emplacement de l’espace de travail. +- Heure (UTC + heure utilisateur convertie si configurée). +- Métadonnées d’exécution (hôte/OS/modèle/réflexion). +- Fichiers bootstrap de l’espace de travail injectés sous **Contexte du projet**. -Ventilation complète : [Prompt système](/fr/concepts/system-prompt). +Ventilation complète : [Prompt système](/fr/concepts/system-prompt). -## Fichiers d’espace de travail injectés (Contexte du projet) +## Fichiers de l’espace de travail injectés (Contexte du projet) -Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail (s’ils sont présents) : +Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail (s’ils sont présents) : - `AGENTS.md` - `SOUL.md` @@ -119,59 +119,59 @@ Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail - `HEARTBEAT.md` - `BOOTSTRAP.md` (première exécution uniquement) -Les fichiers volumineux sont tronqués par fichier selon `agents.defaults.bootstrapMaxChars` (valeur par défaut `20000` caractères). OpenClaw applique également une limite totale d’injection bootstrap sur l’ensemble des fichiers avec `agents.defaults.bootstrapTotalMaxChars` (valeur par défaut `150000` caractères). `/context` affiche les tailles **brutes vs injectées** et indique si une troncature a eu lieu. +Les fichiers volumineux sont tronqués fichier par fichier à l’aide de `agents.defaults.bootstrapMaxChars` (par défaut `12000` caractères). OpenClaw applique aussi un plafond total d’injection bootstrap sur l’ensemble des fichiers avec `agents.defaults.bootstrapTotalMaxChars` (par défaut `60000` caractères). `/context` affiche les tailles **brutes vs injectées** et indique si une troncature a eu lieu. -Lorsqu’une troncature se produit, le runtime peut injecter un bloc d’avertissement dans le prompt sous Contexte du projet. Configurez cela avec `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; valeur par défaut `once`). +Lorsqu’une troncature se produit, l’exécution peut injecter un bloc d’avertissement dans le prompt sous Contexte du projet. Configurez cela avec `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; `once` par défaut). -## Skills : injectés ou chargés à la demande +## Skills : injectés ou chargés à la demande -Le prompt système inclut une liste compacte de **Skills** (nom + description + emplacement). Cette liste a une surcharge réelle. +Le prompt système inclut une liste compacte des **Skills** (nom + description + emplacement). Cette liste a un coût réel. -Les instructions des Skills ne sont _pas_ incluses par défaut. Le modèle est censé `read` le fichier `SKILL.md` du skill **uniquement quand nécessaire**. +Les instructions des Skills ne sont _pas_ incluses par défaut. Le modèle est censé `read` le `SKILL.md` du skill **uniquement lorsque nécessaire**. -## Outils : il y a deux coûts +## Outils : il y a deux coûts -Les outils affectent le contexte de deux façons : +Les outils affectent le contexte de deux façons : -1. **Texte de la liste des outils** dans le prompt système (ce que vous voyez comme « Outillage »). +1. **Texte de la liste des outils** dans le prompt système (ce que vous voyez comme « Tooling »). 2. **Schémas d’outils** (JSON). Ils sont envoyés au modèle afin qu’il puisse appeler des outils. Ils comptent dans le contexte même si vous ne les voyez pas sous forme de texte brut. -`/context detail` détaille les plus gros schémas d’outils afin que vous puissiez voir ce qui domine. +`/context detail` ventile les schémas d’outils les plus volumineux afin que vous puissiez voir ce qui domine. -## Commandes, directives et « raccourcis en ligne » +## Commandes, directives et « raccourcis inline » -Les commandes slash sont gérées par la Gateway. Il existe quelques comportements différents : +Les commandes slash sont gérées par la Gateway. Il existe quelques comportements différents : -- **Commandes autonomes** : un message qui n’est que `/...` s’exécute comme une commande. -- **Directives** : `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` sont retirées avant que le modèle ne voie le message. - - Les messages contenant uniquement une directive conservent les paramètres de session. - - Les directives en ligne dans un message normal agissent comme des indications par message. -- **Raccourcis en ligne** (expéditeurs autorisés uniquement) : certains jetons `/...` dans un message normal peuvent s’exécuter immédiatement (exemple : « hey /status »), et sont retirés avant que le modèle ne voie le texte restant. +- **Commandes autonomes** : un message qui contient uniquement `/...` s’exécute comme une commande. +- **Directives** : `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` sont retirées avant que le modèle ne voie le message. + - Les messages contenant uniquement des directives conservent les paramètres de session. + - Les directives inline dans un message normal agissent comme des indications propres au message. +- **Raccourcis inline** (expéditeurs autorisés uniquement) : certains tokens `/...` dans un message normal peuvent s’exécuter immédiatement (exemple : « hey /status »), et sont retirés avant que le modèle ne voie le texte restant. -Détails : [Commandes slash](/fr/tools/slash-commands). +Détails : [Commandes slash](/fr/tools/slash-commands). -## Sessions, compaction et élagage (ce qui persiste) +## Sessions, Compaction et élagage (ce qui persiste) -Ce qui persiste d’un message à l’autre dépend du mécanisme : +Ce qui persiste entre les messages dépend du mécanisme : -- **L’historique normal** persiste dans la transcription de session jusqu’à être compacté/élagué par la politique. -- **La compaction** conserve un résumé dans la transcription et garde les messages récents intacts. -- **L’élagage** supprime les anciens résultats d’outils du prompt _en mémoire_ pour une exécution, mais ne réécrit pas la transcription. +- **L’historique normal** persiste dans la transcription de session jusqu’à ce qu’il soit compacté/élagué par la politique. +- **Compaction** conserve un résumé dans la transcription et garde intacts les messages récents. +- **L’élagage** retire les anciens résultats d’outils du prompt _en mémoire_ pour une exécution, mais ne réécrit pas la transcription. -Documentation : [Session](/fr/concepts/session), [Compaction](/fr/concepts/compaction), [Élagage de session](/fr/concepts/session-pruning). +Documentation : [Session](/fr/concepts/session), [Compaction](/fr/concepts/compaction), [Élagage de session](/fr/concepts/session-pruning). -Par défaut, OpenClaw utilise le moteur de contexte intégré `legacy` pour l’assemblage et la compaction. Si vous installez un Plugin qui fournit `kind: "context-engine"` et le sélectionnez avec `plugins.slots.contextEngine`, OpenClaw délègue alors l’assemblage du contexte, `/compact` et les hooks associés du cycle de vie du contexte de sous-agent à ce moteur à la place. `ownsCompaction: false` ne provoque pas de retour automatique au moteur legacy ; le moteur actif doit toujours implémenter `compact()` correctement. Voir [Context Engine](/fr/concepts/context-engine) pour l’interface enfichable complète, les hooks de cycle de vie et la configuration. +Par défaut, OpenClaw utilise le moteur de contexte intégré `legacy` pour l’assemblage et la Compaction. Si vous installez un Plugin qui fournit `kind: "context-engine"` et le sélectionnez avec `plugins.slots.contextEngine`, OpenClaw délègue à ce moteur l’assemblage du contexte, `/compact` et les hooks de cycle de vie de contexte des sous-agents associés. `ownsCompaction: false` ne revient pas automatiquement au moteur legacy ; le moteur actif doit tout de même implémenter correctement `compact()`. Voir [Context Engine](/fr/concepts/context-engine) pour l’interface enfichable complète, les hooks de cycle de vie et la configuration. -## Ce que `/context` signale réellement +## Ce que `/context` rapporte réellement -`/context` privilégie le dernier rapport de prompt système **construit à l’exécution** lorsqu’il est disponible : +`/context` privilégie le dernier rapport de prompt système **construit à l’exécution** lorsqu’il est disponible : -- `System prompt (run)` = capturé à partir de la dernière exécution embarquée (capable d’utiliser des outils) et conservé dans le stockage de session. +- `System prompt (run)` = capturé lors de la dernière exécution embarquée (capable d’utiliser des outils) et conservé dans le stockage de session. - `System prompt (estimate)` = calculé à la volée lorsqu’aucun rapport d’exécution n’existe (ou lors d’une exécution via un backend CLI qui ne génère pas le rapport). -Dans les deux cas, il signale les tailles et les principaux contributeurs ; il ne vide **pas** le prompt système complet ni les schémas d’outils. +Dans les deux cas, il rapporte des tailles et les principaux contributeurs ; il **n’affiche pas** le prompt système complet ni les schémas d’outils. -## Lié à ce sujet +## Lié - [Context Engine](/fr/concepts/context-engine) — injection de contexte personnalisée via des plugins - [Compaction](/fr/concepts/compaction) — résumé des longues conversations diff --git a/docs/fr/concepts/qa-e2e-automation.md b/docs/fr/concepts/qa-e2e-automation.md index 0b68172df..38d95f991 100644 --- a/docs/fr/concepts/qa-e2e-automation.md +++ b/docs/fr/concepts/qa-e2e-automation.md @@ -2,50 +2,50 @@ read_when: - Extension de qa-lab ou de 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 + - Création d’une automatisation QA de plus grand réalisme autour du tableau de bord Gateway summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios initialisés et les rapports de protocole title: Automatisation QA E2E x-i18n: - generated_at: "2026-04-17T06:57:31Z" + generated_at: "2026-04-18T06:43:38Z" model: gpt-5.4 provider: openai - source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 + source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatisation QA E2E -La pile QA privée a pour but d’exercer OpenClaw d’une manière plus réaliste, -structurée comme un canal, qu’un simple test unitaire ne peut le faire. +La pile QA privée a pour objectif d’exercer OpenClaw d’une manière plus réaliste, +façonnée comme un canal, qu’un simple test unitaire ne peut le faire. -Éléments actuels : +Éléments actuels : -- `extensions/qa-channel` : canal de messages synthétique avec des surfaces pour les MP, les canaux, les fils, - les réactions, les modifications et les suppressions. -- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription, +- `extensions/qa-channel` : canal de messages synthétique avec des surfaces de MP, canal, fil, + réaction, modification et suppression. +- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription, injecter des messages entrants et exporter un rapport Markdown. -- `qa/` : ressources initiales adossées au dépôt pour la tâche de démarrage et les +- `qa/` : ressources initiales adossées au dépôt pour la tâche de lancement et les scénarios QA de référence. -Le flux opérateur QA actuel est un site QA à deux volets : +Le flux opérateur QA actuel est un site QA à deux volets : -- Gauche : tableau de bord Gateway (UI de contrôle) avec l’agent. -- Droite : QA Lab, affichant la transcription de type Slack et le plan du scénario. +- Gauche : tableau de bord Gateway (Control UI) avec l’agent. +- Droite : QA Lab, affichant une transcription de type Slack et le plan de scénario. -Exécutez-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 confier à 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 à l’agent une +mission QA, observer le comportement réel du canal et consigner ce qui a fonctionné, échoué +ou est resté bloqué. -Pour itérer plus rapidement sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois, -démarrez la pile avec un bundle QA Lab monté par liaison : +Pour une itération plus rapide 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 pnpm openclaw qa docker-build-image @@ -57,24 +57,24 @@ pnpm qa:lab:watch `qa:lab:up:fast` conserve 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. +des ressources de QA Lab change. -Pour une voie de smoke test Matrix sur transport réel, exécutez : +Pour une voie smoke Matrix avec transport réel, exécutez : ```bash pnpm openclaw qa matrix ``` Cette voie provisionne un homeserver Tuwunel jetable dans Docker, enregistre -des utilisateurs temporaires pilote, SUT et observateur, crée une salle privée, puis exécute -le vrai Plugin Matrix dans un enfant Gateway QA. La voie sur transport réel conserve +des utilisateurs temporaires de pilote, SUT et observateur, crée un salon privé, puis exécute +le vrai plugin Matrix dans un processus enfant QA Gateway. La voie de transport en direct conserve la configuration enfant limitée au transport testé, afin que Matrix s’exécute sans -`qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés ainsi -qu’un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour -capturer également la sortie externe de build/lancement de `scripts/run-node.mjs`, définissez +`qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés et +un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour +capturer également la sortie de construction/lancement externe de `scripts/run-node.mjs`, définissez `OPENCLAW_RUN_NODE_OUTPUT_LOG=` vers un fichier journal local au dépôt. -Pour une voie de smoke test Telegram sur transport réel, exécutez : +Pour une voie smoke Telegram avec transport réel, exécutez : ```bash pnpm openclaw qa telegram @@ -85,122 +85,127 @@ serveur jetable. Elle nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, ainsi que deux bots distincts dans le même groupe privé. Le bot SUT doit avoir un nom d’utilisateur Telegram, et l’observation -bot à bot fonctionne mieux lorsque les deux bots ont le mode de communication Bot-to-Bot -activé dans `@BotFather`. +bot à bot fonctionne au mieux lorsque les deux bots ont le mode de communication +bot à bot activé dans `@BotFather`. -Les voies sur transport réel partagent désormais un contrat plus réduit au lieu que chacune -invente sa propre structure de liste de scénarios. +Les voies de transport en direct partagent désormais un contrat plus restreint au lieu que chacune invente +sa propre forme de liste de scénarios. -`qa-channel` reste la suite large de comportements produit synthétiques et ne fait pas partie -de la matrice de couverture des transports réels. +`qa-channel` reste la suite large de comportement produit synthétique et ne fait pas partie +de la matrice de couverture de transport en direct. -| Voie | Canary | Gating par mention | Blocage par allowlist | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande d’aide | -| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | --------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Voie | Canary | Filtrage des mentions | Blocage de la liste d’autorisation | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande help | +| -------- | ------ | --------------------- | ---------------------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | ------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Cela permet à `qa-channel` de rester la suite large de comportements produit, tandis que Matrix, -Telegram et les futurs transports réels partagent une checklist explicite unique du contrat de transport. +Cela permet de conserver `qa-channel` comme suite large de comportement produit tandis que Matrix, +Telegram et les futurs transports en direct partagent une checklist explicite de contrat de transport. -Pour une voie de VM Linux jetable sans intégrer Docker dans le chemin QA, exécutez : +Pour une voie VM Linux jetable sans faire entrer Docker dans le chemin QA, exécutez : ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw -dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le -résumé dans `.artifacts/qa-e2e/...` sur l’hôte. +Cela démarre un invité Multipass neuf, installe les dépendances, construit OpenClaw +dans l’invité, exécute `qa suite`, puis copie le rapport QA et le +résumé habituels vers `.artifacts/qa-e2e/...` sur l’hôte. Cela réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte. -Les exécutions de suite sur l’hôte et dans Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle -avec des workers Gateway isolés, jusqu’à 64 workers ou au nombre de scénarios sélectionnés. -Utilisez `--concurrency ` pour ajuster le nombre de workers, ou +Les exécutions de suite sur hôte et Multipass exécutent plusieurs scénarios sélectionnés en parallèle +avec des workers Gateway isolés par défaut, jusqu’à 64 workers ou au nombre +de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, ou `--concurrency 1` pour une exécution en série. -Les exécutions live transmettent les entrées d’auth QA prises en charge qui sont pratiques pour -l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA live, et -`CODEX_HOME` lorsqu’il est présent. Conservez `--output-dir` sous la racine du dépôt afin que l’invité -puisse écrire en retour via l’espace de travail monté. +Les exécutions en direct transmettent les entrées d’auth QA prises en charge qui sont pratiques pour +l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA en direct, 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é. ## Ressources initiales adossées au dépôt -Les ressources initiales se trouvent dans `qa/` : +Les ressources initiales se trouvent dans `qa/` : - `qa/scenarios/index.md` -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` -Elles sont volontairement dans git afin que le plan QA soit visible à la fois pour les humains et pour +Elles sont volontairement dans git pour que le plan QA soit visible à la fois des humains et de l’agent. `qa-lab` doit rester un exécuteur Markdown générique. Chaque fichier Markdown de scénario est -la source de vérité pour une exécution de test et doit définir : +la source de vérité pour une exécution de test et doit définir : - les métadonnées du scénario +- des métadonnées facultatives de catégorie, capacité, voie et risque - les références de documentation et de code -- les exigences facultatives en matière de Plugin -- le correctif facultatif de configuration Gateway +- des exigences de plugin facultatives +- un patch de configuration Gateway facultatif - le `qa-flow` exécutable La surface d’exécution réutilisable qui sous-tend `qa-flow` peut rester générique -et transverse. Par exemple, des scénarios Markdown peuvent combiner des helpers côté transport -avec des helpers côté navigateur qui pilotent l’UI de contrôle intégrée via le -point d’intégration Gateway `browser.request` sans ajouter d’exécuteur spécialisé. +et transversale. Par exemple, les scénarios Markdown peuvent combiner des helpers côté +transport avec des helpers côté navigateur qui pilotent la Control UI intégrée via la +jointure Gateway `browser.request` sans ajouter d’exécuteur spécifique. -La liste de référence doit rester suffisamment large pour couvrir : +Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier +de l’arborescence source. Gardez les ID de scénario stables lorsque les fichiers sont déplacés ; utilisez +`docsRefs` et `codeRefs` pour la traçabilité de l’implémentation. -- les MP et les conversations en canal +La liste de référence doit rester suffisamment large pour couvrir : + +- les MP et le chat en canal - le comportement des fils - le cycle de vie des actions sur les messages - les rappels Cron -- le rappel de mémoire +- le rappel mémoire - le changement de modèle -- le transfert vers un sous-agent +- le transfert à un sous-agent - la lecture du dépôt et de la documentation -- une petite tâche de build comme Lobster Invaders +- une petite tâche de build telle que Lobster Invaders -## Voies avec fournisseur simulé +## Voies mock de fournisseur -`qa suite` dispose de deux voies locales avec fournisseur simulé : +`qa suite` dispose de deux voies mock locales de fournisseur : -- `mock-openai` est le mock OpenClaw sensible aux scénarios. Il reste la - voie simulée déterministe par défaut pour la QA adossée au dépôt et les gates de parité. -- `aimock` démarre un serveur fournisseur adossé à AIMock pour une couverture expérimentale - de protocole, de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne - remplace pas le répartiteur de scénarios `mock-openai`. +- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste la + voie mock déterministe par défaut pour la QA adossée au dépôt et les contrôles de parité. +- `aimock` démarre un serveur de fournisseur adossé à AIMock pour une couverture expérimentale de protocole, + de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne remplace pas + le répartiteur de scénarios `mock-openai`. -L’implémentation des voies fournisseur se trouve sous `extensions/qa-lab/src/providers/`. -Chaque fournisseur possède ses valeurs par défaut, le démarrage de serveur local, la configuration -du modèle Gateway, les besoins de préparation du profil d’auth, et les indicateurs de capacités live/simulées. -Le code partagé de suite et Gateway doit passer par le registre des fournisseurs plutôt que de -se brancher selon les noms de fournisseurs. +L’implémentation des voies de fournisseur se trouve dans `extensions/qa-lab/src/providers/`. +Chaque fournisseur possède ses valeurs par défaut, le démarrage du serveur local, la configuration +du modèle Gateway, les besoins de préparation du profil d’authentification, et les drapeaux de capacité live/mock. +Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu +de brancher sur les noms des fournisseurs. ## Adaptateurs de transport -`qa-lab` possède un point d’intégration de transport générique pour les scénarios QA Markdown. -`qa-channel` est le premier adaptateur sur ce point d’intégration, mais l’objectif de conception est plus large : -les futurs canaux réels ou synthétiques doivent pouvoir se brancher sur le même exécuteur de suite +`qa-lab` possède une jointure de transport générique pour les scénarios QA Markdown. +`qa-channel` est le premier adaptateur sur cette jointure, mais l’objectif de conception est plus large : +les futurs canaux réels ou synthétiques doivent se brancher sur le même exécuteur de suite au lieu d’ajouter un exécuteur QA spécifique au transport. -Au niveau de l’architecture, la séparation est la suivante : +Au niveau de l’architecture, la séparation est la suivante : -- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et les rapports. +- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting. - l’adaptateur de transport possède la configuration Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé. -- les fichiers de scénarios Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute. +- les fichiers de scénario Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute. -Les directives d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans +Les consignes d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans [Testing](/fr/help/testing#adding-a-channel-to-qa). ## 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 live -et écrivez un rapport Markdown évalué : +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 écrivez un rapport Markdown évalué : ```bash pnpm openclaw qa character-eval \ @@ -219,36 +224,36 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -La commande exécute des processus enfants Gateway QA locaux, pas Docker. Les -scénarios d’évaluation de caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur -ordinaires tels que la conversation, 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 conserve chaque -transcription complète, enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec +La commande exécute des processus enfants QA Gateway locaux, pas Docker. Les +scénarios d’évaluation du caractère doivent définir le persona via `SOUL.md`, puis exécuter des tours +utilisateur ordinaires tels que le chat, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle +candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque transcription complète, +enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode fast 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 entre fournisseurs : l’invite du juge reçoit toujours -chaque transcription et l’état d’exécution, mais les références candidates sont remplacées par des -étiquettes neutres telles que `candidate-01` ; le rapport réassocie les classements aux vraies références après +Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours +chaque transcription et état 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 aux vraies références après l’analyse. Les exécutions candidates utilisent par défaut un niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui le prennent en charge. Remplacez un candidat spécifique en ligne avec `--model provider/model,thinking=`. `--thinking ` définit toujours une valeur de repli globale, et l’ancienne forme `--model-thinking ` est conservée pour compatibilité. -Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé là -où le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un -candidat ou juge particulier a besoin d’un remplacement. Passez `--fast` uniquement lorsque vous souhaitez -forcer le mode rapide pour tous les modèles candidats. Les durées des candidats et des juges sont -enregistrées dans le rapport pour l’analyse de benchmark, mais les invites des juges indiquent explicitement +Les références candidates OpenAI utilisent par défaut le mode fast afin que le traitement prioritaire soit utilisé là où +le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un +candidat ou juge donné a besoin d’une substitution. Passez `--fast` uniquement si vous souhaitez +forcer le mode fast pour tous les modèles candidats. Les durées des candidats et des juges sont +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 le Gateway local -rendent une exécution trop bruitée. -Lorsqu’aucun `--model` candidat n’est fourni, l’évaluation de caractère utilise par défaut +`--concurrency` ou `--judge-concurrency` lorsque les limites des fournisseurs ou la pression sur la Gateway locale +rendent une exécution trop bruyante. +Lorsqu’aucun `--model` candidat n’est transmis, 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 -`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est fourni. -Lorsqu’aucun `--judge-model` n’est fourni, les juges utilisent par défaut +`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est transmis. +Lorsqu’aucun `--judge-model` n’est transmis, les juges utilisent par défaut `openai/gpt-5.4,thinking=xhigh,fast` et `anthropic/claude-opus-4-6,thinking=high`. diff --git a/docs/fr/concepts/system-prompt.md b/docs/fr/concepts/system-prompt.md index b702b626d..ec9a26c6d 100644 --- a/docs/fr/concepts/system-prompt.md +++ b/docs/fr/concepts/system-prompt.md @@ -1,14 +1,14 @@ --- read_when: - - Modification du texte du prompt système, de la liste des outils ou des sections d’heure/Heartbeat - - Modification du bootstrap de l’espace de travail ou du comportement d’injection des Skills + - Modification du texte du prompt système, de la liste des outils ou des sections de l’heure/Heartbeat + - Modification du comportement d’amorçage de l’espace de travail ou d’injection des Skills summary: Ce que contient le prompt système d’OpenClaw et comment il est assemblé title: Prompt système x-i18n: - generated_at: "2026-04-15T19:41:43Z" + generated_at: "2026-04-18T06:43:37Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab source_path: concepts/system-prompt.md workflow: 15 --- @@ -19,81 +19,80 @@ OpenClaw construit un prompt système personnalisé pour chaque exécution d’a Le prompt est assemblé par OpenClaw et injecté dans chaque exécution d’agent. -Les plugins de fournisseur peuvent apporter des indications de prompt compatibles avec le cache sans remplacer l’intégralité du prompt détenu par OpenClaw. Le runtime du fournisseur peut : +Les plugins de fournisseur peuvent contribuer avec des indications de prompt conscientes du cache sans remplacer l’intégralité du prompt appartenant à OpenClaw. L’environnement d’exécution du fournisseur peut : -- remplacer un petit ensemble de sections cœur nommées (`interaction_style`, +- remplacer un petit ensemble de sections principales nommées (`interaction_style`, `tool_call_style`, `execution_bias`) -- injecter un **préfixe stable** au-dessus de la limite du cache de prompt -- injecter un **suffixe dynamique** en dessous de la limite du cache de prompt +- injecter un **préfixe stable** au-dessus de la limite de cache du prompt +- injecter un **suffixe dynamique** en dessous de la limite de cache du prompt -Utilisez des contributions détenues par le fournisseur pour les ajustements spécifiques à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour des changements de prompt réellement globaux, pas pour le comportement normal d’un fournisseur. +Utilisez les contributions appartenant au fournisseur pour l’ajustement spécifique à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour de véritables changements globaux du prompt, pas pour le comportement normal d’un fournisseur. ## Structure -Le prompt est volontairement compact et utilise des sections fixes : +Le prompt est intentionnellement compact et utilise des sections fixes : -- **Tooling** : rappel de la source de vérité des outils structurés, plus indications d’utilisation des outils au runtime. -- **Safety** : court rappel de garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision. -- **Skills** (lorsqu’ils sont disponibles) : indique au modèle comment charger à la demande les instructions des Skills. +- **Tooling** : rappel structuré de la source de vérité des outils, plus indications d’exécution sur l’utilisation des outils. +- **Safety** : bref rappel de garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision. +- **Skills** (quand disponibles) : indique au modèle comment charger à la demande les instructions de Skills. - **OpenClaw Self-Update** : comment inspecter la configuration en toute sécurité avec - `config.schema.lookup`, corriger la configuration avec `config.patch`, remplacer la - configuration complète avec `config.apply`, et exécuter `update.run` uniquement sur demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse également de réécrire + `config.schema.lookup`, modifier la configuration avec `config.patch`, remplacer la configuration complète avec `config.apply`, et exécuter `update.run` uniquement à la demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse aussi de réécrire `tools.exec.ask` / `tools.exec.security`, y compris les alias hérités `tools.bash.*` qui se normalisent vers ces chemins exec protégés. - **Workspace** : répertoire de travail (`agents.defaults.workspace`). - **Documentation** : chemin local vers la documentation OpenClaw (dépôt ou package npm) et quand la lire. -- **Workspace Files (injected)** : indique que les fichiers de bootstrap sont inclus ci-dessous. -- **Sandbox** (lorsqu’elle est activée) : indique le runtime sandboxé, les chemins de la sandbox et si l’exécution élevée est disponible. -- **Current Date & Time** : heure locale de l’utilisateur, fuseau horaire et format horaire. +- **Workspace Files (injected)** : indique que des fichiers d’amorçage sont inclus ci-dessous. +- **Sandbox** (quand activé) : indique l’environnement d’exécution sandboxé, les chemins sandbox, et si une exécution avec privilèges élevés est disponible. +- **Current Date & Time** : heure locale de l’utilisateur, fuseau horaire et format d’heure. - **Reply Tags** : syntaxe facultative des balises de réponse pour les fournisseurs pris en charge. -- **Heartbeats** : prompt de Heartbeat et comportement d’accusé de réception, lorsque les Heartbeats sont activés pour l’agent par défaut. -- **Runtime** : hôte, OS, node, modèle, racine du dépôt (lorsqu’elle est détectée), niveau de réflexion (une ligne). -- **Reasoning** : niveau de visibilité actuel + indication de bascule /reasoning. +- **Heartbeats** : prompt Heartbeat et comportement d’accusé de réception, lorsque les Heartbeats sont activés pour l’agent par défaut. +- **Runtime** : hôte, OS, node, modèle, racine du dépôt (quand détectée), niveau de réflexion (une ligne). +- **Reasoning** : niveau de visibilité actuel + indication de bascule `/reasoning`. -La section Tooling inclut également des indications d’exécution pour les tâches longues : +La section Tooling inclut également des indications d’exécution pour le travail de longue durée : - utiliser Cron pour un suivi ultérieur (`check back later`, rappels, travail récurrent) - au lieu de boucles de veille `exec`, d’astuces de délai `yieldMs` ou de sondages `process` - répétés -- utiliser `exec` / `process` uniquement pour des commandes qui démarrent maintenant et continuent à s’exécuter + au lieu de boucles de veille `exec`, d’astuces de délai `yieldMs`, ou d’un sondage répété de `process` +- utiliser `exec` / `process` uniquement pour les commandes qui démarrent maintenant et continuent de s’exécuter en arrière-plan -- lorsque le réveil automatique à la fin est activé, démarrer la commande une seule fois et s’appuyer sur - le mécanisme de réveil push lorsqu’elle produit une sortie ou échoue -- utiliser `process` pour les journaux, l’état, l’entrée ou l’intervention lorsque vous devez +- lorsque le réveil automatique à l’achèvement est activé, démarrer la commande une seule fois et s’appuyer sur + le chemin de réveil par push lorsqu’elle émet une sortie ou échoue +- utiliser `process` pour les journaux, l’état, l’entrée ou une intervention lorsque vous devez inspecter une commande en cours d’exécution -- si la tâche est plus importante, préférer `sessions_spawn` ; la fin des sous-agents est - signalée par push et réannoncée automatiquement au demandeur +- si la tâche est plus importante, préférer `sessions_spawn` ; l’achèvement du sous-agent se fait par push et est annoncé automatiquement au demandeur - ne pas sonder `subagents list` / `sessions_list` en boucle uniquement pour attendre - la fin + l’achèvement -Lorsque l’outil expérimental `update_plan` est activé, Tooling indique également au -modèle de ne l’utiliser que pour un travail non trivial en plusieurs étapes, de conserver exactement une étape +Lorsque l’outil expérimental `update_plan` est activé, Tooling indique aussi au +modèle de ne l’utiliser que pour un travail non trivial à plusieurs étapes, de conserver exactement une étape `in_progress`, et d’éviter de répéter le plan entier après chaque mise à jour. -Les garde-fous de Safety dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations exec, la sandbox et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception. +Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas de politique. Utilisez la politique des outils, les approbations d’exécution, le sandboxing et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception. -Sur les canaux disposant de cartes/boutons d’approbation natifs, le prompt runtime indique désormais à l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle -`/approve` que lorsque le résultat de l’outil indique que les approbations dans le chat ne sont pas disponibles ou que l’approbation manuelle est la seule option. +Sur les canaux disposant de cartes/boutons d’approbation natifs, le prompt d’exécution indique maintenant à +l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle +`/approve` que si le résultat de l’outil indique que les approbations par chat ne sont pas disponibles ou +si l’approbation manuelle est la seule voie possible. ## Modes de prompt -OpenClaw peut générer des prompts système plus petits pour les sous-agents. Le runtime définit un +OpenClaw peut générer des prompts système plus petits pour les sous-agents. L’environnement d’exécution définit un `promptMode` pour chaque exécution (pas une configuration destinée à l’utilisateur) : - `full` (par défaut) : inclut toutes les sections ci-dessus. - `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Memory Recall**, **OpenClaw Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, - **Messaging**, **Silent Replies** et **Heartbeats**. Tooling, **Safety**, - Workspace, Sandbox, Current Date & Time (lorsqu’ils sont connus), Runtime et le contexte + **Messaging**, **Silent Replies**, et **Heartbeats**. Tooling, **Safety**, + Workspace, Sandbox, Current Date & Time (quand connue), Runtime, et le contexte injecté restent disponibles. - `none` : renvoie uniquement la ligne d’identité de base. -Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont étiquetés **Subagent +Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont libellés **Subagent Context** au lieu de **Group Chat Context**. -## Injection du bootstrap de l’espace de travail +## Injection de l’amorçage de l’espace de travail -Les fichiers de bootstrap sont tronqués et ajoutés sous **Project Context** afin que le modèle voie le contexte d’identité et de profil sans avoir besoin de lectures explicites : +Les fichiers d’amorçage sont tronqués puis ajoutés sous **Project Context** afin que le modèle voie le contexte d’identité et de profil sans nécessiter de lectures explicites : - `AGENTS.md` - `SOUL.md` @@ -105,46 +104,46 @@ Les fichiers de bootstrap sont tronqués et ajoutés sous **Project Context** af - `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de repli en minuscules Tous ces fichiers sont **injectés dans la fenêtre de contexte** à chaque tour, sauf si -une condition spécifique au fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque -les Heartbeats sont désactivés pour l’agent par défaut ou que +un garde-fou spécifique à un fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque les +Heartbeats sont désactivés pour l’agent par défaut ou quand `agents.defaults.heartbeat.includeSystemPromptSection` vaut false. Gardez les fichiers injectés concis — -en particulier `MEMORY.md`, qui peut grossir avec le temps et entraîner -une utilisation du contexte étonnamment élevée ainsi qu’une Compaction plus fréquente. +en particulier `MEMORY.md`, qui peut grossir avec le temps et entraîner une utilisation +du contexte étonnamment élevée ainsi qu’une Compaction plus fréquente. > **Remarque :** les fichiers quotidiens `memory/*.md` ne font **pas** partie du -> Project Context de bootstrap normal. Lors des tours ordinaires, ils sont consultés à la demande via les outils -> `memory_search` et `memory_get`, de sorte qu’ils ne comptent pas dans la -> fenêtre de contexte sauf si le modèle les lit explicitement. Les tours `/new` et -> `/reset` seuls constituent l’exception : le runtime peut préfixer de la mémoire quotidienne récente -> comme bloc de contexte de démarrage à usage unique pour ce premier tour. +> Project Context d’amorçage normal. Lors des tours ordinaires, on y accède à la +> demande via les outils `memory_search` et `memory_get`, donc ils ne comptent pas dans la +> fenêtre de contexte tant que le modèle ne les lit pas explicitement. Les tours `/new` et +> `/reset` simples constituent l’exception : l’environnement d’exécution peut préfixer la mémoire quotidienne récente +> sous forme de bloc ponctuel de contexte de démarrage pour ce premier tour. -Les fichiers volumineux sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par -`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total du bootstrap injecté +Les gros fichiers sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par +`agents.defaults.bootstrapMaxChars` (par défaut : 12000). Le contenu total injecté de l’amorçage sur l’ensemble des fichiers est plafonné par `agents.defaults.bootstrapTotalMaxChars` -(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. En cas de troncature, -OpenClaw peut injecter un bloc d’avertissement dans Project Context ; contrôlez cela avec +(par défaut : 60000). Les fichiers manquants injectent un court marqueur de fichier manquant. Lorsqu’une troncature +se produit, OpenClaw peut injecter un bloc d’avertissement dans Project Context ; contrôlez cela avec `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; par défaut : `once`). -Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers de bootstrap -sont filtrés pour garder le contexte du sous-agent réduit). +Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers d’amorçage +sont filtrés pour conserver un petit contexte de sous-agent). Les hooks internes peuvent intercepter cette étape via `agent:bootstrap` pour modifier ou remplacer -les fichiers de bootstrap injectés (par exemple en remplaçant `SOUL.md` par un persona alternatif). +les fichiers d’amorçage injectés (par exemple en remplaçant `SOUL.md` par une persona alternative). Si vous souhaitez que l’agent paraisse moins générique, commencez par [Guide de personnalité SOUL.md](/fr/concepts/soul). -Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge de schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context). +Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge du schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Context](/fr/concepts/context). ## Gestion du temps Le prompt système inclut une section dédiée **Current Date & Time** lorsque le -fuseau horaire de l’utilisateur est connu. Pour garder le cache de prompt stable, il n’inclut désormais que le -**fuseau horaire** (sans horloge dynamique ni format horaire). +fuseau horaire de l’utilisateur est connu. Pour conserver la stabilité du cache du prompt, il inclut désormais uniquement le +**fuseau horaire** (sans horloge dynamique ni format d’heure). Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte d’état -inclut une ligne d’horodatage. Le même outil peut aussi définir un remplacement de modèle par session +inclut une ligne d’horodatage. Le même outil peut aussi définir une substitution de modèle par session (`model=default` l’efface). Configurez avec : @@ -152,17 +151,17 @@ Configurez avec : - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Voir [Date & Time](/fr/date-time) pour tous les détails de comportement. +Voir [Date & Time](/fr/date-time) pour les détails complets du comportement. ## Skills Lorsque des Skills admissibles existent, OpenClaw injecte une **liste compacte des Skills disponibles** -(`formatSkillsForPrompt`) qui inclut le **chemin de fichier** pour chaque Skill. Le -prompt indique au modèle d’utiliser `read` pour charger le SKILL.md à l’emplacement indiqué -(espace de travail, géré ou intégré). Si aucun Skill n’est admissible, la +(`formatSkillsForPrompt`) qui inclut le **chemin de fichier** de chaque Skill. Le +prompt indique au modèle d’utiliser `read` pour charger le SKILL.md à l’emplacement +indiqué (espace de travail, géré ou intégré). Si aucun Skill n’est admissible, la section Skills est omise. -L’admissibilité inclut les conditions des métadonnées des Skills, les vérifications de l’environnement/configuration du runtime, +L’admissibilité comprend les garde-fous de métadonnées du Skill, les vérifications de l’environnement/configuration d’exécution, et la liste d’autorisation effective des Skills de l’agent lorsque `agents.defaults.skills` ou `agents.list[].skills` est configuré. @@ -176,26 +175,26 @@ et la liste d’autorisation effective des Skills de l’agent lorsque `agents.d ``` -Cela permet de conserver un prompt de base réduit tout en rendant possible une utilisation ciblée des Skills. +Cela permet de conserver un petit prompt de base tout en activant un usage ciblé des Skills. Le budget de la liste des Skills appartient au sous-système des Skills : - Valeur globale par défaut : `skills.limits.maxSkillsPromptChars` -- Remplacement par agent : `agents.list[].skillsLimits.maxSkillsPromptChars` +- Substitution par agent : `agents.list[].skillsLimits.maxSkillsPromptChars` -Les extraits runtime génériques bornés utilisent une autre surface : +Les extraits d’exécution génériques bornés utilisent une surface différente : - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Cette séparation permet de découpler le dimensionnement des Skills de celui de la lecture/injection au runtime -comme `memory_get`, les résultats d’outil en direct et les actualisations de `AGENTS.md` après Compaction. +Cette séparation garde le dimensionnement des Skills distinct du dimensionnement de lecture/injection de l’exécution, par exemple pour +`memory_get`, les résultats d’outils en direct, et les actualisations de AGENTS.md après Compaction. ## Documentation Lorsqu’elle est disponible, le prompt système inclut une section **Documentation** qui pointe vers le -répertoire local de la documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du -package npm intégré) et mentionne également le miroir public, le dépôt source, le Discord de la communauté et -ClawHub ([https://clawhub.ai](https://clawhub.ai)) pour la découverte des Skills. Le prompt indique au modèle de consulter d’abord la documentation locale +répertoire local de documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du +package npm intégré) et mentionne également le miroir public, le dépôt source, le Discord de la communauté, et +ClawHub ([https://clawhub.ai](https://clawhub.ai)) pour la découverte de Skills. Le prompt indique au modèle de consulter d’abord la documentation locale pour le comportement, les commandes, la configuration ou l’architecture d’OpenClaw, et d’exécuter lui-même `openclaw status` lorsque c’est possible (en ne demandant à l’utilisateur que lorsqu’il n’y a pas accès). diff --git a/docs/fr/gateway/configuration-reference.md b/docs/fr/gateway/configuration-reference.md index abb8b312d..6c8462900 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 de configuration au niveau des champs ou des valeurs par défaut - - Vous validez des blocs de configuration de canal, de modèle, de Gateway ou d’outil -summary: Référence de configuration de Gateway pour les clés OpenClaw principales, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes + - Vous avez besoin de la sémantique exacte de la configuration au niveau des champs ou des valeurs par défaut. + - Vous validez des blocs de configuration de canal, de modèle, de Gateway ou d’outil. +summary: Référence de configuration du Gateway pour les clés OpenClaw principales, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes title: Référence de configuration x-i18n: - generated_at: "2026-04-15T19:41:43Z" + generated_at: "2026-04-18T06:43:34Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâches, voir [Configuration](/fr/gateway/configuration). -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’inclure sur une seule page chaque catalogue de commandes propre à un canal/Plugin ni chaque paramètre avancé de mémoire/QMD. +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 **n’essaie pas** d’intégrer sur une seule page chaque catalogue de commandes propre à un canal/Plugin ni chaque réglage approfondi 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 des éléments groupés/Plugin/canaux fusionnées lorsqu’elles sont disponibles -- `config.schema.lookup` renvoie un nœud de schéma limité à un chemin pour les outils d’exploration détaillée -- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hachage de référence de la documentation de configuration par rapport à la surface de schéma actuelle +- `openclaw config schema` affiche le schéma JSON actif utilisé pour la validation et l’interface utilisateur Control, avec les métadonnées bundle/plugin/channel fusionnées lorsqu’elles sont disponibles +- `config.schema.lookup` renvoie un nœud de schéma circonscrit à un chemin pour les outils d’exploration détaillée +- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hachage de base des documents de configuration par rapport à la surface de schéma actuelle 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 + groupées -- pages du canal/Plugin propriétaire pour les surfaces de commandes spécifiques au canal +- [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 + bundle +- les pages du canal/Plugin propriétaire pour les surfaces de commande propres 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. +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 aux messages privés et aux groupes +### Accès DM et groupe -Tous les canaux prennent en charge des politiques pour les messages privés et les groupes : +Tous les canaux prennent en charge des politiques de DM et des politiques de groupe : -| Politique de MP | 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 dans le stockage d’autorisation associé) | -| `open` | Autoriser tous les MP entrants (nécessite `allowFrom: ["*"]`) | -| `disabled` | Ignorer tous les MP entrants | +| Politique de DM | Comportement | +| ------------------- | --------------------------------------------------------------- | +| `pairing` (par défaut) | Les expéditeurs inconnus reçoivent un code d’appairage à usage unique ; le propriétaire doit approuver | +| `allowlist` | Uniquement les expéditeurs dans `allowFrom` (ou le stockage d’autorisation appairé) | +| `open` | Autoriser tous les DM entrants (nécessite `allowFrom: ["*"]`) | +| `disabled` | Ignorer tous les DM entrants | -| Politique de groupe | Comportement | -| ---------------------- | ------------------------------------------------------ | +| Politique de groupe | Comportement | +| --------------------- | ----------------------------------------------------- | | `allowlist` (par défaut) | Uniquement les groupes correspondant à la liste d’autorisation configurée | -| `open` | Contourner les listes d’autorisation de groupe (le filtrage par mention s’applique toujours) | -| `disabled` | Bloquer tous les messages de groupe/salon | +| `open` | Contourner les listes d’autorisation 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 de MP en attente sont limitées à **3 par canal**. -Si un bloc de fournisseur est entièrement absent (`channels.` absent), la politique de groupe à l’exécution revient à `allowlist` (échec sécurisé) 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 en mode fermé) avec un avertissement au démarrage. ### Remplacements de modèle par canal -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 mappage du 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 mappage de canal s’applique lorsqu’une session n’a pas déjà un remplacement de modèle (par exemple, défini via `/model`). ```json5 { @@ -105,15 +105,15 @@ Utilisez `channels.defaults` pour le comportement partagé de politique de group } ``` -- `channels.defaults.groupPolicy` : politique de groupe de repli lorsqu’un `groupPolicy` au niveau du 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 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 canaux 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 sous forme d’indicateur. +- `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 de citation/fil/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 statuts de canaux sains dans la sortie Heartbeat. +- `channels.defaults.heartbeat.showAlerts` : inclure les statuts dégradés/en erreur dans la sortie Heartbeat. +- `channels.defaults.heartbeat.useIndicator` : afficher une sortie Heartbeat compacte de type indicateur. ### WhatsApp -WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. +WhatsApp fonctionne via le canal web du Gateway (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. ```json5 { @@ -124,7 +124,7 @@ WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre au textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // coches bleues (false en mode discussion avec soi-même) + sendReadReceipts: true, // coches bleues (false en mode auto-discussion) groups: { "*": { requireMention: true }, }, @@ -225,10 +225,10 @@ WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre au } ``` -- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier normal uniquement ; les liens symboliques sont refusés), avec `TELEGRAM_BOT_TOKEN` comme repli pour le compte par défaut. +- Jeton du 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. - `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 une valeur par défaut explicite (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) pour éviter le routage de repli ; `openclaw doctor` avertit lorsque cela est absent ou invalide. -- `configWrites: false` bloque les écritures de configuration déclenchées depuis Telegram (migrations d’ID de supergroupe, `/config set|unset`). +- `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 discussions directes et de groupe). - Politique de nouvelle tentative : voir [Politique de nouvelle tentative](/fr/concepts/retry). @@ -336,31 +336,31 @@ WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre au - 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 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:` (MP) ou `channel:` (canal de serveur) comme cibles de livraison ; les ID numériques nus sont refusés. -- Les slugs de serveur 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 ID de serveur. +- Utilisez `user:` (DM) ou `channel:` (canal de guilde) pour les cibles de livraison ; les ID numériques seuls sont rejetés. +- Les slugs de guilde sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom transformé en slug (sans `#`). Préférez les ID de guilde. - 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) ignore 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 trop longs en lignes, même lorsqu’ils font moins de 2000 caractères. +- `channels.discord.guilds..ignoreOtherMentions` (et les remplacements au niveau du canal) ignore les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here). +- `maxLinesPerMessage` (17 par défaut) scinde les messages hauts même lorsqu’ils restent sous 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`, ainsi que 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 `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et 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 des conteneurs de composants Discord v2. + - `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 la perte de focus automatique 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 avec `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 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’accent 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 également une récupération de la réception vocale en quittant/rejoignant une session vocale après des échecs répétés de déchiffrement. +- OpenClaw tente également 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. - `channels.discord.streaming` est la clé canonique du mode de flux. Les anciennes valeurs `streamMode` et booléennes `streaming` sont migrées automatiquement. -- `channels.discord.autoPresence` mappe la disponibilité à l’exécution à la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et permet des remplacements facultatifs du texte d’état. -- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag mutable (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 les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers` : ID d’utilisateurs Discord autorisés à approuver les demandes d’exécution. Utilise `commands.ownerAllowFrom` comme repli lorsqu’il est omis. - - `agentFilter` : liste d’autorisation facultative des ID d’agent. Omettez-le pour transférer les approbations pour tous les agents. +- `channels.discord.autoPresence` associe la disponibilité d’exécution à la présence du bot (sain => online, dégradé => idle, épuisé => dnd) et autorise des remplacements facultatifs du texte d’état. +- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag mutable (mode de compatibilité « break-glass »). +- `channels.discord.execApprovals` : livraison des approbations d’exécution native à Discord 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 à partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers` : ID d’utilisateurs Discord autorisés à approuver les demandes d’exécution. Revient à `commands.ownerAllowFrom` lorsqu’il est omis. + - `agentFilter` : liste d’autorisation facultative des ID d’agents. Omettez-la pour transmettre 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 MP des approbateurs, `"channel"` envoie au 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 MP d’approbation après approbation, refus ou expiration. + - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut) envoie vers les DM des approbateurs, `"channel"` envoie vers le canal d’origine, `"both"` envoie vers les 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). @@ -393,11 +393,11 @@ WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre au } ``` -- JSON de compte de service : en ligne (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`). -- SecretRef de compte de service également pris en charge (`serviceAccountRef`). +- JSON du compte de service : intégré (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`). +- SecretRef du compte de service également pris en charge (`serviceAccountRef`). - Variables d’environnement de repli : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Utilisez `spaces/` ou `users/` comme cibles de livraison. -- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance mutable du principal d’e-mail (mode de compatibilité de dernier recours). +- Utilisez `spaces/` ou `users/` pour les cibles de livraison. +- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance mutable du principal d’e-mail (mode de compatibilité « break-glass »). ### Slack @@ -464,39 +464,39 @@ WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre au } ``` -- Le **mode socket** nécessite à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le repli par variable 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 de caractères en clair +- Le **mode socket** exige à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le repli d’environnement du compte par défaut). +- Le **mode HTTP** exige `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 `botTokenSource`, `botTokenStatus`, `appTokenStatus` et, en mode HTTP, +- Les instantanés de compte Slack exposent des champs de source/statut par identifiant tels que + `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. -- `configWrites: false` bloque les écritures de configuration déclenchées depuis Slack. +- `configWrites: false` bloque les écritures de configuration initiées par Slack. - `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:` (MP) ou `channel:` pour les cibles de livraison. +- 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 de session de fil :** `thread.historyScope` est par fil (par défaut) ou partagé avec le canal. `thread.inheritParent` copie la transcription du canal parent vers les nouveaux fils. +**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 vers les nouveaux fils. -- Le flux natif Slack ainsi que l’état de fil de type assistant Slack « is typing... » nécessitent une cible de réponse dans un fil. Les MP 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 qu’une réponse est en cours, puis la supprime à la fin. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`. -- `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"`). +- Le flux natif Slack ainsi que le statut de fil « is typing... » de style assistant Slack exigent 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 le traitement d’une réponse, puis la retire à la fin. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals` : livraison des approbations d’exécution native à Slack 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 | Notes | +| ---------------- | ---------- | ---------------------- | | reactions | activé | Réagir + lister les réactions | | messages | activé | Lire/envoyer/modifier/supprimer | | pins | activé | Épingler/désépingler/lister | -| memberInfo | activé | Informations sur le membre | -| emojiList | activé | Liste des emoji personnalisés | +| memberInfo | activé | Informations sur les membres | +| emojiList | activé | Liste des emojis personnalisés | ### Mattermost -Mattermost est distribué comme un Plugin : `openclaw plugins install @openclaw/mattermost`. +Mattermost est fourni comme Plugin : `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -526,22 +526,22 @@ Mattermost est distribué comme un Plugin : `openclaw plugins install @openclaw } ``` -Modes de discussion : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe de déclenchement). +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 pointer vers le point de terminaison Gateway OpenClaw et être accessible depuis le serveur Mattermost. -- Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés +- Les rappels slash natifs sont authentifiés à l’aide des jetons par commande renvoyés par Mattermost lors de l’enregistrement des commandes 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 nécessiter que - `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/le domaine de rappel. +- Pour les hôtes de rappel privés/tailnet/internes, Mattermost peut exiger que + `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/domaine de rappel. Utilisez des valeurs d’hôte/domaine, pas des URL complètes. -- `channels.mattermost.configWrites` : autoriser ou refuser les écritures de configuration déclenchées depuis Mattermost. +- `channels.mattermost.configWrites` : autoriser ou refuser les écritures de configuration initiées par Mattermost. - `channels.mattermost.requireMention` : exiger une `@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). +- `channels.mattermost.groups..requireMention` : remplacement du filtrage par mention au niveau du canal (`"*"` 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 @@ -551,7 +551,7 @@ Lorsque les commandes natives Mattermost sont activées : channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // liaison de compte facultative dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -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` : autorise ou refuse les écritures de configuration déclenchées depuis Signal. +- `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 un Plugin, configuré sous `channels.bluebubbles`). +BlueBubbles est le chemin recommandé pour iMessage (pris en charge par un Plugin, configuré sous `channels.bluebubbles`). ```json5 { @@ -593,7 +593,7 @@ BlueBubbles est le chemin iMessage recommandé (pris en charge par un Plugin, co ### iMessage -OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port requis. +OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port n’est requis. ```json5 { @@ -621,10 +621,10 @@ OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port requis. - 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 discussions. -- `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`). +- `cliPath` peut pointer vers un wrapper SSH ; définissez `remoteHost` (`host` ou `user@host`) pour la récupération des pièces jointes via SCP. +- `attachmentRoots` et `remoteAttachmentRoots` restreignent 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é d’hôte du relais existe déjà dans `~/.ssh/known_hosts`. -- `channels.imessage.configWrites` : autorise ou refuse les écritures de configuration déclenchées depuis iMessage. +- `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 discussion 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). @@ -670,19 +670,19 @@ Matrix est pris en charge par une extension et configuré sous `channels.matrix` - L’authentification par jeton utilise `accessToken` ; l’authentification par mot de passe utilise `userId` + `password`. - `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 option réseau explicite sont des contrôles indépendants. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette option 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 ; ainsi, les salons invités et les nouvelles invitations de type MP 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 les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. +- `channels.matrix.autoJoin` vaut par défaut `off`, les salons invités et les nouvelles invitations de type DM sont donc ignorés tant que vous ne définissez pas `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals` : livraison des approbations d’exécution native à Matrix 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 à partir de `approvers` ou `commands.ownerAllowFrom`. - `approvers` : ID d’utilisateurs Matrix (par ex. `@owner:example.org`) autorisés à approuver les demandes d’exécution. - - `agentFilter` : liste d’autorisation facultative des ID d’agent. Omettez-le pour transférer les approbations pour tous les agents. + - `agentFilter` : liste d’autorisation facultative des ID d’agents. Omettez-la pour transmettre 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"`. - Remplacements par compte : `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` contrôle la manière dont les MP Matrix sont regroupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon de MP. -- Les sondes d’état Matrix et les recherches en direct dans l’annuaire 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 des exemples d’installation sont documentés dans [Matrix](/fr/channels/matrix). +- `channels.matrix.dm.sessionScope` contrôle la façon dont les DM Matrix sont groupés en sessions : `per-user` (par défaut) partage par pair acheminé, tandis que `per-room` isole chaque salon DM. +- Les sondes d’état Matrix et les recherches dans l’annuaire 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). ### Microsoft Teams @@ -702,7 +702,7 @@ Microsoft Teams est pris en charge par une extension et configuré sous `channel ``` - Chemins de clés principaux couverts ici : `channels.msteams`, `channels.msteams.configWrites`. -- La configuration complète de Teams (identifiants, Webhook, politique MP/groupe, remplacements par équipe/par canal) est documentée dans [Microsoft Teams](/fr/channels/msteams). +- 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 @@ -757,24 +757,24 @@ Exécutez plusieurs comptes par canal (chacun avec son propre `accountId`) : - `default` est utilisé lorsque `accountId` est omis (CLI + routage). - Les jetons d’environnement ne s’appliquent qu’au compte **default**. - Les paramètres de base du canal 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’onboarding du canal) alors que vous êtes encore sur une configuration de canal mono-compte au niveau supérieur, OpenClaw promeut d’abord les valeurs mono-compte de niveau supérieur à portée de compte dans la map des comptes du canal afin que le compte d’origine continue à 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 propres au canal (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons à portée de compte restent facultatives. -- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs mono-compte de niveau supérieur à portée de 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. +- Utilisez `bindings[].match.accountId` pour acheminer chaque compte vers un agent différent. +- 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 mono-compte, OpenClaw promeut d’abord les valeurs mono-compte de niveau supérieur circonscrites au compte vers 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 uniquement au niveau du canal (sans `accountId`) continuent à correspondre au compte par défaut ; les liaisons circonscrites au compte restent facultatives. +- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs mono-compte de niveau supérieur circonscrites 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 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). +De nombreux canaux d’extension sont configurés en tant que `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). ### Filtrage par mention dans les discussions de groupe -Par défaut, les messages de groupe **nécessitent une mention** (mention dans les métadonnées ou motifs regex sûrs). Cela s’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage. +Les messages de groupe exigent par défaut **une mention obligatoire** (mention dans les métadonnées ou motifs regex sûrs). S’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage. **Types de mention :** -- **Mentions dans les métadonnées** : mentions @ natives de la plateforme. Ignorées en mode discussion avec soi-même sur WhatsApp. -- **Motifs textuels** : 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. +- **Mentions dans les métadonnées** : mentions @ natives de la plateforme. Ignorées en mode auto-discussion WhatsApp. +- **Motifs de 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). ```json5 @@ -788,9 +788,9 @@ Par défaut, les messages de groupe **nécessitent une mention** (mention dans l } ``` -`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 la 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 MP +#### Limites d’historique DM ```json5 { @@ -805,13 +805,13 @@ Par défaut, les messages de groupe **nécessitent une mention** (mention dans l } ``` -Résolution : remplacement par MP → valeur par défaut du fournisseur → aucune limite (tout est conservé). +Résolution : remplacement par DM → valeur par défaut du fournisseur → aucune limite (tout est conservé). Pris en charge : `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Mode discussion avec soi-même +#### Mode auto-discussion -Incluez votre propre numéro dans `allowFrom` pour activer le mode discussion avec soi-même (ignore les mentions @ natives, répond uniquement aux motifs textuels) : +Incluez votre propre numéro dans `allowFrom` pour activer le mode auto-discussion (ignore les mentions @ natives, répond uniquement aux motifs textuels) : ```json5 { @@ -832,7 +832,7 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode discussion av } ``` -### Commands (gestion des commandes de discussion) +### Commandes (gestion des commandes de chat) ```json5 { @@ -861,32 +861,32 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode discussion av -- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + groupées, voir [Commandes Slash](/fr/tools/slash-commands). -- Cette page est une **référence des clés de configuration**, pas le catalogue complet des commandes. Les commandes propres à 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 textuelles 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 natives de Skills pour Discord/Telegram, laisse Slack désactivé. +- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + bundle, voir [Commandes slash](/fr/tools/slash-commands). +- Cette page est une **référence des clés de configuration**, pas le catalogue complet des commandes. Les commandes propres à un canal/Plugin, comme 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 textuelles doivent être des messages **autonomes** commençant par `/`. +- `native: "auto"` active les commandes natives pour Discord/Telegram, et laisse Slack désactivé. +- `nativeSkills: "auto"` active les commandes natives de Skills 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`. +- Remplacez l’enregistrement natif des commandes de 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 un expéditeur présent dans `tools.elevated.allowFrom.`. -- `config: true` active `/config` (lit/écrit `openclaw.json`). Pour les clients Gateway `chat.send`, les écritures persistantes `/config set|unset` nécessitent aussi `operator.admin` ; la commande en lecture seule `/config show` reste disponible pour les clients opérateur normaux avec portée d’écriture. +- `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 `chat.send` du Gateway, les écritures persistantes `/config set|unset` exigent également `operator.admin` ; `/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 du serveur MCP géré 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. +- `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 aussi 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 Gateway. 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 du Gateway. Par défaut : `true`. - `ownerAllowFrom` est la liste d’autorisation explicite du propriétaire pour les commandes/outils réservés au propriétaire. Elle est distincte de `allowFrom`. -- `ownerDisplay: "hash"` hache les ID de propriétaire dans l’invite 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’autorisation/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. +- `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 l’**unique** source d’autorisation (les listes d’autorisation/appairage du 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 propres au canal : [Canaux](/fr/channels) + - catalogue intégré + bundle : [Commandes slash](/fr/tools/slash-commands) + - surfaces de commande propres aux canaux : [Canaux](/fr/channels) - commandes QQ Bot : [QQ Bot](/fr/channels/qqbot) - - commandes d’association : [Pairing](/fr/channels/pairing) + - commandes d’appairage : [Appairage](/fr/channels/pairing) - commande de carte LINE : [LINE](/fr/channels/line) - - dreaming de memory : [Dreaming](/fr/concepts/dreaming) + - Dreaming de la mémoire : [Dreaming](/fr/concepts/dreaming) @@ -906,7 +906,7 @@ Par défaut : `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Racine de dépôt facultative affichée dans la ligne Runtime de l’invite système. Si elle n’est pas définie, OpenClaw la détecte automatiquement en remontant depuis l’espace de travail. +Racine de dépôt facultative affichée dans la ligne Runtime du prompt système. Si elle n’est pas définie, OpenClaw la détecte automatiquement en remontant depuis le workspace. ```json5 { @@ -916,7 +916,7 @@ Racine de dépôt facultative affichée dans la ligne Runtime de l’invite syst ### `agents.defaults.skills` -Liste d’autorisation par défaut facultative de Skills pour les agents qui ne définissent pas +Liste d’autorisation de Skills par défaut facultative pour les agents qui ne définissent pas `agents.list[].skills`. ```json5 @@ -924,23 +924,23 @@ Liste d’autorisation par défaut facultative de Skills pour les agents qui ne 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 non restreints par défaut. +- Omettez `agents.defaults.skills` pour autoriser tous les Skills par défaut. - Omettez `agents.list[].skills` pour hériter des valeurs par défaut. - Définissez `agents.list[].skills: []` pour n’avoir aucun Skills. -- Une liste non vide dans `agents.list[].skills` est l’ensemble final pour cet agent ; elle +- Une liste non vide `agents.list[].skills` est l’ensemble final pour cet agent ; elle ne fusionne pas avec les valeurs par défaut. ### `agents.defaults.skipBootstrap` -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`). +Désactive la création automatique des fichiers bootstrap du workspace (`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 de l’espace de trav ### `agents.defaults.contextInjection` -Contrôle à quel moment les fichiers bootstrap de l’espace de travail sont injectés dans l’invite système. Par défaut : `"always"`. +Contrôle quand les fichiers bootstrap du workspace 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 terminée de l’assistant) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille de l’invite. Les exécutions Heartbeat et les nouvelles tentatives après Compaction reconstruisent toujours le contexte. +- `"continuation-skip"` : les tours de continuation sûrs (après une réponse complète de l’assistant) évitent la réinjection du bootstrap du workspace, réduisant la taille du prompt. Les exécutions Heartbeat et les nouvelles tentatives post-Compaction reconstruisent toujours le contexte. ```json5 { @@ -962,21 +962,21 @@ Contrôle à quel moment les fichiers bootstrap de l’espace de travail sont in ### `agents.defaults.bootstrapMaxChars` -Nombre maximal de caractères par fichier bootstrap de l’espace de travail avant troncature. Par défaut : `20000`. +Nombre maximal de caractères par fichier bootstrap du workspace avant troncature. Par défaut : `12000`. ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -Nombre total maximal de caractères injectés sur l’ensemble des fichiers bootstrap de l’espace de travail. Par défaut : `150000`. +Nombre total maximal de caractères injectés dans l’ensemble des fichiers bootstrap du workspace. Par défaut : `60000`. ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` @@ -985,8 +985,8 @@ Nombre total maximal de caractères injectés sur l’ensemble des fichiers boot Contrôle le texte d’avertissement visible par l’agent lorsque le contexte bootstrap est tronqué. Par défaut : `"once"`. -- `"off"` : n’injecte jamais de texte d’avertissement dans l’invite système. -- `"once"` : injecte l’avertissement une fois par signature de troncature unique (recommandé). +- `"off"` : n’injecte jamais de texte d’avertissement dans le prompt système. +- `"once"` : injecte l’avertissement une fois par signature unique de troncature (recommandé). - `"always"` : injecte l’avertissement à chaque exécution lorsqu’une troncature existe. ```json5 @@ -998,21 +998,21 @@ Par défaut : `"once"`. ### Cartographie de propriété du budget de contexte OpenClaw possède plusieurs budgets de prompt/contexte à fort volume, et ils sont -volontairement répartis par sous-système au lieu de tous passer par un unique -paramètre générique. +délibérément répartis par sous-système au lieu de tous passer par un unique +réglage générique. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars` : - injection bootstrap normale de l’espace de travail. + injection bootstrap normale du workspace. - `agents.defaults.startupContext.*` : - prélude de démarrage ponctuel pour `/new` et `/reset`, y compris les fichiers + préambule de démarrage à usage unique pour `/new` et `/reset`, y compris les fichiers récents `memory/*.md` quotidiens. - `skills.limits.*` : - la liste compacte de Skills injectée dans l’invite système. + la liste compacte des Skills injectée dans le prompt système. - `agents.defaults.contextLimits.*` : - extraits bornés à l’exécution et blocs injectés appartenant à l’exécution. + extraits d’exécution bornés et blocs injectés appartenant à l’exécution. - `memory.qmd.limits.*` : - dimensionnement des extraits et de l’injection de recherche mémoire indexée. + extraits de recherche mémoire indexés et dimensionnement d’injection. Utilisez le remplacement correspondant par agent uniquement lorsqu’un agent a besoin d’un budget différent : @@ -1022,8 +1022,8 @@ budget différent : #### `agents.defaults.startupContext` -Contrôle le prélude de démarrage du premier tour injecté lors des exécutions -simples `/new` et `/reset`. +Contrôle le préambule de démarrage du premier tour injecté lors des exécutions +`/new` et `/reset` sans autre contenu. ```json5 { @@ -1044,7 +1044,7 @@ simples `/new` et `/reset`. #### `agents.defaults.contextLimits` -Valeurs partagées par défaut pour les surfaces de contexte bornées à l’exécution. +Valeurs par défaut partagées pour les surfaces de contexte d’exécution bornées. ```json5 { @@ -1061,18 +1061,18 @@ Valeurs partagées par défaut pour les surfaces de contexte bornées à l’ex } ``` -- `memoryGetMaxChars` : plafond par défaut de l’extrait `memory_get` avant l’ajout - des métadonnées de troncature et de l’avis de continuation. -- `memoryGetDefaultLines` : fenêtre de lignes par défaut de `memory_get` lorsque `lines` est +- `memoryGetMaxChars` : plafond d’extrait `memory_get` par défaut avant l’ajout des + métadonnées de troncature et de l’avis de continuation. +- `memoryGetDefaultLines` : fenêtre de lignes `memory_get` par défaut lorsque `lines` est omis. -- `toolResultMaxChars` : plafond des résultats d’outil en direct utilisé pour les résultats persistés et - la récupération en cas de débordement. -- `postCompactionMaxChars` : plafond d’extrait AGENTS.md utilisé lors de l’injection - d’actualisation après Compaction. +- `toolResultMaxChars` : plafond des résultats d’outil en direct utilisé pour les résultats persistés et la + récupération de débordement. +- `postCompactionMaxChars` : plafond d’extrait de `AGENTS.md` utilisé lors de l’injection de + rafraîchissement post-Compaction. #### `agents.list[].contextLimits` -Remplacement par agent pour les paramètres partagés `contextLimits`. Les champs omis héritent +Remplacement par agent pour les réglages partagés `contextLimits`. Les champs omis héritent de `agents.defaults.contextLimits`. ```json5 @@ -1099,7 +1099,7 @@ de `agents.defaults.contextLimits`. #### `skills.limits.maxSkillsPromptChars` -Plafond global pour la liste compacte de Skills injectée dans l’invite système. Cela +Plafond global pour la liste compacte des Skills injectée dans le prompt système. Cela n’affecte pas la lecture à la demande des fichiers `SKILL.md`. ```json5 @@ -1114,7 +1114,7 @@ n’affecte pas la lecture à la demande des fichiers `SKILL.md`. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Remplacement par agent pour le budget d’invite des Skills. +Remplacement par agent pour le budget du prompt de Skills. ```json5 { @@ -1133,10 +1133,10 @@ Remplacement par agent pour le budget d’invite des Skills. ### `agents.defaults.imageMaxDimensionPx` -Taille maximale en pixels du plus long côté de l’image dans les blocs image de transcription/d’outil avant les appels fournisseur. +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’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 faibles réduisent généralement l’usage des jetons de vision et la taille des charges utiles pour les exécutions riches en captures d’écran. Des valeurs plus élevées préservent davantage de détails visuels. ```json5 @@ -1147,7 +1147,7 @@ Des valeurs plus élevées préservent davantage de détails visuels. ### `agents.defaults.userTimezone` -Fuseau horaire pour le contexte de l’invite système (pas les horodatages des messages). Revient au fuseau horaire de l’hôte. +Fuseau horaire pour le contexte du prompt système (pas les horodatages des messages). Revient au fuseau horaire de l’hôte. ```json5 { @@ -1157,7 +1157,7 @@ Fuseau horaire pour le contexte de l’invite système (pas les horodatages des ### `agents.defaults.timeFormat` -Format d’heure dans l’invite système. 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 de l’OS). ```json5 { @@ -1195,7 +1195,7 @@ Format d’heure dans l’invite système. Par défaut : `auto` (préférence d 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 embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1215,45 +1215,45 @@ Format d’heure dans l’invite système. Par défaut : `auto` (préférence d ``` - `model` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - La forme chaîne ne définit que le modèle principal. - - La forme objet définit le modèle principal ainsi que les modèles de basculement ordonnés. + - La forme chaîne définit uniquement le modèle principal. + - La forme objet définit le principal plus des modèles de bascule ordonnés. - `imageModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par le chemin d’outil `image` comme configuration de modèle de vision. + - 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 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’image et par 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’image Gemini native, `fal/fal-ai/flux/dev` pour fal, ou `openai/gpt-image-1` pour OpenAI Images. + - 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 Gemini native, `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 aussi 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/*`). - - Si omis, `image_generate` peut quand même déduire une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’image enregistrés restants dans l’ordre des ID de fournisseur. + - Si omis, `image_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’images enregistrés dans l’ordre des ID de fournisseur. - `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 par l’outil intégré `music_generate`. + - 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+`. - - Si omis, `music_generate` peut quand même déduire une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale enregistrés restants dans l’ordre des ID de fournisseur. + - Si omis, `music_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale enregistrés dans l’ordre des ID de fournisseur. - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification/la clé API du fournisseur 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 par l’outil intégré `video_generate`. + - 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`. - - Si omis, `video_generate` peut quand même déduire une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération vidéo enregistrés restants dans l’ordre des ID de fournisseur. + - Si omis, `video_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération vidéo enregistrés dans l’ordre des ID de fournisseur. - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi 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 au niveau du fournisseur `size`, `aspectRatio`, `resolution`, `audio` et `watermark`. + - 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 et les options de niveau fournisseur `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 du modèle. - Si omis, l’outil PDF revient à `imageModel`, puis au 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 considéré par défaut par le mode de repli d’extraction dans l’outil `pdf`. -- `verboseDefault` : niveau verbeux par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`. +- `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas transmis à 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 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 fournisseur, OpenClaw essaie d’abord un alias, puis une correspondance unique de fournisseur configuré pour cet ID de modèle exact, et seulement ensuite revient au fournisseur par défaut configuré (comportement de compatibilité obsolète, il est donc préférable d’utiliser explicitement `provider/model`). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient au premier fournisseur/modèle configuré au lieu d’exposer une valeur par défaut obsolète d’un fournisseur supprimé. -- `models` : catalogue et liste d’autorisation des 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é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é. Voir [Mise en cache des invites](/fr/reference/prompt-caching) pour les détails. -- `embeddedHarness` : politique par défaut du runtime d’agent intégré de bas niveau. Utilisez `runtime: "auto"` pour laisser les harnesses de Plugin enregistrés revendiquer les modèles pris en charge, `runtime: "pi"` pour forcer le harness PI intégré, ou un ID de harness enregistré tel que `runtime: "codex"`. Définissez `fallback: "none"` pour désactiver le repli automatique sur PI. -- Les rédacteurs 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 c’est possible. -- `maxConcurrent` : nombre maximal d’exécutions parallèles d’agents entre les sessions (chaque session reste tout de même sérialisée). Par défaut : 4. +- `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 ID de modèle exact, et seulement ensuite revient au fournisseur par défaut configuré (comportement de compatibilité déprécié, donc préférez l’explicite `provider/model`). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient au premier fournisseur/modèle configuré au lieu d’exposer un ancien défaut d’un fournisseur supprimé. +- `models` : le catalogue de modèles configuré et la liste d’autorisation 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 de fournisseur par défaut 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` (ID d’agent correspondant) remplace par clé. Voir [Prompt Caching](/fr/reference/prompt-caching) pour les détails. +- `embeddedHarness` : politique d’exécution embarquée bas niveau par défaut pour les agents. Utilisez `runtime: "auto"` pour laisser les harness de Plugin enregistrés revendiquer les modèles pris en charge, `runtime: "pi"` pour forcer le harness PI intégré, ou un ID de harness enregistré tel que `runtime: "codex"`. Définissez `fallback: "none"` pour désactiver le repli automatique vers PI. +- Les outils d’écriture 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 parallèles d’agents entre les sessions (chaque session reste sérialisée). Par défaut : 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` contrôle quel exécuteur de bas niveau exécute les tours d’agent intégrés. +`embeddedHarness` contrôle quel exécuteur bas niveau traite les tours d’agent embarqués. La plupart des déploiements devraient conserver la valeur par défaut `{ runtime: "auto", fallback: "pi" }`. Utilisez-le lorsqu’un Plugin de confiance fournit un harness natif, comme le harness groupé du serveur d’application Codex. @@ -1274,32 +1274,32 @@ groupé du serveur d’application Codex. - `runtime` : `"auto"`, `"pi"` ou un ID de harness de Plugin enregistré. Le Plugin Codex groupé enregistre `codex`. - `fallback` : `"pi"` ou `"none"`. `"pi"` conserve le harness PI intégré comme repli de compatibilité. `"none"` fait échouer une sélection de harness de Plugin absente ou non prise en charge au lieu d’utiliser silencieusement PI. -- Remplacements par variables d’environnement : `OPENCLAW_AGENT_RUNTIME=` remplace `runtime` ; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` désactive le repli PI pour ce processus. +- Remplacements d’environnement : `OPENCLAW_AGENT_RUNTIME=` remplace `runtime` ; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` désactive le repli PI pour ce processus. - Pour les déploiements Codex uniquement, définissez `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` et `embeddedHarness.fallback: "none"`. -- Cela ne contrôle que le harness de discussion intégré. La génération de médias, la vision, le PDF, la musique, la vidéo et la TTS utilisent toujours leurs paramètres fournisseur/modèle. +- Cela ne contrôle que le harness de chat embarqué. La génération de média, la vision, les PDF, la musique, la vidéo et le TTS utilisent toujours leurs paramètres fournisseur/modèle. -**Alias raccourcis intégrés** (ne s’appliquent que lorsque le modèle est dans `agents.defaults.models`) : +**Raccourcis d’alias intégrés** (s’appliquent uniquement lorsque le modèle figure dans `agents.defaults.models`) : -| Alias | Modèle | -| ------------------- | -------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| Alias | Modèle | +| ------------------- | ------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | 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 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’outil. 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 le mode thinking `adaptive` lorsqu’aucun niveau explicite de thinking n’est défini. +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 le mode thinking `adaptive` lorsqu’aucun niveau de thinking explicite n’est défini. ### `agents.defaults.cliBackends` -Backends CLI facultatifs pour les exécutions de repli texte uniquement (sans appels d’outil). Utiles comme solution de secours lorsque les fournisseurs d’API échouent. +Backends CLI facultatifs pour les exécutions de repli en texte seul (sans appels d’outil). Utile comme solution de secours lorsque les fournisseurs d’API échouent. ```json5 { @@ -1327,13 +1327,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. +- 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 direct d’images est pris en charge lorsque `imageArg` accepte des chemins de fichiers. +- Le passage d’images est pris en charge lorsque `imageArg` accepte des chemins de fichiers. ### `agents.defaults.systemPromptOverride` -Remplace l’intégralité de l’invite système assemblée 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 d’invite contrôlées. +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 de prompt contrôlées. ```json5 { @@ -1347,7 +1347,7 @@ Remplace l’intégralité de l’invite système assemblée par OpenClaw par un ### `agents.defaults.heartbeat` -Exécutions périodiques Heartbeat. +Exécutions Heartbeat périodiques. ```json5 { @@ -1375,14 +1375,14 @@ Exécutions périodiques Heartbeat. ``` - `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 de l’invite 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 lors des exécutions Heartbeat. -- `timeoutSeconds` : durée maximale en secondes autorisée pour un tour d’agent Heartbeat avant son interruption. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. -- `directPolicy` : politique de livraison directe/MP. `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’exécute dans une session fraîche sans historique de conversation antérieur. Même modèle 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 définit `heartbeat`, **seuls ces agents** exécutent des Heartbeats. -- Les Heartbeats exécutent des tours complets d’agent — des intervalles plus courts consomment davantage de jetons. +- `includeSystemPromptSection` : lorsqu’il vaut 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` : lorsqu’il vaut true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions Heartbeat. +- `timeoutSeconds` : durée maximale en secondes autorisée pour un tour d’agent Heartbeat avant interruption. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. +- `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison à une cible directe. `block` supprime la livraison à une cible directe et émet `reason=dm-blocked`. +- `lightContext` : lorsqu’il vaut true, les exécutions Heartbeat utilisent un contexte bootstrap allégé et ne conservent que `HEARTBEAT.md` parmi les fichiers bootstrap du workspace. +- `isolatedSession` : lorsqu’il vaut true, chaque Heartbeat s’exécute dans une nouvelle session 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 à ~2-5K jetons. +- Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent quelconque définit `heartbeat`, **seuls ces agents** exécutent des Heartbeat. +- Les Heartbeat exécutent des tours d’agent complets — des intervalles plus courts consomment plus de jetons. ### `agents.defaults.compaction` @@ -1412,19 +1412,19 @@ Exécutions périodiques Heartbeat. } ``` -- `mode` : `default` ou `safeguard` (résumé par morceaux pour les longs historiques). Voir [Compaction](/fr/concepts/compaction). -- `provider` : ID d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, le `summarize()` du fournisseur est appelé au lieu du résumé LLM intégré. Revient à 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 seule opération de Compaction avant qu’OpenClaw ne l’interrompe. Par défaut : `900`. +- `mode` : `default` ou `safeguard` (résumé par blocs pour les longs historiques). Voir [Compaction](/fr/concepts/compaction). +- `provider` : ID d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, le `summarize()` du fournisseur est appelé à la place du résumé LLM intégré. Revient à 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é pour une opération unique de Compaction avant qu’OpenClaw ne l’interrompe. Par défaut : `900`. - `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` préfixe des consignes intégrées de conservation des identifiants opaques pendant le résumé de Compaction. -- `identifierInstructions` : texte facultatif personnalisé de préservation des identifiants utilisé lorsque `identifierPolicy=custom`. -- `postCompactionSections` : noms facultatifs de sections H2/H3 d’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 en-têtes `Every Session`/`Safety` sont également acceptés comme solution de repli héritée. -- `model` : remplacement facultatif `provider/model-id` uniquement pour le résumé de Compaction. 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émarrage de la Compaction (par exemple, « Compacting context... »). 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. +- `identifierInstructions` : texte personnalisé facultatif de conservation 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 en-têtes `Every Session`/`Safety` sont aussi acceptés comme repli hérité. +- `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 être exécutés sur un autre ; lorsqu’il n’est pas défini, la Compaction utilise le modèle principal de la session. +- `notifyUser` : lorsqu’il vaut `true`, envoie un bref avis à l’utilisateur au démarrage de la Compaction (par exemple, « Compactage du contexte... »). Désactivé par défaut afin que la Compaction reste silencieuse. +- `memoryFlush` : tour agentique silencieux avant la Compaction automatique pour stocker les mémoires durables. Ignoré lorsque le workspace est en lecture seule. ### `agents.defaults.contextPruning` -É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. +Émonde les **anciens résultats d’outils** du contexte en mémoire avant l’envoi au LLM. **Ne modifie pas** l’historique de session sur le disque. ```json5 { @@ -1448,23 +1448,23 @@ Exécutions périodiques Heartbeat. -- `mode: "cache-ttl"` active les passes d’élagage. -- `ttl` contrôle la fréquence à laquelle l’élagage peut à nouveau s’exécuter (après le dernier contact avec le cache). -- L’élagage raccourcit d’abord légèrement les résultats d’outil trop volumineux, puis efface complètement les anciens résultats d’outil si nécessaire. +- `mode: "cache-ttl"` active les passes d’émondage. +- `ttl` contrôle à quelle fréquence l’émondage peut être réexécuté (après le dernier accès au cache). +- L’émondage tronque d’abord partiellement les résultats d’outils surdimensionnés, puis efface complètement les anciens résultats d’outils si nécessaire. -**Soft-trim** conserve le début + la fin et insère `...` au milieu. +**Le tronquage partiel** conserve le début + la fin et insère `...` au milieu. -**Hard-clear** remplace l’intégralité du résultat d’outil par le texte de remplacement. +**L’effacement complet** remplace l’intégralité du résultat d’outil par le texte de remplacement. Remarques : -- Les blocs d’image ne sont jamais raccourcis ni effacés. -- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptages exacts de jetons. -- S’il existe moins de `keepLastAssistants` messages d’assistant, l’élagage est ignoré. +- Les blocs d’image ne sont jamais tronqués/effacés. +- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptes exacts de jetons. +- S’il existe moins de `keepLastAssistants` messages d’assistant, l’émondage est ignoré. -Voir [Élagage de session](/fr/concepts/session-pruning) pour le détail du comportement. +Voir [Émondage de session](/fr/concepts/session-pruning) pour les détails de comportement. ### Streaming par blocs @@ -1482,13 +1482,13 @@ Voir [Élagage de session](/fr/concepts/session-pruning) pour le détail du comp } ``` -- Les canaux autres que Telegram nécessitent un `*.blockStreaming: true` explicite pour activer les réponses par blocs. +- Les canaux autres que Telegram exigent `*.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–2500 ms. Remplacement par agent : `agents.list[].humanDelay`. +- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500ms. Remplacement par agent : `agents.list[].humanDelay`. -Voir [Streaming](/fr/concepts/streaming) pour le comportement + les détails de découpage. +Voir [Streaming](/fr/concepts/streaming) pour le comportement et les détails de segmentation. -### Indicateurs de saisie +### Indicateurs de frappe ```json5 { @@ -1504,13 +1504,13 @@ Voir [Streaming](/fr/concepts/streaming) pour le comportement + les détails de - Valeurs par défaut : `instant` pour les discussions 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). +Voir [Indicateurs de frappe](/fr/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing facultatif pour l’agent intégré. Voir [Sandboxing](/fr/gateway/sandboxing) pour le guide complet. +Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sandboxing) pour le guide complet. ```json5 { @@ -1605,25 +1605,25 @@ Sandboxing facultatif pour l’agent intégré. 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 d’exécution Docker local (par défaut) +- `ssh` : environnement d’exécution distant générique adossé à SSH +- `openshell` : environnement d’exécution OpenShell -Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques au runtime sont déplacés vers +Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques à l’environnement d’exécution sont déplacés vers `plugins.entries.openshell.config`. **Configuration du backend SSH :** - `target` : cible SSH au format `user@host[:port]` -- `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 passés à OpenSSH -- `identityData` / `certificateData` / `knownHostsData` : contenus en ligne ou SecretRefs qu’OpenClaw matérialise en fichiers temporaires à l’exécution -- `strictHostKeyChecking` / `updateHostKeys` : paramètres de politique de clé d’hôte OpenSSH +- `command` : commande client SSH (par défaut : `ssh`) +- `workspaceRoot` : racine distante absolue utilisée pour les workspaces par portée +- `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants transmis à OpenSSH +- `identityData` / `certificateData` / `knownHostsData` : contenus intégrés ou SecretRefs qu’OpenClaw matérialise dans des fichiers temporaires à l’exécution +- `strictHostKeyChecking` / `updateHostKeys` : réglages de politique de clé d’hôte OpenSSH **Priorité de l’authentification SSH :** @@ -1634,23 +1634,23 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques a **Comportement du backend SSH :** -- amorce l’espace de travail distant une fois après sa création ou recréation -- conserve ensuite l’espace de travail SSH distant comme source canonique -- route `exec`, les outils de fichier et les chemins de média via SSH -- ne synchronise pas automatiquement les modifications distantes vers l’hôte +- initialise le workspace distant une fois après création ou recréation +- puis conserve le workspace SSH distant comme canonique +- achemine `exec`, les outils de fichiers et les chemins média via SSH +- ne resynchronise pas automatiquement les modifications distantes vers l’hôte - ne prend pas en charge les conteneurs de navigateur sandbox -**Accès à l’espace de travail :** +**Accès au workspace :** -- `none` : espace de travail sandbox par portée sous `~/.openclaw/sandboxes` -- `ro` : espace de travail sandbox à `/workspace`, espace de travail de l’agent monté en lecture seule à `/agent` -- `rw` : espace de travail de l’agent monté en lecture/écriture à `/workspace` +- `none` : workspace sandbox par portée sous `~/.openclaw/sandboxes` +- `ro` : workspace sandbox à `/workspace`, workspace agent monté en lecture seule sur `/agent` +- `rw` : workspace agent monté en lecture/écriture sur `/workspace` **Portée :** -- `session` : conteneur + espace de travail par session -- `agent` : un conteneur + espace de travail par agent (par défaut) -- `shared` : conteneur et espace de travail partagés (aucune isolation entre sessions) +- `session` : conteneur + workspace par session +- `agent` : un conteneur + workspace par agent (par défaut) +- `shared` : conteneur et workspace partagés (aucune isolation inter-sessions) **Configuration du Plugin OpenShell :** @@ -1680,30 +1680,30 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques a **Mode OpenShell :** -- `mirror` : amorce le distant depuis le local avant `exec`, resynchronise après `exec` ; l’espace de travail local reste canonique -- `remote` : amorce 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 vers le local après `exec` ; le workspace local reste canonique +- `remote` : initialise le distant une fois lors de la création du sandbox, puis conserve le workspace distant comme canonique -En mode `remote`, les modifications locales sur l’hôte effectuées hors d’OpenClaw ne sont pas synchronisées automatiquement dans le sandbox après l’étape d’amorçage. -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. +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 s’effectue en SSH dans 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 accessible en écriture, et l’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 accessible en écriture et l’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 dernier recours). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (mode « break-glass »). -**Les pièces jointes entrantes** sont préparées dans `media/inbound/*` dans l’espace de travail actif. +**Les pièces jointes entrantes** sont placées dans `media/inbound/*` dans le workspace 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 l’invite système. Ne nécessite pas `browser.enabled` dans `openclaw.json`. +**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). - `allowHostControl: false` (par défaut) empêche les sessions sandboxées de cibler le navigateur de l’hôte. -- `network` vaut par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez `bridge` uniquement lorsque vous souhaitez explicitement une connectivité bridge globale. +- `network` vaut par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez-le sur `bridge` uniquement si vous voulez explicitement une connectivité bridge globale. - `cdpSourceRange` restreint éventuellement 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ôtes 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 de conteneurs : +- `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 par défaut de lancement sont définies dans `scripts/sandbox-browser-entrypoint.sh` et réglées pour les hôtes de conteneurs : - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1723,24 +1723,24 @@ L’accès observateur noVNC utilise l’authentification VNC par défaut et Ope - `--disable-extensions` (activé par défaut) - `--disable-3d-apis`, `--disable-software-rasterizer` et `--disable-gpu` sont activés par défaut et peuvent être désactivés avec - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si l’utilisation de WebGL/3D l’exige. + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si un usage WebGL/3D l’exige. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` réactive les extensions si votre flux de travail en dépend. - `--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 constituent la ligne de 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. + - Les valeurs par défaut correspondent à la base de l’image du 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 pris en charge uniquement avec Docker. +Le sandboxing du navigateur et `sandbox.docker.binds` sont disponibles uniquement avec 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 sandbox principale +scripts/sandbox-browser-setup.sh # image de navigateur facultative ``` ### `agents.list` (remplacements par agent) @@ -1793,26 +1793,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `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 utilisée par défaut. -- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les valeurs de repli globales). Les tâches Cron qui ne remplacent que `primary` héritent toujours des valeurs de repli par défaut sauf si vous définissez `fallbacks: []`. -- `params` : paramètres de flux par agent fusionnés par-dessus l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez cela pour des remplacements spécifiques à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer l’ensemble du catalogue de modèles. -- `skills` : liste d’autorisation facultative de 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 par défaut facultatif de thinking 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é par défaut facultative du reasoning par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement de reasoning par message ou session n’est défini. -- `fastModeDefault` : valeur par défaut facultative du mode rapide par agent (`true | false`). S’applique lorsqu’aucun remplacement de mode rapide par message ou session n’est défini. -- `embeddedHarness` : remplacement facultatif de politique de harness de bas niveau par agent. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent réservé à Codex tandis que les autres agents conservent le repli PI par défaut. -- `runtime` : descripteur facultatif du runtime 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 harness ACP. -- `identity.avatar` : chemin relatif à l’espace de travail, URL `http(s)` ou URI `data:`. +- `default` : lorsque plusieurs sont définis, le premier l’emporte (avertissement journalisé). Si aucun n’est défini, la première entrée de la 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 sauf si vous définissez `fallbacks: []`. +- `params` : paramètres de flux par agent fusionnés sur l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez cela pour des remplacements spécifiques à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles. +- `skills` : liste d’autorisation de Skills facultative 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 de les 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é de reasoning par défaut facultative par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement de reasoning par message ou 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 session n’est défini. +- `embeddedHarness` : remplacement facultatif par agent de la politique de harness bas niveau. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent réservé à Codex tandis que les autres agents conservent le repli PI par défaut. +- `runtime` : descripteur d’exécution 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 harness ACP. +- `identity.avatar` : chemin relatif au workspace, URL `http(s)` ou URI `data:`. - `identity` dérive des valeurs par défaut : `ackReaction` depuis `emoji`, `mentionPatterns` depuis `name`/`emoji`. -- `subagents.allowAgents` : liste d’autorisation des ID d’agent pour `sessions_spawn` (`["*"]` = tous ; par défaut : même agent uniquement). -- Garde-fou d’héritage du sandbox : si la session requérante 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 explicite de profil ; par défaut : false). +- `subagents.allowAgents` : liste d’autorisation des ID d’agents pour `sessions_spawn` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement). +- Garde d’héritage du sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient hors sandbox. +- `subagents.requireAgentId` : lorsqu’il vaut true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite de profil ; par défaut : false). --- ## Routage multi-agent -Exécutez plusieurs agents isolés dans une seule Gateway. Voir [Multi-Agent](/fr/concepts/multi-agent). +Exécute plusieurs agents isolés dans un seul Gateway. Voir [Multi-Agent](/fr/concepts/multi-agent). ```json5 { @@ -1829,9 +1829,9 @@ Exécutez plusieurs agents isolés dans une seule Gateway. Voir [Multi-Agent](/f } ``` -### Champs de correspondance des liaisons +### Champs `match` des liaisons -- `type` (facultatif) : `route` pour le routage normal (type manquant = route par défaut), `acp` pour les liaisons persistantes de conversation ACP. +- `type` (facultatif) : `route` pour le routage normal (type manquant = route par défaut), `acp` pour les liaisons ACP persistantes de conversation. - `match.channel` (obligatoire) - `match.accountId` (facultatif ; `*` = n’importe quel compte ; omis = compte par défaut) - `match.peer` (facultatif ; `{ kind: direct|group|channel, id }`) @@ -1843,13 +1843,13 @@ Exécutez plusieurs agents isolés dans une seule Gateway. Voir [Multi-Agent](/f 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exact, sans pair/serveur/équipe) +4. `match.accountId` (exact, sans pair/guilde/équipe) 5. `match.accountId: "*"` (à l’échelle du canal) 6. Agent par défaut -À l’intérieur de chaque niveau, la première entrée correspondante de `bindings` l’emporte. +À l’intérieur de chaque niveau, la première entrée `bindings` correspondante l’emporte. -Pour les entrées `type: "acp"`, OpenClaw résout selon l’identité exacte de la conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre de niveaux de liaison de routage 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 par niveaux des liaisons de routage ci-dessus. ### Profils d’accès par agent @@ -1871,7 +1871,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout selon l’identité exacte de - + ```json5 { @@ -1946,7 +1946,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout selon l’identité exacte de -Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour le détail des priorités. +Voir [Sandbox & outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour les détails de priorité. --- @@ -2001,33 +2001,33 @@ Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour l - **`scope`** : stratégie de base de regroupement des sessions pour les contextes de discussion de groupe. - `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 intentionnel). -- **`dmScope`** : manière dont les MP sont regroupés. - - `main` : tous les MP partagent la session principale. + - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsqu’un contexte partagé est voulu). +- **`dmScope`** : façon dont les DM sont regroupés. + - `main` : tous les DM partagent la session principale. - `per-peer` : isole par ID d’expéditeur entre 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 des ID canoniques vers des pairs préfixés par fournisseur pour le partage de session inter-canal. -- **`reset`** : politique principale de réinitialisation. `daily` réinitialise à `atHour` selon l’heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte. +- **`identityLinks`** : mappe les ID canoniques vers des pairs préfixés par fournisseur pour le partage de session inter-canaux. +- **`reset`** : politique de réinitialisation principale. `daily` réinitialise à `atHour` selon l’heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, la première échéance l’emporte. - **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien `dm` est accepté comme alias de `direct`. -- **`parentForkMaxTokens`** : valeur maximale de `totalTokens` de la session parente autorisée lors de la création d’une session de fil bifurquée (par défaut `100000`). - - Si le `totalTokens` parent est au-dessus de 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 bifurcation depuis le parent. -- **`mainKey`** : champ hérité. Le runtime utilise toujours `"main"` pour le compartiment principal de discussion directe. -- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse entre agents pendant les é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. +- **`parentForkMaxTokens`** : `totalTokens` maximal autorisé pour la session parente lors de la création d’une session de fil dérivée (par défaut `100000`). + - Si `totalTokens` de la parente dépasse cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription de la parente. + - Définissez `0` pour désactiver cette protection et toujours autoriser la dérivation depuis la parente. +- **`mainKey`** : champ hérité. L’exécution utilise toujours `"main"` pour le compartiment principal des discussions directes. +- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse aller-retour entre agents pendant les é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’alias hérité `dm`), `keyPrefix` ou `rawKeyPrefix`. Le premier refus l’emporte. +- **`maintenance`** : contrôles de nettoyage + rétention du stockage de session. - `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` : effectue une rotation de `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`). - - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Par défaut, utilise `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 pivoter `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`). + - `resetArchiveRetention` : rétention pour les archives de transcription `*.reset.`. Par défaut, hérite de `pruneAfter` ; définissez `false` pour désactiver. + - `maxDiskBytes` : budget disque facultatif pour le répertoire des sessions. En mode `warn`, journalise des avertissements ; en mode `enforce`, 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 globales par défaut pour les fonctionnalités de session liées aux fils. - `enabled` : interrupteur maître par défaut (les fournisseurs peuvent le remplacer ; Discord utilise `channels.discord.threadBindings.enabled`) - - `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) + - `idleHours` : perte de focus automatique 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) @@ -2071,30 +2071,30 @@ Résolution (le plus spécifique l’emporte) : compte → canal → global. `" **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 actuel de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nom de l’identité de l’agent | (identique à `"auto"`) | +| `{provider}` | Nom du fournisseur | `anthropic` | +| `{thinkingLevel}` | Niveau de thinking actuel | `high`, `low`, `off` | +| `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) | Les variables sont insensibles à la casse. `{think}` est un alias de `{thinkingLevel}`. -### Réaction d’accusé de réception +### Réaction d’accusé - Par défaut, utilise `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 sur l’identité. +- Ordre de résolution : compte → canal → `messages.ackReaction` → repli d’identité. - Portée : `group-mentions` (par défaut), `group-all`, `direct`, `all`. -- `removeAckAfterReply` : supprime l’accusé de réception après la réponse sur Slack, Discord et Telegram. -- `messages.statusReactions.enabled` : active les réactions d’état de 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é de réception sont actives. - Sur Telegram, définissez-le explicitement à `true` pour activer les réactions d’état de cycle de vie. +- `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 actives lorsque les réactions d’accusé sont actives. + Sur Telegram, définissez-le explicitement sur `true` pour activer les réactions d’état du cycle de vie. -### Anti-rebond entrant +### Antirebond entrant -Regroupe les messages texte rapides provenant 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. +Regroupe les messages texte rapides d’un même expéditeur en un seul tour d’agent. Les médias/pièces jointes déclenchent un vidage immédiat. Les commandes de contrôle contournent l’antirebond. ### TTS (synthèse vocale) @@ -2137,18 +2137,18 @@ Regroupe les messages texte rapides provenant du même expéditeur en un seul to } ``` -- `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. +- `auto` contrôle le mode d’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 l’auto-résumé. - `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut par défaut `false` (activation explicite requise). - Les clés API reviennent à `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`. +- `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`. - 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. --- ## Talk -Valeurs par défaut pour le mode Talk (macOS/iOS/Android). +Valeurs par défaut du mode Talk (macOS/iOS/Android). ```json5 { @@ -2172,8 +2172,8 @@ Valeurs par défaut pour le 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 migrées automatiquement vers `talk.providers.`. +- `talk.provider` doit correspondre à une clé de `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 compatibles uniquement et sont migrées automatiquement vers `talk.providers.`. - Les ID de voix reviennent à `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. @@ -2188,7 +2188,7 @@ Valeurs par défaut pour le mode Talk (macOS/iOS/Android). `tools.profile` définit une liste d’autorisation de base avant `tools.allow`/`tools.deny` : -L’onboarding local 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). +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 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | @@ -2202,17 +2202,17 @@ L’onboarding local définit par défaut les nouvelles configurations locales s | Groupe | Outils | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` est accepté comme alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `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` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `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:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `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 fournisseurs) | ### `tools.allow` / `tools.deny` @@ -2226,7 +2226,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 du fournisseur → autorisation/refus. +Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. Ordre : profil de base → profil fournisseur → autorisation/refus. ```json5 { @@ -2242,7 +2242,7 @@ Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. O ### `tools.elevated` -Contrôle l’accès `exec` élevé en dehors du sandbox : +Contrôle l’accès `exec` élevé hors du sandbox : ```json5 { @@ -2260,7 +2260,7 @@ Contrôle l’accès `exec` élevé 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 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`). +- L’`exec` élevé contourne le sandboxing et utilise le chemin d’échappement configuré (`gateway` par défaut, ou `node` lorsque la cible d’exécution est `node`). ### `tools.exec` @@ -2306,13 +2306,13 @@ Les paramètres peuvent être définis globalement dans `tools.loopDetection` et } ``` -- `historySize` : historique maximal des appels d’outil conservé pour l’analyse de boucle. +- `historySize` : historique maximal des appels d’outils conservé pour l’analyse des boucles. - `warningThreshold` : seuil de motif 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 brutal 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 des outils de sondage connus (`process.poll`, `command_status`, etc.). -- `detectors.pingPong` : avertit/bloque sur des motifs alternés de paires sans progression. +- `globalCircuitBreakerThreshold` : seuil d’arrêt strict 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 pour les outils d’interrogation connus (`process.poll`, `command_status`, etc.). +- `detectors.pingPong` : avertit/bloque pour les motifs alternés de paires sans progression. - Si `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, la validation échoue. ### `tools.web` @@ -2379,32 +2379,32 @@ Configure la compréhension des médias entrants (image/audio/vidéo) : } ``` - + **Entrée fournisseur** (`type: "provider"` ou omis) : -- `provider` : ID du fournisseur API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model` : remplacement d’ID de modèle +- `provider` : ID du fournisseur d’API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) +- `model` : remplacement de l’ID du modèle - `profile` / `preferredProfile` : sélection de profil `auth-profiles.json` **Entrée CLI** (`type: "cli"`) : - `command` : exécutable à lancer -- `args` : arguments avec modèle (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) +- `args` : arguments avec 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 reviennent à l’entrée suivante. +- En cas d’échec, bascule vers l’entrée suivante. -L’authentification du fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`. +L’authentification fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`. -**Champs d’achèvement asynchrone :** +**Champs de fin asynchrone :** -- `asyncCompletion.directSend` : lorsque `true`, les tâches `music_generate` - et `video_generate` asynchrones terminées tentent d’abord une livraison directe au canal. Par défaut : `false` - (ancien chemin de réveil de session du demandeur/livraison par modèle). +- `asyncCompletion.directSend` : lorsqu’il vaut `true`, les tâches asynchrones terminées `music_generate` + et `video_generate` tentent d’abord une livraison directe au canal. Par défaut : `false` + (ancien chemin de réveil de session demandeuse/livraison par modèle). @@ -2442,13 +2442,13 @@ Remarques : - `self` : uniquement la clé de session actuelle. - `tree` : session actuelle + sessions engendré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-agent nécessite toujours `tools.agentToAgent`. -- Limitation du 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"`. +- `agent` : toute session appartenant à l’ID d’agent actuel (peut inclure d’autres utilisateurs si vous utilisez des sessions par expéditeur sous le même ID d’agent). +- `all` : toute session. Le ciblage inter-agents exige toujours `tools.agentToAgent`. +- Restriction 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 en ligne pour `sessions_spawn`. +Contrôle la prise en charge des pièces jointes intégrées pour `sessions_spawn`. ```json5 { @@ -2469,15 +2469,15 @@ Contrôle la prise en charge des pièces jointes en ligne pour `sessions_spawn`. Remarques : - Les pièces jointes ne sont prises en charge que pour `runtime: "subagent"`. Le runtime ACP les rejette. -- Les fichiers sont matérialisés dans l’espace de travail enfant à `.openclaw/attachments//` avec un `.manifest.json`. -- Le contenu des pièces jointes est automatiquement expurgé de 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. +- Les fichiers sont matérialisés dans le workspace enfant sous `.openclaw/attachments//` avec un `.manifest.json`. +- Le contenu des pièces jointes est automatiquement caviardé dans la persistance de 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 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` -Indicateurs expérimentaux pour les outils intégrés. Désactivés par défaut sauf si une règle d’auto-activation stricte agentique GPT-5 s’applique. +Indicateurs expérimentaux d’outils intégrés. Désactivés par défaut sauf lorsqu’une règle d’activation automatique stricte-agentique GPT-5 s’applique. ```json5 { @@ -2491,9 +2491,9 @@ Indicateurs expérimentaux pour les outils intégrés. Désactivés par défaut Remarques : -- `planTool` : active l’outil structuré `update_plan` pour le suivi des travaux non triviaux en plusieurs étapes. -- Par défaut : `false` sauf si `agents.defaults.embeddedPi.executionContract` (ou un remplacement par agent) est défini sur `"strict-agentic"` pour une exécution OpenAI ou OpenAI Codex de la famille GPT-5. Définissez `true` pour forcer l’activation de l’outil en dehors de ce cadre, ou `false` pour le garder désactivé même pour les exécutions GPT-5 strict-agentiques. -- Lorsqu’il est activé, l’invite système ajoute aussi des consignes d’utilisation 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é expérimental `update_plan` pour le suivi de travaux non triviaux à plusieurs étapes. +- Par défaut : `false` sauf si `agents.defaults.embeddedPi.executionContract` (ou un remplacement par agent) est défini sur `"strict-agentic"` pour une exécution OpenAI ou OpenAI Codex de la famille GPT-5. Définissez `true` pour forcer l’activation hors de ce cadre, ou `false` pour le laisser désactivé même pour les exécutions GPT-5 strict-agentiques. +- Lorsqu’il est activé, le prompt système ajoute également des consignes d’utilisation afin que le modèle ne l’utilise que pour un travail substantiel et conserve au plus une étape `in_progress`. ### `agents.defaults.subagents` @@ -2514,15 +2514,15 @@ Remarques : ``` - `model` : modèle par défaut pour les sous-agents engendrés. S’il est omis, les sous-agents héritent du modèle de l’appelant. -- `allowAgents` : liste d’autorisation 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 maximal par défaut (secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai maximal. +- `allowAgents` : liste d’autorisation par défaut des ID d’agents 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 (en 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 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 intégré de modèles. Ajoutez des fournisseurs personnalisés via `models.providers` dans la configuration ou `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2551,48 +2551,48 @@ 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 de l’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, alias hérité de variable d’environnement). +- Utilisez `authHeader: true` + `headers` pour des besoins d’authentification personnalisés. +- Remplacez la racine de configuration agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, alias hérité de variable d’environnement). - Priorité de fusion pour les ID de fournisseur correspondants : - - Les valeurs non vides de `baseUrl` dans `models.json` de l’agent l’emportent. - - Les valeurs non vides de `apiKey` de l’agent ne l’emportent 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 actualisées depuis les marqueurs source (`ENV_VAR_NAME` pour les références d’environnement, `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 actualisées depuis les marqueurs source (`secretref-env:ENV_VAR_NAME` pour les références d’environnement, `secretref-managed` pour les références fichier/exec). - - Les valeurs `apiKey`/`baseUrl` d’agent vides ou absentes reviennent à `models.providers` dans la configuration. - - Les valeurs `contextWindow`/`maxTokens` du modèle correspondant utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue. - - Les valeurs `contextTokens` du modèle correspondant conservent une limite explicite du runtime lorsqu’elle est présente ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle. + - Les valeurs `baseUrl` d’agent `models.json` non vides l’emportent. + - Les valeurs `apiKey` d’agent non vides l’emportent uniquement 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 depuis les marqueurs de source (`ENV_VAR_NAME` pour les références d’environnement, `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 depuis les marqueurs de source (`secretref-env:ENV_VAR_NAME` pour les références d’environnement, `secretref-managed` pour les références fichier/exec). + - Les `apiKey`/`baseUrl` d’agent vides ou absents reviennent à `models.providers` dans la configuration. + - Les `contextWindow`/`maxTokens` des modèles correspondants utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue. + - Les `contextTokens` des modèles correspondants conservent un plafond d’exécution explicite lorsqu’il est présent ; utilisez-le 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 pilotée par la source : les marqueurs sont écrits à partir de l’instantané actif de configuration source (pré-résolution), et non à partir des valeurs secrètes résolues à l’exécution. + - La persistance des marqueurs est pilotée par la source : les marqueurs sont écrits à partir de l’instantané actif de la configuration source (avant résolution), et non à partir des valeurs secrètes d’exécution résolues. -### Détails des champs du fournisseur +### Détails des champs fournisseur - `models.mode` : comportement du catalogue de fournisseurs (`merge` ou `replace`). -- `models.providers` : map des fournisseurs personnalisés, indexée par ID de fournisseur. +- `models.providers` : map de fournisseurs personnalisés indexée par ID de fournisseur. - `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/la substitution par variable d’environnement). +- `models.providers.*.apiKey` : identifiant de fournisseur (préférez SecretRef / la substitution d’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 des identifiants dans l’en-tête `Authorization` lorsque nécessaire. +- `models.providers.*.authHeader` : force le transport de l’identifiant dans l’en-tête `Authorization` lorsque requis. - `models.providers.*.baseUrl` : URL de base de l’API en amont. - `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 fournisseur de modèles. +- `models.providers.*.request` : remplacements de transport pour les requêtes HTTP du fournisseur de modèle. - `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. - - `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (tous acceptent SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork` : lorsque `true`, autorise HTTPS vers `baseUrl` lorsque le DNS se résout vers des plages privées, CGNAT ou similaires, via la protection de récupération HTTP SSRF du fournisseur (activation explicite 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 côté récupération. Par défaut `false`. + - `request.auth` : remplacement de stratégie d’authentification. Modes : `"provider-default"` (utilise 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"` (utilise les variables d’environnement `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (avec `url`). Les deux modes acceptent un sous-objet `tls` facultatif. + - `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (acceptent tous SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork` : lorsqu’il vaut `true`, autorise HTTPS vers `baseUrl` lorsque DNS se résout vers des plages privées, CGNAT ou similaires, via la garde SSRF de récupération HTTP du fournisseur (activation explicite opérateur pour les points de terminaison OpenAI compatibles auto-hébergés de confiance). WebSocket utilise le même `request` pour les en-têtes/TLS, mais pas cette garde SSRF de récupération. Par défaut `false`. - `models.providers.*.models` : entrées explicites du catalogue de modèles du fournisseur. - `models.providers.*.models.*.contextWindow` : métadonnées de fenêtre de contexte native du modèle. -- `models.providers.*.models.*.contextTokens` : plafond facultatif de contexte à l’exécution. Utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle. -- `models.providers.*.models.*.compat.supportsDeveloperRole` : indication facultative de compatibilité. Pour `api: "openai-completions"` avec un `baseUrl` non vide et 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` : indication facultative de compatibilité pour les points de terminaison de discussion compatibles OpenAI acceptant uniquement des chaînes. Lorsque `true`, OpenClaw aplatit les tableaux `messages[].content` purement textuels 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` : active/désactive 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’ID de fournisseur pour une découverte ciblée. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour le rafraîchissement 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 `contextWindow` natif du modèle. +- `models.providers.*.models.*.compat.supportsDeveloperRole` : indice de compatibilité facultatif. Pour `api: "openai-completions"` avec un `baseUrl` non vide et non natif (hôte différent de `api.openai.com`), OpenClaw le force à `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 OpenAI compatibles qui n’acceptent que des chaînes. Lorsqu’il vaut `true`, OpenClaw aplatie les tableaux `messages[].content` purement textuels 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 fournisseur pour une détection ciblée. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour le rafraîchissement 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 @@ -2630,7 +2630,7 @@ OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs pe } ``` -Utilisez `cerebras/zai-glm-4.7` pour Cerebras ; `zai/glm-4.7` pour Z.AI direct. +Utilisez `cerebras/zai-glm-4.7` pour Cerebras ; `zai/glm-4.7` pour Z.AI en direct. @@ -2647,7 +2647,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`. @@ -2664,11 +2664,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 code (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. +- Pour le point de terminaison général, définissez un fournisseur personnalisé avec le remplacement de l’URL de base. @@ -2709,9 +2709,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’utilisation du streaming sur le transport partagé -`openai-completions`, et OpenClaw se base sur les capacités du point de terminaison -plutôt que sur le seul ID du fournisseur intégré. +Les points de terminaison Moonshot natifs annoncent la compatibilité d’usage du streaming sur le transport partagé +`openai-completions`, et OpenClaw s’appuie sur les capacités du point de terminaison +plutôt que sur le seul ID de fournisseur intégré. @@ -2812,8 +2812,8 @@ 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 utilise par défaut uniquement M2.7. -Sur le chemin de streaming compatible Anthropic, OpenClaw désactive par défaut le thinking de MiniMax -sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou +Sur le chemin de streaming compatible Anthropic, OpenClaw désactive thinking de MiniMax +par défaut sauf si vous définissez explicitement `thinking`. `/fast on` ou `params.fastMode: true` réécrit `MiniMax-M2.7` en `MiniMax-M2.7-highspeed`. @@ -2821,7 +2821,7 @@ sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou -Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand modèle local via l’API LM Studio Responses sur un matériel sérieux ; conservez les modèles hébergés fusionnés comme solution de repli. +Voir [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 sérieux ; conservez les modèles hébergés fusionnés pour le repli. @@ -2852,14 +2852,14 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand } ``` -- `allowBundled` : liste d’autorisation facultative pour les Skills groupés uniquement (les Skills gérés/de l’espace de travail ne sont pas affectés). -- `load.extraDirs` : racines partagées supplémentaires de Skills (priorité la plus faible). -- `install.preferBrew` : lorsque true, préfère les installateurs Homebrew lorsque `brew` est +- `allowBundled` : liste d’autorisation facultative pour les Skills groupés uniquement (les Skills gérés/workspace ne sont pas affectés). +- `load.extraDirs` : racines supplémentaires de Skills partagés (priorité la plus faible). +- `install.preferBrew` : lorsqu’il vaut true, préfère les installateurs Homebrew lorsque `brew` est disponible avant de revenir à d’autres types d’installateurs. -- `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` : raccourci pratique pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef). +- `entries..apiKey` : champ pratique pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef). --- @@ -2887,39 +2887,39 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand } ``` -- 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 Gateway.** -- `allow` : liste d’autorisation facultative (seuls les plugins listés se chargent). `deny` l’emporte. -- `plugins.entries..apiKey` : champ pratique de clé API au niveau du plugin (lorsque pris en charge par le plugin). -- `plugins.entries..env` : map de variables d’environnement à portée du plugin. -- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le noyau bloque `before_prompt_build` et ignore les champs de mutation d’invite issus de l’ancien `before_agent_start`, tout en conservant 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 en arrière-plan de sous-agent. -- `plugins.entries..subagent.allowedModels` : liste d’autorisation facultative des cibles canoniques `provider/model` pour les remplacements de sous-agent de confiance. Utilisez `"*"` uniquement lorsque vous souhaitez intentionnellement autoriser n’importe quel modèle. -- `plugins.entries..config` : objet de configuration défini par le plugin (validé par le schéma de plugin OpenClaw natif lorsqu’il est disponible). +- Chargé depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, ainsi que `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 avec disposition par défaut. +- **Les modifications de configuration exigent un redémarrage du Gateway.** +- `allow` : liste d’autorisation facultative (seuls les plugins listés sont chargés). `deny` l’emporte. +- `plugins.entries..apiKey` : champ pratique de clé API au niveau du plugin (lorsqu’il est pris en charge par le plugin). +- `plugins.entries..env` : map de variables d’environnement circonscrite au plugin. +- `plugins.entries..hooks.allowPromptInjection` : lorsqu’il vaut `false`, le cœur bloque `before_prompt_build` et ignore les champs de mutation du prompt provenant de l’ancien `before_agent_start`, tout en conservant 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-agent en arrière-plan. +- `plugins.entries..subagent.allowedModels` : liste d’autorisation facultative des cibles canoniques `provider/model` pour les remplacements de sous-agent de confiance. 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). Revient à `plugins.entries.firecrawl.config.webSearch.apiKey`, à l’ancien `tools.web.fetch.firecrawl.apiKey`, ou à la variable d’environnement `FIRECRAWL_API_KEY`. + - `apiKey` : clé API Firecrawl (accepte SecretRef). Revient à `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` : 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 la requête d’exploration en secondes (par défaut : `60`). -- `plugins.entries.xai.config.xSearch` : paramètres de xAI X Search (recherche web Grok). + - `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 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 de memory. Voir [Dreaming](/fr/concepts/dreaming) pour les phases et seuils. +- `plugins.entries.memory-core.config.dreaming` : paramètres de Dreaming de la mémoire. Voir [Dreaming](/fr/concepts/dreaming) pour les phases et les seuils. - `enabled` : interrupteur maître de Dreaming (par défaut `false`). - - `frequency` : cadence Cron pour chaque cycle complet de dreaming (`"0 3 * * *"` par défaut). + - `frequency` : cadence Cron pour chaque balayage complet de Dreaming (`"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 à l’utilisateur). -- La configuration complète de memory 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 par défaut intégrées pour Pi depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, et non comme correctifs bruts de configuration OpenClaw. -- `plugins.slots.memory` : choisit l’ID du plugin memory actif, ou `"none"` pour désactiver les plugins memory. -- `plugins.slots.contextEngine` : choisit l’ID du plugin de 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`. +- Les plugins de bundle Claude activés peuvent également contribuer des valeurs par défaut Pi embarquées depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent nettoyés, pas comme correctifs bruts de configuration OpenClaw. +- `plugins.slots.memory` : choisit l’ID du plugin mémoire actif, ou `"none"` pour désactiver les plugins mémoire. +- `plugins.slots.contextEngine` : choisit l’ID du plugin moteur de contexte actif ; 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`. - Traitez `plugins.installs.*` comme un état géré ; préférez les commandes CLI aux modifications manuelles. @@ -2964,28 +2964,28 @@ Voir [Plugins](/fr/tools/plugin). ``` - `evaluateEnabled: false` désactive `act:evaluate` et `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini, de sorte que la navigation du navigateur reste stricte par défaut. -- Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` uniquement lorsque vous faites intentionnellement confiance à la navigation du navigateur sur réseau privé. -- En mode strict, les points de terminaison de profils CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage des réseaux privés lors des vérifications d’accessibilité/découverte. -- `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme ancien alias. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini, donc la navigation du navigateur reste stricte par défaut. +- Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` uniquement lorsque vous faites délibérément confiance à la navigation du navigateur vers un réseau privé. +- En mode strict, les points de terminaison des profils CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage des réseaux privés lors des vérifications d’accessibilité/découverte. +- `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias hérité. - En mode strict, utilisez `ssrfPolicy.hostnameAllowlist` et `ssrfPolicy.allowedHostnames` pour des exceptions explicites. -- Les profils distants sont en mode attachement seul (démarrage/arrêt/réinitialisation désactivés). +- Les profils distants sont en attachement seul (démarrage/arrêt/réinitialisation désactivés). - `profiles.*.cdpUrl` accepte `http://`, `https://`, `ws://` et `wss://`. Utilisez HTTP(S) lorsque vous voulez qu’OpenClaw découvre `/json/version` ; utilisez WS(S) lorsque votre fournisseur vous donne une URL WebSocket DevTools directe. -- Les profils `existing-session` sont limités à 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 tel que Brave ou Edge. -- Les profils `existing-session` conservent les limites actuelles de route Chrome MCP : - actions pilotées par instantané/référence au lieu d’un ciblage par sélecteur CSS, hooks de téléversement - à fichier unique, aucun remplacement de délai maximal de boîte de dialogue, aucun `wait --load networkidle`, - et pas de `responsebody`, d’export PDF, d’interception de téléchargement, ni d’actions par lots. -- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; définissez - `cdpUrl` explicitement uniquement pour un CDP distant. +- Les profils `existing-session` sont réservés à l’hôte et utilisent Chrome MCP au lieu de CDP. +- Les profils `existing-session` peuvent définir `userDataDir` pour cibler un profil spécifique + d’un navigateur basé sur Chromium comme Brave ou Edge. +- Les profils `existing-session` conservent les limites actuelles de la route Chrome MCP : + actions pilotées par instantané/référence au lieu d’un ciblage par sélecteur CSS, hooks d’envoi + d’un seul fichier, pas de remplacement du délai d’expiration des boîtes de dialogue, pas de `wait --load networkidle`, et pas de + `responsebody`, export PDF, interception de téléchargement ou actions par lots. +- Les profils locaux gérés `openclaw` assignent 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). +- `extraArgs` ajoute des indicateurs de lancement supplémentaires au démarrage local de Chromium (par exemple + `--disable-gpu`, dimensionnement de fenêtre ou indicateurs de débogage). --- @@ -3003,8 +3003,8 @@ Voir [Plugins](/fr/tools/plugin). } ``` -- `seamColor` : couleur d’accentuation de l’interface native de l’application (teinte de la bulle du mode Talk, etc.). -- `assistant` : remplacement d’identité de l’interface de contrôle. Revient à l’identité de l’agent actif. +- `seamColor` : couleur d’accent pour l’habillage de l’interface native de l’application (teinte de bulle du mode Talk, etc.). +- `assistant` : remplacement d’identité pour l’interface utilisateur Control. Revient à l’identité de l’agent actif. --- @@ -3071,53 +3071,53 @@ Voir [Plugins](/fr/tools/plugin). } ``` - + -- `mode` : `local` (exécuter la Gateway) ou `remote` (se connecter à une Gateway distante). La Gateway refuse de démarrer sauf en mode `local`. +- `mode` : `local` (exécuter le Gateway) ou `remote` (se connecter à un Gateway distant). Le Gateway refuse de démarrer sauf en mode `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`), et non les alias d’hôte (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Remarque Docker** : le bind `loopback` par défaut écoute sur `127.0.0.1` à l’intérieur du conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc la Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. -- **Auth** : requise par défaut. Les binds non-loopback nécessitent l’authentification de Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse conscient de l’identité avec `gateway.auth.mode: "trusted-proxy"`. L’assistant d’onboarding génère un jeton par défaut. -- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés (y compris via 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 locales de confiance ; cette option n’est volontairement pas proposée par les invites d’onboarding. -- `gateway.auth.mode: "trusted-proxy"` : délègue l’authentification à un proxy inverse conscient de l’identité et fait confiance aux en-têtes d’identité issus de `gateway.trustedProxies` (voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend une source 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 l’interface de contrôle/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison d’API HTTP **n’utilisent pas** cette authentification d’en-tête Tailscale ; ils suivent à la place le mode d’authentification HTTP normal de la Gateway. Ce flux sans jeton suppose que l’hôte de la Gateway 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 cliente 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 de l’interface de contrôle Tailscale Serve, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives incorrectes concurrentes provenant du même client peuvent donc déclencher le limiteur à la deuxième requête au lieu de laisser les deux passer comme de simples non-correspondances. - - `gateway.auth.rateLimit.exemptLoopback` vaut par défaut `true` ; définissez `false` lorsque vous souhaitez intentionnellement que le trafic localhost soit également limité (pour les configurations de test ou les 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 la force brute localhost depuis le navigateur). -- En loopback, ces verrouillages d’origine navigateur sont isolés par valeur `Origin` - normalisée, de sorte que des échecs répétés depuis une origine localhost ne - verrouillent pas automatiquement une autre origine. -- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite une authentification). -- `controlUi.allowedOrigins` : liste d’autorisation 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 basé sur l’en-tête Host pour les déploiements qui s’appuient intentionnellement sur la politique d’origine basée sur Host. +- **Alias `bind` hérités** : utilisez les valeurs de mode bind dans `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), pas les alias d’hôte (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Remarque Docker** : la liaison `loopback` par défaut écoute sur `127.0.0.1` à l’intérieur du conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc le Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. +- **Auth** : requise par défaut. Les liaisons non loopback exigent l’authentification Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse à gestion d’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`. Le démarrage et les flux 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 locales de confiance ; ce mode n’est volontairement pas proposé dans les invites d’intégration. +- `gateway.auth.mode: "trusted-proxy"` : délègue l’authentification à un proxy inverse à gestion d’identité et fait confiance aux en-têtes d’identité provenant de `gateway.trustedProxies` (voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend une source de proxy **non loopback** ; les proxys inverses loopback sur la même machine ne satisfont pas l’authentification trusted-proxy. +- `gateway.auth.allowTailscale` : lorsqu’il vaut `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’authentification de l’interface utilisateur Control/WebSocket (vérifiés 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 du Gateway. Ce flux sans jeton suppose que l’hôte Gateway est de confiance. Par défaut `true` lorsque `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit` : limiteur facultatif des échecs d’authentification. S’applique par IP cliente et par portée d’authentification (secret partagé et jeton d’appareil sont suivis séparément). Les tentatives bloquées renvoient `429` + `Retry-After`. + - Sur le chemin asynchrone Tailscale Serve de l’interface utilisateur Control, les tentatives échouées pour un même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives mauvaises concurrentes du même client peuvent donc déclencher le limiteur à la deuxième requête au lieu de laisser passer les deux comme de simples non-correspondances. + - `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 de 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 la force brute localhost depuis le navigateur). +- En loopback, ces verrouillages provenant d’origines navigateur sont isolés par valeur `Origin` + normalisée, de sorte que des échecs répétés depuis une origine localhost n’entraînent pas automatiquement + le verrouillage d’une autre origine. +- `tailscale.mode` : `serve` (tailnet uniquement, liaison loopback) ou `funnel` (public, nécessite une authentification). +- `controlUi.allowedOrigins` : liste d’autorisation explicite des origines navigateur pour les connexions WebSocket au Gateway. Requise lorsque des clients navigateur sont attendus depuis des origines non loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le repli d’origine basé sur l’en-tête Host pour les déploiements qui reposent volontairement sur une politique d’origine fondée sur Host. - `remote.transport` : `ssh` (par défaut) ou `direct` (ws/wss). Pour `direct`, `remote.url` doit être `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : 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 client distant. Ils ne configurent pas à eux seuls l’authentification de Gateway. -- `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 appuyés sur un relais vers la Gateway. Cette URL doit correspondre à l’URL de relais compilée dans le build iOS. -- `gateway.push.apns.relay.timeoutMs` : délai maximal d’envoi Gateway-vers-relais en millisecondes. Par défaut : `10000`. -- Les enregistrements adossés au relais sont délégués à une identité Gateway spécifique. L’application iOS associée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais et transmet à la Gateway une autorisation d’envoi à portée d’enregistrement. Une autre Gateway ne peut pas réutiliser cet enregistrement stocké. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements temporaires par variable d’environnement pour la configuration de relais ci-dessus. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` : échappatoire de développement uniquement 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 conservant le moniteur global activé. -- `channels..accounts..healthMonitor.enabled` : remplacement par compte pour les canaux multi-comptes. Lorsqu’il est défini, il prend priorité sur le remplacement au niveau du canal. -- Les chemins d’appel de Gateway locale peuvent utiliser `gateway.remote.*` comme repli uniquement lorsque `gateway.auth.*` n’est pas défini. -- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en mode fermé (aucun repli distant masquant). -- `trustedProxies` : IP des proxies inverses qui terminent TLS ou injectent des en-têtes client transférés. Ne listez que 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 éligibles à `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback` : lorsque `true`, la Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement en échec sécurisé. -- `gateway.tools.deny` : noms d’outils supplémentaires bloqués pour HTTP `POST /tools/invoke` (étend la liste de refus par défaut). -- `gateway.tools.allow` : retire des noms d’outils de la liste de refus HTTP par défaut. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : remplacement client « break-glass » qui autorise `ws://` en clair vers des IP 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 du Gateway. +- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après qu’ils ont publié des enregistrements adossés au relais vers le Gateway. Cette URL doit correspondre à l’URL du relais compilée dans le build iOS. +- `gateway.push.apns.relay.timeoutMs` : délai d’envoi Gateway-vers-relais en millisecondes. Par défaut `10000`. +- Les enregistrements adossés au relais sont délégués à une identité spécifique du Gateway. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais et transmet au Gateway une autorisation d’envoi circonscrite à l’enregistrement. Un autre Gateway ne peut pas réutiliser cet enregistrement stocké. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements d’environnement temporaires pour la configuration de 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 d’état des canaux en minutes. Définissez `0` pour désactiver globalement les redémarrages du moniteur d’état. Par défaut : `5`. +- `gateway.channelStaleEventThresholdMinutes` : seuil de socket obsolète en minutes. Conservez une valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`. +- `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages du moniteur d’état par canal/compte sur une heure glissante. Par défaut : `10`. +- `channels..healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur d’état tout en conservant 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 du Gateway local peuvent utiliser `gateway.remote.*` comme repli uniquement lorsque `gateway.auth.*` n’est pas défini. +- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en mode fermé (aucun repli distant ne masque cela). +- `trustedProxies` : IP de proxy inverse qui terminent TLS ou injectent des en-têtes client transférés. Listez uniquement les proxys que vous contrôlez. Les entrées loopback restent valides pour les configurations de proxy sur le même hôte / détection locale (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` : lorsqu’il vaut `true`, le Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement en mode fermé. +- `gateway.tools.deny` : noms d’outils supplémentaires bloqués pour `POST /tools/invoke` HTTP (étend la liste de refus par défaut). +- `gateway.tools.allow` : supprime des noms d’outils de la liste de refus HTTP par défaut. ### Points de terminaison compatibles OpenAI -- Chat Completions : désactivé par défaut. Activez-le avec `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions : désactivé par défaut. Activez avec `gateway.http.endpoints.chatCompletions.enabled: true`. - API Responses : `gateway.http.endpoints.responses.enabled`. - Renforcement des entrées URL de Responses : - `gateway.http.endpoints.responses.maxUrlParts` @@ -3125,12 +3125,12 @@ Voir [Plugins](/fr/tools/plugin). - `gateway.http.endpoints.responses.images.urlAllowlist` Les listes d’autorisation vides sont traitées comme non définies ; utilisez `gateway.http.endpoints.responses.files.allowUrl=false` et/ou `gateway.http.endpoints.responses.images.allowUrl=false` pour désactiver la récupération d’URL. -- En-tête facultatif de renforcement des réponses : - - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour les origines HTTPS que vous contrôlez ; voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) +- En-tête facultatif de durcissement des réponses : + - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour des origines HTTPS que vous contrôlez ; voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolation multi-instance -Exécutez plusieurs Gateways sur un même hôte avec des ports et des répertoires d’état uniques : +Exécutez plusieurs Gateway sur un même hôte avec des ports et répertoires d’état uniques : ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3138,9 +3138,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Drapeaux pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). +Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). -Voir [Gateways multiples](/fr/gateway/multiple-gateways). +Voir [Plusieurs Gateway](/fr/gateway/multiple-gateways). ### `gateway.tls` @@ -3159,10 +3159,10 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). ``` - `enabled` : active la terminaison TLS au niveau de l’écouteur Gateway (HTTPS/WSS) (par défaut : `false`). -- `autoGenerate` : génère automatiquement une paire locale certifié/clé auto-signée lorsque des fichiers explicites ne sont pas configurés ; pour un usage local/dev uniquement. +- `autoGenerate` : génère automatiquement une paire locale cert/key autosignée lorsqu’aucun fichier explicite n’est configuré ; pour usage local/dev uniquement. - `certPath` : chemin du système de fichiers vers le fichier de certificat TLS. -- `keyPath` : chemin du système de fichiers vers le fichier de clé privée TLS ; conservez des permissions restreintes. -- `caPath` : chemin facultatif du bundle CA pour la vérification client ou des chaînes de confiance personnalisées. +- `keyPath` : chemin du système de fichiers vers la clé privée TLS ; gardez des permissions restrictives. +- `caPath` : chemin facultatif vers un bundle CA pour la vérification client ou des chaînes de confiance personnalisées. ### `gateway.reload` @@ -3182,8 +3182,8 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). - `"off"` : ignore les modifications en direct ; les changements nécessitent un redémarrage explicite. - `"restart"` : redémarre toujours le processus Gateway lors d’un changement de configuration. - `"hot"` : applique les changements dans le processus sans redémarrage. - - `"hybrid"` (par défaut) : tente d’abord le rechargement à chaud ; revient au redémarrage si nécessaire. -- `debounceMs` : fenêtre d’anti-rebond en ms avant l’application des changements de configuration (entier non négatif). + - `"hybrid"` (par défaut) : tente d’abord un rechargement à chaud ; revient à un redémarrage si nécessaire. +- `debounceMs` : fenêtre d’antirebond en ms avant l’application des changements de configuration (entier non négatif). - `deferralTimeoutMs` : durée maximale en ms d’attente des opérations en cours avant de forcer un redémarrage (par défaut : `300000` = 5 minutes). --- @@ -3222,35 +3222,35 @@ Voir [Gateways multiples](/fr/gateway/multiple-gateways). ``` Auth : `Authorization: Bearer ` ou `x-openclaw-token: `. -Les jetons de hook dans la chaîne de requête sont refusés. +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` ; la réutilisation du jeton Gateway est refusée. -- `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié tel que `/hooks`. -- Si `hooks.allowRequestSessionKey=true`, limitez `hooks.allowedSessionKeyPrefixes` (par exemple `["hook:"]`). +- `hooks.enabled=true` exige 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é comme `/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` issu de la charge utile de la requête n’est accepté que lorsque `hooks.allowRequestSessionKey=true` (par défaut : `false`). + - `sessionKey` provenant de la charge utile de 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 refusés). -- `agentId` route vers un agent spécifique ; les ID inconnus reviennent à l’agent par défaut. + - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et la traversée sont rejetés). +- `agentId` achemine vers un agent spécifique ; les ID inconnus reviennent à 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 de hook sans `sessionKey` explicite. -- `allowRequestSessionKey` : permet aux appelants de `/hooks/agent` de définir `sessionKey` (par défaut : `false`). -- `allowedSessionKeyPrefixes` : liste d’autorisation facultative des préfixes pour les valeurs `sessionKey` explicites (requête + mappage), par ex. `["hook:"]`. -- `deliver: true` envoie la réponse finale à un canal ; `channel` vaut par défaut `last`. +- `defaultSessionKey` : clé de session fixe facultative pour les exécutions d’agent hook sans `sessionKey` explicite. +- `allowRequestSessionKey` : autorise les appelants de `/hooks/agent` à définir `sessionKey` (par défaut : `false`). +- `allowedSessionKeyPrefixes` : liste d’autorisation facultative de préfixes pour les valeurs explicites de `sessionKey` (requête + mapping), par ex. `["hook:"]`. +- `deliver: true` envoie la réponse finale vers un canal ; `channel` vaut `last` par défaut. - `model` remplace le LLM pour cette exécution de hook (doit être autorisé si le catalogue de modèles est défini). @@ -3278,8 +3278,8 @@ Remarques de validation et de sécurité : } ``` -- 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` distinct en parallèle de la Gateway. +- Le 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 du Gateway. --- @@ -3295,17 +3295,17 @@ Remarques de validation et de sécurité : } ``` -- Sert du HTML/CSS/JS modifiable par l’agent et A2UI sur HTTP sous le port Gateway : +- Sert du HTML/CSS/JS modifiable par l’agent et A2UI sur HTTP sous le port du Gateway : - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Local uniquement : conservez `gateway.bind: "loopback"` (par défaut). -- Binds non-loopback : les routes canvas nécessitent l’authentification Gateway (jeton/mot de passe/trusted-proxy), comme les autres surfaces HTTP Gateway. -- Les Node WebViews n’envoient généralement pas d’en-têtes d’authentification ; une fois qu’un node est appairé et connecté, la Gateway annonce des URL de capacité à portée de node pour l’accès à canvas/A2UI. -- Les URL de capacité sont liées à la session WS active du node et expirent rapidement. Aucun repli basé sur l’IP n’est utilisé. +- Liaisons non loopback : les routes canvas exigent l’authentification Gateway (token/password/trusted-proxy), comme les autres surfaces HTTP du Gateway. +- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; après appairage et connexion d’un Node, le Gateway annonce des URL de capacité circonscrites au Node pour l’accès à canvas/A2UI. +- Les URL de capacité sont liées à la session WS active du Node et expirent rapidement. Le repli basé sur l’IP n’est pas utilisé. - Injecte un client de rechargement en direct dans le HTML servi. -- Crée automatiquement un `index.html` de démarrage lorsque le répertoire est vide. +- Crée automatiquement un `index.html` de départ lorsqu’il est vide. - Sert aussi A2UI à `/__openclaw__/a2ui/`. -- Les changements nécessitent un redémarrage de la Gateway. +- Les changements exigent un redémarrage du Gateway. - Désactivez le rechargement en direct pour les grands répertoires ou en cas d’erreurs `EMFILE`. --- @@ -3338,15 +3338,15 @@ Remarques de validation et de sécurité : } ``` -Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour une découverte inter-réseaux, combinez-la avec un serveur DNS (CoreDNS recommandé) + DNS fractionné Tailscale. +Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour une découverte inter-réseaux, associez-la à un serveur DNS (CoreDNS recommandé) + DNS scindé Tailscale. -Installation : `openclaw dns setup --apply`. +Configuration : `openclaw dns setup --apply`. --- ## Environnement -### `env` (variables d’environnement en ligne) +### `env` (variables d’environnement intégrées) ```json5 { @@ -3363,8 +3363,8 @@ Installation : `openclaw dns setup --apply`. } ``` -- 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 de travail actuel + `~/.openclaw/.env` (aucun des deux ne remplace des variables existantes). +- Les variables d’environnement intégrées 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 votre profil de shell de connexion. - Voir [Environnement](/fr/help/environment) pour l’ordre de priorité complet. @@ -3389,7 +3389,7 @@ Référencez des variables d’environnement dans n’importe quelle chaîne de ## Secrets -Les références de secret sont additives : les valeurs en clair fonctionnent toujours. +Les références de secret sont additives : les valeurs en clair continuent de fonctionner. ### `SecretRef` @@ -3401,17 +3401,17 @@ Utilisez une seule forme d’objet : Validation : -- motif de `provider` : `^[a-z][a-z0-9_-]{0,63}$` -- motif de `id` pour `source: "env"` : `^[A-Z][A-Z0-9_]{0,127}$` -- `id` pour `source: "file"` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) -- motif de `id` pour `source: "exec"` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- les `id` avec `source: "exec"` ne doivent pas contenir de segments de chemin séparés par `/` égaux à `.` ou `..` (par exemple `a/../b` est refusé) +- motif `provider` : `^[a-z][a-z0-9_-]{0,63}$` +- motif `source: "env"` pour `id` : `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` pour `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` de `source: "exec"` ne doivent pas contenir de segments de chemin `/./` ou `/../` séparés par des slashs (par exemple `a/../b` est rejeté) ### Surface d’identifiants prise en charge -- Matrice canonique : [Surface des identifiants SecretRef](/fr/reference/secretref-credential-surface) +- 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. +- Les références de `auth-profiles.json` sont incluses dans la résolution à l’exécution et dans la couverture d’audit. ### Configuration des fournisseurs de secrets @@ -3444,12 +3444,12 @@ Validation : Remarques : - Le fournisseur `file` prend en charge `mode: "json"` et `mode: "singleValue"` (`id` doit être `"value"` en mode singleValue). -- Le fournisseur `exec` nécessite un chemin `command` absolu et utilise des charges utiles de protocole sur stdin/stdout. -- Par défaut, les chemins de commande symboliques sont refusés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symboliques tout en validant le chemin cible résolu. +- Le fournisseur `exec` exige un chemin `command` absolu et utilise des charges utiles de protocole sur stdin/stdout. +- Par défaut, les chemins de commande symboliques sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symboliques tout en validant le chemin cible résolu. - Si `trustedDirs` est configuré, la vérification des répertoires de confiance s’applique au chemin cible résolu. -- L’environnement enfant `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. +- L’environnement enfant de `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. - Les références de secret sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête ne lisent que 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. +- Le filtrage des surfaces actives 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 diagnostics. --- @@ -3472,12 +3472,12 @@ Remarques : ``` - Les profils par agent sont stockés dans `/auth-profiles.json`. -- `auth-profiles.json` prend en charge les références au niveau des valeurs (`keyRef` pour `api_key`, `tokenRef` pour `token`) pour les modes d’identifiants statiques. +- `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 adossés à SecretRef. -- Les identifiants statiques à l’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. +- Les identifiants statiques d’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. - Les anciennes importations OAuth proviennent de `~/.openclaw/credentials/oauth.json`. - Voir [OAuth](/fr/concepts/oauth). -- Comportement du runtime des secrets et outillage `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). +- Comportement d’exécution des secrets et outils `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). ### `auth.cooldowns` @@ -3499,21 +3499,21 @@ Remarques : } ``` -- `billingBackoffHours` : délai de repli de base en heures lorsqu’un profil échoue à cause de véritables - erreurs de facturation/crédit insuffisant (par défaut : `5`). Un texte explicite de facturation peut - toujours arriver ici même sur des réponses `401`/`403`, mais les - correspondances textuelles spécifiques au fournisseur restent limitées au fournisseur 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 d’organisation/espace de travail qui peuvent être réessayés restent dans le chemin `rate_limit` +- `billingBackoffHours` : repli de base en heures lorsqu’un profil échoue à cause de vraies + erreurs de facturation / crédit insuffisant (par défaut : `5`). Un texte de facturation explicite peut + toujours aboutir ici même sur des réponses `401`/`403`, mais les correspondances de texte + spécifiques au fournisseur restent circonscrites au fournisseur qui les possède (par exemple OpenRouter + `Key limit exceeded`). Les messages `402` de fenêtre d’usage + réessayables ou de limite de dépenses d’organisation/espace de travail restent dans le chemin `rate_limit` à la place. -- `billingBackoffHoursByProvider` : remplacements facultatifs par fournisseur pour le délai de repli de facturation en heures. -- `billingMaxHours` : plafond en heures pour la croissance exponentielle du délai de repli de facturation (par défaut : `24`). -- `authPermanentBackoffMinutes` : délai de repli de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`). -- `authPermanentMaxMinutes` : plafond en minutes pour la croissance du délai de repli `auth_permanent` (par défaut : `60`). -- `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de délai de repli (par défaut : `24`). -- `overloadedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas d’erreurs de surcharge avant de basculer vers le modèle de repli (par défaut : `1`). Les formes indiquant un fournisseur occupé comme `ModelNotReadyException` arrivent ici. -- `overloadedBackoffMs` : délai fixe avant nouvelle tentative d’une rotation de profil/fournisseur surchargé (par défaut : `0`). -- `rateLimitedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas d’erreurs de limite de débit avant de basculer vers le modèle de repli (par défaut : `1`). Cette catégorie de limite de débit inclut des textes typiques du fournisseur comme `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. +- `billingBackoffHoursByProvider` : remplacements facultatifs par fournisseur pour les heures de repli de facturation. +- `billingMaxHours` : plafond en heures pour la croissance exponentielle du repli de facturation (par défaut : `24`). +- `authPermanentBackoffMinutes` : repli de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`). +- `authPermanentMaxMinutes` : plafond en minutes pour la croissance du repli `auth_permanent` (par défaut : `60`). +- `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de repli (par défaut : `24`). +- `overloadedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas de surcharge avant de basculer vers le modèle de repli (par défaut : `1`). Les formes de fournisseur occupé comme `ModelNotReadyException` aboutissent ici. +- `overloadedBackoffMs` : délai fixe avant de réessayer une rotation de fournisseur/profil surchargé (par défaut : `0`). +- `rateLimitedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas de limitation de débit avant de basculer vers le modèle de repli (par défaut : `1`). Ce compartiment de limitation de débit inclut du texte typé fournisseur tel que `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. --- @@ -3535,7 +3535,7 @@ Remarques : - 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 que les écritures soient supprimées (entier positif ; par défaut : `524288000` = 500 MB). Utilisez une rotation externe des journaux pour les déploiements de production. +- `maxFileBytes` : taille maximale du fichier journal en octets avant suppression des écritures (entier positif ; par défaut : `524288000` = 500 MB). Utilisez une rotation de journaux externe pour les déploiements de production. --- @@ -3573,19 +3573,19 @@ Remarques : ``` - `enabled` : interrupteur maître de sortie d’instrumentation (par défaut : `true`). -- `flags` : tableau de chaînes de drapeaux activant une sortie 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. +- `flags` : tableau de chaînes d’indicateurs activant une sortie de journal ciblée (prend en charge les jokers comme `"telegram.*"` ou `"*"`). +- `stuckSessionWarnMs` : seuil d’ancienneté en ms pour émettre des avertissements de session bloquée pendant qu’une session reste en é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 de service pour les attributs de ressource. -- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export de traces, métriques ou journaux. +- `otel.serviceName` : nom du service pour les attributs de ressource. +- `otel.traces` / `otel.metrics` / `otel.logs` : activent l’export des traces, métriques ou 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 des instantanés de trace de cache pour les exécutions intégrées (par défaut : `false`). +- `cacheTrace.enabled` : journalise des instantanés de trace de cache pour les exécutions embarquées (par défaut : `false`). - `cacheTrace.filePath` : chemin de sortie pour le JSONL de trace de cache (par défaut : `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem` : contrôlent ce qui est inclus dans la sortie de trace de cache (tous à `true` par défaut). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem` : contrôlent ce qui est inclus dans la sortie de trace de cache (tous par défaut : `true`). --- @@ -3608,11 +3608,11 @@ Remarques : ``` - `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 Gateway (par défaut : `true`). -- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations par paquet (par défaut : `false`). +- `checkOnStart` : vérifie les mises à jour npm au démarrage du Gateway (par défaut : `true`). +- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de 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 de répartition du déploiement sur le 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`). +- `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 des vérifications du canal bêta en heures (par défaut : `1` ; max : `24`). --- @@ -3645,22 +3645,22 @@ Remarques : } ``` -- `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 conserver les commandes ACP disponibles tout en bloquant l’exécution. -- `backend` : ID du backend de runtime ACP par défaut (doit correspondre à un Plugin de runtime ACP enregistré). +- `enabled` : porte de fonctionnalité ACP globale (par défaut : `false`). +- `dispatch.enabled` : porte indépendante pour la répartition des tours de session ACP (par défaut : `true`). Définissez `false` pour conserver les commandes ACP disponibles tout en bloquant l’exécution. +- `backend` : ID par défaut du backend d’exécution ACP (doit correspondre à un Plugin d’exécution ACP enregistré). - `defaultAgent` : ID d’agent ACP cible de repli lorsque les créations ne spécifient pas de cible explicite. -- `allowedAgents` : liste d’autorisation des ID d’agent permis pour les sessions de runtime ACP ; vide signifie aucune restriction supplémentaire. +- `allowedAgents` : liste d’autorisation des ID d’agents 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 à l’inactivité en ms pour le texte diffusé en continu. -- `stream.maxChunkChars` : taille maximale de bloc avant découpage de la projection de bloc diffusé en continu. -- `stream.repeatSuppression` : supprime les lignes répétées de statut/outil par tour (par défaut : `true`). +- `stream.coalesceIdleMs` : fenêtre de vidage inactif en ms pour le texte diffusé. +- `stream.maxChunkChars` : taille maximale de bloc avant découpage de la projection par blocs diffusés. +- `stream.repeatSuppression` : supprime les lignes d’état/d’outil répétées 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 caché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 projetées de statut/mise à jour ACP. -- `stream.tagVisibility` : enregistrement des noms de balise vers des remplacements booléens de visibilité pour les événements diffusés. -- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant éligibilité au nettoyage. -- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement de runtime ACP. +- `stream.maxSessionUpdateChars` : nombre maximal de caractères pour les lignes projetées d’état/mise à jour ACP. +- `stream.tagVisibility` : enregistrement des noms de balises vers des remplacements booléens de visibilité pour les événements diffusés. +- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant nettoyage admissible. +- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement d’exécution ACP. --- @@ -3680,13 +3680,13 @@ Remarques : - `"random"` (par défaut) : slogans tournants humoristiques/de saison. - `"default"` : slogan neutre fixe (`All your chats, one OpenClaw.`). - `"off"` : aucun texte de slogan (le titre/version de la bannière reste affiché). -- Pour masquer toute la bannière (et pas seulement les slogans), définissez la variable d’environnement `OPENCLAW_HIDE_BANNER=1`. +- 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 d’installation guidée CLI (`onboard`, `configure`, `doctor`) : +Métadonnées écrites par les flux CLI de configuration guidée (`onboard`, `configure`, `doctor`) : ```json5 { @@ -3710,9 +3710,9 @@ Voir les champs d’identité de `agents.list` sous [Valeurs par défaut des age ## Bridge (hérité, supprimé) -Les versions actuelles n’incluent plus le bridge TCP. Les nodes 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). +Les builds actuels n’incluent plus le bridge TCP. Les Node 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 { @@ -3750,11 +3750,11 @@ Les versions actuelles n’incluent plus le bridge TCP. Les nodes se connectent } ``` -- `sessionRetention` : durée de conservation des sessions isolées terminées d’exécution Cron avant leur élagage de `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` : plus récentes lignes 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 de Cron (`delivery.mode = "webhook"`) ; s’il est omis, aucun en-tête d’authentification n’est envoyé. -- `webhook` : URL Webhook héritée de repli obsolète (http/https), utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. +- `sessionRetention` : durée de conservation des sessions d’exécution Cron isolées terminées avant émondage depuis `sessions.json`. Contrôle également le nettoyage des transcriptions Cron archivées supprimé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 émondage. Par défaut : `2_000_000` octets. +- `runLog.keepLines` : lignes les plus récentes conservées lorsque l’émondage 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 de repli héritée obsolète (http/https) utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. ### `cron.retry` @@ -3771,8 +3771,8 @@ Les versions actuelles n’incluent plus le bridge TCP. Les nodes se connectent ``` - `maxAttempts` : nombre maximal de nouvelles tentatives pour les tâches ponctuelles en cas d’erreurs transitoires (par défaut : `3` ; plage : `0`–`10`). -- `backoffMs` : tableau des délais de repli en ms pour chaque tentative de nouvelle exécution (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). -- `retryOn` : types d’erreur qui déclenchent des nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez pour réessayer tous les types transitoires. +- `backoffMs` : tableau des délais de repli en ms pour chaque tentative de nouvelle tentative (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). +- `retryOn` : types d’erreurs qui déclenchent de nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez pour réessayer tous les types transitoires. S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes utilisent une gestion distincte des échecs. @@ -3793,10 +3793,10 @@ S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes u ``` - `enabled` : active les alertes d’échec pour les tâches Cron (par défaut : `false`). -- `after` : nombre d’échecs consécutifs avant déclenchement d’une alerte (entier positif, min : `1`). -- `cooldownMs` : nombre minimal de millisecondes entre des alertes répétées pour la même tâche (entier non négatif). -- `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 portée de la livraison de l’alerte. +- `after` : nombre d’échecs consécutifs avant le déclenchement d’une alerte (entier positif, min : `1`). +- `cooldownMs` : nombre minimal de millisecondes entre des alertes répétées pour une même tâche (entier non négatif). +- `mode` : mode de livraison — `"announce"` envoie via un message de canal ; `"webhook"` publie sur le Webhook configuré. +- `accountId` : ID facultatif de compte ou de canal pour circonscrire la livraison de l’alerte. ### `cron.failureDestination` @@ -3814,15 +3814,15 @@ S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes u ``` - Destination par défaut pour les notifications d’échec Cron sur l’ensemble des tâches. -- `mode` : `"announce"` ou `"webhook"` ; vaut par défaut `"announce"` lorsque suffisamment de données de cible existent. +- `mode` : `"announce"` ou `"webhook"` ; par défaut `"announce"` lorsque suffisamment de données cibles existent. - `channel` : remplacement de canal pour la livraison par annonce. `"last"` réutilise le dernier canal de livraison connu. -- `to` : cible explicite d’annonce ou URL Webhook. Obligatoire pour le mode webhook. +- `to` : cible explicite d’annonce ou URL Webhook. Obligatoire en mode Webhook. - `accountId` : remplacement facultatif du 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, en cas d’échec, à cette cible d’annonce principale. -- `delivery.failureDestination` n’est pris en charge que pour les tâches `sessionTarget="isolated"`, sauf si le `delivery.mode` principal de la tâche est `"webhook"`. +- `delivery.failureDestination` par tâche remplace cette valeur par défaut globale. +- 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 principale d’annonce en cas d’échec. +- `delivery.failureDestination` n’est pris en charge que pour les tâches `sessionTarget="isolated"` sauf si le `delivery.mode` principal de la tâche est `"webhook"`. -Voir [Tâches Cron](/fr/automation/cron-jobs). Les exécutions Cron isolées sont suivies comme des [tâches d’arrière-plan](/fr/automation/tasks). +Voir [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). --- @@ -3833,7 +3833,7 @@ 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) | +| `{{RawBody}}` | Corps brut (sans wrappers d’historique/expéditeur) | | `{{BodyStripped}}` | Corps avec les mentions de groupe supprimées | | `{{From}}` | Identifiant de l’expéditeur | | `{{To}}` | Identifiant de destination | @@ -3844,20 +3844,20 @@ Espaces réservés de modèle développés dans `tools.media.models[].args` : | `{{MediaPath}}` | chemin local du média | | `{{MediaType}}` | type de média (image/audio/document/…) | | `{{Transcript}}` | transcription audio | -| `{{Prompt}}` | invite média résolue pour les entrées CLI | -| `{{MaxChars}}` | nombre maximal résolu de caractères de sortie pour les entrées CLI | +| `{{Prompt}}` | prompt média résolu pour les entrées CLI | +| `{{MaxChars}}` | nombre maximal de caractères résolu pour les entrées CLI | | `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | sujet du groupe (meilleur effort) | -| `{{GroupMembers}}` | aperçu des membres du groupe (meilleur effort) | -| `{{SenderName}}` | nom d’affichage de l’expéditeur (meilleur effort) | -| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (meilleur effort) | +| `{{GroupSubject}}` | sujet du groupe (au mieux) | +| `{{GroupMembers}}` | aperçu des membres du groupe (au mieux) | +| `{{SenderName}}` | nom d’affichage de l’expéditeur (au mieux) | +| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (au mieux) | | `{{Provider}}` | indication du fournisseur (whatsapp, telegram, discord, etc.) | --- -## Includes de configuration (`$include`) +## Inclusions de configuration (`$include`) -Scindez la configuration en plusieurs fichiers : +Divisez la configuration en plusieurs fichiers : ```json5 // ~/.openclaw/openclaw.json @@ -3873,11 +3873,11 @@ Scindez la configuration en plusieurs fichiers : **Comportement de fusion :** - Fichier unique : remplace l’objet conteneur. -- Tableau de fichiers : fusion profonde dans l’ordre (les derniers remplacent les précédents). -- Clés sœurs : fusionnées après les includes (remplacent les valeurs incluses). -- Includes imbriqués : 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, les erreurs d’analyse et les includes circulaires. +- Tableau de fichiers : fusion profonde dans l’ordre (les suivants 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 à l’intérieur du 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, les erreurs d’analyse et les inclusions circulaires. --- diff --git a/docs/fr/gateway/protocol.md b/docs/fr/gateway/protocol.md index 26644b1a6..9878354ae 100644 --- a/docs/fr/gateway/protocol.md +++ b/docs/fr/gateway/protocol.md @@ -1,34 +1,34 @@ --- read_when: - - Implémentation ou mise à jour des clients WS Gateway + - Implémenter ou mettre à jour des clients WS Gateway - 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 Gateway : poignée de main, trames, gestion des versions' +summary: 'Protocole WebSocket Gateway : négociation, trames, gestion des versions' title: Protocole Gateway x-i18n: - generated_at: "2026-04-16T06:57:00Z" + generated_at: "2026-04-18T06:43:36Z" model: gpt-5.4 provider: openai - source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 + source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41 source_path: gateway/protocol.md workflow: 15 --- # Protocole Gateway (WebSocket) -Le protocole WS Gateway est le **plan de contrôle unique + transport de nœuds** pour -OpenClaw. Tous les clients (CLI, interface web, application macOS, nœuds iOS/Android, -nœuds headless) se connectent via WebSocket et déclarent leur **rôle** + leur **portée** -au moment de la poignée de main. +Le protocole WS Gateway est le **plan de contrôle unique + 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 de la négociation. ## Transport - WebSocket, trames texte avec charges utiles JSON. - La première trame **doit** être une requête `connect`. -## Poignée de main (`connect`) +## Négociation (`connect`) -Gateway → Client (challenge avant connexion) : +Gateway → Client (défi de pré-connexion) : ```json { @@ -96,9 +96,23 @@ Gateway → Client : ``` `server`, `features`, `snapshot` et `policy` sont tous obligatoires d’après le schéma -(`src/gateway/protocol/schema/frames.ts`). `auth` et `canvasHostUrl` sont facultatifs. +(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` est facultatif. `auth` +rapporte le rôle/les portées négociés lorsqu’ils sont disponibles, et inclut `deviceToken` +quand la gateway en émet un. -Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également : +Lorsqu’aucun jeton d’appareil n’est émis, `hello-ok.auth` peut quand même rapporter les +autorisations négociées : + +```json +{ + "auth": { + "role": "operator", + "scopes": ["operator.read", "operator.write"] + } +} +``` + +Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut aussi : ```json { @@ -110,8 +124,8 @@ Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également : } ``` -Pendant le transfert d’amorçage approuvé, `hello-ok.auth` peut également inclure des -entrées de rôle supplémentaires bornées dans `deviceTokens` : +Lors du transfert d’amorçage approuvé, `hello-ok.auth` peut aussi inclure des entrées de rôle +supplémentaires et bornées dans `deviceTokens` : ```json { @@ -130,13 +144,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 de nœud principal reste à -`scopes: []` et tout jeton d’opérateur transféré reste borné à la liste d’autorisations +Pour le flux d’amorçage intégré nœud/opérateur, le jeton principal du nœud reste +`scopes: []` et tout jeton d’opérateur transmis reste borné à la liste d’autorisations 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 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. +`operator.talk.secrets`, `operator.write`). Les vérifications de portée d’amorçage 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 @@ -173,7 +186,7 @@ préfixe de rôle. } ``` -## Format des trames +## Encapsulation - **Requête** : `{type:"req", id, method, params}` - **Réponse** : `{type:"res", id, ok, payload|error}` @@ -185,7 +198,7 @@ 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 du plan de contrôle (CLI/interface/automatisation). - `node` = hôte de capacités (camera/screen/canvas/system.run). ### Portées (`operator`) @@ -202,317 +215,312 @@ Portées courantes : `talk.config` avec `includeSecrets: true` nécessite `operator.talk.secrets` (ou `operator.admin`). -Les méthodes RPC Gateway enregistrées par Plugin peuvent demander leur propre portée opérateur, mais -les préfixes d’administration réservés du noyau (`config.*`, `exec.approvals.*`, `wizard.*`, +Les méthodes RPC Gateway enregistrées par des plugins peuvent demander leur propre portée opérateur, mais +les préfixes d’administration de base réservés (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) se résolvent toujours en `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`. +La portée de méthode n’est que la première barrière. Certaines commandes slash atteintes via +`chat.send` appliquent en plus des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes +`/config set` et `/config unset` nécessitent `operator.admin`. -`node.pair.approve` a aussi 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 aussi 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 commandes de nœud non exec : `operator.pairing` + `operator.write` +- requêtes avec commandes de nœud autres que d’exécution : `operator.pairing` + `operator.write` - requêtes qui incluent `system.run`, `system.run.prepare` ou `system.which` : `operator.pairing` + `operator.admin` -### Caps/commands/permissions (`node`) +### `caps`/`commands`/`permissions` (`node`) -Les nœuds déclarent leurs 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’autorisations de commandes pour `invoke`. +- `commands` : liste d’autorisations de commandes pour l’invocation. - `permissions` : bascules granulaires (par ex. `screen.record`, `camera.capture`). -Gateway traite ces éléments comme des **revendications** et applique côté serveur des -listes d’autorisations. +La Gateway traite celles-ci comme des **revendications** et applique des listes d’autorisations 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 UI puissent afficher une seule ligne par appareil +- Les entrées de présence incluent `deviceId`, `roles` et `scopes` pour que les interfaces puissent afficher une seule ligne par appareil même lorsqu’il se connecte à la fois comme **operator** et **node**. ## Familles courantes de méthodes RPC -Cette page n’est pas un vidage complet généré, mais la surface WS publique est plus large -que les exemples de poignée de main/authentification ci-dessus. Voici les principales familles -de méthodes que Gateway expose aujourd’hui. +Cette page n’est pas une génération complète, mais la surface WS publique est plus large +que les exemples de négociation/authentification ci-dessus. Voici les principales familles de méthodes que la +Gateway expose aujourd’hui. -`hello-ok.features.methods` est une liste de découverte prudente construite à partir de -`src/gateway/server-methods-list.ts` ainsi que des exports de méthodes de Plugin/canal chargés. -Traitez-la comme une découverte de fonctionnalités, pas comme un vidage généré de chaque helper appelable -implémenté dans `src/gateway/server-methods/*.ts`. +`hello-ok.features.methods` est une liste de découverte conservatrice construite à partir de +`src/gateway/server-methods-list.ts` plus les exportations de méthodes de plugins/canaux chargés. +Traitez-la comme une découverte de fonctionnalités, et non comme une génération exhaustive de tous les assistants appelables +implémentés dans `src/gateway/server-methods/*.ts`. ### Système et identité -- `health` renvoie l’instantané de santé Gateway mis en cache ou sondé à nouveau. -- `status` renvoie le résumé Gateway de type `/status` ; les champs sensibles ne sont - inclus que pour les clients opérateur avec portée admin. -- `gateway.identity.get` renvoie l’identité d’appareil Gateway utilisée par les flux de relais et +- `health` renvoie l’instantané d’état de santé de la gateway, mis en cache ou sondé récemment. +- `status` renvoie le résumé de gateway au format `/status` ; les champs sensibles ne sont + inclus que pour les clients opérateur avec portée d’administration. +- `gateway.identity.get` renvoie l’identité d’appareil de la gateway utilisée par les flux de relais et d’appairage. - `system-presence` renvoie l’instantané 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 persisté. -- `set-heartbeats` active ou désactive le traitement des Heartbeat sur Gateway. +- `set-heartbeats` active ou désactive le traitement des Heartbeat sur la gateway. ### Modèles et utilisation - `models.list` renvoie le catalogue de modèles autorisés à l’exécution. -- `usage.status` renvoie les fenêtres d’utilisation fournisseur/les résumés de quota restant. -- `usage.cost` renvoie des résumés agrégés des coûts pour une plage de dates. -- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour le - workspace actif de l’agent par défaut. +- `usage.status` renvoie les fenêtres d’utilisation des fournisseurs/résumés de quota restant. +- `usage.cost` renvoie des résumés agrégés de coût d’utilisation pour un intervalle de dates. +- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour + l’espace de travail actif de l’agent par défaut. - `sessions.usage` renvoie des résumés d’utilisation par session. - `sessions.usage.timeseries` renvoie une série temporelle d’utilisation pour une session. -- `sessions.usage.logs` renvoie les entrées de journal 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.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.start` démarre un flux de connexion QR/web pour le fournisseur de canal web compatible QR actuellement actif. - `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 un push APNs de test à un nœud iOS enregistré. -- `voicewake.get` renvoie les déclencheurs de mot de réveil stockés. -- `voicewake.set` met à jour les déclencheurs de mot de réveil et diffuse la modification. +- `push.test` envoie une notification 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. ### Messagerie et journaux -- `send` est la RPC de livraison sortante directe pour les envois ciblés par +- `send` est la RPC de distribution 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 Gateway configuré avec curseur/limite et - contrôles de taille maximale en octets. +- `logs.tail` renvoie la fin du journal de fichiers configuré de la gateway avec curseur/limite et + contrôles du nombre maximal d’octets. ### Talk et TTS -- `talk.config` renvoie la charge utile effective de configuration Talk ; `includeSecrets` +- `talk.config` renvoie la charge utile de config Talk effective ; `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.speak` synthétise la parole via le fournisseur vocal Talk actif. -- `tts.status` renvoie l’état d’activation du TTS, le fournisseur actif, les fournisseurs de secours +- `talk.speak` synthétise la parole via le fournisseur de parole Talk actif. +- `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 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 texte-parole ponctuelle. -### Secrets, configuration, mise à jour et assistant +### Secrets, config, mise à jour et assistant -- `secrets.reload` re-résout les SecretRef actifs et ne remplace l’état secret d’exécution - qu’en cas de réussite complète. -- `secrets.resolve` résout les assignations de secrets ciblées par commande pour un - ensemble commande/cible spécifique. -- `config.get` renvoie l’instantané et le hash de la configuration actuelle. +- `secrets.reload` résout à nouveau les SecretRef actifs et remplace l’état des secrets à l’exécution + uniquement en cas de réussite complète. +- `secrets.resolve` résout les affectations de secrets ciblées par commande pour un ensemble spécifique + de commandes/cibles. +- `config.get` renvoie l’instantané de configuration actuel et son hachage. - `config.set` écrit une charge utile de configuration validée. - `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 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 l’exécution 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’UI, y compris pour les objets imbriqués, caractères génériques, - éléments de tableau et branches de composition `anyOf` / `oneOf` / `allOf` lorsque la + et textes d’aide utilisés par l’interface, 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 une charge utile de consultation limitée à un chemin pour un chemin de configuration : +- `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, indice correspondant + `hintPath`, et - résumés immédiats des enfants pour l’exploration détaillée UI/CLI. - - Les nœuds de schéma de consultation conservent la documentation orientée utilisateur et les champs de validation courants : + résumés immédiats des enfants pour l’exploration d’interface/CLI. + - 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 tels que + 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`, ainsi que le `hint` / `hintPath` correspondant. -- `update.run` exécute le flux de mise à jour Gateway et ne planifie un redémarrage que - si la mise à jour elle-même a réussi. + - Les résumés d’enfants exposent `key`, le `path` normalisé, `type`, `required`, + `hasChildren`, plus les `hint` / `hintPath` correspondants. +- `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’intégration via WS RPC. -### Familles principales existantes +### Familles majeures existantes -#### Helpers d’agent et de workspace +#### Assistants pour agent et 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 raccordement du workspace. +- `agents.list` renvoie les entrées d’agents configurées. +- `agents.create`, `agents.update` et `agents.delete` gèrent les enregistrements d’agents et + le câblage de l’espace de travail. - `agents.files.list`, `agents.files.get` et `agents.files.set` gèrent les - fichiers de workspace d’amorçage exposés pour un agent. + 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 +- `agent.wait` attend la fin d’une exécution et renvoie l’instantané terminal lorsqu’il est disponible. #### Contrôle de session - `sessions.list` renvoie l’index actuel des sessions. -- `sessions.subscribe` et `sessions.unsubscribe` activent ou désactivent les abonnements - aux événements de changement de session pour le client WS actuel. +- `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.preview` renvoie des aperçus bornés de transcription pour des clés + de session spécifiques. - `sessions.resolve` résout ou canonise 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 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 - des sessions. +- `sessions.patch` met à jour les métadonnées/remplacements de la session. +- `sessions.reset`, `sessions.delete` et `sessions.compact` effectuent la + maintenance des sessions. - `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 inline sont +- `chat.history` est normalisé pour l’affichage côté clients d’interface : 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 `...`, `...`, `...`, `...`, et 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 assistant composées uniquement de jetons silencieux telles que `NO_REPLY` / - `no_reply` exacts sont omises, et les lignes surdimensionnées peuvent être remplacées - par des espaces réservés. + sont supprimés, les lignes d’assistant composées uniquement de jetons silencieux comme `NO_REPLY` / + `no_reply` exacts sont omises, et les lignes surdimensionnées peuvent être remplacées par des espaces réservés. #### Appairage d’appareils et jetons d’appareil - `device.pair.list` renvoie les appareils appairés en attente et approuvés. - `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent - les enregistrements d’appairage d’appareil. + les enregistrements d’appairage d’appareils. - `device.token.rotate` fait tourner un jeton d’appareil appairé dans les limites approuvées - de rôle et de portée. + de son rôle et de ses portées. - `device.token.revoke` révoque un jeton d’appareil appairé. -#### Appairage de nœuds, invocation et travail en attente +#### Appairage de nœud, invocation et travail en attente - `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject` et `node.pair.verify` couvrent l’appairage des nœuds et la + `node.pair.reject` et `node.pair.verify` couvrent l’appairage de nœud et la vérification d’amorçage. - `node.list` et `node.describe` renvoient l’état des nœuds connus/connectés. - `node.rename` met à jour un libellé de nœud appairé. -- `node.invoke` transfère une commande à un nœud connecté. +- `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 les événements d’origine nœud de retour dans la Gateway. -- `node.canvas.capability.refresh` rafraîchit les jetons de capacité canvas bornés par porté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 en attente durable +- `node.event` transporte les événements émis par le nœud vers la gateway. +- `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œud connecté. +- `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 requêtes d’approbation exec ponctuelles ainsi que la + `exec.approval.resolve` couvrent les requêtes ponctuelles d’approbation exec 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élai d’attente). + la décision finale (ou `null` en cas de délai dépassé). - `exec.approvals.get` et `exec.approvals.set` gèrent les instantanés de politique - d’approbation exec de Gateway. -- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale exec - d’approbation de nœud via des commandes de relais de nœud. + d’approbation exec de la gateway. +- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale du nœud pour exec + via des commandes 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 familles principales +#### Autres familles majeures -- automatisation : - - `wake` planifie une injection de texte immédiate ou au prochain Heartbeat +- automation : + - `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 : `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 limités à la transcription. -- `session.message` et `session.tool` : mises à jour du flux de transcription/événements pour une +- `chat` : mises à jour du chat de l’interface comme `chat.inject` et autres + événements 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é. +- `sessions.changed` : l’index ou les métadonnées des sessions 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é Gateway. +- `tick` : événement périodique de maintien en vie / vitalité. +- `health` : mise à jour de l’instantané d’état de santé de la gateway. - `heartbeat` : mise à jour du flux d’événements Heartbeat. -- `cron` : événement de changement d’exécution/de tâche Cron. -- `shutdown` : notification d’arrêt de Gateway. -- `node.pair.requested` / `node.pair.resolved` : cycle de vie d’appairage de nœud. -- `node.invoke.request` : diffusion d’une requête d’invocation de nœud. -- `device.pair.requested` / `device.pair.resolved` : cycle de vie d’appareil appairé. -- `voicewake.changed` : la configuration des déclencheurs de mot de réveil a changé. -- `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. +- `cron` : événement de modification d’exécution/de tâche Cron. +- `shutdown` : notification d’arrêt de la gateway. +- `node.pair.requested` / `node.pair.resolved` : cycle de vie de l’appairage de nœud. +- `node.invoke.request` : diffusion de requête d’invocation de nœud. +- `device.pair.requested` / `device.pair.resolved` : cycle de vie d’un appareil appairé. +- `voicewake.changed` : la configuration des déclencheurs du 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 de nœud +### Méthodes d’assistance pour nœud - Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables de Skills pour les vérifications d’auto-autorisation. -### Méthodes helper d’opérateur +### Méthodes d’assistance pour opérateur -- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire - des commandes d’exécution pour un agent. - - `agentId` est facultatif ; omettez-le pour lire le workspace de l’agent par défaut. +- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire des commandes à l’exécution d’un agent. + - `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut. - `scope` contrôle la surface ciblée par le `name` principal : - - `text` renvoie le jeton de commande texte principal sans le `/` initial - - `native` et le chemin par défaut `both` renvoient des noms natifs sensibles au fournisseur + - `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 sensible au fournisseur lorsqu’il existe. - - `provider` est facultatif et n’affecte que le nommage natif ainsi que la disponibilité des - commandes Plugin natives. + - `textAliases` contient les alias slash exacts comme `/model` et `/m`. + - `nativeName` contient le nom de commande natif adapté au fournisseur lorsqu’il existe. + - `provider` est facultatif et n’affecte que la dénomination native ainsi que la disponibilité des + commandes natives de plugins. - `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 d’exécution pour un +- Les opérateurs peuvent appeler `tools.catalog` (`operator.read`) pour récupérer le catalogue d’outils à l’exécution d’un agent. La réponse inclut des outils groupés et des métadonnées de provenance : - `source` : `core` ou `plugin` - - `pluginId` : propriétaire Plugin lorsque `source="plugin"` - - `optional` : indique si un outil de Plugin est facultatif -- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire effectif - des outils d’exécution pour une session. + - `pluginId` : propriétaire du plugin lorsque `source="plugin"` + - `optional` : si un outil de plugin est facultatif +- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire des outils effectifs à l’exécution + pour une session. - `sessionKey` est obligatoire. - - La Gateway dérive un contexte d’exécution approuvé 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 - maintenant, y compris les outils du noyau, de Plugin et de canal. -- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire visible - de Skills pour un agent. - - `agentId` est facultatif ; omettez-le pour lire le workspace de l’agent par défaut. + - La gateway dérive côté serveur le contexte d’exécution approuvé à partir de la session au lieu d’accepter + un contexte d’authentification ou de distribution fourni par l’appelant. + - La réponse est limitée à la session et reflète ce que la conversation active peut utiliser actuellement, + y compris les outils de base, de plugins et de canaux. +- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire + visible de 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 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 - dossier de skill dans le répertoire `skills/` du workspace de l’agent par défaut. - - 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 workspace de l’agent par défaut. - - le mode config modifie par patch les valeurs de `skills.entries.` telles que `enabled`, + les options d’installation assainies sans exposer de 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`) en deux modes : + - 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 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`) en deux modes : + - 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 applique des correctifs aux valeurs `skills.entries.` telles que `enabled`, `apiKey` et `env`. ## Approbations exec -- Lorsqu’une requête exec a besoin d’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`). +- Lorsqu’une requête exec nécessite une approbation, la gateway diffuse `exec.approval.requested`. +- Les clients opérateurs 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 transférés `node.invoke system.run` réutilisent ce - `systemRunPlan` canonique comme contexte faisant autorité pour commande/cwd/session. +- Après approbation, les appels transmis `node.invoke system.run` réutilisent ce + `systemRunPlan` canonique comme contexte faisant autorité pour la commande/le répertoire de travail/la session. - Si un appelant modifie `command`, `rawCommand`, `cwd`, `agentId` ou - `sessionKey` entre `prepare` et le transfert final approuvé de `system.run`, la - Gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée. + `sessionKey` entre la préparation et la transmission finale approuvée de `system.run`, la + gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée. -## Repli de livraison d’agent +## Repli de distribution d’agent -- Les requêtes `agent` peuvent inclure `deliver=true` pour demander une livraison sortante. -- `bestEffortDeliver=false` conserve un comportement strict : les cibles de livraison non résolues ou internes uniquement renvoient `INVALID_REQUEST`. -- `bestEffortDeliver=true` autorise un repli vers une exécution limitée à la session lorsqu’aucune route de livraison externe ne peut être résolue (par exemple sessions internes/webchat ou configurations multicanales ambiguës). +- Les requêtes `agent` peuvent inclure `deliver=true` pour demander une distribution sortante. +- `bestEffortDeliver=false` conserve le comportement strict : les cibles de distribution non résolues ou internes uniquement renvoient `INVALID_REQUEST`. +- `bestEffortDeliver=true` autorise un repli vers une exécution limitée à la session lorsqu’aucune route externe distribuable ne peut être résolue (par exemple sessions internes/webchat ou configurations multicanales ambiguës). ## Gestion des versions @@ -525,122 +533,118 @@ implémenté dans `src/gateway/server-methods/*.ts`. ### Constantes client -Le client de référence dans `src/gateway/client.ts` utilise ces valeurs par défaut. Elles sont -stables sur le protocole v3 et constituent la base attendue pour les clients tiers. +Le client de référence dans `src/gateway/client.ts` utilise ces valeurs par défaut. Les valeurs sont +stables pour le protocole v3 et constituent la base attendue pour les clients tiers. -| Constante | Par défaut | Source | +| Constante | Valeur par défaut | Source | | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| Délai d’attente de requête (par RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| Délai d’attente préauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (limite `250`–`10_000`) | +| Délai d’expiration des requêtes (par RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| Délai préauth / défi de connexion | `10_000` ms | `src/gateway/handshake-timeouts.ts` (limite `250`–`10_000`) | | Backoff de reconnexion initial | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | | Backoff de reconnexion maximal | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | | Limite de nouvelle tentative rapide après fermeture par jeton d’appareil | `250` ms | `src/gateway/client.ts` | -| Délai de grâce avant `terminate()` forcé | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| Délai d’attente par défaut de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | -| Intervalle `tick` par défaut (avant `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | -| Fermeture pour expiration du `tick` | code `4000` lorsque le silence dépasse `tickIntervalMs * 2` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 Mo) | `src/gateway/server-constants.ts` | +| Grâce d’arrêt forcé avant `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| Délai par défaut de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| Intervalle tick par défaut (avant `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | +| Fermeture pour dépassement de délai tick | code `4000` quand le silence dépasse `tickIntervalMs * 2` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | Le serveur annonce les valeurs effectives `policy.tickIntervalMs`, `policy.maxPayload` et `policy.maxBufferedBytes` dans `hello-ok` ; les clients doivent respecter ces valeurs -plutôt que les valeurs par défaut avant la poignée de main. +plutôt que les valeurs par défaut d’avant négociation. ## Authentification - 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 +- Les modes porteurs d’identité tels que 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 plutôt que de `connect.params.auth.*`. -- Le mode d’ingress privé `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion - par secret partagé ; n’exposez pas ce mode sur un ingress public/non approuvé. -- Après l’appairage, la Gateway émet un **jeton d’appareil** borné au rôle + aux portées de la - connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être + `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’ingress privé `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une ingress publique/non approuvée. +- Après l’appairage, la Gateway émet un **jeton 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 lecture/sondage/état qui a déjà été accordé - et évite de réduire silencieusement les reconnexions à une +- Une reconnexion avec ce jeton d’appareil **stocké** doit aussi réutiliser l’ensemble de portées approuvé stocké pour ce jeton. Cela préserve l’accès lecture/sondage/état + déjà accordé et évite de réduire silencieusement les reconnexions à une portée implicite plus étroite, limitée à l’administration. - Assemblage côté client de l’authentification de connexion (`selectConnectAuth` dans `src/gateway/client.ts`) : - - `auth.password` est orthogonal et est toujours transféré lorsqu’il est défini. - - `auth.token` est renseigné par ordre de priorité : d’abord un jeton partagé explicite, - puis un `deviceToken` explicite, puis un jeton par appareil stocké (indexé par + - `auth.password` est orthogonal et est toujours transmis lorsqu’il est défini. + - `auth.token` est renseigné dans l’ordre de priorité suivant : d’abord un jeton partagé explicite, + puis un `deviceToken` explicite, puis un jeton stocké par appareil (indexé par `deviceId` + `role`). - - `auth.bootstrapToken` n’est envoyé que si aucun des éléments ci-dessus n’a résolu un - `auth.token`. Un jeton partagé ou tout jeton d’appareil résolu le supprime. - - La promotion automatique d’un jeton d’appareil stocké lors de l’unique - nouvelle tentative `AUTH_TOKEN_MISMATCH` est limitée aux **points de terminaison approuvés uniquement** — - loopback, ou `wss://` avec `tlsFingerprint` épinglé. Un `wss://` public - sans épinglage n’est pas admissible. + - `auth.bootstrapToken` n’est envoyé que lorsqu’aucun des éléments ci-dessus n’a résolu + un `auth.token`. Un jeton partagé ou tout jeton d’appareil résolu le supprime. + - L’auto-promotion d’un jeton d’appareil stocké lors de la nouvelle tentative unique + `AUTH_TOKEN_MISMATCH` est réservée **aux points de terminaison approuvés uniquement** — + loopback, ou `wss://` avec `tlsFingerprint` épinglé. Le `wss://` public + sans épinglage ne remplit pas cette condition. - 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 approuvé + Ne les persistez que lorsque la connexion a utilisé une auth d’amorçage sur un transport approuvé tel que `wss://` ou loopback/appairage local. - Si un client fournit un `deviceToken` **explicite** ou des `scopes` explicites, cet - ensemble de portées demandé par l’appelant reste faisant autorité ; les portées mises en cache ne sont - réutilisées que lorsque le client réutilise le jeton par appareil stocké. + 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 jeton stocké par appareil. - Les jetons 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 de rôles approuvés enregistré dans +- L’émission/la rotation des jetons reste limitée à l’ensemble de rôles approuvé enregistré dans l’entrée d’appairage de cet appareil ; la rotation d’un jeton ne peut pas étendre l’appareil à un rôle que l’approbation d’appairage n’a jamais accordé. -- Pour les sessions de jeton d’appareil appairé, la gestion des appareils est limitée à soi-même sauf si l’appelant - dispose également de `operator.admin` : les appelants non administrateurs 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 +- Pour les sessions de jeton d’appareil appairé, la gestion des appareils est limitée à soi-même sauf si l’appelant dispose aussi de `operator.admin` : les appelants non administrateurs ne peuvent supprimer/révoquer/faire tourner que **leur propre** entrée d’appareil. +- `device.token.rotate` vérifie aussi l’ensemble de portées opérateur demandé par rapport aux portées de session actuelles de l’appelant. Les appelants non administrateurs ne peuvent pas faire tourner un jeton 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` plus des indications de récupération : +- 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 du client pour `AUTH_TOKEN_MISMATCH` : - - Les clients approuvés peuvent tenter une nouvelle tentative bornée avec un jeton par appareil mis en cache. +- Comportement client pour `AUTH_TOKEN_MISMATCH` : + - Les clients approuvés peuvent tenter une nouvelle tentative bornée avec un jeton stocké par appareil en cache. - Si cette nouvelle tentative échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des indications d’action à l’opérateur. ## Identité d’appareil + appairage -- 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 Gateways émettent des jetons par appareil + rôle. -- Les approbations d’appairage sont requises pour les nouveaux ID d’appareil, sauf si l’approbation automatique locale +- 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 gateways émettent des jetons par appareil + rôle. +- Les approbations d’appairage sont requises pour les nouveaux IDs d’appareil sauf si l’auto-approbation locale est activée. -- L’approbation automatique d’appairage est centrée sur les connexions loopback locales directes. -- OpenClaw dispose également d’un chemin étroit d’auto-connexion local backend/conteneur pour - les flux helper approuvés à secret partagé. -- Les connexions tailnet ou LAN du même hôte sont toujours traitées comme distantes pour l’appairage et +- L’auto-approbation d’appairage est centrée sur les connexions directes locales loopback. +- OpenClaw dispose aussi d’un chemin étroit d’auto-connexion locale backend/conteneur pour + les flux d’assistance approuvés à secret partagé. +- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’appairage 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 ces modes : - `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost uniquement. - authentification opérateur Control UI réussie avec `gateway.auth.mode: "trusted-proxy"`. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (solution de dernier recours, forte dégradation de sécurité). + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (bris de glace, dégradation de sécurité sévère). - Toutes les connexions doivent signer le nonce `connect.challenge` fourni par le serveur. -### Diagnostics de migration d’authentification d’appareil +### Diagnostics de migration de l’authentification d’appareil -Pour les clients hérités qui utilisent encore le comportement de signature antérieur au challenge, `connect` renvoie maintenant +Pour les clients hérités qui utilisent encore le comportement de signature d’avant le défi, `connect` renvoie maintenant des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec un `error.details.reason` stable. Échecs de migration courants : -| Message | details.code | details.reason | Signification | +| 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` | 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 hors de la dérive autorisée. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est hors de l’écart 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/la canonisation de la clé publique a échoué. | Cible de migration : -- Toujours attendre `connect.challenge`. -- Signer la charge utile v2 qui inclut le nonce serveur. -- Envoyer le même nonce dans `connect.params.device.nonce`. +- Attendez toujours `connect.challenge`. +- Signez la charge utile v2 qui inclut le nonce du serveur. +- Envoyez 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 appareil/client/rôle/portées/jeton/nonce. - Les signatures héritées `v2` restent acceptées pour compatibilité, mais l’épinglage des métadonnées @@ -649,11 +653,11 @@ Cible de migration : ## TLS + épinglage - TLS est pris en charge pour les connexions WS. -- Les clients peuvent facultativement épingler l’empreinte du certificat Gateway (voir la - configuration `gateway.tls` ainsi que `gateway.remote.tlsFingerprint` ou la CLI `--tls-fingerprint`). +- Les clients peuvent éventuellement épingler l’empreinte du certificat de la gateway (voir la config `gateway.tls` + ainsi que `gateway.remote.tlsFingerprint` ou le CLI `--tls-fingerprint`). ## Portée -Ce protocole expose l’**API Gateway complète** (é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 cb618a95a..3658b2946 100644 --- a/docs/fr/help/testing.md +++ b/docs/fr/help/testing.md @@ -1,24 +1,24 @@ --- read_when: - - Exécution des tests localement ou en CI - - Ajout de tests de régression pour les bugs de modèle/fournisseur - - Débogage du comportement de Gateway + agent -summary: 'Kit de test : suites unitaires/e2e/live, exécuteurs Docker et ce que couvre chaque test' -title: Tests + - Exécuter les tests en local ou en CI + - Ajouter des tests de régression pour les bugs de modèle/fournisseur + - Déboguer le comportement du Gateway + de l’agent +summary: 'Kit de test : suites unitaires/e2e/en direct, exécuteurs Docker, et ce que couvre chaque test' +title: Test x-i18n: - generated_at: "2026-04-17T06:57:43Z" + generated_at: "2026-04-18T06:43:37Z" model: gpt-5.4 provider: openai - source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 + source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a source_path: help/testing.md workflow: 15 --- # Tests -OpenClaw comporte trois suites Vitest (unitaire/intégration, e2e, live) ainsi qu’un petit ensemble d’exécuteurs Docker. +OpenClaw comporte trois suites Vitest (unit/integration, e2e, live) et un petit ensemble d’exécuteurs Docker. -Ce document est un guide « comment nous testons » : +Ce document est un guide « comment nous testons » : - Ce que couvre chaque suite (et ce qu’elle ne couvre délibérément _pas_) - Quelles commandes exécuter pour les workflows courants (local, avant push, débogage) @@ -27,111 +27,111 @@ Ce document est un guide « comment nous testons » : ## Démarrage rapide -La plupart du temps : +La plupart du temps : -- Barrière complète (attendue avant un push) : `pnpm build && pnpm check && pnpm test` -- Exécution locale plus rapide de la suite complète sur une machine 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` +- Barrière complète (attendue avant 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` +- 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 plus de confiance : +Quand vous modifiez des tests ou souhaitez davantage de confiance : -- Barrière de couverture : `pnpm test:coverage` -- Suite E2E : `pnpm test:e2e` +- Barrière de couverture : `pnpm test:coverage` +- Suite E2E : `pnpm test:e2e` -Quand vous déboguez 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 Gateway outil/image) : `pnpm test:live` -- Cibler silencieusement un fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (modèles + sondes Gateway outil/image) : `pnpm test:live` +- Cibler silencieusement un fichier live : `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Astuce : lorsque vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. +Astuce : lorsque vous n’avez besoin que d’un seul cas en échec, préférez restreindre les tests live via les variables d’environnement de liste d’autorisation décrites ci-dessous. ## Exécuteurs spécifiques à la QA -Ces commandes se trouvent à côté des suites de test principales lorsque vous avez besoin du réalisme de qa-lab : +Ces commandes se trouvent à côté des suites de test principales lorsque vous avez besoin du réalisme de QA-lab : - `pnpm openclaw qa suite` - - Exécute directement sur l’hôte les scénarios QA adossés au dépôt. - - Exécute par défaut plusieurs scénarios sélectionnés en parallèle avec des workers Gateway isolés, jusqu’à 64 workers ou au nombre de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, ou `--concurrency 1` pour l’ancienne voie sérielle. + - Exécute directement sur l’hôte des scénarios QA adossés au dépôt. + - Exécute en parallèle plusieurs scénarios sélectionnés par défaut avec des workers Gateway isolés, jusqu’à 64 workers ou le nombre de scénarios sélectionnés. Utilisez `--concurrency ` pour ajuster le nombre de workers, ou `--concurrency 1` pour l’ancienne voie sérielle. - Prend en charge les modes fournisseur `live-frontier`, `mock-openai` et `aimock`. - `aimock` démarre un serveur fournisseur local adossé à AIMock pour une couverture expérimentale de fixtures et de moqueries de protocole, sans remplacer la voie `mock-openai` orientée scénario. + `aimock` démarre un serveur fournisseur local adossé à AIMock pour une couverture expérimentale des fixtures et des simulations de protocole sans remplacer la voie `mock-openai` orientée scénario. - `pnpm openclaw qa suite --runner multipass` - Exécute la même suite QA dans une VM Linux Multipass jetable. - Conserve le même comportement de sélection de scénarios que `qa suite` sur l’hôte. - Réutilise les mêmes drapeaux de sélection 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 exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA et `CODEX_HOME` lorsqu’il est présent. - - Les répertoires de sortie doivent rester sous la racine du dépôt afin que l’invité puisse y réécrire via l’espace de travail monté. - - Écrit le rapport + résumé QA habituels ainsi que les journaux Multipass dans + - Les répertoires de sortie doivent rester sous la racine du dépôt afin que l’invité puisse réécrire via l’espace de travail monté. + - Écrit le rapport QA + résumé habituels ainsi que les journaux Multipass sous `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Démarre le site QA adossé à Docker pour un travail QA de type opérateur. + - Démarre le site QA adossé à Docker pour le travail QA de type opérateur. - `pnpm openclaw qa aimock` - Démarre uniquement le serveur fournisseur AIMock local pour des tests de fumée directs du protocole. - `pnpm openclaw qa matrix` - Exécute la voie QA live Matrix contre un homeserver Tuwunel jetable adossé à Docker. - - Cet hôte QA est aujourd’hui réservé au dépôt/au développement. Les installations OpenClaw packagées n’embarquent pas `qa-lab`, elles n’exposent donc pas `openclaw qa`. - - Les clones du dépôt chargent directement l’exécuteur groupé ; aucune étape d’installation de Plugin séparée n’est nécessaire. - - Provisionne trois utilisateurs Matrix temporaires (`driver`, `sut`, `observer`) plus une salle privée, puis démarre un processus enfant QA Gateway avec le vrai Plugin Matrix comme transport du SUT. - - Utilise par défaut l’image Tuwunel stable épinglée `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Remplacez-la avec `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` lorsque vous devez tester une autre image. + - Cet hôte QA est aujourd’hui réservé au dépôt/développement. Les installations OpenClaw empaquetées n’embarquent pas `qa-lab`, donc elles n’exposent pas `openclaw qa`. + - Les clones du dépôt chargent directement l’exécuteur intégré ; aucune étape d’installation de Plugin distincte n’est nécessaire. + - Provisionne trois utilisateurs Matrix temporaires (`driver`, `sut`, `observer`) plus une salle privée, puis démarre un processus enfant Gateway QA avec le vrai Plugin Matrix comme transport SUT. + - Utilise par défaut l’image stable Tuwunel épinglée `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Remplacez-la avec `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` lorsque vous devez tester une autre image. - Matrix n’expose pas de drapeaux partagés de source d’identifiants, car la voie provisionne localement des utilisateurs jetables. - - Écrit un rapport QA Matrix, un résumé, un artefact des événements observés et un journal combiné stdout/stderr dans `.artifacts/qa-e2e/...`. + - Écrit sous `.artifacts/qa-e2e/...` un rapport QA Matrix, un résumé, un artefact des événements observés et un journal combiné stdout/stderr. - `pnpm openclaw qa telegram` - - Exécute la voie QA live Telegram contre un vrai groupe privé à l’aide des jetons de bot driver et SUT issus de l’environnement. + - Exécute la voie QA live Telegram contre un vrai groupe privé à l’aide des jetons de bot driver et SUT fournis par l’environnement. - Nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. L’identifiant du groupe doit être l’identifiant numérique du chat Telegram. - - Prend en charge `--credential-source convex` pour des identifiants mutualisés partagés. Utilisez le mode environnement par défaut, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour opter pour des baux mutualisés. - - Nécessite deux bots distincts dans le même groupe privé, le bot SUT devant exposer un nom d’utilisateur Telegram. - - Pour une observation stable entre bots, activez le mode de communication bot-à-bot dans `@BotFather` pour les deux bots et assurez-vous que le bot driver peut observer le trafic des bots du groupe. - - Écrit un rapport QA Telegram, un résumé et un artefact des messages observés dans `.artifacts/qa-e2e/...`. + - Prend en charge `--credential-source convex` pour les identifiants mutualisés en pool. Utilisez par défaut le mode env, ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` pour activer les baux mutualisés. + - Nécessite deux bots distincts dans le même groupe privé, le bot SUT exposant un nom d’utilisateur Telegram. + - Pour une observation stable bot-à-bot, activez le mode Bot-to-Bot Communication dans `@BotFather` pour les deux bots et assurez-vous que le bot driver peut observer le trafic des bots du groupe. + - Écrit sous `.artifacts/qa-e2e/...` un rapport QA Telegram, un résumé et un artefact des messages observés. -Les voies de transport live partagent un contrat standard unique afin que les nouveaux transports ne divergent pas : +Les voies de transport live partagent un contrat standard unique afin que les nouveaux transports ne divergent pas : -`qa-channel` reste la suite QA synthétique large et ne fait pas partie de la matrice de couverture des transports live. +`qa-channel` reste la large suite QA synthétique et ne fait pas partie de la matrice de couverture des transports live. -| Voie | Canary | Filtrage des mentions | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation des fils | Observation des réactions | Commande d’aide | -| -------- | ------ | --------------------- | -------------------------------- | ------------------------- | ------------------------- | ------------ | ------------------ | ------------------------- | --------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Voie | Canary | Filtrage des mentions | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation de fil | Observation des réactions | Commande d’aide | +| -------- | ------ | --------------------- | -------------------------------- | ------------------------- | ------------------------- | ------------ | ---------------- | ------------------------- | --------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Identifiants Telegram partagés via Convex (v1) Lorsque `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) est activé pour -`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie un Heartbeat -de ce bail pendant l’exécution de la voie, puis libère le bail à l’arrêt. +`openclaw qa telegram`, QA lab acquiert un bail exclusif depuis un pool adossé à Convex, envoie des Heartbeat +pendant l’exécution de la voie, puis libère le bail à l’arrêt. -Structure de projet Convex de référence : +Référence de structure de projet Convex : - `qa/convex-credential-broker/` -Variables d’environnement requises : +Variables d’environnement requises : - `OPENCLAW_QA_CONVEX_SITE_URL` (par exemple `https://your-deployment.convex.site`) -- Un secret pour le rôle sélectionné : +- Un secret pour le rôle sélectionné : - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` pour `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` pour `ci` -- Sélection du rôle d’identifiant : - - CLI : `--credential-role maintainer|ci` - - Valeur par défaut via l’environnement : `OPENCLAW_QA_CREDENTIAL_ROLE` (par défaut `maintainer`) +- Sélection du rôle d’identifiant : + - CLI : `--credential-role maintainer|ci` + - Valeur par défaut de l’environnement : `OPENCLAW_QA_CREDENTIAL_ROLE` (par défaut `maintainer`) -Variables d’environnement facultatives : +Variables d’environnement facultatives : - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (par défaut `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (par défaut `30000`) - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (par défaut `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (par défaut `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (par défaut `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (identifiant de traçabilité facultatif) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` autorise les URL Convex `http://` en loopback pour le développement strictement local. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (identifiant de trace facultatif) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` autorise les URL Convex `http://` en loopback pour le développement local uniquement. `OPENCLAW_QA_CONVEX_SITE_URL` doit utiliser `https://` en fonctionnement normal. -Les commandes d’administration de maintenance (ajout/suppression/liste du pool) nécessitent +Les commandes d’administration maintainer (ajout/suppression/liste de pool) nécessitent spécifiquement `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Assistants CLI pour les mainteneurs : +Aides CLI pour les maintainers : ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -141,86 +141,86 @@ pnpm openclaw qa credentials remove --credential-id Utilisez `--json` pour une sortie lisible par machine dans les scripts et utilitaires CI. -Contrat de point de terminaison par défaut (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`) : +Contrat de point de terminaison par défaut (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`) : - `POST /acquire` - - Requête : `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - - Succès : `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Épuisé/réessayable : `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Requête : `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Succès : `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - Épuisé/réessayable : `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - Succès : `{ status: "ok" }` (ou `2xx` vide) + - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Succès : `{ status: "ok" }` (ou `2xx` vide) - `POST /release` - - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - Succès : `{ status: "ok" }` (ou `2xx` vide) + - Requête : `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Succès : `{ status: "ok" }` (ou `2xx` vide) - `POST /admin/add` (secret maintainer uniquement) - - Requête : `{ kind, actorId, payload, note?, status? }` - - Succès : `{ status: "ok", credential }` + - Requête : `{ kind, actorId, payload, note?, status? }` + - Succès : `{ status: "ok", credential }` - `POST /admin/remove` (secret maintainer uniquement) - - Requête : `{ credentialId, actorId }` - - Succès : `{ status: "ok", changed, credential }` - - Garde de bail actif : `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Requête : `{ credentialId, actorId }` + - Succès : `{ status: "ok", changed, credential }` + - Garde sur bail actif : `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (secret maintainer uniquement) - - Requête : `{ kind?, status?, includePayload?, limit? }` - - Succès : `{ status: "ok", credentials, count }` + - Requête : `{ kind?, status?, includePayload?, limit? }` + - Succès : `{ status: "ok", credentials, count }` -Forme de charge utile pour le type Telegram : +Forme du payload pour le type Telegram : - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` doit être une chaîne correspondant à un identifiant numérique de chat Telegram. -- `admin/add` valide cette forme pour `kind: "telegram"` et rejette les charges utiles mal formées. +- `groupId` doit être une chaîne contenant un identifiant numérique de chat Telegram. +- `admin/add` valide cette forme pour `kind: "telegram"` et rejette les payloads mal formés. ### Ajouter un canal à la QA -L’ajout d’un canal au système QA Markdown nécessite exactement deux éléments : +L’ajout d’un canal au système QA markdown nécessite exactement deux éléments : 1. Un adaptateur de transport pour le canal. -2. Un paquet de scénarios qui exerce le contrat du canal. +2. Un pack de scénarios qui exerce le contrat du canal. N’ajoutez pas une nouvelle racine de commande QA de premier niveau lorsque l’hôte partagé `qa-lab` peut -prendre en charge le flux. +prendre en charge ce flux. -`qa-lab` possède les mécanismes hôtes partagés : +`qa-lab` prend en charge les mécanismes hôtes partagés : - la racine de commande `openclaw qa` - le démarrage et l’arrêt de la suite - la concurrence des workers - l’écriture des artefacts -- la génération de rapports +- la génération des rapports - l’exécution des scénarios - les alias de compatibilité pour les anciens scénarios `qa-channel` -Les Plugins d’exécuteur possèdent le contrat de transport : +Les Plugins d’exécuteur prennent en charge le contrat de transport : - comment `openclaw qa ` est monté sous la racine partagée `qa` -- comment Gateway est configuré pour ce transport +- comment le Gateway est configuré pour ce transport - comment l’état prêt est vérifié - comment les événements entrants sont injectés - comment les messages sortants sont observés - comment les transcriptions et l’état de transport normalisé sont exposés - comment les actions adossées au transport sont exécutées -- comment la réinitialisation ou le nettoyage spécifique au transport est géré +- comment la réinitialisation ou le nettoyage propres au transport sont gérés -Le seuil minimal d’adoption pour un nouveau canal est : +Le seuil minimal d’adoption pour un nouveau canal est : 1. Conserver `qa-lab` comme propriétaire de la racine partagée `qa`. -2. Implémenter l’exécuteur de transport sur la jonction hôte partagée `qa-lab`. -3. Conserver les mécanismes spécifiques au transport dans le Plugin d’exécuteur ou le harnais du Plugin. -4. Monter l’exécuteur comme `openclaw qa ` au lieu d’enregistrer une racine de commande concurrente. +2. Implémenter l’exécuteur de transport sur la couture hôte partagée `qa-lab`. +3. Conserver les mécanismes spécifiques au transport dans le Plugin d’exécuteur ou le harnais du canal. +4. Monter l’exécuteur comme `openclaw qa ` au lieu d’enregistrer une commande racine concurrente. Les Plugins d’exécuteur doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. - Gardez `runtime-api.ts` léger ; l’exécution paresseuse de la CLI et de l’exécuteur doit rester derrière des points d’entrée séparés. -5. Rédiger ou adapter des scénarios Markdown sous `qa/scenarios/`. -6. Utiliser les assistants de scénario génériques pour les nouveaux scénarios. -7. Conserver les alias de compatibilité existants, sauf si le dépôt effectue une migration intentionnelle. + Gardez `runtime-api.ts` léger ; le chargement paresseux de la CLI et l’exécution de l’exécuteur doivent rester derrière des points d’entrée distincts. +5. Rédiger ou adapter les scénarios markdown sous les répertoires thématiques `qa/scenarios/`. +6. Utiliser les aides de scénario génériques pour les nouveaux scénarios. +7. Conserver les alias de compatibilité existants sauf si le dépôt effectue une migration intentionnelle. -La règle de décision est stricte : +La règle de décision est stricte : - Si un comportement peut être exprimé une seule fois dans `qa-lab`, placez-le dans `qa-lab`. -- Si un comportement dépend d’un seul transport de canal, conservez-le dans ce Plugin d’exécuteur ou ce harnais de Plugin. -- Si un scénario nécessite une nouvelle capacité utilisable par plus d’un canal, ajoutez un assistant générique au lieu d’une branche spécifique au canal dans `suite.ts`. -- Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique à ce transport et rendez cela explicite dans le contrat du scénario. +- Si un comportement dépend d’un seul transport de canal, conservez-le dans ce Plugin d’exécuteur ou harnais de Plugin. +- Si un scénario a besoin d’une nouvelle capacité que plus d’un canal peut utiliser, ajoutez une aide générique au lieu d’une branche spécifique à un canal dans `suite.ts`. +- Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique au transport et rendez cela explicite dans le contrat du scénario. -Les noms d’assistants génériques préférés pour les nouveaux scénarios sont : +Les noms d’aides génériques préférés pour les nouveaux scénarios sont : - `waitForTransportReady` - `waitForChannelReady` @@ -235,7 +235,7 @@ Les noms d’assistants génériques préférés pour les nouveaux scénarios so - `formatTransportTranscript` - `resetTransport` -Des alias de compatibilité restent disponibles pour les scénarios existants, notamment : +Les alias de compatibilité restent disponibles pour les scénarios existants, notamment : - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -243,247 +243,247 @@ Des alias de compatibilité restent disponibles pour les scénarios existants, n - `formatConversationTranscript` - `resetBus` -Les nouveaux travaux sur les canaux doivent utiliser les noms d’assistants génériques. -Les alias de compatibilité existent pour éviter une migration brutale, pas comme modèle pour -la rédaction de nouveaux scénarios. +Les nouveaux travaux sur les canaux doivent utiliser les noms d’aides génériques. +Les alias de compatibilité existent pour éviter une migration en une journée, pas comme modèle +pour la rédaction de nouveaux scénarios. ## Suites de test (ce qui s’exécute où) -Considérez les suites comme un « réalisme croissant » (et une instabilité/un coût croissants) : +Considérez les suites comme ayant un « réalisme croissant » (et une instabilité/un coût croissants) : ### Unitaire / intégration (par défaut) -- Commande : `pnpm test` -- Config : dix exécutions de fragments séquentielles (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants -- Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, et les tests node `ui` autorisés couverts par `vitest.unit.config.ts` -- Portée : +- Commande : `pnpm test` +- Config : dix exécutions de fragments séquentielles (`vitest.full-*.config.ts`) sur les projets Vitest ciblés existants +- Fichiers : inventaires core/unit sous `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, ainsi que les tests Node `ui` autorisés couverts par `vitest.unit.config.ts` +- Portée : - Tests unitaires purs - - Tests d’intégration en processus (auth Gateway, routage, outillage, analyse, config) + - Tests d’intégration en processus (authentification Gateway, routage, outils, analyse, configuration) - Régressions déterministes pour des bugs connus -- Attentes : +- Attentes : - S’exécute en CI - Aucune vraie clé requise - Doit être rapide et stable -- Note sur les projets : - - `pnpm test` non ciblé exécute désormais onze petites configs 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 racine natif. Cela réduit le pic de RSS sur les machines chargées et évite que le travail `auto-reply`/extension n’affame des suites sans rapport. - - `pnpm test --watch` utilise toujours le graphe de projets natif racine `vitest.config.ts`, car une boucle watch multi-fragments n’est pas pratique. - - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` font d’abord passer les cibles explicites de fichier/répertoire par 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 ces mêmes voies ciblées lorsque le diff ne touche que des fichiers source/test routables ; les modifications de config/setup reviennent toujours à une relance large du projet racine. - - Les tests unitaires légers en imports provenant des agents, commandes, plugins, assistants `auto-reply`, `plugin-sdk` et zones utilitaires pures similaires passent par la voie `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers à état/lourds à l’exécution restent sur les voies existantes. - - Certains fichiers source assistants `plugin-sdk` et `commands` font aussi correspondre les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications d’assistants évitent de relancer toute la suite lourde pour ce répertoire. - - `auto-reply` possède maintenant trois compartiments dédiés : assistants core de premier niveau, tests d’intégration `reply.*` de premier niveau, et le sous-arbre `src/auto-reply/reply/**`. Cela garde le travail le plus lourd du harnais de réponse hors des tests bon marché de statut/fragment/token. -- Note sur l’exécuteur embarqué : - - Lorsque vous modifiez les entrées de découverte des message-tools ou le contexte d’exécution de Compaction, +- Note sur les projets : + - `pnpm test` sans ciblage exécute désormais onze configurations de fragments 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 géant natif de projet racine. Cela réduit le pic de RSS sur les machines chargées et évite que le travail `auto-reply`/extension n’affame les suites non liées. + - `pnpm test --watch` utilise toujours le graphe de projets racine natif `vitest.config.ts`, parce qu’une boucle de surveillance multi-fragments n’est pas pratique. + - `pnpm test`, `pnpm test:watch` et `pnpm test:perf:imports` acheminent d’abord les cibles explicites de fichier/répertoire via des voies ciblées, de sorte que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` évite de payer le coût complet de démarrage du projet racine. + - `pnpm test:changed` étend les chemins git modifiés vers ces mêmes voies ciblées lorsque le diff ne touche que des fichiers source/test routables ; les modifications de config/setup reviennent toujours à une relance large du projet racine. + - Les tests unitaires légers à l’import depuis les agents, commandes, plugins, aides `auto-reply`, `plugin-sdk` et zones utilitaires pures similaires passent par la voie `unit-fast`, qui ignore `test/setup-openclaw-runtime.ts` ; les fichiers avec état/runtime lourd restent sur les voies existantes. + - Certains fichiers source d’aide `plugin-sdk` et `commands` font aussi correspondre les exécutions en mode changed à des tests frères explicites dans ces voies légères, afin que les modifications 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 premier niveau, tests d’intégration `reply.*` de premier niveau et sous-arborescence `src/auto-reply/reply/**`. Cela garde le travail du harnais de réponse le plus lourd à l’écart 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 runtime de Compaction, conservez les deux niveaux de couverture. - - Ajoutez des régressions d’assistants ciblées pour les frontières pures de routage/normalisation. - - Gardez aussi les suites d’intégration de l’exécuteur embarqué en bon état : + - Ajoutez des régressions d’aide ciblées pour les limites pures de routage/normalisation. + - Gardez aussi 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 continuent bien de circuler - dans les vrais chemins `run.ts` / `compact.ts` ; des tests d’assistants seuls ne constituent pas + - 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 d’aide seuls ne constituent pas un substitut suffisant à ces chemins d’intégration. -- Note sur le pool : +- Note sur le pool : - La config Vitest de base utilise désormais `threads` par défaut. - - La config Vitest partagée fixe aussi `isolate: false` et utilise l’exécuteur non isolé sur les projets racine, e2e et live. - - La voie UI racine conserve son setup `jsdom` et son optimiseur, mais s’exécute maintenant elle aussi sur l’exécuteur partagé non isolé. + - La config Vitest partagée fixe aussi `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 `jsdom` et son optimiseur, mais s’exécute maintenant elle 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 config Vitest partagée. - - Le lanceur partagé `scripts/run-vitest.mjs` ajoute aussi désormais `--no-maglev` par défaut pour les processus Node enfants de Vitest afin de réduire l’agitation 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 locale rapide : + - 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 la charge de compilation V8 pendant les grosses exécutions locales. Définissez `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si vous devez comparer avec le comportement V8 standard. +- Note sur l’itération locale rapide : - `pnpm test:changed` passe par des voies ciblées lorsque les chemins modifiés correspondent proprement à une suite plus petite. - `pnpm test:max` et `pnpm test:changed:max` conservent le même comportement de routage, simplement avec une limite de workers plus élevée. - - L’auto-dimensionnement local des workers est désormais volontairement conservateur et ralentit aussi lorsque la charge moyenne de l’hôte est déjà élevée, afin que plusieurs exécutions Vitest concurrentes causent moins de dégâts par défaut. - - La config Vitest de base marque les fichiers projets/config comme `forceRerunTriggers` afin que les relances en mode changed restent correctes lorsque le câblage des tests change. - - La config conserve `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 du profilage direct. -- Note sur le débogage des performances : - - `pnpm test:perf:imports` active le rapport de durée d’import Vitest ainsi qu’une sortie détaillée des imports. + - L’auto-dimensionnement local des workers est désormais volontairement conservateur et recule aussi lorsque la moyenne de charge de l’hôte est déjà élevée, de sorte que plusieurs exécutions Vitest concurrentes fassent moins de dégâts par défaut. + - La config Vitest de base marque les projets/fichiers de config comme `forceRerunTriggers` afin que les 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 un profilage direct. +- Note sur le débogage des performances : + - `pnpm test:perf:imports` active le rapport de durée d’import de Vitest ainsi qu’une sortie de ventilation 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 ainsi que le RSS max macOS. -- `pnpm test:perf:changed:bench -- --worktree` mesure l’arbre de travail sale actuel en faisant passer la liste des fichiers modifiés par `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 de fichiers désactivé. +- `pnpm test:perf:changed:bench -- --ref ` compare `test:changed` routé avec le chemin natif du projet racine pour ce diff validé et affiche le temps mur ainsi que le RSS max macOS. +- `pnpm test:perf:changed:bench -- --worktree` mesure l’arbre sale actuel 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 la surcharge 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 par fichier désactivé. ### E2E (test de fumée Gateway) -- 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 : +- Commande : `pnpm test:e2e` +- Config : `vitest.e2e.config.ts` +- Fichiers : `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` +- Valeurs par défaut du runtime : - 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 le coût des E/S console. -- Remplacements utiles : - - `OPENCLAW_E2E_WORKERS=` pour forcer le nombre de workers (plafonné à 16). - - `OPENCLAW_E2E_VERBOSE=1` pour réactiver une sortie console verbeuse. -- Portée : + - Utilise des workers adaptatifs (CI : jusqu’à 2, local : 1 par défaut). + - S’exécute en mode silencieux par défaut pour réduire la surcharge d’E/S console. +- Remplacements utiles : + - `OPENCLAW_E2E_WORKERS=` pour forcer le nombre de workers (limité à 16). + - `OPENCLAW_E2E_VERBOSE=1` pour réactiver la sortie console détaillée. +- Portée : - Comportement end-to-end Gateway multi-instance - - Surfaces WebSocket/HTTP, appairage de nœuds et réseau plus lourd -- Attentes : - - S’exécute en CI (quand activé dans le pipeline) + - Surfaces WebSocket/HTTP, appairage de Node et réseau plus lourd +- 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 : test de fumée du backend OpenShell +### E2E : test de fumée du backend OpenShell -- Commande : `pnpm test:e2e:openshell` -- Fichier : `test/openshell-sandbox.e2e.test.ts` -- Portée : - - Démarre via Docker une Gateway OpenShell isolée sur l’hôte - - Crée un bac à sable à partir d’un Dockerfile local temporaire +- Commande : `pnpm test:e2e:openshell` +- Fichier : `test/openshell-sandbox.e2e.test.ts` +- Portée : + - Démarre sur l’hôte un Gateway OpenShell isolé via Docker + - Crée un sandbox à partir d’un Dockerfile local temporaire - Exerce le backend OpenShell d’OpenClaw via un vrai `sandbox ssh-config` + exécution SSH - - Vérifie le comportement du système de fichiers canonique distant via le pont fs du bac à sable -- Attentes : - - Uniquement sur activation volontaire ; ne fait pas partie de l’exécution par défaut `pnpm test:e2e` - - Nécessite une CLI `openshell` locale ainsi qu’un démon Docker opérationnel - - Utilise un `HOME` / `XDG_CONFIG_HOME` isolé, puis détruit la Gateway 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 + - Vérifie le comportement du système de fichiers canonique distant via le pont fs du sandbox +- Attentes : + - Opt-in uniquement ; ne fait pas partie de l’exécution `pnpm test:e2e` par défaut + - Nécessite une CLI `openshell` locale ainsi qu’un démon Docker fonctionnel + - Utilise des `HOME` / `XDG_CONFIG_HOME` isolés, puis détruit le Gateway de test et le sandbox +- Remplacements utiles : + - `OPENCLAW_E2E_OPENSHELL=1` pour activer le test lors d’une 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 : - - « Ce fournisseur/modèle fonctionne-t-il réellement _aujourd’hui_ avec de vrais identifiants ? » - - Détecter les changements de format fournisseur, les particularités d’appel d’outils, les problèmes d’authentification et le comportement de limitation de débit -- Attentes : - - Pas stable en CI par conception (vrais réseaux, vraies politiques fournisseur, quotas, indisponibilités) +- 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 réellement _aujourd’hui_ avec de vrais identifiants ? » + - Détecter les changements de format fournisseur, les particularités d’appel d’outil, les problèmes d’authentification et le comportement face aux limites de débit +- Attentes : + - Non stable en CI par conception (vrais réseaux, vraies politiques 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 vers un répertoire personnel 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 voulez intentionnellement que les tests live utilisent votre vrai répertoire personnel. -- `pnpm test:live` utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression `[live] ...`, mais masque l’avis supplémentaire `~/.profile` et coupe les journaux de bootstrap Gateway/le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer les journaux de démarrage complets. -- Rotation des clés API (spécifique au fournisseur) : définissez `*_API_KEYS` au 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 sur les réponses de limitation de débit. -- Sortie de progression/Heartbeat : - - Les suites live émettent désormais des lignes de progression sur 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 de console par Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions live. + - 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 d’API manquantes. +- Par défaut, les exécutions live isolent toujours `HOME` et copient le matériel de config/authentification dans un répertoire personnel 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 voulez volontairement que les tests live utilisent votre vrai répertoire personnel. +- `pnpm test:live` utilise désormais par défaut un mode plus silencieux : il conserve la sortie de progression `[live] ...`, mais supprime l’avis supplémentaire sur `~/.profile` et coupe les journaux de démarrage Gateway / le bruit Bonjour. Définissez `OPENCLAW_LIVE_TEST_QUIET=0` si vous voulez récupérer les journaux de démarrage complets. +- Rotation des clés d’API (spécifique au fournisseur) : définissez `*_API_KEYS` au format virgule/point-virgule ou `*_API_KEY_1`, `*_API_KEY_2` (par exemple `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou utilisez le remplacement propre au live via `OPENCLAW_LIVE_*_KEY` ; les tests réessaient sur les réponses de limite de débit. +- Sortie de progression/Heartbeat : + - Les suites live émettent désormais les lignes de progression vers stderr afin que les longs appels fournisseur restent visiblement actifs même lorsque la capture de console Vitest est silencieuse. + - `vitest.live.config.ts` désactive l’interception de console de Vitest afin que les lignes de progression fournisseur/Gateway soient diffusées immédiatement pendant les exécutions live. - Ajustez les Heartbeat des modèles directs avec `OPENCLAW_LIVE_HEARTBEAT_MS`. - Ajustez les Heartbeat Gateway/sondes 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 de la logique/des tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié) -- Toucher au réseau Gateway / au protocole WS / à l’appairage : ajoutez `pnpm test:e2e` -- Déboguer « mon bot est hors service » / des échecs spécifiques à un fournisseur / l’appel d’outils : exécutez un `pnpm test:live` restreint +- Modification de logique/tests : exécutez `pnpm test` (et `pnpm test:coverage` si vous avez beaucoup modifié) +- Si vous touchez au réseau Gateway / protocole WS / appairage : ajoutez `pnpm test:e2e` +- Débogage de « mon bot est hors service » / échecs spécifiques à un fournisseur / appel d’outil : exécutez un `pnpm test:live` restreint -## Live : balayage des capacités du nœud Android +## Live : balayage des capacités du Node 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 contractuel de la commande. -- Portée : - - Préconfiguration/manuelle (la suite n’installe pas, n’exécute pas et n’appaire pas l’application). - - Validation `node.invoke` Gateway commande par commande pour le nœud Android sélectionné. -- Préconfiguration requise : - - Application Android déjà connectée + appairée à la Gateway. - - Application maintenue au premier plan. +- Test : `src/gateway/android-node.capabilities.live.test.ts` +- Script : `pnpm android:test:integration` +- Objectif : invoquer **chaque commande actuellement annoncée** par un Node Android connecté et vérifier le comportement du contrat de commande. +- Portée : + - Préconfiguration/configuration manuelle requise (la suite n’installe ni n’exécute ni n’appaire l’application). + - Validation `node.invoke` Gateway commande par commande pour le Node Android sélectionné. +- Préconfiguration requise : + - Application Android déjà connectée et appairée au Gateway. + - Application gardée au premier plan. - Permissions/consentement de capture accordés pour les capacités que vous attendez comme réussies. -- Remplacements facultatifs de cible : +- Remplacements facultatifs de cible : - `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 la configuration Android : [Application Android](/fr/platforms/android) +- Détails complets de configuration Android : [Android App](/fr/platforms/android) -## Live : test de fumée des modèles (clés de profil) +## Live : test de fumée de modèle (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 de pouvoir isoler les échecs : -- « Modèle direct » nous indique si le fournisseur/modèle peut répondre tout court avec la clé donnée. -- « Test de fumée Gateway » nous indique si le pipeline complet Gateway+agent fonctionne pour ce modèle (sessions, historique, outils, politique de bac à sable, etc.). +- Le « modèle direct » nous indique si le fournisseur/modèle peut répondre tout court avec la clé donnée. +- Le « test de fumée Gateway » nous indique si tout le pipeline gateway+agent fonctionne pour ce modèle (sessions, historique, outils, politique de sandbox, etc.). -### Couche 1 : complétion directe du modèle (sans Gateway) +### Couche 1 : complétion directe du modèle (sans Gateway) -- 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 test de fumée Gateway -- Comment sélectionner les modèles : +- Définissez `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) pour exécuter réellement cette suite ; sinon elle est ignorée afin de garder `pnpm test:live` concentré sur le test de fumée Gateway +- Comment sélectionner les modèles : - `OPENCLAW_LIVE_MODELS=modern` pour exécuter la liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` est un alias de la liste d’autorisation moderne - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (liste d’autorisation séparée par des virgules) - - Les balayages modern/all utilisent par défaut un plafond curaté à 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 : + - Les balayages modern/all utilisent par défaut un plafond sélectionné à fort signal ; définissez `OPENCLAW_LIVE_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus réduit. +- 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 solutions de repli via l’environnement +- D’où viennent les clés : + - Par défaut : magasin de profils et replis vers l’environnement - Définissez `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour imposer **uniquement le magasin de profils** -- Pourquoi cela existe : - - Sépare « l’API du fournisseur est cassée / la clé est invalide » de « le pipeline d’agent Gateway est cassé » - - Contient de petites régressions isolées (exemple : rejeu de raisonnement OpenAI Responses/Codex Responses + flux d’appel d’outils) +- Pourquoi cela existe : + - Sépare « l’API du fournisseur est cassée / la clé est invalide » de « le pipeline d’agent Gateway est cassé » + - Contient de petites régressions isolées (exemple : rejouage du raisonnement OpenAI Responses/Codex Responses + flux d’appel d’outil) -### Couche 2 : test de fumée Gateway + agent de développement (ce que fait réellement « @openclaw ») +### Couche 2 : test de fumée Gateway + agent de développement (ce que fait réellement "@openclaw") -- Test : `src/gateway/gateway-models.profiles.live.test.ts` -- Objectif : - - Démarrer une Gateway en processus - - Créer/modifier une session `agent:dev:*` (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) - - sondes d’outils supplémentaires facultatives (sonde exec+read) - - les chemins de régression OpenAI (tool-call-only → suivi) continuent de fonctionner -- Détails des sondes (afin d’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 via `exec` un nonce dans un fichier temporaire, puis de le relire via `read`. - - sonde d’image : le test joint un PNG généré (chat + code aléatoire) et attend du modèle qu’il 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 : +- Test : `src/gateway/gateway-models.profiles.live.test.ts` +- Objectif : + - Démarrer un Gateway en processus + - Créer/modifier une session `agent:dev:*` (remplacement du modèle à chaque exécution) + - Itérer sur les modèles-avec-clés et vérifier : + - une réponse « significative » (sans outils) + - qu’un véritable appel d’outil fonctionne (sonde de lecture) + - des sondes d’outil supplémentaires facultatives (sonde exec+read) + - que les chemins de régression OpenAI (appel-d’outil-seulement → suivi) continuent de fonctionner +- Détails des sondes (pour pouvoir expliquer rapidement les échecs) : + - sonde `read` : le test écrit un fichier nonce dans l’espace de travail et demande à l’agent de le `read` puis de renvoyer la nonce. + - sonde `exec+read` : le test demande à l’agent d’écrire une nonce via `exec` dans un fichier temporaire, puis de la relire via `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 : - `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 pour la liste d’autorisation moderne +- Comment sélectionner les modèles : + - Par défaut : liste d’autorisation moderne (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` est un alias de la liste d’autorisation moderne - Ou définissez `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou une liste séparée par des virgules) pour restreindre - - Les balayages Gateway modern/all utilisent par défaut un plafond curaté à 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 (éviter « tout OpenRouter ») : + - Les balayages Gateway modern/all utilisent par défaut un plafond sélectionné à fort signal ; définissez `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` pour un balayage moderne exhaustif ou un nombre positif pour un plafond plus réduit. +- Comment sélectionner les fournisseurs (éviter « OpenRouter tout ») : - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (liste d’autorisation séparée par des virgules) -- Les sondes outil + image sont toujours activées dans ce test live : - - sonde `read` + sonde `exec+read` (stress des outils) - - la sonde d’image s’exécute lorsque le modèle annonce la prise en charge de l’entrée 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`) +- Les sondes d’outil + 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 de l’entrée d’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: "" }]` - - Gateway analyse les pièces jointes en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Le Gateway 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 : petites erreurs autorisées) + - Vérification : la réponse contient `cat` + le code (tolérance OCR : erreurs mineures autorisées) -Astuce : 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 : test de fumée du backend CLI (Claude, Codex, Gemini ou autres CLI locales) +## Live : test de fumée 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 config par défaut. -- Les valeurs par défaut des tests de fumée spécifiques au backend se trouvent dans 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 spécifiques aux tests de fumée du backend vivent avec la définition `cli-backend.ts` de l’extension propriétaire. +- Activer : - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` si vous invoquez Vitest directement) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Valeurs par défaut : - - 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. -- Remplacements facultatifs : +- Valeurs par défaut : + - Fournisseur/modèle par défaut : `claude-cli/claude-sonnet-4-6` + - Le comportement commande/arguments/image provient des métadonnées du Plugin backend CLI propriétaire. +- Remplacements facultatifs : - `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 l’invite). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` pour transmettre les chemins de 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 manière dont les arguments image sont transmis lorsque `IMAGE_ARG` est défini. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` pour envoyer une véritable 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 arguments CLI au lieu d’une injection dans le prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) pour contrôler la façon dont les arguments image sont 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 de continuité par défaut sur la même session Claude Sonnet -> Opus (définissez `1` pour la forcer lorsque le modèle sélectionné prend en charge une cible de bascule). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` pour désactiver la sonde de continuité de session par défaut Claude Sonnet -> Opus sur une même session (définissez `1` pour la forcer lorsque le modèle sélectionné prend en charge une cible de changement). -Exemple : +Exemple : ```bash OPENCLAW_LIVE_CLI_BACKEND=1 \ @@ -491,13 +491,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 mono-fournisseur : +Recettes Docker mono-fournisseur : ```bash pnpm test:docker:live-cli-backend:claude @@ -506,42 +506,42 @@ pnpm test:docker:live-cli-backend:codex pnpm test:docker:live-cli-backend:gemini ``` -Notes : +Remarques : - L’exécuteur Docker se trouve dans `scripts/test-live-cli-backend-docker.sh`. -- Il exécute le test de fumée live du backend CLI dans l’image Docker du dépôt en tant qu’utilisateur `node` non root. -- Il résout les métadonnées du test de fumée 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 inscriptible mis en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` nécessite une authentification OAuth portable Claude Code subscription via soit `~/.claude/.credentials.json` avec `claudeAiOauth.subscriptionType`, soit `CLAUDE_CODE_OAUTH_TOKEN` issu de `claude setup-token`. Il prouve d’abord un `claude -p` direct dans Docker, puis exécute deux tours Gateway backend CLI sans conserver les variables d’environnement de clé API Anthropic. Cette voie subscription désactive par défaut la sonde Claude MCP/tool et les sondes d’image, car Claude achemine actuellement l’usage d’applications tierces via une facturation d’usage supplémentaire plutôt que via les limites normales du plan d’abonnement. -- Le test de fumée live du 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 la CLI Gateway. +- Il exécute le test de fumée live du backend CLI à l’intérieur de l’image Docker du dépôt en tant qu’utilisateur non root `node`. +- Il résout les métadonnées de test de fumée CLI depuis l’extension propriétaire, puis installe le package CLI Linux correspondant (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) dans un préfixe inscriptible mis en cache à `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (par défaut : `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` nécessite une OAuth portable d’abonnement Claude Code via soit `~/.claude/.credentials.json` avec `claudeAiOauth.subscriptionType`, soit `CLAUDE_CODE_OAUTH_TOKEN` depuis `claude setup-token`. Il prouve d’abord le `claude -p` direct dans Docker, puis exécute deux tours Gateway backend CLI sans conserver les variables d’environnement de clé d’API Anthropic. Cette voie d’abonnement désactive par défaut les sondes Claude MCP/outils et image, car Claude achemine actuellement l’usage des applications tierces via une facturation d’usage supplémentaire plutôt que par les limites normales du plan d’abonnement. +- Le test de fumée live du backend CLI exerce désormais le même flux end-to-end pour Claude, Codex et Gemini : tour texte, tour de classification d’image, puis appel d’outil MCP `cron` vérifié via la CLI Gateway. - Le test de fumée par défaut de Claude modifie aussi la session de Sonnet vers Opus et vérifie que la session reprise se souvient toujours d’une note antérieure. -## Live : test de fumée de liaison ACP (`/acp spawn ... --bind here`) +## Live : test de fumée 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 véritable 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 messages - envoyer un suivi normal sur cette même conversation - - vérifier que le suivi aboutit dans la transcription de session ACP liée -- Activer : + - vérifier que le suivi atterrit dans la transcription de session ACP liée +- Activer : - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Valeurs par défaut : - - Agents ACP dans Docker : `claude,codex,gemini` - - Agent ACP pour `pnpm test:live ...` direct : `claude` - - Canal synthétique : contexte de conversation de type message direct 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` +- Remplacements : - `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@'` -- Notes : - - Cette voie utilise la surface `chat.send` de Gateway avec des champs de route d’origine synthétiques réservés à l’admin afin que les tests puissent joindre un contexte de canal de messages sans prétendre à une livraison externe. +- Remarques : + - Cette voie utilise la surface Gateway `chat.send` avec des champs synthétiques d’itinéraire d’origine réservés à l’administration afin que les tests puissent attacher un contexte de canal de messages sans prétendre livrer de messages en externe. - 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 \ @@ -549,13 +549,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 mono-agent : +Recettes Docker mono-agent : ```bash pnpm test:docker:live-acp-bind:claude @@ -563,36 +563,36 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Notes Docker : +Remarques Docker : - L’exécuteur Docker se trouve dans `scripts/test-live-acp-bind-docker.sh`. -- Par défaut, il exécute en séquence le test de fumée de liaison ACP contre tous les agents CLI live pris en charge : `claude`, `codex`, puis `gemini`. +- Par défaut, il exécute le test de fumée 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 dans le conteneur le matériel d’authentification CLI correspondant, installe `acpx` dans un préfixe npm inscriptible, puis installe la CLI live demandée (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) si elle est absente. -- Dans Docker, l’exécuteur définit `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` afin que acpx conserve pour la CLI de harnais enfant les variables d’environnement du fournisseur issues du profil chargé. +- À 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 pour la CLI de harnais enfant les variables d’environnement fournisseur issues du profil chargé. -## Live : test de fumée du harnais Codex app-server +## Live : test de fumée du harnais app-server Codex -- Objectif : valider le harnais Codex possédé par le Plugin via la méthode - `agent` normale de Gateway : - - charger le Plugin `codex` groupé +- Objectif : valider le harnais Codex appartenant au Plugin via la méthode Gateway + `agent` normale : + - charger le Plugin `codex` intégré - sélectionner `OPENCLAW_AGENT_RUNTIME=codex` - - envoyer un premier tour agent Gateway à `codex/gpt-5.4` - - envoyer un second tour à la même session OpenClaw et vérifier que le fil + - envoyer un premier tour d’agent Gateway à `codex/gpt-5.4` + - envoyer un second tour à la même session OpenClaw et vérifier que le thread app-server peut reprendre - exécuter `/codex status` et `/codex models` via le même chemin de commande Gateway -- Test : `src/gateway/gateway-codex-harness.live.test.ts` -- Activer : `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Modèle par défaut : `codex/gpt-5.4` -- Sonde d’image facultative : `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sonde MCP/tool facultative : `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Le test de fumée définit `OPENCLAW_AGENT_HARNESS_FALLBACK=none` afin qu’un harnais Codex - défectueux ne puisse pas réussir en basculant silencieusement vers PI. -- Authentification : `OPENAI_API_KEY` depuis le shell/profil, plus éventuellement - `~/.codex/auth.json` et `~/.codex/config.toml` copiés +- Test : `src/gateway/gateway-codex-harness.live.test.ts` +- Activer : `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Modèle par défaut : `codex/gpt-5.4` +- Sonde d’image facultative : `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonde MCP/outil facultative : `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Le test de fumée définit `OPENCLAW_AGENT_HARNESS_FALLBACK=none` afin qu’un harnais Codex cassé + ne puisse pas réussir en se rabattant silencieusement sur Pi. +- Authentification : `OPENAI_API_KEY` depuis le shell/profil, plus copie facultative de + `~/.codex/auth.json` et `~/.codex/config.toml` -Recette locale : +Recette locale : ```bash source ~/.profile @@ -603,417 +603,415 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Recette Docker : +Recette Docker : ```bash source ~/.profile pnpm test:docker:live-codex-harness ``` -Notes Docker : +Remarques Docker : - L’exécuteur Docker se trouve dans `scripts/test-live-codex-harness-docker.sh`. -- Il charge le `~/.profile` monté, transmet `OPENAI_API_KEY`, copie les fichiers d’authentification de la CLI Codex lorsqu’ils sont présents, installe `@openai/codex` dans un préfixe npm monté inscriptible, prépare l’arborescence source, puis exécute uniquement le test live du harnais Codex. -- Docker active par défaut les sondes d’image ainsi que les sondes MCP/tool. Définissez +- Il charge le `~/.profile` monté, transmet `OPENAI_API_KEY`, copie les fichiers d’authentification de la CLI Codex lorsqu’ils sont présents, installe `@openai/codex` dans un préfixe npm monté et inscriptible, prépare l’arborescence source, puis n’exécute que le test live du harnais Codex. +- Docker active par défaut les sondes d’image et MCP/outil. Définissez `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` lorsque vous avez besoin d’une exécution de débogage plus restreinte. -- Docker exporte aussi `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, conformément à la config du test - live afin qu’un fallback `openai-codex/*` ou PI ne puisse pas masquer une régression - du harnais Codex. +- Docker exporte aussi `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, conformément à la configuration du test live afin qu’un repli sur `openai-codex/*` ou Pi ne puisse pas masquer une régression du harnais Codex. ### Recettes live recommandées -Les listes d’autorisation étroites et explicites sont les plus rapides et les moins instables : +Les listes d’autorisation étroites et explicites sont les plus rapides et les moins instables : -- Modèle unique, direct (sans Gateway) : +- Modèle unique, direct (sans Gateway) : - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modèle unique, test de fumée Gateway : +- Modèle unique, test de fumée Gateway : - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Appel d’outils sur plusieurs fournisseurs : +- Appel d’outil 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é d’API Gemini + Antigravity) : + - Gemini (clé d’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` -Notes : +Remarques : -- `google/...` utilise l’API Gemini (clé API). +- `google/...` utilise l’API Gemini (clé d’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 (clé API / authentification de 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). +- `google-gemini-cli/...` utilise la CLI Gemini locale sur votre machine (authentification séparée + particularités d’outillage). +- API Gemini vs CLI Gemini : + - API : OpenClaw appelle l’API Gemini hébergée de Google via HTTP (clé d’API / authentification de profil) ; c’est ce que la plupart des utilisateurs entendent par « Gemini ». + - CLI : OpenClaw exécute un binaire `gemini` local ; 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 activé sur demande), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement disposant des clés. +Il n’existe pas de « liste de modèles CI » fixe (le live est opt-in), mais voici les modèles **recommandés** à couvrir régulièrement sur une machine de développement disposant des clés. -### Ensemble de fumée moderne (appel d’outils + image) +### Ensemble de test de fumée moderne (appel d’outil + image) -Il s’agit de l’exécution des « modèles courants » que nous attendons de garder fonctionnelle : +Il s’agit de l’exécution « modèles courants » que nous nous attendons à voir continuer à fonctionner : -- 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` (évitez les anciens modèles Gemini 2.x) +- Google (Antigravity) : `google-antigravity/claude-opus-4-6-thinking` et `google-antigravity/gemini-3-flash` +- Z.AI (GLM) : `zai/glm-4.7` +- MiniMax : `minimax/MiniMax-M2.7` -Exécutez le test de fumée Gateway avec outils + image : +Exécuter le test de fumée Gateway avec outils + image : `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Référence de base : appel d’outils (Read + Exec facultatif) +### Référence de base : appel d’outil (Read + Exec facultatif) -Choisissez au moins un modèle par famille de fournisseurs : +Choisissez au moins un modèle 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 additionnelle facultative (agréable à avoir) : +Couverture supplémentaire facultative (utile à avoir) : -- xAI : `xai/grok-4` (ou le plus récent 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) +- 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) -### 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 Claude/Gemini/OpenAI compatibles vision, etc.) afin d’exercer la sonde d’image. ### Agrégateurs / passerelles alternatives -Si vous avez activé les clés, nous prenons aussi en charge les tests via : +Si vous avez les clés activées, nous prenons aussi en charge les tests via : -- OpenRouter : `openrouter/...` (des centaines de modèles ; utilisez `openclaw models scan` pour trouver des candidats compatibles outil+image) -- OpenCode : `opencode/...` pour Zen et `opencode-go/...` pour Go (authentification 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.) -Astuce : 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 de référence est celle que renvoie `discoverModels(...)` sur votre machine + les clés disponibles. ## Identifiants (ne jamais valider) -Les tests live découvrent les identifiants de la même façon que la CLI. Implications pratiques : +Les tests live découvrent les identifiants de la même manière que la CLI. Implications pratiques : - Si la CLI fonctionne, les tests live devraient trouver les mêmes clés. -- Si un test live indique « pas d’identifiants », déboguez-le comme vous débogueriez `openclaw models list` / la sélection de modèle. +- Si un test live indique « aucun identifiant », déboguez-le comme vous le feriez pour `openclaw models list` / la sélection du 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`) -- Répertoire d’état hérité : `~/.openclaw/credentials/` (copié dans le répertoire personnel 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 répertoire `credentials/` et les répertoires d’authentification CLI externes pris en charge dans un répertoire personnel de test temporaire ; les répertoires personnels live préparés ignorent `workspace/` et `sandboxes/`, et les remplacements de chemin `agents.*.workspace` / `agentDir` sont supprimés afin que les sondes restent en dehors 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 magasin principal des clés de profil) +- Les exécutions live locales copient par défaut la configuration active, les fichiers `auth-profiles.json` par agent, l’ancien répertoire `credentials/` et les répertoires d’authentification CLI externes pris en charge dans un HOME de test temporaire ; les HOME 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. Si vous voulez vous appuyer sur des clés d’environnement (par exemple exportées dans votre `~/.profile`), exécutez les tests locaux après `source ~/.profile`, ou utilisez les exécuteurs Docker ci-dessous (ils peuvent monter `~/.profile` dans le conteneur). ## Live Deepgram (transcription audio) -- Test : `src/media-understanding/providers/deepgram/audio.live.test.ts` -- Activer : `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` +- Test : `src/media-understanding/providers/deepgram/audio.live.test.ts` +- Activer : `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` ## Live BytePlus coding plan -- Test : `src/agents/byteplus.live.test.ts` -- Activer : `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Remplacement facultatif du modèle : `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` +- Remplacement facultatif de modèle : `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live média de workflow ComfyUI +## Live médias de workflow ComfyUI -- Test : `extensions/comfy/comfy.live.test.ts` -- Activer : `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Portée : - - Exerce les chemins groupés comfy image, vidéo et `music_generate` - - Ignore chaque capacité à moins que `models.providers.comfy.` ne soit configuré - - Utile après modification de la soumission de workflow comfy, du polling, des téléchargements ou de l’enregistrement du Plugin +- Test : `extensions/comfy/comfy.live.test.ts` +- Activer : `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` +- Portée : + - Exerce les chemins image, vidéo et `music_generate` du comfy intégré + - Ignore chaque capacité sauf si `models.providers.comfy.` est configuré + - Utile après une modification de l’envoi de workflow comfy, du polling, des téléchargements ou de l’enregistrement du Plugin ## Live génération d’image -- 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 : +- 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 fournisseur de génération d’image enregistré - - Charge les variables d’environnement 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 périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell - - Ignore les fournisseurs sans auth/profil/modèle exploitable - - Exécute les variantes standard de génération d’image via la capacité d’exécution partagée : + - Charge les variables d’environnement fournisseur manquantes depuis votre shell de connexion (`~/.profile`) avant les sondes + - Utilise par défaut les clés d’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 véritables identifiants du shell + - Ignore les fournisseurs sans authentification/profil/modèle utilisable + - Exécute les variantes standard de génération d’image via la capacité runtime partagée : - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Fournisseurs groupés actuellement couverts : +- Fournisseurs intégré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 basés sur l’environnement +- Comportement d’authentification facultatif : + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement fournis par l’environnement -## Live génération de musique +## Live 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é des fournisseurs de 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` +- Harnais : `pnpm test:live:media music` +- Portée : + - Exerce le chemin partagé intégré des fournisseurs de génération musicale - Couvre actuellement Google et MiniMax - - Charge les variables d’environnement 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 périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell - - Ignore les fournisseurs sans auth/profil/modèle exploitable - - Exécute les deux modes d’exécution déclarés lorsqu’ils sont disponibles : - - `generate` avec entrée uniquement textuelle + - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant les sondes + - Utilise par défaut les clés d’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 véritables 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 sous forme de prompt - `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 distinct, 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 basés sur l’environnement +- Comportement d’authentification facultatif : + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement fournis par l’environnement -## Live génération de vidéo +## Live génération vidéo -- 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é des fournisseurs de génération de vidéo - - Utilise par défaut le chemin de fumée sûr pour une release : fournisseurs hors FAL, une requête texte-vers-vidéo par fournisseur, une invite lobster d’une seconde, et une limite d’opération par fournisseur issue de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` par défaut) - - Ignore FAL par défaut car la latence de file d’attente côté fournisseur peut dominer le temps de release ; passez `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` pour l’exécuter explicitement - - Charge les variables d’environnement 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 périmées dans `auth-profiles.json` ne masquent pas de vrais identifiants du shell - - Ignore les fournisseurs sans auth/profil/modèle exploitable - - Exécute uniquement `generate` par défaut - - Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi les modes de transformation déclarés lorsqu’ils sont disponibles : - - `imageToVideo` lorsque le fournisseur déclare `capabilities.imageToVideo.enabled` et que le fournisseur/modèle sélectionné accepte dans le 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 dans le 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` car le `veo3` groupé est texte uniquement et le `kling` groupé nécessite 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 partagé intégré des fournisseurs de génération vidéo + - Utilise par défaut le chemin de test de fumée sûr pour la release : fournisseurs autres que FAL, une requête text-to-video par fournisseur, prompt lobster d’une seconde, et un plafond d’opération par fournisseur issu de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` par défaut) + - Ignore FAL par défaut, car la latence de file d’attente côté fournisseur peut dominer le temps de release ; passez `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` pour l’exécuter explicitement + - Charge les variables d’environnement fournisseur depuis votre shell de connexion (`~/.profile`) avant les sondes + - Utilise par défaut les clés d’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 véritables identifiants du shell + - Ignore les fournisseurs sans authentification/profil/modèle utilisable + - N’exécute que `generate` par défaut + - Définissez `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` pour exécuter aussi les modes de transformation déclarés lorsqu’ils sont disponibles : + - `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` intégré est uniquement texte et le `kling` intégré 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` 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` : + - ce fichier exécute `veo3` text-to-video ainsi qu’une voie `kling` qui utilise par défaut une fixture d’URL d’image distante + - Couverture live `videoToVideo` actuelle : - `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` car ces chemins nécessitent 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 le video inpaint/remix -- 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 partagée Gemini/Veo actuelle utilise une entrée locale adossée à un buffer, et ce chemin n’est pas accepté dans le balayage partagé + - `openai`, car la voie partagée actuelle ne garantit pas l’accès spécifique à l’organisation pour l’inpainting/remix vidéo +- Restriction facultative : - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` pour inclure chaque fournisseur dans le balayage par défaut, y compris FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` pour réduire la limite d’opération de chaque fournisseur lors d’une exécution de fumée agressive -- Comportement d’authentification facultatif : - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement basés sur l’environnement + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` pour inclure tous les fournisseurs dans le balayage par défaut, y compris FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` pour réduire le plafond d’opération de chaque fournisseur dans un test de fumée agressif +- Comportement d’authentification facultatif : + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour forcer l’authentification par magasin de profils et ignorer les remplacements uniquement fournis par l’environnement ## 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 unique natif du dépôt +- 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 fournisseur manquantes depuis `~/.profile` - - Restreint automatiquement par défaut chaque suite aux fournisseurs disposant actuellement d’une authentification exploitable - - Réutilise `scripts/test-live.mjs`, afin que le comportement Heartbeat et le mode silencieux restent cohérents -- Exemples : + - 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 de Heartbeat 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 répartissent en deux catégories : +Ces exécuteurs Docker se répartissent en deux catégories : -- Exécuteurs live de modèles : `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 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 Docker live utilisent par défaut un plafond de fumée plus petit afin 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 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 Docker live utilisent par défaut un plafond de test de fumée plus petit afin qu’un balayage Docker complet reste praticable : `test:docker:live-models` utilise par défaut `OPENCLAW_LIVE_MAX_MODELS=12`, et `test:docker:live-gateway` utilise par défaut `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, et `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Remplacez ces variables d’environnement lorsque vous - voulez explicitement lancer le balayage exhaustif plus large. -- `test:docker:all` construit l’image Docker live une fois via `test:docker:live-build`, puis la réutilise pour les deux voies Docker live. -- Exécuteurs de fumée en 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. + voulez explicitement le balayage exhaustif plus large. +- `test:docker:all` construit une fois l’image Docker live via `test:docker:live-build`, puis la réutilise pour les deux voies Docker live. +- Exécuteurs de test de fumée de conteneur : `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, et `test:docker:plugins` démarrent un ou plusieurs vrais conteneurs et vérifient des chemins d’intégration de plus haut niveau. -Les exécuteurs Docker live de modèles montent également en bind uniquement les répertoires d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le répertoire personnel du conteneur avant l’exécution afin que l’OAuth des CLI externes puisse rafraîchir les jetons sans modifier le magasin d’authentification de l’hôte : +Les exécuteurs Docker live-model montent aussi en bind uniquement les HOME d’authentification CLI nécessaires (ou tous ceux pris en charge lorsque l’exécution n’est pas restreinte), puis les copient dans le HOME du conteneur avant l’exécution afin que l’OAuth CLI externe puisse rafraîchir les jetons sans modifier le magasin d’authentification de l’hôte : -- Modèles directs : `pnpm test:docker:live-models` (script : `scripts/test-live-models-docker.sh`) -- Test de fumée de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`) -- Test de fumée du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) -- Test de fumée du harnais Codex app-server : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agent de développement : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`) -- Test de fumée 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 Gateway (deux conteneurs, authentification WS + état de santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) -- Pont de canal MCP (Gateway prérempli + pont stdio + test de fumée brut de trame de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (fumée 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`) +- Test de fumée de liaison ACP : `pnpm test:docker:live-acp-bind` (script : `scripts/test-live-acp-bind-docker.sh`) +- Test de fumée du backend CLI : `pnpm test:docker:live-cli-backend` (script : `scripts/test-live-cli-backend-docker.sh`) +- Test de fumée du harnais app-server Codex : `pnpm test:docker:live-codex-harness` (script : `scripts/test-live-codex-harness-docker.sh`) +- Gateway + agent de développement : `pnpm test:docker:live-gateway` (script : `scripts/test-live-gateway-models-docker.sh`) +- Test de fumée 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 Gateway (deux conteneurs, authentification WS + état de santé) : `pnpm test:docker:gateway-network` (script : `scripts/e2e/gateway-network-docker.sh`) +- Pont de canal MCP (Gateway initialisé + pont stdio + test de fumée brut de trame de notification Claude) : `pnpm test:docker:mcp-channels` (script : `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (test de fumée 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 de modèles montent aussi en bind le checkout courant en lecture seule et -le préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image d’exécution +Les exécuteurs Docker live-model montent aussi en bind le clone courant en lecture seule et +le préparent dans un répertoire de travail temporaire à l’intérieur du conteneur. Cela garde l’image runtime légère tout en exécutant Vitest sur votre source/config locale exacte. -L’étape de préparation ignore les gros caches strictement locaux et les sorties de build d’applications telles que -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires `.build` locaux aux applications ou -les répertoires de sortie Gradle, afin que les exécutions Docker live ne passent pas des minutes à copier -des artefacts spécifiques à la machine. +L’étape de préparation ignore les gros caches uniquement locaux et les sorties de build d’app comme +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, ainsi que les répertoires `.build` locaux à l’app ou les sorties +Gradle, afin que les exécutions Docker live ne passent pas des minutes à copier +des artefacts propres à la machine. Ils définissent aussi `OPENCLAW_SKIP_CHANNELS=1` afin que les sondes live Gateway ne démarrent pas -de vrais workers de canaux Telegram/Discord/etc. dans le conteneur. -`test:docker:live-models` exécute toujours `pnpm test:live`, donc transmettez aussi -`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture -live Gateway de cette voie Docker. -`test:docker:openwebui` est un test de fumée de compatibilité de plus haut niveau : il démarre un +de vrais workers de canal Telegram/Discord/etc. à l’intérieur du conteneur. +`test:docker:live-models` exécute toujours `pnpm test:live`, alors transmettez aussi +`OPENCLAW_LIVE_GATEWAY_*` lorsque vous devez restreindre ou exclure la couverture live +Gateway de cette voie Docker. +`test:docker:openwebui` est un test de fumée de compatibilité de plus haut niveau : il démarre un conteneur Gateway OpenClaw avec les points de terminaison HTTP compatibles OpenAI activés, -démarre un conteneur Open WebUI épinglé contre cette Gateway, se connecte via +démarre un conteneur Open WebUI épinglé contre ce Gateway, se connecte via Open WebUI, vérifie que `/api/models` expose `openclaw/default`, puis envoie une vraie requête de chat via le proxy `/api/chat/completions` d’Open WebUI. -La première exécution peut être sensiblement plus lente car Docker peut devoir récupérer l’image -Open WebUI et Open WebUI peut devoir terminer son propre 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. +La première exécution peut être sensiblement plus lente, car Docker peut devoir extraire +l’image Open WebUI et Open WebUI peut devoir terminer sa propre configuration de démarrage à froid. +Cette voie attend une clé de modèle live utilisable, et `OPENCLAW_PROFILE_FILE` +(`~/.profile` par défaut) est le principal moyen de la fournir dans les exécutions sous Docker. 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 -prérempli, lance un second conteneur qui exécute `openclaw mcp serve`, puis -vérifie la découverte de conversations routées, les lectures de transcription, les métadonnées de pièces jointes, -le comportement de la file d’événements live, le routage des envois sortants, ainsi que les notifications -de canal + permissions de type Claude via le vrai pont MCP stdio. La vérification de notification -inspecte directement les trames MCP stdio brutes afin que le test de fumée valide ce que -le pont émet réellement, et pas seulement ce qu’un SDK client particulier choisit d’exposer. +véritable compte Telegram, Discord ou iMessage. Il démarre un conteneur Gateway +initialisé, lance un second conteneur qui démarre `openclaw mcp serve`, puis +vérifie la découverte de conversation routée, les lectures de transcriptions, les métadonnées de pièces jointes, +le comportement de la file d’événements live, le routage des envois sortants, et les notifications de canal + +permissions de style Claude via le véritable pont stdio MCP. La vérification des notifications +inspecte directement les trames MCP stdio brutes afin que le test de fumée valide ce que le +pont émet réellement, et pas seulement ce qu’un SDK client particulier choisit d’exposer. -Test manuel ACP de fil en langage naturel (hors CI) : +Test manuel ACP de thread en langage naturel (hors CI) : - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conservez ce script pour les workflows de régression/débogage. Il pourra être de nouveau nécessaire pour la validation du routage de fils 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 des threads ACP, donc ne le supprimez pas. -Variables d’environnement utiles : +Variables d’environnement utiles : -- `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté sur `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté sur `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté sur `/home/node/.profile` et chargé avant l’exécution des tests -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement chargées depuis `OPENCLAW_PROFILE_FILE`, avec des répertoires temporaires de config/espace de travail et sans montage d’authentification CLI externe -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour les installations CLI mises en cache dans Docker -- Les répertoires/fichiers d’authentification CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés vers `/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` +- `OPENCLAW_CONFIG_DIR=...` (par défaut : `~/.openclaw`) monté sur `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (par défaut : `~/.openclaw/workspace`) monté sur `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (par défaut : `~/.profile`) monté sur `/home/node/.profile` et chargé avant l’exécution des tests +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` pour vérifier uniquement les variables d’environnement chargées depuis `OPENCLAW_PROFILE_FILE`, avec des répertoires config/workspace temporaires et sans montage d’authentification CLI externe +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (par défaut : `~/.cache/openclaw/docker-cli-tools`) monté sur `/home/node/.npm-global` pour les installations CLI mises en cache dans Docker +- Les répertoires/fichiers d’authentification CLI externes sous `$HOME` sont montés en lecture seule sous `/host-auth...`, puis copiés dans `/home/node/...` avant le démarrage des tests + - Répertoires par défaut : `.minimax` + - Fichiers par défaut : `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Les exécutions restreintes par fournisseur ne montent que les répertoires/fichiers nécessaires déduits de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - 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` + - 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_SKIP_DOCKER_BUILD=1` pour réutiliser une image `openclaw:local-live` existante lors de relances ne nécessitant pas de reconstruction - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` pour garantir que les identifiants proviennent du magasin de profils (et non de l’environnement) -- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par la Gateway pour le test de fumée Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer l’invite de vérification par nonce utilisée par le test de fumée Open WebUI -- `OPENWEBUI_IMAGE=...` pour remplacer la balise d’image Open WebUI épinglée +- `OPENCLAW_OPENWEBUI_MODEL=...` pour choisir le modèle exposé par le Gateway pour le test de fumée Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` pour remplacer le prompt de vérification de nonce utilisé par le test de fumée Open WebUI +- `OPENWEBUI_IMAGE=...` pour remplacer le tag d’image Open WebUI épinglé ## Vérification de cohérence de la documentation -Exécutez les vérifications de documentation après des modifications de doc : `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`. +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 des vérifications d’en-têtes dans la page : `pnpm docs:check-links:anchors`. ## Régression hors ligne (compatible CI) -Il s’agit de régressions en « pipeline réel » sans vrais fournisseurs : +Voici des régressions de « pipeline réel » sans vrais fournisseurs : -- Appel d’outils Gateway (OpenAI simulé, vraie boucle Gateway + agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistant Gateway (WS `wizard.start`/`wizard.next`, écriture de config + auth imposée) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") +- Appel d’outil Gateway (mock OpenAI, vraie boucle Gateway + agent) : `src/gateway/gateway.test.ts` (cas : "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistant Gateway (WS `wizard.start`/`wizard.next`, écrit config + auth imposées) : `src/gateway/gateway.test.ts` (cas : "runs wizard over ws and writes auth token config") -## Évaluations de fiabilité de l’agent (Skills) +## Évaluations de fiabilité d’agent (Skills) -Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité de l’agent » : +Nous avons déjà quelques tests compatibles CI qui se comportent comme des « évaluations de fiabilité d’agent » : -- Appel d’outils simulé via la vraie boucle Gateway + agent (`src/gateway/gateway.test.ts`). +- Appel d’outil simulé via la vraie boucle Gateway + 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 l’invite, l’agent choisit-il la bonne Skill (ou évite-t-il les Skills non pertinentes) ? -- **Conformité :** l’agent lit-il `SKILL.md` avant usage et suit-il les étapes/arguments 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. +- **Décision :** lorsque des Skills sont listées dans le prompt, l’agent choisit-il la bonne Skill (ou évite-t-il celles qui ne sont pas pertinentes) ? +- **Conformité :** l’agent lit-il `SKILL.md` avant usage 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 sandbox. -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 de Skill et le câblage de session. -- Une petite suite de scénarios centrés sur les Skills (utiliser vs éviter, contrôles, injection d’invite). -- Des évaluations live facultatives (sur activation, protégées par variables d’environnement) uniquement après la mise en place de la suite compatible CI. +- Un exécuteur de scénarios utilisant des fournisseurs simulés pour vérifier les appels d’outils + leur ordre, la lecture des fichiers de Skills et le câblage de session. +- Une petite suite de scénarios centrés sur les Skills (utiliser vs éviter, contrôles, injection de prompt). +- Des évaluations live facultatives (opt-in, contrôlées par l’environnement) uniquement après la mise en place de la suite compatible CI. -## Tests de contrat (forme des Plugins et des canaux) +## Tests de contrat (forme 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 -vérifications de forme et de comportement. La voie unitaire par défaut `pnpm test` -ignore volontairement ces fichiers partagés de joints et de fumée ; exécutez les commandes de contrat explicitement -lorsque vous modifiez des surfaces partagées de canal ou de fournisseur. +contrat d’interface. Ils parcourent tous les Plugins découverts et exécutent une suite de +vérifications de forme et de comportement. La voie unitaire `pnpm test` par défaut +ignore volontairement ces fichiers de couture partagée et de tests de fumée ; exécutez les commandes de contrat explicitement +lorsque vous touchez à des surfaces partagées de canal ou de fournisseur. ### Commandes -- Tous les contrats : `pnpm test:contracts` -- Contrats de canaux uniquement : `pnpm test:contracts:channels` -- Contrats de fournisseurs uniquement : `pnpm test:contracts:plugins` +- Tous les contrats : `pnpm test:contracts` +- Contrats de canaux uniquement : `pnpm test:contracts:channels` +- Contrats de fournisseurs uniquement : `pnpm test:contracts:plugins` ### Contrats de canaux -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 - **session-binding** - Comportement de liaison de session - **outbound-payload** - Structure de charge utile des messages - **inbound** - Gestion des messages entrants -- **actions** - Gestionnaires d’actions de canal -- **threading** - Gestion des identifiants de fil -- **directory** - API d’annuaire/de liste +- **actions** - Gestionnaires d’actions du canal +- **threading** - Gestion de l’identifiant de fil +- **directory** - API de répertoire/liste des membres - **group-policy** - Application de la politique de groupe ### Contrats d’état des fournisseurs Situés dans `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondes d’état des canaux +- **status** - Sondes d’état du canal - **registry** - Forme du registre de Plugins ### Contrats de fournisseurs -Situés dans `src/plugins/contracts/*.contract.test.ts` : +Situés dans `src/plugins/contracts/*.contract.test.ts` : -- **auth** - Contrat de flux d’authentification -- **auth-choice** - Choix/sélection de l’authentification +- **auth** - Contrat du flux d’authentification +- **auth-choice** - Choix/sélection d’authentification - **catalog** - API du catalogue de modèles -- **discovery** - Découverte des Plugins -- **loader** - Chargement des Plugins -- **runtime** - Exécution du fournisseur +- **discovery** - Découverte de Plugins +- **loader** - Chargement de Plugins +- **runtime** - Runtime du fournisseur - **shape** - Forme/interface du Plugin - **wizard** - Assistant de configuration ### Quand les exécuter -- Après modification des exportations ou sous-chemins de `plugin-sdk` -- Après ajout ou modification d’un Plugin de canal ou de fournisseur -- Après refactorisation de l’enregistrement ou de la découverte des Plugins +- Après avoir modifié des exportations ou sous-chemins de `plugin-sdk` +- Après avoir ajouté ou modifié un Plugin de canal ou de fournisseur +- Après avoir refactorisé l’enregistrement ou la découverte de Plugins -Les tests de contrat s’exécutent 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 d’API. ## 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 compatible CI (fournisseur simulé/substitué, ou capture de la transformation exacte de forme de requête) -- Si le problème est intrinsèquement limité au live (limitations de débit, politiques d’authentification), gardez le test live étroit et activé sur demande 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 Gateway session/historique/outils → test de fumée live Gateway ou test simulé Gateway 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 depuis les métadonnées du registre (`listSecretTargetRegistryEntries()`), puis vérifie que les identifiants exec de segment de parcours sont rejetés. +- Ajoutez si possible une régression compatible CI (fournisseur simulé/stub, ou capture exacte de la transformation de forme de requête) +- Si le problème est intrinsèquement limité au live (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 bug : + - bug de conversion/rejeu de requête fournisseur → test direct des modèles + - bug du pipeline de session/historique/outils Gateway → test de fumée Gateway live ou test simulé Gateway 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 segment 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 classés afin que de nouvelles classes ne puissent pas être ignorées silencieusement. diff --git a/docs/fr/platforms/macos.md b/docs/fr/platforms/macos.md index e6097f07b..591bd8621 100644 --- a/docs/fr/platforms/macos.md +++ b/docs/fr/platforms/macos.md @@ -1,76 +1,76 @@ --- read_when: - - Implémenter des fonctionnalités de l'application macOS - - Modifier le cycle de vie de la gateway ou le pontage de nœud sur macOS -summary: Application compagnon OpenClaw pour macOS (barre de menus + courtier gateway) -title: Application macOS + - Implémentation des fonctionnalités de l’app macOS + - Modification du cycle de vie de Gateway ou du pontage des nœuds sur macOS +summary: Application compagnon macOS OpenClaw (barre des menus + broker Gateway) +title: App macOS x-i18n: - generated_at: "2026-04-05T12:49:16Z" + generated_at: "2026-04-18T06:43:38Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# Application compagnon OpenClaw pour macOS (barre de menus + courtier gateway) +# Companion macOS OpenClaw (barre des menus + broker Gateway) -L'application macOS est le **compagnon de barre de menus** d'OpenClaw. Elle gère les autorisations, -gère/se rattache à la gateway localement (launchd ou manuel), et expose les capacités -macOS à l'agent comme un nœud. +L’app macOS est le **compagnon de barre des menus** pour OpenClaw. Elle gère les autorisations, +gère/se connecte au Gateway localement (launchd ou manuel), et expose les capacités macOS +à l’agent en tant que nœud. -## Ce qu'elle fait +## Ce qu’elle fait -- Affiche des notifications natives et l'état dans la barre de menus. -- Gère les invites TCC (Notifications, Accessibilité, Enregistrement d'écran, Microphone, +- Affiche des notifications natives et l’état dans la barre des menus. +- Gère les invites TCC (Notifications, Accessibilité, Enregistrement de l’écran, Microphone, Reconnaissance vocale, Automation/AppleScript). -- Exécute ou connecte la gateway (locale ou distante). -- Expose des outils propres à macOS (Canvas, caméra, enregistrement d'écran, `system.run`). -- Démarre le service hôte de nœud local en mode **remote** (launchd), et l'arrête en mode **local**. -- Peut éventuellement héberger **PeekabooBridge** pour l'automatisation de l'interface. -- Installe la CLI globale (`openclaw`) sur demande via npm, pnpm ou bun (l'application préfère npm, puis pnpm, puis bun ; Node reste le runtime recommandé pour la gateway). +- Exécute ou se connecte au Gateway (local ou distant). +- Expose des outils propres à macOS (Canvas, Caméra, Enregistrement de l’écran, `system.run`). +- Démarre le service hôte de nœud local en mode **distant** (launchd), et l’arrête en mode **local**. +- Peut héberger **PeekabooBridge** pour l’automatisation de l’interface utilisateur. +- Installe la CLI globale (`openclaw`) à la demande via npm, pnpm ou bun (l’app préfère npm, puis pnpm, puis bun ; Node reste l’environnement d’exécution recommandé pour Gateway). ## Mode local vs distant -- **Local** (par défaut) : l'application se rattache à une gateway locale déjà en cours d'exécution si elle existe ; +- **Local** (par défaut) : l’app se connecte à un Gateway local en cours d’exécution s’il est présent ; sinon elle active le service launchd via `openclaw gateway install`. -- **Remote** : l'application se connecte à une gateway via SSH/Tailscale et ne démarre jamais +- **Distant** : l’app se connecte à un Gateway via SSH/Tailscale et ne démarre jamais de processus local. - L'application démarre le **service hôte de nœud** local afin que la gateway distante puisse atteindre ce Mac. - L'application ne lance pas la gateway comme processus enfant. - La découverte de la gateway préfère désormais les noms Tailscale MagicDNS aux IP tailnet brutes, - de sorte que l'application Mac se rétablit plus fiablement lorsque les IP tailnet changent. + L’app démarre le **service hôte de nœud** local afin que le Gateway distant puisse atteindre ce Mac. + L’app ne lance pas le Gateway comme processus enfant. + La découverte de Gateway privilégie désormais les noms Tailscale MagicDNS plutôt que les IP tailnet brutes, + afin que l’app Mac se rétablisse plus fiablement lorsque les IP tailnet changent. ## Contrôle Launchd -L'application gère un LaunchAgent par utilisateur étiqueté `ai.openclaw.gateway` -(ou `ai.openclaw.` lors de l'utilisation de `--profile`/`OPENCLAW_PROFILE` ; l'ancien `com.openclaw.*` continue d'être déchargé). +L’app gère un LaunchAgent par utilisateur libellé `ai.openclaw.gateway` +(ou `ai.openclaw.` lors de l’utilisation de `--profile`/`OPENCLAW_PROFILE` ; l’ancien `com.openclaw.*` se décharge toujours). ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` -Remplacez le label par `ai.openclaw.` lors de l'exécution d'un profil nommé. +Remplacez le libellé par `ai.openclaw.` lors de l’exécution avec un profil nommé. -Si le LaunchAgent n'est pas installé, activez-le depuis l'application ou exécutez +Si le LaunchAgent n’est pas installé, activez-le depuis l’app ou exécutez `openclaw gateway install`. -## Capacités du nœud (Mac) +## Capacités du nœud (mac) -L'application macOS se présente comme un nœud. Commandes courantes : +L’app macOS se présente comme un nœud. Commandes courantes : - Canvas : `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` - Caméra : `camera.snap`, `camera.clip` -- Écran : `screen.record` +- Écran : `screen.snapshot`, `screen.record` - Système : `system.run`, `system.notify` -Le nœud signale une map `permissions` afin que les agents puissent décider de ce qui est autorisé. +Le nœud rapporte une map `permissions` afin que les agents puissent déterminer ce qui est autorisé. -Service de nœud + IPC d'application : +Service de nœud + IPC de l’app : -- Lorsque le service hôte de nœud headless est en cours d'exécution (mode remote), il se connecte à la gateway WS comme nœud. -- `system.run` s'exécute dans l'application macOS (contexte UI/TCC) via un socket Unix local ; les invites et la sortie restent dans l'application. +- Lorsque le service hôte de nœud sans interface est en cours d’exécution (mode distant), il se connecte au Gateway WS en tant que nœud. +- `system.run` s’exécute dans l’app macOS (contexte UI/TCC) via un socket Unix local ; les invites et la sortie restent dans l’app. Schéma (SCI) : @@ -81,10 +81,10 @@ Gateway -> Node Service (WS) Mac App (UI + TCC + system.run) ``` -## Approbations Exec (`system.run`) +## Approbations d’exécution (system.run) -`system.run` est contrôlé par les **approbations Exec** dans l'application macOS (Settings → Exec approvals). -La sécurité + la demande + la liste d'autorisation sont stockées localement sur le Mac dans : +`system.run` est contrôlé par les **approbations d’exécution** dans l’app macOS (Réglages → Approbations d’exécution). +La sécurité + la demande + la liste d’autorisation sont stockées localement sur le Mac dans : ``` ~/.openclaw/exec-approvals.json @@ -111,20 +111,20 @@ Exemple : Remarques : -- Les entrées `allowlist` sont des motifs glob pour les chemins binaires résolus. -- Le texte brut de commande shell contenant une syntaxe de contrôle ou d'expansion shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance dans la liste d'autorisation et nécessite une approbation explicite (ou l'ajout du binaire shell à la liste d'autorisation). -- Choisir « Always Allow » dans l'invite ajoute cette commande à la liste d'autorisation. -- Les remplacements d'environnement de `system.run` sont filtrés (supprime `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) puis fusionnés avec l'environnement de l'application. -- Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les remplacements d'environnement limités à la requête sont réduits à une petite liste d'autorisation explicite (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -- Pour les décisions d'autorisation permanente en mode allowlist, les wrappers de répartition connus (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistent les chemins exécutables internes plutôt que les chemins des wrappers. Si le déballage n'est pas sûr, aucune entrée de liste d'autorisation n'est persistée automatiquement. +- Les entrées `allowlist` sont des motifs glob pour les chemins de binaires résolus. +- Le texte brut d’une commande shell qui contient une syntaxe de contrôle ou d’expansion shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance de liste d’autorisation et nécessite une approbation explicite (ou l’ajout du binaire shell à la liste d’autorisation). +- Choisir « Toujours autoriser » dans l’invite ajoute cette commande à la liste d’autorisation. +- Les remplacements d’environnement de `system.run` sont filtrés (supprime `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) puis fusionnés avec l’environnement de l’app. +- Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les remplacements d’environnement propres à la requête sont réduits à une petite liste d’autorisation explicite (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +- Pour les décisions toujours autoriser en mode liste d’autorisation, les wrappers de distribution connus (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) conservent les chemins des exécutables internes au lieu des chemins des wrappers. Si le déballage n’est pas sûr, aucune entrée de liste d’autorisation n’est automatiquement conservée. ## Liens profonds -L'application enregistre le schéma d'URL `openclaw://` pour les actions locales. +L’app enregistre le schéma d’URL `openclaw://` pour les actions locales. ### `openclaw://agent` -Déclenche une requête `agent` vers la gateway. +Déclenche une requête Gateway `agent`. __OC_I18N_900004__ Paramètres de requête : @@ -133,28 +133,28 @@ Paramètres de requête : - `thinking` (facultatif) - `deliver` / `to` / `channel` (facultatif) - `timeoutSeconds` (facultatif) -- `key` (facultatif, clé de mode sans supervision) +- `key` (facultatif, clé pour le mode sans surveillance) Sécurité : -- Sans `key`, l'application demande une confirmation. -- Sans `key`, l'application impose une limite courte de longueur de message pour l'invite de confirmation et ignore `deliver` / `to` / `channel`. -- Avec une `key` valide, l'exécution est sans supervision (prévue pour des automatisations personnelles). +- Sans `key`, l’app demande une confirmation. +- Sans `key`, l’app applique une limite courte de message pour l’invite de confirmation et ignore `deliver` / `to` / `channel`. +- Avec une `key` valide, l’exécution se fait sans surveillance (prévu pour des automatisations personnelles). -## Flux d'onboarding (typique) +## Flux d’intégration (typique) 1. Installez et lancez **OpenClaw.app**. 2. Complétez la liste de vérification des autorisations (invites TCC). -3. Assurez-vous que le mode **Local** est actif et que la gateway est en cours d'exécution. -4. Installez la CLI si vous souhaitez un accès terminal. +3. Assurez-vous que le mode **Local** est actif et que le Gateway est en cours d’exécution. +4. Installez la CLI si vous souhaitez un accès au terminal. -## Emplacement du répertoire d'état (macOS) +## Emplacement du répertoire d’état (macOS) -Évitez de placer votre répertoire d'état OpenClaw dans iCloud ou dans d'autres dossiers synchronisés dans le cloud. -Les chemins adossés à une synchronisation peuvent ajouter de la latence et provoquer occasionnellement des courses de verrouillage/synchronisation de fichiers pour +Évitez de placer votre répertoire d’état OpenClaw dans iCloud ou dans d’autres dossiers synchronisés dans le cloud. +Les chemins pris en charge par la synchronisation peuvent ajouter de la latence et provoquer occasionnellement des courses de verrouillage/synchronisation de fichiers pour les sessions et les identifiants. -Préférez un chemin d'état local non synchronisé tel que : +Préférez un chemin d’état local non synchronisé tel que : __OC_I18N_900005__ Si `openclaw doctor` détecte un état sous : @@ -167,56 +167,56 @@ il affichera un avertissement et recommandera de revenir à un chemin local. - `cd apps/macos && swift build` - `swift run OpenClaw` (ou Xcode) -- Packager l'application : `scripts/package-mac-app.sh` +- Packager l’app : `scripts/package-mac-app.sh` -## Déboguer la connectivité gateway (CLI macOS) +## Déboguer la connectivité Gateway (CLI macOS) -Utilisez la CLI de débogage pour exercer la même poignée de main WebSocket gateway et la même logique de découverte -que l'application macOS, sans lancer l'application. +Utilisez la CLI de débogage pour exercer la même poignée de main WebSocket Gateway et la même logique de découverte +que l’app macOS, sans lancer l’app. __OC_I18N_900006__ Options de connexion : -- `--url ` : remplace la configuration -- `--mode ` : résout à partir de la configuration (par défaut : config ou local) -- `--probe` : force une nouvelle sonde d'état -- `--timeout ` : délai de requête (par défaut : `15000`) -- `--json` : sortie structurée pour comparaison +- `--url ` : remplace la config +- `--mode ` : résout à partir de la config (par défaut : config ou local) +- `--probe` : force une nouvelle sonde d’état +- `--timeout ` : délai d’expiration de la requête (par défaut : `15000`) +- `--json` : sortie structurée pour les comparaisons Options de découverte : -- `--include-local` : inclure les gateways qui seraient filtrées comme « local » +- `--include-local` : inclut les gateways qui seraient filtrés comme « locaux » - `--timeout ` : fenêtre globale de découverte (par défaut : `2000`) -- `--json` : sortie structurée pour comparaison +- `--json` : sortie structurée pour les comparaisons -Astuce : comparez avec `openclaw gateway discover --json` pour voir si le -pipeline de découverte de l'application macOS (`local.` plus le domaine wide-area configuré, avec -des replis wide-area et Tailscale Serve) diffère de +Astuce : comparez avec `openclaw gateway discover --json` pour voir si le pipeline de découverte +de l’app macOS (`local.` plus le domaine étendu configuré, avec +des solutions de repli wide-area et Tailscale Serve) diffère de la découverte basée sur `dns-sd` de la CLI Node. -## Plomberie de connexion distante (tunnels SSH) +## Plomberie des connexions distantes (tunnels SSH) -Lorsque l'application macOS fonctionne en mode **Remote**, elle ouvre un tunnel SSH afin que les composants UI locaux -puissent communiquer avec une gateway distante comme si elle était sur localhost. +Lorsque l’app macOS s’exécute en mode **distant**, elle ouvre un tunnel SSH afin que les composants de l’interface locale +puissent communiquer avec un Gateway distant comme s’il était sur localhost. -### Tunnel de contrôle (port WebSocket gateway) +### Tunnel de contrôle (port WebSocket Gateway) -- **Objectif :** vérifications d'état, status, Web Chat, configuration et autres appels du plan de contrôle. -- **Port local :** le port gateway (par défaut `18789`), toujours stable. -- **Port distant :** le même port gateway sur l'hôte distant. -- **Comportement :** pas de port local aléatoire ; l'application réutilise un tunnel sain existant +- **But :** contrôles d’état, statut, Chat Web, config et autres appels du plan de contrôle. +- **Port local :** le port Gateway (par défaut `18789`), toujours stable. +- **Port distant :** le même port Gateway sur l’hôte distant. +- **Comportement :** pas de port local aléatoire ; l’app réutilise un tunnel sain existant ou le redémarre si nécessaire. -- **Forme SSH :** `ssh -N -L :127.0.0.1:` avec BatchMode + - ExitOnForwardFailure + options de keepalive. -- **Remontée d'IP :** le tunnel SSH utilise loopback, donc la gateway verra l'IP du nœud - comme `127.0.0.1`. Utilisez le transport **Direct (ws/wss)** si vous souhaitez que la véritable - IP cliente apparaisse (voir [accès distant macOS](/platforms/mac/remote)). +- **Forme SSH :** `ssh -N -L :127.0.0.1:` avec les options BatchMode + + ExitOnForwardFailure + keepalive. +- **Rapport d’IP :** le tunnel SSH utilise le loopback, donc le gateway verra l’IP du nœud + comme `127.0.0.1`. Utilisez le transport **Direct (ws/wss)** si vous souhaitez que la véritable IP + cliente apparaisse (voir [accès distant macOS](/fr/platforms/mac/remote)). -Pour les étapes de configuration, voir [accès distant macOS](/platforms/mac/remote). Pour les détails -du protocole, voir [Protocole de la gateway](/gateway/protocol). +Pour les étapes de configuration, voir [accès distant macOS](/fr/platforms/mac/remote). Pour les détails +du protocole, voir [protocole Gateway](/fr/gateway/protocol). ## Documentation associée -- [Runbook gateway](/gateway) -- [Gateway (macOS)](/platforms/mac/bundled-gateway) -- [Autorisations macOS](/platforms/mac/permissions) -- [Canvas](/platforms/mac/canvas) +- [Runbook Gateway](/fr/gateway) +- [Gateway (macOS)](/fr/platforms/mac/bundled-gateway) +- [Autorisations macOS](/fr/platforms/mac/permissions) +- [Canvas](/fr/platforms/mac/canvas) diff --git a/docs/fr/plugins/sdk-channel-plugins.md b/docs/fr/plugins/sdk-channel-plugins.md index 2a7bc9006..27d28ea81 100644 --- a/docs/fr/plugins/sdk-channel-plugins.md +++ b/docs/fr/plugins/sdk-channel-plugins.md @@ -5,119 +5,110 @@ read_when: - Vous devez comprendre la surface d’adaptation de ChannelPlugin sidebarTitle: Channel Plugins summary: Guide étape par étape pour créer un Plugin de canal de messagerie pour OpenClaw -title: Créer des Plugins de canal +title: Création de Plugins de canal x-i18n: - generated_at: "2026-04-15T19:41:43Z" + generated_at: "2026-04-18T06:44:10Z" model: gpt-5.4 provider: openai - source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b + source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Créer des Plugins de canal +# Création de Plugins de canal Ce guide explique comment créer un Plugin de canal qui connecte OpenClaw à une -plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec -la sécurité des messages privés, l’appairage, le fil de réponse et la -messagerie sortante. +plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec sécurité des DM, +pairing, threading des réponses et messagerie sortante. - Si vous n’avez encore jamais créé de Plugin OpenClaw, lisez d’abord - [Getting Started](/fr/plugins/building-plugins) pour comprendre la structure de - package de base et la configuration du manifeste. + Si vous n’avez encore créé aucun Plugin OpenClaw, lisez d’abord + [Getting Started](/fr/plugins/building-plugins) pour la structure de package + de base et la configuration du manifeste. ## Fonctionnement des Plugins de canal -Les Plugins de canal n’ont pas besoin de leurs propres outils send/edit/react. -OpenClaw conserve un seul outil `message` partagé dans le cœur. Votre Plugin -gère : +Les Plugins de canal n’ont pas besoin de leurs propres outils d’envoi/édition/réaction. OpenClaw conserve un +outil `message` partagé dans le cœur. Votre Plugin prend en charge : -- **Configuration** — résolution du compte et assistant de configuration -- **Sécurité** — politique des messages privés et listes d’autorisation -- **Appairage** — flux d’approbation des messages privés -- **Grammaire de session** — comment les identifiants de conversation spécifiques au fournisseur sont mappés vers les discussions de base, les identifiants de fil et les solutions de repli parent +- **Configuration** — résolution de compte et assistant de configuration +- **Sécurité** — politique DM et listes d’autorisation +- **Pairing** — flux d’approbation DM +- **Grammaire de session** — comment les identifiants de conversation spécifiques au provider se mappent aux chats de base, aux identifiants de thread et aux solutions de repli parent - **Sortant** — envoi de texte, de médias et de sondages vers la plateforme -- **Fil de discussion** — comment les réponses sont organisées en fil +- **Threading** — comment les réponses sont threadées -Le cœur gère l’outil de message partagé, le câblage des prompts, la forme -externe de la clé de session, le suivi générique `:thread:` et la répartition. +Le cœur prend en charge l’outil de message partagé, le câblage du prompt, la forme externe de la clé de session, +la tenue générique des registres `:thread:` et la répartition. -Si votre canal ajoute des paramètres d’outil de message qui transportent des -sources de médias, exposez ces noms de paramètres via -`describeMessageTool(...).mediaSourceParams`. Le cœur utilise -cette liste explicite pour la normalisation des chemins du bac à sable et la -politique d’accès aux médias sortants. Les Plugins n’ont donc pas besoin de cas -particuliers dans le cœur partagé pour les paramètres spécifiques au -fournisseur, comme l’avatar, les pièces jointes ou l’image de couverture. -Préférez renvoyer une map indexée par action, comme -`{ "set-profile": ["avatarUrl", "avatarPath"] }`, afin que des actions sans -rapport n’héritent pas des arguments média d’une autre action. Un tableau plat -fonctionne également pour des paramètres volontairement partagés par toutes les -actions exposées. +Si votre canal ajoute des paramètres d’outil de message qui transportent des sources média, exposez ces +noms de paramètres via `describeMessageTool(...).mediaSourceParams`. Le cœur utilise +cette liste explicite pour la normalisation des chemins du sandbox et la politique d’accès +aux médias sortants, afin que les Plugins n’aient pas besoin de cas particuliers dans le cœur partagé pour les paramètres +spécifiques au provider comme avatar, pièce jointe ou image de couverture. +Préférez renvoyer une map indexée par action comme +`{ "set-profile": ["avatarUrl", "avatarPath"] }` afin que des actions sans rapport n’héritent pas +des arguments média d’une autre action. Un tableau plat fonctionne toujours pour les paramètres +qui sont volontairement partagés par chaque action exposée. -Si votre plateforme stocke une portée supplémentaire dans les identifiants de -conversation, conservez cette logique d’analyse dans le Plugin avec -`messaging.resolveSessionConversation(...)`. Il s’agit du hook canonique pour -mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil -facultatif, l’éventuel `baseConversationId` et tous les -`parentConversationCandidates`. -Lorsque vous renvoyez `parentConversationCandidates`, gardez-les ordonnés du -parent le plus spécifique au parent le plus large ou à la conversation de base. +Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, gardez cette logique d’analyse +dans le Plugin avec `messaging.resolveSessionConversation(...)`. C’est le hook canonique +pour mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de thread optionnel, +`baseConversationId` explicite et tout `parentConversationCandidates`. +Lorsque vous renvoyez `parentConversationCandidates`, conservez-les ordonnés +du parent le plus étroit au parent le plus large / à la conversation de base. -Les Plugins intégrés qui ont besoin de la même analyse avant le démarrage du -registre de canaux peuvent aussi exposer un fichier `session-key-api.ts` de -niveau supérieur avec un export `resolveSessionConversation(...)` -correspondant. Le cœur utilise cette surface sûre pour l’amorçage uniquement -lorsque le registre de Plugin d’exécution n’est pas encore disponible. +Les Plugins intégrés qui ont besoin de la même logique d’analyse avant +le démarrage du registre de canal peuvent aussi exposer un fichier `session-key-api.ts` +de niveau supérieur avec une exportation correspondante +`resolveSessionConversation(...)`. Le cœur utilise cette surface sûre pour l’amorçage +uniquement lorsque le registre de Plugin d’exécution n’est pas encore disponible. -`messaging.resolveParentConversationCandidates(...)` reste disponible comme -solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin que de -solutions de repli parent au-dessus de l’identifiant générique ou brut. Si les -deux hooks existent, le cœur utilise d’abord -`resolveSessionConversation(...).parentConversationCandidates` et ne se rabat -sur `resolveParentConversationCandidates(...)` que lorsque le hook canonique ne -les fournit pas. +`messaging.resolveParentConversationCandidates(...)` reste disponible comme solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin +que de solutions de repli parent en plus de l’identifiant générique/brut. Si les deux hooks existent, le cœur utilise +d’abord `resolveSessionConversation(...).parentConversationCandidates` et ne +revient à `resolveParentConversationCandidates(...)` que si le hook canonique +les omet. -## Approbations et capacités des canaux +## Approbations et capacités de canal -La plupart des Plugins de canal n’ont pas besoin de code spécifique aux -approbations. +La plupart des Plugins de canal n’ont pas besoin de code spécifique aux approbations. -- Le cœur gère `/approve` dans la même discussion, les charges utiles de bouton d’approbation partagées et la livraison de repli générique. -- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal nécessite un comportement spécifique aux approbations. -- `ChannelPlugin.approvals` a été supprimé. Placez les informations de livraison, native, rendu et authentification des approbations dans `approvalCapability`. -- `plugin.auth` est réservé à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation depuis cet objet. -- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la jonction canonique pour l’authentification des approbations. -- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans la même discussion. -- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface initiatrice ou du client natif lorsqu’il diffère de l’authentification d’approbation dans la même discussion. Le cœur utilise ce hook spécifique à l’exécution pour distinguer `enabled` et `disabled`, décider si le canal initiateur prend en charge les approbations d’exécution natives et inclure le canal dans les indications de repli du client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit ce rôle pour le cas courant. -- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, comme masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison. -- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression du repli. -- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation native gérées par le canal. Gardez-le paresseux sur les points d’entrée critiques du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module d’exécution à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations. +- Le cœur prend en charge `/approve` dans le même chat, les charges utiles de bouton d’approbation partagées et la livraison générique de secours. +- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal a besoin d’un comportement spécifique aux approbations. +- `ChannelPlugin.approvals` est supprimé. Placez les faits de livraison/native/render/auth des approbations dans `approvalCapability`. +- `plugin.auth` est réservé à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation à partir de cet objet. +- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la surface canonique pour l’authentification d’approbation. +- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans le même chat. +- Si votre canal expose des approbations exec natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface d’initiation / du client natif lorsqu’il diffère de l’authentification d’approbation dans le même chat. Le cœur utilise ce hook spécifique à exec pour distinguer `enabled` de `disabled`, décider si le canal initiateur prend en charge les approbations exec natives et inclure le canal dans les indications de secours pour client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit cela pour le cas courant. +- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, par exemple masquer les prompts locaux d’approbation en double ou envoyer des indicateurs de saisie avant la livraison. +- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression des solutions de secours. +- Utilisez `approvalCapability.nativeRuntime` pour les faits d’approbation native détenus par le canal. Gardez-le lazy sur les points d’entrée chauds du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module runtime à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations. - Utilisez `approvalCapability.render` uniquement lorsqu’un canal a réellement besoin de charges utiles d’approbation personnalisées au lieu du moteur de rendu partagé. -- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse du chemin désactivé explique exactement quels paramètres de configuration sont nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent afficher des chemins à portée de compte comme `channels..accounts..execApprovals.*` au lieu de valeurs par défaut de niveau supérieur. -- Si un canal peut déduire des identités de messages privés stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans la même discussion sans ajouter de logique spécifique aux approbations dans le cœur. -- Si un canal a besoin de la livraison d’approbations natives, gardez le code du canal centré sur la normalisation de la cible ainsi que sur les informations de transport et de présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les notifications de routage ailleurs. `nativeRuntime` est divisé en quelques jonctions plus petites : -- `availability` — si le compte est configuré et si une requête doit être prise en charge -- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente, résolues, expirées ou vers des actions finales -- `transport` — préparer les cibles puis envoyer, mettre à jour ou supprimer les messages d’approbation natifs -- `interactions` — hooks facultatifs pour lier, délier ou effacer des actions pour les boutons ou réactions natifs +- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse du chemin désactivé explique les paramètres de configuration exacts nécessaires pour activer les approbations exec natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à compte nommé doivent générer des chemins à portée de compte comme `channels..accounts..execApprovals.*` au lieu des valeurs par défaut de niveau supérieur. +- Si un canal peut déduire des identités DM stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans le même chat sans ajouter de logique spécifique aux approbations dans le cœur. +- Si un canal a besoin d’une livraison d’approbation native, gardez le code du canal focalisé sur la normalisation des cibles ainsi que sur les faits de transport / présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les faits spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage vers un autre emplacement. `nativeRuntime` est découpé en quelques surfaces plus petites : +- `availability` — si le compte est configuré et si une requête doit être traitée +- `presentation` — mapper le view model d’approbation partagé vers des charges utiles natives pending/resolved/expired ou des actions finales +- `transport` — préparer les cibles puis envoyer / mettre à jour / supprimer les messages d’approbation natifs +- `interactions` — hooks facultatifs bind/unbind/clear-action pour les boutons ou réactions natifs - `observe` — hooks facultatifs de diagnostic de livraison -- Si le canal a besoin d’objets gérés par l’exécution, comme un client, un jeton, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte d’exécution permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de colle d’enveloppe spécifique aux approbations. -- N’utilisez le niveau plus bas `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` que lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive. -- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` via ces helpers. `accountId` conserve la portée de la politique d’approbation multi-compte sur le bon compte de bot, et `approvalKind` conserve le comportement d’approbation d’exécution par rapport au Plugin disponible pour le canal sans branches codées en dur dans le cœur. -- Le cœur gère désormais aussi les notifications de reroutage des approbations. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi du type « l’approbation est allée dans les messages privés / un autre canal » depuis `createChannelNativeApprovalRuntime` ; à la place, exposez un routage précis de l’origine et des messages privés de l’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier toute notification dans la discussion initiatrice. -- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas deviner ni réécrire le routage des approbations d’exécution par rapport aux approbations de Plugin à partir d’un état local au canal. -- Différents types d’approbation peuvent volontairement exposer différentes surfaces natives. +- Si le canal a besoin d’objets détenus par le runtime comme un client, un token, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte runtime permet au cœur d’amorcer des gestionnaires pilotés par capacités à partir de l’état de démarrage du canal sans ajouter de glue d’encapsulation spécifique aux approbations. +- N’utilisez `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` au niveau inférieur que lorsque la surface pilotée par capacités n’est pas encore assez expressive. +- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` par ces helpers. `accountId` maintient la portée correcte de la politique d’approbation multi-compte pour le bon compte bot, et `approvalKind` conserve le comportement d’approbation exec vs Plugin disponible pour le canal sans branches codées en dur dans le cœur. +- Le cœur prend désormais aussi en charge les avis de reroutage des approbations. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation a été envoyée en DM / vers un autre canal » depuis `createChannelNativeApprovalRuntime` ; exposez plutôt un routage précis de l’origine + des DM d’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier un avis dans le chat initiateur. +- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas + deviner ou réécrire le routage d’approbation exec vs Plugin à partir de l’état local du canal. +- Des types d’approbation différents peuvent volontairement exposer des surfaces natives différentes. Exemples intégrés actuels : - - Slack conserve le routage d’approbation native disponible à la fois pour les identifiants d’exécution et de Plugin. - - Matrix conserve le même routage natif en messages privés ou canal et la même UX basée sur les réactions pour les approbations d’exécution et de Plugin, tout en permettant à l’authentification de différer selon le type d’approbation. -- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme enveloppe de compatibilité, mais le nouveau code doit préférer le constructeur de capacités et exposer `approvalCapability` sur le Plugin. + - Slack conserve le routage d’approbation native disponible à la fois pour les identifiants exec et Plugin. + - Matrix conserve le même routage DM/canal natif et la même UX par réaction pour les approbations exec + et Plugin, tout en laissant l’authentification varier selon le type d’approbation. +- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le générateur de capacités et exposer `approvalCapability` sur le Plugin. -Pour les points d’entrée critiques du canal, préférez les sous-chemins -d’exécution plus étroits lorsque vous n’avez besoin que d’une seule partie de -cette famille : +Pour les points d’entrée chauds du canal, préférez les sous-chemins runtime plus étroits lorsque vous n’avez besoin +que d’une partie de cette famille : - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -134,91 +125,98 @@ De même, préférez `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` et -`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la -surface englobante plus large. +`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la surface +globale plus large. -Pour la configuration en particulier : +Pour la configuration plus précisément : -- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution : adaptateurs de patch de configuration sûrs à l’importation (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), sortie des notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries` et les constructeurs de proxy de configuration déléguée -- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite, consciente de l’environnement, pour `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration d’installation facultative ainsi que quelques primitives sûres pour la configuration : +- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs pour le runtime : + adaptateurs de patch de configuration sûrs à l’importation (`createPatchedAccountSetupAdapter`, + `createEnvPatchedAccountSetupAdapter`, + `createSetupInputPresenceValidator`), sortie de note de recherche, + `promptResolvedAllowFrom`, `splitSetupEntries` et les constructeurs + de proxy de configuration déléguée +- `openclaw/plugin-sdk/setup-adapter-runtime` est la surface étroite d’adaptateur sensible à l’environnement + pour `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration + à installation facultative ainsi que quelques primitives sûres pour la configuration : `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Si votre canal prend en charge une configuration ou une authentification pilotée -par des variables d’environnement et que les flux génériques de démarrage ou de -configuration doivent connaître ces noms de variables avant le chargement de -l’exécution, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`. -Conservez `envVars` de l’exécution du canal ou des constantes locales -uniquement pour le texte destiné aux opérateurs. +Si votre canal prend en charge une configuration ou une authentification pilotée par l’environnement et que les flux génériques de démarrage/configuration +doivent connaître ces noms de variables d’environnement avant le chargement du runtime, déclarez-les dans le +manifeste du Plugin avec `channelEnvVars`. Conservez `envVars` du runtime du canal ou des constantes locales +uniquement pour le texte orienté opérateur. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` et `splitSetupEntries` -- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez aussi besoin des helpers partagés de configuration plus lourds, comme `moveSingleAccountChannelSectionToDefaultAccount(...)` +- utilisez la surface plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez également besoin des + helpers partagés plus lourds de configuration/configuration comme + `moveSingleAccountChannelSectionToDefaultAccount(...)` Si votre canal veut seulement annoncer « installez d’abord ce Plugin » dans les -surfaces de configuration, préférez -`createOptionalChannelSetupSurface(...)`. L’adaptateur et l’assistant générés -échouent en mode fermé sur les écritures de configuration et la finalisation, et -ils réutilisent le même message « installation requise » dans la validation, la -finalisation et le texte du lien vers la documentation. +surfaces de configuration, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur/l’assistant +généré échoue en mode fermé sur les écritures de configuration et la finalisation, et réutilise +le même message d’installation requise pour la validation, la finalisation et le texte +de lien vers la documentation. -Pour les autres chemins critiques du canal, préférez les helpers étroits aux +Pour les autres chemins chauds du canal, préférez les helpers étroits aux surfaces héritées plus larges : - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` et `openclaw/plugin-sdk/account-helpers` pour la configuration multi-compte et - la solution de repli du compte par défaut + la solution de repli vers le compte par défaut - `openclaw/plugin-sdk/inbound-envelope` et - `openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de la route ou - de l’enveloppe entrante ainsi que de l’enregistrement et de la répartition -- `openclaw/plugin-sdk/messaging-targets` pour l’analyse et la correspondance - des cibles + `openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage des routes/enveloppes entrantes et + record-and-dispatch +- `openclaw/plugin-sdk/messaging-targets` pour l’analyse et la correspondance des cibles - `openclaw/plugin-sdk/outbound-media` et - `openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que - les délégués d’identité et d’envoi sortants -- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des - liaisons de fil et l’enregistrement des adaptateurs -- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition - héritée des champs de charge utile agent/média est encore nécessaire -- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des - commandes personnalisées Telegram, la validation des doublons ou conflits, et - un contrat de configuration de commande stable en solution de repli + `openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que les délégués + d’identité/envoi sortants +- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des liaisons de thread + et l’enregistrement des adaptateurs +- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champ héritée + agent/media est encore requise +- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des commandes personnalisées Telegram, + la validation des doublons/conflits et un contrat de configuration de commande + stable en solution de repli -Les canaux basés uniquement sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes et d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de discussion personnalisés doivent utiliser les helpers natifs partagés au lieu de créer leur propre cycle de vie d’approbation. +Les canaux uniquement d’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes/d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de chat personnalisés doivent utiliser les helpers natifs partagés au lieu de créer leur propre cycle de vie d’approbation. -## Politique des mentions entrantes +## Politique de mention entrante -Conservez la gestion des mentions entrantes répartie en deux couches : +Conservez la gestion des mentions entrantes divisée en deux couches : -- collecte de preuves gérée par le Plugin +- collecte de preuves détenue par le Plugin - évaluation de politique partagée -Utilisez `openclaw/plugin-sdk/channel-inbound` pour la couche partagée. +Utilisez `openclaw/plugin-sdk/channel-mention-gating` pour les décisions de politique de mention. +Utilisez `openclaw/plugin-sdk/channel-inbound` uniquement lorsque vous avez besoin de la surface +plus large de helpers entrants. -Bon cas d’usage pour la logique locale au Plugin : +Bon choix pour la logique locale au Plugin : - détection de réponse au bot - détection de citation du bot -- vérifications de participation au fil -- exclusions de messages de service ou système -- caches natifs à la plateforme nécessaires pour prouver la participation du bot +- vérifications de participation au thread +- exclusions de messages de service/système +- caches natifs de plateforme nécessaires pour prouver la participation du bot -Bon cas d’usage pour le helper partagé : +Bon choix pour le helper partagé : - `requireMention` - résultat de mention explicite - liste d’autorisation de mention implicite -- contournement de commande +- contournement des commandes - décision finale d’ignorer Flux recommandé : 1. Calculez les faits de mention locaux. -2. Transmettez ces faits à `resolveInboundMentionDecision({ facts, policy })`. -3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde d’entrée. +2. Passez ces faits à `resolveInboundMentionDecision({ facts, policy })`. +3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde entrante. ```typescript import { @@ -257,8 +255,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour -les Plugins de canal intégrés qui dépendent déjà de l’injection d’exécution : +`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour les +Plugins de canal intégrés qui dépendent déjà de l’injection runtime : - `buildMentionRegexes` - `matchesMentionPatterns` @@ -266,20 +264,23 @@ les Plugins de canal intégrés qui dépendent déjà de l’injection d’exéc - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Les anciens helpers `resolveMentionGating*` restent dans -`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité. -Le nouveau code doit utiliser -`resolveInboundMentionDecision({ facts, policy })`. +Si vous n’avez besoin que de `implicitMentionKindWhen` et +`resolveInboundMentionDecision`, importez-les depuis +`openclaw/plugin-sdk/channel-mention-gating` afin d’éviter de charger des helpers runtime +entrants sans rapport. -## Procédure pas à pas +Les anciens helpers `resolveMentionGating*` restent disponibles sur +`openclaw/plugin-sdk/channel-inbound` uniquement comme exportations de compatibilité. Le nouveau code +doit utiliser `resolveInboundMentionDecision({ facts, policy })`. + +## Procédure détaillée - Créez les fichiers de Plugin standard. Le champ `channel` dans `package.json` - est ce qui en fait un Plugin de canal. Pour la surface complète des - métadonnées de package, consultez - [Plugin Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) : + Créez les fichiers standards du Plugin. Le champ `channel` dans `package.json` est + ce qui en fait un Plugin de canal. Pour la surface complète des métadonnées de package, + consultez [Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) : ```json package.json @@ -328,10 +329,9 @@ Le nouveau code doit utiliser - - L’interface `ChannelPlugin` possède de nombreuses surfaces d’adaptation - facultatives. Commencez par le minimum — `id` et `setup` — puis ajoutez des - adaptateurs selon vos besoins. + + L’interface `ChannelPlugin` comporte de nombreuses surfaces d’adaptation facultatives. Commencez par + le minimum — `id` et `setup` — puis ajoutez des adaptateurs selon vos besoins. Créez `src/channel.ts` : @@ -427,24 +427,23 @@ Le nouveau code doit utiliser ``` - Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas - niveau, vous fournissez des options déclaratives et le constructeur les - compose : + Au lieu d’implémenter manuellement des interfaces d’adaptation de bas niveau, vous passez + des options déclaratives et le constructeur les compose : - | Option | Ce qu’elle connecte | + | Option | Ce qui est câblé | | --- | --- | - | `security.dm` | Résolveur de sécurité des messages privés à portée limitée depuis les champs de configuration | - | `pairing.text` | Flux d’appairage de messages privés basé sur du texte avec échange de code | + | `security.dm` | Résolveur de sécurité DM à portée limitée à partir des champs de configuration | + | `pairing.text` | Flux de pairing DM basé sur du texte avec échange de code | | `threading` | Résolveur de mode de réponse (fixe, à portée de compte ou personnalisé) | | `outbound.attachedResults` | Fonctions d’envoi qui renvoient des métadonnées de résultat (identifiants de message) | - Vous pouvez aussi transmettre des objets d’adaptateur bruts au lieu des - options déclaratives si vous avez besoin d’un contrôle total. + Vous pouvez également passer des objets d’adaptateur bruts au lieu des options déclaratives + si vous avez besoin d’un contrôle total. - + Créez `index.ts` : ```typescript index.ts @@ -480,24 +479,21 @@ Le nouveau code doit utiliser }); ``` - Placez les descripteurs CLI gérés par le canal dans - `registerCliMetadata(...)` afin qu’OpenClaw puisse les afficher dans l’aide - racine sans activer l’exécution complète du canal, tandis que les - chargements complets normaux récupèrent toujours les mêmes descripteurs pour - l’enregistrement réel des commandes. Conservez `registerFull(...)` pour le - travail réservé à l’exécution. + Placez les descripteurs CLI détenus par le canal dans `registerCliMetadata(...)` afin qu’OpenClaw + puisse les afficher dans l’aide racine sans activer le runtime complet du canal, + tandis que les chargements complets normaux récupèrent toujours les mêmes descripteurs pour le véritable enregistrement + des commandes. Réservez `registerFull(...)` aux tâches limitées au runtime. Si `registerFull(...)` enregistre des méthodes RPC Gateway, utilisez un - préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur - (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés - et se résolvent toujours vers `operator.admin`. - `defineChannelPluginEntry` gère automatiquement cette séparation des modes - d’enregistrement. Consultez - [Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour - toutes les options. + préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et se + résolvent toujours vers `operator.admin`. + `defineChannelPluginEntry` gère automatiquement cette séparation des modes d’enregistrement. Consultez + [Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour toutes les + options. - + Créez `setup-entry.ts` pour un chargement léger pendant l’onboarding : ```typescript setup-entry.ts @@ -507,24 +503,21 @@ Le nouveau code doit utiliser export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw charge ceci à la place du point d’entrée complet lorsque le canal - est désactivé ou non configuré. Cela évite de charger du code d’exécution - lourd pendant les flux de configuration. - Consultez [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de - détails. + OpenClaw charge ceci au lieu du point d’entrée complet lorsque le canal est désactivé + ou non configuré. Cela évite de charger du code runtime lourd pendant les flux de configuration. + Consultez [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de détails. - Les canaux d’espace de travail intégrés qui répartissent les exports sûrs - pour la configuration dans des modules annexes peuvent utiliser - `defineBundledChannelSetupEntry(...)` depuis - `openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont aussi besoin - d’un setter d’exécution explicite au moment de la configuration. + Les canaux d’espace de travail intégrés qui répartissent les exportations sûres pour la configuration dans des modules + compagnons peuvent utiliser `defineBundledChannelSetupEntry(...)` depuis + `openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont également besoin d’un + setter runtime explicite au moment de la configuration. - Votre Plugin doit recevoir les messages depuis la plateforme et les - transférer vers OpenClaw. Le modèle habituel est un Webhook qui vérifie la - requête et la distribue via le gestionnaire entrant de votre canal : + Votre Plugin doit recevoir les messages depuis la plateforme et les transférer vers + OpenClaw. Le modèle habituel est un Webhook qui vérifie la requête et + la répartit via le gestionnaire entrant de votre canal : ```typescript registerFull(api) { @@ -548,10 +541,9 @@ Le nouveau code doit utiliser ``` - La gestion des messages entrants est spécifique au canal. Chaque Plugin de - canal gère son propre pipeline entrant. Examinez les Plugins de canal - intégrés (par exemple le package Plugin Microsoft Teams ou Google Chat) - pour voir des modèles réels. + La gestion des messages entrants est spécifique au canal. Chaque Plugin de canal possède + son propre pipeline entrant. Regardez les Plugins de canal intégrés + (par exemple le package Plugin Microsoft Teams ou Google Chat) pour voir de vrais modèles. @@ -564,8 +556,8 @@ Le nouveau code doit utiliser import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; - describe("plugin acme-chat", () => { - it("résout le compte à partir de la configuration", () => { + describe("acme-chat plugin", () => { + it("resolves account from config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -575,7 +567,7 @@ Le nouveau code doit utiliser expect(account.token).toBe("test-token"); }); - it("inspecte le compte sans matérialiser les secrets", () => { + it("inspects account without materializing secrets", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -584,7 +576,7 @@ Le nouveau code doit utiliser expect(result.tokenStatus).toBe("available"); }); - it("signale une configuration manquante", () => { + it("reports missing config", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -609,19 +601,19 @@ Le nouveau code doit utiliser ├── openclaw.plugin.json # Manifeste avec schéma de configuration ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Exports publics (facultatif) -├── runtime-api.ts # Exports d’exécution internes (facultatif) +├── api.ts # Exportations publiques (facultatif) +├── runtime-api.ts # Exportations runtime internes (facultatif) └── src/ ├── channel.ts # ChannelPlugin via createChatChannelPlugin ├── channel.test.ts # Tests ├── client.ts # Client API de la plateforme - └── runtime.ts # Stockage d’exécution (si nécessaire) + └── runtime.ts # Store runtime (si nécessaire) ``` ## Sujets avancés - + Modes de réponse fixes, à portée de compte ou personnalisés @@ -630,22 +622,21 @@ Le nouveau code doit utiliser inferTargetChatType, looksLikeId, resolveTarget - - TTS, STT, médias, sous-agent via api.runtime + + TTS, STT, média, sous-agent via api.runtime -Certaines jonctions de helpers intégrés existent encore pour la maintenance et -la compatibilité des Plugins intégrés. Ce n’est pas le modèle recommandé pour -les nouveaux Plugins de canal ; préférez les sous-chemins génériques -channel/setup/reply/runtime de la surface SDK commune, sauf si vous maintenez -directement cette famille de Plugins intégrés. +Certaines surfaces de helpers intégrés existent encore pour la maintenance et la +compatibilité des Plugins intégrés. Ce n’est pas le modèle recommandé pour les nouveaux Plugins de canal ; +préférez les sous-chemins génériques channel/setup/reply/runtime de la surface +SDK commune, sauf si vous maintenez directement cette famille de Plugins intégrés. ## Étapes suivantes -- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles -- [SDK Overview](/fr/plugins/sdk-overview) — référence complète des imports de sous-chemins +- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit également des modèles +- [SDK Overview](/fr/plugins/sdk-overview) — référence complète des importations par sous-chemin - [SDK Testing](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat - [Plugin Manifest](/fr/plugins/manifest) — schéma complet du manifeste diff --git a/docs/fr/plugins/sdk-overview.md b/docs/fr/plugins/sdk-overview.md index 0be0f93bb..8f62be48e 100644 --- a/docs/fr/plugins/sdk-overview.md +++ b/docs/fr/plugins/sdk-overview.md @@ -1,367 +1,379 @@ --- read_when: - Vous devez savoir depuis quel sous-chemin du SDK importer - - Vous voulez une référence pour toutes les méthodes d’enregistrement sur `OpenClawPluginApi` - - Vous recherchez une exportation SDK spécifique + - Vous voulez une référence pour toutes les méthodes d’enregistrement sur OpenClawPluginApi + - Vous recherchez une exportation spécifique du SDK sidebarTitle: SDK Overview -summary: Map d’importation, référence de l’API d’enregistrement et architecture du SDK -title: Vue d’ensemble du SDK Plugin +summary: Map d’import, référence de l’API d’enregistrement et architecture du SDK +title: Aperçu du SDK Plugin x-i18n: - generated_at: "2026-04-17T06:57:33Z" + generated_at: "2026-04-18T06:44:10Z" model: gpt-5.4 provider: openai - source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a + source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331 source_path: plugins/sdk-overview.md workflow: 15 --- -# Vue d’ensemble du SDK Plugin +# Aperçu du SDK Plugin Le SDK Plugin est le contrat typé entre les plugins et le cœur. Cette page est la référence pour **quoi importer** et **ce que vous pouvez enregistrer**. - **Vous cherchez un guide pratique ?** - - Premier plugin ? Commencez par [Premiers pas](/fr/plugins/building-plugins) - - Plugin de canal ? Voir [Plugins de canal](/fr/plugins/sdk-channel-plugins) - - Plugin de fournisseur ? Voir [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) + **Vous cherchez un guide pratique ?** + - Premier plugin ? Commencez par [Prise en main](/fr/plugins/building-plugins) + - Plugin de canal ? Voir [Plugins de canal](/fr/plugins/sdk-channel-plugins) + - Plugin de fournisseur ? Voir [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) -## Convention d’importation +## Convention d’import -Importez toujours depuis un sous-chemin spécifique : +Importez toujours depuis un sous-chemin spécifique : ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Chaque sous-chemin est un module petit et autonome. Cela permet de garder un -démarrage rapide et d’éviter les problèmes de dépendances circulaires. Pour les -helpers d’entrée/de build spécifiques aux canaux, préférez -`openclaw/plugin-sdk/channel-core` ; gardez `openclaw/plugin-sdk/core` pour -la surface parapluie plus large et les helpers partagés tels que +Chaque sous-chemin est un petit module autonome. Cela permet de garder un +démarrage rapide et d’éviter les problèmes de dépendances circulaires. Pour les helpers +d’entrée/de construction spécifiques aux canaux, privilégiez `openclaw/plugin-sdk/channel-core` ; réservez `openclaw/plugin-sdk/core` à +la surface ombrelle plus large et aux helpers partagés comme `buildChannelConfigSchema`. -N’ajoutez pas et ne dépendez pas de surfaces de commodité nommées d’après des fournisseurs comme +N’ajoutez pas et ne dépendez pas de points d’entrée de commodité nommés d’après des fournisseurs tels que `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de -surfaces helper associées à une marque de canal. Les plugins intégrés doivent -composer des sous-chemins SDK génériques dans leurs propres barrels `api.ts` ou `runtime-api.ts`, et le cœur +points d’entrée helpers marqués canal. Les plugins intégrés doivent composer des +sous-chemins génériques du SDK dans leurs propres barrels `api.ts` ou `runtime-api.ts`, et le cœur doit soit utiliser ces barrels locaux au plugin, soit ajouter un contrat SDK générique étroit lorsque le besoin est réellement transversal aux canaux. -La map d’exportation générée contient encore un petit ensemble de surfaces helper -pour les plugins intégrés, comme `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +La map d’export générée contient encore un petit ensemble de points d’entrée helpers de plugins intégrés +tels que `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` et `plugin-sdk/matrix*`. Ces -sous-chemins n’existent que pour la maintenance et la compatibilité des plugins intégrés ; -ils sont volontairement omis du tableau courant ci-dessous et ne constituent pas -le chemin d’importation recommandé pour les nouveaux plugins tiers. +sous-chemins existent uniquement pour la maintenance et la compatibilité des plugins intégrés ; ils sont +volontairement omis du tableau courant ci-dessous et ne constituent pas le +chemin d’import recommandé pour les nouveaux plugins tiers. ## Référence des sous-chemins -Les sous-chemins les plus couramment utilisés, regroupés par usage. La liste -complète générée de plus de 200 sous-chemins se trouve dans -`scripts/lib/plugin-sdk-entrypoints.json`. +Les sous-chemins les plus couramment utilisés, regroupés par usage. La liste complète générée de +plus de 200 sous-chemins se trouve dans `scripts/lib/plugin-sdk-entrypoints.json`. -Les sous-chemins helper réservés aux plugins intégrés figurent toujours dans cette -liste générée. Traitez-les comme des surfaces de détail d’implémentation/de compatibilité, sauf si une page de documentation -en promeut explicitement une comme publique. +Les sous-chemins helpers réservés aux plugins intégrés figurent toujours dans cette liste générée. +Traitez-les comme des surfaces de détail d’implémentation/de compatibilité, sauf si une page de documentation +en promeut explicitement un comme public. ### Entrée de plugin -| Sous-chemin | Exportations clés | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| Sous-chemin | Exportations principales | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | Sous-chemin | Exportations clés | + | Sous-chemin | Exportations principales | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Exportation du schéma Zod racine `openclaw.json` (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ainsi que `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/config-schema` | Export Zod du schéma racine `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/setup` | Helpers partagés d’assistant de configuration, invites d’allowlist, constructeurs d’état de configuration | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de config/mécanisme de contrôle d’action multi-compte, helpers de repli pour compte par défaut | + | `plugin-sdk/account-core` | Helpers de configuration multi-comptes/gate d’action, helpers de repli de compte par défaut | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalisation d’identifiant de compte | - | `plugin-sdk/account-resolution` | Helpers de recherche de compte + repli par défaut | - | `plugin-sdk/account-helpers` | Helpers étroits de liste de comptes/action sur compte | + | `plugin-sdk/account-resolution` | Recherche de compte + helpers de repli par défaut | + | `plugin-sdk/account-helpers` | Helpers ciblés de liste de comptes/action de compte | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Types de schéma de config de canal | - | `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation de commandes personnalisées Telegram avec repli sur contrat intégré | + | `plugin-sdk/channel-config-schema` | Types de schéma de configuration de canal | + | `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation des commandes personnalisées Telegram avec repli de contrat intégré | + | `plugin-sdk/command-gating` | Helpers ciblés de gate d’autorisation de commande | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | | `plugin-sdk/inbound-envelope` | Helpers partagés de route entrante + construction d’enveloppe | - | `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d’enregistrement et de répartition entrante | + | `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d’enregistrement entrant et de distribution | | `plugin-sdk/messaging-targets` | Helpers d’analyse/de correspondance de cibles | | `plugin-sdk/outbound-media` | Helpers partagés de chargement de médias sortants | | `plugin-sdk/outbound-runtime` | Helpers de délégation d’envoi/d’identité sortante | - | `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d’adaptateur pour liaisons de fils | - | `plugin-sdk/agent-media-payload` | Constructeur historique de charge utile média d’agent | - | `plugin-sdk/conversation-runtime` | Helpers de liaison conversation/fil, appairage et liaison configurée | - | `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de config d’exécution | - | `plugin-sdk/runtime-group-policy` | Helpers de résolution de politique de groupe à l’exécution | - | `plugin-sdk/channel-status` | Helpers partagés d’instantané/résumé de statut de canal | - | `plugin-sdk/channel-config-primitives` | Primitives étroites de schéma de config de canal | - | `plugin-sdk/channel-config-writes` | Helpers d’autorisation d’écriture de config de canal | - | `plugin-sdk/channel-plugin-common` | Exportations de prélude partagées pour plugin de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de lecture/modification de config d’allowlist | + | `plugin-sdk/poll-runtime` | Helpers ciblés de normalisation de sondage | + | `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d’adaptateur des liaisons de thread | + | `plugin-sdk/agent-media-payload` | Constructeur hérité de payload média d’agent | + | `plugin-sdk/conversation-runtime` | Helpers de liaison de conversation/thread, d’appairage et de liaison configurée | + | `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de configuration d’exécution | + | `plugin-sdk/runtime-group-policy` | Helpers d’exécution de résolution de politique de groupe | + | `plugin-sdk/channel-status` | Helpers partagés d’instantané/résumé d’état de canal | + | `plugin-sdk/channel-config-primitives` | Primitives ciblées de schéma de configuration de canal | + | `plugin-sdk/channel-config-writes` | Helpers d’autorisation d’écriture de configuration de canal | + | `plugin-sdk/channel-plugin-common` | Exports de prélude partagés de plugin de canal | + | `plugin-sdk/allowlist-config-edit` | Helpers de lecture/édition de configuration d’allowlist | | `plugin-sdk/group-access` | Helpers partagés de décision d’accès de groupe | - | `plugin-sdk/direct-dm` | Helpers partagés d’authentification/de garde pour messages directs | - | `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de charge utile de réponse interactive | - | `plugin-sdk/channel-inbound` | Helpers d’anti-rebond entrant, de correspondance de mention, de politique de mention et d’enveloppe | + | `plugin-sdk/direct-dm` | Helpers partagés d’authentification/garde de message direct | + | `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de payload de réponse interactive | + | `plugin-sdk/channel-inbound` | Barrel de compatibilité pour le debounce entrant, la correspondance de mention, les helpers de politique de mention et les helpers d’enveloppe | + | `plugin-sdk/channel-mention-gating` | Helpers ciblés de politique de mention sans la surface d’exécution entrante plus large | + | `plugin-sdk/channel-location` | Helpers de contexte et de formatage d’emplacement de canal | + | `plugin-sdk/channel-logging` | Helpers de journalisation de canal pour les rejets entrants et les échecs de saisie/d’accusé de réception | | `plugin-sdk/channel-send-result` | Types de résultat de réponse | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Helpers d’analyse/de correspondance de cibles | | `plugin-sdk/channel-contract` | Types de contrat de canal | - | `plugin-sdk/channel-feedback` | Câblage de feedback/réaction | - | `plugin-sdk/channel-secret-runtime` | Helpers étroits de contrat de secret comme `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, ainsi que les types de cible de secret | + | `plugin-sdk/channel-feedback` | Câblage des retours/réactions | + | `plugin-sdk/channel-secret-runtime` | Helpers ciblés de contrat de secret comme `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, et types de cible de secret | - | Sous-chemin | Exportations clés | + | Sous-chemin | Exportations principales | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helpers de configuration organisés pour fournisseurs locaux/autohébergés | + | `plugin-sdk/provider-setup` | Helpers de configuration sélectionnés pour les fournisseurs locaux/autohébergés | | `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur autohébergé compatible OpenAI | - | `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpers d’exécution de résolution de clé API pour plugins de fournisseur | - | `plugin-sdk/provider-auth-api-key` | Helpers d’intégration/écriture de profil de clé API comme `upsertApiKeyProfile` | + | `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes de watchdog | + | `plugin-sdk/provider-auth-runtime` | Helpers d’exécution de résolution de clé API pour les plugins de fournisseur | + | `plugin-sdk/provider-auth-api-key` | Helpers d’intégration/écriture de profil de clé API tels que `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Constructeur standard de résultat d’authentification OAuth | - | `plugin-sdk/provider-auth-login` | Helpers partagés de connexion interactive pour plugins de fournisseur | - | `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d’environnement d’authentification de fournisseur | + | `plugin-sdk/provider-auth-login` | Helpers partagés de connexion interactive pour les plugins de fournisseur | + | `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d’environnement d’authentification fournisseur | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de relecture, helpers de point de terminaison de fournisseur, et helpers de normalisation d’identifiant de modèle tels que `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de rejeu, helpers de point de terminaison fournisseur et helpers de normalisation d’identifiant de modèle comme `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helpers génériques de capacité HTTP/point de terminaison de fournisseur | - | `plugin-sdk/provider-web-fetch-contract` | Helpers étroits de contrat de config/sélection web-fetch comme `enablePluginInConfig` et `WebFetchProviderPlugin` | + | `plugin-sdk/provider-http` | Helpers génériques de capacité HTTP/point de terminaison fournisseur | + | `plugin-sdk/provider-web-fetch-contract` | Helpers ciblés de contrat de configuration/sélection web-fetch comme `enablePluginInConfig` et `WebFetchProviderPlugin` | | `plugin-sdk/provider-web-fetch` | Helpers d’enregistrement/cache de fournisseur web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers étroits de config/identifiants web-search pour les fournisseurs qui n’ont pas besoin du câblage d’activation du plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers étroits de contrat de config/identifiants web-search comme `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et les setters/getters d’identifiants à portée limitée | - | `plugin-sdk/provider-web-search` | Helpers d’exécution/cache/enregistrement de fournisseur web-search | + | `plugin-sdk/provider-web-search-config-contract` | Helpers ciblés de configuration/d’identifiants web-search pour les fournisseurs qui n’ont pas besoin de câblage d’activation de plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers ciblés de contrat de configuration/d’identifiants web-search comme `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d’identifiants à portée limitée | + | `plugin-sdk/provider-web-search` | Helpers d’enregistrement/cache/exécution de fournisseur web-search | | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI comme `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` et similaires | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types de wrapper de flux, et helpers partagés de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helpers de correctif de config d’intégration | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types de wrappers de flux, et helpers partagés de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Helpers de correctif de configuration d’intégration | | `plugin-sdk/global-singleton` | Helpers de singleton/map/cache locaux au processus | - | Sous-chemin | Exportations clés | + | Sous-chemin | Exportations principales | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registre de commandes, helpers d’autorisation d’expéditeur | - | `plugin-sdk/command-status` | Constructeurs de messages de commande/d’aide tels que `buildCommandsMessagePaginated` et `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Helpers de résolution d’approbateur et d’authentification d’action dans la même discussion | - | `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation d’exécution native | - | `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/livraison d’approbation | + | `plugin-sdk/command-status` | Constructeurs de messages de commande/d’aide comme `buildCommandsMessagePaginated` et `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helpers de résolution d’approbateur et d’authentification d’action dans le même chat | + | `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation exec natifs | + | `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/de livraison d’approbation | | `plugin-sdk/approval-gateway-runtime` | Helper partagé de résolution de Gateway d’approbation | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal critiques | - | `plugin-sdk/approval-handler-runtime` | Helpers plus larges du runtime de gestionnaire d’approbation ; préférez les surfaces adaptateur/Gateway plus étroites lorsqu’elles suffisent | - | `plugin-sdk/approval-native-runtime` | Helpers natifs de cible d’approbation + liaison de compte | - | `plugin-sdk/approval-reply-runtime` | Helpers de charge utile de réponse d’approbation exec/plugin | - | `plugin-sdk/command-auth-native` | Helpers natifs d’authentification de commande + helpers natifs de cible de session | - | `plugin-sdk/command-detection` | Helpers partagés de détection de commande | - | `plugin-sdk/command-surface` | Helpers de normalisation de corps de commande et de surface de commande | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation natif pour points d’entrée de canal à chaud | + | `plugin-sdk/approval-handler-runtime` | Helpers d’exécution plus larges de gestionnaire d’approbation ; privilégiez les points d’entrée plus étroits adapter/gateway lorsqu’ils suffisent | + | `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation native + de liaison de compte | + | `plugin-sdk/approval-reply-runtime` | Helpers de payload de réponse d’approbation exec/plugin | + | `plugin-sdk/command-auth-native` | Authentification de commande native + helpers natifs de cible de session | + | `plugin-sdk/command-detection` | Helpers partagés de détection de commandes | + | `plugin-sdk/command-surface` | Helpers de normalisation du corps de commande et de surface de commande | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helpers étroits de collecte de contrat de secret pour les surfaces de secret de canal/plugin | - | `plugin-sdk/secret-ref-runtime` | Helpers étroits `coerceSecretRef` et de typage SecretRef pour l’analyse de contrat de secret/config | - | `plugin-sdk/security-runtime` | Helpers partagés de confiance, contrôle DM, contenu externe et collecte de secrets | - | `plugin-sdk/ssrf-policy` | Helpers de politique SSRF d’allowlist d’hôtes et de réseau privé | - | `plugin-sdk/ssrf-runtime` | Helpers de répartiteur épinglé, fetch protégé par SSRF et politique SSRF | + | `plugin-sdk/channel-secret-runtime` | Helpers ciblés de collecte de contrat de secret pour surfaces de secrets de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Helpers ciblés `coerceSecretRef` et de typage SecretRef pour l’analyse des contrats de secret/de la configuration | + | `plugin-sdk/security-runtime` | Helpers partagés de confiance, gate DM, contenu externe et collecte de secrets | + | `plugin-sdk/ssrf-policy` | Helpers de politique SSRF de liste d’autorisation d’hôtes et de réseau privé | + | `plugin-sdk/ssrf-dispatcher` | Helpers ciblés de dispatcher épinglé sans la large surface d’exécution infra | + | `plugin-sdk/ssrf-runtime` | Helpers de dispatcher épinglé, fetch protégé contre SSRF et politique SSRF | | `plugin-sdk/secret-input` | Helpers d’analyse d’entrée de secret | | `plugin-sdk/webhook-ingress` | Helpers de requête/cible Webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de taille du corps de requête/délai d’attente | + | `plugin-sdk/webhook-request-guards` | Helpers de taille de corps de requête/délai d’expiration | - - | Sous-chemin | Exportations clés | + + | Sous-chemin | Exportations principales | | --- | --- | - | `plugin-sdk/runtime` | Helpers larges de runtime/journalisation/sauvegarde/installation de plugin | - | `plugin-sdk/runtime-env` | Helpers étroits d’environnement de runtime, logger, délai d’attente, retry et backoff | - | `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche du contexte d’exécution de canal | + | `plugin-sdk/runtime` | Helpers larges d’exécution/journalisation/sauvegarde/installation de plugin | + | `plugin-sdk/runtime-env` | Helpers ciblés d’environnement d’exécution, logger, délai d’expiration, nouvelle tentative et backoff | + | `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche de contexte d’exécution de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | Helpers partagés de commande/hook/http/interaction de plugin | | `plugin-sdk/hook-runtime` | Helpers partagés de pipeline de Webhook/hook interne | - | `plugin-sdk/lazy-runtime` | Helpers d’importation/de liaison de runtime paresseux tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` | + | `plugin-sdk/lazy-runtime` | Helpers d’import/liaison d’exécution paresseuse comme `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Helpers d’exécution de processus | - | `plugin-sdk/cli-runtime` | Helpers de formatage, d’attente et de version pour CLI | - | `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de correctif de statut de canal | - | `plugin-sdk/config-runtime` | Helpers de chargement/écriture de config | - | `plugin-sdk/telegram-command-config` | Normalisation du nom/de la description de commande Telegram et vérifications de doublon/conflit, même lorsque la surface de contrat Telegram intégrée n’est pas disponible | - | `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers d’authentification/profil, helpers natifs de routage/runtime | - | `plugin-sdk/reply-runtime` | Helpers partagés du runtime entrant/de réponse, segmentation, répartition, Heartbeat, planificateur de réponse | - | `plugin-sdk/reply-dispatch-runtime` | Helpers étroits de répartition/finalisation de réponse | - | `plugin-sdk/reply-history` | Helpers partagés d’historique de réponse sur fenêtre courte tels que `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/cli-runtime` | Helpers de formatage, d’attente et de version pour la CLI | + | `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de correctif d’état de canal | + | `plugin-sdk/config-runtime` | Helpers de chargement/écriture de configuration | + | `plugin-sdk/telegram-command-config` | Normalisation des noms/descriptions de commandes Telegram et vérifications des doublons/conflits, même lorsque la surface de contrat Telegram intégrée n’est pas disponible | + | `plugin-sdk/text-autolink-runtime` | Détection d’autolien de référence de fichier sans le large barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers d’authentification/de profil, helpers de routage/d’exécution natifs | + | `plugin-sdk/reply-runtime` | Helpers partagés d’exécution entrante/de réponse, découpage en blocs, distribution, Heartbeat, planificateur de réponse | + | `plugin-sdk/reply-dispatch-runtime` | Helpers ciblés de distribution/finalisation de réponse | + | `plugin-sdk/reply-history` | Helpers partagés d’historique de réponse sur courte fenêtre comme `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers étroits de segmentation de texte/Markdown | - | `plugin-sdk/session-store-runtime` | Helpers de chemin du magasin de session + date de mise à jour | - | `plugin-sdk/state-paths` | Helpers de chemin de répertoire pour état/OAuth | - | `plugin-sdk/routing` | Helpers de routage/clé de session/liaison de compte tels que `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helpers partagés de résumé de statut de canal/compte, valeurs par défaut de l’état d’exécution et helpers de métadonnées de problème | + | `plugin-sdk/reply-chunking` | Helpers ciblés de découpage de texte/Markdown | + | `plugin-sdk/session-store-runtime` | Helpers de chemin de stockage de session + `updated-at` | + | `plugin-sdk/state-paths` | Helpers de chemins de répertoire State/OAuth | + | `plugin-sdk/routing` | Helpers de route/clé de session/liaison de compte comme `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helpers partagés de résumé d’état de canal/compte, valeurs par défaut d’état d’exécution et helpers de métadonnées de problème | | `plugin-sdk/target-resolver-runtime` | Helpers partagés de résolution de cible | | `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de slug/chaîne | - | `plugin-sdk/request-url` | Extraire des URL de chaîne à partir d’entrées de type fetch/request | + | `plugin-sdk/request-url` | Extrait des URL chaîne depuis des entrées de type fetch/request | | `plugin-sdk/run-command` | Exécuteur de commande temporisé avec résultats stdout/stderr normalisés | - | `plugin-sdk/param-readers` | Lecteurs courants de paramètres d’outil/CLI | - | `plugin-sdk/tool-payload` | Extraire des charges utiles normalisées à partir d’objets résultat d’outil | - | `plugin-sdk/tool-send` | Extraire les champs de cible d’envoi canoniques à partir des arguments d’outil | + | `plugin-sdk/param-readers` | Lecteurs de paramètres communs d’outil/CLI | + | `plugin-sdk/tool-payload` | Extrait des payloads normalisés depuis des objets de résultat d’outil | + | `plugin-sdk/tool-send` | Extrait les champs de cible d’envoi canoniques depuis les arguments d’outil | | `plugin-sdk/temp-path` | Helpers partagés de chemin de téléchargement temporaire | | `plugin-sdk/logging-core` | Helpers de logger de sous-système et de masquage | | `plugin-sdk/markdown-table-runtime` | Helpers de mode de tableau Markdown | | `plugin-sdk/json-store` | Petits helpers de lecture/écriture d’état JSON | - | `plugin-sdk/file-lock` | Helpers de verrouillage de fichier réentrant | - | `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication sauvegardé sur disque | - | `plugin-sdk/acp-runtime` | Helpers ACP de runtime/session et de répartition de réponse | - | `plugin-sdk/agent-config-primitives` | Primitives étroites de schéma de config du runtime d’agent | - | `plugin-sdk/boolean-param` | Lecteur souple de paramètre booléen | - | `plugin-sdk/dangerous-name-runtime` | Helpers de résolution de correspondance de nom dangereux | - | `plugin-sdk/device-bootstrap` | Helpers d’initialisation d’appareil et de jeton d’appairage | - | `plugin-sdk/extension-shared` | Primitives helper partagées pour canal passif, statut et proxy ambiant | - | `plugin-sdk/models-provider-runtime` | Helpers de réponse de fournisseur/commande `/models` | - | `plugin-sdk/skill-commands-runtime` | Helpers de liste de commandes Skills | - | `plugin-sdk/native-command-registry` | Helpers natifs de registre/construction/sérialisation de commande | - | `plugin-sdk/agent-harness` | Surface expérimentale de plugin approuvé pour des harnais d’agent bas niveau : types de harnais, helpers de pilotage/abandon d’exécution active, helpers de pont d’outil OpenClaw et utilitaires de résultat de tentative | + | `plugin-sdk/file-lock` | Helpers de verrouillage de fichier réentrants | + | `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication adossé au disque | + | `plugin-sdk/acp-runtime` | Helpers ACP d’exécution/session et de distribution de réponse | + | `plugin-sdk/acp-binding-resolve-runtime` | Résolution en lecture seule des liaisons ACP sans imports de démarrage du cycle de vie | + | `plugin-sdk/agent-config-primitives` | Primitives ciblées de schéma de configuration d’exécution d’agent | + | `plugin-sdk/boolean-param` | Lecteur permissif de paramètre booléen | + | `plugin-sdk/dangerous-name-runtime` | Helpers de résolution de correspondance de noms dangereux | + | `plugin-sdk/device-bootstrap` | Helpers de bootstrap d’appareil et de jeton d’appairage | + | `plugin-sdk/extension-shared` | Primitives helpers partagées de canal passif, statut et proxy ambiant | + | `plugin-sdk/models-provider-runtime` | Helpers de réponse de commande `/models`/fournisseur | + | `plugin-sdk/skill-commands-runtime` | Helpers de listage des commandes Skills | + | `plugin-sdk/native-command-registry` | Helpers natifs de registre/construction/sérialisation de commandes | + | `plugin-sdk/agent-harness` | Surface expérimentale de plugin de confiance pour harnais d’agent de bas niveau : types de harnais, helpers de pilotage/abandon d’exécution active, helpers de pont d’outil OpenClaw et utilitaires de résultat de tentative | | `plugin-sdk/provider-zai-endpoint` | Helpers de détection de point de terminaison Z.A.I | | `plugin-sdk/infra-runtime` | Helpers d’événement système/Heartbeat | | `plugin-sdk/collection-runtime` | Petits helpers de cache borné | | `plugin-sdk/diagnostic-runtime` | Helpers de drapeau et d’événement de diagnostic | - | `plugin-sdk/error-runtime` | Helpers de graphe d’erreur, formatage, classification d’erreur partagée, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helpers de fetch enveloppé, proxy et recherche épinglée | + | `plugin-sdk/error-runtime` | Graphe d’erreurs, formatage, helpers partagés de classification d’erreurs, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helpers de fetch encapsulé, proxy et recherche épinglée | + | `plugin-sdk/runtime-fetch` | Fetch d’exécution sensible au dispatcher sans imports proxy/fetch protégé | + | `plugin-sdk/response-limit-runtime` | Lecteur borné de corps de réponse sans la large surface d’exécution média | + | `plugin-sdk/session-binding-runtime` | État de liaison de conversation actuelle sans routage de liaison configurée ni magasins d’appairage | + | `plugin-sdk/session-store-runtime` | Helpers de lecture du magasin de session sans imports larges d’écriture/de maintenance de configuration | + | `plugin-sdk/context-visibility-runtime` | Résolution de visibilité du contexte et filtrage de contexte supplémentaire sans imports larges de configuration/sécurité | + | `plugin-sdk/string-coerce-runtime` | Helpers ciblés de coercition et de normalisation de record/chaîne primitive sans imports Markdown/journalisation | | `plugin-sdk/host-runtime` | Helpers de normalisation de nom d’hôte et d’hôte SCP | - | `plugin-sdk/retry-runtime` | Helpers de config de retry et d’exécuteur de retry | + | `plugin-sdk/retry-runtime` | Helpers de configuration de nouvelle tentative et d’exécuteur de nouvelle tentative | | `plugin-sdk/agent-runtime` | Helpers de répertoire/identité/espace de travail d’agent | - | `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire basée sur la config | + | `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire adossée à la configuration | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Sous-chemin | Exportations clés | + + | Sous-chemin | Exportations principales | | --- | --- | - | `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias ainsi que constructeurs de charge utile média | - | `plugin-sdk/media-generation-runtime` | Helpers partagés de basculement en cas d’échec pour la génération de médias, sélection de candidats et messagerie de modèle manquant | - | `plugin-sdk/media-understanding` | Types de fournisseur de compréhension des médias ainsi qu’exportations helper orientées fournisseur pour image/audio | - | `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation tels que suppression du texte visible par l’assistant, helpers de rendu/segmentation/tableau Markdown, helpers de masquage, helpers de balise de directive et utilitaires de texte sûr | - | `plugin-sdk/text-chunking` | Helper de segmentation de texte sortant | - | `plugin-sdk/speech` | Types de fournisseur Speech ainsi qu’helpers orientés fournisseur pour directives, registre et validation | - | `plugin-sdk/speech-core` | Helpers partagés de types, registre, directive et normalisation pour fournisseur Speech | + | `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias, plus constructeurs de payload média | + | `plugin-sdk/media-generation-runtime` | Helpers partagés de basculement en cas d’échec pour la génération de médias, sélection de candidats et messages de modèle manquant | + | `plugin-sdk/media-understanding` | Types de fournisseur de compréhension de médias, plus exports helpers côté fournisseur pour image/audio | + | `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation comme la suppression de texte visible par l’assistant, les helpers de rendu/découpage/tableau Markdown, les helpers de masquage, les helpers de balises de directive et les utilitaires de texte sûr | + | `plugin-sdk/text-chunking` | Helper de découpage de texte sortant | + | `plugin-sdk/speech` | Types de fournisseur Speech, plus helpers côté fournisseur pour directives, registre et validation | + | `plugin-sdk/speech-core` | Helpers partagés de types de fournisseur Speech, registre, directive et normalisation | | `plugin-sdk/realtime-transcription` | Types de fournisseur de transcription en temps réel et helpers de registre | | `plugin-sdk/realtime-voice` | Types de fournisseur de voix en temps réel et helpers de registre | | `plugin-sdk/image-generation` | Types de fournisseur de génération d’image | | `plugin-sdk/image-generation-core` | Helpers partagés de types, basculement en cas d’échec, authentification et registre pour la génération d’image | - | `plugin-sdk/music-generation` | Types de fournisseur/de requête/de résultat pour la génération musicale | - | `plugin-sdk/music-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération musicale | - | `plugin-sdk/video-generation` | Types de fournisseur/de requête/de résultat pour la génération vidéo | - | `plugin-sdk/video-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération vidéo | - | `plugin-sdk/webhook-targets` | Helpers de registre de cible Webhook et d’installation de route | + | `plugin-sdk/music-generation` | Types de fournisseur/requête/résultat pour la génération musicale | + | `plugin-sdk/music-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de `model-ref` pour la génération musicale | + | `plugin-sdk/video-generation` | Types de fournisseur/requête/résultat pour la génération vidéo | + | `plugin-sdk/video-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de `model-ref` pour la génération vidéo | + | `plugin-sdk/webhook-targets` | Registre de cibles Webhook et helpers d’installation de route | | `plugin-sdk/webhook-path` | Helpers de normalisation de chemin Webhook | | `plugin-sdk/web-media` | Helpers partagés de chargement de médias distants/locaux | | `plugin-sdk/zod` | `zod` réexporté pour les consommateurs du SDK Plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Sous-chemin | Exportations clés | + + | Sous-chemin | Exportations principales | | --- | --- | - | `plugin-sdk/memory-core` | Surface helper `memory-core` intégrée pour les helpers de gestionnaire/config/fichier/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Façade de runtime pour l’indexation/la recherche mémoire | - | `plugin-sdk/memory-core-host-engine-foundation` | Exportations du moteur de fondation hôte mémoire | - | `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embedding hôte mémoire, accès au registre, fournisseur local et helpers génériques de lot/distant | - | `plugin-sdk/memory-core-host-engine-qmd` | Exportations du moteur QMD hôte mémoire | - | `plugin-sdk/memory-core-host-engine-storage` | Exportations du moteur de stockage hôte mémoire | + | `plugin-sdk/memory-core` | Surface helper `memory-core` intégrée pour les helpers de gestionnaire/configuration/fichier/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Façade d’exécution d’indexation/recherche mémoire | + | `plugin-sdk/memory-core-host-engine-foundation` | Exports du moteur de fondation hôte mémoire | + | `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embeddings hôte mémoire, accès au registre, fournisseur local et helpers génériques de lot/distants | + | `plugin-sdk/memory-core-host-engine-qmd` | Exports du moteur QMD hôte mémoire | + | `plugin-sdk/memory-core-host-engine-storage` | Exports du moteur de stockage hôte mémoire | | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte mémoire | | `plugin-sdk/memory-core-host-query` | Helpers de requête hôte mémoire | | `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte mémoire | | `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements hôte mémoire | - | `plugin-sdk/memory-core-host-status` | Helpers de statut hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime CLI hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime central hôte mémoire | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/runtime hôte mémoire | - | `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers de runtime central hôte mémoire | + | `plugin-sdk/memory-core-host-status` | Helpers d’état hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-cli` | Helpers d’exécution CLI hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-core` | Helpers d’exécution cœur hôte mémoire | + | `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/d’exécution hôte mémoire | + | `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers d’exécution cœur hôte mémoire | | `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements hôte mémoire | - | `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/runtime hôte mémoire | - | `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins adjacents à la mémoire | - | `plugin-sdk/memory-host-search` | Façade de runtime Active Memory pour l’accès au gestionnaire de recherche | - | `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers de statut hôte mémoire | + | `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/d’exécution hôte mémoire | + | `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins liés à la mémoire | + | `plugin-sdk/memory-host-search` | Façade d’exécution Active Memory pour l’accès au gestionnaire de recherche | + | `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers d’état hôte mémoire | | `plugin-sdk/memory-lancedb` | Surface helper `memory-lancedb` intégrée | - - | Famille | Sous-chemins actuels | Utilisation prévue | + + | Famille | Sous-chemins actuels | Usage prévu | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de support pour le plugin Browser intégré (`browser-support` reste le barrel de compatibilité) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/runtime Matrix intégrée | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/runtime LINE intégrée | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de prise en charge du Plugin browser intégré (`browser-support` reste le barrel de compatibilité) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/d’exécution Matrix intégrée | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/d’exécution LINE intégrée | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface helper IRC intégrée | - | Helpers spécifiques à un canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Surfaces de compatibilité/helper de canaux intégrés | - | Helpers spécifiques à l’authentification/au plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Surfaces helper de fonctionnalités/plugins intégrés ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` | + | Helpers spécifiques aux canaux | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Points d’entrée de compatibilité/helper de canaux intégrés | + | Helpers spécifiques à l’authentification/au plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Points d’entrée helper de fonctionnalité/plugin intégrés ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` | ## API d’enregistrement Le callback `register(api)` reçoit un objet `OpenClawPluginApi` avec ces -méthodes : +méthodes : ### Enregistrement de capacités -| Méthode | Ce qu’elle enregistre | -| ----------------------------------------------- | -------------------------------------- | -| `api.registerProvider(...)` | Inférence de texte (LLM) | -| `api.registerAgentHarness(...)` | Exécuteur d’agent bas niveau expérimental | -| `api.registerCliBackend(...)` | Backend local d’inférence CLI | -| `api.registerChannel(...)` | Canal de messagerie | -| `api.registerSpeechProvider(...)` | Synthèse texte-parole / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Transcription en temps réel en streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales duplex en temps réel | -| `api.registerMediaUnderstandingProvider(...)` | Analyse d’image/audio/vidéo | -| `api.registerImageGenerationProvider(...)` | Génération d’image | -| `api.registerMusicGenerationProvider(...)` | Génération musicale | -| `api.registerVideoGenerationProvider(...)` | Génération vidéo | -| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web | -| `api.registerWebSearchProvider(...)` | Recherche web | +| Méthode | Ce qu’elle enregistre | +| ------------------------------------------------ | -------------------------------------- | +| `api.registerProvider(...)` | Inférence de texte (LLM) | +| `api.registerAgentHarness(...)` | Exécuteur d’agent expérimental de bas niveau | +| `api.registerCliBackend(...)` | Backend local d’inférence CLI | +| `api.registerChannel(...)` | Canal de messagerie | +| `api.registerSpeechProvider(...)` | Synthèse texte-parole / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Transcription temps réel en streaming | +| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales temps réel duplex | +| `api.registerMediaUnderstandingProvider(...)` | Analyse d’images/audio/vidéo | +| `api.registerImageGenerationProvider(...)` | Génération d’image | +| `api.registerMusicGenerationProvider(...)` | Génération musicale | +| `api.registerVideoGenerationProvider(...)` | Génération vidéo | +| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web | +| `api.registerWebSearchProvider(...)` | Recherche web | ### Outils et commandes -| Méthode | Ce qu’elle enregistre | -| ----------------------------- | ------------------------------------------- | -| `api.registerTool(tool, opts?)` | Outil d’agent (obligatoire ou `{ optional: true }`) | -| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) | +| Méthode | Ce qu’elle enregistre | +| ------------------------------- | --------------------------------------------- | +| `api.registerTool(tool, opts?)` | Outil d’agent (requis ou `{ optional: true }`) | +| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) | ### Infrastructure -| Méthode | Ce qu’elle enregistre | -| --------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook d’événement | -| `api.registerHttpRoute(params)` | Point de terminaison HTTP Gateway | -| `api.registerGatewayMethod(name, handler)` | Méthode RPC Gateway | -| `api.registerCli(registrar, opts?)` | Sous-commande CLI | -| `api.registerService(service)` | Service en arrière-plan | -| `api.registerInteractiveHandler(registration)` | Gestionnaire interactif | -| `api.registerMemoryPromptSupplement(builder)` | Section additive de prompt adjacente à la mémoire | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire | +| Méthode | Ce qu’elle enregistre | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook d’événement | +| `api.registerHttpRoute(params)` | Point de terminaison HTTP Gateway | +| `api.registerGatewayMethod(name, handler)` | Méthode RPC Gateway | +| `api.registerCli(registrar, opts?)` | Sous-commande CLI | +| `api.registerService(service)` | Service d’arrière-plan | +| `api.registerInteractiveHandler(registration)` | Gestionnaire interactif | +| `api.registerMemoryPromptSupplement(builder)` | Section additive de prompt liée à la mémoire | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire | Les espaces de noms d’administration du cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) restent toujours `operator.admin`, même si un plugin essaie d’assigner une -portée de méthode Gateway plus étroite. Préférez des préfixes spécifiques au plugin pour -les méthodes appartenant au plugin. +`update.*`) restent toujours `operator.admin`, même si un plugin tente +d’attribuer une portée de méthode Gateway plus étroite. Préférez des préfixes spécifiques au plugin pour les +méthodes possédées par le plugin. ### Métadonnées d’enregistrement CLI -`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de premier niveau : +`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de premier niveau : -- `commands` : racines de commande explicites appartenant au registrar -- `descriptors` : descripteurs de commande au moment de l’analyse utilisés pour l’aide de la CLI racine, - le routage et l’enregistrement paresseux de la CLI du plugin +- `commands` : racines de commande explicites possédées par le registrar +- `descriptors` : descripteurs de commande au moment de l’analyse utilisés pour l’aide de la CLI racine, + le routage et l’enregistrement paresseux de CLI de plugin -Si vous voulez qu’une commande de plugin reste chargée paresseusement dans le chemin CLI racine normal, +Si vous voulez qu’une commande de plugin reste chargée à la demande dans le chemin normal de la CLI racine, fournissez des `descriptors` qui couvrent chaque racine de commande de premier niveau exposée par ce registrar. @@ -383,135 +395,134 @@ api.registerCli( ); ``` -Utilisez `commands` seul uniquement lorsque vous n’avez pas besoin d’un enregistrement CLI racine paresseux. -Ce chemin de compatibilité eager reste pris en charge, mais il n’installe pas -d’emplacements réservés adossés à des descripteurs pour le chargement paresseux au moment de l’analyse. +Utilisez `commands` seul uniquement lorsque vous n’avez pas besoin d’un enregistrement paresseux dans la CLI racine. +Ce chemin de compatibilité chargé de manière anticipée reste pris en charge, mais il n’installe pas +de placeholders adossés à des descripteurs pour le chargement paresseux au moment de l’analyse. -### Enregistrement du backend CLI +### Enregistrement de backend CLI -`api.registerCliBackend(...)` permet à un plugin de posséder la config par défaut d’un backend CLI -d’IA local tel que `codex-cli`. +`api.registerCliBackend(...)` permet à un plugin de posséder la configuration par défaut pour un +backend CLI IA local tel que `codex-cli`. -- L’`id` du backend devient le préfixe de fournisseur dans des références de modèle comme `codex-cli/gpt-5`. -- La `config` du backend utilise la même forme que `agents.defaults.cliBackends.`. -- La config utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.` sur la +- Le `id` du backend devient le préfixe du fournisseur dans des références de modèle comme `codex-cli/gpt-5`. +- Le `config` du backend utilise la même forme que `agents.defaults.cliBackends.`. +- La configuration utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.` par-dessus la valeur par défaut du plugin avant d’exécuter la CLI. - Utilisez `normalizeConfig` lorsqu’un backend a besoin de réécritures de compatibilité après fusion (par exemple pour normaliser d’anciennes formes de drapeaux). -### Emplacements exclusifs +### Slots exclusifs -| Méthode | Ce qu’elle enregistre | -| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts au prompt. | -| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée | -| `api.registerMemoryPromptSection(builder)` | Constructeur de section de prompt mémoire | -| `api.registerMemoryFlushPlan(resolver)` | Résolveur de plan de vidage mémoire | -| `api.registerMemoryRuntime(runtime)` | Adaptateur de runtime mémoire | +| Méthode | Ce qu’elle enregistre | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts au prompt. | +| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée | +| `api.registerMemoryPromptSection(builder)` | Constructeur de section de prompt mémoire | +| `api.registerMemoryFlushPlan(resolver)` | Résolveur de plan de vidage mémoire | +| `api.registerMemoryRuntime(runtime)` | Adaptateur d’exécution mémoire | -### Adaptateurs d’embedding mémoire +### Adaptateurs d’embeddings mémoire -| Méthode | Ce qu’elle enregistre | -| --------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d’embedding mémoire pour le plugin actif | +| Méthode | Ce qu’elle enregistre | +| ---------------------------------------------- | --------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d’embeddings mémoire pour le plugin actif | -- `registerMemoryCapability` est l’API de plugin mémoire exclusive préférée. +- `registerMemoryCapability` est l’API exclusive préférée pour les plugins mémoire. - `registerMemoryCapability` peut aussi exposer `publicArtifacts.listArtifacts(...)` - afin que des plugins compagnons puissent consommer les artefacts mémoire exportés via - `openclaw/plugin-sdk/memory-host-core` au lieu d’atteindre la disposition privée d’un - plugin mémoire spécifique. + afin que des plugins compagnons puissent consommer des artefacts mémoire exportés via + `openclaw/plugin-sdk/memory-host-core` au lieu d’atteindre la disposition privée + d’un plugin mémoire spécifique. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` et - `registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec les versions historiques. + `registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec l’héritage. - `registerMemoryEmbeddingProvider` permet au plugin mémoire actif d’enregistrer un - ou plusieurs identifiants d’adaptateur d’embedding (par exemple `openai`, `gemini` ou un identifiant - personnalisé défini par le plugin). -- La config utilisateur comme `agents.defaults.memorySearch.provider` et - `agents.defaults.memorySearch.fallback` se résout par rapport à ces identifiants - d’adaptateur enregistrés. + ou plusieurs identifiants d’adaptateur d’embeddings (par exemple `openai`, `gemini` ou un identifiant personnalisé + défini par le plugin). +- La configuration utilisateur, comme `agents.defaults.memorySearch.provider` et + `agents.defaults.memorySearch.fallback`, se résout par rapport à ces identifiants d’adaptateur enregistrés. ### Événements et cycle de vie -| Méthode | Ce qu’elle fait | -| ------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé | +| Méthode | Ce qu’elle fait | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé | | `api.onConversationBindingResolved(handler)` | Callback de liaison de conversation | ### Sémantique de décision des hooks -- `before_tool_call` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `before_tool_call` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge. -- `before_install` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `before_install` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge. -- `reply_dispatch` : retourner `{ handled: true, ... }` est terminal. Dès qu’un gestionnaire revendique la répartition, les gestionnaires de priorité inférieure et le chemin par défaut de répartition du modèle sont ignorés. -- `message_sending` : retourner `{ cancel: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. -- `message_sending` : retourner `{ cancel: false }` est traité comme aucune décision (comme si `cancel` était omis), et non comme une surcharge. +- `before_tool_call` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `before_tool_call` : retourner `{ block: false }` est traité comme aucune décision (identique à l’omission de `block`), et non comme une substitution. +- `before_install` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `before_install` : retourner `{ block: false }` est traité comme aucune décision (identique à l’omission de `block`), et non comme une substitution. +- `reply_dispatch` : retourner `{ handled: true, ... }` est terminal. Dès qu’un gestionnaire revendique la distribution, les gestionnaires de priorité inférieure et le chemin par défaut de distribution du modèle sont ignorés. +- `message_sending` : retourner `{ cancel: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés. +- `message_sending` : retourner `{ cancel: false }` est traité comme aucune décision (identique à l’omission de `cancel`), et non comme une substitution. ### Champs de l’objet API | Champ | Type | Description | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Identifiant du plugin | +| `api.id` | `string` | ID du plugin | | `api.name` | `string` | Nom d’affichage | -| `api.version` | `string?` | Version du plugin (facultatif) | -| `api.description` | `string?` | Description du plugin (facultatif) | +| `api.version` | `string?` | Version du plugin (facultative) | +| `api.description` | `string?` | Description du plugin (facultative) | | `api.source` | `string` | Chemin source du plugin | | `api.rootDir` | `string?` | Répertoire racine du plugin (facultatif) | -| `api.config` | `OpenClawConfig` | Instantané de config actuel (instantané actif en mémoire à l’exécution lorsqu’il est disponible) | -| `api.pluginConfig` | `Record` | Config spécifique au plugin depuis `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/fr/plugins/sdk-runtime) | +| `api.config` | `OpenClawConfig` | Instantané de configuration actuel (instantané d’exécution en mémoire actif lorsqu’il est disponible) | +| `api.pluginConfig` | `Record` | Configuration spécifique au plugin provenant de `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helpers d’exécution](/fr/plugins/sdk-runtime) | | `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant le chargement complet | +| `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant l’entrée complète | | `api.resolvePath(input)` | `(string) => string` | Résoudre un chemin relatif à la racine du plugin | ## Convention de module interne -Dans votre plugin, utilisez des fichiers barrel locaux pour les importations internes : +Dans votre plugin, utilisez des fichiers barrel locaux pour les imports internes : ``` my-plugin/ - api.ts # Exportations publiques pour les consommateurs externes - runtime-api.ts # Exportations de runtime réservées à l’interne + api.ts # Exports publics pour les consommateurs externes + runtime-api.ts # Exports d’exécution internes uniquement index.ts # Point d’entrée du plugin - setup-entry.ts # Entrée légère réservée à la configuration (facultatif) + setup-entry.ts # Entrée légère pour configuration uniquement (facultatif) ``` N’importez jamais votre propre plugin via `openclaw/plugin-sdk/` - depuis le code de production. Faites passer les importations internes par `./api.ts` ou - `./runtime-api.ts`. Le chemin du SDK est uniquement le contrat externe. + depuis le code de production. Faites passer les imports internes via `./api.ts` ou + `./runtime-api.ts`. Le chemin SDK est uniquement le contrat externe. -Les surfaces publiques des plugins intégrés chargées via façade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` et fichiers d’entrée publics similaires) préfèrent désormais -l’instantané actif de config d’exécution lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané -d’exécution n’existe encore, elles reviennent au fichier de config résolu sur le disque. +Les surfaces publiques de plugins intégrés chargées via façade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` et fichiers d’entrée publics similaires) privilégient désormais l’instantané +de configuration d’exécution actif lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané +d’exécution n’existe encore, elles reviennent au fichier de configuration résolu sur disque. -Les plugins de fournisseur peuvent aussi exposer un barrel de contrat local au plugin et étroit lorsqu’un -helper est intentionnellement spécifique à un fournisseur et n’a pas encore sa place dans un sous-chemin SDK -générique. Exemple intégré actuel : le fournisseur Anthropic conserve ses helpers de flux Claude -dans sa propre surface publique `api.ts` / `contract-api.ts` au lieu de +Les plugins de fournisseur peuvent également exposer un barrel de contrat local au plugin et étroit lorsqu’un +helper est volontairement spécifique au fournisseur et n’a pas encore sa place dans un sous-chemin SDK +générique. Exemple intégré actuel : le fournisseur Anthropic conserve ses helpers de flux Claude +dans son propre point d’entrée public `api.ts` / `contract-api.ts` au lieu de promouvoir la logique d’en-tête bêta Anthropic et `service_tier` dans un contrat générique `plugin-sdk/*`. -Autres exemples intégrés actuels : +Autres exemples intégrés actuels : -- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de fournisseur, +- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de fournisseur, des helpers de modèle par défaut et des constructeurs de fournisseur temps réel -- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de fournisseur ainsi que - des helpers d’intégration/de config +- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de fournisseur ainsi que + des helpers d’intégration/de configuration - Le code de production des extensions doit également éviter les importations `openclaw/plugin-sdk/`. + Le code de production d’extension doit également éviter les imports `openclaw/plugin-sdk/`. Si un helper est réellement partagé, promouvez-le vers un sous-chemin SDK neutre tel que `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou une autre surface orientée capacité au lieu de coupler deux plugins entre eux. -## Liens connexes +## Lié -- [Points d’entrée](/fr/plugins/sdk-entrypoints) — options de `definePluginEntry` et `defineChannelPluginEntry` -- [Helpers de runtime](/fr/plugins/sdk-runtime) — référence complète de l’espace de noms `api.runtime` -- [Configuration et config](/fr/plugins/sdk-setup) — empaquetage, manifestes, schémas de config +- [Points d’entrée](/fr/plugins/sdk-entrypoints) — options `definePluginEntry` et `defineChannelPluginEntry` +- [Helpers d’exécution](/fr/plugins/sdk-runtime) — référence complète de l’espace de noms `api.runtime` +- [Configuration et config](/fr/plugins/sdk-setup) — empaquetage, manifestes, schémas de configuration - [Tests](/fr/plugins/sdk-testing) — utilitaires de test et règles de lint - [Migration du SDK](/fr/plugins/sdk-migration) — migration depuis des surfaces obsolètes -- [Internes des plugins](/fr/plugins/architecture) — architecture détaillée et modèle de capacités +- [Internes des plugins](/fr/plugins/architecture) — architecture approfondie et modèle de capacité diff --git a/docs/fr/refactor/qa.md b/docs/fr/refactor/qa.md index 21c23baac..45ccc3f18 100644 --- a/docs/fr/refactor/qa.md +++ b/docs/fr/refactor/qa.md @@ -1,33 +1,34 @@ --- x-i18n: - generated_at: "2026-04-08T06:01:41Z" + generated_at: "2026-04-18T06:44:12Z" model: gpt-5.4 provider: openai - source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd + source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca source_path: refactor/qa.md workflow: 15 --- -# Refactorisation de la QA +# Refactorisation QA -Statut : migration fondamentale terminée. +Statut : la migration de base a été intégrée. ## Objectif -Faire évoluer la QA d’OpenClaw d’un modèle à définition répartie vers une source de vérité unique : +Faire évoluer la QA d’OpenClaw d’un modèle à définitions séparées vers une source de vérité unique : - métadonnées des scénarios - prompts envoyés au modèle - configuration et nettoyage - logique du harnais - assertions et critères de réussite -- artefacts et indications pour les rapports +- artefacts et indications de rapport -L’état final souhaité est un harnais QA générique qui charge de puissants fichiers de définition de scénario au lieu de coder en dur la majeure partie du comportement en TypeScript. +L’état final souhaité est un harnais QA générique qui charge des fichiers de définition de scénarios puissants au lieu de coder en dur la majeure partie du comportement en TypeScript. ## État actuel -La source principale de vérité se trouve désormais dans `qa/scenarios/index.md` plus un fichier par scénario sous `qa/scenarios/*.md`. +La source de vérité principale vit désormais dans `qa/scenarios/index.md` plus un fichier par +scénario sous `qa/scenarios//*.md`. Implémenté : @@ -35,30 +36,30 @@ Implémenté : - métadonnées canoniques du pack QA - identité de l’opérateur - mission de lancement -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` - un fichier Markdown par scénario - métadonnées du scénario - - liaisons de handlers - - configuration d’exécution spécifique au scénario + - associations de handlers + - configuration d’exécution propre au scénario - `extensions/qa-lab/src/scenario-catalog.ts` - parseur de pack Markdown + validation zod - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - rendu du plan à partir du pack Markdown - `extensions/qa-lab/src/qa-agent-workspace.ts` - - génère les fichiers de compatibilité initiaux plus `QA_SCENARIOS.md` + - alimente les fichiers de compatibilité générés plus `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - sélectionne les scénarios exécutables via des liaisons de handlers définies en Markdown -- Protocole QA bus + UI + - sélectionne les scénarios exécutables via des associations de handlers définies en Markdown +- Protocole de bus QA + interface utilisateur - pièces jointes inline génériques pour le rendu image/vidéo/audio/fichier -Surfaces encore réparties : +Surfaces encore séparées : - `extensions/qa-lab/src/suite.ts` - - possède encore la majeure partie de la logique des handlers exécutables personnalisés + - possède encore la majeure partie de la logique de handlers personnalisés exécutables - `extensions/qa-lab/src/report.ts` - dérive encore la structure du rapport à partir des sorties d’exécution -Ainsi, la répartition de la source de vérité est corrigée, mais l’exécution reste encore majoritairement appuyée sur des handlers plutôt que pleinement déclarative. +La séparation de la source de vérité est donc corrigée, mais l’exécution reste encore majoritairement pilotée par des handlers plutôt que pleinement déclarative. ## À quoi ressemble réellement la surface des scénarios @@ -66,39 +67,39 @@ La lecture de la suite actuelle montre quelques classes de scénarios distinctes ### Interaction simple -- référence de base du canal -- référence de base en message direct -- suivi dans un fil +- référence de canal +- référence DM +- suivi en fil - changement de modèle -- suivi après approbation -- réaction/modification/suppression +- poursuite après approbation +- réaction/édition/suppression ### Mutation de configuration et d’exécution -- désactivation de skill par patch de config -- config apply restart wake-up -- inversion de capacité après redémarrage de configuration +- correctif de config avec désactivation de skill +- réveil après redémarrage suite à application de config +- bascule de capacité après redémarrage de config - vérification de dérive de l’inventaire d’exécution -### Assertions sur système de fichiers et dépôt +### Assertions sur le système de fichiers et le dépôt - rapport de découverte source/docs -- build Lobster Invaders -- recherche d’artefact d’image générée +- build de Lobster Invaders +- recherche d’artefact d’image généré ### Orchestration de la mémoire -- rappel de mémoire -- outils de mémoire dans un contexte de canal -- repli en cas d’échec de la mémoire +- rappel mémoire +- outils mémoire dans le contexte du canal +- repli en cas d’échec mémoire - classement de la mémoire de session -- isolation de la mémoire par fil -- memory dreaming sweep +- isolation mémoire par fil +- balayage Dreaming de la mémoire ### Intégration d’outils et de plugins - appel MCP plugin-tools -- visibilité des Skills +- visibilité des skill - installation à chaud de skill - génération d’image native - aller-retour d’image @@ -107,31 +108,32 @@ La lecture de la suite actuelle montre quelques classes de scénarios distinctes ### Multi-tour et multi-acteur - transfert vers un sous-agent -- synthèse par fanout de sous-agents -- flux de style reprise après redémarrage +- synthèse par répartition sur plusieurs sous-agents +- flux de type récupération après redémarrage -Ces catégories sont importantes parce qu’elles pilotent les exigences du DSL. Une simple liste de prompt + texte attendu ne suffit pas. +Ces catégories sont importantes car elles déterminent les exigences du DSL. Une liste plate de prompt + texte attendu ne suffit pas. ## Orientation ### Source de vérité unique -Utiliser `qa/scenarios/index.md` plus `qa/scenarios/*.md` comme source de vérité rédigée. +Utiliser `qa/scenarios/index.md` plus `qa/scenarios//*.md` comme +source de vérité rédigée. Le pack doit rester : - lisible par un humain en revue -- analysable par machine -- suffisamment riche pour piloter : +- analysable par la machine +- assez riche pour piloter : - l’exécution de la suite - - l’initialisation de l’espace de travail QA - - les métadonnées de l’UI QA Lab - - les prompts de documentation/découverte + - le bootstrap de l’espace de travail QA + - les métadonnées de l’interface QA Lab + - les prompts de docs/découverte - la génération de rapports ### Format de rédaction préféré -Utiliser Markdown comme format de premier niveau, avec du YAML structuré à l’intérieur. +Utiliser Markdown comme format de haut niveau, avec du YAML structuré à l’intérieur. Forme recommandée : @@ -142,7 +144,7 @@ Forme recommandée : - tags - docs refs - code refs - - surcharges de modèle/fournisseur + - remplacements de modèle/provider - prérequis - sections en prose - objectif @@ -157,12 +159,12 @@ Forme recommandée : Cela apporte : - une meilleure lisibilité en PR qu’un énorme JSON -- un contexte plus riche qu’un simple YAML -- une analyse stricte et une validation zod +- un contexte plus riche que du YAML pur +- un parsing strict et une validation zod Le JSON brut n’est acceptable qu’en tant que forme intermédiaire générée. -## Forme proposée pour un fichier de scénario +## Forme proposée du fichier de scénario Exemple : @@ -237,7 +239,7 @@ Verify generated media is reattached on the follow-up turn. ## Capacités du runner que le DSL doit couvrir -D’après la suite actuelle, le runner générique a besoin de plus que de l’exécution de prompts. +D’après la suite actuelle, le runner générique a besoin de plus que l’exécution de prompts. ### Actions d’environnement et de configuration @@ -248,7 +250,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’ - `thread.create` - `workspace.writeSkill` -### Actions de tour d’agent +### Actions de tour agent - `agent.send` - `agent.wait` @@ -264,7 +266,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’ - `tools.effective` - `skills.status` -### Actions sur fichiers et artefacts +### Actions sur les fichiers et artefacts - `file.write` - `file.read` @@ -273,7 +275,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’ - `artifact.captureGeneratedImage` - `artifact.capturePath` -### Actions de mémoire et de cron +### Actions mémoire et Cron - `memory.indexForce` - `memory.searchCli` @@ -312,36 +314,36 @@ Exemples issus de la suite actuelle : - créer un fil, puis réutiliser `threadId` - créer une session, puis réutiliser `sessionKey` - générer une image, puis joindre le fichier au tour suivant -- générer une chaîne marqueur de réveil, puis vérifier qu’elle apparaît plus tard +- générer une chaîne de marqueur de réveil, puis vérifier qu’elle apparaît plus tard Capacités nécessaires : - `saveAs` - `${vars.name}` - `${artifacts.name}` -- références typées pour les chemins, clés de session, identifiants de fil, marqueurs, sorties d’outils +- références typées pour les chemins, clés de session, ids de fil, marqueurs, sorties d’outils -Sans prise en charge des variables, le harnais continuera à faire fuiter la logique des scénarios vers le TypeScript. +Sans prise en charge des variables, le harnais continuera à faire fuir la logique des scénarios vers TypeScript. ## Ce qui doit rester comme échappatoires -Un runner purement déclaratif n’est pas réaliste en phase 1. +Un runner entièrement déclaratif pur n’est pas réaliste en phase 1. Certains scénarios sont intrinsèquement lourds en orchestration : -- memory dreaming sweep -- config apply restart wake-up -- config restart capability flip -- résolution d’artefact d’image générée par horodatage/chemin +- balayage Dreaming de la mémoire +- réveil après redémarrage suite à application de config +- bascule de capacité après redémarrage de config +- résolution d’artefact d’image généré par horodatage/chemin - évaluation du rapport de découverte -Ils devraient pour l’instant utiliser des handlers personnalisés explicites. +Ceux-ci devraient utiliser pour l’instant des handlers personnalisés explicites. Règle recommandée : - 85-90 % déclaratif - étapes `customHandler` explicites pour le reste difficile -- uniquement des handlers personnalisés nommés et documentés +- seulement des handlers personnalisés nommés et documentés - aucun code inline anonyme dans le fichier de scénario Cela garde le moteur générique propre tout en permettant d’avancer. @@ -350,19 +352,19 @@ Cela garde le moteur générique propre tout en permettant d’avancer. ### Actuel -Le Markdown des scénarios est déjà la source de vérité pour : +Le Markdown de scénario est déjà la source de vérité pour : - l’exécution de la suite -- les fichiers d’initialisation de l’espace de travail -- le catalogue de scénarios de l’UI QA Lab +- les fichiers de bootstrap de l’espace de travail +- le catalogue de scénarios de l’interface QA Lab - les métadonnées de rapport - les prompts de découverte Compatibilité générée : -- l’espace de travail initial inclut toujours `QA_KICKOFF_TASK.md` -- l’espace de travail initial inclut toujours `QA_SCENARIO_PLAN.md` -- l’espace de travail initial inclut désormais aussi `QA_SCENARIOS.md` +- l’espace de travail initialisé inclut encore `QA_KICKOFF_TASK.md` +- l’espace de travail initialisé inclut encore `QA_SCENARIO_PLAN.md` +- l’espace de travail initialisé inclut désormais aussi `QA_SCENARIOS.md` ## Plan de refactorisation @@ -371,16 +373,16 @@ Compatibilité générée : Terminé. - ajout de `qa/scenarios/index.md` -- séparation des scénarios dans `qa/scenarios/*.md` -- ajout d’un parseur pour le contenu YAML Markdown nommé du pack +- découpage des scénarios dans `qa/scenarios//*.md` +- ajout d’un parseur pour le contenu de pack YAML Markdown nommé - validation avec zod -- basculement des consommateurs vers le pack analysé +- bascule des consommateurs vers le pack parsé - suppression de `qa/seed-scenarios.json` et `qa/QA_KICKOFF_TASK.md` au niveau du dépôt ### Phase 2 : moteur générique -- diviser `extensions/qa-lab/src/suite.ts` en : - - chargeur +- découper `extensions/qa-lab/src/suite.ts` en : + - loader - moteur - registre d’actions - registre d’assertions @@ -391,12 +393,12 @@ Livrable : - le moteur exécute des scénarios déclaratifs simples -Commencer par les scénarios qui sont principalement prompt + attente + assertion : +Commencer par des scénarios qui sont principalement prompt + attente + assertion : -- suivi dans un fil +- suivi en fil - compréhension d’image à partir d’une pièce jointe -- visibilité et invocation de Skills -- référence de base du canal +- visibilité et invocation de skill +- référence de canal Livrable : @@ -405,10 +407,10 @@ Livrable : ### Phase 4 : migrer les scénarios intermédiaires - aller-retour de génération d’image -- outils de mémoire dans un contexte de canal +- outils mémoire dans le contexte du canal - classement de la mémoire de session - transfert vers un sous-agent -- synthèse par fanout de sous-agents +- synthèse par répartition sur plusieurs sous-agents Livrable : @@ -416,24 +418,24 @@ Livrable : ### Phase 5 : conserver les scénarios difficiles sur des handlers personnalisés -- memory dreaming sweep -- config apply restart wake-up -- config restart capability flip -- dérive d’inventaire d’exécution +- balayage Dreaming de la mémoire +- réveil après redémarrage suite à application de config +- bascule de capacité après redémarrage de config +- dérive de l’inventaire d’exécution Livrable : -- même format de rédaction, mais avec des blocs d’étapes personnalisées explicites là où nécessaire +- même format de rédaction, mais avec des blocs d’étapes personnalisées explicites quand nécessaire ### Phase 6 : supprimer la map de scénarios codée en dur -Quand la couverture du pack sera suffisamment bonne : +Une fois que la couverture du pack est suffisamment bonne : -- supprimer la majeure partie du branchement TypeScript spécifique aux scénarios dans `extensions/qa-lab/src/suite.ts` +- supprimer la majeure partie des branchements TypeScript spécifiques aux scénarios de `extensions/qa-lab/src/suite.ts` -## Faux Slack / prise en charge des médias riches +## Prise en charge du faux Slack / des médias enrichis -Le QA bus actuel est centré sur le texte. +Le bus QA actuel est centré sur le texte. Fichiers concernés : @@ -443,7 +445,7 @@ Fichiers concernés : - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -Aujourd’hui, le QA bus prend en charge : +Aujourd’hui, le bus QA prend en charge : - texte - réactions @@ -453,7 +455,7 @@ Il ne modélise pas encore les pièces jointes média inline. ### Contrat de transport nécessaire -Ajouter un modèle générique de pièce jointe QA bus : +Ajouter un modèle générique de pièce jointe au bus QA : ```ts type QaBusAttachment = { @@ -478,55 +480,55 @@ Puis ajouter `attachments?: QaBusAttachment[]` à : - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### Pourquoi commencer par du générique +### Pourquoi d’abord générique -Ne construisez pas un modèle média réservé à Slack. +Ne pas construire un modèle de média propre à Slack uniquement. À la place : -- un modèle de transport QA générique -- plusieurs moteurs de rendu par-dessus - - le chat actuel de QA Lab - - un futur faux Slack web +- un modèle de transport QA générique unique +- plusieurs moteurs de rendu au-dessus + - le chat QA Lab actuel + - un futur faux web Slack - toute autre vue de faux transport -Cela évite la logique dupliquée et permet aux scénarios média de rester indépendants du transport. +Cela évite la duplication de logique et permet aux scénarios média de rester indépendants du transport. -### Travail UI nécessaire +### Travail d’interface nécessaire -Mettre à jour l’UI QA pour afficher : +Mettre à jour l’interface QA pour afficher : - aperçu d’image inline - lecteur audio inline - lecteur vidéo inline -- puce de pièce jointe de fichier +- puce de pièce jointe fichier -L’UI actuelle peut déjà afficher les fils et les réactions, donc le rendu des pièces jointes devrait pouvoir se superposer au même modèle de carte de message. +L’interface actuelle sait déjà afficher les fils et les réactions, donc le rendu des pièces jointes devrait se superposer au même modèle de carte de message. -### Travail sur les scénarios rendu possible par le transport média +### Travail de scénario rendu possible par le transport média -Une fois que les pièces jointes circuleront dans le QA bus, nous pourrons ajouter des scénarios de faux chat plus riches : +Une fois que les pièces jointes circulent via le bus QA, nous pouvons ajouter des scénarios de faux chat plus riches : - réponse avec image inline dans un faux Slack -- compréhension d’une pièce jointe audio -- compréhension d’une pièce jointe vidéo +- compréhension de pièce jointe audio +- compréhension de pièce jointe vidéo - ordre mixte des pièces jointes - réponse dans un fil avec conservation du média ## Recommandation -Le prochain bloc d’implémentation devrait être : +Le prochain lot d’implémentation devrait être : -1. ajouter un chargeur de scénarios Markdown + un schéma zod +1. ajouter un chargeur de scénarios Markdown + schéma zod 2. générer le catalogue actuel à partir du Markdown 3. migrer d’abord quelques scénarios simples -4. ajouter la prise en charge générique des pièces jointes QA bus -5. afficher une image inline dans l’UI QA +4. ajouter la prise en charge générique des pièces jointes du bus QA +5. afficher l’image inline dans l’interface QA 6. puis étendre à l’audio et à la vidéo -C’est le plus petit chemin qui prouve les deux objectifs : +C’est le plus petit chemin qui valide les deux objectifs : -- QA générique définie en Markdown +- QA générique définie par Markdown - surfaces de messagerie simulées plus riches ## Questions ouvertes @@ -534,5 +536,5 @@ C’est le plus petit chemin qui prouve les deux objectifs : - si les fichiers de scénario doivent autoriser des modèles de prompt Markdown embarqués avec interpolation de variables - si setup/cleanup doivent être des sections nommées ou simplement des listes d’actions ordonnées - si les références d’artefacts doivent être fortement typées dans le schéma ou basées sur des chaînes -- si les handlers personnalisés doivent vivre dans un seul registre ou dans des registres par surface +- si les handlers personnalisés doivent vivre dans un registre unique ou dans des registres par surface - si le fichier de compatibilité JSON généré doit rester versionné pendant la migration