From aa426faafd9d0b211d9528e9855057b900031850 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 15:25:08 +0000 Subject: [PATCH] chore(i18n): refresh fr translations --- docs/fr/gateway/configuration-reference.md | 1076 +++++++------ .../gpt54-codex-agentic-parity-maintainers.md | 174 ++ docs/fr/help/gpt54-codex-agentic-parity.md | 229 +++ docs/fr/plugins/architecture.md | 1415 ++++++++--------- docs/fr/plugins/manifest.md | 453 ++++-- docs/fr/reference/rich-output-protocol.md | 60 + docs/fr/tools/video-generation.md | 286 ++-- 7 files changed, 2125 insertions(+), 1568 deletions(-) create mode 100644 docs/fr/help/gpt54-codex-agentic-parity-maintainers.md create mode 100644 docs/fr/help/gpt54-codex-agentic-parity.md create mode 100644 docs/fr/reference/rich-output-protocol.md diff --git a/docs/fr/gateway/configuration-reference.md b/docs/fr/gateway/configuration-reference.md index 793b806df..b542e2b47 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 des champs de configuration ou des valeurs par défaut - - Vous validez les blocs de configuration de canal, de modèle, de passerelle ou d’outil -summary: Référence de configuration de la passerelle pour les clés principales d’OpenClaw, 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 passerelle ou d’outil +summary: Référence de configuration de la passerelle pour les clés, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes principaux d’OpenClaw title: Référence de configuration x-i18n: - generated_at: "2026-04-11T02:44:19Z" + generated_at: "2026-04-11T15:16:00Z" model: gpt-5.4 provider: openai - source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 + source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,19 +17,19 @@ x-i18n: Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâches, consultez [Configuration](/fr/gateway/configuration). -Cette page couvre les principales surfaces de configuration d’OpenClaw et renvoie vers d’autres pages lorsqu’un sous-système a sa propre référence plus détaillée. Elle **n’essaie pas** d’intégrer sur une seule page tous les catalogues de commandes propres aux canaux/plugins ni tous les réglages détaillés de mémoire/QMD. +Cette page couvre les principales surfaces de configuration d’OpenClaw et renvoie vers d’autres pages lorsqu’un sous-système dispose de sa propre référence plus détaillée. Elle **n’essaie pas** d’inclure sur une seule page chaque catalogue de commandes détenu par un canal/plugin ni chaque paramètre avancé de mémoire/QMD. -Source de vérité dans le code : +Source de vérité du code : -- `openclaw config schema` affiche le schéma JSON actif utilisé pour la validation et l’interface de contrôle, avec les métadonnées des bundles/plugins/canaux fusionnées lorsqu’elles sont disponibles +- `openclaw config schema` affiche le schéma JSON actif utilisé pour la validation et l’interface de contrôle, avec les métadonnées fusionnées des bundles/plugins/canaux lorsqu’elles sont disponibles - `config.schema.lookup` renvoie un nœud de schéma limité à un chemin pour les outils d’exploration détaillée -- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hachage de référence des documents de configuration par rapport à la surface actuelle du schéma +- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hash de référence de la documentation de configuration par rapport à la surface actuelle du schéma Références détaillées dédiées : -- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` et la configuration du dreaming sous `plugins.entries.memory-core.config.dreaming` +- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` et la configuration de rêverie sous `plugins.entries.memory-core.config.dreaming` - [Commandes slash](/fr/tools/slash-commands) pour le catalogue actuel des commandes intégrées + groupées -- les pages du canal/plugin propriétaire pour les surfaces de commande spécifiques à chaque canal +- pages du canal/plugin propriétaire pour les surfaces de commandes spécifiques aux canaux Le format de configuration est **JSON5** (commentaires + virgules finales autorisés). Tous les champs sont facultatifs — OpenClaw utilise des valeurs par défaut sûres lorsqu’ils sont omis. @@ -39,16 +39,16 @@ Le format de configuration est **JSON5** (commentaires + virgules finales autori Chaque canal démarre automatiquement lorsque sa section de configuration existe (sauf si `enabled: false`). -### Accès DM et groupe +### Accès aux messages privés et aux groupes -Tous les canaux prennent en charge des politiques de DM et des politiques de groupe : +Tous les canaux prennent en charge des politiques de messages privés et des politiques de groupe : -| Politique DM | Comportement | -| -------------------- | ------------------------------------------------------------- | +| Politique 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 magasin d’autorisations appairées) | -| `open` | Autoriser tous les DM entrants (nécessite `allowFrom: ["*"]`) | -| `disabled` | Ignorer tous les DM entrants | +| `allowlist` | Uniquement les expéditeurs dans `allowFrom` (ou le stockage d’autorisations appairées) | +| `open` | Autoriser tous les messages privés entrants (nécessite `allowFrom: ["*"]`) | +| `disabled` | Ignorer tous les messages privés entrants | | Politique de groupe | Comportement | | ---------------------- | ------------------------------------------------------ | @@ -59,12 +59,12 @@ Tous les canaux prennent en charge des politiques de DM et des politiques de gro `channels.defaults.groupPolicy` définit la valeur par défaut lorsque le `groupPolicy` d’un fournisseur n’est pas défini. 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 à l’exécution revient à `allowlist` (échec fermé) avec un avertissement au démarrage. +Si un bloc de fournisseur est entièrement absent (`channels.` absent), la politique de groupe à l’exécution revient à `allowlist` (échec 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 de canal s’applique lorsqu’une session n’a pas déjà un remplacement de modèle (par exemple, défini via `/model`). +Utilisez `channels.modelByChannel` pour épingler des ID de canal spécifiques à un modèle. Les valeurs acceptent `provider/model` ou des alias de modèles configurés. Le mappage de canal s’applique lorsqu’une session n’a pas déjà un remplacement de modèle (par exemple, défini via `/model`). ```json5 { @@ -87,7 +87,7 @@ Utilisez `channels.modelByChannel` pour épingler des ID de canal spécifiques ### Valeurs par défaut des canaux et heartbeat -Utilisez `channels.defaults` pour partager les comportements de politique de groupe et de heartbeat entre fournisseurs : +Utilisez `channels.defaults` pour le comportement partagé de politique de groupe et de heartbeat entre les fournisseurs : ```json5 { @@ -106,14 +106,14 @@ Utilisez `channels.defaults` pour partager les comportements de politique de gro ``` - `channels.defaults.groupPolicy` : politique de groupe de secours 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, inclut tout le contexte cité/de fil/d’historique), `allowlist` (inclut 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 sains des canaux dans la sortie du heartbeat. -- `channels.defaults.heartbeat.showAlerts` : inclure les états dégradés/en erreur dans la sortie du heartbeat. +- `channels.defaults.contextVisibility` : mode de visibilité du contexte supplémentaire par défaut pour tous les canaux. Valeurs : `all` (par défaut, inclure tout le contexte cité/de fil/d’historique), `allowlist` (inclure uniquement le contexte provenant d’expéditeurs autorisés), `allowlist_quote` (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk` : inclure les états des canaux en bonne santé dans la sortie de heartbeat. +- `channels.defaults.heartbeat.showAlerts` : inclure les états dégradés/en erreur dans la sortie de heartbeat. - `channels.defaults.heartbeat.useIndicator` : afficher une sortie de heartbeat compacte de type indicateur. ### WhatsApp -WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. +WhatsApp fonctionne via le canal web de la passerelle (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. ```json5 { @@ -166,7 +166,7 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar - Les commandes sortantes utilisent par défaut le compte `default` s’il est présent ; sinon, le premier ID de compte configuré (trié). - `channels.whatsapp.defaultAccount` facultatif remplace cette sélection de compte par défaut de secours lorsqu’il correspond à un ID de compte configuré. -- Le répertoire d’authentification Baileys historique à compte unique est migré par `openclaw doctor` vers `whatsapp/default`. +- L’ancien répertoire d’authentification Baileys mono-compte est migré par `openclaw doctor` vers `whatsapp/default`. - Remplacements par compte : `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,11 +225,11 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar } ``` -- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier normal uniquement ; les liens symboliques sont rejetés), avec `TELEGRAM_BOT_TOKEN` comme secours pour le compte par défaut. +- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier standard uniquement ; les liens symboliques sont refusés), avec `TELEGRAM_BOT_TOKEN` comme solution de secours 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 secours ; `openclaw doctor` avertit lorsque cette valeur est absente ou invalide. -- `configWrites: false` bloque les écritures de configuration initiées par Telegram (migrations d’ID de supergroupe, `/config set|unset`). -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les sujets de forum (utilisez la forme 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). +- 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 secours ; `openclaw doctor` avertit lorsque cette valeur manque ou est invalide. +- `configWrites: false` bloque les écritures de configuration initiées depuis 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 `chatId:topic:topicId` canonique 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). @@ -333,36 +333,36 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar } ``` -- Jeton : `channels.discord.token`, avec `DISCORD_BOT_TOKEN` comme secours 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 continuent de provenir du compte sélectionné dans l’instantané actif à l’exécution. +- Jeton : `channels.discord.token`, avec `DISCORD_BOT_TOKEN` comme solution de secours 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é actif à l’exécution. - `channels.discord.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. -- Utilisez `user:` (DM) ou `channel:` (canal de serveur) pour les cibles de livraison ; les ID numériques seuls sont rejetés. -- Les slugs de serveurs sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom slugifié (sans `#`). Préférez les ID de serveur. +- Utilisez `user:` (DM) ou `channel:` (canal de serveur) pour les cibles de livraison ; les ID numériques seuls sont refusés. +- Les slugs de serveur sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom converti en slug (sans `#`). Préférez les ID de serveur. - Les messages rédigés par des bots sont ignorés par défaut. `allowBots: true` les active ; utilisez `allowBots: "mentions"` pour n’accepter que les messages de bots qui mentionnent le bot (les propres messages restent filtrés). -- `channels.discord.guilds..ignoreOtherMentions` (et les remplacements au niveau du canal) supprime les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here). -- `maxLinesPerMessage` (17 par défaut) découpe les messages longs même lorsqu’ils restent sous 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) découpe les messages hauts même lorsqu’ils sont inférieurs à 2000 caractères. - `channels.discord.threadBindings` contrôle le routage lié aux fils Discord : - - `enabled` : remplacement Discord pour les fonctionnalités de session liées aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, et la livraison/le routage liés) - - `idleHours` : remplacement Discord pour la désactivation 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/la liaison automatiques de fils avec `sessions_spawn({ thread: true })` + - `enabled` : remplacement Discord pour les fonctionnalités de session liées aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` et la livraison/le routage liés) + - `idleHours` : remplacement Discord pour le retrait automatique du focus après inactivité en heures (`0` désactive) + - `maxAgeHours` : remplacement Discord pour l’âge maximal strict en heures (`0` désactive) + - `spawnSubagentSessions` : option d’activation pour la création/liaison automatique de fil par `sessions_spawn({ thread: true })` - Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et les fils (utilisez l’ID du canal/fil dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` définit la couleur d’accentuation pour les conteneurs Discord components v2. -- `channels.discord.voice` active les conversations dans les canaux vocaux Discord et les remplacements facultatifs d’auto-connexion + TTS. +- `channels.discord.ui.components.accentColor` définit la couleur d’accent pour les conteneurs de composants v2 Discord. +- `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 de récupérer la réception vocale en quittant/rejoignant une session vocale après des échecs répétés de déchiffrement. +- OpenClaw tente en plus 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 vers la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et autorise des remplacements facultatifs du texte de statut. -- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance sur nom/tag modifiables (mode de compatibilité de dernier recours). +- `channels.discord.autoPresence` mappe la disponibilité d’exécution sur 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 modifiable (mode de compatibilité de secours). - `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 depuis `approvers` ou `commands.ownerAllowFrom`. - - `approvers` : ID d’utilisateurs Discord autorisés à approuver les demandes d’exécution. Utilise `commands.ownerAllowFrom` comme secours lorsqu’il est omis. - - `agentFilter` : liste d’autorisations facultative des ID d’agents. Omettez pour transférer les approbations pour tous les agents. + - `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. Revient à `commands.ownerAllowFrom` lorsqu’il est omis. + - `agentFilter` : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents. - `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex). - - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut) envoie aux DM des approbateurs, `"channel"` envoie 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 DM d’approbation après approbation, refus ou expiration. + - `target` : emplacement d’envoi des 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` : lorsque défini à `true`, supprime les DM d’approbation après approbation, refus ou expiration. -**Modes de notification de réaction :** `off` (aucun), `own` (messages du bot, par défaut), `all` (tous les messages), `allowlist` (depuis `guilds..users` sur tous les messages). +**Modes de notification des réactions :** `off` (aucun), `own` (messages du bot, par défaut), `all` (tous les messages), `allowlist` (depuis `guilds..users` sur tous les messages). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar } ``` -- JSON du compte de service : en ligne (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`). -- SecretRef du compte de service est également pris en charge (`serviceAccountRef`). -- Secours par variables d’environnement : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON du compte de service : en ligne (`serviceAccount`) ou via fichier (`serviceAccountFile`). +- SecretRef de compte de service également pris en charge (`serviceAccountRef`). +- Solutions de secours d’environnement : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Utilisez `spaces/` ou `users/` pour les cibles de livraison. -- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance sur principal email modifiable (mode de compatibilité de dernier recours). +- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance par principal d’e-mail modifiable (mode de compatibilité de secours). ### Slack @@ -464,39 +464,34 @@ WhatsApp s’exécute via le canal web de la passerelle (Baileys Web). Il démar } ``` -- **Le mode Socket** nécessite à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le secours 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 en texte brut - 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, - `signingSecretStatus`. `configured_unavailable` signifie que le compte est - configuré via SecretRef mais que le chemin de commande/d’exécution actuel n’a pas pu - résoudre la valeur du secret. -- `configWrites: false` bloque les écritures de configuration initiées par Slack. +- Le **mode socket** nécessite à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` comme solutions de secours d’environnement du compte par défaut). +- Le **mode HTTP** nécessite `botToken` plus `signingSecret` (à la racine ou par compte). +- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes en texte brut ou des objets SecretRef. +- Les instantanés de compte Slack exposent des champs par identifiant d’authentification 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 initiées depuis 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. +- `channels.slack.streaming.mode` est la clé canonique du mode de flux Slack. `channels.slack.streaming.nativeTransport` contrôle le transport natif de flux de Slack. Les anciennes valeurs `streamMode`, booléennes `streaming` et `nativeStreaming` sont migrées automatiquement. - Utilisez `user:` (DM) ou `channel:` pour les cibles de livraison. -**Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). +**Modes de notification des réactions :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). **Isolation des sessions de fil :** `thread.historyScope` est par fil (par défaut) ou partagé sur le canal. `thread.inheritParent` copie la transcription du canal parent vers les nouveaux fils. -- Le streaming natif Slack ainsi que l’état de fil Slack de type assistant « is typing... » nécessitent une cible de réponse dans un fil. Les DM de premier niveau restent hors fil par défaut ; ils utilisent donc `typingReaction` ou la livraison normale au lieu de l’aperçu de style fil. -- `typingReaction` ajoute une réaction temporaire au message Slack entrant pendant l’exécution d’une réponse, puis la supprime une fois terminée. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`. +- Le flux natif Slack ainsi que l’état de fil Slack de type assistant « is typing... » nécessitent une cible de réponse dans un fil. Les DM de niveau supérieur restent hors fil par défaut ; ils utilisent donc `typingReaction` ou la livraison normale au lieu de l’aperçu de type fil. +- `typingReaction` ajoute une réaction temporaire au message Slack entrant pendant l’exécution d’une réponse, puis la supprime à la fin. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`. - `channels.slack.execApprovals` : livraison native Slack des approbations d’exécution et autorisation des approbateurs. Même schéma que Discord : `enabled` (`true`/`false`/`"auto"`), `approvers` (ID d’utilisateurs Slack), `agentFilter`, `sessionFilter` et `target` (`"dm"`, `"channel"` ou `"both"`). -| Groupe d’actions | Par défaut | Notes | -| ---------------- | ---------- | ------------------------- | +| Groupe d’actions | Par défaut | 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 les membres | -| emojiList | activé | Liste d’emojis personnalisés | +| emojiList | activé | Liste des emoji personnalisés | ### Mattermost -Mattermost est distribué comme plugin : `openclaw plugins install @openclaw/mattermost`. +Mattermost est fourni comme plugin : `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -526,22 +521,17 @@ Mattermost est distribué comme plugin : `openclaw plugins install @openclaw/mat } ``` -Modes de discussion : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par le préfixe de déclenchement). +Modes de discussion : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe déclencheur). 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 de la passerelle OpenClaw et être accessible depuis le serveur Mattermost. -- Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés - par Mattermost lors de l’enregistrement 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 exiger que - `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/domaine du rappel. - Utilisez des valeurs d’hôte/domaine, pas des URL complètes. -- `channels.mattermost.configWrites` : autoriser ou refuser les écritures de configuration initiées par Mattermost. +- `commands.callbackPath` doit être un chemin (par exemple `/api/channels/mattermost/command`), et non une URL complète. +- `commands.callbackUrl` doit résoudre vers le point de terminaison de la passerelle OpenClaw et être accessible depuis le serveur Mattermost. +- Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés par Mattermost lors de l’enregistrement 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 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 initiées depuis Mattermost. - `channels.mattermost.requireMention` : exiger une `@mention` avant de répondre dans les canaux. -- `channels.mattermost.groups..requireMention` : remplacement du filtrage par mention au niveau du canal (`"*"` pour la valeur par défaut). +- `channels.mattermost.groups..requireMention` : remplacement par canal du filtrage par mention (`"*"` pour la valeur par défaut). - `channels.mattermost.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. ### Signal @@ -563,10 +553,10 @@ Lorsque les commandes natives Mattermost sont activées : } ``` -**Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). +**Modes de notification des réactions :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). - `channels.signal.account` : épingler le démarrage du canal à une identité de compte Signal spécifique. -- `channels.signal.configWrites` : autoriser ou refuser les écritures de configuration initiées par Signal. +- `channels.signal.configWrites` : autoriser ou refuser les écritures de configuration initiées depuis Signal. - `channels.signal.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. ### BlueBubbles @@ -588,7 +578,7 @@ BlueBubbles est le chemin iMessage recommandé (pris en charge par plugin, confi - Chemins de clés principaux couverts ici : `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. - `channels.bluebubbles.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier les conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle BlueBubbles ou une chaîne cible (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique partagée des champs : [Agents ACP](/fr/tools/acp-agents#channel-specific-settings). +- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier des conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle ou une chaîne cible BlueBubbles (`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). - La configuration complète du canal BlueBubbles est documentée dans [BlueBubbles](/fr/channels/bluebubbles). ### iMessage @@ -621,11 +611,11 @@ OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port n’est req - 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. +- `cliPath` peut pointer vers un wrapper SSH ; définissez `remoteHost` (`host` ou `user@host`) pour la récupération SCP des pièces jointes. - `attachmentRoots` et `remoteAttachmentRoots` restreignent les chemins des pièces jointes entrantes (par défaut : `/Users/*/Library/Messages/Attachments`). -- SCP utilise une vérification stricte des clés d’hôte ; assurez-vous donc que la clé de l’hôte relais existe déjà dans `~/.ssh/known_hosts`. -- `channels.imessage.configWrites` : autoriser ou refuser les écritures de configuration initiées par iMessage. -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier les 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). +- SCP utilise une vérification stricte des clés d’hôte ; assurez-vous donc que la clé d’hôte du relais existe déjà dans `~/.ssh/known_hosts`. +- `channels.imessage.configWrites` : autoriser ou refuser les écritures de configuration initiées depuis 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). @@ -669,19 +659,19 @@ Matrix est pris en charge par extension et configuré sous `channels.matrix`. ``` - L’authentification par jeton utilise `accessToken` ; l’authentification par mot de passe utilise `userId` + `password`. -- `channels.matrix.proxy` route le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` fait passer le trafic HTTP Matrix par un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`. - `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette activation réseau sont des contrôles indépendants. - `channels.matrix.defaultAccount` sélectionne le compte préféré dans les configurations multi-comptes. -- `channels.matrix.autoJoin` vaut par défaut `off`, de sorte que les salons invités et les nouvelles invitations de type DM sont ignorés jusqu’à ce que vous définissiez `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.autoJoin` vaut `off` par défaut ; les salons invités et les nouvelles invitations de type DM sont donc 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 depuis `approvers` ou `commands.ownerAllowFrom`. + - `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 Matrix (par ex. `@owner:example.org`) autorisés à approuver les demandes d’exécution. - - `agentFilter` : liste d’autorisations facultative des ID d’agents. Omettez pour transférer les approbations pour tous les agents. + - `agentFilter` : liste d’autorisations facultative d’ID d’agent. Omettez-la pour transférer les approbations pour tous les agents. - `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex). - - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`. + - `target` : emplacement d’envoi des invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`. - Remplacements par compte : `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` contrôle la façon dont les DM Matrix sont regroupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon DM. -- Les sondes d’état Matrix et les recherches live dans l’annuaire utilisent la même politique de proxy que le trafic à l’exécution. +- `channels.matrix.dm.sessionScope` contrôle comment les DM Matrix sont regroupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon DM. +- Les sondes d’état Matrix et les recherches 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 les exemples de configuration sont documentés dans [Matrix](/fr/channels/matrix). ### Microsoft Teams @@ -758,23 +748,23 @@ Exécutez plusieurs comptes par canal (chacun avec son propre `accountId`) : - Les jetons d’environnement s’appliquent uniquement au compte **default**. - Les paramètres de base du canal s’appliquent à tous les comptes sauf remplacement par compte. - 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 de canal) alors que vous êtes encore sur une configuration de canal de niveau supérieur à compte unique, OpenClaw promeut d’abord les valeurs de compte unique de niveau supérieur propres au compte dans la map des comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent dans `channels..accounts.default` ; Matrix peut à la place préserver une cible nommée/par défaut existante correspondante. +- Si vous ajoutez un compte non par défaut via `openclaw channels add` (ou l’onboarding de canal) alors que vous utilisez encore une configuration de canal mono-compte au niveau supérieur, OpenClaw promeut d’abord les valeurs mono-compte de niveau supérieur portées par le compte dans la carte des comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent dans `channels..accounts.default` ; Matrix peut à la place préserver une cible nommée/par défaut existante correspondante. - Les liaisons existantes limitées au canal (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons limitées au compte restent facultatives. -- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs de compte unique de niveau supérieur propres au compte dans le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut à la place préserver une cible nommée/par défaut existante correspondante. +- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs mono-compte de niveau supérieur portées par le compte dans le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut à la place préserver 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 comme `channels.` et documentés dans leurs pages de canal dédiées (par exemple Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat et Twitch). Consultez l’index complet des canaux : [Canaux](/fr/channels). ### Filtrage par mention dans les discussions de groupe -Les messages de groupe exigent par défaut **une mention requise** (métadonnées de mention ou motifs regex sûrs). S’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage. +Les messages de groupe exigent par défaut **une mention requise** (mention de métadonnées ou motifs regex sûrs). Cela s’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage. **Types de mention :** -- **Mentions de métadonnées** : @-mentions natives de la plateforme. Ignorées en mode discussion avec soi-même 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. +- **Mentions de métadonnées** : @-mentions natives de la plateforme. Ignorées en mode auto-discussion 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. - Le filtrage par mention n’est appliqué que lorsque la détection est possible (mentions natives ou au moins un motif). ```json5 @@ -788,7 +778,7 @@ Les messages de groupe exigent par défaut **une mention requise** (métadonnée } ``` -`messages.groupChat.historyLimit` définit la valeur par défaut globale. Les canaux peuvent la remplacer avec `channels..historyLimit` (ou par compte). Définissez `0` pour désactiver. +`messages.groupChat.historyLimit` définit la valeur globale par défaut. Les canaux peuvent la remplacer avec `channels..historyLimit` (ou par compte). Définissez `0` pour désactiver. #### Limites d’historique DM @@ -809,9 +799,9 @@ Résolution : remplacement par DM → valeur par défaut du fournisseur → aucu 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 de texte) : +Incluez votre propre numéro dans `allowFrom` pour activer le mode auto-discussion (ignore les @-mentions natives, répond uniquement aux motifs textuels) : ```json5 { @@ -861,38 +851,38 @@ 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, consultez [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 aux canaux/plugins 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). +- Ce bloc configure les surfaces de commandes. Pour le catalogue actuel des commandes intégrées + groupées, consultez [Commandes slash](/fr/tools/slash-commands). +- Cette page est une **référence des clés de configuration**, et non le catalogue complet des commandes. Les commandes détenues par des canaux/plugins 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, laisse Slack désactivé. -- `nativeSkills: "auto"` active les commandes de Skills natives pour Discord/Telegram, laisse Slack désactivé. +- `native: "auto"` active les commandes natives pour Discord/Telegram et laisse Slack désactivé. +- `nativeSkills: "auto"` active les commandes natives 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 des Skills natives par canal avec `channels..commands.nativeSkills`. +- Remplacez l’enregistrement natif des Skills par canal avec `channels..commands.nativeSkills`. - `channels.telegram.customCommands` ajoute des entrées supplémentaires au menu du bot Telegram. -- `bash: true` active `! ` pour le shell hôte. Nécessite `tools.elevated.enabled` et que l’expéditeur figure dans `tools.elevated.allowFrom.`. -- `config: true` active `/config` (lit/écrit `openclaw.json`). Pour les clients `chat.send` de la passerelle, les écritures persistantes `/config set|unset` nécessitent également `operator.admin` ; la commande en lecture seule `/config show` reste disponible pour les clients opérateur normaux avec portée d’écriture. -- `mcp: true` active `/mcp` pour la configuration des serveurs MCP gérés par OpenClaw sous `mcp.servers`. +- `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 de passerelle `chat.send`, les écritures persistantes `/config set|unset` exigent également `operator.admin` ; la commande en lecture seule `/config show` reste disponible pour les clients opérateur normaux avec portée d’écriture. +- `mcp: true` active `/mcp` pour la configuration de serveur MCP gérée par OpenClaw sous `mcp.servers`. - `plugins: true` active `/plugins` pour la découverte, l’installation et les contrôles d’activation/désactivation des plugins. - `channels..configWrites` contrôle les mutations de configuration par canal (par défaut : true). - Pour les canaux multi-comptes, `channels..accounts..configWrites` contrôle également les écritures ciblant ce compte (par exemple `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `restart: false` désactive `/restart` et les actions de l’outil de redémarrage de la passerelle. Par défaut : `true`. -- `ownerAllowFrom` est la liste d’autorisations explicite des propriétaires pour les commandes/outils réservés au propriétaire. Elle est distincte de `allowFrom`. -- `ownerDisplay: "hash"` hache les ID des propriétaires dans le prompt système. Définissez `ownerDisplaySecret` pour contrôler le hachage. -- `allowFrom` est défini par fournisseur. Lorsqu’il est défini, c’est la **seule** source d’autorisation (les listes d’autorisations/appairages du canal et `useAccessGroups` sont ignorés). +- `restart: false` désactive `/restart` et les actions d’outil de redémarrage de la passerelle. Par défaut : `true`. +- `ownerAllowFrom` est la liste d’autorisations explicite du propriétaire pour les commandes/outils réservés au propriétaire. Elle est distincte de `allowFrom`. +- `ownerDisplay: "hash"` hache les ID de 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’autorisations/appairages de canal et `useAccessGroups` sont ignorés). - `useAccessGroups: false` permet aux commandes de contourner les politiques des groupes d’accès lorsque `allowFrom` n’est pas défini. -- Correspondance de la documentation des commandes : +- Carte de la documentation des commandes : - catalogue intégré + groupé : [Commandes slash](/fr/tools/slash-commands) - - surfaces de commande spécifiques à chaque canal : [Canaux](/fr/channels) + - surfaces de commandes spécifiques aux canaux : [Canaux](/fr/channels) - commandes QQ Bot : [QQ Bot](/fr/channels/qqbot) - commandes d’appairage : [Appairage](/fr/channels/pairing) - commande de carte LINE : [LINE](/fr/channels/line) - - dreaming de la mémoire : [Dreaming](/fr/concepts/dreaming) + - rêverie mémoire : [Dreaming](/fr/concepts/dreaming) --- -## Valeurs par défaut des agents +## Valeurs par défaut de l’agent ### `agents.defaults.workspace` @@ -916,7 +906,7 @@ Racine de dépôt facultative affichée dans la ligne Runtime du prompt système ### `agents.defaults.skills` -Liste d’autorisations par défaut des Skills, facultative, pour les agents qui ne définissent pas +Liste d’autorisations Skills par défaut facultative pour les agents qui ne définissent pas `agents.list[].skills`. ```json5 @@ -924,19 +914,19 @@ Liste d’autorisations par défaut des Skills, facultative, pour les agents qui 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 skill ], }, } ``` -- Omettez `agents.defaults.skills` pour des Skills sans restriction par défaut. +- Omettez `agents.defaults.skills` pour des Skills non restreints par défaut. - Omettez `agents.list[].skills` pour hériter des valeurs par défaut. - Définissez `agents.list[].skills: []` pour n’avoir aucun Skills. -- Une liste non vide dans `agents.list[].skills` constitue l’ensemble final pour cet agent ; elle - ne fusionne pas avec les valeurs par défaut. +- Une liste `agents.list[].skills` non vide constitue l’ensemble final pour cet agent ; elle + n’est pas fusionnée avec les valeurs par défaut. ### `agents.defaults.skipBootstrap` @@ -950,9 +940,9 @@ Désactive la création automatique des fichiers bootstrap de l’espace de trav ### `agents.defaults.contextInjection` -Contrôle quand les fichiers bootstrap de l’espace de travail sont injectés dans le prompt système. Par défaut : `"always"`. +Contrôle quand les fichiers bootstrap de l’espace de travail sont injectés dans le prompt système. Valeur par défaut : `"always"`. -- `"continuation-skip"` : les tours de continuation sûrs (après une réponse d’assistant terminée) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille du prompt. Les exécutions de 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 assistant terminée) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille du prompt. Les exécutions de heartbeat et les nouvelles tentatives après compactage reconstruisent toujours le contexte. ```json5 { @@ -972,7 +962,7 @@ Nombre maximal de caractères par fichier bootstrap de l’espace de travail ava ### `agents.defaults.bootstrapTotalMaxChars` -Nombre total maximal de caractères injectés dans l’ensemble des fichiers bootstrap de l’espace de travail. Par défaut : `150000`. +Nombre maximal total de caractères injectés dans l’ensemble des fichiers bootstrap de l’espace de travail. Par défaut : `150000`. ```json5 { @@ -997,10 +987,10 @@ Par défaut : `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Taille maximale en pixels du côté le plus long d’une image dans les blocs image du transcript/outils avant les appels au fournisseur. +Taille maximale en pixels du côté le plus long d’une image dans les blocs image de transcription/outil avant les appels au 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 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 de la charge utile pour les exécutions riches en captures d’écran. Des valeurs plus élevées conservent davantage de détails visuels. ```json5 @@ -1011,7 +1001,7 @@ Des valeurs plus élevées conservent davantage de détails visuels. ### `agents.defaults.userTimezone` -Fuseau horaire pour le contexte du prompt système (pas les horodatages des messages). Utilise le fuseau horaire de l’hôte comme secours. +Fuseau horaire pour le contexte du prompt système (pas pour les horodatages des messages). Revient au fuseau horaire de l’hôte par défaut. ```json5 { @@ -1021,7 +1011,7 @@ Fuseau horaire pour le contexte du prompt système (pas les horodatages des mess ### `agents.defaults.timeFormat` -Format de l’heure dans le prompt système. Par défaut : `auto` (préférence de l’OS). +Format de l’heure dans le prompt système. Par défaut : `auto` (préférence du système d’exploitation). ```json5 { @@ -1059,7 +1049,7 @@ Format de l’heure dans le prompt système. Par défaut : `auto` (préférence primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // paramètres globaux par défaut du fournisseur embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1080,47 +1070,46 @@ Format de l’heure dans le prompt système. Par défaut : `auto` (préférence - `model` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - La forme chaîne définit uniquement le modèle principal. - - La forme objet définit le modèle principal plus les modèles de basculement ordonnés. + - La forme objet définit le modèle principal ainsi que des modèles de basculement ordonnés. - `imageModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par le chemin de l’outil `image` comme configuration de modèle de vision. - - Également utilisé comme routage de secours lorsque le modèle sélectionné/par défaut ne peut pas accepter d’entrée image. + - Utilisé par le chemin d’outil `image` comme configuration de modèle de vision. + - Également utilisé comme routage de secours lorsque le modèle sélectionné/par défaut ne peut pas accepter une entrée image. - `imageGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par la capacité partagée de génération d’images et toute future surface d’outil/plugin qui génère des images. + - Utilisé par la capacité partagée de génération d’images ainsi que 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’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’images enregistrés restants dans l’ordre des ID de fournisseur. + - Si vous sélectionnez directement un provider/model, 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 toujours 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 de musique et 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 de musique enregistrés restants 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. + - Si omis, `music_generate` peut toujours 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 provider/model, 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 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 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 de niveau fournisseur `size`, `aspectRatio`, `resolution`, `audio` et `watermark`. + - Si omis, `video_generate` peut toujours 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 provider/model, 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, 10 secondes de durée, ainsi que 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 résolu de la session/par défaut. -- `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas transmis au moment de l’appel. -- `pdfMaxPages` : nombre maximal de pages par défaut pris en compte par le mode de secours d’extraction dans l’outil `pdf`. -- `verboseDefault` : niveau détaillé par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`. + - 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 passé à l’appel. +- `pdfMaxPages` : nombre maximal de pages pris en compte par défaut par le mode d’extraction de secours dans l’outil `pdf`. +- `verboseDefault` : niveau verbose 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, donc préférez `provider/model` explicite). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient au premier fournisseur/modèle configuré au lieu de présenter une valeur par défaut obsolète d’un fournisseur supprimé. +- `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 avec un 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 `provider/model` explicite). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient au premier provider/model configuré au lieu d’exposer une valeur par défaut obsolète d’un fournisseur supprimé. - `models` : le catalogue de modèles configuré et la liste d’autorisations pour `/model`. Chaque entrée peut inclure `alias` (raccourci) et `params` (spécifiques au fournisseur, par exemple `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params` : paramètres de fournisseur globaux par défaut appliqués à tous les modèles. À définir sous `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 prompts](/fr/reference/prompt-caching) pour les détails. -- `embeddedHarness` : politique par défaut du runtime bas niveau d’agent embarqué. Utilisez `runtime: "auto"` pour laisser les harnais de plugin enregistrés revendiquer les modèles pris en charge, `runtime: "pi"` pour forcer le harnais PI intégré, ou un ID de harnais enregistré tel que `runtime: "codex"`. Définissez `fallback: "none"` pour désactiver le secours PI automatique. -- Les rédacteurs de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de secours) enregistrent la forme objet canonique et préservent les listes de secours existantes lorsque c’est possible. +- `params` : paramètres globaux par défaut du fournisseur appliqués à tous les modèles. Définissez-les 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 clé par clé. Voir [Prompt Caching](/fr/reference/prompt-caching) pour plus de détails. +- `embeddedHarness` : politique par défaut du runtime agent embarqué de bas niveau. Utilisez `runtime: "auto"` pour laisser les harnesses de plugin enregistrés réclamer 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 retour automatique vers PI. +- Les écrivains de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de secours) enregistrent la forme objet canonique et préservent autant que possible les listes de basculement existantes. - `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 bas niveau exécute les tours d’agent embarqués. +`embeddedHarness` contrôle quel exécuteur de bas niveau exécute 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 harnais natif, comme le harnais groupé -de serveur d’application Codex. +Utilisez-le lorsqu’un plugin approuvé fournit un harness natif, comme le harness app-server Codex groupé. ```json5 { @@ -1136,13 +1125,13 @@ de serveur d’application Codex. } ``` -- `runtime` : `"auto"`, `"pi"` ou un ID de harnais de plugin enregistré. Le plugin Codex groupé enregistre `codex`. -- `fallback` : `"pi"` ou `"none"`. `"pi"` conserve le harnais PI intégré comme secours de compatibilité. `"none"` fait échouer la sélection d’un harnais de plugin manquant ou non pris 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 secours PI pour ce processus. -- Pour des déploiements Codex uniquement, définissez `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` et `embeddedHarness.fallback: "none"`. -- Cela contrôle uniquement le harnais de discussion embarqué. 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. +- `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 solution de compatibilité de secours. `"none"` fait échouer la sélection d’un harness de plugin manquant ou non pris en charge au lieu d’utiliser PI silencieusement. +- Remplacements par variable d’environnement : `OPENCLAW_AGENT_RUNTIME=` remplace `runtime` ; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` désactive le retour vers 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 contrôle uniquement le harness de discussion embarqué. La génération de médias, la vision, le PDF, la musique, la vidéo et le TTS utilisent toujours leurs paramètres de provider/model. -**Raccourcis d’alias intégrés** (s’appliquent uniquement lorsque le modèle figure dans `agents.defaults.models`) : +**Raccourcis d’alias intégrés** (s’appliquent uniquement lorsque le modèle est dans `agents.defaults.models`) : | Alias | Modèle | | ------------------- | -------------------------------------- | @@ -1158,12 +1147,12 @@ de serveur d’application Codex. 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’outils. Définissez `agents.defaults.models["zai/"].params.tool_stream` à `false` pour le désactiver. -Les modèles Anthropic Claude 4.6 utilisent par défaut le mode thinking `adaptive` lorsqu’aucun niveau thinking explicite n’est défini. +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 de réflexion explicite n’est défini. ### `agents.defaults.cliBackends` -Backends CLI facultatifs pour les exécutions de secours texte uniquement (sans appels d’outils). Utile comme solution de repli lorsque les fournisseurs API échouent. +Backends CLI facultatifs pour les exécutions de secours texte seul (sans appels d’outil). Utile comme solution de repli lorsque les fournisseurs d’API échouent. ```json5 { @@ -1193,11 +1182,11 @@ Backends CLI facultatifs pour les exécutions de secours texte uniquement (sans - 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 fichier. +- Le passage d’images est pris en charge lorsque `imageArg` accepte des chemins de fichiers. ### `agents.defaults.systemPromptOverride` -Remplace tout le 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. +Remplace l’intégralité du prompt système assemblé par OpenClaw par une chaîne fixe. Définissez-le au niveau par défaut (`agents.defaults.systemPromptOverride`) ou par agent (`agents.list[].systemPromptOverride`). Les valeurs par agent ont priorité ; une valeur vide ou ne contenant que des espaces est ignorée. Utile pour des expériences contrôlées sur les prompts. ```json5 { @@ -1239,14 +1228,14 @@ Exécutions périodiques de 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 du prompt système et ignore l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Par défaut : `true`. -- `suppressToolErrorWarnings` : lorsque true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions de heartbeat. -- `timeoutSeconds` : temps maximal, en secondes, autorisé pour un tour d’agent heartbeat avant son interruption. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. -- `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison vers des cibles directes. `block` supprime la livraison vers des cibles directes et émet `reason=dm-blocked`. -- `lightContext` : lorsque true, les exécutions de 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 de heartbeat s’exécute dans une session fraîche sans historique de conversation préalable. Même modèle d’isolation que cron `sessionTarget: "isolated"`. Réduit le coût en jetons par heartbeat d’environ 100K à environ 2-5K jetons. +- `includeSystemPromptSection` : lorsque défini à false, omet la section Heartbeat du prompt système et ignore l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Par défaut : `true`. +- `suppressToolErrorWarnings` : lorsque défini à true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions de 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/DM. `allow` (par défaut) autorise la livraison vers une cible directe. `block` supprime la livraison vers une cible directe et émet `reason=dm-blocked`. +- `lightContext` : lorsque défini à true, les exécutions de heartbeat utilisent un contexte bootstrap léger et conservent uniquement `HEARTBEAT.md` parmi les fichiers bootstrap de l’espace de travail. +- `isolatedSession` : lorsque défini à true, chaque heartbeat s’exécute dans une session fraîche sans historique de conversation antérieur. Même schéma d’isolation que 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 heartbeats. -- Les heartbeats exécutent des tours complets d’agent — des intervalles plus courts consomment davantage de jetons. +- Les heartbeats exécutent des tours d’agent complets — des intervalles plus courts consomment plus de jetons. ### `agents.defaults.compaction` @@ -1278,17 +1267,17 @@ Exécutions périodiques de 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é à 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 seule opération de compaction avant qu’OpenClaw ne l’interrompe. Par défaut : `900`. -- `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` préfixe les consignes intégrées de conservation des identifiants opaques pendant le résumé de 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 de AGENTS.md à réinjecter après compaction. Valeur par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il 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 secours historique. -- `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 la compaction automatique pour stocker des souvenirs durables. Ignoré lorsque l’espace de travail est en lecture seule. +- `postCompactionSections` : noms facultatifs de sections H2/H3 d’AGENTS.md à réinjecter après compaction. Valeur par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il est non défini ou explicitement défini à cette paire par défaut, les anciens en-têtes `Every Session`/`Safety` sont également acceptés comme solution de secours héritée. +- `model` : remplacement facultatif `provider/model-id` utilisé 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 défini à `true`, envoie un bref avis à 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 la compaction automatique afin de stocker les souvenirs durables. Ignoré lorsque l’espace de travail est en lecture seule. ### `agents.defaults.contextPruning` -Élague les **anciens résultats d’outils** du contexte en mémoire avant l’envoi au LLM. **Ne modifie pas** l’historique de session sur disque. +Épure les **anciens résultats d’outil** du contexte en mémoire avant envoi au LLM. Ne **modifie pas** l’historique de session sur disque. ```json5 { @@ -1312,23 +1301,23 @@ Exécutions périodiques de heartbeat. -- `mode: "cache-ttl"` active les passes d’élagage. -- `ttl` contrôle la fréquence maximale à laquelle l’élagage peut s’exécuter à nouveau (après le dernier accès au cache). -- L’élagage réduit d’abord partiellement les résultats d’outil surdimensionnés, puis efface complètement les anciens résultats d’outil si nécessaire. +- `mode: "cache-ttl"` active les passes d’épuration. +- `ttl` contrôle à quelle fréquence l’épuration peut être relancée (après le dernier accès au cache). +- L’épuration tronque légèrement d’abord les résultats d’outil surdimensionnés, puis efface complètement les anciens résultats d’outil si nécessaire. -**Réduction partielle** conserve le début + la fin et insère `...` au milieu. +**Troncature légère** conserve le début + la fin et insère `...` au milieu. -**Effacement complet** remplace l’ensemble du résultat d’outil par l’espace réservé. +**Effacement complet** remplace l’intégralité du résultat d’outil par l’espace réservé. Remarques : -- Les blocs d’image ne sont jamais réduits/effacés. -- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptes exacts de jetons. -- S’il existe moins de `keepLastAssistants` messages assistant, l’élagage est ignoré. +- Les blocs image ne sont jamais tronqués/effacés. +- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptages exacts de jetons. +- Si moins de `keepLastAssistants` messages assistant existent, l’épuration est ignorée. -Voir [Élagage de session](/fr/concepts/session-pruning) pour les détails du comportement. +Voir [Épuration de session](/fr/concepts/session-pruning) pour les détails de comportement. ### Streaming par blocs @@ -1348,11 +1337,11 @@ Voir [Élagage de session](/fr/concepts/session-pruning) pour les détails du co - Les canaux autres que Telegram nécessitent `*.blockStreaming: true` explicite pour activer les réponses par blocs. - Remplacements par canal : `channels..blockStreamingCoalesce` (et variantes par compte). Signal/Slack/Discord/Google Chat utilisent par défaut `minChars: 1500`. -- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500ms. Remplacement par agent : `agents.list[].humanDelay`. +- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500 ms. Remplacement par agent : `agents.list[].humanDelay`. -Voir [Streaming](/fr/concepts/streaming) pour le comportement et les détails de découpage. +Voir [Streaming](/fr/concepts/streaming) pour les détails de comportement + découpage. -### Indicateurs de frappe +### Indicateurs de saisie ```json5 { @@ -1368,7 +1357,7 @@ Voir [Streaming](/fr/concepts/streaming) pour le comportement et 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 frappe](/fr/concepts/typing-indicators). +Voir [Indicateurs de saisie](/fr/concepts/typing-indicators). @@ -1474,47 +1463,47 @@ Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sa **Backend :** - `docker` : runtime Docker local (par défaut) -- `ssh` : runtime distant générique adossé à SSH +- `ssh` : runtime distant générique pris en charge par SSH - `openshell` : runtime OpenShell -Lorsque `backend: "openshell"` est sélectionné, les paramètres propres au runtime sont déplacés vers +Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques au runtime sont déplacés vers `plugins.entries.openshell.config`. **Configuration du backend SSH :** -- `target` : cible SSH sous la forme `user@host[:port]` -- `command` : commande du client SSH (par défaut : `ssh`) -- `workspaceRoot` : racine distante absolue utilisée pour les espaces de travail selon le scope +- `target` : cible SSH au format `user@host[:port]` +- `command` : commande client SSH (par défaut : `ssh`) +- `workspaceRoot` : racine distante absolue utilisée pour les espaces de travail selon la portée - `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants transmis à OpenSSH -- `identityData` / `certificateData` / `knownHostsData` : contenus en ligne ou SecretRefs que OpenClaw matérialise dans des fichiers temporaires à l’exécution -- `strictHostKeyChecking` / `updateHostKeys` : réglages de politique des clés d’hôte 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 -**Priorité de l’authentification SSH :** +**Priorité d’authentification SSH :** - `identityData` a priorité sur `identityFile` - `certificateData` a priorité sur `certificateFile` - `knownHostsData` a priorité sur `knownHostsFile` -- Les valeurs `*Data` adossées à SecretRef sont résolues à partir de l’instantané actif du runtime des secrets avant le démarrage de la session sandbox +- Les valeurs `*Data` basées sur SecretRef sont résolues depuis l’instantané actif du runtime des secrets avant le démarrage de la session sandbox **Comportement du backend SSH :** - initialise l’espace de travail distant une fois après création ou recréation -- conserve ensuite l’espace de travail SSH distant comme source canonique +- conserve ensuite l’espace de travail SSH distant comme canonique - route `exec`, les outils de fichiers et les chemins média via SSH -- ne synchronise pas automatiquement les modifications distantes vers l’hôte +- 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 :** -- `none` : espace de travail sandbox par scope 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` : espace de travail sandbox selon la portée sous `~/.openclaw/sandboxes` +- `ro` : espace de travail sandbox à `/workspace`, espace de travail agent monté en lecture seule à `/agent` +- `rw` : espace de travail agent monté en lecture/écriture à `/workspace` -**Scope :** +**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 inter-sessions) +- `shared` : conteneur et espace de travail partagés (pas d’isolation inter-sessions) **Configuration du plugin OpenShell :** @@ -1544,30 +1533,30 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres propres au run **Mode OpenShell :** -- `mirror` : initialise le distant depuis le local avant `exec`, synchronise en retour après `exec` ; l’espace de travail local reste canonique -- `remote` : initialise le distant une fois lors de la création du sandbox, puis conserve l’espace de travail distant comme source canonique +- `mirror` : initialise le distant depuis le local avant `exec`, puis resynchronise après `exec` ; l’espace de travail local reste canonique +- `remote` : initialise le distant une fois lors de la création du sandbox, puis conserve l’espace de travail distant comme canonique -En mode `remote`, les modifications locales sur l’hôte effectuées en dehors d’OpenClaw ne sont pas synchronisées automatiquement dans le sandbox après l’étape d’initialisation. -Le transport se fait via SSH dans 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 hors d’OpenClaw ne sont pas automatiquement synchronisées dans le sandbox après l’étape d’initialisation. +Le transport se fait via SSH dans le sandbox OpenShell, mais le plugin possède le cycle de vie du sandbox et la synchronisation miroir facultative. -**`setupCommand`** s’exécute une fois après la création du conteneur (via `sh -lc`). Nécessite une sortie réseau, une racine inscriptible 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` (solution de secours). **Les pièces jointes entrantes** sont placées dans `media/inbound/*` dans l’espace de travail actif. **`docker.binds`** monte des répertoires hôte supplémentaires ; les montages globaux et par agent sont fusionnés. **Navigateur sandboxé** (`sandbox.browser.enabled`) : Chromium + CDP dans un conteneur. L’URL noVNC est injectée dans le prompt système. Ne nécessite pas `browser.enabled` dans `openclaw.json`. -L’accès observateur noVNC utilise par défaut l’authentification VNC et OpenClaw émet une URL à jeton de courte durée (au lieu d’exposer le mot de passe dans l’URL partagée). +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. +- `allowHostControl: false` (par défaut) empêche les sessions sandboxées de cibler le navigateur hôte. - `network` vaut par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez `bridge` uniquement lorsque vous souhaitez explicitement une connectivité bridge globale. -- `cdpSourceRange` restreint éventuellement l’entrée CDP en bordure du conteneur à une plage CIDR (par exemple `172.21.0.1/32`). +- `cdpSourceRange` restreint facultativement l’entrée CDP à la bordure du conteneur à une plage CIDR (par exemple `172.21.0.1/32`). - `sandbox.browser.binds` monte des répertoires hôte supplémentaires uniquement dans le conteneur du navigateur sandboxé. Lorsqu’il est défini (y compris `[]`), il remplace `docker.binds` pour le conteneur du navigateur. -- Les valeurs par défaut de lancement sont définies dans `scripts/sandbox-browser-entrypoint.sh` et ajustées pour les hôtes de conteneurs : +- Les valeurs par défaut de lancement sont définies dans `scripts/sandbox-browser-entrypoint.sh` et ajustées pour les hôtes conteneurisés : - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1587,24 +1576,24 @@ L’accès observateur noVNC utilise par défaut l’authentification VNC 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_EXTENSIONS=0` réactive les extensions si votre workflow + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si l’usage de 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. - - ainsi que `--no-sandbox` et `--disable-setuid-sandbox` lorsque `noSandbox` est activé. - - Les valeurs par défaut constituent la base de l’image conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur. + - plus `--no-sandbox` et `--disable-setuid-sandbox` lorsque `noSandbox` est activé. + - Les valeurs par défaut sont la base de l’image du conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur. -Le sandboxing du navigateur et `sandbox.docker.binds` sont réservés à Docker. +Le sandboxing du navigateur et `sandbox.docker.binds` sont 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) @@ -1657,20 +1646,20 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id` : ID d’agent stable (obligatoire). -- `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 celle par défaut. -- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les fallbacks globaux). Les tâches cron qui ne remplacent que `primary` héritent toujours des fallbacks par défaut sauf si vous définissez `fallbacks: []`. -- `params` : paramètres de flux par agent fusionnés au-dessus de l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez ceci pour des remplacements propres à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles. -- `skills` : liste d’autorisations 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 de les fusionner, et `[]` signifie aucun Skills. -- `thinkingDefault` : niveau thinking facultatif par défaut par agent (`off | minimal | low | medium | high | xhigh | adaptive`). Remplace `agents.defaults.thinkingDefault` pour cet agent lorsqu’aucun remplacement par message ou session n’est défini. -- `reasoningDefault` : visibilité du raisonnement facultative par défaut par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement du raisonnement 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 du mode rapide par message ou session n’est défini. -- `embeddedHarness` : remplacement facultatif de la politique de harnais bas niveau par agent. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent uniquement Codex tandis que les autres agents conservent le fallback PI par défaut. -- `runtime` : descripteur facultatif de runtime par agent. Utilisez `type: "acp"` avec les valeurs par défaut de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions de harnais ACP. +- `default` : lorsque plusieurs sont définis, le premier l’emporte (un avertissement est enregistré). Si aucun n’est défini, la première entrée de la liste est l’agent par défaut. +- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les basculements globaux). Les tâches cron qui ne remplacent que `primary` héritent toujours des basculements par défaut sauf si vous définissez `fallbacks: []`. +- `params` : paramètres de flux par agent fusionnés au-dessus de l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez-les pour des remplacements propres à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles. +- `skills` : liste d’autorisations Skills facultative par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsqu’il est défini ; une liste explicite remplace les valeurs par défaut au lieu d’être fusionnée, et `[]` signifie aucun Skills. +- `thinkingDefault` : niveau 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é reasoning par défaut facultative par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement 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 du mode rapide par message ou session n’est défini. +- `embeddedHarness` : remplacement facultatif par agent de la politique de harness de bas niveau. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent uniquement Codex tandis que les autres agents conservent le retour PI par défaut. +- `runtime` : descripteur de runtime facultatif par agent. Utilisez `type: "acp"` avec les valeurs par défaut `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions de harness ACP. - `identity.avatar` : chemin relatif à l’espace de travail, 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’autorisations des ID d’agents pour `sessions_spawn` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement). +- `identity` dérive des valeurs par défaut : `ackReaction` à partir de `emoji`, `mentionPatterns` à partir de `name`/`emoji`. +- `subagents.allowAgents` : liste d’autorisations des ID d’agent pour `sessions_spawn` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement). - Garde d’héritage du sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans sandbox. -- `subagents.requireAgentId` : lorsque true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite de profil ; par défaut : false). +- `subagents.requireAgentId` : lorsque défini à true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite du profil ; par défaut : false). --- @@ -1695,7 +1684,7 @@ Exécutez plusieurs agents isolés dans une seule passerelle. Voir [Multi-Agent] ### Champs de correspondance des liaisons -- `type` (facultatif) : `route` pour le routage normal (type manquant = route par défaut), `acp` pour les liaisons de conversation ACP persistantes. +- `type` (facultatif) : `route` pour le routage normal (type manquant = route par défaut), `acp` pour les liaisons persistantes de conversation ACP. - `match.channel` (obligatoire) - `match.accountId` (facultatif ; `*` = n’importe quel compte ; omis = compte par défaut) - `match.peer` (facultatif ; `{ kind: direct|group|channel, id }`) @@ -1707,13 +1696,13 @@ Exécutez plusieurs agents isolés dans une seule passerelle. Voir [Multi-Agent] 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exact, sans peer/guild/team) +4. `match.accountId` (exact, sans pair/serveur/équipe) 5. `match.accountId: "*"` (à l’échelle du canal) 6. Agent par défaut Dans chaque niveau, la première entrée `bindings` correspondante l’emporte. -Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre des niveaux de 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 de niveaux de routage ci-dessus. ### Profils d’accès par agent @@ -1810,7 +1799,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conver -Voir [Sandbox multi-agent et outils](/fr/tools/multi-agent-sandbox-tools) pour les détails de priorité. +Voir [Sandbox et outils multi-agent](/fr/tools/multi-agent-sandbox-tools) pour les détails de priorité. --- @@ -1863,35 +1852,35 @@ Voir [Sandbox multi-agent et outils](/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 reçoit une session isolée dans un contexte de canal. +- **`scope`** : stratégie de regroupement de session de base 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 souhaité). -- **`dmScope`** : façon dont les DM sont regroupés. +- **`dmScope`** : comment les DM sont regroupés. - `main` : tous les DM partagent la session principale. - - `per-peer` : isolation par ID d’expéditeur entre les canaux. - - `per-channel-peer` : isolation par canal + expéditeur (recommandé pour les boîtes de réception multi-utilisateurs). - - `per-account-channel-peer` : isolation par compte + canal + expéditeur (recommandé pour le multi-compte). -- **`identityLinks`** : mappe les ID canoniques vers des pairs préfixés par fournisseur pour le partage de session entre canaux. -- **`reset`** : politique principale de réinitialisation. `daily` réinitialise à `atHour` en heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte. + - `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-canaux. +- **`reset`** : politique principale de réinitialisation. `daily` réinitialise à `atHour` heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte. - **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien alias `dm` est accepté pour `direct`. -- **`parentForkMaxTokens`** : nombre maximal de `totalTokens` de la session parente autorisé lors de la création d’une session de fil bifurquée (par défaut `100000`). - - Si le `totalTokens` parent dépasse 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 garde et toujours autoriser la bifurcation depuis le parent. -- **`mainKey`** : champ historique. Le runtime utilise toujours `"main"` pour le compartiment principal de discussion directe. -- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse en retour entre agents pendant les échanges agent à agent (entier, plage : `0`–`5`). `0` désactive l’enchaînement ping-pong. +- **`parentForkMaxTokens`** : nombre maximal de `totalTokens` de session parente autorisé lors de la création d’une session de fil forkée (par défaut `100000`). + - Si `totalTokens` du parent est supérieur à cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription du parent. + - Définissez `0` pour désactiver cette protection et toujours autoriser le fork de la session parente. +- **`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 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’ancien alias `dm`), `keyPrefix` ou `rawKeyPrefix`. Le premier refus l’emporte. -- **`maintenance`** : contrôles de nettoyage + rétention du magasin de sessions. - - `mode` : `warn` n’émet que des avertissements ; `enforce` applique le nettoyage. +- **`maintenance`** : contrôles de nettoyage + de rétention du stockage de sessions. + - `mode` : `warn` émet uniquement des avertissements ; `enforce` applique le nettoyage. - `pruneAfter` : seuil d’ancienneté pour les entrées obsolètes (par défaut `30d`). - `maxEntries` : nombre maximal d’entrées dans `sessions.json` (par défaut `500`). - - `rotateBytes` : fait tourner `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`). - - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Utilise `pruneAfter` par défaut ; 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. - - `enabled` : interrupteur principal par défaut (les fournisseurs peuvent remplacer ; Discord utilise `channels.discord.threadBindings.enabled`) - - `idleHours` : désactivation automatique du focus après inactivité, par défaut, 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) + - `rotateBytes` : fait pivoter `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 de 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 globales par défaut pour les fonctionnalités de session liées aux fils. + - `enabled` : interrupteur maître par défaut (les fournisseurs peuvent 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) @@ -1931,16 +1920,16 @@ Voir [Sandbox multi-agent et outils](/fr/tools/multi-agent-sandbox-tools) pour l Remplacements par canal/compte : `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Résolution (le plus spécifique l’emporte) : compte → canal → global. `""` désactive et arrête la cascade. `"auto"` dérive `[{identity.name}]`. +Résolution (la plus spécifique l’emporte) : compte → canal → global. `""` désactive et arrête la cascade. `"auto"` dérive `[{identity.name}]`. **Variables de modèle :** -| Variable | Description | Exemple | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nom court du modèle | `claude-opus-4-6` | +| Variable | Description | Exemple | +| ----------------- | ----------------------- | --------------------------- | +| `{model}` | Nom court du modèle | `claude-opus-4-6` | | `{modelFull}` | Identifiant complet du modèle | `anthropic/claude-opus-4-6` | -| `{provider}` | Nom du fournisseur | `anthropic` | -| `{thinkingLevel}` | Niveau thinking actuel | `high`, `low`, `off` | +| `{provider}` | Nom du fournisseur | `anthropic` | +| `{thinkingLevel}` | Niveau de réflexion actuel | `high`, `low`, `off` | | `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) | Les variables sont insensibles à la casse. `{think}` est un alias de `{thinkingLevel}`. @@ -1949,16 +1938,16 @@ Les variables sont insensibles à la casse. `{think}` est un alias de `{thinking - Utilise par défaut `identity.emoji` de l’agent actif, sinon `"👀"`. Définissez `""` pour désactiver. - Remplacements par canal : `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordre de résolution : compte → canal → `messages.ackReaction` → secours d’identité. +- Ordre de résolution : compte → canal → `messages.ackReaction` → secours via identity. - Portée : `group-mentions` (par défaut), `group-all`, `direct`, `all`. -- `removeAckAfterReply` : supprime l’accusé après réponse sur Slack, Discord et Telegram. -- `messages.statusReactions.enabled` : active les réactions d’état du cycle de vie sur Slack, Discord et Telegram. - Sur Slack et Discord, une valeur non définie maintient les réactions d’état activées lorsque les réactions d’accusé sont actives. - Sur Telegram, définissez-la explicitement à `true` pour activer les réactions d’état du cycle de vie. +- `removeAckAfterReply` supprime l’accusé après 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, une valeur non définie conserve les réactions d’état activées lorsque les réactions d’accusé sont actives. + Sur Telegram, définissez-le explicitement sur `true` pour activer les réactions d’état de cycle de vie. -### Anti-rebond entrant +### Debounce entrant -Regroupe les messages texte rapides d’un même expéditeur en un seul tour d’agent. Les médias/pièces jointes sont vidés immédiatement. Les commandes de contrôle contournent l’anti-rebond. +Regroupe les messages textuels rapides du même expéditeur en un seul tour d’agent. Les médias/pièces jointes déclenchent immédiatement l’envoi. Les commandes de contrôle contournent le debounce. ### TTS (synthèse vocale) @@ -2003,9 +1992,9 @@ Regroupe les messages texte rapides d’un même expéditeur en un seul tour d - `auto` contrôle le mode auto-TTS par défaut : `off`, `always`, `inbound` ou `tagged`. `/tts on|off` peut remplacer les préférences locales, et `/tts status` affiche l’état effectif. - `summaryModel` remplace `agents.defaults.model.primary` pour le résumé automatique. -- `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut `false` par défaut (activation explicite). -- Les clés API utilisent `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY` comme secours. -- `openai.baseUrl` remplace le point de terminaison TTS OpenAI. L’ordre de résolution est : config, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`. +- `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut `false` par défaut (activation explicite requise). +- Les clés API utilisent `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY` comme solutions de secours. +- `openai.baseUrl` remplace le point de terminaison TTS OpenAI. L’ordre de résolution est : configuration, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`. - Lorsque `openai.baseUrl` pointe vers un point de terminaison non OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix. --- @@ -2038,11 +2027,11 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android). - `talk.provider` doit correspondre à une clé dans `talk.providers` lorsque plusieurs fournisseurs Talk sont configurés. - Les anciennes clés Talk plates (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sont uniquement conservées pour compatibilité et sont migrées automatiquement vers `talk.providers.`. -- Les ID de voix utilisent `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID` comme secours. +- Les ID de voix utilisent `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID` comme solution de secours. - `providers.*.apiKey` accepte des chaînes en texte brut ou des objets SecretRef. -- Le secours `ELEVENLABS_API_KEY` ne s’applique que lorsqu’aucune clé API Talk n’est configurée. +- La solution de secours `ELEVENLABS_API_KEY` s’applique uniquement lorsqu’aucune clé API Talk n’est configurée. - `providers.*.voiceAliases` permet aux directives Talk d’utiliser des noms conviviaux. -- `silenceTimeoutMs` contrôle combien de temps le mode Talk attend après le silence de l’utilisateur avant d’envoyer la transcription. Une valeur non définie conserve la fenêtre de pause par défaut de la plateforme (`700 ms sur macOS et Android, 900 ms sur iOS`). +- `silenceTimeoutMs` contrôle combien de temps le mode Talk attend après le silence de l’utilisateur avant d’envoyer la transcription. Non défini, il conserve la fenêtre de pause par défaut de la plateforme (`700 ms sur macOS et Android, 900 ms sur iOS`). --- @@ -2054,12 +2043,12 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android). 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). -| Profil | Inclut | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | `session_status` uniquement | +| Profil | Inclut | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status` uniquement | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Aucune restriction (identique à non défini) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Aucune restriction (identique à non défini) | ### Groupes d’outils @@ -2090,7 +2079,7 @@ Politique globale d’autorisation/refus des outils (le refus l’emporte). Inse ### `tools.byProvider` -Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. Ordre : profil de base → profil fournisseur → autorisation/refus. +Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. Ordre : profil de base → profil du fournisseur → autorisation/refus. ```json5 { @@ -2106,7 +2095,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 { @@ -2123,7 +2112,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. +- `/elevated on|off|ask|full` enregistre l’état par session ; les directives en ligne s’appliquent à un seul message. - `exec` élevé contourne le sandboxing et utilise le chemin d’échappement configuré (`gateway` par défaut, ou `node` lorsque la cible `exec` est `node`). ### `tools.exec` @@ -2170,12 +2159,12 @@ Les paramètres peuvent être définis globalement dans `tools.loopDetection` et } ``` -- `historySize` : historique maximal des appels d’outils conservé pour l’analyse de boucle. -- `warningThreshold` : seuil des motifs répétitifs sans progression pour les avertissements. +- `historySize` : historique maximal des appels d’outil conservé pour l’analyse des boucles. +- `warningThreshold` : seuil d’avertissement pour les motifs répétitifs sans progression. - `criticalThreshold` : seuil répétitif plus élevé pour bloquer les boucles critiques. -- `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 sur les outils de sondage connus (`process.poll`, `command_status`, etc.). +- `globalCircuitBreakerThreshold` : seuil d’arrêt dur pour toute exécution sans progression. +- `detectors.genericRepeat` : avertit sur les appels répétés au même outil/avec les mêmes arguments. +- `detectors.knownPollNoProgress` : avertit/bloque sur les outils de poll connus (`process.poll`, `command_status`, etc.). - `detectors.pingPong` : avertit/bloque sur les motifs alternés par paires sans progression. - Si `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, la validation échoue. @@ -2247,28 +2236,28 @@ 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 à modèle (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) **Champs communs :** -- `capabilities` : liste facultative (`image`, `audio`, `video`). Par défaut : `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `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 basculent vers l’entrée suivante. +- En cas d’échec, le système passe à l’entrée suivante. -L’authentification fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`. +L’authentification du fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`. -**Champs de complétion asynchrone :** +**Champs d’exécution asynchrone :** -- `asyncCompletion.directSend` : lorsque `true`, les tâches `music_generate` - et `video_generate` asynchrones terminées tentent d’abord une livraison directe au canal. Par défaut : `false` - (ancien chemin de réveil de session demandeuse / livraison par modèle). +- `asyncCompletion.directSend` : lorsque défini à `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). @@ -2289,7 +2278,7 @@ L’authentification fournisseur suit l’ordre standard : `auth-profiles.json` Contrôle quelles sessions peuvent être ciblées par les outils de session (`sessions_list`, `sessions_history`, `sessions_send`). -Par défaut : `tree` (session actuelle + sessions engendrées par elle, comme les sous-agents). +Par défaut : `tree` (session actuelle + sessions qu’elle a lancées, comme les sous-agents). ```json5 { @@ -2305,7 +2294,7 @@ Par défaut : `tree` (session actuelle + sessions engendrées par elle, comme le Remarques : - `self` : uniquement la clé de session actuelle. -- `tree` : session actuelle + sessions engendrées par la session actuelle (sous-agents). +- `tree` : session actuelle + sessions lancées par la session actuelle (sous-agents). - `agent` : toute session appartenant à l’ID d’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même ID d’agent). - `all` : toute session. Le ciblage inter-agents nécessite toujours `tools.agentToAgent`. - 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"`. @@ -2333,15 +2322,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 sous `.openclaw/attachments//` avec un `.manifest.json`. -- Le contenu des pièces jointes est automatiquement expurgé de la persistance du transcript. -- Les entrées Base64 sont validées avec des vérifications strictes d’alphabet/de padding et une garde de taille avant décodage. +- 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 masqué dans la persistance de transcription. +- Les entrées base64 sont validées avec des vérifications strictes d’alphabet/de padding et une protection de taille avant décodage. - Les permissions de fichiers 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 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. +Indicateurs expérimentaux pour les outils intégrés. Désactivés par défaut sauf lorsqu’une règle d’auto-activation stricte et agentique GPT-5 s’applique. ```json5 { @@ -2355,9 +2344,9 @@ Indicateurs expérimentaux d’outils intégrés. Désactivés par défaut sauf 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 hors de ce cadre, ou `false` pour le garder 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`. +- `planTool` : active l’outil structuré expérimental `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 de la famille GPT-5 OpenAI ou OpenAI Codex. Définissez `true` pour forcer l’activation de l’outil hors de ce cadre, ou `false` pour le garder désactivé même pour les exécutions GPT-5 strict-agentic. +- Lorsqu’il est activé, le prompt système ajoute aussi des consignes d’usage afin que le modèle ne l’utilise que pour les travaux substantiels et conserve au plus une étape `in_progress`. ### `agents.defaults.subagents` @@ -2377,10 +2366,10 @@ Remarques : } ``` -- `model` : modèle par défaut des sous-agents engendrés. Si omis, les sous-agents héritent du modèle de l’appelant. -- `allowAgents` : liste d’autorisations 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 (secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai d’expiration. -- Politique d’outils par sous-agent : `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model` : modèle par défaut pour les sous-agents lancés. S’il est omis, les sous-agents héritent du modèle de l’appelant. +- `allowAgents` : liste d’autorisations par défaut des 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. +- Politique d’outil par sous-agent : `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2416,44 +2405,44 @@ OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs pe ``` - Utilisez `authHeader: true` + `headers` pour des besoins d’authentification personnalisés. -- Remplacez la racine de configuration de l’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, un ancien alias de variable d’environnement). +- Remplacez la racine de configuration de l’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, alias hérité de variable d’environnement). - Priorité de fusion pour les ID de fournisseur correspondants : - - Les valeurs `baseUrl` non vides du `models.json` de l’agent l’emportent. - - Les valeurs `apiKey` non vides de l’agent 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 actualisées à partir des marqueurs de source (`ENV_VAR_NAME` pour les refs d’environnement, `secretref-managed` pour les refs 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 à partir des marqueurs de source (`secretref-env:ENV_VAR_NAME` pour les refs d’environnement, `secretref-managed` pour les refs fichier/exec). - - Les valeurs `apiKey`/`baseUrl` vides ou absentes de l’agent 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 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 souhaitez que la configuration réécrive complètement `models.json`. - - La persistance des marqueurs est pilotée par la source : les marqueurs sont écrits à partir de l’instantané actif de la configuration source (pré-résolution), et non à partir des valeurs secrètes résolues à l’exécution. + - Les valeurs `baseUrl` non vides de l’agent `models.json` l’emportent. + - Les valeurs `apiKey` non vides de l’agent l’emportent uniquement lorsque ce fournisseur n’est pas géré par SecretRef dans le contexte actuel config/profil d’authentification. + - Les valeurs `apiKey` de fournisseur gérées par SecretRef sont actualisées à partir des 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 à partir des marqueurs 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 autoritaire côté source : les marqueurs sont écrits à partir de l’instantané de configuration source actif (avant résolution), et non à partir des valeurs de secret résolues à l’exécution. ### Détails des champs du 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` : carte des 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/substitution de variable d’environnement). +- `models.providers.*.apiKey` : identifiant du fournisseur (préférez SecretRef/la substitution par variable 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 de l’identifiant dans l’en-tête `Authorization` lorsque nécessaire. +- `models.providers.*.authHeader` : force le transport des identifiants dans l’en-tête `Authorization` lorsque nécessaire. - `models.providers.*.baseUrl` : URL de base de l’API amont. -- `models.providers.*.headers` : en-têtes statiques supplémentaires pour le routage proxy/tenant. -- `models.providers.*.request` : remplacements de transport pour les requêtes HTTP du fournisseur de modèles. +- `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è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"` (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 facultatif `tls`. - - `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (acceptent tous 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 garde SSRF de récupération HTTP 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 garde SSRF de récupération. Par défaut `false`. + - `request.auth` : remplacement de la 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 du proxy HTTP. Modes : `"env-proxy"` (utilise les variables d’environnement `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (avec `url`). Les deux modes acceptent un sous-objet facultatif `tls`. + - `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (tous acceptent SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork` : lorsque défini à `true`, autorise HTTPS vers `baseUrl` lorsque le DNS se résout vers des plages privées, CGNAT ou similaires, via la garde SSRF HTTP fetch du fournisseur (activation opérateur pour les 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 garde SSRF fetch. 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 souhaitez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle. -- `models.providers.*.models.*.compat.supportsDeveloperRole` : indication de compatibilité facultative. Pour `api: "openai-completions"` avec un `baseUrl` non natif non vide (hôte différent de `api.openai.com`), OpenClaw force cette valeur à `false` à l’exécution. Un `baseUrl` vide/omis conserve le comportement OpenAI par défaut. -- `models.providers.*.models.*.compat.requiresStringContent` : indication de compatibilité facultative pour les points de terminaison de chat compatibles OpenAI n’acceptant que des chaînes. Lorsque `true`, OpenClaw aplatit les tableaux `messages[].content` purement textuels en chaînes simples avant l’envoi de la requête. +- `models.providers.*.models.*.contextTokens` : plafond de contexte d’exécution facultatif. Utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle. +- `models.providers.*.models.*.compat.supportsDeveloperRole` : indication de compatibilité facultative. 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 de compatibilité facultative pour les points de terminaison de discussion compatibles OpenAI acceptant uniquement des chaînes. Lorsque défini à `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é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.providerFilter` : filtre facultatif par ID de fournisseur pour une détection ciblée. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour l’actualisation de la détection. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow` : fenêtre de contexte de secours pour les modèles détectés. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens` : nombre maximal de jetons de sortie de secours pour les modèles détectés. @@ -2511,7 +2500,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 des références `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 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`. @@ -2532,7 +2521,7 @@ Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont des alias acceptés. Raccou - 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 `baseUrl`. @@ -2575,7 +2564,7 @@ Pour le point de terminaison Chine : `baseUrl: "https://api.moonshot.cn/v1"` ou Les points de terminaison Moonshot natifs annoncent la compatibilité d’utilisation 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é. +plutôt que sur l’ID du fournisseur intégré uniquement. @@ -2675,8 +2664,8 @@ L’URL de base doit omettre `/v1` (le client Anthropic l’ajoute). Raccourci : Définissez `MINIMAX_API_KEY`. Raccourcis : `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. -Le catalogue de modèles utilise par défaut M2.7 uniquement. -Sur le chemin de streaming compatible Anthropic, OpenClaw désactive thinking pour MiniMax +Le catalogue de modèles utilise par défaut uniquement M2.7. +Sur le chemin de streaming compatible Anthropic, OpenClaw désactive thinking MiniMax par défaut sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou `params.fastMode: true` réécrit `MiniMax-M2.7` en `MiniMax-M2.7-highspeed`. @@ -2685,7 +2674,7 @@ par défaut sauf si vous définissez explicitement `thinking` vous-même. `/fast -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 un matériel sérieux ; conservez les modèles hébergés fusionnés pour le secours. +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 secours. @@ -2716,14 +2705,14 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand m } ``` -- `allowBundled` : liste d’autorisations 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 de Skills partagées supplémentaires (priorité la plus faible). -- `install.preferBrew` : lorsque true, préfère les installateurs Homebrew lorsque `brew` est - disponible avant de revenir à d’autres types d’installateurs. -- `install.nodeManager` : préférence d’installateur Node pour les spécifications `metadata.openclaw.install` - (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` désactive une Skill même si elle est groupée/installée. -- `entries..apiKey` : raccourci pour les Skills qui déclarent une variable d’environnement primaire (chaîne en texte brut ou objet SecretRef). +- `allowBundled` : liste d’autorisations facultative pour les Skills groupés uniquement (les Skills gérés/d’espace de travail ne sont pas affectés). +- `load.extraDirs` : racines Skills partagées supplémentaires (priorité la plus faible). +- `install.preferBrew` : lorsque défini à true, préfère les installateurs Homebrew lorsque `brew` est + disponible avant de revenir à d’autres types d’installateur. +- `install.nodeManager` : préférence du gestionnaire Node pour les spécifications + `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` désactive un skill même s’il est groupé/installé. +- `entries..apiKey` : raccourci pour les Skills déclarant une variable d’environnement primaire (chaîne en texte brut ou objet SecretRef). --- @@ -2751,39 +2740,39 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand m } ``` -- Chargé depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, ainsi que `plugins.load.paths`. -- La détection accepte les plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude sans manifeste à disposition par défaut. -- **Les changements de configuration nécessitent un redémarrage de la passerelle.** +- Chargés depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, plus `plugins.load.paths`. +- La découverte accepte les plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude sans manifeste utilisant la disposition par défaut. +- **Les modifications de configuration nécessitent un redémarrage de la passerelle.** - `allow` : liste d’autorisations facultative (seuls les plugins listés sont chargés). `deny` l’emporte. -- `plugins.entries..apiKey` : champ de commodité de clé API au niveau du plugin (lorsqu’il est pris en charge par le plugin). -- `plugins.entries..env` : map de variables d’environnement limitée au plugin. -- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le cœur bloque `before_prompt_build` et ignore les champs qui modifient le prompt de l’ancien `before_agent_start`, tout en préservant `modelOverride` et `providerOverride` hérités. S’applique aux hooks de plugins natifs et aux répertoires de hooks fournis par bundle pris en charge. -- `plugins.entries..subagent.allowModelOverride` : faire explicitement confiance à ce plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions de sous-agents en arrière-plan. -- `plugins.entries..subagent.allowedModels` : liste d’autorisations facultative des cibles canoniques `provider/model` pour les remplacements de sous-agent de confiance. Utilisez `"*"` uniquement si vous souhaitez volontairement autoriser n’importe quel modèle. +- `plugins.entries..apiKey` : champ pratique de clé API au niveau du plugin (lorsqu’il est pris en charge par le plugin). +- `plugins.entries..env` : carte de variables d’environnement limitée au plugin. +- `plugins.entries..hooks.allowPromptInjection` : lorsque défini à `false`, le noyau bloque `before_prompt_build` et ignore les champs modifiant le prompt 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 pris en charge fournis par bundle. +- `plugins.entries..subagent.allowModelOverride` : fait explicitement confiance à ce plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions d’arrière-plan de sous-agent. +- `plugins.entries..subagent.allowedModels` : liste d’autorisations facultative des cibles canoniques `provider/model` pour les remplacements approuvés de sous-agent. 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 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` : extraire uniquement le contenu principal des pages (par défaut : `true`). + - `onlyMainContent` : extrait uniquement le contenu principal des pages (par défaut : `true`). - `maxAgeMs` : âge maximal du cache en millisecondes (par défaut : `172800000` / 2 jours). - - `timeoutSeconds` : délai d’expiration des requêtes de scraping, en secondes (par défaut : `60`). + - `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 la mémoire (expérimental). Voir [Dreaming](/fr/concepts/dreaming) pour les phases et seuils. - - `enabled` : interrupteur principal du dreaming (par défaut `false`). - - `frequency` : cadence cron pour chaque balayage complet de dreaming (par défaut `"0 3 * * *"`). - - la politique de phase et les seuils sont des détails d’implémentation (pas des clés de configuration destinées aux utilisateurs). -- La configuration complète de la mémoire se trouve dans [Référence de configuration de la mémoire](/fr/reference/memory-config) : +- `plugins.entries.memory-core.config.dreaming` : paramètres de rêverie mémoire (expérimental). Voir [Dreaming](/fr/concepts/dreaming) pour les phases et seuils. + - `enabled` : interrupteur maître de la rêverie (par défaut `false`). + - `frequency` : cadence cron pour chaque balayage complet de rêverie (par défaut `"0 3 * * *"`). + - 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 mémoire complète 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 également contribuer aux valeurs par défaut de Pi embarqué depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, et non comme correctifs bruts de configuration OpenClaw. -- `plugins.slots.memory` : choisissez l’ID du plugin mémoire actif, ou `"none"` pour désactiver les plugins mémoire. -- `plugins.slots.contextEngine` : choisissez l’ID du plugin 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 aux valeurs par défaut Pi embarquées 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 mémoire actif, ou `"none"` pour désactiver les plugins mémoire. +- `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 et 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. @@ -2829,8 +2818,8 @@ 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, donc la navigation du navigateur reste stricte par défaut. -- Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` uniquement lorsque vous faites volontairement 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. +- 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 profil CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage des réseaux privés lors des vérifications d’accessibilité/de découverte. - `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme ancien alias. - En mode strict, utilisez `ssrfPolicy.hostnameAllowlist` et `ssrfPolicy.allowedHostnames` pour des exceptions explicites. - Les profils distants sont en mode attachement uniquement (démarrage/arrêt/réinitialisation désactivés). @@ -2839,17 +2828,18 @@ Voir [Plugins](/fr/tools/plugin). 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 - spécifique d’un navigateur basé sur Chromium 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 du ciblage par sélecteur CSS, hooks - de téléchargement d’un seul fichier, pas de remplacement des délais d’expiration de boîte de dialogue, pas de `wait --load networkidle`, et pas de - `responsebody`, export PDF, interception de téléchargement ou actions par lot. -- Les profils locaux gérés `openclaw` attribuent automatiquement `cdpPort` et `cdpUrl` ; ne définissez - explicitement `cdpUrl` que pour un CDP distant. -- Ordre de détection automatique : navigateur par défaut s’il est basé sur Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. + spécifique de navigateur basé sur Chromium comme Brave ou Edge. +- Les profils `existing-session` conservent les limites actuelles de routage Chrome MCP : + actions pilotées par snapshot/réf au lieu d’un ciblage par sélecteur CSS, hooks + d’envoi de fichier unique, pas de remplacements de délai pour les boîtes de dialogue, + pas de `wait --load networkidle`, ni `responsebody`, export PDF, interception de téléchargement + ou actions en lot. +- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; ne + définissez `cdpUrl` explicitement que pour un CDP distant. +- Ordre d’auto-détection : navigateur par défaut s’il est basé sur Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Service de contrôle : loopback uniquement (port dérivé de `gateway.port`, par défaut `18791`). -- `extraArgs` ajoute des indicateurs de lancement supplémentaires au démarrage local de Chromium (par exemple - `--disable-gpu`, dimensionnement de fenêtre ou indicateurs de débogage). +- `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). --- @@ -2867,7 +2857,7 @@ Voir [Plugins](/fr/tools/plugin). } ``` -- `seamColor` : couleur d’accentuation pour le chrome de l’interface native (teinte de la bulle du mode Talk, etc.). +- `seamColor` : couleur d’accent pour le chrome de l’UI de l’application native (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. --- @@ -2901,6 +2891,8 @@ Voir [Plugins](/fr/tools/plugin). enabled: true, basePath: "/openclaw", // root: "dist/control-ui", + // embedSandbox: "scripts", // strict | scripts | trusted + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, @@ -2935,43 +2927,43 @@ Voir [Plugins](/fr/tools/plugin). -- `mode` : `local` (exécuter la passerelle) ou `remote` (se connecter à une passerelle distante). La passerelle refuse de démarrer sauf si `local`. +- `mode` : `local` (exécuter la passerelle) ou `remote` (se connecter à une passerelle distante). La passerelle 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`), pas 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 passerelle est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. -- **Auth** : requise par défaut. Les binds non loopback nécessitent l’authentification de la passerelle. 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. +- `bind` : `auto`, `loopback` (par défaut), `lan` (`0.0.0.0`), `tailnet` (IP Tailscale uniquement), ou `custom`. +- **Anciens alias de liaison** : utilisez les valeurs de mode de liaison 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** : 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 la passerelle est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. +- **Authentification** : requise par défaut. Les liaisons non loopback exigent l’authentification de la passerelle. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse 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 sans authentification explicite. À utiliser uniquement pour des configurations de confiance en local loopback ; ce mode n’est volontairement pas proposé 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é provenant de `gateway.trustedProxies` (voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend une source proxy **non loopback** ; les proxys 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 API HTTP n’utilisent **pas** cette authentification par en-tête Tailscale ; ils suivent à la place le mode d’authentification HTTP normal de la passerelle. Ce flux sans jeton suppose que l’hôte de la passerelle est de confiance. Vaut par défaut `true` lorsque `tailscale.mode = "serve"`. +- `gateway.auth.mode: "none"` : mode explicite sans authentification. À utiliser uniquement pour des configurations de loopback local approuvées ; ce mode n’est volontairement pas proposé dans 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é venant de `gateway.trustedProxies` (voir [Authentification par proxy approuvé](/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 défini à `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 de l’API HTTP n’utilisent **pas** cette authentification par en-tête Tailscale ; ils suivent à la place le mode normal d’authentification HTTP de la passerelle. Ce flux sans jeton suppose que l’hôte de la passerelle est approuvé. La valeur par défaut est `true` lorsque `tailscale.mode = "serve"`. - `gateway.auth.rateLimit` : limiteur facultatif des échecs d’authentification. S’applique par IP client et par portée d’authentification (secret partagé et jeton d’appareil sont suivis indépendamment). Les tentatives bloquées renvoient `429` + `Retry-After`. - - Sur le chemin asynchrone 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 concurrentes erronées du même client peuvent donc déclencher le limiteur dès la deuxième requête au lieu de passer toutes les deux comme de simples incohérences. - - `gateway.auth.rateLimit.exemptLoopback` vaut par défaut `true` ; définissez `false` lorsque vous souhaitez volontairement appliquer aussi la limitation au trafic localhost (pour des configurations de test ou des déploiements proxy stricts). -- Les tentatives d’authentification WS d’origine navigateur sont toujours limitées avec l’exemption loopback désactivée (défense en profondeur contre la force brute localhost depuis un navigateur). -- En loopback, ces blocages d’origine navigateur sont isolés par valeur `Origin` - normalisée, de sorte que des échecs répétés depuis une origine localhost ne - bloquent pas automatiquement une autre origine. -- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite une authentification). -- `controlUi.allowedOrigins` : liste d’autorisations explicite des origines navigateur pour les connexions WebSocket de la passerelle. Obligatoire lorsque des clients navigateur sont attendus depuis des origines non loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le secours d’origine via l’en-tête Host pour les déploiements qui s’appuient volontairement sur cette politique. + - 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 simultanées incorrectes depuis le même client peuvent donc déclencher le limiteur dès la deuxième requête au lieu de laisser les deux passer comme de simples erreurs de correspondance. + - `gateway.auth.rateLimit.exemptLoopback` vaut `true` par défaut ; définissez `false` lorsque vous souhaitez intentionnellement que le trafic localhost soit lui aussi limité (pour des configurations de test ou des déploiements proxy stricts). +- Les tentatives d’authentification WS d’origine navigateur sont toujours limitées avec l’exemption loopback désactivée (défense en profondeur contre le brute force localhost basé sur 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 n’entraînent pas automatiquement + le verrouillage d’une autre origine. +- `tailscale.mode` : `serve` (tailnet uniquement, liaison loopback) ou `funnel` (public, authentification requise). +- `controlUi.allowedOrigins` : liste d’autorisations explicite des origines navigateur pour les connexions WebSocket à la passerelle. 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 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 trafic en clair reste limité au loopback. -- `gateway.remote.token` / `.password` sont des champs d’identifiants du client distant. Ils ne configurent pas à eux seuls l’authentification de la passerelle. -- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après qu’ils ont publié à la passerelle des enregistrements adossés au relais. Cette URL doit correspondre à l’URL de relais compilée dans le build iOS. -- `gateway.push.apns.relay.timeoutMs` : délai d’expiration en millisecondes pour les envois passerelle-vers-relais. Par défaut `10000`. -- Les enregistrements adossés au relais sont délégués à une identité de passerelle spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais et transmet à la passerelle une autorisation d’envoi limitée à cet enregistrement. Une autre passerelle ne peut pas réutiliser cet enregistrement stocké. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : remplacement côté client en mode secours qui autorise `ws://` en clair vers des IP approuvées de réseau privé ; par défaut, le texte en clair reste limité au loopback. +- `gateway.remote.token` / `.password` sont des champs d’identifiants de client distant. Ils ne configurent pas à eux seuls l’authentification de la passerelle. +- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après publication par ceux-ci des inscriptions adossées au relais vers la passerelle. Cette URL doit correspondre à l’URL de relais compilée dans le build iOS. +- `gateway.push.apns.relay.timeoutMs` : délai d’envoi de la passerelle vers le relais en millisecondes. Par défaut : `10000`. +- Les inscriptions adossées à un relais sont déléguées à une identité de passerelle spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’inscription au relais et transmet à la passerelle une autorisation d’envoi limitée à cette inscription. Une autre passerelle ne peut pas réutiliser cette inscription stockée. - `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 réservée au développement pour les URL de relais HTTP en 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. Gardez cette 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é. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` : échappatoire réservée au développement pour les URL de relais HTTP en loopback. Les URL de relais en 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. Gardez cette valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`. +- `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages du moniteur de santé par canal/compte sur une heure glissante. Par défaut : `10`. +- `channels..healthMonitor.enabled` : désactivation par canal des redémarrages du moniteur de santé tout en 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 de passerelle locale peuvent utiliser `gateway.remote.*` comme secours uniquement lorsque `gateway.auth.*` n’est pas défini. +- Les chemins d’appel de passerelle locale peuvent utiliser `gateway.remote.*` comme solution de secours 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 secours distant ne masque cela). -- `trustedProxies` : IP des proxys inverses qui terminent TLS ou injectent des en-têtes de client transférés. Ne listez que des proxys que vous contrôlez. Les entrées loopback restent valides pour des 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 passerelle accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement fail-closed. +- `trustedProxies` : IP de proxy inverse qui terminent TLS ou injectent des en-têtes de client transféré. 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 défini à `true`, la passerelle 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 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. @@ -2979,7 +2971,7 @@ Voir [Plugins](/fr/tools/plugin). ### Points de terminaison compatibles OpenAI -- Chat Completions : désactivé par défaut. Activez avec `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions : désactivé par défaut. Activez-le avec `gateway.http.endpoints.chatCompletions.enabled: true`. - API Responses : `gateway.http.endpoints.responses.enabled`. - Renforcement des entrées URL de Responses : - `gateway.http.endpoints.responses.maxUrlParts` @@ -2988,11 +2980,11 @@ Voir [Plugins](/fr/tools/plugin). Les listes d’autorisations vides sont traitées comme non définies ; utilisez `gateway.http.endpoints.responses.files.allowUrl=false` et/ou `gateway.http.endpoints.responses.images.allowUrl=false` pour désactiver la récupération d’URL. - En-tête facultatif de renforcement des réponses : - - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour des origines HTTPS que vous contrôlez ; voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour des origines HTTPS que vous contrôlez ; voir [Authentification par proxy approuvé](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolation multi-instance -Exécutez plusieurs passerelles sur un même hôte avec des ports et des répertoires d’état uniques : +Exécutez plusieurs passerelles sur un même hôte avec des ports et répertoires d’état uniques : ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3000,7 +2992,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + le port `19001`), `--profile ` (utilise `~/.openclaw-`). +Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). Voir [Passerelles multiples](/fr/gateway/multiple-gateways). @@ -3020,11 +3012,11 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). } ``` -- `enabled` : active la terminaison TLS au niveau de l’écouteur de la passerelle (HTTPS/WSS) (par défaut : `false`). -- `autoGenerate` : génère automatiquement une paire locale auto-signée certificat/clé lorsque les fichiers explicites ne sont pas configurés ; pour usage local/dev uniquement. -- `certPath` : chemin système de fichiers vers le fichier certificat TLS. -- `keyPath` : chemin système de fichiers vers la clé privée TLS ; conservez des permissions restrictives. -- `caPath` : chemin facultatif du bundle CA pour la vérification client ou les chaînes de confiance personnalisées. +- `enabled` : active la terminaison TLS au niveau du listener de la passerelle (HTTPS/WSS) (par défaut : `false`). +- `autoGenerate` : génère automatiquement une paire locale certificat/clé auto-signée lorsque des fichiers explicites ne sont pas configurés ; à utiliser uniquement en local/dev. +- `certPath` : chemin du système de fichiers vers le fichier de certificat TLS. +- `keyPath` : chemin du système de fichiers vers le fichier de clé privée TLS ; gardez des permissions restreintes. +- `caPath` : chemin facultatif vers le bundle CA pour la vérification client ou les chaînes de confiance personnalisées. ### `gateway.reload` @@ -3040,13 +3032,13 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). } ``` -- `mode` : contrôle comment les modifications de configuration sont appliquées à l’exécution. +- `mode` : contrôle la manière dont les modifications de configuration sont appliquées à l’exécution. - `"off"` : ignore les modifications en direct ; les changements nécessitent un redémarrage explicite. - - `"restart"` : redémarre toujours le processus de la passerelle lors d’un changement de configuration. - - `"hot"` : applique les changements dans le processus sans redémarrer. - - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; revient à un redémarrage si nécessaire. -- `debounceMs` : fenêtre d’anti-rebond en ms avant application des changements de configuration (entier non négatif). -- `deferralTimeoutMs` : temps maximal d’attente, en ms, pour les opérations en cours avant de forcer un redémarrage (par défaut : `300000` = 5 minutes). + - `"restart"` : redémarre toujours le processus de passerelle en cas de changement de configuration. + - `"hot"` : applique les changements en cours de processus sans redémarrage. + - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; revient au redémarrage si nécessaire. +- `debounceMs` : fenêtre de debounce en ms avant l’application des modifications de configuration (entier non négatif). +- `deferralTimeoutMs` : durée maximale en ms pendant laquelle attendre la fin des opérations en cours avant de forcer un redémarrage (par défaut : `300000` = 5 minutes). --- @@ -3083,37 +3075,37 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). } ``` -Auth : `Authorization: Bearer ` ou `x-openclaw-token: `. +Authentification : `Authorization: Bearer ` ou `x-openclaw-token: `. Les jetons de hook dans la chaîne de requête sont rejetés. Remarques de validation et de sécurité : - `hooks.enabled=true` nécessite un `hooks.token` non vide. -- `hooks.token` doit être **distinct** de `gateway.auth.token` ; réutiliser le jeton de la passerelle est rejeté. +- `hooks.token` doit être **distinct** de `gateway.auth.token` ; la réutilisation du jeton de passerelle est rejetée. - `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié tel que `/hooks`. -- Si `hooks.allowRequestSessionKey=true`, contraignez `hooks.allowedSessionKeyPrefixes` (par exemple `["hook:"]`). +- Si `hooks.allowRequestSessionKey=true`, limitez `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` venant de la charge utile de la requête n’est accepté que lorsque `hooks.allowRequestSessionKey=true` (par défaut : `false`). - `POST /hooks/` → résolu via `hooks.mappings` - + - `match.path` correspond au sous-chemin après `/hooks` (par ex. `/hooks/gmail` → `gmail`). - `match.source` correspond à un champ de la charge utile pour les chemins génériques. -- Les modèles comme `{{messages[0].subject}}` lisent depuis la charge utile. +- Les modèles comme `{{messages[0].subject}}` lisent à partir de la charge utile. - `transform` peut pointer vers un module JS/TS renvoyant une action de hook. - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et la traversée sont rejetés). - `agentId` route vers un agent spécifique ; les ID inconnus 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. +- `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’autorisations facultative de préfixes pour les valeurs explicites de `sessionKey` (requête + mappage), par ex. `["hook:"]`. -- `deliver: true` envoie la réponse finale à un canal ; `channel` vaut par défaut `last`. -- `model` remplace le LLM pour cette exécution de hook (doit être autorisé si le catalogue de modèles est défini). +- `allowedSessionKeyPrefixes` : liste d’autorisations facultative de préfixes pour les valeurs explicites de `sessionKey` (requête + mapping), par ex. `["hook:"]`. +- `deliver: true` envoie la réponse finale vers un canal ; `channel` vaut par défaut `last`. +- `model` remplace le LLM pour cette exécution de hook (doit être autorisé si un catalogue de modèles est défini). @@ -3157,18 +3149,18 @@ Remarques de validation et de sécurité : } ``` -- Sert du HTML/CSS/JS modifiable par l’agent et A2UI via HTTP sous le port de la passerelle : +- Sert HTML/CSS/JS modifiables par agent et A2UI via HTTP sous le port de la passerelle : - `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 de la passerelle (token/password/trusted-proxy), comme les autres surfaces HTTP de la passerelle. -- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; une fois qu’un nœud est appairé et connecté, la passerelle annonce des URL de capacité limitées au nœud pour l’accès canvas/A2UI. -- Les URL de capacité sont liées à la session WS active du nœud et expirent rapidement. Aucun secours basé sur l’IP n’est utilisé. -- Injecte le client de rechargement en direct dans le HTML servi. -- Crée automatiquement un `index.html` de démarrage lorsqu’il est vide. -- Sert également A2UI à `/__openclaw__/a2ui/`. -- Les changements nécessitent un redémarrage de la passerelle. -- Désactivez le rechargement en direct pour les gros répertoires ou les erreurs `EMFILE`. +- Liaisons non loopback : les routes canvas exigent l’authentification de la passerelle (jeton/mot de passe/trusted-proxy), comme les autres surfaces HTTP de la passerelle. +- Les WebViews Node n’envoient généralement pas d’en-têtes d’authentification ; après appairage et connexion d’un nœud, la passerelle annonce des URL de capacité limitées au nœud pour l’accès canvas/A2UI. +- Les URL de capacité sont liées à la session WS active du nœud et expirent rapidement. Aucun secours basé sur IP n’est utilisé. +- Injecte un client live-reload dans le HTML servi. +- Crée automatiquement un `index.html` de départ lorsque le répertoire est vide. +- Sert également A2UI sous `/__openclaw__/a2ui/`. +- Les modifications nécessitent un redémarrage de la passerelle. +- Désactivez le live reload pour les grands répertoires ou les erreurs `EMFILE`. --- @@ -3190,7 +3182,7 @@ Remarques de validation et de sécurité : - `full` : inclut `cliPath` + `sshPort`. - Le nom d’hôte vaut par défaut `openclaw`. Remplacez-le avec `OPENCLAW_MDNS_HOSTNAME`. -### Large zone (DNS-SD) +### Large portée (DNS-SD) ```json5 { @@ -3200,7 +3192,7 @@ 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é) + le split DNS Tailscale. +Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour la découverte inter-réseaux, combinez avec un serveur DNS (CoreDNS recommandé) + DNS fractionné Tailscale. Configuration : `openclaw dns setup --apply`. @@ -3226,11 +3218,11 @@ Configuration : `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 courant + `~/.openclaw/.env` (aucun des deux ne remplace les variables existantes). -- `shellEnv` : importe les clés attendues manquantes depuis le profil de votre shell de connexion. -- Voir [Environnement](/fr/help/environment) pour l’ordre de priorité complet. +- Fichiers `.env` : `.env` du répertoire courant + `~/.openclaw/.env` (aucun ne remplace des variables existantes). +- `shellEnv` : importe les clés attendues manquantes depuis votre profil shell de connexion. +- Voir [Environnement](/fr/help/environment) pour la priorité complète. -### Substitution de variables d’environnement +### Substitution de variable d’environnement Référencez des variables d’environnement dans n’importe quelle chaîne de configuration avec `${VAR_NAME}` : @@ -3242,8 +3234,8 @@ Référencez des variables d’environnement dans n’importe quelle chaîne de } ``` -- Seuls les noms en majuscules sont reconnus : `[A-Z_][A-Z0-9_]*`. -- Les variables manquantes/vides déclenchent une erreur au chargement de la configuration. +- Seuls les noms en majuscules sont pris en compte : `[A-Z_][A-Z0-9_]*`. +- Les variables manquantes/vides provoquent une erreur au chargement de la configuration. - Échappez avec `$${VAR}` pour obtenir un littéral `${VAR}`. - Fonctionne avec `$include`. @@ -3267,7 +3259,7 @@ Validation : - motif `id` pour `source: "env"` : `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` `id` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) - motif `id` pour `source: "exec"` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- les `id` pour `source: "exec"` ne doivent pas contenir de segments de chemin `/./` ou `/../` délimités par slash (par exemple `a/../b` est rejeté) +- Les `id` de `source: "exec"` ne doivent pas contenir de segments de chemin `.` ou `..` séparés par `/` (par exemple `a/../b` est rejeté) ### Surface d’identifiants prise en charge @@ -3306,12 +3298,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 `command` en chemin absolu et utilise des charges utiles de protocole sur stdin/stdout. +- 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 symlink sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symlink tout en validant le chemin cible résolu. -- Si `trustedDirs` est configuré, la vérification des répertoires de confiance s’applique au chemin cible résolu. -- L’environnement enfant de `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. +- Si `trustedDirs` est configuré, la vérification des répertoires approuvés s’applique au chemin cible résolu. +- L’environnement enfant `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. - Les références de secret sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête lisent uniquement cet instantané. -- Le filtrage des surfaces actives s’applique pendant l’activation : les références non résolues sur les surfaces activées font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec diagnostic. +- Le filtrage des surfaces actives s’applique pendant l’activation : les références non résolues sur les surfaces activées font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec diagnostics. --- @@ -3334,10 +3326,10 @@ 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 des références au niveau des valeurs (`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 des 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 purgées lorsqu’elles sont découvertes. -- Importations OAuth historiques depuis `~/.openclaw/credentials/oauth.json`. +- Les identifiants statiques d’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont purgées lorsqu’elles sont découvertes. +- Importations OAuth héritées depuis `~/.openclaw/credentials/oauth.json`. - Voir [OAuth](/fr/concepts/oauth). - Comportement du runtime des secrets et outils `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). @@ -3361,21 +3353,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 aboutir ici même sur des réponses `401`/`403`, mais les - comparateurs de texte spécifiques au fournisseur restent limités au fournisseur - qui les possède (par exemple OpenRouter - `Key limit exceeded`). Les messages réessayables `402` liés à la fenêtre d’utilisation ou - aux limites de dépenses d’organisation/espace de travail restent dans le chemin `rate_limit` +- `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` réessayables liés à une fenêtre d’utilisation ou + à une limite de dépense d’organisation/espace de travail restent dans le chemin `rate_limit` à la place. -- `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`). +- `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 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 chez un même fournisseur pour les erreurs de surcharge avant basculement vers le fallback de modèle (par défaut : `1`). Les formes de fournisseur occupé telles que `ModelNotReadyException` aboutissent ici. -- `overloadedBackoffMs` : délai fixe avant réessai d’une rotation de fournisseur/profil surchargé (par défaut : `0`). -- `rateLimitedProfileRotations` : nombre maximal de rotations de profil d’authentification chez un même fournisseur pour les erreurs de limitation de débit avant basculement vers le fallback de modèle (par défaut : `1`). Ce compartiment de limitation de débit inclut des textes propres au fournisseur tels que `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. +- `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 du même fournisseur pour les erreurs de surcharge avant de passer au modèle de secours (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 du même fournisseur pour les erreurs de limite de débit avant de passer au modèle de secours (par défaut : `1`). Cette catégorie de limite de débit inclut des textes propres aux fournisseurs tels que `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. --- @@ -3434,7 +3426,7 @@ Remarques : } ``` -- `enabled` : interrupteur principal de la sortie d’instrumentation (par défaut : `true`). +- `enabled` : interrupteur maître pour la sortie d’instrumentation (par défaut : `true`). - `flags` : tableau de chaînes d’indicateurs activant une sortie de journal ciblée (prend en charge des jokers comme `"telegram.*"` ou `"*"`). - `stuckSessionWarnMs` : seuil d’ancienneté en ms pour émettre des avertissements de session bloquée tant qu’une session reste à l’état de traitement. - `otel.enabled` : active le pipeline d’export OpenTelemetry (par défaut : `false`). @@ -3442,10 +3434,10 @@ Remarques : - `otel.protocol` : `"http/protobuf"` (par défaut) ou `"grpc"`. - `otel.headers` : en-têtes de métadonnées HTTP/gRPC supplémentaires envoyés avec les requêtes d’export OTel. - `otel.serviceName` : nom du service pour les attributs de ressource. -- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export de traces, métriques ou journaux. +- `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 la télémétrie en ms. -- `cacheTrace.enabled` : journalise des instantanés de trace de cache pour les exécutions embarquées (par défaut : `false`). +- `otel.flushIntervalMs` : intervalle périodique de vidage de télémétrie en ms. +- `cacheTrace.enabled` : journalise les 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 par défaut : `true`). @@ -3471,10 +3463,10 @@ 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 passerelle (par défaut : `true`). -- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de paquets (par défaut : `false`). -- `auto.stableDelayHours` : délai minimal en heures avant application automatique sur le canal stable (par défaut : `6` ; max : `168`). -- `auto.stableJitterHours` : fenêtre supplémentaire d’étalement du déploiement sur le canal stable, en heures (par défaut : `12` ; max : `168`). -- `auto.betaCheckIntervalHours` : fréquence d’exécution des vérifications sur le canal bêta, en heures (par défaut : `1` ; max : `24`). +- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de package (par défaut : `false`). +- `auto.stableDelayHours` : délai minimal en heures avant l’application automatique sur le canal stable (par défaut : `6` ; max : `168`). +- `auto.stableJitterHours` : fenêtre supplémentaire de lissage 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`). --- @@ -3508,21 +3500,21 @@ Remarques : ``` - `enabled` : garde de fonctionnalité ACP globale (par défaut : `false`). -- `dispatch.enabled` : garde indépendante 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é). -- `defaultAgent` : ID d’agent ACP cible de secours lorsque les engendrements ne spécifient pas de cible explicite. -- `allowedAgents` : liste d’autorisations des ID d’agents autorisés pour les sessions de runtime ACP ; vide signifie aucune restriction supplémentaire. +- `dispatch.enabled` : garde indépendante pour l’envoi 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 runtime ACP par défaut (doit correspondre à un plugin runtime ACP enregistré). +- `defaultAgent` : ID d’agent ACP cible de secours lorsque les lancements ne spécifient pas de cible explicite. +- `allowedAgents` : liste d’autorisations des ID d’agent permis pour les sessions runtime 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é. -- `stream.maxChunkChars` : taille maximale d’un bloc avant fractionnement de la projection du flux. +- `stream.coalesceIdleMs` : fenêtre de vidage après inactivité en ms pour le texte diffusé en continu. +- `stream.maxChunkChars` : taille maximale de bloc avant découpage de la projection du flux. - `stream.repeatSuppression` : supprime les lignes répétées d’état/d’outil par tour (par défaut : `true`). -- `stream.deliveryMode` : `"live"` diffuse de manière incrémentale ; `"final_only"` met en tampon jusqu’aux événements terminaux du tour. +- `stream.deliveryMode` : `"live"` diffuse progressivement ; `"final_only"` met en mémoire tampon jusqu’aux événements terminaux du tour. - `stream.hiddenBoundarySeparator` : séparateur avant le texte visible après des événements d’outil masqués (par défaut : `"paragraph"`). - `stream.maxOutputChars` : nombre maximal de caractères de sortie assistant projetés par tour ACP. - `stream.maxSessionUpdateChars` : nombre maximal de caractères pour les lignes 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 éligible. -- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement de runtime ACP. +- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’initialisation d’un environnement runtime ACP. --- @@ -3539,14 +3531,14 @@ Remarques : ``` - `cli.banner.taglineMode` contrôle le style du slogan de la bannière : - - `"random"` (par défaut) : slogans tournants amusants/de saison. - - `"default"` : slogan neutre fixe (`Tous vos chats, un seul OpenClaw.`). - - `"off"` : aucun texte de slogan (le titre/la version de la bannière restent affichés). + - `"random"` (par défaut) : slogans tournants amusants/saisonniers. + - `"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 (pas seulement les slogans), définissez la variable d’environnement `OPENCLAW_HIDE_BANNER=1`. --- -## Wizard +## Assistant Métadonnées écrites par les flux de configuration guidée de la CLI (`onboard`, `configure`, `doctor`) : @@ -3566,15 +3558,15 @@ Métadonnées écrites par les flux de configuration guidée de la CLI (`onboard ## Identité -Voir les champs d’identité de `agents.list` sous [Valeurs par défaut des agents](#agent-defaults). +Voir les champs d’identité de `agents.list` dans [Valeurs par défaut de l’agent](#agent-defaults). --- -## Bridge (historique, supprimé) +## Bridge (hérité, supprimé) -Les builds actuels n’incluent plus le bridge TCP. Les nœuds se connectent via le WebSocket de la passerelle. 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 supprimer les clés inconnues). +Les builds actuels n’incluent plus le bridge TCP. Les nœuds se connectent via le WebSocket de la passerelle. Les clés `bridge.*` ne font plus partie du schéma de configuration (la validation échoue jusqu’à leur suppression ; `openclaw doctor --fix` peut retirer les clés inconnues). - + ```json { @@ -3612,11 +3604,11 @@ Les builds actuels n’incluent plus le bridge TCP. Les nœuds se connectent via } ``` -- `sessionRetention` : durée de conservation des sessions terminées d’exécution cron isolée avant leur élagage 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. +- `sessionRetention` : durée de conservation des sessions terminées d’exécution cron isolée 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` : lignes les plus récentes conservées lorsque l’élagage du journal d’exécution se déclenche. Par défaut : `2000`. +- `runLog.keepLines` : lignes les plus récentes conservées lorsque l’élagage du journal d’exécution est déclenché. Par défaut : `2000`. - `webhookToken` : jeton bearer utilisé pour la livraison POST du webhook cron (`delivery.mode = "webhook"`), si omis aucun en-tête d’authentification n’est envoyé. -- `webhook` : URL de webhook historique obsolète (http/https) utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. +- `webhook` : URL de webhook de secours héritée et dépréciée (http/https), utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. ### `cron.retry` @@ -3633,10 +3625,10 @@ Les builds actuels n’incluent plus le bridge TCP. Les nœuds se connectent via ``` - `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 nouvelle tentative (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). -- `retryOn` : types d’erreurs qui déclenchent les 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 exécution (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). +- `retryOn` : types d’erreurs déclenchant les 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 des échecs distincte. +S’applique uniquement aux tâches cron ponctuelles. Les tâches récurrentes utilisent une gestion d’échec distincte. ### `cron.failureAlert` @@ -3655,10 +3647,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 le déclenchement d’une alerte (entier positif, min : `1`). -- `cooldownMs` : nombre minimal de millisecondes entre alertes répétées pour une même tâche (entier non négatif). +- `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 livraison des alertes. +- `accountId` : ID facultatif de compte ou de canal pour limiter la portée de la livraison d’alerte. ### `cron.failureDestination` @@ -3675,16 +3667,16 @@ S’applique uniquement aux tâches cron ponctuelles. Les tâches récurrentes u } ``` -- Destination par défaut des notifications d’échec cron pour toutes les tâches. -- `mode` : `"announce"` ou `"webhook"` ; vaut par défaut `"announce"` lorsque suffisamment de données de cible existent. +- Destination par défaut pour les notifications d’échec cron pour toutes les tâches. +- `mode` : `"announce"` ou `"webhook"` ; vaut par défaut `"announce"` lorsque suffisamment de données cibles existent. - `channel` : remplacement de canal pour la livraison announce. `"last"` réutilise le dernier canal de livraison connu. -- `to` : cible announce explicite ou URL de webhook. Obligatoire pour le mode webhook. -- `accountId` : remplacement de compte facultatif pour la livraison. -- `delivery.failureDestination` par tâche remplace cette valeur par défaut globale. +- `to` : cible announce explicite ou URL du webhook. Obligatoire pour le 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 ni par tâche n’est définie, les tâches qui livrent déjà via `announce` reviennent à cette cible announce principale en cas d’échec. - `delivery.failureDestination` n’est pris en charge que pour les tâches `sessionTarget="isolated"` sauf si le `delivery.mode` principal de la tâche est `"webhook"`. -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). +Voir [Tâches cron](/fr/automation/cron-jobs). Les exécutions cron isolées sont suivies en tant que [tâches d’arrière-plan](/fr/automation/tasks). --- @@ -3695,7 +3687,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/encapsulation expéditeur) | +| `{{RawBody}}` | Corps brut (sans enveloppes historique/expéditeur) | | `{{BodyStripped}}` | Corps avec les mentions de groupe supprimées | | `{{From}}` | Identifiant de l’expéditeur | | `{{To}}` | Identifiant de destination | @@ -3709,15 +3701,15 @@ Espaces réservés de modèle développés dans `tools.media.models[].args` : | `{{Prompt}}` | prompt média résolu pour les entrées CLI | | `{{MaxChars}}` | nombre maximal de caractères de sortie résolu pour les entrées CLI | | `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | sujet du groupe (best effort) | -| `{{GroupMembers}}` | aperçu des membres du groupe (best effort) | -| `{{SenderName}}` | nom d’affichage de l’expéditeur (best effort) | -| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (best effort) | -| `{{Provider}}` | indication de fournisseur (whatsapp, telegram, discord, etc.) | +| `{{GroupSubject}}` | sujet du groupe (au mieux) | +| `{{GroupMembers}}` | aperçu des membres du groupe (au mieux) | +| `{{SenderName}}` | nom d’affichage de l’expéditeur (au mieux) | +| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (au mieux) | +| `{{Provider}}` | indice du fournisseur (whatsapp, telegram, discord, etc.) | --- -## Inclusions de configuration (`$include`) +## Includes de configuration (`$include`) Divisez la configuration en plusieurs fichiers : @@ -3735,12 +3727,12 @@ Divisez 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 inclusions (remplacent les valeurs incluses). -- Inclusions imbriquées : jusqu’à 10 niveaux de profondeur. +- Tableau de fichiers : fusion profonde dans l’ordre (les suivants remplacent les précédents). +- Clés voisines : 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 dans cette limite. -- Erreurs : messages clairs pour fichiers manquants, erreurs d’analyse et inclusions circulaires. +- Erreurs : messages clairs pour les fichiers manquants, les erreurs d’analyse et les includes circulaires. --- -_Related: [Configuration](/fr/gateway/configuration) · [Configuration Examples](/fr/gateway/configuration-examples) · [Doctor](/fr/gateway/doctor)_ +_Related: [Configuration](/fr/gateway/configuration) · [Exemples de configuration](/fr/gateway/configuration-examples) · [Doctor](/fr/gateway/doctor)_ diff --git a/docs/fr/help/gpt54-codex-agentic-parity-maintainers.md b/docs/fr/help/gpt54-codex-agentic-parity-maintainers.md new file mode 100644 index 000000000..26bae4345 --- /dev/null +++ b/docs/fr/help/gpt54-codex-agentic-parity-maintainers.md @@ -0,0 +1,174 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:53Z" + model: gpt-5.4 + provider: openai + source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e + source_path: help/gpt54-codex-agentic-parity-maintainers.md + workflow: 15 +--- + +# Notes de maintenance sur la parité GPT-5.4 / Codex + +Cette note explique comment examiner le programme de parité GPT-5.4 / Codex comme quatre unités de fusion sans perdre l’architecture originale en six contrats. + +## Unités de fusion + +### PR A : exécution agentique stricte + +Possède : + +- `executionContract` +- suivi dans le même tour, d’abord GPT-5 +- `update_plan` comme suivi de progression non terminal +- états bloqués explicites au lieu d’arrêts silencieux limités au plan + +Ne possède pas : + +- classification des échecs d’authentification/runtime +- véracité des permissions +- refonte du rejeu/de la continuation +- benchmarking de parité + +### PR B : véracité du runtime + +Possède : + +- exactitude des scopes OAuth Codex +- classification typée des échecs provider/runtime +- disponibilité véridique de `/elevated full` et raisons de blocage + +Ne possède pas : + +- normalisation du schéma des outils +- état de rejeu/vivacité +- contrôle du benchmark + +### PR C : exactitude de l’exécution + +Possède : + +- compatibilité des outils OpenAI/Codex possédée par le provider +- gestion stricte des schémas sans paramètres +- exposition des rejeux invalides +- visibilité des états de tâche longue en pause, bloquée et abandonnée + +Ne possède pas : + +- continuation auto-élue +- comportement générique du dialecte Codex en dehors des hooks du provider +- contrôle du benchmark + +### PR D : harnais de parité + +Possède : + +- premier lot de scénarios GPT-5.4 vs Opus 4.6 +- documentation de la parité +- rapport de parité et mécanismes de contrôle à la publication + +Ne possède pas : + +- changements de comportement du runtime en dehors de QA-lab +- simulation auth/proxy/DNS dans le harnais + +## Correspondance avec les six contrats d’origine + +| Contrat d’origine | Unité de fusion | +| --------------------------------------- | --------------- | +| Exactitude du transport/auth provider | PR B | +| Compatibilité contrat/schéma des outils | PR C | +| Exécution dans le même tour | PR A | +| Véracité des permissions | PR B | +| Exactitude rejeu/continuation/vivacité | PR C | +| Contrôle benchmark/publication | PR D | + +## Ordre de revue + +1. PR A +2. PR B +3. PR C +4. PR D + +PR D est la couche de preuve. Elle ne doit pas être la raison pour laquelle les PR de correction du runtime sont retardées. + +## Points à vérifier + +### PR A + +- les exécutions GPT-5 agissent ou échouent de manière fermée au lieu de s’arrêter au commentaire +- `update_plan` ne ressemble plus à lui seul à une progression +- le comportement reste d’abord GPT-5 et limité au périmètre Pi embarqué + +### PR B + +- les échecs auth/proxy/runtime ne sont plus ramenés à une gestion générique de type « le modèle a échoué » +- `/elevated full` n’est décrit comme disponible que lorsqu’il l’est réellement +- les raisons de blocage sont visibles à la fois pour le modèle et pour le runtime exposé à l’utilisateur + +### PR C + +- l’enregistrement strict des outils OpenAI/Codex se comporte de manière prévisible +- les outils sans paramètres n’échouent pas aux vérifications strictes du schéma +- les résultats de rejeu et de compaction préservent un état de vivacité véridique + +### PR D + +- le lot de scénarios est compréhensible et reproductible +- le lot inclut une voie mutante de sécurité de rejeu, pas seulement des flux en lecture seule +- les rapports sont lisibles par les humains et par l’automatisation +- les affirmations de parité sont étayées par des preuves, pas anecdotiques + +Artéfacts attendus de PR D : + +- `qa-suite-report.md` / `qa-suite-summary.json` pour chaque exécution de modèle +- `qa-agentic-parity-report.md` avec comparaison agrégée et au niveau des scénarios +- `qa-agentic-parity-summary.json` avec un verdict lisible par machine + +## Contrôle de publication + +Ne pas affirmer la parité ou la supériorité de GPT-5.4 sur Opus 4.6 tant que : + +- PR A, PR B et PR C ne sont pas fusionnées +- PR D n’exécute pas proprement le premier lot de parité +- les suites de régression de véracité du runtime restent vertes +- le rapport de parité ne montre aucun cas de faux succès et aucune régression du comportement d’arrêt + +```mermaid +flowchart LR + A["PR A-C fusionnées"] --> B["Exécuter le lot de parité GPT-5.4"] + A --> C["Exécuter le lot de parité Opus 4.6"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["qa parity-report"] + E --> F + F --> G["Rapport Markdown + verdict JSON"] + G --> H{"Réussite ?"} + H -- "oui" --> I["Affirmation de parité autorisée"] + H -- "non" --> J["Garder les correctifs runtime / la boucle de revue ouverte"] +``` + +Le harnais de parité n’est pas la seule source de preuve. Gardez cette séparation explicite dans la revue : + +- PR D possède la comparaison par scénarios entre GPT-5.4 et Opus 4.6 +- les suites déterministes de PR B possèdent toujours les preuves auth/proxy/DNS et de véracité d’accès complet + +## Cartographie objectif-preuve + +| Élément du critère d’achèvement | Propriétaire principal | Artéfact de revue | +| ---------------------------------------- | ---------------------- | -------------------------------------------------------------------- | +| Aucun blocage limité au plan | PR A | tests runtime agentiques stricts et `approval-turn-tool-followthrough` | +| Aucun faux progrès ni fausse exécution d’outil | PR A + PR D | nombre de faux succès de parité plus détails du rapport au niveau des scénarios | +| Aucun faux guidage `/elevated full` | PR B | suites déterministes de véracité du runtime | +| Les échecs de rejeu/vivacité restent explicites | PR C + PR D | suites cycle de vie/rejeu plus `compaction-retry-mutating-tool` | +| GPT-5.4 égale ou dépasse Opus 4.6 | PR D | `qa-agentic-parity-report.md` et `qa-agentic-parity-summary.json` | + +## Abréviation pour les reviewers : avant vs après + +| Problème visible par l’utilisateur avant | Signal de revue après | +| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| GPT-5.4 s’arrêtait après la planification | PR A montre un comportement agir-ou-bloquer au lieu d’une fin limitée au commentaire | +| L’usage des outils semblait fragile avec les schémas stricts OpenAI/Codex | PR C garde un enregistrement des outils et une invocation sans paramètres prévisibles | +| Les indications `/elevated full` étaient parfois trompeuses | PR B relie les indications à la capacité réelle du runtime et aux raisons de blocage | +| Les tâches longues pouvaient disparaître dans l’ambiguïté du rejeu/de la compaction | PR C émet des états explicites : en pause, bloquée, abandonnée et rejeu invalide | +| Les affirmations de parité étaient anecdotiques | PR D produit un rapport plus un verdict JSON avec la même couverture de scénarios sur les deux modèles | diff --git a/docs/fr/help/gpt54-codex-agentic-parity.md b/docs/fr/help/gpt54-codex-agentic-parity.md new file mode 100644 index 000000000..9fdad21a1 --- /dev/null +++ b/docs/fr/help/gpt54-codex-agentic-parity.md @@ -0,0 +1,229 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:53Z" + model: gpt-5.4 + provider: openai + source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6 + source_path: help/gpt54-codex-agentic-parity.md + workflow: 15 +--- + +# GPT-5.4 / Parité agentique Codex dans OpenClaw + +OpenClaw fonctionnait déjà bien avec les modèles de pointe utilisant des outils, mais les modèles de type GPT-5.4 et Codex restaient moins performants dans quelques cas pratiques : + +- ils pouvaient s'arrêter après la planification au lieu d'effectuer le travail +- ils pouvaient utiliser incorrectement les schémas d'outils stricts d'OpenAI/Codex +- ils pouvaient demander `/elevated full` même lorsque l'accès complet était impossible +- ils pouvaient perdre l'état des tâches longues pendant la relecture ou la compaction +- les affirmations de parité avec Claude Opus 4.6 reposaient sur des anecdotes plutôt que sur des scénarios reproductibles + +Ce programme de parité corrige ces lacunes en quatre volets révisables. + +## Ce qui a changé + +### PR A : exécution stricte agentique + +Ce volet ajoute un contrat d'exécution `strict-agentic` optionnel pour les exécutions GPT-5 embarquées sur Pi. + +Lorsqu'il est activé, OpenClaw n'accepte plus les tours de planification seule comme une complétion « suffisante ». Si le modèle dit seulement ce qu'il a l'intention de faire sans réellement utiliser d'outils ni progresser, OpenClaw réessaie avec une instruction de passage immédiat à l'action, puis échoue en mode fermé avec un état bloqué explicite au lieu de terminer silencieusement la tâche. + +Cela améliore surtout l'expérience GPT-5.4 dans les cas suivants : + +- courts suivis du type « ok fais-le » +- tâches de code où la première étape est évidente +- flux où `update_plan` doit servir au suivi de progression plutôt qu'à du texte de remplissage + +### PR B : véracité de l'exécution + +Ce volet fait en sorte qu'OpenClaw dise la vérité sur deux points : + +- pourquoi l'appel au fournisseur/à l'environnement d'exécution a échoué +- si `/elevated full` est réellement disponible + +Cela signifie que GPT-5.4 reçoit de meilleurs signaux d'exécution pour les portées manquantes, les échecs de rafraîchissement d'authentification, les échecs d'authentification HTML 403, les problèmes de proxy, les échecs DNS ou de délai d'expiration, ainsi que les modes d'accès complet bloqués. Le modèle est moins susceptible d'halluciner une mauvaise remédiation ou de continuer à demander un mode d'autorisation que l'environnement d'exécution ne peut pas fournir. + +### PR C : exactitude de l'exécution + +Ce volet améliore deux types d'exactitude : + +- la compatibilité des schémas d'outils OpenAI/Codex possédés par le fournisseur +- l'exposition de la relecture et de la vivacité des tâches longues + +Le travail de compatibilité des outils réduit les frictions de schéma pour l'enregistrement strict des outils OpenAI/Codex, en particulier autour des outils sans paramètres et des attentes strictes de racine objet. Le travail sur la relecture et la vivacité rend les tâches longues plus observables, de sorte que les états en pause, bloqués et abandonnés sont visibles au lieu de disparaître dans un texte d'échec générique. + +### PR D : harnais de parité + +Ce volet ajoute le premier pack de parité QA-lab afin que GPT-5.4 et Opus 4.6 puissent être exercés à travers les mêmes scénarios et comparés à l'aide d'éléments de preuve partagés. + +Le pack de parité constitue la couche de preuve. Il ne modifie pas à lui seul le comportement d'exécution. + +Après avoir obtenu deux artefacts `qa-suite-summary.json`, générez la comparaison de validation de release avec : + +```bash +pnpm openclaw qa parity-report \ + --repo-root . \ + --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \ + --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \ + --output-dir .artifacts/qa-e2e/parity +``` + +Cette commande écrit : + +- un rapport Markdown lisible par des humains +- un verdict JSON lisible par machine +- un résultat de validation explicite `pass` / `fail` + +## Pourquoi cela améliore GPT-5.4 en pratique + +Avant ce travail, GPT-5.4 sur OpenClaw pouvait sembler moins agentique qu'Opus dans de vraies sessions de codage, car l'environnement d'exécution tolérait des comportements particulièrement nuisibles aux modèles de type GPT-5 : + +- tours contenant uniquement des commentaires +- friction de schéma autour des outils +- retours vagues sur les autorisations +- rupture silencieuse de la relecture ou de la compaction + +L'objectif n'est pas de faire imiter Opus à GPT-5.4. L'objectif est de donner à GPT-5.4 un contrat d'exécution qui récompense les vrais progrès, fournit des sémantiques plus nettes pour les outils et les autorisations, et transforme les modes d'échec en états explicites lisibles à la fois par des machines et par des humains. + +Cela fait passer l'expérience utilisateur de : + +- « le modèle avait un bon plan mais s'est arrêté » + +à : + +- « le modèle a soit agi, soit OpenClaw a exposé la raison exacte pour laquelle il ne pouvait pas le faire » + +## Avant / après pour les utilisateurs de GPT-5.4 + +| Avant ce programme | Après les PR A-D | +| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| GPT-5.4 pouvait s'arrêter après un plan raisonnable sans effectuer l'étape d'outil suivante | PR A transforme « plan uniquement » en « agir maintenant ou exposer un état bloqué » | +| Les schémas d'outils stricts pouvaient rejeter les outils sans paramètres ou au format OpenAI/Codex de façon déroutante | PR C rend l'enregistrement et l'invocation des outils possédés par le fournisseur plus prévisibles | +| Les indications sur `/elevated full` pouvaient être vagues ou incorrectes dans des environnements bloqués | PR B fournit à GPT-5.4 et à l'utilisateur des indications d'exécution et d'autorisation véridiques | +| Les échecs de relecture ou de compaction pouvaient donner l'impression que la tâche avait silencieusement disparu | PR C expose explicitement les résultats en pause, bloqués, abandonnés et invalides pour relecture | +| « GPT-5.4 semble moins bon qu'Opus » était surtout anecdotique | PR D transforme cela en un même pack de scénarios, les mêmes métriques et une validation dure de type pass/fail | + +## Architecture + +```mermaid +flowchart TD + A["Demande utilisateur"] --> B["Environnement d'exécution Pi embarqué"] + B --> C["Contrat d'exécution strict-agentic"] + B --> D["Compatibilité des outils possédés par le fournisseur"] + B --> E["Véracité de l'exécution"] + B --> F["État de relecture et de vivacité"] + C --> G["Appel d'outil ou état bloqué explicite"] + D --> G + E --> G + F --> G + G --> H["Pack de parité QA-lab"] + H --> I["Rapport de scénario et validation de parité"] +``` + +## Flux de release + +```mermaid +flowchart LR + A["Volets d'exécution fusionnés (PR A-C)"] --> B["Exécuter le pack de parité GPT-5.4"] + A --> C["Exécuter le pack de parité Opus 4.6"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["openclaw qa parity-report"] + E --> F + F --> G["qa-agentic-parity-report.md"] + F --> H["qa-agentic-parity-summary.json"] + H --> I{"Validation réussie ?"} + I -- "oui" --> J["Affirmation de parité étayée par des preuves"] + I -- "non" --> K["Maintenir ouverte la boucle d'exécution/de revue"] +``` + +## Pack de scénarios + +Le pack de parité de première vague couvre actuellement cinq scénarios : + +### `approval-turn-tool-followthrough` + +Vérifie que le modèle ne s'arrête pas à « Je vais le faire » après une approbation courte. Il doit entreprendre la première action concrète dans le même tour. + +### `model-switch-tool-continuity` + +Vérifie que le travail utilisant des outils reste cohérent à travers les limites de changement de modèle ou d'environnement d'exécution, au lieu de se réinitialiser en commentaire ou de perdre le contexte d'exécution. + +### `source-docs-discovery-report` + +Vérifie que le modèle peut lire le code source et la documentation, synthétiser ses constats et poursuivre la tâche de manière agentique plutôt que de produire un résumé mince et de s'arrêter prématurément. + +### `image-understanding-attachment` + +Vérifie que les tâches en mode mixte impliquant des pièces jointes restent actionnables et ne se réduisent pas à une narration vague. + +### `compaction-retry-mutating-tool` + +Vérifie qu'une tâche avec une véritable écriture mutante garde l'insécurité de relecture explicite au lieu de paraître silencieusement sûre à relire si l'exécution compacte, réessaie ou perd l'état de réponse sous pression. + +## Matrice des scénarios + +| Scénario | Ce qu'il teste | Bon comportement GPT-5.4 | Signal d'échec | +| ---------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | +| `approval-turn-tool-followthrough` | Tours d'approbation courts après un plan | Démarre immédiatement la première action d'outil concrète au lieu de reformuler son intention | suivi en plan uniquement, aucune activité d'outil, ou tour bloqué sans vrai bloqueur | +| `model-switch-tool-continuity` | Changement d'environnement/modèle sous utilisation d'outils | Préserve le contexte de la tâche et continue à agir de manière cohérente | se réinitialise en commentaire, perd le contexte d'outil, ou s'arrête après le changement | +| `source-docs-discovery-report` | Lecture du code source + synthèse + action | Trouve les sources, utilise les outils et produit un rapport utile sans bloquer | résumé mince, travail d'outil manquant, ou arrêt en tour incomplet | +| `image-understanding-attachment` | Travail agentique piloté par pièce jointe | Interprète la pièce jointe, la relie aux outils et poursuit la tâche | narration vague, pièce jointe ignorée, ou absence d'action concrète suivante | +| `compaction-retry-mutating-tool` | Travail mutant sous pression de compaction | Effectue une vraie écriture et garde l'insécurité de relecture explicite après l'effet de bord | une écriture mutante a lieu mais la sûreté de relecture est implicite, absente ou contradictoire | + +## Validation de release + +GPT-5.4 ne peut être considéré à parité ou meilleur que lorsque l'environnement d'exécution fusionné réussit le pack de parité et les régressions de véracité de l'exécution en même temps. + +Résultats requis : + +- aucun blocage sur plan uniquement lorsque l'action d'outil suivante est claire +- aucune fausse complétion sans exécution réelle +- aucune indication incorrecte sur `/elevated full` +- aucun abandon silencieux de relecture ou de compaction +- des métriques du pack de parité au moins aussi solides que la référence Opus 4.6 convenue + +Pour le harnais de première vague, la validation compare : + +- le taux de complétion +- le taux d'arrêts non intentionnels +- le taux d'appels d'outil valides +- le nombre de faux succès + +Les preuves de parité sont délibérément réparties en deux couches : + +- la PR D prouve le comportement GPT-5.4 vs Opus 4.6 sur les mêmes scénarios avec QA-lab +- les suites déterministes de la PR B prouvent la véracité de l'authentification, du proxy, du DNS et de `/elevated full` en dehors du harnais + +## Matrice objectif-preuve + +| Élément de validation de complétion | PR responsable | Source de preuve | Signal de réussite | +| -------------------------------------------------------- | -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| GPT-5.4 ne bloque plus après la planification | PR A | `approval-turn-tool-followthrough` plus suites d'exécution PR A | les tours d'approbation déclenchent un vrai travail ou un état bloqué explicite | +| GPT-5.4 ne simule plus des progrès ou une fausse complétion d'outil | PR A + PR D | résultats de scénarios du rapport de parité et nombre de faux succès | aucun résultat de réussite suspect et aucune complétion basée uniquement sur des commentaires | +| GPT-5.4 ne donne plus de fausses indications sur `/elevated full` | PR B | suites déterministes de véracité | les raisons de blocage et les indications d'accès complet restent exactes vis-à-vis de l'environnement d'exécution | +| Les échecs de relecture/vivacité restent explicites | PR C + PR D | suites de cycle de vie/relecture PR C plus `compaction-retry-mutating-tool` | le travail mutant garde l'insécurité de relecture explicite au lieu de disparaître silencieusement | +| GPT-5.4 égale ou dépasse Opus 4.6 sur les métriques convenues | PR D | `qa-agentic-parity-report.md` et `qa-agentic-parity-summary.json` | même couverture de scénarios et aucune régression sur la complétion, le comportement d'arrêt ou l'utilisation valide des outils | + +## Comment lire le verdict de parité + +Utilisez le verdict dans `qa-agentic-parity-summary.json` comme décision finale lisible par machine pour le pack de parité de première vague. + +- `pass` signifie que GPT-5.4 a couvert les mêmes scénarios qu'Opus 4.6 et n'a pas régressé sur les métriques agrégées convenues. +- `fail` signifie qu'au moins une validation stricte a échoué : complétion plus faible, davantage d'arrêts non intentionnels, utilisation valide des outils plus faible, au moins un cas de faux succès, ou couverture de scénarios non concordante. +- « shared/base CI issue » n'est pas en soi un résultat de parité. Si du bruit CI en dehors de la PR D bloque une exécution, le verdict doit attendre une exécution propre sur l'environnement d'exécution fusionné au lieu d'être déduit à partir de journaux d'époque de branche. +- La véracité de l'authentification, du proxy, du DNS et de `/elevated full` continue de provenir des suites déterministes de la PR B, donc l'affirmation finale de release nécessite les deux : un verdict de parité PR D réussi et une couverture de véracité PR B au vert. + +## Qui doit activer `strict-agentic` + +Utilisez `strict-agentic` lorsque : + +- l'agent est censé agir immédiatement lorsqu'une étape suivante est évidente +- les modèles de la famille GPT-5.4 ou Codex constituent l'environnement d'exécution principal +- vous préférez des états bloqués explicites à des réponses de récapitulatif uniquement « utiles » + +Conservez le contrat par défaut lorsque : + +- vous souhaitez conserver le comportement existant plus souple +- vous n'utilisez pas de modèles de la famille GPT-5 +- vous testez des prompts plutôt que l'application des règles par l'environnement d'exécution diff --git a/docs/fr/plugins/architecture.md b/docs/fr/plugins/architecture.md index 17d6a2366..bc687317c 100644 --- a/docs/fr/plugins/architecture.md +++ b/docs/fr/plugins/architecture.md @@ -1,186 +1,175 @@ --- read_when: - - Création ou débogage de plugins OpenClaw natifs - - Compréhension du modèle de capacités des plugins ou des limites de propriété - - Travail sur le pipeline de chargement des plugins ou le registre - - Implémentation de hooks d'exécution de fournisseur ou de plugins de canal + - Création ou débogage des plugins OpenClaw natifs + - Comprendre le modèle de capacités des plugins ou les limites de propriété + - Travailler sur le pipeline de chargement des plugins ou le registre + - Implémenter des hooks d’exécution de fournisseur ou des plugins de canal sidebarTitle: Internals -summary: 'Éléments internes des plugins : modèle de capacités, propriété, contrats, pipeline de chargement et helpers d''exécution' -title: Éléments internes des plugins +summary: 'Composants internes des plugins : modèle de capacités, propriété, contrats, pipeline de chargement et assistants d’exécution' +title: Composants internes des plugins x-i18n: - generated_at: "2026-04-09T01:32:15Z" + generated_at: "2026-04-11T15:16:02Z" model: gpt-5.4 provider: openai - source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 + source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 source_path: plugins/architecture.md workflow: 15 --- -# Éléments internes des plugins +# Composants internes des plugins - Il s'agit de la **référence d'architecture approfondie**. Pour des guides pratiques, voir : + Il s’agit de la **référence d’architecture approfondie**. Pour des guides pratiques, voir : - [Installer et utiliser des plugins](/fr/tools/plugin) — guide utilisateur - - [Bien démarrer](/fr/plugins/building-plugins) — premier tutoriel de plugin + - [Premiers pas](/fr/plugins/building-plugins) — premier tutoriel de plugin - [Plugins de canal](/fr/plugins/sdk-channel-plugins) — créer un canal de messagerie - [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — créer un fournisseur de modèles - - [Vue d'ensemble du SDK](/fr/plugins/sdk-overview) — carte des imports et API d'enregistrement + - [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — carte des imports et API d’enregistrement -Cette page couvre l'architecture interne du système de plugins d'OpenClaw. +Cette page couvre l’architecture interne du système de plugins OpenClaw. ## Modèle de capacités public -Les capacités constituent le modèle public de **plugin natif** dans OpenClaw. Chaque -plugin OpenClaw natif s'enregistre auprès d'un ou plusieurs types de capacités : +Les capacités constituent le modèle public des **plugins natifs** dans OpenClaw. Chaque +plugin OpenClaw natif s’enregistre pour un ou plusieurs types de capacités : | Capability | Registration method | Example plugins | | ---------------------- | ------------------------------------------------ | ------------------------------------ | | Inférence de texte | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend d'inférence CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Backend d’inférence CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | | Parole | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Transcription en temps réel | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Voix en temps réel | `api.registerRealtimeVoiceProvider(...)` | `openai` | | Compréhension des médias | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Génération d'images | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Génération de musique | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Génération de vidéo | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Génération d’images | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Génération musicale | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Génération de vidéos | `api.registerVideoGenerationProvider(...)` | `qwen` | | Récupération web | `api.registerWebFetchProvider(...)` | `firecrawl` | | Recherche web | `api.registerWebSearchProvider(...)` | `google` | | Canal / messagerie | `api.registerChannel(...)` | `msteams`, `matrix` | -Un plugin qui n'enregistre aucune capacité mais fournit des hooks, des outils ou -des services est un plugin **legacy hook-only**. Ce modèle reste entièrement pris en charge. +Un plugin qui enregistre zéro capacité mais fournit des hooks, des outils ou des +services est un plugin **legacy hook-only**. Ce modèle reste entièrement pris en charge. -### Position actuelle sur la compatibilité externe +### Position de compatibilité externe Le modèle de capacités est intégré au cœur et utilisé par les plugins -natifs/intégrés aujourd'hui, mais la compatibilité des plugins externes exige -encore une barre plus stricte que « c'est exporté, donc c'est figé ». +bundled/natifs aujourd’hui, mais la compatibilité des plugins externes exige +encore un niveau d’exigence plus élevé que « c’est exporté, donc c’est figé ». -Directive actuelle : +Recommandations actuelles : -- **plugins externes existants :** continuer à faire fonctionner les - intégrations basées sur des hooks ; considérez cela comme la base de compatibilité -- **nouveaux plugins natifs/intégrés :** préférer un enregistrement explicite des capacités - plutôt que des accès ciblés spécifiques à un fournisseur ou de nouveaux modèles hook-only -- **plugins externes adoptant l'enregistrement de capacités :** autorisé, mais - considérez les surfaces helper spécifiques aux capacités comme évolutives sauf si - la documentation marque explicitement un contrat comme stable +- **plugins externes existants :** conserver le fonctionnement des intégrations basées sur des hooks ; traiter cela comme la base de compatibilité +- **nouveaux plugins bundled/natifs :** préférer un enregistrement explicite des capacités plutôt que des accès spécifiques à un fournisseur ou de nouveaux modèles hook-only +- **plugins externes adoptant l’enregistrement des capacités :** autorisés, mais considérer les surfaces d’assistance spécifiques aux capacités comme évolutives, sauf si la documentation marque explicitement un contrat comme stable Règle pratique : -- les API d'enregistrement de capacités constituent la direction visée -- les hooks legacy restent le chemin le plus sûr sans rupture pour les plugins externes pendant - la transition -- les sous-chemins helper exportés n'ont pas tous le même statut ; préférez le - contrat étroit documenté, pas des exports helper accidentels +- les API d’enregistrement des capacités sont l’orientation voulue +- les hooks legacy restent la voie la plus sûre pour éviter les ruptures pour les plugins externes pendant la transition +- tous les sous-chemins d’assistance exportés ne se valent pas ; préférez le contrat documenté étroit, et non des exports d’assistance accessoires ### Formes de plugins OpenClaw classe chaque plugin chargé selon une forme basée sur son comportement -d'enregistrement réel (et pas seulement sur des métadonnées statiques) : +réel d’enregistrement (et non uniquement sur des métadonnées statiques) : -- **plain-capability** -- enregistre exactement un type de capacité (par exemple un - plugin uniquement fournisseur comme `mistral`) -- **hybrid-capability** -- enregistre plusieurs types de capacités (par exemple - `openai` possède l'inférence de texte, la parole, la compréhension des médias et la génération - d'images) -- **hook-only** -- enregistre uniquement des hooks (typés ou personnalisés), sans capacités, - outils, commandes ni services -- **non-capability** -- enregistre des outils, commandes, services ou routes, mais aucune - capacité +- **plain-capability** -- enregistre exactement un type de capacité (par exemple un plugin de fournisseur uniquement comme `mistral`) +- **hybrid-capability** -- enregistre plusieurs types de capacités (par exemple `openai` possède l’inférence de texte, la parole, la compréhension des médias et la génération d’images) +- **hook-only** -- enregistre uniquement des hooks (typés ou personnalisés), sans capacités, outils, commandes ni services +- **non-capability** -- enregistre des outils, commandes, services ou routes, mais aucune capacité -Utilisez `openclaw plugins inspect ` pour voir la forme d'un plugin et la -répartition de ses capacités. Voir [Référence CLI](/cli/plugins#inspect) pour plus de détails. +Utilisez `openclaw plugins inspect ` pour voir la forme d’un plugin et le +détail de ses capacités. Voir [Référence CLI](/cli/plugins#inspect) pour plus de détails. ### Hooks legacy -Le hook `before_agent_start` reste pris en charge comme chemin de compatibilité pour +Le hook `before_agent_start` reste pris en charge comme voie de compatibilité pour les plugins hook-only. Des plugins legacy utilisés en conditions réelles en dépendent encore. Orientation : - le conserver fonctionnel - le documenter comme legacy -- préférer `before_model_resolve` pour les surcharges de modèle/fournisseur -- préférer `before_prompt_build` pour la modification du prompt -- ne le retirer qu'après une baisse de l'usage réel et une couverture par fixtures prouvant la sécurité de la migration +- préférer `before_model_resolve` pour le travail de substitution de modèle/fournisseur +- préférer `before_prompt_build` pour le travail de mutation de prompt +- ne le supprimer qu’après baisse de l’usage réel et lorsque la couverture des fixtures prouve la sécurité de la migration ### Signaux de compatibilité Lorsque vous exécutez `openclaw doctor` ou `openclaw plugins inspect `, vous pouvez voir -l'un de ces libellés : +l’un de ces libellés : -| Signal | Signification | -| -------------------------- | ------------------------------------------------------------ | -| **configuration valide** | La configuration est correctement analysée et les plugins sont résolus | -| **avis de compatibilité** | Le plugin utilise un modèle pris en charge mais plus ancien (par ex. `hook-only`) | -| **avertissement legacy** | Le plugin utilise `before_agent_start`, qui est obsolète | -| **erreur bloquante** | La configuration est invalide ou le plugin n'a pas pu être chargé | +| Signal | Signification | +| -------------------------- | -------------------------------------------------------------- | +| **config valid** | La configuration est analysée correctement et les plugins se résolvent | +| **compatibility advisory** | Le plugin utilise un modèle pris en charge mais plus ancien (par ex. `hook-only`) | +| **legacy warning** | Le plugin utilise `before_agent_start`, qui est obsolète | +| **hard error** | La configuration est invalide ou le plugin n’a pas pu être chargé | -Ni `hook-only` ni `before_agent_start` ne casseront votre plugin aujourd'hui -- -`hook-only` est un avis, et `before_agent_start` ne déclenche qu'un avertissement. Ces -signaux apparaissent également dans `openclaw status --all` et `openclaw plugins doctor`. +Ni `hook-only` ni `before_agent_start` ne casseront votre plugin aujourd’hui -- +`hook-only` est un avis, et `before_agent_start` ne déclenche qu’un avertissement. Ces +signaux apparaissent aussi dans `openclaw status --all` et `openclaw plugins doctor`. -## Vue d'ensemble de l'architecture +## Vue d’ensemble de l’architecture -Le système de plugins d'OpenClaw comporte quatre couches : +Le système de plugins d’OpenClaw comporte quatre couches : 1. **Manifeste + découverte** - OpenClaw trouve les plugins candidats à partir des chemins configurés, des racines d'espace de travail, - des racines globales d'extensions et des extensions intégrées. La découverte lit d'abord + OpenClaw trouve les plugins candidats à partir des chemins configurés, des racines d’espace de travail, + des racines globales d’extensions et des extensions bundled. La découverte lit d’abord les manifestes natifs `openclaw.plugin.json` ainsi que les manifestes de bundle pris en charge. 2. **Activation + validation** Le cœur décide si un plugin découvert est activé, désactivé, bloqué ou - sélectionné pour un emplacement exclusif tel que la mémoire. -3. **Chargement à l'exécution** - Les plugins OpenClaw natifs sont chargés en processus via jiti et enregistrent + sélectionné pour un emplacement exclusif comme la mémoire. +3. **Chargement à l’exécution** + Les plugins OpenClaw natifs sont chargés dans le processus via jiti et enregistrent des capacités dans un registre central. Les bundles compatibles sont normalisés en - enregistrements de registre sans importer de code d'exécution. + enregistrements de registre sans importer de code d’exécution. 4. **Consommation des surfaces** - Le reste d'OpenClaw lit le registre pour exposer outils, canaux, configuration - des fournisseurs, hooks, routes HTTP, commandes CLI et services. + Le reste d’OpenClaw lit le registre pour exposer les outils, canaux, configuration des fournisseurs, + hooks, routes HTTP, commandes CLI et services. -Pour la CLI des plugins en particulier, la découverte des commandes racines est divisée en deux phases : +Pour la CLI des plugins en particulier, la découverte des commandes racine est divisée en deux phases : -- les métadonnées au moment de l'analyse proviennent de `registerCli(..., { descriptors: [...] })` -- le vrai module CLI du plugin peut rester paresseux et s'enregistrer à la première invocation +- les métadonnées au moment de l’analyse viennent de `registerCli(..., { descriptors: [...] })` +- le véritable module CLI du plugin peut rester paresseux et s’enregistrer lors de la première invocation -Cela permet de conserver le code CLI appartenant au plugin à l'intérieur du plugin tout en laissant OpenClaw -réserver les noms de commandes racines avant l'analyse. +Cela permet de conserver le code CLI appartenant au plugin dans le plugin tout en laissant OpenClaw +réserver les noms de commandes racine avant l’analyse. -La frontière de conception importante : +La limite de conception importante : -- la découverte + validation de configuration doivent fonctionner à partir des **métadonnées du manifeste/schéma** - sans exécuter le code du plugin -- le comportement d'exécution natif provient du chemin `register(api)` du module du plugin +- la découverte + validation de la configuration doivent fonctionner à partir des **métadonnées de manifeste/schéma** + sans exécuter de code de plugin +- le comportement d’exécution natif provient du chemin `register(api)` du module du plugin -Cette séparation permet à OpenClaw de valider la configuration, d'expliquer les plugins manquants/désactivés et -de construire des indices d'UI/schéma avant que l'exécution complète ne soit active. +Cette séparation permet à OpenClaw de valider la configuration, d’expliquer les plugins manquants/désactivés et +de construire des indications d’interface/schéma avant que l’exécution complète ne soit active. ### Plugins de canal et outil de message partagé -Les plugins de canal n'ont pas besoin d'enregistrer un outil séparé d'envoi/édition/réaction pour -les actions de chat normales. OpenClaw conserve un outil `message` partagé dans le cœur, et les -plugins de canal possèdent la découverte et l'exécution spécifiques au canal derrière celui-ci. +Les plugins de canal n’ont pas besoin d’enregistrer un outil séparé d’envoi/édition/réaction pour +les actions de chat normales. OpenClaw conserve un outil `message` partagé dans le cœur, et +les plugins de canal possèdent la découverte et l’exécution spécifiques au canal qui se trouvent derrière. -La frontière actuelle est la suivante : +La limite actuelle est la suivante : -- le cœur possède l'hôte de l'outil `message` partagé, le câblage de prompt, la tenue des sessions/fils - et la répartition de l'exécution -- les plugins de canal possèdent la découverte d'actions à portée, la découverte de capacités et toute - partie de schéma spécifique au canal -- les plugins de canal possèdent la grammaire de conversation de session spécifique au fournisseur, par exemple +- le cœur possède l’hôte de l’outil `message` partagé, le câblage des prompts, la + tenue des sessions/fils et la répartition de l’exécution +- les plugins de canal possèdent la découverte d’actions délimitées, la découverte des + capacités et tout fragment de schéma spécifique au canal +- les plugins de canal possèdent la grammaire de conversation de session spécifique au fournisseur, comme la manière dont les identifiants de conversation encodent les identifiants de fil ou héritent des conversations parentes -- les plugins de canal exécutent l'action finale via leur adaptateur d'action +- les plugins de canal exécutent l’action finale via leur adaptateur d’action Pour les plugins de canal, la surface SDK est `ChannelMessageActionAdapter.describeMessageTool(...)`. Cet appel de découverte unifié -permet à un plugin de renvoyer ensemble ses actions visibles, ses capacités et ses -contributions de schéma afin que ces éléments ne divergent pas. +permet à un plugin de renvoyer ensemble ses actions visibles, ses capacités et ses contributions au schéma, +afin que ces éléments ne divergent pas. -Le cœur transmet la portée d'exécution à cette étape de découverte. Les champs importants incluent : +Le cœur transmet la portée d’exécution à cette étape de découverte. Les champs importants incluent : - `accountId` - `currentChannelId` @@ -189,123 +178,116 @@ Le cœur transmet la portée d'exécution à cette étape de découverte. Les ch - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` entrant de confiance +- `requesterSenderId` entrant approuvé -C'est important pour les plugins sensibles au contexte. Un canal peut masquer ou exposer -des actions de message selon le compte actif, la salle/le fil/le message courant, ou -l'identité du demandeur de confiance, sans coder en dur de branches spécifiques au canal -dans l'outil `message` du cœur. +C’est important pour les plugins sensibles au contexte. Un canal peut masquer ou exposer +des actions de message en fonction du compte actif, de la salle/du fil/du message courant, ou de +l’identité de demandeur approuvée, sans coder en dur des branches spécifiques au canal dans +l’outil `message` du cœur. -C'est pourquoi les changements de routage du runner embarqué restent du travail de plugin : le runner est -responsable de transmettre l'identité actuelle du chat/de la session à la frontière de découverte du plugin -afin que l'outil `message` partagé expose la bonne surface appartenant au canal pour le tour courant. +C’est pourquoi les modifications de routage de l’embedded-runner restent du travail de plugin : le runner est +responsable de transmettre l’identité actuelle du chat/de la session à la limite de découverte du plugin afin que +l’outil `message` partagé expose la bonne surface appartenant au canal pour le tour courant. -Pour les helpers d'exécution appartenant au canal, les plugins intégrés doivent conserver le runtime -d'exécution dans leurs propres modules d'extension. Le cœur ne possède plus les runtimes -d'actions de message Discord, Slack, Telegram ou WhatsApp sous `src/agents/tools`. -Nous ne publions pas de sous-chemins séparés `plugin-sdk/*-action-runtime`, et les plugins intégrés -doivent importer directement leur propre code runtime local depuis leurs -modules appartenant à l'extension. +Pour les assistants d’exécution appartenant aux canaux, les plugins bundled doivent conserver l’exécution +dans leurs propres modules d’extension. Le cœur ne possède plus les environnements d’exécution d’actions de message +Discord, Slack, Telegram ou WhatsApp sous `src/agents/tools`. +Nous ne publions pas de sous-chemins `plugin-sdk/*-action-runtime` séparés, et les plugins bundled +doivent importer directement leur propre code d’exécution local depuis leurs +modules appartenant à l’extension. -La même frontière s'applique aux seams SDK nommés par fournisseur en général : le cœur ne doit -pas importer de barrel de commodité spécifique à un canal pour Slack, Discord, Signal, -WhatsApp ou des extensions similaires. Si le cœur a besoin d'un comportement, il doit soit consommer -le barrel `api.ts` / `runtime-api.ts` du plugin intégré, soit faire remonter ce besoin -dans une capacité générique étroite du SDK partagé. +La même limite s’applique de manière générale aux points d’intégration SDK nommés d’après un fournisseur : +le cœur ne doit pas importer de barils de commodité spécifiques à un canal pour Slack, Discord, Signal, +WhatsApp ou des extensions similaires. Si le cœur a besoin d’un comportement, il doit soit consommer +le propre baril `api.ts` / `runtime-api.ts` du plugin bundled, soit faire évoluer le besoin +vers une capacité générique étroite dans le SDK partagé. -Pour les sondages en particulier, il existe deux chemins d'exécution : +Pour les sondages en particulier, il existe deux chemins d’exécution : -- `outbound.sendPoll` est la base partagée pour les canaux qui correspondent au modèle - commun de sondage -- `actions.handleAction("poll")` est le chemin préféré pour la sémantique de sondage spécifique au canal - ou les paramètres de sondage supplémentaires +- `outbound.sendPoll` est la base partagée pour les canaux qui correspondent au modèle de sondage commun +- `actions.handleAction("poll")` est le chemin préféré pour la sémantique de sondage spécifique au canal ou pour des paramètres de sondage supplémentaires -Le cœur diffère désormais l'analyse partagée des sondages jusqu'à ce que le dispatch du plugin de sondage refuse -l'action, afin que les gestionnaires de sondage appartenant au plugin puissent accepter des champs de sondage -spécifiques au canal sans être bloqués d'abord par l'analyseur générique de sondage. +Le cœur diffère désormais l’analyse partagée des sondages jusqu’à ce que la répartition du sondage par plugin décline +l’action, afin que les gestionnaires de sondages appartenant au plugin puissent accepter des champs +de sondage spécifiques au canal sans être bloqués d’abord par l’analyseur générique de sondages. Voir [Pipeline de chargement](#load-pipeline) pour la séquence complète de démarrage. ## Modèle de propriété des capacités -OpenClaw traite un plugin natif comme la limite de propriété d'une **entreprise** ou d'une -**fonctionnalité**, et non comme un fourre-tout d'intégrations sans lien. +OpenClaw considère un plugin natif comme la limite de propriété pour une **entreprise** ou une +**fonctionnalité**, et non comme un regroupement d’intégrations sans lien. Cela signifie : -- un plugin d'entreprise doit en général posséder toutes les surfaces OpenClaw de cette entreprise -- un plugin de fonctionnalité doit en général posséder toute la surface de la fonctionnalité qu'il introduit -- les canaux doivent consommer les capacités partagées du cœur au lieu de réimplémenter - de manière ad hoc le comportement des fournisseurs +- un plugin d’entreprise doit généralement posséder toutes les surfaces OpenClaw de cette entreprise +- un plugin de fonctionnalité doit généralement posséder l’ensemble de la surface de la fonctionnalité qu’il introduit +- les canaux doivent consommer les capacités partagées du cœur au lieu de réimplémenter de manière ad hoc le comportement des fournisseurs Exemples : -- le plugin intégré `openai` possède le comportement de fournisseur de modèles OpenAI et le comportement - OpenAI pour la parole + la voix temps réel + la compréhension des médias + la génération d'images -- le plugin intégré `elevenlabs` possède le comportement de parole ElevenLabs -- le plugin intégré `microsoft` possède le comportement de parole Microsoft -- le plugin intégré `google` possède le comportement de fournisseur de modèles Google ainsi que le comportement Google - pour la compréhension des médias + la génération d'images + la recherche web -- le plugin intégré `firecrawl` possède le comportement de récupération web Firecrawl -- les plugins intégrés `minimax`, `mistral`, `moonshot` et `zai` possèdent leurs - backends de compréhension des médias -- le plugin `voice-call` est un plugin de fonctionnalité : il possède le transport d'appel, les outils, - la CLI, les routes et le pont Twilio media-stream, mais il consomme des capacités partagées de parole - ainsi que de transcription temps réel et de voix temps réel au lieu d'importer directement des plugins fournisseurs +- le plugin bundled `openai` possède le comportement de fournisseur de modèles OpenAI et le comportement OpenAI pour la parole + la voix en temps réel + la compréhension des médias + la génération d’images +- le plugin bundled `elevenlabs` possède le comportement de parole ElevenLabs +- le plugin bundled `microsoft` possède le comportement de parole Microsoft +- le plugin bundled `google` possède le comportement de fournisseur de modèles Google ainsi que les comportements Google de compréhension des médias + génération d’images + recherche web +- le plugin bundled `firecrawl` possède le comportement de récupération web Firecrawl +- les plugins bundled `minimax`, `mistral`, `moonshot` et `zai` possèdent leurs backends de compréhension des médias +- le plugin bundled `qwen` possède le comportement de fournisseur de texte Qwen ainsi que les comportements de compréhension des médias et de génération de vidéos +- le plugin `voice-call` est un plugin de fonctionnalité : il possède le transport d’appel, les outils, + la CLI, les routes et le pontage de flux média Twilio, mais il consomme les capacités partagées de parole, + plus la transcription en temps réel et la voix en temps réel au lieu d’importer directement les plugins fournisseurs -L'état final visé est le suivant : +L’état final visé est : -- OpenAI vit dans un seul plugin même s'il couvre les modèles de texte, la parole, les images et - la vidéo à venir -- un autre fournisseur peut faire de même pour sa propre surface -- les canaux ne se soucient pas du plugin fournisseur qui possède le fournisseur ; ils consomment le - contrat de capacité partagé exposé par le cœur +- OpenAI se trouve dans un seul plugin même s’il couvre les modèles de texte, la parole, les images et, à l’avenir, la vidéo +- un autre fournisseur peut faire de même pour sa propre surface fonctionnelle +- les canaux ne se soucient pas du plugin fournisseur qui possède le fournisseur ; ils consomment le contrat de capacité partagé exposé par le cœur -Voici la distinction essentielle : +C’est la distinction clé : - **plugin** = limite de propriété -- **capacité** = contrat du cœur que plusieurs plugins peuvent implémenter ou consommer +- **capability** = contrat du cœur que plusieurs plugins peuvent implémenter ou consommer -Ainsi, si OpenClaw ajoute un nouveau domaine comme la vidéo, la première question n'est pas -« quel fournisseur doit coder en dur la gestion de la vidéo ? » La première question est -« quel est le contrat de capacité vidéo du cœur ? » Une fois ce contrat en place, les plugins fournisseurs -peuvent s'y enregistrer et les plugins de canal/de fonctionnalité peuvent le consommer. +Ainsi, si OpenClaw ajoute un nouveau domaine comme la vidéo, la première question n’est pas +« quel fournisseur doit coder en dur la gestion de la vidéo ? » La première question est « quel est +le contrat de capacité vidéo du cœur ? » Une fois ce contrat en place, les plugins fournisseurs +peuvent s’y enregistrer et les plugins de canal/de fonctionnalité peuvent le consommer. -Si la capacité n'existe pas encore, la bonne démarche est généralement : +Si la capacité n’existe pas encore, la bonne démarche est généralement : 1. définir la capacité manquante dans le cœur -2. l'exposer via l'API/le runtime du plugin de manière typée -3. câbler les canaux/fonctionnalités sur cette capacité -4. laisser les plugins fournisseurs enregistrer des implémentations +2. l’exposer de manière typée via l’API/l’exécution des plugins +3. raccorder les canaux/fonctionnalités à cette capacité +4. laisser les plugins fournisseurs enregistrer les implémentations -Cela maintient une propriété explicite tout en évitant un comportement du cœur dépendant d'un -seul fournisseur ou d'un chemin de code spécifique à un plugin isolé. +Cela permet de garder une propriété explicite tout en évitant un comportement du cœur qui dépend +d’un seul fournisseur ou d’un chemin de code spécifique à un plugin ponctuel. ### Stratification des capacités Utilisez ce modèle mental pour décider où le code doit se trouver : -- **couche de capacité du cœur** : orchestration partagée, politique, fallback, règles de fusion de configuration, - sémantique de livraison et contrats typés +- **couche de capacité du cœur** : orchestration partagée, politique, repli, + règles de fusion de configuration, sémantique de livraison et contrats typés - **couche de plugin fournisseur** : API spécifiques au fournisseur, authentification, catalogues de modèles, synthèse vocale, - génération d'images, futurs backends vidéo, endpoints d'usage -- **couche de plugin canal/fonctionnalité** : intégration Slack/Discord/voice-call/etc. + génération d’images, backends vidéo futurs, points de terminaison d’usage +- **couche de plugin de canal/fonctionnalité** : intégration Slack/Discord/voice-call/etc. qui consomme les capacités du cœur et les présente sur une surface Par exemple, la synthèse vocale suit cette forme : -- le cœur possède la politique TTS au moment de la réponse, l'ordre de fallback, les préférences et la livraison par canal +- le cœur possède la politique TTS au moment de la réponse, l’ordre de repli, les préférences et la livraison au canal - `openai`, `elevenlabs` et `microsoft` possèdent les implémentations de synthèse -- `voice-call` consomme le helper runtime TTS de téléphonie +- `voice-call` consomme l’assistant d’exécution TTS de téléphonie -Ce même modèle doit être préféré pour les capacités futures. +Ce même schéma doit être privilégié pour les capacités futures. -### Exemple de plugin d'entreprise multi-capacités +### Exemple de plugin d’entreprise multi-capacités -Un plugin d'entreprise doit sembler cohérent vu de l'extérieur. Si OpenClaw dispose de -contrats partagés pour les modèles, la parole, la transcription temps réel, la voix temps réel, la compréhension des médias, -la génération d'images, la génération de vidéo, la récupération web et la recherche web, -un fournisseur peut posséder toutes ses surfaces en un seul endroit : +Un plugin d’entreprise doit sembler cohérent de l’extérieur. Si OpenClaw a des +contrats partagés pour les modèles, la parole, la transcription en temps réel, la voix en temps réel, la +compréhension des médias, la génération d’images, la génération de vidéos, la récupération web et la recherche web, +un fournisseur peut posséder toutes ses surfaces au même endroit : ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -320,12 +302,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hooks auth/catalogue de modèles/runtime + // hooks d’authentification/de catalogue de modèles/d’exécution }); api.registerSpeechProvider({ id: "exampleai", - // configuration de parole fournisseur — implémente directement l'interface SpeechProviderPlugin + // config de parole du fournisseur — implémente directement l’interface SpeechProviderPlugin }); api.registerMediaUnderstandingProvider({ @@ -350,7 +332,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // logique d'identifiants + de récupération + // logique d’identifiants + de récupération }), ); }, @@ -359,65 +341,64 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Ce qui compte n'est pas le nom exact des helpers. C'est la forme qui importe : +Ce qui compte, ce ne sont pas les noms exacts des assistants. C’est la forme qui compte : - un seul plugin possède la surface du fournisseur - le cœur possède toujours les contrats de capacité -- les canaux et plugins de fonctionnalité consomment les helpers `api.runtime.*`, pas le code fournisseur -- les tests de contrat peuvent vérifier que le plugin a enregistré les capacités qu'il - prétend posséder +- les canaux et plugins de fonctionnalité consomment les assistants `api.runtime.*`, pas le code du fournisseur +- les tests de contrat peuvent vérifier que le plugin a enregistré les capacités + qu’il prétend posséder ### Exemple de capacité : compréhension vidéo -OpenClaw traite déjà la compréhension d'image/audio/vidéo comme une capacité partagée unique. -Le même modèle de propriété s'y applique : +OpenClaw traite déjà la compréhension d’image/audio/vidéo comme une seule +capacité partagée. Le même modèle de propriété s’y applique : 1. le cœur définit le contrat de compréhension des médias 2. les plugins fournisseurs enregistrent `describeImage`, `transcribeAudio` et `describeVideo` selon le cas 3. les canaux et plugins de fonctionnalité consomment le comportement partagé du cœur au lieu de - se connecter directement au code fournisseur + se raccorder directement au code du fournisseur -Cela évite d'intégrer dans le cœur les hypothèses vidéo d'un seul fournisseur. Le plugin possède -la surface du fournisseur ; le cœur possède le contrat de capacité et le comportement de fallback. +Cela évite d’intégrer dans le cœur les hypothèses vidéo d’un seul fournisseur. Le plugin possède +la surface du fournisseur ; le cœur possède le contrat de capacité et le comportement de repli. -La génération de vidéo suit déjà cette même séquence : le cœur possède le contrat de capacité typé -et le helper runtime, et les plugins fournisseurs enregistrent des implémentations -`api.registerVideoGenerationProvider(...)` dessus. +La génération vidéo utilise déjà cette même séquence : le cœur possède le +contrat de capacité typé et l’assistant d’exécution, et les plugins fournisseurs enregistrent +des implémentations `api.registerVideoGenerationProvider(...)` sur cette base. -Besoin d'une checklist concrète de déploiement ? Voir -[Capability Cookbook](/fr/plugins/architecture). +Besoin d’une liste de déploiement concrète ? Voir +[Recettes de capacités](/fr/plugins/architecture). ## Contrats et application -La surface de l'API des plugins est volontairement typée et centralisée dans -`OpenClawPluginApi`. Ce contrat définit les points d'enregistrement pris en charge et -les helpers runtime sur lesquels un plugin peut s'appuyer. +La surface de l’API des plugins est intentionnellement typée et centralisée dans +`OpenClawPluginApi`. Ce contrat définit les points d’enregistrement pris en charge et +les assistants d’exécution sur lesquels un plugin peut s’appuyer. -Pourquoi c'est important : +Pourquoi c’est important : -- les auteurs de plugins obtiennent une norme interne stable unique -- le cœur peut rejeter une propriété en doublon, par exemple deux plugins enregistrant le même identifiant de fournisseur -- le démarrage peut exposer des diagnostics exploitables pour un enregistrement mal formé -- les tests de contrat peuvent imposer la propriété des plugins intégrés et empêcher une dérive silencieuse +- les auteurs de plugins bénéficient d’une norme interne stable +- le cœur peut rejeter une propriété en double, par exemple deux plugins enregistrant le même identifiant de fournisseur +- le démarrage peut afficher des diagnostics exploitables pour un enregistrement mal formé +- les tests de contrat peuvent imposer la propriété des plugins bundled et éviter les dérives silencieuses -Il existe deux couches d'application : +Il existe deux couches d’application : -1. **application de l'enregistrement à l'exécution** +1. **application de l’enregistrement à l’exécution** Le registre des plugins valide les enregistrements à mesure que les plugins se chargent. Exemples : - identifiants de fournisseur dupliqués, identifiants de fournisseur de parole dupliqués et enregistrements - mal formés produisent des diagnostics de plugin au lieu d'un comportement indéfini. + les identifiants de fournisseurs en double, les identifiants de fournisseurs de parole en double, et les + enregistrements mal formés produisent des diagnostics de plugin au lieu d’un comportement indéfini. 2. **tests de contrat** - Les plugins intégrés sont capturés dans des registres de contrat pendant les tests afin - qu'OpenClaw puisse vérifier explicitement la propriété. Aujourd'hui, cela est utilisé pour les - fournisseurs de modèles, les fournisseurs de parole, les fournisseurs de recherche web et la propriété - des enregistrements intégrés. + Les plugins bundled sont capturés dans des registres de contrat pendant les exécutions de test afin + qu’OpenClaw puisse affirmer explicitement la propriété. Aujourd’hui, cela est utilisé pour les + fournisseurs de modèles, fournisseurs de parole, fournisseurs de recherche web et la propriété de l’enregistrement bundled. -L'effet pratique est qu'OpenClaw sait, dès le départ, quel plugin possède quelle -surface. Cela permet au cœur et aux canaux de se composer proprement, car la propriété est -déclarée, typée et testable plutôt qu'implicite. +L’effet pratique est qu’OpenClaw sait, dès le départ, quel plugin possède quelle +surface. Cela permet au cœur et aux canaux de se composer de manière fluide parce que la propriété est +déclarée, typée et testable plutôt qu’implicite. -### Ce qui doit figurer dans un contrat +### Ce qui a sa place dans un contrat Les bons contrats de plugin sont : @@ -426,22 +407,22 @@ Les bons contrats de plugin sont : - spécifiques à une capacité - possédés par le cœur - réutilisables par plusieurs plugins -- consommables par des canaux/fonctionnalités sans connaissance du fournisseur +- consommables par les canaux/fonctionnalités sans connaissance d’un fournisseur Les mauvais contrats de plugin sont : - une politique spécifique au fournisseur cachée dans le cœur -- des échappatoires ponctuelles pour un plugin qui contournent le registre -- du code de canal qui accède directement à une implémentation fournisseur -- des objets runtime ad hoc qui ne font pas partie de `OpenClawPluginApi` ou de +- des échappatoires ponctuelles de plugin qui contournent le registre +- du code de canal qui accède directement à une implémentation de fournisseur +- des objets d’exécution ad hoc qui ne font pas partie de `OpenClawPluginApi` ou de `api.runtime` -En cas de doute, montez le niveau d'abstraction : définissez d'abord la capacité, puis -laissez les plugins s'y brancher. +En cas de doute, élevez le niveau d’abstraction : définissez d’abord la capacité, puis +laissez les plugins s’y brancher. -## Modèle d'exécution +## Modèle d’exécution -Les plugins OpenClaw natifs s'exécutent **dans le processus** avec la Gateway. Ils ne sont pas +Les plugins OpenClaw natifs s’exécutent **dans le processus** avec la Gateway. Ils ne sont pas sandboxés. Un plugin natif chargé partage la même limite de confiance au niveau du processus que le code du cœur. @@ -449,80 +430,83 @@ Implications : - un plugin natif peut enregistrer des outils, des gestionnaires réseau, des hooks et des services - un bug dans un plugin natif peut faire planter ou déstabiliser la gateway -- un plugin natif malveillant équivaut à une exécution de code arbitraire à l'intérieur - du processus OpenClaw +- un plugin natif malveillant équivaut à une exécution de code arbitraire dans le processus OpenClaw -Les bundles compatibles sont plus sûrs par défaut car OpenClaw les traite actuellement +Les bundles compatibles sont plus sûrs par défaut parce qu’OpenClaw les traite actuellement comme des packs de métadonnées/contenu. Dans les versions actuelles, cela signifie surtout des -Skills intégrées. +Skills bundled. -Utilisez des listes d'autorisation et des chemins explicites d'installation/de chargement pour les plugins non intégrés. -Considérez les plugins d'espace de travail comme du code de développement, pas comme des valeurs par défaut de production. +Utilisez des listes d’autorisation et des chemins d’installation/de chargement explicites pour les plugins non bundled. Traitez +les plugins d’espace de travail comme du code de développement, et non comme des valeurs par défaut de production. -Pour les noms de paquets de l'espace de travail intégrés, conservez l'identifiant du plugin ancré dans le nom npm : +Pour les noms de packages d’espace de travail bundled, gardez l’identifiant du plugin ancré dans le nom npm : `@openclaw/` par défaut, ou un suffixe typé approuvé tel que `-provider`, `-plugin`, `-speech`, `-sandbox` ou `-media-understanding` lorsque -le paquet expose intentionnellement un rôle de plugin plus étroit. +le package expose intentionnellement un rôle de plugin plus étroit. Note de confiance importante : -- `plugins.allow` fait confiance aux **identifiants de plugin**, pas à la provenance de la source. -- Un plugin d'espace de travail ayant le même identifiant qu'un plugin intégré masque volontairement - la copie intégrée lorsque ce plugin d'espace de travail est activé/sur liste d'autorisation. -- C'est normal et utile pour le développement local, les tests de correctifs et les correctifs à chaud. +- `plugins.allow` fait confiance aux **identifiants de plugin**, et non à la provenance de la source. +- Un plugin d’espace de travail portant le même identifiant qu’un plugin bundled masque intentionnellement + la copie bundled lorsque ce plugin d’espace de travail est activé/sur liste d’autorisation. +- C’est normal et utile pour le développement local, les tests de correctifs et les correctifs urgents. -## Frontière d'export +## Limite d’export -OpenClaw exporte des capacités, pas des commodités d'implémentation. +OpenClaw exporte des capacités, pas des commodités d’implémentation. -Gardez l'enregistrement des capacités public. Réduisez les exports helper hors contrat : +Gardez l’enregistrement des capacités public. Réduisez les exports d’assistance hors contrat : -- sous-chemins helper spécifiques à un plugin intégré -- sous-chemins de plomberie runtime non destinés à être une API publique -- helpers de commodité spécifiques à un fournisseur -- helpers de configuration/d'onboarding qui sont des détails d'implémentation +- sous-chemins d’assistance spécifiques à un plugin bundled +- sous-chemins de plomberie d’exécution non destinés à l’API publique +- assistants de commodité spécifiques à un fournisseur +- assistants de configuration/d’onboarding qui sont des détails d’implémentation -Certains sous-chemins helper de plugins intégrés restent encore dans la carte d'export -SDK générée pour la compatibilité et la maintenance des plugins intégrés. Exemples actuels : +Certains sous-chemins d’assistance de plugins bundled restent encore présents dans la carte d’exports SDK générée +pour des raisons de compatibilité et de maintenance des plugins bundled. Exemples actuels : `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` et plusieurs seams `plugin-sdk/matrix*`. Traitez-les comme -des exports réservés de détail d'implémentation, et non comme le modèle SDK recommandé pour +`plugin-sdk/zalo-setup`, et plusieurs points d’intégration `plugin-sdk/matrix*`. Traitez-les comme des +exports réservés de détail d’implémentation, et non comme le modèle SDK recommandé pour de nouveaux plugins tiers. ## Pipeline de chargement -Au démarrage, OpenClaw fait approximativement ceci : +Au démarrage, OpenClaw fait grosso modo ceci : -1. découvrir les racines de plugins candidates -2. lire les manifestes natifs ou de bundles compatibles et les métadonnées de paquet -3. rejeter les candidats non sûrs -4. normaliser la configuration des plugins (`plugins.enabled`, `allow`, `deny`, `entries`, +1. découvre les racines de plugins candidates +2. lit les manifestes natifs ou de bundles compatibles et les métadonnées de package +3. rejette les candidats non sûrs +4. normalise la configuration des plugins (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. décider de l'activation de chaque candidat -6. charger les modules natifs activés via jiti -7. appeler les hooks natifs `register(api)` (ou `activate(api)` — un alias legacy) et collecter les enregistrements dans le registre des plugins -8. exposer le registre aux surfaces commandes/runtime +5. décide de l’activation pour chaque candidat +6. charge les modules natifs activés via jiti +7. appelle les hooks natifs `register(api)` (ou `activate(api)` — un alias legacy) et collecte les enregistrements dans le registre des plugins +8. expose le registre aux surfaces de commandes/d’exécution -`activate` est un alias legacy de `register` — le chargeur résout la présence de l'un ou de l'autre (`def.register ?? def.activate`) et l'appelle au même moment. Tous les plugins intégrés utilisent `register` ; préférez `register` pour les nouveaux plugins. +`activate` est un alias legacy de `register` — le chargeur résout celui qui est présent (`def.register ?? def.activate`) et l’appelle au même moment. Tous les plugins bundled utilisent `register` ; préférez `register` pour les nouveaux plugins. -Les garde-fous de sécurité se produisent **avant** l'exécution du runtime. Les candidats sont bloqués -lorsque l'entrée sort de la racine du plugin, que le chemin est modifiable par tous, ou que la propriété du chemin -semble suspecte pour les plugins non intégrés. +Les barrières de sécurité interviennent **avant** l’exécution à l’exécution. Les candidats sont bloqués +lorsque le point d’entrée sort de la racine du plugin, que le chemin est accessible en écriture par tout le monde, ou que la propriété du chemin semble suspecte pour les plugins non bundled. -### Comportement orienté manifeste +### Comportement manifest-first -Le manifeste est la source de vérité du plan de contrôle. OpenClaw l'utilise pour : +Le manifeste est la source de vérité du plan de contrôle. OpenClaw l’utilise pour : - identifier le plugin -- découvrir les canaux/Skills/schéma de configuration déclarés ou les capacités du bundle +- découvrir les canaux/Skills/schéma de configuration déclarés ou les capacités de bundle - valider `plugins.entries..config` -- enrichir les libellés/placeholders du Control UI -- afficher les métadonnées d'installation/de catalogue +- enrichir les libellés/placeholders de l’interface de contrôle +- afficher les métadonnées d’installation/de catalogue +- conserver des descripteurs bon marché d’activation et de configuration sans charger l’exécution du plugin -Pour les plugins natifs, le module runtime est la partie plan de données. Il enregistre -le comportement réel comme les hooks, outils, commandes ou flux de fournisseur. +Pour les plugins natifs, le module d’exécution est la partie plan de données. Il enregistre le +comportement réel tel que hooks, outils, commandes ou flux de fournisseur. + +Les blocs facultatifs `activation` et `setup` du manifeste restent sur le plan de contrôle. +Ce sont des descripteurs de métadonnées uniquement pour la planification d’activation et la découverte de configuration ; +ils ne remplacent pas l’enregistrement d’exécution, `register(...)` ou `setupEntry`. ### Ce que le chargeur met en cache @@ -532,10 +516,10 @@ OpenClaw conserve de courts caches en processus pour : - les données du registre de manifestes - les registres de plugins chargés -Ces caches réduisent les démarrages brusques et la surcharge de commandes répétées. Vous pouvez -les considérer comme des caches de performance de courte durée, pas comme de la persistance. +Ces caches réduisent les démarrages brusques et la surcharge des commandes répétées. On peut les considérer sans danger +comme des caches de performance à courte durée de vie, et non comme de la persistance. -Note de performance : +Note sur les performances : - Définissez `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` ou `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` pour désactiver ces caches. @@ -544,38 +528,37 @@ Note de performance : ## Modèle de registre -Les plugins chargés ne modifient pas directement des globals aléatoires du cœur. Ils s'enregistrent dans un -registre central de plugins. +Les plugins chargés ne mutent pas directement des variables globales arbitraires du cœur. Ils s’enregistrent dans un +registre central des plugins. Le registre suit : -- les enregistrements de plugin (identité, source, origine, statut, diagnostics) +- les enregistrements de plugins (identité, source, origine, statut, diagnostics) - les outils -- les hooks legacy et les hooks typés +- les hooks legacy et hooks typés - les canaux - les fournisseurs -- les gestionnaires RPC Gateway +- les gestionnaires Gateway RPC - les routes HTTP -- les registrars CLI -- les services en arrière-plan +- les enregistreurs CLI +- les services d’arrière-plan - les commandes appartenant au plugin -Les fonctionnalités du cœur lisent ensuite ce registre au lieu de communiquer directement avec les modules -de plugin. Cela conserve un chargement à sens unique : +Les fonctionnalités du cœur lisent ensuite ce registre au lieu de parler directement aux modules de plugin. +Cela maintient un chargement à sens unique : - module de plugin -> enregistrement dans le registre -- runtime du cœur -> consommation du registre +- exécution du cœur -> consommation du registre -Cette séparation est importante pour la maintenabilité. Elle signifie que la plupart des surfaces du cœur n'ont besoin -que d'un seul point d'intégration : « lire le registre », et non « traiter chaque module -de plugin comme un cas particulier ». +Cette séparation est importante pour la maintenabilité. Cela signifie que la plupart des surfaces du cœur n’ont besoin +que d’un seul point d’intégration : « lire le registre », et non « traiter spécialement chaque module de plugin ». ## Callbacks de liaison de conversation -Les plugins qui lient une conversation peuvent réagir lorsqu'une approbation est résolue. +Les plugins qui lient une conversation peuvent réagir lorsqu’une approbation est résolue. -Utilisez `api.onConversationBindingResolved(...)` pour recevoir un callback après qu'une -demande de liaison a été approuvée ou refusée : +Utilisez `api.onConversationBindingResolved(...)` pour recevoir un callback après qu’une requête de liaison +est approuvée ou refusée : ```ts export default { @@ -588,7 +571,7 @@ export default { return; } - // La demande a été refusée ; effacez tout état local en attente. + // La requête a été refusée ; effacez tout état local en attente. console.log(event.request.conversation.conversationId); }); }, @@ -599,24 +582,24 @@ Champs de la charge utile du callback : - `status`: `"approved"` ou `"denied"` - `decision`: `"allow-once"`, `"allow-always"` ou `"deny"` -- `binding`: la liaison résolue pour les demandes approuvées -- `request`: le résumé de la demande d'origine, l'indice de détachement, l'identifiant d'expéditeur et +- `binding`: la liaison résolue pour les requêtes approuvées +- `request`: le résumé de la requête d’origine, l’indication de détachement, l’identifiant de l’expéditeur et les métadonnées de conversation Ce callback est uniquement une notification. Il ne modifie pas qui est autorisé à lier une -conversation, et il s'exécute après la fin du traitement d'approbation du cœur. +conversation, et il s’exécute une fois le traitement d’approbation du cœur terminé. -## Hooks runtime de fournisseur +## Hooks d’exécution du fournisseur Les plugins de fournisseur ont désormais deux couches : -- métadonnées du manifeste : `providerAuthEnvVars` pour une recherche bon marché de l'auth fournisseur via les variables d'environnement - avant le chargement du runtime, `providerAuthAliases` pour les variantes de fournisseur qui partagent - l'authentification, `channelEnvVars` pour une recherche bon marché de l'auth/de la configuration du canal avant - le chargement du runtime, ainsi que `providerAuthChoices` pour des libellés bon marché - d'onboarding/de choix d'authentification et des métadonnées de flags CLI avant le chargement du runtime -- hooks au moment de la configuration : `catalog` / `discovery` legacy plus `applyConfigDefaults` -- hooks runtime : `normalizeModelId`, `normalizeTransport`, +- métadonnées de manifeste : `providerAuthEnvVars` pour une recherche légère de l’authentification du fournisseur par variable d’environnement + avant le chargement de l’exécution, `providerAuthAliases` pour les variantes de fournisseur qui partagent + l’authentification, `channelEnvVars` pour une recherche légère de l’environnement/de la configuration du canal avant le + chargement de l’exécution, ainsi que `providerAuthChoices` pour des libellés légers d’onboarding/de choix d’authentification et + des métadonnées d’indicateurs CLI avant le chargement de l’exécution +- hooks au moment de la configuration : `catalog` / ancien `discovery` plus `applyConfigDefaults` +- hooks d’exécution : `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -636,87 +619,85 @@ Les plugins de fournisseur ont désormais deux couches : `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw possède toujours la boucle générique d'agent, le failover, la gestion des transcriptions et la -politique d'outils. Ces hooks constituent la surface d'extension pour le comportement spécifique au fournisseur sans -nécessiter tout un transport d'inférence personnalisé. +OpenClaw possède toujours la boucle d’agent générique, le basculement, la gestion des transcriptions et +la politique des outils. Ces hooks constituent la surface d’extension pour le comportement spécifique au fournisseur sans +avoir besoin d’un transport d’inférence entièrement personnalisé. -Utilisez le manifeste `providerAuthEnvVars` lorsque le fournisseur possède des identifiants basés sur des variables d'environnement -que les chemins génériques auth/statut/sélecteur de modèles doivent voir sans charger le runtime du plugin. -Utilisez le manifeste `providerAuthAliases` lorsqu'un identifiant de fournisseur doit réutiliser -les variables d'environnement, profils d'auth, auth basée sur la configuration et choix d'onboarding par clé API -d'un autre identifiant de fournisseur. Utilisez le manifeste `providerAuthChoices` lorsque les surfaces -CLI d'onboarding/de choix d'auth doivent connaître l'identifiant de choix du fournisseur, les libellés de groupe et le câblage -simple d'authentification à un seul flag sans charger le runtime du fournisseur. Conservez le runtime de fournisseur -`envVars` pour les indices orientés opérateur tels que les libellés d'onboarding ou les variables -de configuration OAuth client-id/client-secret. +Utilisez le `providerAuthEnvVars` du manifeste lorsque le fournisseur dispose d’identifiants basés sur l’environnement +que les chemins génériques d’authentification/statut/sélecteur de modèle doivent voir sans charger l’exécution du plugin. +Utilisez `providerAuthAliases` du manifeste lorsqu’un identifiant de fournisseur doit réutiliser +les variables d’environnement, profils d’authentification, authentification basée sur la configuration et choix d’onboarding par clé API d’un autre identifiant de fournisseur. +Utilisez `providerAuthChoices` du manifeste lorsque les +surfaces CLI d’onboarding/de choix d’authentification doivent connaître l’identifiant de choix du fournisseur, les libellés de groupe et le câblage simple d’authentification par indicateur unique sans charger l’exécution du fournisseur. Conservez `envVars` de l’exécution du fournisseur pour les indications destinées à l’opérateur, comme les libellés d’onboarding ou les +variables de configuration de client OAuth `client-id`/`client-secret`. -Utilisez le manifeste `channelEnvVars` lorsqu'un canal possède une auth ou une configuration pilotée par des variables d'environnement que -le fallback générique shell-env, les vérifications config/status ou les invites de configuration doivent voir -sans charger le runtime du canal. +Utilisez `channelEnvVars` du manifeste lorsqu’un canal possède une authentification ou une configuration pilotée par l’environnement +que le repli générique sur l’environnement shell, les vérifications config/statut ou les invites de configuration doivent voir +sans charger l’exécution du canal. -### Ordre des hooks et utilisation +### Ordre et usage des hooks -Pour les plugins de modèle/fournisseur, OpenClaw appelle les hooks dans cet ordre approximatif. -La colonne « Quand l'utiliser » est le guide de décision rapide. +Pour les plugins de modèle/fournisseur, OpenClaw appelle les hooks approximativement dans cet ordre. +La colonne « Quand l’utiliser » sert de guide rapide de décision. -| # | Hook | Ce qu'il fait | Quand l'utiliser | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publie la configuration du fournisseur dans `models.providers` pendant la génération de `models.json` | Le fournisseur possède un catalogue ou des valeurs par défaut de base URL | -| 2 | `applyConfigDefaults` | Applique les valeurs par défaut globales de configuration du fournisseur lors de la matérialisation de la configuration | Les valeurs par défaut dépendent du mode d'auth, de l'environnement ou de la sémantique de la famille de modèles du fournisseur | -| -- | _(recherche de modèle intégrée)_ | OpenClaw essaie d'abord le chemin normal de registre/catalogue | _(ce n'est pas un hook de plugin)_ | -| 3 | `normalizeModelId` | Normalise les alias legacy ou preview d'identifiants de modèle avant la recherche | Le fournisseur possède le nettoyage des alias avant la résolution canonique du modèle | -| 4 | `normalizeTransport` | Normalise `api` / `baseUrl` de la famille de fournisseurs avant l'assemblage générique du modèle | Le fournisseur possède le nettoyage du transport pour des identifiants de fournisseur personnalisés dans la même famille de transport | -| 5 | `normalizeConfig` | Normalise `models.providers.` avant la résolution runtime/fournisseur | Le fournisseur a besoin d'un nettoyage de configuration qui doit vivre avec le plugin ; les helpers intégrés de la famille Google servent aussi de filet de sécurité pour les entrées de configuration Google prises en charge | -| 6 | `applyNativeStreamingUsageCompat` | Applique des réécritures de compatibilité native d'usage de streaming aux fournisseurs de configuration | Le fournisseur a besoin de correctifs de métadonnées d'usage de streaming dictés par l'endpoint | -| 7 | `resolveConfigApiKey` | Résout l'auth à marqueur d'environnement pour les fournisseurs de configuration avant le chargement de l'auth runtime | Le fournisseur possède sa propre résolution de clé API à marqueur d'environnement ; `amazon-bedrock` dispose aussi ici d'un résolveur intégré de marqueur d'environnement AWS | -| 8 | `resolveSyntheticAuth` | Expose une auth locale/autohébergée ou basée sur la configuration sans persister de texte en clair | Le fournisseur peut fonctionner avec un marqueur d'identifiant synthétique/local | -| 9 | `resolveExternalAuthProfiles` | Superpose les profils d'auth externes appartenant au fournisseur ; la `persistence` par défaut est `runtime-only` pour les identifiants possédés par la CLI/l'app | Le fournisseur réutilise des identifiants d'auth externes sans persister de jetons d'actualisation copiés | -| 10 | `shouldDeferSyntheticProfileAuth` | Relègue les placeholders de profil synthétique stockés derrière l'auth basée sur l'env/la configuration | Le fournisseur stocke des profils placeholders synthétiques qui ne doivent pas avoir la priorité | -| 11 | `resolveDynamicModel` | Fallback synchrone pour les identifiants de modèle appartenant au fournisseur mais pas encore dans le registre local | Le fournisseur accepte des identifiants de modèle upstream arbitraires | -| 12 | `prepareDynamicModel` | Préchauffage asynchrone, puis `resolveDynamicModel` s'exécute de nouveau | Le fournisseur a besoin de métadonnées réseau avant de résoudre des identifiants inconnus | -| 13 | `normalizeResolvedModel` | Réécriture finale avant que le runner embarqué n'utilise le modèle résolu | Le fournisseur a besoin de réécritures de transport tout en utilisant un transport du cœur | -| 14 | `contributeResolvedModelCompat` | Apporte des drapeaux de compatibilité pour des modèles fournisseurs derrière un autre transport compatible | Le fournisseur reconnaît ses propres modèles sur des transports proxy sans prendre la main sur le fournisseur | -| 15 | `capabilities` | Métadonnées de transcription/outillage appartenant au fournisseur et utilisées par la logique partagée du cœur | Le fournisseur a besoin de particularités de transcription/famille de fournisseur | -| 16 | `normalizeToolSchemas` | Normalise les schémas d'outils avant que le runner embarqué ne les voie | Le fournisseur a besoin d'un nettoyage de schéma propre à la famille de transport | -| 17 | `inspectToolSchemas` | Expose les diagnostics de schéma appartenant au fournisseur après normalisation | Le fournisseur veut des avertissements sur des mots-clés sans enseigner au cœur des règles spécifiques au fournisseur | -| 18 | `resolveReasoningOutputMode` | Sélectionne le contrat de sortie de raisonnement natif ou avec balises | Le fournisseur a besoin d'une sortie raisonnement/finale avec balises plutôt que de champs natifs | -| 19 | `prepareExtraParams` | Normalisation des paramètres de requête avant les wrappers génériques d'options de stream | Le fournisseur a besoin de paramètres de requête par défaut ou d'un nettoyage par fournisseur | -| 20 | `createStreamFn` | Remplace complètement le chemin de stream normal par un transport personnalisé | Le fournisseur a besoin d'un protocole filaire personnalisé, pas seulement d'un wrapper | -| 21 | `wrapStreamFn` | Wrapper de stream après l'application des wrappers génériques | Le fournisseur a besoin de wrappers de compatibilité d'en-têtes/corps/modèle de requête sans transport personnalisé | -| 22 | `resolveTransportTurnState` | Attache des en-têtes ou métadonnées natifs par tour de transport | Le fournisseur veut que les transports génériques envoient une identité de tour native du fournisseur | -| 23 | `resolveWebSocketSessionPolicy` | Attache des en-têtes WebSocket natifs ou une politique de refroidissement de session | Le fournisseur veut que les transports WS génériques ajustent les en-têtes de session ou la politique de fallback | -| 24 | `formatApiKey` | Formateur de profil d'auth : le profil stocké devient la chaîne `apiKey` du runtime | Le fournisseur stocke des métadonnées d'auth supplémentaires et a besoin d'une forme de jeton runtime personnalisée | -| 25 | `refreshOAuth` | Surcharge d'actualisation OAuth pour des endpoints d'actualisation personnalisés ou une politique d'échec d'actualisation | Le fournisseur ne correspond pas aux actualisateurs partagés `pi-ai` | -| 26 | `buildAuthDoctorHint` | Indice de réparation ajouté lorsqu'une actualisation OAuth échoue | Le fournisseur a besoin de sa propre guidance de réparation d'auth après échec d'actualisation | -| 27 | `matchesContextOverflowError` | Détecteur d'overflow de fenêtre de contexte appartenant au fournisseur | Le fournisseur a des erreurs brutes d'overflow que les heuristiques génériques manqueraient | -| 28 | `classifyFailoverReason` | Classification de la raison de failover appartenant au fournisseur | Le fournisseur peut mapper des erreurs brutes d'API/transport vers rate-limit/surcharge/etc. | -| 29 | `isCacheTtlEligible` | Politique de cache de prompt pour les fournisseurs proxy/backhaul | Le fournisseur a besoin d'un filtrage TTL de cache spécifique au proxy | -| 30 | `buildMissingAuthMessage` | Remplacement du message générique de récupération d'auth manquante | Le fournisseur a besoin de son propre indice de récupération d'auth manquante | -| 31 | `suppressBuiltInModel` | Suppression d'un modèle upstream obsolète avec indice d'erreur orienté utilisateur en option | Le fournisseur a besoin de masquer des lignes upstream obsolètes ou de les remplacer par un indice fournisseur | -| 32 | `augmentModelCatalog` | Lignes de catalogue synthétiques/finales ajoutées après la découverte | Le fournisseur a besoin de lignes synthétiques de compatibilité ascendante dans `models list` et les sélecteurs | -| 33 | `isBinaryThinking` | Bascule de raisonnement activé/désactivé pour les fournisseurs à raisonnement binaire | Le fournisseur n'expose qu'un mode binaire activé/désactivé | -| 34 | `supportsXHighThinking` | Prise en charge du raisonnement `xhigh` pour des modèles sélectionnés | Le fournisseur veut `xhigh` uniquement sur un sous-ensemble de modèles | -| 35 | `resolveDefaultThinkingLevel` | Niveau `/think` par défaut pour une famille spécifique de modèles | Le fournisseur possède la politique `/think` par défaut d'une famille de modèles | -| 36 | `isModernModelRef` | Détecteur de modèle moderne pour les filtres de profils live et la sélection smoke | Le fournisseur possède la correspondance des modèles préférés live/smoke | -| 37 | `prepareRuntimeAuth` | Échange un identifiant configuré contre le vrai jeton/la vraie clé runtime juste avant l'inférence | Le fournisseur a besoin d'un échange de jeton ou d'un identifiant de requête de courte durée | -| 38 | `resolveUsageAuth` | Résout les identifiants d'usage/de facturation pour `/usage` et les surfaces de statut associées | Le fournisseur a besoin d'une analyse personnalisée du jeton d'usage/quota ou d'un autre identifiant d'usage | -| 39 | `fetchUsageSnapshot` | Récupère et normalise des instantanés d'usage/quota propres au fournisseur après résolution de l'auth | Le fournisseur a besoin d'un endpoint d'usage propre ou d'un parseur de charge utile | -| 40 | `createEmbeddingProvider` | Construit un adaptateur d'embeddings appartenant au fournisseur pour mémoire/recherche | Le comportement d'embedding mémoire appartient au plugin fournisseur | -| 41 | `buildReplayPolicy` | Renvoie une politique de replay contrôlant la gestion des transcriptions pour le fournisseur | Le fournisseur a besoin d'une politique de transcription personnalisée (par ex. suppression de blocs de réflexion) | -| 42 | `sanitizeReplayHistory` | Réécrit l'historique de replay après le nettoyage générique des transcriptions | Le fournisseur a besoin de réécritures de replay spécifiques au fournisseur au-delà des helpers de compaction partagés | -| 43 | `validateReplayTurns` | Validation ou remodelage final des tours de replay avant le runner embarqué | Le transport du fournisseur a besoin d'une validation plus stricte des tours après l'assainissement générique | -| 44 | `onModelSelected` | Exécute des effets de bord appartenant au fournisseur après sélection d'un modèle | Le fournisseur a besoin de télémétrie ou d'état possédé par le fournisseur lorsqu'un modèle devient actif | +| # | Hook | Ce qu’il fait | Quand l’utiliser | +| --- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Publie la configuration du fournisseur dans `models.providers` pendant la génération de `models.json` | Le fournisseur possède un catalogue ou des valeurs par défaut de base URL | +| 2 | `applyConfigDefaults` | Applique les valeurs par défaut globales de configuration appartenant au fournisseur pendant la matérialisation de la configuration | Les valeurs par défaut dépendent du mode d’authentification, de l’environnement ou de la sémantique de famille de modèles du fournisseur | +| -- | _(recherche de modèle intégrée)_ | OpenClaw essaie d’abord le chemin normal registre/catalogue | _(pas un hook de plugin)_ | +| 3 | `normalizeModelId` | Normalise les alias legacy ou de préversion des identifiants de modèle avant la recherche | Le fournisseur possède le nettoyage des alias avant la résolution canonique du modèle | +| 4 | `normalizeTransport` | Normalise `api` / `baseUrl` d’une famille de fournisseurs avant l’assemblage générique du modèle | Le fournisseur possède le nettoyage du transport pour des identifiants de fournisseurs personnalisés dans la même famille de transport | +| 5 | `normalizeConfig` | Normalise `models.providers.` avant la résolution d’exécution/du fournisseur | Le fournisseur a besoin d’un nettoyage de configuration qui doit vivre avec le plugin ; les assistants bundled de la famille Google servent aussi de solution de secours pour les entrées de configuration Google prises en charge | +| 6 | `applyNativeStreamingUsageCompat` | Applique aux fournisseurs de configuration des réécritures de compatibilité d’usage en streaming natif | Le fournisseur a besoin de correctifs de métadonnées d’usage en streaming natif pilotés par le point de terminaison | +| 7 | `resolveConfigApiKey` | Résout l’authentification par marqueur d’environnement pour les fournisseurs de configuration avant le chargement de l’authentification d’exécution | Le fournisseur possède sa propre résolution de clé API par marqueur d’environnement ; `amazon-bedrock` a aussi ici un résolveur intégré de marqueur d’environnement AWS | +| 8 | `resolveSyntheticAuth` | Expose une authentification locale/autohébergée ou adossée à la configuration sans persister du texte brut | Le fournisseur peut fonctionner avec un marqueur d’identifiants synthétiques/locaux | +| 9 | `resolveExternalAuthProfiles` | Superpose des profils d’authentification externe appartenant au fournisseur ; `persistence` vaut par défaut `runtime-only` pour les identifiants détenus par la CLI/l’application | Le fournisseur réutilise des identifiants d’authentification externes sans persister de jetons d’actualisation copiés | +| 10 | `shouldDeferSyntheticProfileAuth` | Fait passer les placeholders de profils synthétiques stockés après l’authentification adossée à l’environnement/à la configuration | Le fournisseur stocke des profils placeholders synthétiques qui ne doivent pas avoir la priorité | +| 11 | `resolveDynamicModel` | Repli synchrone pour les identifiants de modèle appartenant au fournisseur qui ne sont pas encore dans le registre local | Le fournisseur accepte des identifiants de modèle amont arbitraires | +| 12 | `prepareDynamicModel` | Préchauffage asynchrone, puis `resolveDynamicModel` s’exécute à nouveau | Le fournisseur a besoin de métadonnées réseau avant de résoudre des identifiants inconnus | +| 13 | `normalizeResolvedModel` | Réécriture finale avant que l’embedded runner n’utilise le modèle résolu | Le fournisseur a besoin de réécritures de transport tout en utilisant toujours un transport du cœur | +| 14 | `contributeResolvedModelCompat` | Contribue des drapeaux de compatibilité pour des modèles fournisseurs derrière un autre transport compatible | Le fournisseur reconnaît ses propres modèles sur des transports proxy sans prendre le contrôle du fournisseur | +| 15 | `capabilities` | Métadonnées de transcription/d’outillage appartenant au fournisseur utilisées par la logique partagée du cœur | Le fournisseur a besoin de particularités de transcription/de famille de fournisseurs | +| 16 | `normalizeToolSchemas` | Normalise les schémas d’outils avant que l’embedded runner ne les voie | Le fournisseur a besoin d’un nettoyage de schéma propre à une famille de transport | +| 17 | `inspectToolSchemas` | Expose des diagnostics de schéma appartenant au fournisseur après normalisation | Le fournisseur veut des avertissements sur les mots-clés sans enseigner au cœur des règles spécifiques au fournisseur | +| 18 | `resolveReasoningOutputMode` | Sélectionne le contrat de sortie de raisonnement natif ou balisé | Le fournisseur a besoin d’une sortie raisonnement/finale balisée au lieu de champs natifs | +| 19 | `prepareExtraParams` | Normalisation des paramètres de requête avant les wrappers génériques d’options de flux | Le fournisseur a besoin de paramètres de requête par défaut ou d’un nettoyage de paramètres par fournisseur | +| 20 | `createStreamFn` | Remplace entièrement le chemin de flux normal par un transport personnalisé | Le fournisseur a besoin d’un protocole filaire personnalisé, et pas seulement d’un wrapper | +| 21 | `wrapStreamFn` | Wrapper de flux après application des wrappers génériques | Le fournisseur a besoin de wrappers de compatibilité pour en-têtes/corps/modèle de requête sans transport personnalisé | +| 22 | `resolveTransportTurnState` | Attache des en-têtes ou métadonnées de transport natives par tour | Le fournisseur veut que les transports génériques envoient une identité de tour native au fournisseur | +| 23 | `resolveWebSocketSessionPolicy` | Attache des en-têtes WebSocket natifs ou une politique de refroidissement de session | Le fournisseur veut que les transports WS génériques ajustent les en-têtes de session ou la politique de repli | +| 24 | `formatApiKey` | Formateur de profil d’authentification : le profil stocké devient la chaîne `apiKey` à l’exécution | Le fournisseur stocke des métadonnées d’authentification supplémentaires et a besoin d’une forme de jeton d’exécution personnalisée | +| 25 | `refreshOAuth` | Remplacement de l’actualisation OAuth pour des points de terminaison d’actualisation personnalisés ou une politique d’échec d’actualisation | Le fournisseur ne correspond pas aux actualisateurs partagés `pi-ai` | +| 26 | `buildAuthDoctorHint` | Indication de réparation ajoutée lorsque l’actualisation OAuth échoue | Le fournisseur a besoin de conseils de réparation d’authentification lui appartenant après l’échec d’actualisation | +| 27 | `matchesContextOverflowError` | Détecteur appartenant au fournisseur des débordements de fenêtre de contexte | Le fournisseur possède des erreurs brutes de débordement que les heuristiques génériques manqueraient | +| 28 | `classifyFailoverReason` | Classification appartenant au fournisseur des raisons de basculement | Le fournisseur peut mapper les erreurs brutes d’API/de transport vers limitation de débit/surcharge/etc. | +| 29 | `isCacheTtlEligible` | Politique de cache de prompt pour les fournisseurs proxy/backhaul | Le fournisseur a besoin d’une régulation TTL du cache spécifique au proxy | +| 30 | `buildMissingAuthMessage` | Remplacement du message générique de récupération en cas d’authentification manquante | Le fournisseur a besoin d’une indication de récupération spécifique au fournisseur en cas d’authentification manquante | +| 31 | `suppressBuiltInModel` | Suppression des modèles amont obsolètes avec indication d’erreur facultative destinée à l’utilisateur | Le fournisseur doit masquer des lignes amont obsolètes ou les remplacer par une indication fournisseur | +| 32 | `augmentModelCatalog` | Lignes de catalogue synthétiques/finales ajoutées après la découverte | Le fournisseur a besoin de lignes synthétiques compatibles vers l’avant dans `models list` et les sélecteurs | +| 33 | `isBinaryThinking` | Bascule de raisonnement marche/arrêt pour les fournisseurs à raisonnement binaire | Le fournisseur n’expose qu’un raisonnement binaire activé/désactivé | +| 34 | `supportsXHighThinking` | Prise en charge du raisonnement `xhigh` pour certains modèles | Le fournisseur veut `xhigh` uniquement sur un sous-ensemble de modèles | +| 35 | `resolveDefaultThinkingLevel` | Niveau `/think` par défaut pour une famille de modèles spécifique | Le fournisseur possède la politique `/think` par défaut pour une famille de modèles | +| 36 | `isModernModelRef` | Détecteur de modèles modernes pour les filtres de profils live et la sélection smoke | Le fournisseur possède la logique de correspondance des modèles préférés live/smoke | +| 37 | `prepareRuntimeAuth` | Échange un identifiant configuré contre le véritable jeton/clé d’exécution juste avant l’inférence | Le fournisseur a besoin d’un échange de jeton ou d’un identifiant de requête de courte durée | +| 38 | `resolveUsageAuth` | Résout les identifiants d’usage/facturation pour `/usage` et les surfaces de statut associées | Le fournisseur a besoin d’une analyse personnalisée des jetons d’usage/de quota ou d’un identifiant d’usage différent | +| 39 | `fetchUsageSnapshot` | Récupère et normalise des instantanés d’usage/de quota spécifiques au fournisseur une fois l’authentification résolue | Le fournisseur a besoin d’un point de terminaison d’usage spécifique au fournisseur ou d’un analyseur de charge utile | +| 40 | `createEmbeddingProvider` | Construit un adaptateur d’embedding appartenant au fournisseur pour la mémoire/la recherche | Le comportement d’embedding mémoire appartient au plugin fournisseur | +| 41 | `buildReplayPolicy` | Renvoie une politique de rejeu qui contrôle la gestion des transcriptions pour le fournisseur | Le fournisseur a besoin d’une politique de transcription personnalisée (par exemple, suppression des blocs de réflexion) | +| 42 | `sanitizeReplayHistory` | Réécrit l’historique de rejeu après le nettoyage générique des transcriptions | Le fournisseur a besoin de réécritures de rejeu spécifiques au fournisseur au-delà des assistants partagés de compaction | +| 43 | `validateReplayTurns` | Validation finale ou remodelage des tours de rejeu avant l’embedded runner | Le transport du fournisseur a besoin d’une validation plus stricte des tours après l’assainissement générique | +| 44 | `onModelSelected` | Exécute des effets de bord post-sélection appartenant au fournisseur | Le fournisseur a besoin de télémétrie ou d’un état appartenant au fournisseur lorsqu’un modèle devient actif | -`normalizeModelId`, `normalizeTransport` et `normalizeConfig` vérifient d'abord le -plugin fournisseur correspondant, puis passent aux autres plugins fournisseurs capables de hooks -jusqu'à ce que l'un change réellement l'identifiant de modèle ou le transport/la configuration. Cela permet aux -shims de compatibilité/alias de fournisseur de fonctionner sans obliger l'appelant à savoir quel -plugin intégré possède la réécriture. Si aucun hook de fournisseur ne réécrit une entrée de configuration -Google prise en charge, le normaliseur de configuration Google intégré applique quand même ce nettoyage de compatibilité. +`normalizeModelId`, `normalizeTransport` et `normalizeConfig` vérifient d’abord le +plugin fournisseur correspondant, puis passent aux autres plugins fournisseurs compatibles avec les hooks +jusqu’à ce que l’un d’eux modifie réellement l’identifiant du modèle ou le transport/la configuration. Cela permet aux +shims d’alias/de fournisseurs compatibles de continuer à fonctionner sans obliger l’appelant à savoir quel +plugin bundled possède la réécriture. Si aucun hook fournisseur ne réécrit une entrée de configuration prise en charge de la famille +Google, le normaliseur de configuration Google bundled applique toujours ce nettoyage de compatibilité. -Si le fournisseur a besoin d'un protocole filaire entièrement personnalisé ou d'un exécuteur de requête personnalisé, -il s'agit d'une autre classe d'extension. Ces hooks concernent un comportement de fournisseur -qui s'exécute toujours sur la boucle normale d'inférence d'OpenClaw. +Si le fournisseur a besoin d’un protocole filaire entièrement personnalisé ou d’un exécuteur de requêtes personnalisé, +il s’agit d’une autre classe d’extension. Ces hooks concernent le comportement du fournisseur qui +s’exécute toujours sur la boucle d’inférence normale d’OpenClaw. ### Exemple de fournisseur @@ -777,116 +758,111 @@ api.registerProvider({ - Anthropic utilise `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - et `wrapStreamFn` parce qu'il possède la compatibilité ascendante de Claude 4.6, - les indices de famille de fournisseurs, la guidance de réparation d'auth, l'intégration - de l'endpoint d'usage, l'éligibilité au cache de prompt, les valeurs par défaut de configuration conscientes de l'auth, - la politique de réflexion par défaut/adaptative de Claude, et la mise en forme spécifique à Anthropic - des streams pour les en-têtes bêta, `/fast` / `serviceTier`, et `context1m`. -- Les helpers de stream spécifiques à Claude d'Anthropic restent pour l'instant dans le seam - public propre au plugin intégré `api.ts` / `contract-api.ts`. Cette surface de paquet + et `wrapStreamFn` parce qu’il possède la compatibilité ascendante de Claude 4.6, + les indications de famille de fournisseurs, les conseils de réparation de l’authentification, l’intégration du point de terminaison d’usage, + l’éligibilité du cache de prompt, les valeurs par défaut de configuration sensibles à l’authentification, la politique + par défaut/adaptative de réflexion de Claude, ainsi que la mise en forme de flux spécifique à Anthropic pour + les en-têtes bêta, `/fast` / `serviceTier`, et `context1m`. +- Les assistants de flux spécifiques à Claude d’Anthropic restent pour l’instant dans le point d’intégration public + `api.ts` / `contract-api.ts` du plugin bundled. Cette surface de package exporte `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, et les constructeurs de wrappers - Anthropic de plus bas niveau au lieu d'élargir le SDK générique autour des règles d'en-têtes bêta - d'un seul fournisseur. -- OpenAI utilise `resolveDynamicModel`, `normalizeResolvedModel`, et - `capabilities` ainsi que `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking`, et `isModernModelRef` - parce qu'il possède la compatibilité ascendante GPT-5.4, la normalisation directe OpenAI - `openai-completions` -> `openai-responses`, les indices d'auth sensibles à Codex, - la suppression de Spark, les lignes synthétiques de liste OpenAI, et la politique - de réflexion / modèle live de GPT-5 ; la famille de stream `openai-responses-defaults` possède les - wrappers natifs partagés d'OpenAI Responses pour les en-têtes d'attribution, - `/fast`/`serviceTier`, la verbosité du texte, la recherche web native Codex, - la mise en forme de charge utile de compatibilité du raisonnement et la gestion du contexte Responses. -- OpenRouter utilise `catalog` ainsi que `resolveDynamicModel` et - `prepareDynamicModel` car le fournisseur est en pass-through et peut exposer de nouveaux - identifiants de modèle avant la mise à jour du catalogue statique d'OpenClaw ; il utilise aussi - `capabilities`, `wrapStreamFn`, et `isCacheTtlEligible` pour garder - hors du cœur les en-têtes de requête spécifiques au fournisseur, les métadonnées de routage, les correctifs de raisonnement - et la politique de cache de prompt. Sa politique de replay vient de la - famille `passthrough-gemini`, tandis que la famille de stream `openrouter-thinking` - possède l'injection de raisonnement proxy et les ignorances de modèles non pris en charge / `auto`. -- GitHub Copilot utilise `catalog`, `auth`, `resolveDynamicModel`, et - `capabilities` ainsi que `prepareRuntimeAuth` et `fetchUsageSnapshot` parce qu'il - a besoin d'une connexion appareil appartenant au fournisseur, d'un comportement de fallback de modèle, de particularités - de transcription Claude, d'un échange de jeton GitHub -> jeton Copilot, et d'un endpoint - d'usage appartenant au fournisseur. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, ainsi que les constructeurs de wrappers Anthropic + de niveau inférieur, au lieu d’élargir le SDK générique autour des règles d’en-tête bêta d’un seul + fournisseur. +- OpenAI utilise `resolveDynamicModel`, `normalizeResolvedModel` et + `capabilities`, ainsi que `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `supportsXHighThinking` et `isModernModelRef` + parce qu’il possède la compatibilité ascendante de GPT-5.4, la normalisation directe OpenAI + `openai-completions` -> `openai-responses`, les indications d’authentification adaptées à Codex, + la suppression de Spark, les lignes synthétiques de liste OpenAI, ainsi que la politique de réflexion / de modèle live de GPT-5 ; la famille de flux `openai-responses-defaults` + possède les wrappers natifs partagés OpenAI Responses pour les en-têtes d’attribution, + `/fast`/`serviceTier`, la verbosité du texte, la recherche web Codex native, + la mise en forme de charge utile compatible avec le raisonnement, et la gestion du contexte Responses. +- OpenRouter utilise `catalog`, ainsi que `resolveDynamicModel` et + `prepareDynamicModel`, parce que le fournisseur est en passthrough et peut exposer de nouveaux + identifiants de modèle avant la mise à jour du catalogue statique d’OpenClaw ; il utilise aussi + `capabilities`, `wrapStreamFn` et `isCacheTtlEligible` afin de maintenir hors du cœur + les en-têtes de requête spécifiques au fournisseur, les métadonnées de routage, les correctifs de raisonnement et + la politique de cache de prompt. Sa politique de rejeu vient de la + famille `passthrough-gemini`, tandis que la famille de flux `openrouter-thinking` + possède l’injection de raisonnement proxy et les omissions de modèles non pris en charge / `auto`. +- GitHub Copilot utilise `catalog`, `auth`, `resolveDynamicModel` et + `capabilities`, ainsi que `prepareRuntimeAuth` et `fetchUsageSnapshot`, car il + a besoin d’un login par appareil appartenant au fournisseur, d’un comportement de repli de modèle, des particularités de transcription Claude, + d’un échange de jeton GitHub -> jeton Copilot, ainsi que d’un point de terminaison d’usage appartenant au fournisseur. - OpenAI Codex utilise `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth`, et `augmentModelCatalog` ainsi que - `prepareExtraParams`, `resolveUsageAuth`, et `fetchUsageSnapshot` parce qu'il - s'exécute toujours sur les transports OpenAI du cœur mais possède sa normalisation de - transport/base URL, sa politique de fallback d'actualisation OAuth, son choix de transport par défaut, - ses lignes synthétiques de catalogue Codex, et l'intégration à l'endpoint d'usage ChatGPT ; il - partage la même famille de stream `openai-responses-defaults` que l'OpenAI direct. + `normalizeResolvedModel`, `refreshOAuth` et `augmentModelCatalog`, ainsi que + `prepareExtraParams`, `resolveUsageAuth` et `fetchUsageSnapshot`, parce qu’il + s’exécute encore sur les transports OpenAI du cœur mais possède sa normalisation de transport/base URL, + sa politique de repli d’actualisation OAuth, son choix de transport par défaut, + ses lignes synthétiques de catalogue Codex, ainsi que l’intégration du point de terminaison d’usage ChatGPT ; il + partage la même famille de flux `openai-responses-defaults` que l’OpenAI direct. - Google AI Studio et Gemini CLI OAuth utilisent `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn`, et `isModernModelRef` parce que la - famille de replay `google-gemini` possède le fallback de compatibilité ascendante Gemini 3.1, - la validation native du replay Gemini, l'assainissement du replay de bootstrap, le mode - de sortie de raisonnement avec balises, et la correspondance de modèles modernes, tandis que la - famille de stream `google-thinking` possède la normalisation de la charge utile de réflexion Gemini ; - Gemini CLI OAuth utilise aussi `formatApiKey`, `resolveUsageAuth`, et - `fetchUsageSnapshot` pour le formatage des jetons, l'analyse des jetons et le câblage - des endpoints de quota. + `resolveReasoningOutputMode`, `wrapStreamFn` et `isModernModelRef` parce que la + famille de rejeu `google-gemini` possède le repli de compatibilité ascendante Gemini 3.1, + la validation native du rejeu Gemini, l’assainissement du rejeu au démarrage, le mode de sortie de raisonnement + balisé, ainsi que la correspondance des modèles modernes, tandis que la + famille de flux `google-thinking` possède la normalisation de charge utile de réflexion Gemini ; + Gemini CLI OAuth utilise aussi `formatApiKey`, `resolveUsageAuth` et + `fetchUsageSnapshot` pour la mise en forme des jetons, l’analyse des jetons et le + câblage du point de terminaison de quota. - Anthropic Vertex utilise `buildReplayPolicy` via la - famille de replay `anthropic-by-model` afin que le nettoyage du replay spécifique à Claude reste - limité aux identifiants Claude plutôt qu'à tout transport `anthropic-messages`. + famille de rejeu `anthropic-by-model` afin que le nettoyage du rejeu spécifique à Claude reste + limité aux identifiants Claude au lieu de tous les transports `anthropic-messages`. - Amazon Bedrock utilise `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason`, et `resolveDefaultThinkingLevel` parce qu'il possède la - classification des erreurs spécifiques à Bedrock de limitation/pas prêt/dépassement de contexte - pour le trafic Anthropic-sur-Bedrock ; sa politique de replay partage toujours le même garde-fou - `anthropic-by-model` réservé à Claude. + `classifyFailoverReason` et `resolveDefaultThinkingLevel` parce qu’il possède + la classification spécifique à Bedrock des erreurs throttle/not-ready/context-overflow + pour le trafic Anthropic-sur-Bedrock ; sa politique de rejeu partage toujours la même + protection `anthropic-by-model` limitée à Claude. - OpenRouter, Kilocode, Opencode et Opencode Go utilisent `buildReplayPolicy` - via la famille de replay `passthrough-gemini` parce qu'ils proxifient des modèles Gemini - à travers des transports compatibles OpenAI et ont besoin de l'assainissement - de signature de pensée Gemini sans validation native du replay Gemini ni réécritures - de bootstrap. + via la famille de rejeu `passthrough-gemini` parce qu’ils proxifient des modèles Gemini + au travers de transports compatibles OpenAI et ont besoin de l’assainissement de signature de pensée + Gemini sans validation native du rejeu Gemini ni réécritures au + démarrage. - MiniMax utilise `buildReplayPolicy` via la - famille de replay `hybrid-anthropic-openai` parce qu'un seul fournisseur possède à la fois - des sémantiques Anthropic-message et OpenAI-compatibles ; il conserve la suppression - des blocs de réflexion réservés à Claude du côté Anthropic tout en rétablissant le mode de sortie de raisonnement en natif, - et la famille de stream `minimax-fast-mode` possède les réécritures de modèles en mode rapide - sur le chemin de stream partagé. -- Moonshot utilise `catalog` ainsi que `wrapStreamFn` parce qu'il utilise toujours le - transport OpenAI partagé mais a besoin d'une normalisation de charge utile de réflexion appartenant au fournisseur ; la - famille de stream `moonshot-thinking` mappe la configuration ainsi que l'état `/think` sur sa + famille de rejeu `hybrid-anthropic-openai` parce qu’un seul fournisseur possède à la fois + la sémantique Anthropic-message et OpenAI-compatible ; il conserve + l’abandon des blocs de réflexion limités à Claude du côté Anthropic tout en remplaçant le mode de sortie + du raisonnement pour revenir au natif, et la famille de flux `minimax-fast-mode` possède + les réécritures de modèles fast-mode sur le chemin de flux partagé. +- Moonshot utilise `catalog` ainsi que `wrapStreamFn` parce qu’il utilise toujours le + transport OpenAI partagé mais a besoin d’une normalisation de charge utile de réflexion appartenant au fournisseur ; la + famille de flux `moonshot-thinking` mappe la configuration ainsi que l’état `/think` sur sa charge utile native de réflexion binaire. -- Kilocode utilise `catalog`, `capabilities`, `wrapStreamFn`, et - `isCacheTtlEligible` parce qu'il a besoin d'en-têtes de requête appartenant au fournisseur, - de la normalisation de charge utile de raisonnement, d'indices de transcription Gemini, et d'un filtrage - TTL de cache Anthropic ; la famille de stream `kilocode-thinking` conserve l'injection - de réflexion Kilo sur le chemin de stream proxy partagé tout en ignorant `kilo/auto` et - d'autres identifiants de modèles proxy qui ne prennent pas en charge des charges utiles de raisonnement explicites. +- Kilocode utilise `catalog`, `capabilities`, `wrapStreamFn` et + `isCacheTtlEligible` parce qu’il a besoin d’en-têtes de requête appartenant au fournisseur, + de normalisation de charge utile de raisonnement, d’indications de transcription Gemini et d’une régulation + Anthropic du cache TTL ; la famille de flux `kilocode-thinking` conserve l’injection de réflexion Kilo + sur le chemin de flux proxy partagé tout en ignorant `kilo/auto` et + d’autres identifiants de modèle proxy qui ne prennent pas en charge des charges utiles de raisonnement explicites. - Z.AI utilise `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth`, et `fetchUsageSnapshot` parce qu'il possède le fallback GLM-5, - les valeurs par défaut `tool_stream`, l'expérience utilisateur de réflexion binaire, la correspondance de modèles modernes, - ainsi que l'auth d'usage + la récupération de quota ; la famille de stream `tool-stream-default-on` - évite que le wrapper `tool_stream` activé par défaut ne se retrouve dans du code manuel - propre à chaque fournisseur. + `resolveUsageAuth` et `fetchUsageSnapshot` parce qu’il possède le repli GLM-5, + les valeurs par défaut `tool_stream`, l’UX de réflexion binaire, la correspondance des modèles modernes, ainsi que + l’authentification d’usage et la récupération de quota ; la famille de flux `tool-stream-default-on` + maintient hors du code manuscrit par fournisseur le wrapper `tool_stream` activé par défaut. - xAI utilise `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, - `resolveSyntheticAuth`, `resolveDynamicModel`, et `isModernModelRef` - parce qu'il possède la normalisation native du transport xAI Responses, les réécritures - d'alias Grok fast-mode, la valeur par défaut `tool_stream`, le nettoyage strict-tool / charge utile de raisonnement, - la réutilisation de l'auth fallback pour les outils appartenant au plugin, la résolution - de modèles Grok à compatibilité ascendante, ainsi que des correctifs de compatibilité - appartenant au fournisseur tels que le profil de schéma d'outil xAI, les mots-clés de schéma non pris en charge, - le `web_search` natif, et le décodage des arguments d'appel d'outil en entités HTML. -- Mistral, OpenCode Zen et OpenCode Go utilisent `capabilities` uniquement pour garder - hors du cœur les particularités de transcription/outillage. -- Les fournisseurs intégrés limités au catalogue tels que `byteplus`, `cloudflare-ai-gateway`, + `resolveSyntheticAuth`, `resolveDynamicModel` et `isModernModelRef` + parce qu’il possède la normalisation native du transport xAI Responses, les réécritures d’alias Grok fast-mode, le `tool_stream` par défaut, le nettoyage strict-tool / charge utile de raisonnement, + la réutilisation d’authentification de repli pour les outils appartenant au plugin, la résolution + compatible vers l’avant des modèles Grok, ainsi que des correctifs de compatibilité appartenant au fournisseur comme le profil de schéma d’outils xAI, + les mots-clés de schéma non pris en charge, le `web_search` natif, et le décodage des arguments d’appel d’outil + avec entités HTML. +- Mistral, OpenCode Zen et OpenCode Go utilisent uniquement `capabilities` pour maintenir hors du cœur + les particularités de transcription/d’outillage. +- Les fournisseurs bundled uniquement catalogue tels que `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, - `synthetic`, `together`, `venice`, `vercel-ai-gateway`, et `volcengine` utilisent + `synthetic`, `together`, `venice`, `vercel-ai-gateway` et `volcengine` utilisent uniquement `catalog`. -- Qwen utilise `catalog` pour son fournisseur de texte ainsi que des enregistrements partagés - de compréhension des médias et de génération de vidéo pour ses surfaces multimodales. -- MiniMax et Xiaomi utilisent `catalog` ainsi que des hooks d'usage parce que leur comportement `/usage` - appartient au plugin même si l'inférence passe toujours par les transports partagés. +- Qwen utilise `catalog` pour son fournisseur de texte ainsi que des enregistrements partagés de compréhension des médias et de génération de vidéos pour ses surfaces multimodales. +- MiniMax et Xiaomi utilisent `catalog` ainsi que les hooks d’usage parce que leur comportement `/usage` + appartient au plugin même si l’inférence s’exécute encore via les transports partagés. -## Helpers runtime +## Assistants d’exécution -Les plugins peuvent accéder à certains helpers du cœur via `api.runtime`. Pour TTS : +Les plugins peuvent accéder à certains assistants du cœur via `api.runtime`. Pour la synthèse vocale : ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -908,11 +884,11 @@ const voices = await api.runtime.tts.listVoices({ Remarques : - `textToSpeech` renvoie la charge utile normale de sortie TTS du cœur pour les surfaces de fichier/note vocale. -- Utilise la configuration du cœur `messages.tts` et la sélection du fournisseur. -- Renvoie un tampon audio PCM + une fréquence d'échantillonnage. Les plugins doivent rééchantillonner/encoder pour les fournisseurs. -- `listVoices` est facultatif selon le fournisseur. Utilisez-le pour les sélecteurs de voix ou les flux de configuration appartenant au fournisseur. -- Les listes de voix peuvent inclure des métadonnées plus riches telles que la locale, le genre et des tags de personnalité pour des sélecteurs sensibles au fournisseur. -- OpenAI et ElevenLabs prennent aujourd'hui en charge la téléphonie. Microsoft non. +- Utilise la configuration du cœur `messages.tts` et la sélection de fournisseur. +- Renvoie un tampon audio PCM + une fréquence d’échantillonnage. Les plugins doivent rééchantillonner/encoder pour les fournisseurs. +- `listVoices` est facultatif selon le fournisseur. Utilisez-le pour les sélecteurs de voix appartenant au fournisseur ou les flux de configuration. +- Les listes de voix peuvent inclure des métadonnées plus riches telles que la locale, le genre et des tags de personnalité pour des sélecteurs conscients du fournisseur. +- OpenAI et ElevenLabs prennent aujourd’hui en charge la téléphonie. Microsoft non. Les plugins peuvent également enregistrer des fournisseurs de parole via `api.registerSpeechProvider(...)`. @@ -934,15 +910,15 @@ api.registerSpeechProvider({ Remarques : -- Conservez la politique TTS, le fallback et la livraison des réponses dans le cœur. +- Conservez dans le cœur la politique TTS, le repli et la livraison des réponses. - Utilisez les fournisseurs de parole pour le comportement de synthèse appartenant au fournisseur. -- L'entrée legacy Microsoft `edge` est normalisée vers l'identifiant de fournisseur `microsoft`. -- Le modèle de propriété préféré est orienté entreprise : un seul plugin fournisseur peut posséder - le texte, la parole, l'image et de futurs fournisseurs de médias à mesure qu'OpenClaw ajoute ces +- L’entrée Microsoft legacy `edge` est normalisée vers l’identifiant de fournisseur `microsoft`. +- Le modèle de propriété privilégié est orienté entreprise : un même plugin fournisseur peut posséder + le texte, la parole, l’image et les futurs fournisseurs de médias à mesure qu’OpenClaw ajoute ces contrats de capacité. -Pour la compréhension d'image/audio/vidéo, les plugins enregistrent un -fournisseur typé de compréhension des médias au lieu d'un sac générique clé/valeur : +Pour la compréhension d’image/audio/vidéo, les plugins enregistrent un fournisseur de +compréhension des médias typé au lieu d’un sac générique clé/valeur : ```ts api.registerMediaUnderstandingProvider({ @@ -956,16 +932,16 @@ api.registerMediaUnderstandingProvider({ Remarques : -- Conservez l'orchestration, le fallback, la configuration et le câblage des canaux dans le cœur. -- Conservez le comportement fournisseur dans le plugin fournisseur. -- L'expansion additive doit rester typée : nouvelles méthodes facultatives, nouveaux champs - de résultat facultatifs, nouvelles capacités facultatives. -- La génération de vidéo suit déjà le même modèle : - - le cœur possède le contrat de capacité et le helper runtime +- Conservez dans le cœur l’orchestration, le repli, la configuration et le câblage des canaux. +- Conservez le comportement du fournisseur dans le plugin fournisseur. +- L’extension additive doit rester typée : nouvelles méthodes optionnelles, nouveaux champs de résultat + optionnels, nouvelles capacités optionnelles. +- La génération de vidéos suit déjà le même schéma : + - le cœur possède le contrat de capacité et l’assistant d’exécution - les plugins fournisseurs enregistrent `api.registerVideoGenerationProvider(...)` - les plugins de fonctionnalité/de canal consomment `api.runtime.videoGeneration.*` -Pour les helpers runtime de compréhension des médias, les plugins peuvent appeler : +Pour les assistants d’exécution de compréhension des médias, les plugins peuvent appeler : ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -980,32 +956,32 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Pour la transcription audio, les plugins peuvent utiliser soit le runtime de compréhension des médias -soit l'ancien alias STT : +Pour la transcription audio, les plugins peuvent utiliser soit l’exécution media-understanding, +soit l’ancien alias STT : ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Facultatif lorsque le type MIME ne peut pas être déduit de manière fiable : + // Facultatif lorsque le type MIME ne peut pas être déduit de façon fiable : mime: "audio/ogg", }); ``` Remarques : -- `api.runtime.mediaUnderstanding.*` est la surface partagée préférée pour la - compréhension d'image/audio/vidéo. -- Utilise la configuration audio du cœur pour la compréhension des médias (`tools.media.audio`) et l'ordre de fallback des fournisseurs. -- Renvoie `{ text: undefined }` lorsqu'aucune sortie de transcription n'est produite (par exemple entrée ignorée/non prise en charge). -- `api.runtime.stt.transcribeAudioFile(...)` reste un alias de compatibilité. +- `api.runtime.mediaUnderstanding.*` est la surface partagée privilégiée pour la + compréhension d’image/audio/vidéo. +- Utilise la configuration audio media-understanding du cœur (`tools.media.audio`) et l’ordre de repli du fournisseur. +- Renvoie `{ text: undefined }` lorsqu’aucune sortie de transcription n’est produite (par exemple entrée ignorée/non prise en charge). +- `api.runtime.stt.transcribeAudioFile(...)` reste disponible comme alias de compatibilité. Les plugins peuvent aussi lancer des exécutions de sous-agent en arrière-plan via `api.runtime.subagent` : ```ts const result = await api.runtime.subagent.run({ sessionKey: "agent:main:subagent:search-helper", - message: "Expand this query into focused follow-up searches.", + message: "Développe cette requête en recherches de suivi ciblées.", provider: "openai", model: "gpt-4.1-mini", deliver: false, @@ -1014,14 +990,14 @@ const result = await api.runtime.subagent.run({ Remarques : -- `provider` et `model` sont des surcharges facultatives par exécution, pas des changements persistants de session. -- OpenClaw n'honore ces champs de surcharge que pour les appelants de confiance. -- Pour les exécutions de secours appartenant à un plugin, les opérateurs doivent activer explicitement `plugins.entries..subagent.allowModelOverride: true`. -- Utilisez `plugins.entries..subagent.allowedModels` pour restreindre les plugins de confiance à des cibles canoniques spécifiques `provider/model`, ou `"*"` pour autoriser explicitement n'importe quelle cible. -- Les exécutions de sous-agent de plugins non fiables fonctionnent toujours, mais les demandes de surcharge sont rejetées au lieu de retomber silencieusement. +- `provider` et `model` sont des remplacements par exécution facultatifs, et non des modifications persistantes de session. +- OpenClaw n’honore ces champs de remplacement que pour les appelants de confiance. +- Pour les exécutions de repli appartenant au plugin, les opérateurs doivent activer explicitement `plugins.entries..subagent.allowModelOverride: true`. +- Utilisez `plugins.entries..subagent.allowedModels` pour limiter les plugins de confiance à des cibles canoniques `provider/model` spécifiques, ou `"*"` pour autoriser explicitement n’importe quelle cible. +- Les exécutions de sous-agent de plugins non fiables fonctionnent toujours, mais les demandes de remplacement sont rejetées au lieu d’entraîner silencieusement un repli. -Pour la recherche web, les plugins peuvent consommer le helper runtime partagé au lieu -d'accéder au câblage de l'outil de l'agent : +Pour la recherche web, les plugins peuvent consommer l’assistant d’exécution partagé au lieu +d’accéder directement au câblage de l’outil d’agent : ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1031,7 +1007,7 @@ const providers = api.runtime.webSearch.listProviders({ const result = await api.runtime.webSearch.search({ config: api.config, args: { - query: "OpenClaw plugin runtime helpers", + query: "Assistants d’exécution des plugins OpenClaw", count: 5, }, }); @@ -1042,16 +1018,16 @@ Les plugins peuvent aussi enregistrer des fournisseurs de recherche web via Remarques : -- Conservez la sélection du fournisseur, la résolution des identifiants et la sémantique de requête partagée dans le cœur. +- Conservez dans le cœur la sélection du fournisseur, la résolution des identifiants et la sémantique partagée des requêtes. - Utilisez les fournisseurs de recherche web pour les transports de recherche spécifiques à un fournisseur. -- `api.runtime.webSearch.*` est la surface partagée préférée pour les plugins de fonctionnalité/de canal qui ont besoin d'un comportement de recherche sans dépendre du wrapper de l'outil d'agent. +- `api.runtime.webSearch.*` est la surface partagée privilégiée pour les plugins de fonctionnalité/de canal qui ont besoin d’un comportement de recherche sans dépendre du wrapper de l’outil d’agent. ### `api.runtime.imageGeneration` ```ts const result = await api.runtime.imageGeneration.generate({ config: api.config, - args: { prompt: "A friendly lobster mascot", size: "1024x1024" }, + args: { prompt: "Une mascotte homard amicale", size: "1024x1024" }, }); const providers = api.runtime.imageGeneration.listProviders({ @@ -1059,12 +1035,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: générer une image à l'aide de la chaîne de fournisseurs configurée pour la génération d'images. -- `listProviders(...)`: lister les fournisseurs disponibles pour la génération d'images et leurs capacités. +- `generate(...)` : génère une image en utilisant la chaîne configurée de fournisseurs de génération d’images. +- `listProviders(...)` : liste les fournisseurs de génération d’images disponibles et leurs capacités. ## Routes HTTP Gateway -Les plugins peuvent exposer des endpoints HTTP avec `api.registerHttpRoute(...)`. +Les plugins peuvent exposer des points de terminaison HTTP avec `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1079,35 +1055,35 @@ api.registerHttpRoute({ }); ``` -Champs de la route : +Champs de route : -- `path`: chemin de route sous le serveur HTTP gateway. -- `auth`: obligatoire. Utilisez `"gateway"` pour exiger l'auth normale de la gateway, ou `"plugin"` pour l'auth gérée par le plugin/la vérification de webhook. -- `match`: facultatif. `"exact"` (par défaut) ou `"prefix"`. -- `replaceExisting`: facultatif. Permet au même plugin de remplacer son propre enregistrement de route existant. -- `handler`: renvoyez `true` lorsque la route a traité la requête. +- `path` : chemin de route sous le serveur HTTP Gateway. +- `auth` : obligatoire. Utilisez `"gateway"` pour exiger l’authentification normale de la gateway, ou `"plugin"` pour l’authentification/la vérification de webhook gérée par le plugin. +- `match` : facultatif. `"exact"` (par défaut) ou `"prefix"`. +- `replaceExisting` : facultatif. Permet au même plugin de remplacer son propre enregistrement de route existant. +- `handler` : renvoie `true` lorsque la route a traité la requête. Remarques : - `api.registerHttpHandler(...)` a été supprimé et provoquera une erreur de chargement du plugin. Utilisez `api.registerHttpRoute(...)` à la place. - Les routes de plugin doivent déclarer `auth` explicitement. -- Les conflits exacts `path + match` sont rejetés sauf si `replaceExisting: true`, et un plugin ne peut pas remplacer la route d'un autre plugin. -- Les routes qui se chevauchent avec des niveaux `auth` différents sont rejetées. Gardez les chaînes de retombée `exact`/`prefix` au même niveau d'auth uniquement. -- Les routes `auth: "plugin"` ne reçoivent **pas** automatiquement les portées runtime de l'opérateur. Elles sont destinées aux webhooks/vérifications de signature gérés par le plugin, pas aux appels privilégiés aux helpers Gateway. -- Les routes `auth: "gateway"` s'exécutent dans une portée runtime de requête Gateway, mais cette portée est volontairement conservatrice : - - l'auth bearer à secret partagé (`gateway.auth.mode = "token"` / `"password"`) maintient les portées runtime des routes de plugin fixées à `operator.write`, même si l'appelant envoie `x-openclaw-scopes` - - les modes HTTP de confiance portant une identité (par exemple `trusted-proxy` ou `gateway.auth.mode = "none"` sur une entrée privée) n'honorent `x-openclaw-scopes` que lorsque l'en-tête est explicitement présent - - si `x-openclaw-scopes` est absent sur ces requêtes de route de plugin portant une identité, la portée runtime retombe sur `operator.write` -- Règle pratique : ne partez pas du principe qu'une route de plugin avec auth gateway est implicitement une surface admin. Si votre route a besoin d'un comportement réservé à l'administration, exigez un mode d'auth portant une identité et documentez le contrat explicite de l'en-tête `x-openclaw-scopes`. +- Les conflits exacts `path + match` sont rejetés sauf si `replaceExisting: true`, et un plugin ne peut pas remplacer la route d’un autre plugin. +- Les routes qui se chevauchent avec des niveaux `auth` différents sont rejetées. Gardez les chaînes de retombée `exact`/`prefix` uniquement au même niveau d’authentification. +- Les routes `auth: "plugin"` ne reçoivent **pas** automatiquement les portées d’exécution de l’opérateur. Elles sont destinées aux webhooks gérés par le plugin / à la vérification de signature, et non aux appels d’assistants Gateway privilégiés. +- Les routes `auth: "gateway"` s’exécutent dans une portée d’exécution de requête Gateway, mais cette portée est volontairement prudente : + - l’authentification bearer par secret partagé (`gateway.auth.mode = "token"` / `"password"`) maintient les portées d’exécution des routes de plugin fixées à `operator.write`, même si l’appelant envoie `x-openclaw-scopes` + - les modes HTTP de confiance avec identité (par exemple `trusted-proxy` ou `gateway.auth.mode = "none"` sur une entrée privée) n’honorent `x-openclaw-scopes` que lorsque l’en-tête est explicitement présent + - si `x-openclaw-scopes` est absent sur ces requêtes de route de plugin porteuses d’identité, la portée d’exécution retombe à `operator.write` +- Règle pratique : ne supposez pas qu’une route de plugin authentifiée par la gateway est implicitement une surface d’administration. Si votre route a besoin d’un comportement réservé à l’administrateur, exigez un mode d’authentification porteur d’identité et documentez le contrat explicite de l’en-tête `x-openclaw-scopes`. -## Chemins d'import du Plugin SDK +## Chemins d’import du SDK de plugin -Utilisez les sous-chemins du SDK au lieu de l'import monolithique `openclaw/plugin-sdk` lorsque -vous développez des plugins : +Utilisez les sous-chemins du SDK au lieu de l’import monolithique `openclaw/plugin-sdk` lorsque +vous créez des plugins : -- `openclaw/plugin-sdk/plugin-entry` pour les primitives d'enregistrement de plugin. -- `openclaw/plugin-sdk/core` pour le contrat générique partagé orienté plugin. -- `openclaw/plugin-sdk/config-schema` pour l'export du schéma Zod racine `openclaw.json` +- `openclaw/plugin-sdk/plugin-entry` pour les primitives d’enregistrement des plugins. +- `openclaw/plugin-sdk/core` pour le contrat partagé générique côté plugin. +- `openclaw/plugin-sdk/config-schema` pour l’export du schéma Zod racine `openclaw.json` (`OpenClawSchema`). - Primitives de canal stables telles que `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1121,15 +1097,15 @@ vous développez des plugins : `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input`, et - `openclaw/plugin-sdk/webhook-ingress` pour le câblage partagé de configuration/auth/réponse/webhook. - `channel-inbound` est le foyer partagé pour l'anti-rebond, la correspondance des mentions, - les helpers de politique de mention entrante, le formatage des enveloppes et les helpers de contexte - d'enveloppe entrante. - `channel-setup` est le seam étroit de configuration à installation facultative. - `setup-runtime` est la surface de configuration sûre à l'exécution utilisée par `setupEntry` / - le démarrage différé, y compris les adaptateurs de patch de configuration sûrs à l'import. - `setup-adapter-runtime` est le seam d'adaptateur de configuration de compte sensible à l'environnement. - `setup-tools` est le petit seam helper CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` pour le câblage partagé de configuration/authentification/réponse/webhook. + `channel-inbound` est la surface partagée pour l’anti-rebond, la correspondance des mentions, + les assistants de politique de mention entrante, le formatage d’enveloppe et les + assistants de contexte d’enveloppe entrante. + `channel-setup` est le point d’intégration étroit de configuration à installation facultative. + `setup-runtime` est la surface de configuration sûre à l’exécution utilisée par `setupEntry` / + le démarrage différé, y compris les adaptateurs de patch de configuration sûrs à l’import. + `setup-adapter-runtime` est le point d’intégration des adaptateurs de configuration de compte sensibles à l’environnement. + `setup-tools` est le petit point d’intégration d’assistance CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Sous-chemins de domaine tels que `openclaw/plugin-sdk/channel-config-helpers`, @@ -1150,169 +1126,190 @@ vous développez des plugins : `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store`, et - `openclaw/plugin-sdk/directory-runtime` pour des helpers runtime/config partagés. - `telegram-command-config` est le seam public étroit pour la normalisation/validation des commandes personnalisées Telegram et reste disponible même si la surface de contrat Telegram intégrée est temporairement indisponible. - `text-runtime` est le seam partagé texte/markdown/journalisation, incluant - la suppression du texte visible par l'assistant, les helpers de rendu/segmentation Markdown, les helpers de masquage, - les helpers de balises de directive et les utilitaires de texte sûr. -- Les seams de canal spécifiques à l'approbation doivent préférer un unique contrat `approvalCapability` - sur le plugin. Le cœur lit ensuite l'auth, la livraison, le rendu, - le routage natif et le comportement lazy de gestionnaire natif via cette seule capacité - au lieu de mélanger le comportement d'approbation à des champs de plugin non liés. -- `openclaw/plugin-sdk/channel-runtime` est obsolète et ne subsiste que comme shim - de compatibilité pour d'anciens plugins. Le nouveau code doit importer les primitives génériques plus étroites à la place, et le code du dépôt ne doit pas ajouter de nouveaux imports du shim. -- Les éléments internes des extensions intégrées restent privés. Les plugins externes ne doivent utiliser que les sous-chemins `openclaw/plugin-sdk/*`. Le code cœur/test d'OpenClaw peut utiliser les points d'entrée publics du dépôt sous une racine de paquet de plugin tels que `index.js`, `api.js`, + `openclaw/plugin-sdk/directory-runtime` pour les assistants partagés d’exécution/de configuration. + `telegram-command-config` est le point d’intégration public étroit pour la normalisation/validation des commandes personnalisées Telegram et reste disponible même si la surface de contrat Telegram bundled est temporairement indisponible. + `text-runtime` est la surface partagée pour le texte/Markdown/la journalisation, y compris + la suppression du texte visible par l’assistant, les assistants de rendu/de découpage Markdown, les assistants de rédaction, + les assistants de balises de directive et les utilitaires de texte sûr. +- Les points d’intégration de canal spécifiques à l’approbation doivent préférer un seul contrat `approvalCapability` + sur le plugin. Le cœur lit ensuite l’authentification, la livraison, le rendu, + le routage natif et le comportement paresseux du gestionnaire natif d’approbation via cette seule capacité + au lieu de mélanger le comportement d’approbation dans des champs de plugin sans lien. +- `openclaw/plugin-sdk/channel-runtime` est obsolète et ne subsiste que comme + shim de compatibilité pour les anciens plugins. Le nouveau code doit importer les primitives génériques + plus étroites à la place, et le code du dépôt ne doit pas ajouter de nouveaux imports du + shim. +- Les composants internes des extensions bundled restent privés. Les plugins externes doivent utiliser uniquement + les sous-chemins `openclaw/plugin-sdk/*`. Le code cœur/test d’OpenClaw peut utiliser les + points d’entrée publics du dépôt sous une racine de package de plugin tels que `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js`, et des fichiers à portée étroite tels que - `login-qr-api.js`. N'importez jamais le `src/*` d'un paquet de plugin depuis le cœur ou depuis une autre extension. -- Scission des points d'entrée du dépôt : - `/api.js` est le barrel helper/types, - `/runtime-api.js` est le barrel réservé au runtime, - `/index.js` est l'entrée du plugin intégré, - et `/setup-entry.js` est l'entrée du plugin de configuration. -- Exemples actuels de fournisseurs intégrés : - - Anthropic utilise `api.js` / `contract-api.js` pour les helpers de stream Claude tels que - `wrapAnthropicProviderStream`, les helpers d'en-tête bêta, et l'analyse de `service_tier`. - - OpenAI utilise `api.js` pour les constructeurs de fournisseurs, les helpers de modèle par défaut, et les constructeurs de fournisseurs temps réel. - - OpenRouter utilise `api.js` pour son constructeur de fournisseur ainsi que des helpers d'onboarding/configuration, tandis que `register.runtime.js` peut toujours réexporter des helpers génériques `plugin-sdk/provider-stream` pour un usage local au dépôt. -- Les points d'entrée publics chargés via façade préfèrent l'instantané actif de configuration runtime lorsqu'il existe, puis reviennent au fichier de configuration résolu sur disque lorsqu'OpenClaw ne sert pas encore d'instantané runtime. -- Les primitives génériques partagées restent le contrat public préféré du SDK. Un petit ensemble réservé de compatibilité de seams helper de marque de canal intégrés existe encore. Traitez-les comme des seams de maintenance/compatibilité pour intégrés, pas comme de nouvelles cibles d'import pour des tiers ; les nouveaux contrats inter-canaux doivent toujours atterrir sur des sous-chemins génériques `plugin-sdk/*` ou sur les barrels locaux `api.js` / `runtime-api.js` du plugin. + `login-qr-api.js`. N’importez jamais `src/*` d’un package de plugin depuis le cœur ou depuis + une autre extension. +- Séparation des points d’entrée du dépôt : + `/api.js` est le baril d’assistants/types, + `/runtime-api.js` est le baril réservé à l’exécution, + `/index.js` est le point d’entrée du plugin bundled, + et `/setup-entry.js` est le point d’entrée du plugin de configuration. +- Exemples actuels de fournisseurs bundled : + - Anthropic utilise `api.js` / `contract-api.js` pour les assistants de flux Claude tels + que `wrapAnthropicProviderStream`, les assistants d’en-tête bêta et l’analyse de `service_tier`. + - OpenAI utilise `api.js` pour les constructeurs de fournisseur, les assistants de modèle par défaut et + les constructeurs de fournisseur en temps réel. + - OpenRouter utilise `api.js` pour son constructeur de fournisseur ainsi que des assistants d’onboarding/de configuration, + tandis que `register.runtime.js` peut toujours réexporter des assistants génériques + `plugin-sdk/provider-stream` pour un usage local au dépôt. +- Les points d’entrée publics chargés par façade préfèrent l’instantané de configuration d’exécution actif + lorsqu’il existe, puis retombent sur le fichier de configuration résolu sur disque lorsque + OpenClaw ne sert pas encore d’instantané d’exécution. +- Les primitives génériques partagées restent le contrat public préféré du SDK. Un petit + ensemble réservé de compatibilité de points d’intégration d’assistance portant la marque de canaux bundled existe encore. Traitez-les comme des points d’intégration de maintenance bundled/de compatibilité, et non comme de nouvelles cibles d’import tierces ; les nouveaux contrats transversaux entre canaux doivent toujours être introduits sur des sous-chemins génériques `plugin-sdk/*` ou sur les barils locaux au plugin `api.js` / + `runtime-api.js`. Note de compatibilité : -- Évitez le barrel racine `openclaw/plugin-sdk` pour le nouveau code. -- Préférez d'abord les primitives stables étroites. Les sous-chemins plus récents de configuration/appairage/réponse/ - feedback/contrat/entrant/threading/commande/secret-input/webhook/infra/ - allowlist/status/message-tool constituent le contrat visé pour les nouveaux - plugins intégrés et externes. - L'analyse/la correspondance des cibles appartient à `openclaw/plugin-sdk/channel-targets`. - Les garde-fous d'action de message et les helpers d'identifiant de message de réaction appartiennent à +- Évitez le baril racine `openclaw/plugin-sdk` pour le nouveau code. +- Préférez d’abord les primitives stables étroites. Les nouveaux sous-chemins setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool constituent le contrat prévu pour les nouveaux travaux de plugins + bundled et externes. + L’analyse/la correspondance des cibles appartient à `openclaw/plugin-sdk/channel-targets`. + Les barrières d’actions de message et les assistants d’identifiant de message de réaction appartiennent à `openclaw/plugin-sdk/channel-actions`. -- Les barrels helper spécifiques à une extension intégrée ne sont pas stables par défaut. Si un - helper n'est nécessaire que pour une extension intégrée, gardez-le derrière le seam local - `api.js` ou `runtime-api.js` de l'extension au lieu de le promouvoir dans +- Les barils d’assistance spécifiques à une extension bundled ne sont pas stables par défaut. Si un + assistant n’est nécessaire qu’à une extension bundled, conservez-le derrière le point d’intégration local + `api.js` ou `runtime-api.js` de l’extension au lieu de le promouvoir dans `openclaw/plugin-sdk/`. -- Les nouveaux seams helper partagés doivent être génériques, pas marqués par un canal. L'analyse - partagée des cibles appartient à `openclaw/plugin-sdk/channel-targets` ; les éléments internes - spécifiques au canal restent derrière le seam local `api.js` ou `runtime-api.js` du plugin propriétaire. +- Les nouveaux points d’intégration d’assistance partagée doivent être génériques, et non marqués par un canal. L’analyse partagée des cibles + appartient à `openclaw/plugin-sdk/channel-targets` ; les composants internes spécifiques au canal + restent derrière le point d’intégration local `api.js` ou `runtime-api.js` du plugin propriétaire. - Des sous-chemins spécifiques à une capacité tels que `image-generation`, - `media-understanding` et `speech` existent parce que les plugins natifs/intégrés les utilisent aujourd'hui. Leur présence ne signifie pas à elle seule que chaque helper exporté est un contrat externe figé à long terme. + `media-understanding` et `speech` existent parce que les plugins bundled/natifs les utilisent + aujourd’hui. Leur présence ne signifie pas à elle seule que chaque assistant exporté constitue un contrat externe figé à long terme. -## Schémas d'outil de message +## Schémas de l’outil de message -Les plugins doivent posséder les contributions de schéma spécifiques au canal de `describeMessageTool(...)`. -Conservez les champs spécifiques au fournisseur dans le plugin, pas dans le cœur partagé. +Les plugins doivent posséder les contributions de schéma `describeMessageTool(...)` spécifiques au canal. +Conservez les champs spécifiques au fournisseur dans le plugin, et non dans le cœur partagé. -Pour des fragments de schéma portables partagés, réutilisez les helpers génériques exportés via +Pour les fragments de schéma portables partagés, réutilisez les assistants génériques exportés via `openclaw/plugin-sdk/channel-actions` : - `createMessageToolButtonsSchema()` pour les charges utiles de style grille de boutons -- `createMessageToolCardSchema()` pour les charges utiles de carte structurée +- `createMessageToolCardSchema()` pour les charges utiles de cartes structurées -Si une forme de schéma n'a de sens que pour un fournisseur, définissez-la dans la -propre source de ce plugin au lieu de la promouvoir dans le SDK partagé. +Si une forme de schéma n’a de sens que pour un seul fournisseur, définissez-la dans les +sources propres à ce plugin au lieu de la promouvoir dans le SDK partagé. -## Résolution des cibles de canal +## Résolution de cible de canal -Les plugins de canal doivent posséder la sémantique des cibles propre au canal. Gardez l'hôte -sortant partagé générique et utilisez la surface de l'adaptateur de messagerie pour les règles du fournisseur : +Les plugins de canal doivent posséder la sémantique de cible spécifique au canal. Gardez l’hôte +sortant partagé générique et utilisez la surface de l’adaptateur de messagerie pour les règles fournisseur : - `messaging.inferTargetChatType({ to })` décide si une cible normalisée - doit être traitée comme `direct`, `group`, ou `channel` avant la recherche dans l'annuaire. + doit être traitée comme `direct`, `group` ou `channel` avant la recherche dans l’annuaire. - `messaging.targetResolver.looksLikeId(raw, normalized)` indique au cœur si une - entrée doit passer directement à une résolution de type identifiant au lieu d'une recherche dans l'annuaire. -- `messaging.targetResolver.resolveTarget(...)` est le fallback du plugin lorsque le - cœur a besoin d'une résolution finale appartenant au fournisseur après normalisation ou après un échec d'annuaire. -- `messaging.resolveOutboundSessionRoute(...)` possède la construction de route de session spécifique au fournisseur une fois la cible résolue. + entrée doit passer directement à une résolution de type identifiant au lieu d’une recherche dans l’annuaire. +- `messaging.targetResolver.resolveTarget(...)` est le repli du plugin lorsque le + cœur a besoin d’une résolution finale appartenant au fournisseur après normalisation ou après un + échec de recherche dans l’annuaire. +- `messaging.resolveOutboundSessionRoute(...)` possède la construction de route de session + spécifique au fournisseur une fois qu’une cible est résolue. Répartition recommandée : -- Utilisez `inferTargetChatType` pour les décisions de catégorie qui doivent se produire avant - la recherche dans les pairs/groupes. -- Utilisez `looksLikeId` pour les vérifications « traiter ceci comme un identifiant de cible explicite/natif ». -- Utilisez `resolveTarget` pour le fallback de normalisation spécifique au fournisseur, pas pour une recherche large dans l'annuaire. -- Conservez les identifiants natifs du fournisseur tels que les identifiants de chat, de fil, les JID, handles et identifiants de salle dans les valeurs `target` ou les paramètres spécifiques au fournisseur, pas dans des champs SDK génériques. +- Utilisez `inferTargetChatType` pour les décisions de catégorie qui doivent intervenir avant la + recherche parmi pairs/groupes. +- Utilisez `looksLikeId` pour les vérifications de type « traiter ceci comme un identifiant de cible explicite/natif ». +- Utilisez `resolveTarget` pour le repli de normalisation spécifique au fournisseur, et non pour une + recherche large dans l’annuaire. +- Conservez les identifiants natifs du fournisseur comme les identifiants de chat, identifiants de fil, JID, handles et identifiants de salle + dans les valeurs `target` ou les paramètres spécifiques au fournisseur, pas dans des champs SDK génériques. ## Annuaires adossés à la configuration -Les plugins qui dérivent des entrées d'annuaire à partir de la configuration doivent conserver cette logique dans le -plugin et réutiliser les helpers partagés de +Les plugins qui dérivent des entrées d’annuaire à partir de la configuration doivent conserver cette logique dans le +plugin et réutiliser les assistants partagés de `openclaw/plugin-sdk/directory-runtime`. -Utilisez ceci lorsqu'un canal a besoin de pairs/groupes adossés à la configuration tels que : +Utilisez cela lorsqu’un canal a besoin de pairs/groupes adossés à la configuration tels que : -- pairs DM pilotés par une liste d'autorisation -- cartes de canaux/groupes configurées -- fallbacks statiques d'annuaire à portée de compte +- pairs de messages privés pilotés par liste d’autorisation +- mappages configurés de canaux/groupes +- replis d’annuaire statiques à portée de compte -Les helpers partagés de `directory-runtime` ne gèrent que des opérations génériques : +Les assistants partagés de `directory-runtime` ne gèrent que les opérations génériques : - filtrage de requête -- application de limites -- helpers de déduplication/normalisation +- application de limite +- assistants de déduplication/normalisation - construction de `ChannelDirectoryEntry[]` -L'inspection de compte spécifique au canal et la normalisation des identifiants doivent rester dans l'implémentation du plugin. +L’inspection de compte spécifique au canal et la normalisation des identifiants doivent rester dans +l’implémentation du plugin. ## Catalogues de fournisseurs -Les plugins de fournisseur peuvent définir des catalogues de modèles pour l'inférence avec +Les plugins fournisseurs peuvent définir des catalogues de modèles pour l’inférence avec `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` renvoie la même forme que celle écrite par OpenClaw dans +`catalog.run(...)` renvoie la même forme que celle qu’OpenClaw écrit dans `models.providers` : - `{ provider }` pour une entrée de fournisseur - `{ providers }` pour plusieurs entrées de fournisseur -Utilisez `catalog` lorsque le plugin possède des identifiants de modèle, des valeurs par défaut de base URL -ou des métadonnées de modèle conditionnées par l'auth propres au fournisseur. +Utilisez `catalog` lorsque le plugin possède des identifiants de modèle spécifiques au fournisseur, des valeurs par défaut de base URL, +ou des métadonnées de modèle protégées par authentification. -`catalog.order` contrôle le moment auquel le catalogue d'un plugin fusionne par rapport aux -fournisseurs implicites intégrés d'OpenClaw : +`catalog.order` contrôle le moment où le catalogue d’un plugin fusionne par rapport aux +fournisseurs implicites intégrés d’OpenClaw : -- `simple`: fournisseurs simples pilotés par clé API ou variables d'environnement -- `profile`: fournisseurs qui apparaissent lorsqu'il existe des profils d'auth -- `paired`: fournisseurs qui synthétisent plusieurs entrées de fournisseur liées -- `late`: dernier passage, après les autres fournisseurs implicites +- `simple` : fournisseurs simples pilotés par clé API ou environnement +- `profile` : fournisseurs qui apparaissent lorsque des profils d’authentification existent +- `paired` : fournisseurs qui synthétisent plusieurs entrées de fournisseur liées +- `late` : dernier passage, après les autres fournisseurs implicites -Les fournisseurs plus tardifs gagnent en cas de collision de clé, de sorte que les plugins peuvent -remplacer intentionnellement une entrée de fournisseur intégrée ayant le même identifiant. +Les fournisseurs plus tardifs l’emportent en cas de collision de clé, ce qui permet aux plugins de remplacer intentionnellement une +entrée de fournisseur intégrée avec le même identifiant de fournisseur. Compatibilité : - `discovery` fonctionne toujours comme alias legacy - si `catalog` et `discovery` sont tous deux enregistrés, OpenClaw utilise `catalog` -## Inspection en lecture seule des canaux +## Inspection de canal en lecture seule Si votre plugin enregistre un canal, préférez implémenter -`plugin.config.inspectAccount(cfg, accountId)` en même temps que `resolveAccount(...)`. +`plugin.config.inspectAccount(cfg, accountId)` en plus de `resolveAccount(...)`. Pourquoi : -- `resolveAccount(...)` est le chemin runtime. Il peut supposer que les identifiants - sont entièrement matérialisés et échouer rapidement si les secrets requis sont absents. -- Les chemins de commande en lecture seule tels que `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, et les flux de réparation - doctor/config ne devraient pas avoir besoin de matérialiser des identifiants runtime simplement pour +- `resolveAccount(...)` est le chemin d’exécution. Il peut supposer que les identifiants + sont entièrement matérialisés et peut échouer rapidement si les secrets requis sont absents. +- Les chemins de commandes en lecture seule tels que `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve`, ainsi que les flux de réparation doctor/config + ne doivent pas avoir besoin de matérialiser les identifiants d’exécution juste pour décrire la configuration. -Comportement recommandé pour `inspectAccount(...)` : +Comportement recommandé de `inspectAccount(...)` : - Renvoyer uniquement un état descriptif du compte. - Préserver `enabled` et `configured`. -- Inclure les champs de source/statut d'identifiants quand c'est pertinent, comme : +- Inclure les champs de source/statut des identifiants lorsque cela est pertinent, tels que : - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Vous n'avez pas besoin de renvoyer les valeurs brutes des jetons simplement pour signaler une disponibilité en lecture seule. Renvoyer `tokenStatus: "available"` (et le champ source correspondant) suffit pour des commandes de type statut. -- Utilisez `configured_unavailable` lorsqu'un identifiant est configuré via SecretRef mais indisponible sur le chemin de commande actuel. +- Vous n’avez pas besoin de renvoyer les valeurs brutes de jeton simplement pour signaler une + disponibilité en lecture seule. Renvoyer `tokenStatus: "available"` (et le champ source correspondant) + suffit pour les commandes de type statut. +- Utilisez `configured_unavailable` lorsqu’un identifiant est configuré via SecretRef mais + indisponible dans le chemin de commande courant. -Cela permet aux commandes en lecture seule de signaler « configuré mais indisponible sur ce chemin de commande » -au lieu de planter ou de rapporter à tort que le compte n'est pas configuré. +Cela permet aux commandes en lecture seule d’indiquer « configuré mais indisponible dans ce chemin de commande » +au lieu de planter ou de signaler à tort que le compte n’est pas configuré. -## Packs de paquets +## Packs de packages Un répertoire de plugin peut inclure un `package.json` avec `openclaw.extensions` : @@ -1326,62 +1323,61 @@ Un répertoire de plugin peut inclure un `package.json` avec `openclaw.extension } ``` -Chaque entrée devient un plugin. Si le pack liste plusieurs extensions, l'identifiant du plugin +Chaque entrée devient un plugin. Si le pack liste plusieurs extensions, l’identifiant du plugin devient `name/`. Si votre plugin importe des dépendances npm, installez-les dans ce répertoire afin que `node_modules` soit disponible (`npm install` / `pnpm install`). -Garde-fou de sécurité : chaque entrée `openclaw.extensions` doit rester à l'intérieur du répertoire du plugin -après résolution des liens symboliques. Les entrées qui sortent du répertoire du paquet sont +Garde-fou de sécurité : chaque entrée `openclaw.extensions` doit rester dans le répertoire du plugin +après résolution des liens symboliques. Les entrées qui sortent du répertoire du package sont rejetées. -Note de sécurité : `openclaw plugins install` installe les dépendances de plugin avec -`npm install --omit=dev --ignore-scripts` (sans scripts de cycle de vie, sans dépendances de développement à l'exécution). Gardez les arbres de dépendances des plugins en « JS/TS pur » et évitez les paquets qui exigent des builds `postinstall`. +Note de sécurité : `openclaw plugins install` installe les dépendances du plugin avec +`npm install --omit=dev --ignore-scripts` (pas de scripts de cycle de vie, pas de dépendances de développement à l’exécution). Gardez les arbres de dépendances des plugins en +« JS/TS pur » et évitez les packages qui nécessitent des compilations `postinstall`. Facultatif : `openclaw.setupEntry` peut pointer vers un module léger réservé à la configuration. Lorsque OpenClaw a besoin de surfaces de configuration pour un plugin de canal désactivé, ou -lorsqu'un plugin de canal est activé mais encore non configuré, il charge `setupEntry` -au lieu de l'entrée complète du plugin. Cela allège le démarrage et la configuration -quand l'entrée principale du plugin câble aussi des outils, hooks ou autre code -réservé au runtime. +lorsqu’un plugin de canal est activé mais encore non configuré, il charge `setupEntry` +au lieu du point d’entrée complet du plugin. Cela allège le démarrage et la configuration +lorsque le point d’entrée principal de votre plugin connecte aussi des outils, hooks ou tout autre code +réservé à l’exécution. Facultatif : `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -peut faire entrer un plugin de canal dans le même chemin `setupEntry` pendant la phase de -démarrage pré-écoute de la gateway, même lorsque le canal est déjà configuré. +peut faire participer un plugin de canal au même chemin `setupEntry` pendant la +phase de démarrage pré-listen de la gateway, même lorsque le canal est déjà configuré. -Utilisez cela uniquement si `setupEntry` couvre complètement la surface de démarrage qui doit exister -avant que la gateway ne commence à écouter. En pratique, cela signifie que l'entrée de configuration -doit enregistrer chaque capacité appartenant au canal dont le démarrage dépend, par exemple : +N’utilisez cela que si `setupEntry` couvre entièrement la surface de démarrage qui doit exister +avant que la gateway commence à écouter. En pratique, cela signifie que le point d’entrée de configuration +doit enregistrer chaque capacité appartenant au canal dont dépend le démarrage, comme : -- l'enregistrement du canal lui-même -- toutes les routes HTTP qui doivent être disponibles avant que la gateway ne commence à écouter -- toutes les méthodes gateway, outils ou services qui doivent exister dans cette même fenêtre +- l’enregistrement du canal lui-même +- toute route HTTP qui doit être disponible avant que la gateway commence à écouter +- toute méthode gateway, tout outil ou tout service qui doit exister pendant cette même fenêtre -Si votre entrée complète possède encore une capacité de démarrage requise, n'activez pas -ce drapeau. Conservez le comportement par défaut du plugin et laissez OpenClaw charger -l'entrée complète au démarrage. +Si votre point d’entrée complet possède encore une capacité de démarrage requise, n’activez pas +ce drapeau. Conservez le comportement par défaut du plugin et laissez OpenClaw charger le +point d’entrée complet pendant le démarrage. -Les canaux intégrés peuvent aussi publier des helpers de surface de contrat réservés à la configuration que le cœur -peut consulter avant que le runtime complet du canal soit chargé. La surface actuelle de promotion de configuration est : +Les canaux bundled peuvent aussi publier des assistants de surface de contrat réservés à la configuration que le cœur +peut consulter avant le chargement de l’exécution complète du canal. La surface actuelle de promotion de configuration est : - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Le cœur utilise cette surface lorsqu'il doit promouvoir une configuration legacy de canal à compte unique -dans `channels..accounts.*` sans charger l'entrée complète du plugin. -Matrix est l'exemple intégré actuel : il ne déplace que les clés d'auth/bootstrap dans un -compte promu nommé lorsque des comptes nommés existent déjà, et il peut préserver -une clé de compte par défaut configurée non canonique au lieu de toujours créer +Le cœur utilise cette surface lorsqu’il doit promouvoir une configuration de canal legacy à compte unique +vers `channels..accounts.*` sans charger le point d’entrée complet du plugin. +Matrix est l’exemple bundled actuel : il ne déplace que les clés d’authentification/d’amorçage vers un +compte promu nommé lorsque des comptes nommés existent déjà, et il peut préserver une +clé de compte par défaut configurée non canonique au lieu de toujours créer `accounts.default`. -Ces adaptateurs de patch de configuration gardent la découverte de surface de contrat intégrée paresseuse. Le temps -d'import reste léger ; la surface de promotion n'est chargée qu'au premier usage au lieu de -réentrer dans le démarrage du canal intégré à l'import du module. +Ces adaptateurs de patch de configuration maintiennent la découverte de surface de contrat bundled de façon paresseuse. Le temps d’import reste léger ; la surface de promotion n’est chargée qu’au premier usage au lieu de réentrer dans le démarrage du canal bundled à l’import du module. -Lorsque ces surfaces de démarrage incluent des méthodes RPC gateway, conservez-les sur un -préfixe spécifique au plugin. Les espaces de noms admin du cœur (`config.*`, +Lorsque ces surfaces de démarrage incluent des méthodes Gateway RPC, conservez-les sur 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`, même si un plugin demande une portée plus étroite. @@ -1403,7 +1399,7 @@ Exemple : ### Métadonnées de catalogue de canal Les plugins de canal peuvent annoncer des métadonnées de configuration/découverte via `openclaw.channel` et -des indices d'installation via `openclaw.install`. Cela permet au cœur de rester sans données de catalogue. +des indications d’installation via `openclaw.install`. Cela permet au catalogue du cœur de rester sans données. Exemple : @@ -1415,10 +1411,10 @@ Exemple : "channel": { "id": "nextcloud-talk", "label": "Nextcloud Talk", - "selectionLabel": "Nextcloud Talk (self-hosted)", + "selectionLabel": "Nextcloud Talk (autohébergé)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", + "blurb": "Chat autohébergé via des bots webhook Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1431,23 +1427,23 @@ Exemple : } ``` -Champs utiles de `openclaw.channel` au-delà de l'exemple minimal : +Champs `openclaw.channel` utiles au-delà de l’exemple minimal : -- `detailLabel`: libellé secondaire pour des surfaces plus riches de catalogue/statut -- `docsLabel`: surcharge du texte du lien de documentation -- `preferOver`: identifiants de plugin/canal de priorité inférieure que cette entrée de catalogue doit dépasser -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: contrôles de copie de la surface de sélection -- `markdownCapable`: marque le canal comme capable de Markdown pour les décisions de formatage sortant -- `exposure.configured`: masque le canal des surfaces de liste des canaux configurés lorsqu'il vaut `false` -- `exposure.setup`: masque le canal des sélecteurs interactifs de configuration lorsqu'il vaut `false` -- `exposure.docs`: marque le canal comme interne/privé pour les surfaces de navigation de documentation -- `showConfigured` / `showInSetup`: alias legacy encore acceptés pour compatibilité ; préférez `exposure` -- `quickstartAllowFrom`: fait entrer le canal dans le flux standard quickstart `allowFrom` -- `forceAccountBinding`: exige une liaison de compte explicite même lorsqu'un seul compte existe -- `preferSessionLookupForAnnounceTarget`: préfère la recherche de session lors de la résolution des cibles d'annonce +- `detailLabel` : libellé secondaire pour des surfaces plus riches de catalogue/statut +- `docsLabel` : remplace le texte du lien de documentation +- `preferOver` : identifiants de plugin/canal de priorité inférieure que cette entrée de catalogue doit surpasser +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras` : contrôles de texte de la surface de sélection +- `markdownCapable` : marque le canal comme compatible Markdown pour les décisions de formatage sortant +- `exposure.configured` : masque le canal des surfaces de liste de canaux configurés lorsqu’il est défini sur `false` +- `exposure.setup` : masque le canal des sélecteurs interactifs de configuration lorsqu’il est défini sur `false` +- `exposure.docs` : marque le canal comme interne/privé pour les surfaces de navigation de documentation +- `showConfigured` / `showInSetup` : alias legacy encore acceptés pour compatibilité ; préférez `exposure` +- `quickstartAllowFrom` : fait participer le canal au flux standard `allowFrom` de démarrage rapide +- `forceAccountBinding` : exige une liaison explicite de compte même lorsqu’un seul compte existe +- `preferSessionLookupForAnnounceTarget` : préfère la recherche de session lors de la résolution des cibles d’annonce -OpenClaw peut aussi fusionner des **catalogues de canaux externes** (par exemple un export -de registre MPM). Déposez un fichier JSON à l'un de ces emplacements : +OpenClaw peut aussi fusionner des **catalogues de canaux externes** (par exemple, un export de registre MPM). +Déposez un fichier JSON à l’un de ces emplacements : - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` @@ -1455,17 +1451,17 @@ de registre MPM). Déposez un fichier JSON à l'un de ces emplacements : Ou pointez `OPENCLAW_PLUGIN_CATALOG_PATHS` (ou `OPENCLAW_MPM_CATALOG_PATHS`) vers un ou plusieurs fichiers JSON (délimités par virgule/point-virgule/`PATH`). Chaque fichier doit -contenir `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. L'analyseur accepte aussi `"packages"` ou `"plugins"` comme alias legacy de la clé `"entries"`. +contenir `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. L’analyseur accepte aussi `"packages"` ou `"plugins"` comme alias legacy de la clé `"entries"`. ## Plugins de moteur de contexte -Les plugins de moteur de contexte possèdent l'orchestration du contexte de session pour l'ingestion, l'assemblage +Les plugins de moteur de contexte possèdent l’orchestration du contexte de session pour l’ingestion, l’assemblage, et la compaction. Enregistrez-les depuis votre plugin avec `api.registerContextEngine(id, factory)`, puis sélectionnez le moteur actif avec `plugins.slots.contextEngine`. -Utilisez cela lorsque votre plugin doit remplacer ou étendre le pipeline de contexte par défaut -plutôt que simplement ajouter une recherche mémoire ou des hooks. +Utilisez cela lorsque votre plugin a besoin de remplacer ou d’étendre le pipeline de contexte par défaut +plutôt que de simplement ajouter une recherche mémoire ou des hooks. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1493,7 +1489,7 @@ export default function (api) { } ``` -Si votre moteur ne possède **pas** l'algorithme de compaction, gardez `compact()` +Si votre moteur ne possède **pas** l’algorithme de compaction, laissez `compact()` implémenté et déléguez-le explicitement : ```ts @@ -1531,49 +1527,50 @@ export default function (api) { ## Ajouter une nouvelle capacité -Lorsqu'un plugin a besoin d'un comportement qui ne correspond pas à l'API actuelle, ne contournez pas -le système de plugins par un accès privé. Ajoutez la capacité manquante. +Lorsqu’un plugin a besoin d’un comportement qui ne correspond pas à l’API actuelle, ne contournez pas +le système de plugins avec un accès privé direct. Ajoutez la capacité manquante. Séquence recommandée : 1. définir le contrat du cœur - Décidez quel comportement partagé le cœur doit posséder : politique, fallback, fusion de configuration, - cycle de vie, sémantique côté canal et forme du helper runtime. -2. ajouter des surfaces typées d'enregistrement/runtime pour les plugins + Décidez quel comportement partagé le cœur doit posséder : politique, repli, fusion de configuration, + cycle de vie, sémantique côté canal et forme de l’assistant d’exécution. +2. ajouter des surfaces typées d’enregistrement/d’exécution des plugins Étendez `OpenClawPluginApi` et/ou `api.runtime` avec la plus petite surface de capacité typée utile. -3. câbler les consommateurs cœur + canal/fonctionnalité +3. raccorder le cœur + les consommateurs canal/fonctionnalité Les canaux et plugins de fonctionnalité doivent consommer la nouvelle capacité via le cœur, - pas en important directement une implémentation fournisseur. -4. enregistrer les implémentations fournisseurs + et non en important directement une implémentation fournisseur. +4. enregistrer les implémentations fournisseur Les plugins fournisseurs enregistrent ensuite leurs backends sur cette capacité. 5. ajouter une couverture de contrat - Ajoutez des tests pour que la propriété et la forme d'enregistrement restent explicites au fil du temps. + Ajoutez des tests afin que la propriété et la forme d’enregistrement restent explicites au fil du temps. -C'est ainsi qu'OpenClaw reste affirmé sans devenir codé en dur selon la vision du monde -d'un fournisseur unique. Voir le [Capability Cookbook](/fr/plugins/architecture) -pour une checklist concrète de fichiers et un exemple détaillé. +C’est ainsi qu’OpenClaw reste structuré sans devenir codé en dur selon la vision du monde +d’un seul fournisseur. Voir les [Recettes de capacités](/fr/plugins/architecture) +pour une liste concrète de fichiers et un exemple détaillé. -### Checklist de capacité +### Liste de contrôle des capacités -Lorsque vous ajoutez une nouvelle capacité, l'implémentation doit en général toucher -ensemble les surfaces suivantes : +Lorsque vous ajoutez une nouvelle capacité, l’implémentation doit généralement toucher ensemble ces +surfaces : - types de contrat du cœur dans `src//types.ts` -- runner/helper runtime du cœur dans `src//runtime.ts` -- surface d'enregistrement de l'API des plugins dans `src/plugins/types.ts` -- câblage du registre de plugins dans `src/plugins/registry.ts` -- exposition du runtime des plugins dans `src/plugins/runtime/*` lorsque des plugins de fonctionnalité/de canal doivent le consommer -- helpers de capture/test dans `src/test-utils/plugin-registration.ts` -- assertions de propriété/contrat dans `src/plugins/contracts/registry.ts` +- runner du cœur/assistant d’exécution dans `src//runtime.ts` +- surface d’enregistrement de l’API des plugins dans `src/plugins/types.ts` +- câblage du registre des plugins dans `src/plugins/registry.ts` +- exposition de l’exécution des plugins dans `src/plugins/runtime/*` lorsque les plugins de fonctionnalité/de canal + doivent la consommer +- assistants de capture/test dans `src/test-utils/plugin-registration.ts` +- assertions de propriété/de contrat dans `src/plugins/contracts/registry.ts` - documentation opérateur/plugin dans `docs/` -Si l'une de ces surfaces manque, c'est généralement le signe que la capacité n'est +Si l’une de ces surfaces manque, c’est généralement le signe que la capacité n’est pas encore entièrement intégrée. ### Modèle de capacité -Modèle minimal : +Motif minimal : ```ts // contrat du cœur @@ -1592,22 +1589,22 @@ api.registerVideoGenerationProvider({ }, }); -// helper runtime partagé pour les plugins de fonctionnalité/de canal +// assistant d’exécution partagé pour les plugins de fonctionnalité/de canal const clip = await api.runtime.videoGeneration.generate({ - prompt: "Show the robot walking through the lab.", + prompt: "Montre le robot marchant dans le laboratoire.", cfg, }); ``` -Modèle de test de contrat : +Motif de test de contrat : ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Cela garde une règle simple : +Cela garde la règle simple : -- le cœur possède le contrat de capacité + l'orchestration -- les plugins fournisseurs possèdent les implémentations fournisseurs -- les plugins de fonctionnalité/de canal consomment les helpers runtime -- les tests de contrat gardent la propriété explicite +- le cœur possède le contrat de capacité + l’orchestration +- les plugins fournisseurs possèdent les implémentations fournisseur +- les plugins de fonctionnalité/de canal consomment les assistants d’exécution +- les tests de contrat gardent une propriété explicite diff --git a/docs/fr/plugins/manifest.md b/docs/fr/plugins/manifest.md index 604554372..ead95204c 100644 --- a/docs/fr/plugins/manifest.md +++ b/docs/fr/plugins/manifest.md @@ -1,62 +1,73 @@ --- read_when: - Vous créez un plugin OpenClaw - - Vous devez livrer un schéma de configuration de plugin ou déboguer des erreurs de validation du plugin -summary: Manifeste du plugin + exigences du schéma JSON (validation stricte de la configuration) -title: Manifeste du plugin + - Vous devez fournir un schéma de configuration de plugin ou déboguer des erreurs de validation du plugin +summary: Exigences du manifeste de plugin + schéma JSON (validation stricte de la configuration) +title: Manifeste de plugin x-i18n: - generated_at: "2026-04-11T02:45:54Z" + generated_at: "2026-04-11T15:16:01Z" model: gpt-5.4 provider: openai - source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88 + source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 source_path: plugins/manifest.md workflow: 15 --- -# Manifeste du plugin (openclaw.plugin.json) +# Manifeste de plugin (`openclaw.plugin.json`) Cette page concerne uniquement le **manifeste de plugin natif OpenClaw**. Pour les dispositions de bundles compatibles, voir [Bundles de plugins](/fr/plugins/bundles). -Les formats de bundle compatibles utilisent des fichiers manifeste différents : +Les formats de bundle compatibles utilisent des fichiers de manifeste différents : - Bundle Codex : `.codex-plugin/plugin.json` -- Bundle Claude : `.claude-plugin/plugin.json` ou la disposition par défaut des composants Claude sans manifeste +- Bundle Claude : `.claude-plugin/plugin.json` ou la disposition par défaut du composant Claude + sans manifeste - Bundle Cursor : `.cursor-plugin/plugin.json` -OpenClaw détecte automatiquement aussi ces dispositions de bundle, mais elles ne sont pas validées par rapport au schéma `openclaw.plugin.json` décrit ici. +OpenClaw détecte automatiquement ces dispositions de bundle également, mais elles ne sont pas validées +par rapport au schéma `openclaw.plugin.json` décrit ici. -Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les racines de Skills déclarées, les racines de commandes Claude, les valeurs par défaut `settings.json` du bundle Claude, les valeurs par défaut LSP du bundle Claude et les packs de hooks pris en charge lorsque la disposition correspond aux attentes du runtime OpenClaw. +Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les +racines de compétences déclarées, les racines de commandes Claude, les valeurs par défaut de `settings.json` du bundle Claude, +les valeurs par défaut LSP du bundle Claude, et les packs de hooks pris en charge lorsque la disposition correspond +aux attentes d’exécution d’OpenClaw. -Chaque plugin natif OpenClaw **doit** fournir un fichier `openclaw.plugin.json` dans la **racine du plugin**. OpenClaw utilise ce manifeste pour valider la configuration **sans exécuter le code du plugin**. Les manifestes manquants ou invalides sont traités comme des erreurs de plugin et bloquent la validation de la configuration. +Chaque plugin OpenClaw natif **doit** fournir un fichier `openclaw.plugin.json` dans la +**racine du plugin**. OpenClaw utilise ce manifeste pour valider la configuration +**sans exécuter le code du plugin**. Les manifestes manquants ou invalides sont traités comme des +erreurs de plugin et bloquent la validation de la configuration. -Voir le guide complet du système de plugins : [Plugins](/fr/tools/plugin). -Pour le modèle de capacités natif et les indications actuelles de compatibilité externe : +Consultez le guide complet du système de plugins : [Plugins](/fr/tools/plugin). +Pour le modèle de capacités natif et les recommandations actuelles de compatibilité externe : [Modèle de capacités](/fr/plugins/architecture#public-capability-model). ## À quoi sert ce fichier -`openclaw.plugin.json` est la métadonnée que OpenClaw lit avant de charger le code de votre plugin. +`openclaw.plugin.json` contient les métadonnées qu’OpenClaw lit avant de charger le +code de votre plugin. Utilisez-le pour : - l’identité du plugin - la validation de la configuration -- les métadonnées d’authentification et d’onboarding qui doivent être disponibles sans démarrer le runtime du plugin -- les métadonnées d’alias et d’activation automatique qui doivent être résolues avant le chargement du runtime du plugin -- les métadonnées abrégées de propriété des familles de modèles qui doivent activer automatiquement le plugin avant le chargement du runtime -- les instantanés statiques de propriété des capacités utilisés pour le câblage de compatibilité des bundles et la couverture des contrats -- les métadonnées de configuration spécifiques aux canaux qui doivent être fusionnées dans le catalogue et les surfaces de validation sans charger le runtime -- les indications pour l’UI de configuration +- les métadonnées d’authentification et d’intégration qui doivent être disponibles sans démarrer l’exécution du plugin +- les indices d’activation légers que les surfaces du plan de contrôle peuvent inspecter avant le chargement de l’exécution +- les descripteurs de configuration légers que les surfaces de configuration/intégration peuvent inspecter avant le chargement de l’exécution +- les métadonnées d’alias et d’activation automatique qui doivent être résolues avant le chargement de l’exécution du plugin +- les métadonnées abrégées de propriété de famille de modèles qui doivent activer automatiquement le plugin avant le chargement de l’exécution +- les instantanés statiques de propriété de capacités utilisés pour le câblage de compatibilité groupée et la couverture des contrats +- les métadonnées de configuration spécifiques aux canaux qui doivent être fusionnées dans les surfaces de catalogue et de validation sans charger l’exécution +- les indices d’interface pour la configuration Ne l’utilisez pas pour : -- enregistrer le comportement du runtime -- déclarer les points d’entrée du code +- enregistrer le comportement d’exécution +- déclarer des points d’entrée de code - les métadonnées d’installation npm -Ces éléments appartiennent à votre code de plugin et à `package.json`. +Ces éléments appartiennent au code de votre plugin et à `package.json`. ## Exemple minimal @@ -77,7 +88,7 @@ Ces éléments appartiennent à votre code de plugin et à `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin provider OpenRouter", + "description": "Plugin de fournisseur OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -127,62 +138,64 @@ Ces éléments appartiennent à votre code de plugin et à `package.json`. } ``` -## Référence des champs de premier niveau +## Référence des champs de niveau supérieur -| Champ | Obligatoire | Type | Signification | -| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Oui | `string` | ID canonique du plugin. C’est l’ID utilisé dans `plugins.entries.`. | -| `configSchema` | Oui | `object` | Schéma JSON inline pour la configuration de ce plugin. | -| `enabledByDefault` | Non | `true` | Marque un plugin bundle comme activé par défaut. Omettez-le, ou définissez toute valeur autre que `true`, pour laisser le plugin désactivé par défaut. | +| Champ | Obligatoire | Type | Signification | +| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Oui | `string` | ID canonique du plugin. Il s’agit de l’ID utilisé dans `plugins.entries.`. | +| `configSchema` | Oui | `object` | Schéma JSON inline pour la configuration de ce plugin. | +| `enabledByDefault` | Non | `true` | Marque un plugin groupé comme activé par défaut. Omettez-le, ou définissez toute valeur autre que `true`, pour laisser le plugin désactivé par défaut. | | `legacyPluginIds` | Non | `string[]` | IDs hérités qui sont normalisés vers cet ID canonique de plugin. | -| `autoEnableWhenConfiguredProviders` | Non | `string[]` | IDs de provider qui doivent activer automatiquement ce plugin lorsque l’authentification, la configuration ou les références de modèles les mentionnent. | -| `kind` | Non | `"memory"` \| `"context-engine"` | Déclare un type de plugin exclusif utilisé par `plugins.slots.*`. | -| `channels` | Non | `string[]` | IDs de canaux possédés par ce plugin. Utilisés pour la découverte et la validation de la configuration. | -| `providers` | Non | `string[]` | IDs de providers possédés par ce plugin. | -| `modelSupport` | Non | `object` | Métadonnées abrégées des familles de modèles, détenues par le manifeste, utilisées pour charger automatiquement le plugin avant le runtime. | -| `cliBackends` | Non | `string[]` | IDs de backends d’inférence CLI possédés par ce plugin. Utilisés pour l’activation automatique au démarrage à partir de références de configuration explicites. | -| `commandAliases` | Non | `object[]` | Noms de commandes possédés par ce plugin qui doivent produire une configuration sensible au plugin et des diagnostics CLI avant le chargement du runtime. | -| `providerAuthEnvVars` | Non | `Record` | Métadonnées d’environnement d’authentification provider peu coûteuses que OpenClaw peut inspecter sans charger le code du plugin. | -| `providerAuthAliases` | Non | `Record` | IDs de provider qui doivent réutiliser un autre ID de provider pour la recherche d’authentification, par exemple un provider de code qui partage la clé API et les profils d’authentification du provider de base. | -| `channelEnvVars` | Non | `Record` | Métadonnées d’environnement de canal peu coûteuses que OpenClaw peut inspecter sans charger le code du plugin. Utilisez-les pour les surfaces d’installation de canal pilotées par l’environnement ou d’authentification que les assistants génériques de démarrage/configuration doivent voir. | -| `providerAuthChoices` | Non | `object[]` | Métadonnées peu coûteuses de choix d’authentification pour les sélecteurs d’onboarding, la résolution des providers préférés et le câblage simple des options CLI. | -| `contracts` | Non | `object` | Instantané statique des capacités bundle pour la parole, la transcription en temps réel, la voix en temps réel, la compréhension des médias, la génération d’images, la génération de musique, la génération de vidéo, la récupération web, la recherche web et la propriété des outils. | -| `channelConfigs` | Non | `Record` | Métadonnées de configuration de canal détenues par le manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement du runtime. | -| `skills` | Non | `string[]` | Répertoires de Skills à charger, relatifs à la racine du plugin. | -| `name` | Non | `string` | Nom lisible du plugin. | -| `description` | Non | `string` | Résumé court affiché dans les surfaces du plugin. | -| `version` | Non | `string` | Version informative du plugin. | -| `uiHints` | Non | `Record` | Libellés UI, placeholders et indications de sensibilité pour les champs de configuration. | +| `autoEnableWhenConfiguredProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer automatiquement ce plugin lorsque l’authentification, la configuration ou les références de modèles les mentionnent. | +| `kind` | Non | `"memory"` \| `"context-engine"` | Déclare un type exclusif de plugin utilisé par `plugins.slots.*`. | +| `channels` | Non | `string[]` | IDs de canaux appartenant à ce plugin. Utilisés pour la découverte et la validation de la configuration. | +| `providers` | Non | `string[]` | IDs de fournisseurs appartenant à ce plugin. | +| `modelSupport` | Non | `object` | Métadonnées abrégées de famille de modèles possédées par le manifeste, utilisées pour charger automatiquement le plugin avant l’exécution. | +| `cliBackends` | Non | `string[]` | IDs de backends d’inférence CLI appartenant à ce plugin. Utilisés pour l’auto-activation au démarrage à partir de références de configuration explicites. | +| `commandAliases` | Non | `object[]` | Noms de commandes appartenant à ce plugin qui doivent produire une configuration sensible au plugin et des diagnostics CLI avant le chargement de l’exécution. | +| `providerAuthEnvVars` | Non | `Record` | Métadonnées légères de variables d’environnement d’authentification fournisseur qu’OpenClaw peut inspecter sans charger le code du plugin. | +| `providerAuthAliases` | Non | `Record` | IDs de fournisseurs qui doivent réutiliser un autre ID de fournisseur pour la recherche d’authentification, par exemple un fournisseur de code qui partage la clé API et les profils d’authentification du fournisseur de base. | +| `channelEnvVars` | Non | `Record` | Métadonnées légères de variables d’environnement de canal qu’OpenClaw peut inspecter sans charger le code du plugin. Utilisez-les pour les surfaces de configuration ou d’authentification de canaux pilotées par des variables d’environnement que les assistants génériques de démarrage/configuration doivent voir. | +| `providerAuthChoices` | Non | `object[]` | Métadonnées légères de choix d’authentification pour les sélecteurs d’intégration, la résolution du fournisseur préféré et le câblage simple des options CLI. | +| `activation` | Non | `object` | Indices d’activation légers pour le chargement déclenché par les fournisseurs, commandes, canaux, routes et capacités. Métadonnées uniquement ; l’exécution du plugin reste propriétaire du comportement réel. | +| `setup` | Non | `object` | Descripteurs légers de configuration/intégration que les surfaces de découverte et de configuration peuvent inspecter sans charger l’exécution du plugin. | +| `contracts` | Non | `object` | Instantané statique des capacités groupées pour la parole, la transcription en temps réel, la voix en temps réel, la compréhension des médias, la génération d’images, la génération de musique, la génération de vidéo, la récupération web, la recherche web et la propriété des outils. | +| `channelConfigs` | Non | `Record` | Métadonnées de configuration de canal possédées par le manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement de l’exécution. | +| `skills` | Non | `string[]` | Répertoires Skills à charger, relatifs à la racine du plugin. | +| `name` | Non | `string` | Nom lisible du plugin. | +| `description` | Non | `string` | Résumé court affiché dans les surfaces de plugin. | +| `version` | Non | `string` | Version informative du plugin. | +| `uiHints` | Non | `Record` | Libellés d’interface, espaces réservés et indices de sensibilité pour les champs de configuration. | -## Référence `providerAuthChoices` +## Référence de `providerAuthChoices` -Chaque entrée `providerAuthChoices` décrit un choix d’onboarding ou d’authentification. -OpenClaw lit cela avant le chargement du runtime du provider. +Chaque entrée `providerAuthChoices` décrit un choix d’intégration ou d’authentification. +OpenClaw lit ces informations avant le chargement de l’exécution du fournisseur. | Champ | Obligatoire | Type | Signification | | --------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Oui | `string` | ID du provider auquel ce choix appartient. | -| `method` | Oui | `string` | ID de la méthode d’authentification vers laquelle dispatcher. | -| `choiceId` | Oui | `string` | ID stable de choix d’authentification utilisé par les flux d’onboarding et CLI. | -| `choiceLabel` | Non | `string` | Libellé destiné à l’utilisateur. S’il est omis, OpenClaw revient à `choiceId`. | +| `provider` | Oui | `string` | ID du fournisseur auquel appartient ce choix. | +| `method` | Oui | `string` | ID de méthode d’authentification vers lequel dispatcher. | +| `choiceId` | Oui | `string` | ID stable de choix d’authentification utilisé par les flux d’intégration et CLI. | +| `choiceLabel` | Non | `string` | Libellé visible par l’utilisateur. S’il est omis, OpenClaw utilise `choiceId` comme repli. | | `choiceHint` | Non | `string` | Court texte d’aide pour le sélecteur. | -| `assistantPriority` | Non | `number` | Les valeurs les plus faibles sont triées plus tôt dans les sélecteurs interactifs pilotés par l’assistant. | -| `assistantVisibility` | Non | `"visible"` \| `"manual-only"` | Masque le choix dans les sélecteurs de l’assistant tout en autorisant la sélection manuelle via CLI. | -| `deprecatedChoiceIds` | Non | `string[]` | IDs hérités de choix qui doivent rediriger les utilisateurs vers ce choix de remplacement. | +| `assistantPriority` | Non | `number` | Les valeurs plus basses sont triées plus tôt dans les sélecteurs interactifs pilotés par l’assistant. | +| `assistantVisibility` | Non | `"visible"` \| `"manual-only"` | Masque ce choix dans les sélecteurs de l’assistant tout en autorisant sa sélection manuelle via la CLI. | +| `deprecatedChoiceIds` | Non | `string[]` | IDs de choix hérités qui doivent rediriger les utilisateurs vers ce choix de remplacement. | | `groupId` | Non | `string` | ID de groupe facultatif pour regrouper des choix liés. | -| `groupLabel` | Non | `string` | Libellé destiné à l’utilisateur pour ce groupe. | +| `groupLabel` | Non | `string` | Libellé visible par l’utilisateur pour ce groupe. | | `groupHint` | Non | `string` | Court texte d’aide pour le groupe. | -| `optionKey` | Non | `string` | Clé d’option interne pour les flux d’authentification simples à un seul flag. | -| `cliFlag` | Non | `string` | Nom du flag CLI, par exemple `--openrouter-api-key`. | +| `optionKey` | Non | `string` | Clé d’option interne pour les flux d’authentification simples à un seul drapeau. | +| `cliFlag` | Non | `string` | Nom du drapeau CLI, par exemple `--openrouter-api-key`. | | `cliOption` | Non | `string` | Forme complète de l’option CLI, par exemple `--openrouter-api-key `. | | `cliDescription` | Non | `string` | Description utilisée dans l’aide CLI. | -| `onboardingScopes` | Non | `Array<"text-inference" \| "image-generation">` | Sur quelles surfaces d’onboarding ce choix doit apparaître. S’il est omis, la valeur par défaut est `["text-inference"]`. | +| `onboardingScopes` | Non | `Array<"text-inference" \| "image-generation">` | Sur quelles surfaces d’intégration ce choix doit apparaître. Si omis, la valeur par défaut est `["text-inference"]`. | -## Référence `commandAliases` +## Référence de `commandAliases` -Utilisez `commandAliases` lorsqu’un plugin possède un nom de commande runtime que les utilisateurs peuvent -par erreur mettre dans `plugins.allow` ou essayer d’exécuter comme commande CLI racine. OpenClaw -utilise ces métadonnées pour les diagnostics sans importer le code runtime du plugin. +Utilisez `commandAliases` lorsqu’un plugin possède un nom de commande d’exécution que les utilisateurs peuvent +mettre par erreur dans `plugins.allow` ou essayer d’exécuter comme commande CLI racine. OpenClaw +utilise ces métadonnées pour les diagnostics sans importer le code d’exécution du plugin. ```json { @@ -196,22 +209,93 @@ utilise ces métadonnées pour les diagnostics sans importer le code runtime du } ``` -| Champ | Obligatoire | Type | Signification | -| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- | -| `name` | Oui | `string` | Nom de commande qui appartient à ce plugin. | +| Champ | Obligatoire | Type | Signification | +| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | +| `name` | Oui | `string` | Nom de commande qui appartient à ce plugin. | | `kind` | Non | `"runtime-slash"` | Marque l’alias comme une commande slash de chat plutôt qu’une commande CLI racine. | -| `cliCommand` | Non | `string` | Commande CLI racine liée à suggérer pour les opérations CLI, si elle existe. | +| `cliCommand` | Non | `string` | Commande CLI racine associée à suggérer pour les opérations CLI, si elle existe. | -## Référence `uiHints` +## Référence de `activation` -`uiHints` est une map des noms de champs de configuration vers de petites indications de rendu. +Utilisez `activation` lorsque le plugin peut déclarer à faible coût quels événements du plan de contrôle +doivent l’activer plus tard. + +Ce bloc contient uniquement des métadonnées. Il n’enregistre pas de comportement d’exécution, et il +ne remplace pas `register(...)`, `setupEntry` ou d’autres points d’entrée d’exécution/plugin. + +```json +{ + "activation": { + "onProviders": ["openai"], + "onCommands": ["models"], + "onChannels": ["web"], + "onRoutes": ["gateway-webhook"], + "onCapabilities": ["provider", "tool"] + } +} +``` + +| Champ | Obligatoire | Type | Signification | +| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------- | +| `onProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer ce plugin lorsqu’ils sont demandés. | +| `onCommands` | Non | `string[]` | IDs de commandes qui doivent activer ce plugin. | +| `onChannels` | Non | `string[]` | IDs de canaux qui doivent activer ce plugin. | +| `onRoutes` | Non | `string[]` | Types de routes qui doivent activer ce plugin. | +| `onCapabilities` | Non | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Indices généraux de capacités utilisés par la planification d’activation du plan de contrôle. | + +## Référence de `setup` + +Utilisez `setup` lorsque les surfaces de configuration et d’intégration ont besoin de métadonnées légères appartenant au plugin +avant le chargement de l’exécution. + +```json +{ + "setup": { + "providers": [ + { + "id": "openai", + "authMethods": ["api-key"], + "envVars": ["OPENAI_API_KEY"] + } + ], + "cliBackends": ["openai-cli"], + "configMigrations": ["legacy-openai-auth"], + "requiresRuntime": false + } +} +``` + +Le champ `cliBackends` de niveau supérieur reste valide et continue de décrire les +backends d’inférence CLI. `setup.cliBackends` est la surface de descripteur spécifique à la configuration pour +les flux du plan de contrôle/de configuration qui doivent rester purement basés sur des métadonnées. + +### Référence de `setup.providers` + +| Champ | Obligatoire | Type | Signification | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | +| `id` | Oui | `string` | ID du fournisseur exposé pendant la configuration ou l’intégration. | +| `authMethods` | Non | `string[]` | IDs de méthodes de configuration/authentification que ce fournisseur prend en charge sans charger l’exécution complète. | +| `envVars` | Non | `string[]` | Variables d’environnement que les surfaces génériques de configuration/statut peuvent vérifier avant le chargement de l’exécution du plugin. | + +### Champs de `setup` + +| Champ | Obligatoire | Type | Signification | +| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------- | +| `providers` | Non | `object[]` | Descripteurs de configuration de fournisseur exposés pendant la configuration et l’intégration. | +| `cliBackends` | Non | `string[]` | IDs de backend disponibles au moment de la configuration sans activation complète de l’exécution. | +| `configMigrations` | Non | `string[]` | IDs de migration de configuration appartenant à la surface de configuration de ce plugin. | +| `requiresRuntime` | Non | `boolean` | Indique si la configuration nécessite encore l’exécution du plugin après la recherche du descripteur. | + +## Référence de `uiHints` + +`uiHints` est une map des noms de champs de configuration vers de petits indices de rendu. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Clé API", + "help": "Utilisée pour les requêtes OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -219,21 +303,21 @@ utilise ces métadonnées pour les diagnostics sans importer le code runtime du } ``` -Chaque indication de champ peut inclure : +Chaque indice de champ peut inclure : -| Champ | Type | Signification | -| ------------- | ---------- | ------------------------------------------ | -| `label` | `string` | Libellé du champ destiné à l’utilisateur. | -| `help` | `string` | Court texte d’aide. | -| `tags` | `string[]` | Tags UI facultatifs. | -| `advanced` | `boolean` | Marque le champ comme avancé. | -| `sensitive` | `boolean` | Marque le champ comme secret ou sensible. | -| `placeholder` | `string` | Texte de placeholder pour les champs de formulaire. | +| Champ | Type | Signification | +| ------------- | ---------- | -------------------------------------- | +| `label` | `string` | Libellé du champ visible par l’utilisateur. | +| `help` | `string` | Court texte d’aide. | +| `tags` | `string[]` | Étiquettes d’interface facultatives. | +| `advanced` | `boolean` | Marque le champ comme avancé. | +| `sensitive` | `boolean` | Marque le champ comme secret ou sensible. | +| `placeholder` | `string` | Texte d’espace réservé pour les champs de formulaire. | -## Référence `contracts` +## Référence de `contracts` -Utilisez `contracts` uniquement pour les métadonnées statiques de propriété des capacités que OpenClaw peut -lire sans importer le runtime du plugin. +Utilisez `contracts` uniquement pour les métadonnées statiques de propriété de capacités qu’OpenClaw peut +lire sans importer l’exécution du plugin. ```json { @@ -253,21 +337,22 @@ lire sans importer le runtime du plugin. Chaque liste est facultative : -| Champ | Type | Signification | -| -------------------------------- | ---------- | --------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs de providers vocaux possédés par ce plugin. | -| `realtimeTranscriptionProviders` | `string[]` | IDs de providers de transcription en temps réel possédés par ce plugin. | -| `realtimeVoiceProviders` | `string[]` | IDs de providers de voix en temps réel possédés par ce plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs de providers de compréhension des médias possédés par ce plugin. | -| `imageGenerationProviders` | `string[]` | IDs de providers de génération d’images possédés par ce plugin. | -| `videoGenerationProviders` | `string[]` | IDs de providers de génération de vidéo possédés par ce plugin. | -| `webFetchProviders` | `string[]` | IDs de providers de récupération web possédés par ce plugin. | -| `webSearchProviders` | `string[]` | IDs de providers de recherche web possédés par ce plugin. | -| `tools` | `string[]` | Noms d’outils d’agent possédés par ce plugin pour les vérifications de contrat des bundles. | +| Champ | Type | Signification | +| -------------------------------- | ---------- | ------------------------------------------------------------- | +| `speechProviders` | `string[]` | IDs des fournisseurs de parole appartenant à ce plugin. | +| `realtimeTranscriptionProviders` | `string[]` | IDs des fournisseurs de transcription en temps réel appartenant à ce plugin. | +| `realtimeVoiceProviders` | `string[]` | IDs des fournisseurs de voix en temps réel appartenant à ce plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs des fournisseurs de compréhension des médias appartenant à ce plugin. | +| `imageGenerationProviders` | `string[]` | IDs des fournisseurs de génération d’images appartenant à ce plugin. | +| `videoGenerationProviders` | `string[]` | IDs des fournisseurs de génération de vidéo appartenant à ce plugin. | +| `webFetchProviders` | `string[]` | IDs des fournisseurs de récupération web appartenant à ce plugin. | +| `webSearchProviders` | `string[]` | IDs des fournisseurs de recherche web appartenant à ce plugin. | +| `tools` | `string[]` | Noms d’outils d’agent appartenant à ce plugin pour les vérifications de contrats groupés. | -## Référence `channelConfigs` +## Référence de `channelConfigs` -Utilisez `channelConfigs` lorsqu’un plugin de canal a besoin de métadonnées de configuration peu coûteuses avant le chargement du runtime. +Utilisez `channelConfigs` lorsqu’un plugin de canal a besoin de métadonnées de configuration légères avant +le chargement de l’exécution. ```json { @@ -282,12 +367,12 @@ Utilisez `channelConfigs` lorsqu’un plugin de canal a besoin de métadonnées }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL du homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Connexion au homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -296,17 +381,18 @@ Utilisez `channelConfigs` lorsqu’un plugin de canal a besoin de métadonnées Chaque entrée de canal peut inclure : -| Champ | Type | Signification | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | -| `schema` | `object` | Schéma JSON pour `channels.`. Obligatoire pour chaque entrée de configuration de canal déclarée. | -| `uiHints` | `Record` | Libellés UI/placeholders/indications de sensibilité facultatifs pour cette section de configuration de canal. | -| `label` | `string` | Libellé du canal fusionné dans les surfaces de sélection et d’inspection lorsque les métadonnées runtime ne sont pas prêtes. | -| `description` | `string` | Brève description du canal pour les surfaces d’inspection et de catalogue. | -| `preferOver` | `string[]` | IDs de plugins hérités ou à priorité inférieure que ce canal doit dépasser dans les surfaces de sélection. | +| Champ | Type | Signification | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| `schema` | `object` | Schéma JSON pour `channels.`. Obligatoire pour chaque entrée déclarée de configuration de canal. | +| `uiHints` | `Record` | Libellés d’interface, espaces réservés et indices de sensibilité facultatifs pour cette section de configuration de canal. | +| `label` | `string` | Libellé du canal fusionné dans les surfaces de sélecteur et d’inspection lorsque les métadonnées d’exécution ne sont pas prêtes. | +| `description` | `string` | Brève description du canal pour les surfaces d’inspection et de catalogue. | +| `preferOver` | `string[]` | IDs de plugins hérités ou de priorité inférieure que ce canal doit surpasser dans les surfaces de sélection. | -## Référence `modelSupport` +## Référence de `modelSupport` -Utilisez `modelSupport` lorsque OpenClaw doit déduire votre plugin provider à partir d’IDs de modèles abrégés comme `gpt-5.4` ou `claude-sonnet-4.6` avant le chargement du runtime du plugin. +Utilisez `modelSupport` lorsqu’OpenClaw doit déduire votre plugin fournisseur à partir +d’IDs de modèles abrégés comme `gpt-5.4` ou `claude-sonnet-4.6` avant le chargement de l’exécution du plugin. ```json { @@ -319,65 +405,74 @@ Utilisez `modelSupport` lorsque OpenClaw doit déduire votre plugin provider à OpenClaw applique cet ordre de priorité : -- les références explicites `provider/model` utilisent les métadonnées de manifeste `providers` du propriétaire -- `modelPatterns` est prioritaire sur `modelPrefixes` -- si un plugin non bundle et un plugin bundle correspondent tous deux, le plugin non bundle l’emporte -- l’ambiguïté restante est ignorée jusqu’à ce que l’utilisateur ou la configuration spécifie un provider +- les références explicites `provider/model` utilisent les métadonnées `providers` du manifeste propriétaire +- `modelPatterns` ont priorité sur `modelPrefixes` +- si un plugin non groupé et un plugin groupé correspondent tous deux, le plugin non groupé + l’emporte +- les ambiguïtés restantes sont ignorées jusqu’à ce que l’utilisateur ou la configuration spécifie un fournisseur Champs : -| Champ | Type | Signification | -| --------------- | ---------- | --------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Préfixes comparés avec `startsWith` aux IDs de modèles abrégés. | +| Champ | Type | Signification | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Préfixes comparés avec `startsWith` aux IDs de modèles abrégés. | | `modelPatterns` | `string[]` | Sources regex comparées aux IDs de modèles abrégés après suppression du suffixe de profil. | -Les clés héritées de capacités au niveau supérieur sont obsolètes. Utilisez `openclaw doctor --fix` pour +Les clés de capacité héritées au niveau supérieur sont obsolètes. Utilisez `openclaw doctor --fix` pour déplacer `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` et `webSearchProviders` sous `contracts` ; le chargement normal -du manifeste ne traite plus ces champs de premier niveau comme +du manifeste ne traite plus ces champs de niveau supérieur comme de la propriété de capacités. ## Manifeste versus package.json -Les deux fichiers remplissent des rôles différents : +Les deux fichiers ont des rôles différents : -| Fichier | Utilisation | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Découverte, validation de configuration, métadonnées de choix d’authentification et indications UI qui doivent exister avant l’exécution du code du plugin | -| `package.json` | Métadonnées npm, installation des dépendances et bloc `openclaw` utilisé pour les points d’entrée, la validation d’installation, la configuration ou les métadonnées de catalogue | +| Fichier | À utiliser pour | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | La découverte, la validation de la configuration, les métadonnées de choix d’authentification et les indices d’interface qui doivent exister avant l’exécution du code du plugin | +| `package.json` | Les métadonnées npm, l’installation des dépendances, et le bloc `openclaw` utilisé pour les points d’entrée, le contrôle d’installation, la configuration ou les métadonnées de catalogue | Si vous ne savez pas où placer une métadonnée, utilisez cette règle : -- si OpenClaw doit la connaître avant de charger le code du plugin, mettez-la dans `openclaw.plugin.json` -- si elle concerne le packaging, les fichiers d’entrée ou le comportement d’installation npm, mettez-la dans `package.json` +- si OpenClaw doit la connaître avant de charger le code du plugin, placez-la dans `openclaw.plugin.json` +- si elle concerne le packaging, les fichiers de point d’entrée ou le comportement d’installation npm, placez-la dans `package.json` -### Champs `package.json` qui affectent la découverte +### Champs de `package.json` qui affectent la découverte -Certaines métadonnées de plugin avant runtime vivent intentionnellement dans `package.json` sous le bloc +Certaines métadonnées de plugin avant exécution vivent intentionnellement dans `package.json` sous le bloc `openclaw` plutôt que dans `openclaw.plugin.json`. Exemples importants : -| Champ | Signification | -| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Déclare les points d’entrée des plugins natifs. | -| `openclaw.setupEntry` | Point d’entrée léger réservé à la configuration, utilisé pendant l’onboarding et le démarrage différé des canaux. | -| `openclaw.channel` | Métadonnées légères du catalogue de canaux comme les libellés, chemins de documentation, alias et texte de sélection. | -| `openclaw.channel.configuredState` | Métadonnées légères du vérificateur d’état configuré pouvant répondre à « une configuration uniquement par variables d’environnement existe-t-elle déjà ? » sans charger tout le runtime du canal. | -| `openclaw.channel.persistedAuthState` | Métadonnées légères du vérificateur d’authentification persistée pouvant répondre à « y a-t-il déjà quelque chose de connecté ? » sans charger tout le runtime du canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indications d’installation/mise à jour pour les plugins bundles et publiés en externe. | -| `openclaw.install.defaultChoice` | Chemin d’installation préféré lorsque plusieurs sources d’installation sont disponibles. | -| `openclaw.install.minHostVersion` | Version minimale prise en charge de l’hôte OpenClaw, en utilisant un plancher semver comme `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Autorise un chemin étroit de récupération par réinstallation de plugin bundle lorsque la configuration est invalide. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permet aux surfaces de canal réservées à la configuration de se charger avant le plugin de canal complet au démarrage. | +| Champ | Signification | +| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Déclare les points d’entrée de plugins natifs. | +| `openclaw.setupEntry` | Point d’entrée léger réservé à la configuration utilisé pendant l’intégration et le démarrage différé des canaux. | +| `openclaw.channel` | Métadonnées légères du catalogue de canaux comme les libellés, les chemins de documentation, les alias et le texte de sélection. | +| `openclaw.channel.configuredState` | Métadonnées légères de vérification de l’état configuré qui peuvent répondre à « une configuration basée uniquement sur l’environnement existe-t-elle déjà ? » sans charger l’exécution complète du canal. | +| `openclaw.channel.persistedAuthState` | Métadonnées légères de vérification d’authentification persistée qui peuvent répondre à « quelque chose est-il déjà connecté ? » sans charger l’exécution complète du canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indices d’installation/mise à jour pour les plugins groupés et publiés en externe. | +| `openclaw.install.defaultChoice` | Chemin d’installation préféré lorsque plusieurs sources d’installation sont disponibles. | +| `openclaw.install.minHostVersion` | Version minimale prise en charge de l’hôte OpenClaw, en utilisant un plancher semver comme `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Autorise un chemin de récupération de réinstallation étroit pour les plugins groupés lorsque la configuration est invalide. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permet aux surfaces de canal réservées à la configuration de se charger avant le plugin de canal complet pendant le démarrage. | -`openclaw.install.minHostVersion` est appliqué pendant l’installation et le chargement du registre de manifestes. Les valeurs invalides sont rejetées ; les valeurs plus récentes mais valides ignorent le plugin sur les hôtes plus anciens. +`openclaw.install.minHostVersion` est appliqué pendant l’installation et lors du chargement du registre +des manifestes. Les valeurs invalides sont rejetées ; les valeurs valides mais plus récentes ignorent le +plugin sur les hôtes plus anciens. -`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il ne rend pas installables des configurations arbitrairement cassées. Aujourd’hui, il permet seulement aux flux d’installation de se remettre de certains échecs hérités de mise à niveau de plugin bundle, comme un chemin de plugin bundle manquant ou une entrée `channels.` obsolète pour ce même plugin bundle. Les erreurs de configuration non liées bloquent toujours l’installation et orientent les opérateurs vers `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il +ne rend pas installables des configurations cassées arbitraires. Aujourd’hui, il permet seulement aux flux d’installation +de récupérer de certains échecs obsolètes de mise à niveau de plugins groupés, comme un +chemin de plugin groupé manquant ou une entrée `channels.` obsolète pour ce même +plugin groupé. Les erreurs de configuration sans rapport bloquent toujours l’installation et redirigent les opérateurs +vers `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` est une métadonnée de package pour un minuscule module de vérification : +`openclaw.channel.persistedAuthState` est une métadonnée de package pour un petit +module de vérification : ```json { @@ -393,9 +488,13 @@ Exemples importants : } ``` -Utilisez-le lorsque les flux de configuration, doctor ou d’état configuré ont besoin d’une sonde d’authentification oui/non peu coûteuse avant le chargement du plugin de canal complet. L’export cible doit être une petite fonction qui lit uniquement l’état persistant ; ne le faites pas passer par le barrel runtime complet du canal. +Utilisez-le lorsque les flux de configuration, doctor ou d’état configuré ont besoin d’une +vérification légère oui/non de l’authentification avant le chargement du plugin de canal complet. L’export ciblé doit être une petite +fonction qui lit uniquement l’état persisté ; ne le faites pas passer par le barrel complet d’exécution du +canal. -`openclaw.channel.configuredState` suit la même forme pour des vérifications légères d’état configuré uniquement par variables d’environnement : +`openclaw.channel.configuredState` suit la même forme pour des vérifications légères de l’état +configuré basées uniquement sur l’environnement : ```json { @@ -411,43 +510,65 @@ Utilisez-le lorsque les flux de configuration, doctor ou d’état configuré on } ``` -Utilisez-le lorsqu’un canal peut répondre à l’état configuré à partir de variables d’environnement ou d’autres petites entrées non runtime. Si la vérification nécessite une résolution complète de la configuration ou le vrai runtime du canal, gardez cette logique dans le hook `config.hasConfiguredState` du plugin à la place. +Utilisez-le lorsqu’un canal peut répondre à l’état configuré à partir de l’environnement ou d’autres petites +entrées hors exécution. Si la vérification nécessite la résolution complète de la configuration ou la véritable +exécution du canal, conservez cette logique dans le hook `config.hasConfiguredState` +du plugin. ## Exigences du schéma JSON - **Chaque plugin doit fournir un schéma JSON**, même s’il n’accepte aucune configuration. - Un schéma vide est acceptable (par exemple, `{ "type": "object", "additionalProperties": false }`). -- Les schémas sont validés au moment de la lecture/écriture de la configuration, pas au runtime. +- Les schémas sont validés au moment de la lecture/écriture de la configuration, pas à l’exécution. ## Comportement de validation -- Les clés `channels.*` inconnues sont des **erreurs**, sauf si l’ID du canal est déclaré par un manifeste de plugin. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` et `plugins.slots.*` doivent référencer des IDs de plugin **découvrables**. Les IDs inconnus sont des **erreurs**. -- Si un plugin est installé mais possède un manifeste ou un schéma cassé ou manquant, la validation échoue et Doctor signale l’erreur du plugin. -- Si une configuration de plugin existe mais que le plugin est **désactivé**, la configuration est conservée et un **avertissement** est affiché dans Doctor + les logs. +- Les clés inconnues `channels.*` sont des **erreurs**, sauf si l’ID du canal est déclaré par + un manifeste de plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` et `plugins.slots.*` + doivent référencer des IDs de plugin **détectables**. Les IDs inconnus sont des **erreurs**. +- Si un plugin est installé mais possède un manifeste ou un schéma manquant ou cassé, + la validation échoue et Doctor signale l’erreur du plugin. +- Si la configuration du plugin existe mais que le plugin est **désactivé**, la configuration est conservée et + un **avertissement** est affiché dans Doctor + les journaux. -Voir [Référence de configuration](/fr/gateway/configuration) pour le schéma complet `plugins.*`. +Consultez la [Référence de configuration](/fr/gateway/configuration) pour le schéma complet de `plugins.*`. ## Remarques -- Le manifeste est **obligatoire pour les plugins natifs OpenClaw**, y compris les chargements depuis le système de fichiers local. -- Le runtime charge toujours le module du plugin séparément ; le manifeste sert uniquement à la découverte + validation. -- Les manifestes natifs sont analysés avec JSON5, donc les commentaires, virgules terminales et clés non entre guillemets sont acceptés tant que la valeur finale reste un objet. -- Seuls les champs documentés du manifeste sont lus par le chargeur de manifeste. Évitez d’ajouter ici des clés de premier niveau personnalisées. -- `providerAuthEnvVars` est le chemin de métadonnées peu coûteux pour les sondes d’authentification, la validation des marqueurs d’environnement et les surfaces similaires d’authentification provider qui ne doivent pas démarrer le runtime du plugin uniquement pour inspecter les noms d’environnement. -- `providerAuthAliases` permet à des variantes de provider de réutiliser les variables d’environnement d’authentification, profils d’authentification, authentification basée sur la configuration et choix d’onboarding par clé API d’un autre provider sans coder en dur cette relation dans le cœur. -- `channelEnvVars` est le chemin de métadonnées peu coûteux pour le repli sur l’environnement shell, les invites de configuration et les surfaces de canal similaires qui ne doivent pas démarrer le runtime du plugin uniquement pour inspecter les noms d’environnement. -- `providerAuthChoices` est le chemin de métadonnées peu coûteux pour les sélecteurs de choix d’authentification, la résolution `--auth-choice`, le mapping de provider préféré et l’enregistrement simple des flags CLI d’onboarding avant le chargement du runtime du provider. Pour les métadonnées d’assistant runtime qui nécessitent du code provider, voir [Hooks runtime provider](/fr/plugins/architecture#provider-runtime-hooks). -- Les types de plugins exclusifs sont sélectionnés via `plugins.slots.*`. +- Le manifeste est **obligatoire pour les plugins OpenClaw natifs**, y compris les chargements depuis le système de fichiers local. +- L’exécution charge toujours séparément le module du plugin ; le manifeste sert uniquement à la + découverte + validation. +- Les manifestes natifs sont analysés avec JSON5, donc les commentaires, virgules finales et + clés non entre guillemets sont acceptés tant que la valeur finale reste un objet. +- Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d’ajouter + ici des clés personnalisées de niveau supérieur. +- `providerAuthEnvVars` est le chemin léger de métadonnées pour les sondes d’authentification, la + validation des marqueurs d’environnement, et des surfaces similaires d’authentification fournisseur qui ne doivent pas démarrer l’exécution du plugin + simplement pour inspecter des noms de variables d’environnement. +- `providerAuthAliases` permet aux variantes de fournisseurs de réutiliser les variables d’environnement d’authentification, + les profils d’authentification, l’authentification fondée sur la configuration et le choix d’intégration par clé API d’un autre fournisseur + sans coder en dur cette relation dans le cœur. +- `channelEnvVars` est le chemin léger de métadonnées pour le repli sur les variables d’environnement du shell, les invites de configuration + et des surfaces de canaux similaires qui ne doivent pas démarrer l’exécution du plugin + simplement pour inspecter des noms de variables d’environnement. +- `providerAuthChoices` est le chemin léger de métadonnées pour les sélecteurs de choix d’authentification, + la résolution de `--auth-choice`, le mappage du fournisseur préféré et l’enregistrement simple des drapeaux CLI + avant le chargement de l’exécution du fournisseur. Pour les métadonnées d’assistant d’exécution + qui nécessitent le code du fournisseur, voir + [Hooks d’exécution du fournisseur](/fr/plugins/architecture#provider-runtime-hooks). +- Les types de plugin exclusifs sont sélectionnés via `plugins.slots.*`. - `kind: "memory"` est sélectionné par `plugins.slots.memory`. - `kind: "context-engine"` est sélectionné par `plugins.slots.contextEngine` (par défaut : `legacy` intégré). -- `channels`, `providers`, `cliBackends` et `skills` peuvent être omis lorsqu’un plugin n’en a pas besoin. -- Si votre plugin dépend de modules natifs, documentez les étapes de build et toute exigence d’allowlist du gestionnaire de paquets (par exemple, pnpm `allow-build-scripts` +- `channels`, `providers`, `cliBackends` et `skills` peuvent être omis lorsqu’un + plugin n’en a pas besoin. +- Si votre plugin dépend de modules natifs, documentez les étapes de compilation et toute + exigence de liste d’autorisation du gestionnaire de paquets (par exemple, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Liens associés +## Liens connexes -- [Créer des plugins](/fr/plugins/building-plugins) — démarrer avec les plugins +- [Créer des plugins](/fr/plugins/building-plugins) — bien démarrer avec les plugins - [Architecture des plugins](/fr/plugins/architecture) — architecture interne -- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence du SDK des plugins +- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence du SDK de plugin diff --git a/docs/fr/reference/rich-output-protocol.md b/docs/fr/reference/rich-output-protocol.md new file mode 100644 index 000000000..dfdf13444 --- /dev/null +++ b/docs/fr/reference/rich-output-protocol.md @@ -0,0 +1,60 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:53Z" + model: gpt-5.4 + provider: openai + source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035 + source_path: reference/rich-output-protocol.md + workflow: 15 +--- + +# Protocole de sortie enrichie + +La sortie de l’assistant peut inclure un petit ensemble de directives de livraison/rendu : + +- `MEDIA:` pour la livraison de pièces jointes +- `[[audio_as_voice]]` pour les indications de présentation audio +- `[[reply_to_current]]` / `[[reply_to:]]` pour les métadonnées de réponse +- `[embed ...]` pour le rendu enrichi dans l’interface de contrôle + +Ces directives sont distinctes. `MEDIA:` et les balises de réponse/voix restent des métadonnées de livraison ; `[embed ...]` est le chemin de rendu enrichi réservé au web. + +## `[embed ...]` + +`[embed ...]` est la seule syntaxe de rendu enrichi destinée aux agents pour l’interface de contrôle. + +Exemple autofermant : + +```text +[embed ref="cv_123" title="Status" /] +``` + +Règles : + +- `[view ...]` n’est plus valide pour les nouvelles sorties. +- Les shortcodes embed s’affichent uniquement dans la surface de message de l’assistant. +- Seuls les embeds adossés à une URL sont rendus. Utilisez `ref="..."` ou `url="..."`. +- Les shortcodes embed en HTML inline sous forme de bloc ne sont pas rendus. +- L’interface web supprime le shortcode du texte visible et rend l’embed en ligne. +- `MEDIA:` n’est pas un alias d’embed et ne doit pas être utilisé pour le rendu enrichi d’embed. + +## Forme de rendu stockée + +Le bloc de contenu normalisé/stocké de l’assistant est un élément structuré `canvas` : + +```json +{ + "type": "canvas", + "preview": { + "kind": "canvas", + "surface": "assistant_message", + "render": "url", + "viewId": "cv_123", + "url": "/__openclaw__/canvas/documents/cv_123/index.html", + "title": "Status", + "preferredHeight": 320 + } +} +``` + +Les blocs enrichis stockés/rendus utilisent directement cette forme `canvas`. `present_view` n’est pas reconnu. diff --git a/docs/fr/tools/video-generation.md b/docs/fr/tools/video-generation.md index 1fe0f8409..6c808b902 100644 --- a/docs/fr/tools/video-generation.md +++ b/docs/fr/tools/video-generation.md @@ -1,35 +1,34 @@ --- read_when: - - Générer des vidéos via l’agent - - Configuration des fournisseurs et modèles de génération vidéo + - Génération de vidéos via l’agent + - Configuration des fournisseurs et des modèles de génération de vidéos - Comprendre les paramètres de l’outil `video_generate` -summary: Générez des vidéos à partir de texte, d’images ou de vidéos existantes à l’aide de 12 backends de fournisseur -title: Génération vidéo +summary: Générez des vidéos à partir de texte, d’images ou de vidéos existantes à l’aide de 14 backends de fournisseur +title: Génération de vidéos x-i18n: - generated_at: "2026-04-11T02:48:15Z" + generated_at: "2026-04-11T15:16:00Z" model: gpt-5.4 provider: openai - source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245 + source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263 source_path: tools/video-generation.md workflow: 15 --- -# Génération vidéo +# Génération de vidéos -Les agents OpenClaw peuvent générer des vidéos à partir d’invites textuelles, d’images de référence ou de vidéos existantes. Douze backends de fournisseur sont pris en charge, chacun avec différentes options de modèle, modes d’entrée et ensembles de fonctionnalités. L’agent choisit automatiquement le bon fournisseur selon votre configuration et les clés API disponibles. +Les agents OpenClaw peuvent générer des vidéos à partir d’invites textuelles, d’images de référence ou de vidéos existantes. Quatorze backends de fournisseur sont pris en charge, chacun avec différentes options de modèle, modes d’entrée et ensembles de fonctionnalités. L’agent choisit automatiquement le bon fournisseur en fonction de votre configuration et des clés API disponibles. -L’outil `video_generate` n’apparaît que lorsqu’au moins un fournisseur de génération vidéo est disponible. Si vous ne le voyez pas dans les outils de votre agent, définissez une clé API de fournisseur ou configurez `agents.defaults.videoGenerationModel`. +L’outil `video_generate` n’apparaît que lorsqu’au moins un fournisseur de génération de vidéos est disponible. Si vous ne le voyez pas dans les outils de votre agent, définissez une clé API de fournisseur ou configurez `agents.defaults.videoGenerationModel`. -OpenClaw traite la génération vidéo selon trois modes d’exécution : +OpenClaw traite la génération de vidéos selon trois modes d’exécution : -- `generate` pour les requêtes texte-vers-vidéo sans média de référence -- `imageToVideo` lorsque la requête inclut une ou plusieurs images de référence -- `videoToVideo` lorsque la requête inclut une ou plusieurs vidéos de référence +- `generate` pour les demandes de texte vers vidéo sans média de référence +- `imageToVideo` lorsque la demande inclut une ou plusieurs images de référence +- `videoToVideo` lorsque la demande inclut une ou plusieurs vidéos de référence -Les fournisseurs peuvent prendre en charge n’importe quel sous-ensemble de ces modes. L’outil valide le -mode actif avant l’envoi et signale les modes pris en charge dans `action=list`. +Les fournisseurs peuvent prendre en charge n’importe quel sous-ensemble de ces modes. L’outil valide le mode actif avant l’envoi et signale les modes pris en charge dans `action=list`. ## Démarrage rapide @@ -47,31 +46,31 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. Demandez à l’agent : -> Générez une vidéo cinématique de 5 secondes d’un homard amical faisant du surf au coucher du soleil. +> Générez une vidéo cinématographique de 5 secondes d’un homard sympathique faisant du surf au coucher du soleil. L’agent appelle automatiquement `video_generate`. Aucune liste d’autorisation d’outils n’est nécessaire. ## Ce qui se passe lorsque vous générez une vidéo -La génération vidéo est asynchrone. Lorsque l’agent appelle `video_generate` dans une session : +La génération de vidéos est asynchrone. Lorsque l’agent appelle `video_generate` dans une session : -1. OpenClaw soumet la requête au fournisseur et renvoie immédiatement un identifiant de tâche. -2. Le fournisseur traite le travail en arrière-plan (généralement entre 30 secondes et 5 minutes selon le fournisseur et la résolution). -3. Lorsque la vidéo est prête, OpenClaw réveille la même session avec un événement interne d’achèvement. -4. L’agent republie la vidéo terminée dans la conversation d’origine. +1. OpenClaw envoie la demande au fournisseur et renvoie immédiatement un ID de tâche. +2. Le fournisseur traite le travail en arrière-plan (généralement de 30 secondes à 5 minutes selon le fournisseur et la résolution). +3. Lorsque la vidéo est prête, OpenClaw réactive la même session avec un événement interne de fin. +4. L’agent publie la vidéo terminée dans la conversation d’origine. -Pendant qu’une tâche est en cours, les appels `video_generate` en double dans la même session renvoient l’état actuel de la tâche au lieu de lancer une autre génération. Utilisez `openclaw tasks list` ou `openclaw tasks show ` pour vérifier la progression depuis la CLI. +Pendant qu’une tâche est en cours, les appels `video_generate` en double dans la même session renvoient l’état actuel de la tâche au lieu de démarrer une autre génération. Utilisez `openclaw tasks list` ou `openclaw tasks show ` pour vérifier la progression depuis la CLI. -En dehors des exécutions d’agent adossées à une session (par exemple, les invocations directes d’outils), l’outil se replie sur une génération en ligne et renvoie le chemin final du média dans le même tour. +En dehors des exécutions d’agent adossées à une session (par exemple, des invocations directes d’outils), l’outil revient à une génération en ligne et renvoie le chemin final du média dans le même tour. -### Cycle de vie de la tâche +### Cycle de vie d’une tâche -Chaque requête `video_generate` passe par quatre états : +Chaque demande `video_generate` passe par quatre états : 1. **queued** -- tâche créée, en attente que le fournisseur l’accepte. -2. **running** -- le fournisseur traite la tâche (généralement entre 30 secondes et 5 minutes selon le fournisseur et la résolution). -3. **succeeded** -- vidéo prête ; l’agent se réveille et la publie dans la conversation. -4. **failed** -- erreur du fournisseur ou délai d’expiration ; l’agent se réveille avec les détails de l’erreur. +2. **running** -- le fournisseur traite la demande (généralement de 30 secondes à 5 minutes selon le fournisseur et la résolution). +3. **succeeded** -- vidéo prête ; l’agent se réactive et la publie dans la conversation. +4. **failed** -- erreur du fournisseur ou expiration du délai ; l’agent se réactive avec les détails de l’erreur. Vérifiez l’état depuis la CLI : @@ -81,49 +80,49 @@ openclaw tasks show openclaw tasks cancel ``` -Prévention des doublons : si une tâche vidéo est déjà `queued` ou `running` pour la session en cours, `video_generate` renvoie l’état de la tâche existante au lieu d’en démarrer une nouvelle. Utilisez `action: "status"` pour vérifier explicitement sans déclencher une nouvelle génération. +Prévention des doublons : si une tâche vidéo est déjà `queued` ou `running` pour la session actuelle, `video_generate` renvoie l’état de la tâche existante au lieu d’en démarrer une nouvelle. Utilisez `action: "status"` pour vérifier explicitement sans déclencher une nouvelle génération. ## Fournisseurs pris en charge -| Fournisseur | Modèle par défaut | Texte | Réf image | Réf vidéo | Clé API | -| ----------- | ------------------------------- | ----- | ----------------- | ---------------- | ----------------------------------------- | -| Alibaba | `wan2.6-t2v` | Oui | Oui (URL distante) | Oui (URL distante) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Oui | 1 image | Non | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Oui | 1 image | Non | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Oui | 1 image | Non | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Oui | 1 image | 1 vidéo | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Oui | 1 image | Non | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Oui | 1 image | 1 vidéo | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Oui | Oui (URL distante) | Oui (URL distante) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Oui | 1 image | 1 vidéo | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Oui | 1 image | Non | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Oui | 1 image (`kling`) | Non | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Oui | 1 image | 1 vidéo | `XAI_API_KEY` | +| Fournisseur | Modèle par défaut | Texte | Image de réf. | Vidéo de réf. | Clé API | +| --------------------- | ------------------------------- | ----- | --------------------------------------------------- | ---------------- | ----------------------------------------- | +| Alibaba | `wan2.6-t2v` | Oui | Oui (URL distante) | Oui (URL distante) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | Oui | Jusqu’à 2 images (modèles I2V uniquement ; première + dernière image) | Non | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Oui | Jusqu’à 2 images (première + dernière image via rôle) | Non | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Oui | Jusqu’à 9 images de référence | Jusqu’à 3 vidéos | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Oui | 1 image | Non | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Oui | 1 image | Non | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Oui | 1 image | 1 vidéo | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Oui | 1 image | Non | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Oui | 1 image | 1 vidéo | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Oui | Oui (URL distante) | Oui (URL distante) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Oui | 1 image | 1 vidéo | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Oui | 1 image | Non | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Oui | 1 image (`kling`) | Non | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Oui | 1 image | 1 vidéo | `XAI_API_KEY` | -Certains fournisseurs acceptent des variables d’environnement de clé API supplémentaires ou alternatives. Voir les [pages fournisseur](#related) individuelles pour plus de détails. +Certains fournisseurs acceptent des variables d’environnement de clé API supplémentaires ou alternatives. Consultez les [pages des fournisseurs](#related) correspondantes pour plus de détails. -Exécutez `video_generate action=list` pour inspecter les fournisseurs, modèles et -modes d’exécution disponibles à l’exécution. +Exécutez `video_generate action=list` pour inspecter à l’exécution les fournisseurs, modèles et modes d’exécution disponibles. -### Matrice de capacités déclarée +### Matrice des capacités déclarées -Il s’agit du contrat de mode explicite utilisé par `video_generate`, les tests de contrat -et le balayage direct partagé. +Il s’agit du contrat de mode explicite utilisé par `video_generate`, les tests de contrat et le balayage partagé en direct. -| Fournisseur | `generate` | `imageToVideo` | `videoToVideo` | Voies directes partagées aujourd’hui | -| ----------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite des URL vidéo distantes `http(s)` | -| BytePlus | Oui | Oui | Non | `generate`, `imageToVideo` | -| ComfyUI | Oui | Oui | Non | Pas dans le balayage partagé ; la couverture spécifique aux workflows vit avec les tests Comfy | -| fal | Oui | Oui | Non | `generate`, `imageToVideo` | -| Google | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré, car le balayage Gemini/Veo actuel adossé aux buffers n’accepte pas cette entrée | -| MiniMax | Oui | Oui | Non | `generate`, `imageToVideo` | +| Fournisseur | `generate` | `imageToVideo` | `videoToVideo` | Voies partagées en direct aujourd’hui | +| ----------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite des URL vidéo distantes `http(s)` | +| BytePlus | Oui | Oui | Non | `generate`, `imageToVideo` | +| ComfyUI | Oui | Oui | Non | Pas dans le balayage partagé ; la couverture spécifique au workflow se trouve dans les tests ComfyUI | +| fal | Oui | Oui | Non | `generate`, `imageToVideo` | +| Google | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré, car le balayage Gemini/Veo actuel adossé à un buffer n’accepte pas cette entrée | +| MiniMax | Oui | Oui | Non | `generate`, `imageToVideo` | | OpenAI | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` partagé ignoré, car ce chemin org/entrée nécessite actuellement un accès inpaint/remix côté fournisseur | -| Qwen | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite des URL vidéo distantes `http(s)` | -| Runway | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` s’exécute uniquement lorsque le modèle sélectionné est `runway/gen4_aleph` | -| Together | Oui | Oui | Non | `generate`, `imageToVideo` | -| Vydra | Oui | Oui | Non | `generate` ; `imageToVideo` partagé ignoré, car `veo3` intégré est texte seul et `kling` intégré nécessite une URL d’image distante | -| xAI | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite actuellement une URL MP4 distante | +| Qwen | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite des URL vidéo distantes `http(s)` | +| Runway | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` s’exécute uniquement lorsque le modèle sélectionné est `runway/gen4_aleph` | +| Together | Oui | Oui | Non | `generate`, `imageToVideo` | +| Vydra | Oui | Oui | Non | `generate` ; `imageToVideo` partagé ignoré, car le `veo3` groupé est uniquement textuel et le `kling` groupé nécessite une URL d’image distante | +| xAI | Oui | Oui | Oui | `generate`, `imageToVideo` ; `videoToVideo` ignoré, car ce fournisseur nécessite actuellement une URL MP4 distante | ## Paramètres de l’outil @@ -135,50 +134,71 @@ et le balayage direct partagé. ### Entrées de contenu -| Paramètre | Type | Description | -| --------- | -------- | ------------------------------------------- | -| `image` | string | Image de référence unique (chemin ou URL) | -| `images` | string[] | Plusieurs images de référence (jusqu’à 5) | -| `video` | string | Vidéo de référence unique (chemin ou URL) | -| `videos` | string[] | Plusieurs vidéos de référence (jusqu’à 4) | +| Paramètre | Type | Description | +| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `image` | string | Image de référence unique (chemin ou URL) | +| `images` | string[] | Plusieurs images de référence (jusqu’à 9) | +| `imageRoles`| string[] | Indications de rôle facultatives par position, parallèles à la liste d’images combinée. Valeurs canoniques : `first_frame`, `last_frame`, `reference_image` | +| `video` | string | Vidéo de référence unique (chemin ou URL) | +| `videos` | string[] | Plusieurs vidéos de référence (jusqu’à 4) | +| `videoRoles`| string[] | Indications de rôle facultatives par position, parallèles à la liste de vidéos combinée. Valeur canonique : `reference_video` | +| `audioRef` | string | Référence audio unique (chemin ou URL). Utilisée par exemple pour une musique de fond ou une référence vocale lorsque le fournisseur prend en charge les entrées audio | +| `audioRefs` | string[] | Plusieurs références audio (jusqu’à 3) | +| `audioRoles`| string[] | Indications de rôle facultatives par position, parallèles à la liste d’audios combinée. Valeur canonique : `reference_audio` | + +Les indications de rôle sont transmises telles quelles au fournisseur. Les valeurs canoniques proviennent de l’union `VideoGenerationAssetRole`, mais les fournisseurs peuvent accepter des chaînes de rôle supplémentaires. Les tableaux `*Roles` ne doivent pas comporter plus d’entrées que la liste de références correspondante ; les erreurs de décalage d’une position échouent avec un message clair. Utilisez une chaîne vide pour laisser un emplacement non défini. ### Contrôles de style -| Paramètre | Type | Description | -| ----------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | `480P`, `720P`, `768P` ou `1080P` | -| `durationSeconds` | number | Durée cible en secondes (arrondie à la valeur prise en charge la plus proche par le fournisseur) | -| `size` | string | Indication de taille lorsque le fournisseur la prend en charge | -| `audio` | boolean | Activer l’audio généré lorsque c’est pris en charge | -| `watermark` | boolean | Activer/désactiver le filigrane du fournisseur lorsque c’est pris en charge | +| Paramètre | Type | Description | +| ---------------- | ------- | -------------------------------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` ou `adaptive` | +| `resolution` | string | `480P`, `720P`, `768P` ou `1080P` | +| `durationSeconds`| number | Durée cible en secondes (arrondie à la valeur prise en charge la plus proche par le fournisseur) | +| `size` | string | Indication de taille lorsque le fournisseur la prend en charge | +| `audio` | boolean | Active l’audio généré dans la sortie lorsqu’il est pris en charge. Distinct de `audioRef*` (entrées) | +| `watermark` | boolean | Active ou désactive le filigrane du fournisseur lorsqu’il est pris en charge | + +`adaptive` est une valeur sentinelle spécifique au fournisseur : elle est transmise telle quelle aux fournisseurs qui déclarent `adaptive` dans leurs capacités (par exemple, BytePlus Seedance l’utilise pour détecter automatiquement le ratio à partir des dimensions de l’image d’entrée). Les fournisseurs qui ne la déclarent pas exposent la valeur via `details.ignoredOverrides` dans le résultat de l’outil afin que l’omission soit visible. ### Avancé -| Paramètre | Type | Description | -| ---------- | ------ | ------------------------------------------------ | -| `action` | string | `"generate"` (par défaut), `"status"` ou `"list"` | -| `model` | string | Remplacement fournisseur/modèle (par exemple `runway/gen4.5`) | -| `filename` | string | Indication de nom de fichier de sortie | +| Paramètre | Type | Description | +| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | `"generate"` (par défaut), `"status"` ou `"list"` | +| `model` | string | Remplacement du fournisseur/modèle (par exemple `runway/gen4.5`) | +| `filename` | string | Indication de nom de fichier de sortie | +| `providerOptions`| object | Options spécifiques au fournisseur sous forme d’objet JSON (par exemple `{"seed": 42, "draft": true}`). Les fournisseurs qui déclarent un schéma typé valident les clés et les types ; les clés inconnues ou incompatibilités font ignorer le candidat pendant le fallback. Les fournisseurs sans schéma déclaré reçoivent les options telles quelles. Exécutez `video_generate action=list` pour voir ce que chaque fournisseur accepte | -Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw normalise déjà la durée à la valeur la plus proche prise en charge par le fournisseur, et remappe aussi les indications de géométrie traduites comme la taille vers le ratio d’aspect lorsqu’un fournisseur de repli expose une surface de contrôle différente. Les remplacements réellement non pris en charge sont ignorés dans une logique de meilleur effort et signalés comme avertissements dans le résultat de l’outil. Les limites strictes de capacité (comme trop d’entrées de référence) échouent avant l’envoi. +Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw normalise déjà la durée à la valeur prise en charge la plus proche par le fournisseur, et remappe également les indications de géométrie traduites, comme size vers aspect ratio, lorsqu’un fournisseur de fallback expose une surface de contrôle différente. Les remplacements réellement non pris en charge sont ignorés dans la mesure du possible et signalés comme avertissements dans le résultat de l’outil. Les limites strictes de capacité (comme un trop grand nombre d’entrées de référence) échouent avant l’envoi. -Les résultats de l’outil indiquent les réglages appliqués. Lorsque OpenClaw remappe la durée ou la géométrie pendant le repli du fournisseur, les valeurs renvoyées `durationSeconds`, `size`, `aspectRatio` et `resolution` reflètent ce qui a été soumis, et `details.normalization` capture la traduction entre la valeur demandée et la valeur appliquée. +Les résultats de l’outil signalent les paramètres appliqués. Lorsque OpenClaw remappe la durée ou la géométrie pendant le fallback du fournisseur, les valeurs renvoyées `durationSeconds`, `size`, `aspectRatio` et `resolution` reflètent ce qui a été envoyé, et `details.normalization` capture la traduction entre la demande et l’application. -Les entrées de référence sélectionnent aussi le mode d’exécution : +Les entrées de référence sélectionnent également le mode d’exécution : - Aucun média de référence : `generate` - Toute image de référence : `imageToVideo` - Toute vidéo de référence : `videoToVideo` +- Les entrées audio de référence ne modifient pas le mode résolu ; elles s’appliquent par-dessus le mode sélectionné par les références d’image/vidéo, et ne fonctionnent qu’avec les fournisseurs qui déclarent `maxInputAudios` -Les références mixtes d’images et de vidéos ne constituent pas une surface de capacité partagée stable. -Préférez un seul type de référence par requête. +Les références d’image et de vidéo mixtes ne constituent pas une surface de capacité partagée stable. +Préférez un seul type de référence par demande. + +#### Fallback et options typées + +Certaines vérifications de capacité sont appliquées au niveau du fallback plutôt qu’à la frontière de l’outil, afin qu’une demande qui dépasse les limites du fournisseur principal puisse tout de même s’exécuter sur un fournisseur de fallback compatible : + +- Si le candidat actif ne déclare pas `maxInputAudios` (ou le déclare à `0`), il est ignoré lorsque la demande contient des références audio, et le candidat suivant est essayé. +- Si `maxDurationSeconds` du candidat actif est inférieur à la valeur demandée dans `durationSeconds` et que le candidat ne déclare pas de liste `supportedDurationSeconds`, il est ignoré. +- Si la demande contient `providerOptions` et que le candidat actif déclare explicitement un schéma typé `providerOptions`, le candidat est ignoré lorsque les clés fournies ne figurent pas dans le schéma ou que les types de valeur ne correspondent pas. Les fournisseurs qui n’ont pas encore déclaré de schéma reçoivent les options telles quelles (transmission compatible avec l’existant). Un fournisseur peut explicitement refuser toutes les options de fournisseur en déclarant un schéma vide (`capabilities.providerOptions: {}`), ce qui provoque le même comportement d’ignorance qu’une incompatibilité de type. + +La première raison d’ignorance dans une demande est journalisée au niveau `warn` afin que les opérateurs voient quand leur fournisseur principal a été ignoré ; les ignorances suivantes sont journalisées au niveau `debug` pour éviter de surcharger les longues chaînes de fallback. Si tous les candidats sont ignorés, l’erreur agrégée inclut la raison d’ignorance de chacun. ## Actions -- **generate** (par défaut) -- créer une vidéo à partir de l’invite donnée et d’éventuelles entrées de référence. -- **status** -- vérifier l’état de la tâche vidéo en cours pour la session actuelle sans démarrer une autre génération. -- **list** -- afficher les fournisseurs, modèles et leurs capacités disponibles. +- **generate** (par défaut) -- crée une vidéo à partir de l’invite donnée et des entrées de référence facultatives. +- **status** -- vérifie l’état de la tâche vidéo en cours pour la session actuelle sans démarrer une autre génération. +- **list** -- affiche les fournisseurs, modèles et capacités disponibles. ## Sélection du modèle @@ -187,12 +207,11 @@ Lors de la génération d’une vidéo, OpenClaw résout le modèle dans cet ord 1. **Paramètre d’outil `model`** -- si l’agent en spécifie un dans l’appel. 2. **`videoGenerationModel.primary`** -- depuis la configuration. 3. **`videoGenerationModel.fallbacks`** -- essayés dans l’ordre. -4. **Détection automatique** -- utilise les fournisseurs qui disposent d’une authentification valide, en commençant par le fournisseur par défaut actuel, puis les autres fournisseurs par ordre alphabétique. +4. **Détection automatique** -- utilise les fournisseurs qui ont une authentification valide, en commençant par le fournisseur par défaut actuel, puis les fournisseurs restants par ordre alphabétique. Si un fournisseur échoue, le candidat suivant est essayé automatiquement. Si tous les candidats échouent, l’erreur inclut les détails de chaque tentative. -Définissez `agents.defaults.mediaGenerationAutoProviderFallback: false` si vous voulez que -la génération vidéo utilise uniquement les entrées explicites `model`, `primary` et `fallbacks`. +Définissez `agents.defaults.mediaGenerationAutoProviderFallback: false` si vous souhaitez que la génération de vidéos utilise uniquement les entrées explicites `model`, `primary` et `fallbacks`. ```json5 { @@ -207,56 +226,28 @@ la génération vidéo utilise uniquement les entrées explicites `model`, `prim } ``` -HeyGen video-agent sur fal peut être épinglé avec : - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", - }, - }, - }, -} -``` - -Seedance 2.0 sur fal peut être épinglé avec : - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", - }, - }, - }, -} -``` - ## Remarques sur les fournisseurs -| Fournisseur | Remarques | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Utilise le point de terminaison asynchrone DashScope/Model Studio. Les images et vidéos de référence doivent être des URL distantes `http(s)`. | -| BytePlus | Une seule image de référence. | -| ComfyUI | Exécution locale ou cloud pilotée par workflow. Prend en charge le texte-vers-vidéo et l’image-vers-vidéo via le graphe configuré. | -| fal | Utilise un flux adossé à une file d’attente pour les tâches longues. Une seule image de référence. Inclut les références de modèles HeyGen video-agent et Seedance 2.0 texte-vers-vidéo et image-vers-vidéo. | -| Google | Utilise Gemini/Veo. Prend en charge une image de référence ou une vidéo de référence. | -| MiniMax | Une seule image de référence. | -| OpenAI | Seul le remplacement `size` est transmis. Les autres remplacements de style (`aspectRatio`, `resolution`, `audio`, `watermark`) sont ignorés avec un avertissement. | -| Qwen | Même backend DashScope qu’Alibaba. Les entrées de référence doivent être des URL distantes `http(s)` ; les fichiers locaux sont rejetés dès le départ. | -| Runway | Prend en charge les fichiers locaux via des URI de données. Le mode vidéo-vers-vidéo nécessite `runway/gen4_aleph`. Les exécutions texte seul exposent les ratios `16:9` et `9:16`. | -| Together | Une seule image de référence. | -| Vydra | Utilise `https://www.vydra.ai/api/v1` directement pour éviter les redirections qui perdent l’authentification. `veo3` est intégré comme texte-vers-vidéo uniquement ; `kling` nécessite une URL d’image distante. | -| xAI | Prend en charge les flux texte-vers-vidéo, image-vers-vidéo et modification/extension de vidéo distante. | +| Fournisseur | Remarques | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Utilise le endpoint asynchrone DashScope/Model Studio. Les images et vidéos de référence doivent être des URL distantes `http(s)`. | +| BytePlus (1.0) | ID du fournisseur `byteplus`. Modèles : `seedance-1-0-pro-250528` (par défaut), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Les modèles T2V (`*-t2v-*`) n’acceptent pas les entrées d’image ; les modèles I2V et les modèles généraux `*-pro-*` prennent en charge une seule image de référence (première image). Passez l’image de manière positionnelle ou définissez `role: "first_frame"`. Les ID de modèle T2V sont automatiquement basculés vers la variante I2V correspondante lorsqu’une image est fournie. Clés `providerOptions` prises en charge : `seed` (number), `draft` (boolean, force le 480p), `camera_fixed` (boolean). | +| BytePlus Seedance 1.5 | Nécessite le plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID du fournisseur `byteplus-seedance15`. Modèle : `seedance-1-5-pro-251215`. Utilise l’API unifiée `content[]`. Prend en charge au maximum 2 images d’entrée (first_frame + last_frame). Toutes les entrées doivent être des URL distantes `https://`. Définissez `role: "first_frame"` / `"last_frame"` sur chaque image, ou passez les images de manière positionnelle. `aspectRatio: "adaptive"` détecte automatiquement le ratio à partir de l’image d’entrée. `audio: true` est mappé à `generate_audio`. `providerOptions.seed` (number) est transmis. | +| BytePlus Seedance 2.0 | Nécessite le plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID du fournisseur `byteplus-seedance2`. Modèles : `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Utilise l’API unifiée `content[]`. Prend en charge jusqu’à 9 images de référence, 3 vidéos de référence et 3 audios de référence. Toutes les entrées doivent être des URL distantes `https://`. Définissez `role` sur chaque ressource — valeurs prises en charge : `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` détecte automatiquement le ratio à partir de l’image d’entrée. `audio: true` est mappé à `generate_audio`. `providerOptions.seed` (number) est transmis. | +| ComfyUI | Exécution locale ou cloud pilotée par workflow. Prend en charge le texte vers vidéo et l’image vers vidéo via le graphe configuré. | +| fal | Utilise un flux adossé à une file d’attente pour les tâches longues. Une seule image de référence uniquement. | +| Google | Utilise Gemini/Veo. Prend en charge une image ou une vidéo de référence. | +| MiniMax | Une seule image de référence uniquement. | +| OpenAI | Seul le remplacement `size` est transmis. Les autres remplacements de style (`aspectRatio`, `resolution`, `audio`, `watermark`) sont ignorés avec un avertissement. | +| Qwen | Même backend DashScope qu’Alibaba. Les entrées de référence doivent être des URL distantes `http(s)` ; les fichiers locaux sont rejetés d’emblée. | +| Runway | Prend en charge les fichiers locaux via des URI de données. Le mode vidéo vers vidéo nécessite `runway/gen4_aleph`. Les exécutions texte uniquement exposent les ratios `16:9` et `9:16`. | +| Together | Une seule image de référence uniquement. | +| Vydra | Utilise directement `https://www.vydra.ai/api/v1` pour éviter les redirections qui suppriment l’authentification. `veo3` est groupé uniquement comme texte vers vidéo ; `kling` nécessite une URL d’image distante. | +| xAI | Prend en charge les flux texte vers vidéo, image vers vidéo, ainsi que les flux distants d’édition/extension de vidéo. | ## Modes de capacité des fournisseurs -Le contrat partagé de génération vidéo permet désormais aux fournisseurs de déclarer des -capacités spécifiques au mode au lieu de se limiter à des limites agrégées plates. Les nouvelles implémentations -de fournisseur doivent privilégier des blocs de mode explicites : +Le contrat partagé de génération de vidéos permet désormais aux fournisseurs de déclarer des capacités spécifiques à chaque mode, au lieu de se limiter à des limites agrégées à plat. Les nouvelles implémentations de fournisseurs doivent privilégier des blocs de mode explicites : ```typescript capabilities: { @@ -280,15 +271,11 @@ capabilities: { } ``` -Les champs agrégés plats tels que `maxInputImages` et `maxInputVideos` ne -suffisent pas à annoncer la prise en charge des modes de transformation. Les fournisseurs doivent déclarer -explicitement `generate`, `imageToVideo` et `videoToVideo` afin que les tests directs, -les tests de contrat et l’outil partagé `video_generate` puissent valider la prise en charge des modes -de manière déterministe. +Les champs agrégés à plat tels que `maxInputImages` et `maxInputVideos` ne suffisent pas à annoncer la prise en charge des modes de transformation. Les fournisseurs doivent déclarer explicitement `generate`, `imageToVideo` et `videoToVideo` afin que les tests en direct, les tests de contrat et l’outil partagé `video_generate` puissent valider la prise en charge des modes de manière déterministe. ## Tests en direct -Couverture en direct activable pour les fournisseurs intégrés partagés : +Couverture en direct sur activation pour les fournisseurs groupés partagés : ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -300,22 +287,19 @@ Wrapper du dépôt : pnpm test:live:media video ``` -Ce fichier direct charge les variables d’environnement manquantes des fournisseurs depuis `~/.profile`, privilégie -par défaut les clés API directes/d’environnement par rapport aux profils d’authentification stockés, et exécute les -modes déclarés qu’il peut tester en toute sécurité avec des médias locaux : +Ce fichier de test en direct charge les variables d’environnement de fournisseur manquantes depuis `~/.profile`, privilégie par défaut les clés API live/env par rapport aux profils d’authentification stockés, et exécute les modes déclarés qu’il peut tester en toute sécurité avec des médias locaux : - `generate` pour chaque fournisseur du balayage - `imageToVideo` lorsque `capabilities.imageToVideo.enabled` -- `videoToVideo` lorsque `capabilities.videoToVideo.enabled` et que le fournisseur/modèle - accepte une entrée vidéo locale adossée à un buffer dans le balayage partagé +- `videoToVideo` lorsque `capabilities.videoToVideo.enabled` et que le fournisseur/modèle accepte une entrée vidéo locale adossée à un buffer dans le balayage partagé -Aujourd’hui, la voie directe partagée `videoToVideo` couvre : +Aujourd’hui, la voie en direct partagée `videoToVideo` couvre : - `runway` uniquement lorsque vous sélectionnez `runway/gen4_aleph` ## Configuration -Définissez le modèle de génération vidéo par défaut dans votre configuration OpenClaw : +Définissez le modèle de génération de vidéos par défaut dans votre configuration OpenClaw : ```json5 { @@ -339,7 +323,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Liens connexes - [Vue d’ensemble des outils](/fr/tools) -- [Tâches en arrière-plan](/fr/automation/tasks) -- suivi des tâches pour la génération vidéo asynchrone +- [Tâches en arrière-plan](/fr/automation/tasks) -- suivi des tâches pour la génération asynchrone de vidéos - [Alibaba Model Studio](/fr/providers/alibaba) - [BytePlus](/fr/concepts/model-providers#byteplus-international) - [ComfyUI](/fr/providers/comfy)