diff --git a/docs/fr/channels/matrix.md b/docs/fr/channels/matrix.md index 110152fdb..a0596b15b 100644 --- a/docs/fr/channels/matrix.md +++ b/docs/fr/channels/matrix.md @@ -1,14 +1,14 @@ --- read_when: - Configurer Matrix dans OpenClaw - - Configurer le chiffrement de bout en bout et la vérification Matrix -summary: État de la prise en charge de Matrix, configuration et exemples de configuration + - Configuration du chiffrement de bout en bout et de la vérification Matrix +summary: Statut de prise en charge de Matrix, configuration initiale et exemples de configuration title: Matrix x-i18n: - generated_at: "2026-04-15T06:56:36Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 + source_hash: bd730bb9d0c8a548ee48b20931b3222e9aa1e6e95f1390b0c236645e03f3576d source_path: channels/matrix.md workflow: 15 --- @@ -20,19 +20,19 @@ Il utilise le `matrix-js-sdk` officiel et prend en charge les messages privés, ## Plugin intégré -Matrix est livré comme Plugin intégré dans les versions actuelles d’OpenClaw, donc les -builds packagées normales n’ont pas besoin d’une installation séparée. +Matrix est livré comme un Plugin intégré dans les versions actuelles d’OpenClaw, donc les +builds empaquetés normaux ne nécessitent pas d’installation séparée. -Si vous utilisez une build plus ancienne ou une installation personnalisée qui exclut Matrix, installez-le -manuellement : +Si vous utilisez une ancienne build ou une installation personnalisée qui exclut Matrix, installez-le +manuellement : -Installer depuis npm : +Installer depuis npm : ```bash openclaw plugins install @openclaw/matrix ``` -Installer depuis un checkout local : +Installer depuis un checkout local : ```bash openclaw plugins install ./path/to/local/matrix-plugin @@ -40,55 +40,55 @@ openclaw plugins install ./path/to/local/matrix-plugin Voir [Plugins](/fr/tools/plugin) pour le comportement des plugins et les règles d’installation. -## Configuration +## Configuration initiale -1. Assurez-vous que le Plugin Matrix est disponible. - - Les versions packagées actuelles d’OpenClaw l’intègrent déjà. - - Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus. +1. Assurez-vous que le plugin Matrix est disponible. + - Les versions empaquetées actuelles d’OpenClaw l’intègrent déjà. + - Les installations anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus. 2. Créez un compte Matrix sur votre homeserver. -3. Configurez `channels.matrix` avec soit : +3. Configurez `channels.matrix` avec soit : - `homeserver` + `accessToken`, soit - `homeserver` + `userId` + `password`. 4. Redémarrez la Gateway. 5. Démarrez un message privé avec le bot ou invitez-le dans un salon. - - Les nouvelles invitations Matrix ne fonctionnent que si `channels.matrix.autoJoin` les autorise. + - Les nouvelles invitations Matrix ne fonctionnent que lorsque `channels.matrix.autoJoin` les autorise. -Chemins de configuration interactifs : +Parcours de configuration interactifs : ```bash openclaw channels add openclaw configure --section channels ``` -L’assistant Matrix demande : +L’assistant Matrix demande : - l’URL du homeserver -- la méthode d’authentification : jeton d’accès ou mot de passe +- la méthode d’authentification : jeton d’accès ou mot de passe - l’ID utilisateur (authentification par mot de passe uniquement) - le nom d’appareil facultatif - s’il faut activer le chiffrement de bout en bout -- s’il faut configurer l’accès aux salons et la jonction automatique sur invitation +- s’il faut configurer l’accès aux salons et l’adhésion automatique aux invitations -Comportements clés de l’assistant : +Comportements clés de l’assistant : - Si des variables d’environnement d’authentification Matrix existent déjà et que ce compte n’a pas déjà une authentification enregistrée dans la config, l’assistant propose un raccourci env pour conserver l’authentification dans les variables d’environnement. -- Les noms de compte sont normalisés vers l’ID du compte. Par exemple, `Ops Bot` devient `ops-bot`. -- Les entrées de liste d’autorisation des messages privés acceptent directement `@user:server` ; les noms d’affichage ne fonctionnent que lorsqu’une recherche en direct dans l’annuaire trouve une seule correspondance exacte. -- Les entrées de liste d’autorisation des salons acceptent directement les ID et alias de salon. Préférez `!room:server` ou `#alias:server` ; les noms non résolus sont ignorés à l’exécution par la résolution de la liste d’autorisation. -- En mode liste d’autorisation pour la jonction automatique sur invitation, utilisez uniquement des cibles d’invitation stables : `!roomId:server`, `#alias:server` ou `*`. Les noms de salon simples sont rejetés. -- Pour résoudre les noms de salon avant l’enregistrement, utilisez `openclaw channels resolve --channel matrix "Project Room"`. +- Les noms de compte sont normalisés vers l’ID de compte. Par exemple, `Ops Bot` devient `ops-bot`. +- Les entrées de liste d’autorisation de messages privés acceptent directement `@user:server` ; les noms d’affichage ne fonctionnent que lorsqu’une recherche active dans l’annuaire trouve exactement une correspondance. +- Les entrées de liste d’autorisation de salon acceptent directement les ID et alias de salon. Préférez `!room:server` ou `#alias:server` ; les noms non résolus sont ignorés à l’exécution lors de la résolution de la liste d’autorisation. +- En mode de liste d’autorisation pour l’adhésion automatique aux invitations, utilisez uniquement des cibles d’invitation stables : `!roomId:server`, `#alias:server` ou `*`. Les noms de salon simples sont rejetés. +- Pour résoudre des noms de salon avant l’enregistrement, utilisez `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` vaut par défaut `off`. +`channels.matrix.autoJoin` est défini par défaut sur `off`. -Si vous ne le définissez pas, le bot ne rejoindra pas les salons invités ni les nouvelles invitations de type message privé ; il n’apparaîtra donc pas dans les nouveaux groupes ou messages privés invités, sauf si vous le faites rejoindre manuellement d’abord. +Si vous le laissez non défini, le bot ne rejoindra pas les salons invités ni les nouvelles invitations de type message privé ; il n’apparaîtra donc pas dans les nouveaux groupes ou messages privés sur invitation à moins que vous ne le fassiez rejoindre manuellement d’abord. -Définissez `autoJoin: "allowlist"` avec `autoJoinAllowlist` pour restreindre les invitations qu’il accepte, ou définissez `autoJoin: "always"` si vous voulez qu’il rejoigne toutes les invitations. +Définissez `autoJoin: "allowlist"` avec `autoJoinAllowlist` pour restreindre les invitations qu’il accepte, ou définissez `autoJoin: "always"` si vous voulez qu’il rejoigne chaque invitation. -En mode `allowlist`, `autoJoinAllowlist` n’accepte que `!roomId:server`, `#alias:server` ou `*`. +En mode `allowlist`, `autoJoinAllowlist` accepte uniquement `!roomId:server`, `#alias:server` ou `*`. -Exemple de liste d’autorisation : +Exemple de liste d’autorisation : ```json5 { @@ -106,7 +106,7 @@ Exemple de liste d’autorisation : } ``` -Rejoindre toutes les invitations : +Rejoindre toutes les invitations : ```json5 { @@ -118,7 +118,7 @@ Rejoindre toutes les invitations : } ``` -Configuration minimale basée sur un jeton : +Configuration minimale basée sur un jeton : ```json5 { @@ -133,7 +133,7 @@ Configuration minimale basée sur un jeton : } ``` -Configuration basée sur un mot de passe (le jeton est mis en cache après connexion) : +Configuration basée sur un mot de passe (le jeton est mis en cache après la connexion) : ```json5 { @@ -149,11 +149,11 @@ Configuration basée sur un mot de passe (le jeton est mis en cache après conne } ``` -Matrix stocke les identifiants mis en cache dans `~/.openclaw/credentials/matrix/`. -Le compte par défaut utilise `credentials.json` ; les comptes nommés utilisent `credentials-.json`. -Lorsque des identifiants mis en cache existent à cet emplacement, OpenClaw considère Matrix comme configuré pour la configuration, doctor et la découverte de l’état des canaux, même si l’authentification actuelle n’est pas définie directement dans la config. +Matrix stocke les informations d’identification mises en cache dans `~/.openclaw/credentials/matrix/`. +Le compte par défaut utilise `credentials.json` ; les comptes nommés utilisent `credentials-.json`. +Lorsque des informations d’identification mises en cache existent à cet emplacement, OpenClaw considère Matrix comme configuré pour la configuration initiale, doctor et la découverte de l’état des canaux, même si l’authentification actuelle n’est pas définie directement dans la config. -Équivalents en variables d’environnement (utilisés lorsque la clé de config n’est pas définie) : +Équivalents en variables d’environnement (utilisés lorsque la clé de config n’est pas définie) : - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -162,7 +162,7 @@ Lorsque des identifiants mis en cache existent à cet emplacement, OpenClaw cons - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Pour les comptes non par défaut, utilisez des variables d’environnement limitées au compte : +Pour les comptes autres que le compte par défaut, utilisez des variables d’environnement ciblées par compte : - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -171,24 +171,24 @@ Pour les comptes non par défaut, utilisez des variables d’environnement limit - `MATRIX__DEVICE_ID` - `MATRIX__DEVICE_NAME` -Exemple pour le compte `ops` : +Exemple pour le compte `ops` : - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -Pour l’ID de compte normalisé `ops-bot`, utilisez : +Pour l’ID de compte normalisé `ops-bot`, utilisez : - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix échappe la ponctuation dans les ID de compte afin d’éviter les collisions dans les variables d’environnement limitées au compte. +Matrix échappe la ponctuation dans les ID de compte afin d’éviter les collisions dans les variables d’environnement ciblées par compte. Par exemple, `-` devient `_X2D_`, donc `ops-prod` devient `MATRIX_OPS_X2D_PROD_*`. -L’assistant interactif ne propose le raccourci par variable d’environnement que lorsque ces variables d’environnement d’authentification sont déjà présentes et que le compte sélectionné n’a pas déjà une authentification Matrix enregistrée dans la config. +L’assistant interactif ne propose le raccourci de variable d’environnement que lorsque ces variables d’authentification sont déjà présentes et que le compte sélectionné n’a pas déjà une authentification Matrix enregistrée dans la config. ## Exemple de configuration -Voici une configuration de base pratique avec appairage des messages privés, liste d’autorisation des salons et chiffrement de bout en bout activé : +Voici une configuration de base pratique avec appairage des messages privés, liste d’autorisation des salons et chiffrement de bout en bout activé : ```json5 { @@ -229,11 +229,11 @@ classifier de manière fiable un salon invité comme message privé ou groupe au ## Aperçus en streaming -Le streaming des réponses Matrix est optionnel. +Le streaming des réponses Matrix est opt-in. -Définissez `channels.matrix.streaming` sur `"partial"` si vous voulez qu’OpenClaw envoie une seule -réponse d’aperçu en direct, modifie cet aperçu sur place pendant que le modèle génère du texte, puis le -finalise une fois la réponse terminée : +Définissez `channels.matrix.streaming` sur `"partial"` lorsque vous voulez qu’OpenClaw envoie un seul aperçu en direct +de réponse, modifie cet aperçu sur place pendant que le modèle génère du texte, puis le finalise lorsque la +réponse est terminée : ```json5 { @@ -245,38 +245,38 @@ finalise une fois la réponse terminée : } ``` -- `streaming: "off"` est la valeur par défaut. OpenClaw attend la réponse finale et l’envoie une seule fois. -- `streaming: "partial"` crée un message d’aperçu modifiable pour le bloc d’assistant en cours à l’aide de messages texte Matrix normaux. Cela préserve le comportement historique de Matrix où l’aperçu déclenche d’abord la notification, donc les clients standard peuvent notifier sur le premier texte d’aperçu diffusé au lieu du bloc terminé. -- `streaming: "quiet"` crée un aperçu discret modifiable pour le bloc d’assistant en cours. Utilisez-le uniquement si vous configurez aussi des règles push côté destinataire pour les modifications d’aperçu finalisées. -- `blockStreaming: true` active des messages de progression Matrix séparés. Avec le streaming d’aperçu activé, Matrix conserve le brouillon en direct pour le bloc actuel et garde les blocs terminés comme messages séparés. -- Lorsque le streaming d’aperçu est activé et que `blockStreaming` est désactivé, Matrix modifie le brouillon en direct sur place et finalise ce même événement lorsque le bloc ou le tour se termine. -- Si l’aperçu ne peut plus tenir dans un seul événement Matrix, OpenClaw arrête le streaming d’aperçu et revient à une livraison finale normale. -- Les réponses multimédias envoient toujours les pièces jointes normalement. Si un aperçu obsolète ne peut plus être réutilisé en toute sécurité, OpenClaw le rédige avant d’envoyer la réponse multimédia finale. -- Les modifications d’aperçu coûtent des appels supplémentaires à l’API Matrix. Laissez le streaming désactivé si vous voulez le comportement le plus prudent vis-à-vis de la limitation de débit. +- `streaming: "off"` est la valeur par défaut. OpenClaw attend la réponse finale et l’envoie en une seule fois. +- `streaming: "partial"` crée un message d’aperçu modifiable pour le bloc assistant en cours en utilisant des messages texte Matrix normaux. Cela préserve le comportement historique de notification sur premier aperçu de Matrix ; les clients standard peuvent donc notifier sur le premier texte d’aperçu en streaming plutôt que sur le bloc terminé. +- `streaming: "quiet"` crée un aperçu silencieux modifiable pour le bloc assistant en cours. Utilisez ceci uniquement si vous configurez aussi des règles push côté destinataire pour les modifications d’aperçu finalisées. +- `blockStreaming: true` active des messages de progression Matrix séparés. Avec l’aperçu en streaming activé, Matrix conserve le brouillon en direct pour le bloc en cours et garde les blocs terminés comme messages séparés. +- Lorsque l’aperçu en streaming est activé et que `blockStreaming` est désactivé, Matrix modifie le brouillon en direct sur place et finalise ce même événement lorsque le bloc ou le tour se termine. +- Si l’aperçu ne tient plus dans un seul événement Matrix, OpenClaw arrête l’aperçu en streaming et revient à la livraison finale normale. +- Les réponses multimédias envoient toujours les pièces jointes normalement. Si un aperçu obsolète ne peut plus être réutilisé en toute sécurité, OpenClaw le supprime avant d’envoyer la réponse multimédia finale. +- Les modifications d’aperçu entraînent des appels supplémentaires à l’API Matrix. Laissez le streaming désactivé si vous voulez le comportement le plus conservateur vis-à-vis des limites de débit. `blockStreaming` n’active pas à lui seul les aperçus de brouillon. -Utilisez `streaming: "partial"` ou `streaming: "quiet"` pour les modifications d’aperçu ; ajoutez ensuite `blockStreaming: true` uniquement si vous voulez aussi que les blocs d’assistant terminés restent visibles comme messages de progression séparés. +Utilisez `streaming: "partial"` ou `streaming: "quiet"` pour les modifications d’aperçu ; puis ajoutez `blockStreaming: true` uniquement si vous voulez aussi que les blocs assistant terminés restent visibles sous forme de messages de progression séparés. -Si vous avez besoin des notifications Matrix standard sans règles push personnalisées, utilisez `streaming: "partial"` pour un comportement avec aperçu d’abord, ou laissez `streaming` désactivé pour un envoi final uniquement. Avec `streaming: "off"` : +Si vous avez besoin de notifications Matrix standard sans règles push personnalisées, utilisez `streaming: "partial"` pour un comportement basé sur le premier aperçu, ou laissez `streaming` désactivé pour un envoi final uniquement. Avec `streaming: "off"` : - `blockStreaming: true` envoie chaque bloc terminé comme un message Matrix normal avec notification. -- `blockStreaming: false` envoie uniquement la réponse finale terminée comme un message Matrix normal avec notification. +- `blockStreaming: false` envoie uniquement la réponse finale complète comme un message Matrix normal avec notification. -### Règles push auto-hébergées pour les aperçus finalisés discrets +### Règles push auto-hébergées pour les aperçus silencieux finalisés -Si vous exploitez votre propre infrastructure Matrix et que vous voulez que les aperçus discrets ne notifient que lorsqu’un bloc ou -une réponse finale est terminé, définissez `streaming: "quiet"` et ajoutez une règle push par utilisateur pour les modifications d’aperçu finalisées. +Si vous exploitez votre propre infrastructure Matrix et souhaitez que les aperçus silencieux ne notifient qu’une fois un bloc ou la +réponse finale terminée, définissez `streaming: "quiet"` et ajoutez une règle push par utilisateur pour les modifications d’aperçu finalisées. -Il s’agit généralement d’une configuration côté utilisateur destinataire, pas d’un changement de config global du homeserver : +Il s’agit généralement d’une configuration côté utilisateur destinataire, pas d’un changement de config global côté homeserver : -Correspondance rapide avant de commencer : +Repères rapides avant de commencer : - utilisateur destinataire = la personne qui doit recevoir la notification - utilisateur bot = le compte Matrix OpenClaw qui envoie la réponse - utilisez le jeton d’accès de l’utilisateur destinataire pour les appels API ci-dessous - faites correspondre `sender` dans la règle push avec le MXID complet de l’utilisateur bot -1. Configurez OpenClaw pour utiliser des aperçus discrets : +1. Configurez OpenClaw pour utiliser des aperçus silencieux : ```json5 { @@ -289,12 +289,12 @@ Correspondance rapide avant de commencer : ``` 2. Assurez-vous que le compte destinataire reçoit déjà les notifications push Matrix normales. Les règles - d’aperçu discret ne fonctionnent que si cet utilisateur a déjà des pushers/appareils fonctionnels. + d’aperçu silencieux ne fonctionnent que si cet utilisateur dispose déjà de pushers/appareils fonctionnels. 3. Obtenez le jeton d’accès de l’utilisateur destinataire. - - Utilisez le jeton de l’utilisateur qui reçoit les messages, pas celui du bot. + - Utilisez le jeton de l’utilisateur qui reçoit, pas celui du bot. - Réutiliser un jeton de session client existant est généralement le plus simple. - - Si vous devez créer un nouveau jeton, vous pouvez vous connecter via l’API Client-Server Matrix standard : + - Si vous devez créer un nouveau jeton, vous pouvez vous connecter via l’API Client-Server Matrix standard : ```bash curl -sS -X POST \ @@ -310,7 +310,7 @@ curl -sS -X POST \ }' ``` -4. Vérifiez que le compte destinataire a déjà des pushers : +4. Vérifiez que le compte destinataire a déjà des pushers : ```bash curl -sS \ @@ -321,7 +321,7 @@ curl -sS \ Si cela ne renvoie aucun pusher/appareil actif, corrigez d’abord les notifications Matrix normales avant d’ajouter la règle OpenClaw ci-dessous. -OpenClaw marque les modifications d’aperçu finalisées contenant uniquement du texte avec : +OpenClaw marque les modifications finalisées d’aperçu texte uniquement avec : ```json { @@ -329,7 +329,7 @@ OpenClaw marque les modifications d’aperçu finalisées contenant uniquement d } ``` -5. Créez une règle push de remplacement pour chaque compte destinataire qui doit recevoir ces notifications : +5. Créez une règle push de remplacement pour chaque compte destinataire qui doit recevoir ces notifications : ```bash curl -sS -X PUT \ @@ -359,25 +359,25 @@ curl -sS -X PUT \ }' ``` -Remplacez ces valeurs avant d’exécuter la commande : +Remplacez ces valeurs avant d’exécuter la commande : -- `https://matrix.example.org` : l’URL de base de votre homeserver -- `$USER_ACCESS_TOKEN` : le jeton d’accès de l’utilisateur qui reçoit les messages -- `openclaw-finalized-preview-botname` : un ID de règle unique à ce bot pour cet utilisateur destinataire -- `@bot:example.org` : le MXID de votre bot Matrix OpenClaw, pas celui de l’utilisateur destinataire +- `https://matrix.example.org` : l’URL de base de votre homeserver +- `$USER_ACCESS_TOKEN` : le jeton d’accès de l’utilisateur destinataire +- `openclaw-finalized-preview-botname` : un ID de règle unique à ce bot pour cet utilisateur destinataire +- `@bot:example.org` : le MXID de votre bot Matrix OpenClaw, pas le MXID de l’utilisateur destinataire -Important pour les configurations avec plusieurs bots : +Important pour les configurations avec plusieurs bots : -- Les règles push sont indexées par `ruleId`. Réexécuter `PUT` avec le même ID de règle met à jour cette règle. -- Si un même utilisateur destinataire doit recevoir des notifications pour plusieurs comptes bot Matrix OpenClaw, créez une règle par bot avec un ID de règle unique pour chaque correspondance `sender`. -- Un schéma simple consiste à utiliser `openclaw-finalized-preview-`, par exemple `openclaw-finalized-preview-ops` ou `openclaw-finalized-preview-support`. +- Les règles push sont indexées par `ruleId`. Relancer `PUT` avec le même ID de règle met à jour cette règle. +- Si un même utilisateur destinataire doit être notifié pour plusieurs comptes de bot Matrix OpenClaw, créez une règle par bot avec un ID de règle unique pour chaque correspondance `sender`. +- Un modèle simple est `openclaw-finalized-preview-`, par exemple `openclaw-finalized-preview-ops` ou `openclaw-finalized-preview-support`. -La règle est évaluée par rapport à l’expéditeur de l’événement : +La règle est évaluée par rapport à l’expéditeur de l’événement : - authentifiez-vous avec le jeton de l’utilisateur destinataire - faites correspondre `sender` avec le MXID du bot OpenClaw -6. Vérifiez que la règle existe : +6. Vérifiez que la règle existe : ```bash curl -sS \ @@ -385,10 +385,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Testez une réponse diffusée en streaming. En mode discret, le salon doit afficher un aperçu de brouillon discret et la +7. Testez une réponse en streaming. En mode silencieux, le salon doit afficher un brouillon d’aperçu silencieux et la modification finale sur place doit envoyer une notification une fois le bloc ou le tour terminé. -Si vous devez supprimer la règle plus tard, supprimez ce même ID de règle avec le jeton de l’utilisateur destinataire : +Si vous devez supprimer la règle plus tard, supprimez ce même ID de règle avec le jeton de l’utilisateur destinataire : ```bash curl -sS -X DELETE \ @@ -396,35 +396,35 @@ curl -sS -X DELETE \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -Remarques : +Remarques : - Créez la règle avec le jeton d’accès de l’utilisateur destinataire, pas celui du bot. -- Les nouvelles règles `override` définies par l’utilisateur sont insérées avant les règles de suppression par défaut ; aucun paramètre d’ordre supplémentaire n’est donc nécessaire. -- Cela n’affecte que les modifications d’aperçu contenant uniquement du texte qu’OpenClaw peut finaliser en toute sécurité sur place. Les replis média et les replis d’aperçu obsolète utilisent toujours la livraison Matrix normale. +- Les nouvelles règles `override` définies par l’utilisateur sont insérées avant les règles de suppression par défaut, donc aucun paramètre d’ordre supplémentaire n’est nécessaire. +- Cela n’affecte que les modifications d’aperçu en texte seul qu’OpenClaw peut finaliser sur place en toute sécurité. Les bascules de secours pour les médias et les aperçus obsolètes utilisent toujours la livraison Matrix normale. - Si `GET /_matrix/client/v3/pushers` n’affiche aucun pusher, l’utilisateur ne dispose pas encore d’une livraison push Matrix fonctionnelle pour ce compte/appareil. #### Synapse -Pour Synapse, la configuration ci-dessus suffit généralement à elle seule : +Pour Synapse, la configuration ci-dessus suffit généralement à elle seule : - Aucune modification spéciale de `homeserver.yaml` n’est requise pour les notifications d’aperçu OpenClaw finalisées. - Si votre déploiement Synapse envoie déjà des notifications push Matrix normales, le jeton utilisateur + l’appel `pushrules` ci-dessus constituent l’étape principale de configuration. -- Si vous exécutez Synapse derrière un reverse proxy ou des workers, assurez-vous que `/_matrix/client/.../pushrules/` atteint correctement Synapse. +- Si vous exécutez Synapse derrière un proxy inverse ou des workers, assurez-vous que `/_matrix/client/.../pushrules/` atteint correctement Synapse. - Si vous utilisez des workers Synapse, assurez-vous que les pushers sont en bon état. La livraison push est gérée par le processus principal ou par `synapse.app.pusher` / les workers pusher configurés. #### Tuwunel -Pour Tuwunel, utilisez le même flux de configuration et le même appel API `pushrules` que ci-dessus : +Pour Tuwunel, utilisez le même flux de configuration et le même appel d’API `pushrules` que ci-dessus : - Aucune configuration spécifique à Tuwunel n’est requise pour le marqueur d’aperçu finalisé lui-même. - Si les notifications Matrix normales fonctionnent déjà pour cet utilisateur, le jeton utilisateur + l’appel `pushrules` ci-dessus constituent l’étape principale de configuration. -- Si les notifications semblent disparaître pendant que l’utilisateur est actif sur un autre appareil, vérifiez si `suppress_push_when_active` est activé. Tuwunel a ajouté cette option dans Tuwunel 1.4.2 le 12 septembre 2025, et elle peut volontairement supprimer les pushs vers d’autres appareils lorsqu’un appareil est actif. +- Si les notifications semblent disparaître pendant que l’utilisateur est actif sur un autre appareil, vérifiez si `suppress_push_when_active` est activé. Tuwunel a ajouté cette option dans Tuwunel 1.4.2 le 12 septembre 2025, et elle peut volontairement supprimer les notifications push vers d’autres appareils pendant qu’un appareil est actif. ## Salons bot à bot Par défaut, les messages Matrix provenant d’autres comptes Matrix OpenClaw configurés sont ignorés. -Utilisez `allowBots` lorsque vous voulez intentionnellement autoriser le trafic Matrix inter-agent : +Utilisez `allowBots` lorsque vous voulez intentionnellement du trafic Matrix inter-agents : ```json5 { @@ -441,19 +441,19 @@ Utilisez `allowBots` lorsque vous voulez intentionnellement autoriser le trafic } ``` -- `allowBots: true` accepte les messages provenant d’autres comptes bot Matrix configurés dans les salons et messages privés autorisés. +- `allowBots: true` accepte les messages d’autres comptes de bot Matrix configurés dans les salons autorisés et les messages privés. - `allowBots: "mentions"` accepte ces messages uniquement lorsqu’ils mentionnent visiblement ce bot dans les salons. Les messages privés restent autorisés. -- `groups..allowBots` remplace le paramètre au niveau du compte pour un salon donné. +- `groups..allowBots` remplace le paramètre au niveau du compte pour un salon. - OpenClaw ignore toujours les messages provenant du même ID utilisateur Matrix afin d’éviter les boucles d’auto-réponse. -- Matrix n’expose pas ici d’indicateur natif de bot ; OpenClaw considère « écrit par un bot » comme « envoyé par un autre compte Matrix configuré sur cette Gateway OpenClaw ». +- Matrix n’expose pas ici d’indicateur natif de bot ; OpenClaw traite « écrit par un bot » comme « envoyé par un autre compte Matrix configuré sur cette Gateway OpenClaw ». -Utilisez des listes d’autorisation de salon strictes et des exigences de mention lorsque vous activez le trafic bot à bot dans des salons partagés. +Utilisez des listes d’autorisation de salons strictes et des exigences de mention lorsque vous activez le trafic bot à bot dans des salons partagés. ## Chiffrement et vérification -Dans les salons chiffrés (E2EE), les événements d’image sortants utilisent `thumbnail_file` afin que les aperçus d’image soient chiffrés en même temps que la pièce jointe complète. Les salons non chiffrés utilisent toujours `thumbnail_url` en clair. Aucune configuration n’est nécessaire — le Plugin détecte automatiquement l’état E2EE. +Dans les salons chiffrés (E2EE), les événements d’image sortants utilisent `thumbnail_file` afin que les aperçus d’image soient chiffrés en même temps que la pièce jointe complète. Les salons non chiffrés utilisent toujours `thumbnail_url` en clair. Aucune configuration n’est nécessaire — le plugin détecte automatiquement l’état E2EE. -Activer le chiffrement : +Activer le chiffrement : ```json5 { @@ -469,92 +469,92 @@ Activer le chiffrement : } ``` -Vérifier l’état de la vérification : +Vérifier l’état de vérification : ```bash openclaw matrix verify status ``` -État détaillé (diagnostics complets) : +État détaillé (diagnostics complets) : ```bash openclaw matrix verify status --verbose ``` -Inclure la clé de récupération stockée dans la sortie lisible par machine : +Inclure la clé de récupération stockée dans la sortie lisible par machine : ```bash openclaw matrix verify status --include-recovery-key --json ``` -Initialiser l’état de cross-signing et de vérification : +Initialiser l’état de cross-signing et de vérification : ```bash openclaw matrix verify bootstrap ``` -Diagnostics détaillés de l’initialisation : +Diagnostics détaillés d’initialisation : ```bash openclaw matrix verify bootstrap --verbose ``` -Forcer une réinitialisation complète de l’identité de cross-signing avant l’initialisation : +Forcer une nouvelle réinitialisation de l’identité de cross-signing avant l’initialisation : ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Vérifier cet appareil avec une clé de récupération : +Vérifier cet appareil avec une clé de récupération : ```bash openclaw matrix verify device "" ``` -Détails détaillés de la vérification de l’appareil : +Détails détaillés de vérification de l’appareil : ```bash openclaw matrix verify device "" --verbose ``` -Vérifier l’état de santé de la sauvegarde des clés de salon : +Vérifier l’état de santé de la sauvegarde des clés de salon : ```bash openclaw matrix verify backup status ``` -Diagnostics détaillés de l’état de santé de la sauvegarde : +Diagnostics détaillés de l’état de santé de la sauvegarde : ```bash openclaw matrix verify backup status --verbose ``` -Restaurer les clés de salon depuis la sauvegarde serveur : +Restaurer les clés de salon depuis la sauvegarde serveur : ```bash openclaw matrix verify backup restore ``` -Diagnostics détaillés de la restauration : +Diagnostics détaillés de restauration : ```bash openclaw matrix verify backup restore --verbose ``` -Supprimer la sauvegarde serveur actuelle et créer une nouvelle base de référence de sauvegarde. Si la -clé de sauvegarde stockée ne peut pas être chargée proprement, cette réinitialisation peut aussi recréer le stockage de secrets afin que -les futurs démarrages à froid puissent charger la nouvelle clé de sauvegarde : +Supprimer la sauvegarde serveur actuelle et créer une nouvelle base de sauvegarde. Si la +clé de sauvegarde stockée ne peut pas être chargée correctement, cette réinitialisation peut aussi recréer le stockage de secrets afin que +les futurs démarrages à froid puissent charger la nouvelle clé de sauvegarde : ```bash openclaw matrix verify backup reset --yes ``` -Toutes les commandes `verify` sont concises par défaut (y compris la journalisation interne discrète du SDK) et n’affichent des diagnostics détaillés qu’avec `--verbose`. -Utilisez `--json` pour une sortie complète lisible par machine dans les scripts. +Toutes les commandes `verify` sont concises par défaut (y compris la journalisation interne silencieuse du SDK) et n’affichent des diagnostics détaillés qu’avec `--verbose`. +Utilisez `--json` pour une sortie entièrement lisible par machine lors du scripting. -Dans les configurations multi-comptes, les commandes Matrix CLI utilisent le compte Matrix par défaut implicite sauf si vous passez `--account `. +Dans les configurations multi-comptes, les commandes CLI Matrix utilisent le compte Matrix par défaut implicite, sauf si vous passez `--account `. Si vous configurez plusieurs comptes nommés, définissez d’abord `channels.matrix.defaultAccount`, sinon ces opérations CLI implicites s’arrêteront et vous demanderont de choisir explicitement un compte. -Utilisez `--account` chaque fois que vous voulez que les opérations de vérification ou d’appareil ciblent explicitement un compte nommé : +Utilisez `--account` chaque fois que vous voulez que les opérations de vérification ou d’appareil ciblent explicitement un compte nommé : ```bash openclaw matrix verify status --account assistant @@ -564,41 +564,41 @@ openclaw matrix devices list --account assistant Lorsque le chiffrement est désactivé ou indisponible pour un compte nommé, les avertissements Matrix et les erreurs de vérification pointent vers la clé de config de ce compte, par exemple `channels.matrix.accounts.assistant.encryption`. -### Ce que signifie « vérifié » +### Ce que signifie « verified » -OpenClaw considère cet appareil Matrix comme vérifié uniquement lorsqu’il est vérifié par votre propre identité de cross-signing. -En pratique, `openclaw matrix verify status --verbose` expose trois signaux de confiance : +OpenClaw ne considère cet appareil Matrix comme vérifié que lorsqu’il est vérifié par votre propre identité de cross-signing. +En pratique, `openclaw matrix verify status --verbose` expose trois signaux de confiance : -- `Locally trusted` : cet appareil n’est approuvé que par le client actuel -- `Cross-signing verified` : le SDK indique que l’appareil est vérifié via le cross-signing -- `Signed by owner` : l’appareil est signé par votre propre clé d’auto-signature +- `Locally trusted` : cet appareil est approuvé uniquement par le client actuel +- `Cross-signing verified` : le SDK indique que l’appareil est vérifié via le cross-signing +- `Signed by owner` : l’appareil est signé par votre propre clé d’auto-signature -`Verified by owner` devient `yes` uniquement lorsque la vérification par cross-signing ou la signature du propriétaire est présente. -La confiance locale seule ne suffit pas pour qu’OpenClaw considère l’appareil comme entièrement vérifié. +`Verified by owner` passe à `yes` uniquement lorsqu’une vérification par cross-signing ou une signature par le propriétaire est présente. +La confiance locale seule ne suffit pas pour qu’OpenClaw traite l’appareil comme entièrement vérifié. -### Ce que fait l’initialisation +### Ce que fait bootstrap `openclaw matrix verify bootstrap` est la commande de réparation et de configuration pour les comptes Matrix chiffrés. -Elle effectue toutes les opérations suivantes dans l’ordre : +Elle effectue toutes les opérations suivantes dans cet ordre : - initialise le stockage de secrets, en réutilisant une clé de récupération existante lorsque c’est possible - initialise le cross-signing et téléverse les clés publiques de cross-signing manquantes - tente de marquer et de signer par cross-signing l’appareil actuel -- crée une nouvelle sauvegarde serveur des clés de salon si elle n’existe pas déjà +- crée une nouvelle sauvegarde côté serveur des clés de salon si elle n’existe pas déjà Si le homeserver exige une authentification interactive pour téléverser les clés de cross-signing, OpenClaw tente d’abord le téléversement sans authentification, puis avec `m.login.dummy`, puis avec `m.login.password` lorsque `channels.matrix.password` est configuré. -Utilisez `--force-reset-cross-signing` uniquement si vous voulez intentionnellement supprimer l’identité de cross-signing actuelle et en créer une nouvelle. +Utilisez `--force-reset-cross-signing` uniquement lorsque vous voulez intentionnellement abandonner l’identité de cross-signing actuelle et en créer une nouvelle. -Si vous voulez intentionnellement supprimer la sauvegarde actuelle des clés de salon et démarrer une nouvelle -base de référence de sauvegarde pour les futurs messages, utilisez `openclaw matrix verify backup reset --yes`. -Faites-le uniquement si vous acceptez que l’ancien historique chiffré irrécupérable reste +Si vous voulez intentionnellement abandonner la sauvegarde actuelle des clés de salon et démarrer une nouvelle +base de sauvegarde pour les futurs messages, utilisez `openclaw matrix verify backup reset --yes`. +Ne faites cela que si vous acceptez qu’un ancien historique chiffré irrécupérable reste indisponible et qu’OpenClaw puisse recréer le stockage de secrets si le secret de sauvegarde actuel ne peut pas être chargé en toute sécurité. -### Nouvelle base de référence de sauvegarde +### Nouvelle base de sauvegarde -Si vous voulez conserver le fonctionnement des futurs messages chiffrés et acceptez de perdre l’ancien historique irrécupérable, exécutez ces commandes dans l’ordre : +Si vous voulez conserver le fonctionnement des futurs messages chiffrés et acceptez de perdre l’ancien historique irrécupérable, exécutez ces commandes dans l’ordre : ```bash openclaw matrix verify backup reset --yes @@ -612,69 +612,70 @@ Ajoutez `--account ` à chaque commande lorsque vous voulez cibler explicite Lorsque `encryption: true`, Matrix définit par défaut `startupVerification` sur `"if-unverified"`. Au démarrage, si cet appareil n’est toujours pas vérifié, Matrix demandera une auto-vérification dans un autre client Matrix, -évitera les demandes en double tant qu’une demande est déjà en attente, et appliquera un délai d’attente local avant de réessayer après les redémarrages. -Les tentatives de demande échouées sont réessayées plus rapidement que la création réussie d’une demande, par défaut. +évitera les demandes en doublon lorsqu’une demande est déjà en attente et appliquera un délai local avant de réessayer après les redémarrages. +Par défaut, les tentatives de demande échouées sont réessayées plus tôt que la création réussie d’une demande. Définissez `startupVerification: "off"` pour désactiver les demandes automatiques au démarrage, ou ajustez `startupVerificationCooldownHours` -si vous voulez une fenêtre de réessai plus courte ou plus longue. +si vous voulez une fenêtre de nouvelle tentative plus courte ou plus longue. Le démarrage effectue également automatiquement un passage conservateur d’initialisation crypto. -Ce passage essaie d’abord de réutiliser le stockage de secrets et l’identité de cross-signing actuels, et évite de réinitialiser le cross-signing à moins que vous n’exécutiez un flux explicite de réparation par initialisation. +Ce passage tente d’abord de réutiliser le stockage de secrets et l’identité de cross-signing actuels, et évite de réinitialiser le cross-signing sauf si vous exécutez un flux explicite de réparation d’initialisation. -Si le démarrage détecte un état d’initialisation défaillant et que `channels.matrix.password` est configuré, OpenClaw peut tenter un chemin de réparation plus strict. +Si le démarrage détecte encore un état d’initialisation cassé, OpenClaw peut tenter un chemin de réparation protégé même lorsque `channels.matrix.password` n’est pas configuré. +Si le homeserver exige une UIA basée sur mot de passe pour cette réparation, OpenClaw enregistre un avertissement et garde un démarrage non fatal au lieu d’interrompre le bot. Si l’appareil actuel est déjà signé par le propriétaire, OpenClaw préserve cette identité au lieu de la réinitialiser automatiquement. -Voir [migration Matrix](/fr/install/migrating-matrix) pour le flux complet de mise à niveau, les limites, les commandes de récupération et les messages de migration courants. +Voir [Migration Matrix](/fr/install/migrating-matrix) pour le flux complet de mise à niveau, les limites, les commandes de récupération et les messages de migration courants. ### Avis de vérification -Matrix publie les avis du cycle de vie de la vérification directement dans le message privé strict de vérification sous forme de messages `m.notice`. -Cela inclut : +Matrix publie les avis de cycle de vie de vérification directement dans le salon strict de vérification en message privé sous forme de messages `m.notice`. +Cela inclut : - les avis de demande de vérification -- les avis de vérification prête (avec des instructions explicites « Verify by emoji ») -- le début et la fin de la vérification -- les détails SAS (emoji et décimaux) lorsqu’ils sont disponibles +- les avis de vérification prête (avec une indication explicite « Vérifier par emoji ») +- les avis de début et d’achèvement de vérification +- les détails SAS (emoji et décimal) lorsqu’ils sont disponibles -Les demandes de vérification entrantes provenant d’un autre client Matrix sont suivies et automatiquement acceptées par OpenClaw. +Les demandes de vérification entrantes provenant d’un autre client Matrix sont suivies et acceptées automatiquement par OpenClaw. Pour les flux d’auto-vérification, OpenClaw démarre également automatiquement le flux SAS lorsque la vérification par emoji devient disponible et confirme son propre côté. Pour les demandes de vérification provenant d’un autre utilisateur/appareil Matrix, OpenClaw accepte automatiquement la demande puis attend que le flux SAS se poursuive normalement. -Vous devez toujours comparer les emoji ou le SAS décimal dans votre client Matrix et confirmer « They match » là-bas pour terminer la vérification. +Vous devez toujours comparer l’emoji ou le SAS décimal dans votre client Matrix et confirmer « Ils correspondent » là-bas pour terminer la vérification. -OpenClaw n’accepte pas automatiquement à l’aveugle les flux dupliqués auto-initiés. Au démarrage, il évite de créer une nouvelle demande lorsqu’une demande d’auto-vérification est déjà en attente. +OpenClaw n’accepte pas automatiquement et aveuglément les flux dupliqués auto-initiés. Au démarrage, il évite de créer une nouvelle demande lorsqu’une demande d’auto-vérification est déjà en attente. -Les avis de vérification de protocole/système ne sont pas transmis au pipeline de chat de l’agent, donc ils ne produisent pas `NO_REPLY`. +Les avis de protocole/système de vérification ne sont pas transmis au pipeline de chat de l’agent, donc ils ne produisent pas de `NO_REPLY`. ### Hygiène des appareils Les anciens appareils Matrix gérés par OpenClaw peuvent s’accumuler sur le compte et rendre la confiance dans les salons chiffrés plus difficile à interpréter. -Listez-les avec : +Listez-les avec : ```bash openclaw matrix devices list ``` -Supprimez les appareils OpenClaw gérés devenus obsolètes avec : +Supprimez les appareils OpenClaw gérés devenus obsolètes avec : ```bash openclaw matrix devices prune-stale ``` -### Stockage crypto +### Magasin crypto -Le chiffrement de bout en bout Matrix utilise le chemin crypto Rust officiel de `matrix-js-sdk` dans Node, avec `fake-indexeddb` comme shim IndexedDB. L’état crypto est conservé dans un fichier d’instantané (`crypto-idb-snapshot.json`) et restauré au démarrage. Le fichier d’instantané est un état d’exécution sensible stocké avec des permissions de fichier restrictives. +Le chiffrement de bout en bout Matrix utilise le chemin crypto Rust officiel de `matrix-js-sdk` dans Node, avec `fake-indexeddb` comme shim IndexedDB. L’état crypto est conservé dans un fichier snapshot (`crypto-idb-snapshot.json`) et restauré au démarrage. Le fichier snapshot contient un état d’exécution sensible stocké avec des permissions de fichier restrictives. L’état d’exécution chiffré se trouve sous des racines par compte, par utilisateur et par hachage de jeton dans `~/.openclaw/matrix/accounts//__//`. Ce répertoire contient le magasin de synchronisation (`bot-storage.json`), le magasin crypto (`crypto/`), -le fichier de clé de récupération (`recovery-key.json`), l’instantané IndexedDB (`crypto-idb-snapshot.json`), -les associations de fils (`thread-bindings.json`) et l’état de vérification au démarrage (`startup-verification.json`). +le fichier de clé de récupération (`recovery-key.json`), le snapshot IndexedDB (`crypto-idb-snapshot.json`), +les liaisons de fils (`thread-bindings.json`) et l’état de vérification au démarrage (`startup-verification.json`). Lorsque le jeton change mais que l’identité du compte reste la même, OpenClaw réutilise la meilleure racine existante -pour ce tuple compte/homeserver/utilisateur afin que l’état de synchronisation antérieur, l’état crypto, les associations de fils +pour ce tuple compte/homeserver/utilisateur afin que l’état de synchronisation précédent, l’état crypto, les liaisons de fils et l’état de vérification au démarrage restent visibles. ## Gestion du profil -Mettez à jour le profil Matrix du compte sélectionné avec : +Mettez à jour le profil Matrix du compte sélectionné avec : ```bash openclaw matrix profile set --name "OpenClaw Assistant" @@ -683,47 +684,47 @@ openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png Ajoutez `--account ` lorsque vous voulez cibler explicitement un compte Matrix nommé. -Matrix accepte directement les URL d’avatar `mxc://`. Lorsque vous transmettez une URL d’avatar `http://` ou `https://`, OpenClaw la téléverse d’abord vers Matrix puis enregistre l’URL `mxc://` résolue dans `channels.matrix.avatarUrl` (ou dans la surcharge du compte sélectionné). +Matrix accepte directement les URL d’avatar `mxc://`. Lorsque vous passez une URL d’avatar `http://` ou `https://`, OpenClaw la téléverse d’abord vers Matrix puis réenregistre l’URL `mxc://` résolue dans `channels.matrix.avatarUrl` (ou dans la surcharge du compte sélectionné). ## Fils -Matrix prend en charge les fils Matrix natifs à la fois pour les réponses automatiques et pour les envois de l’outil de message. +Matrix prend en charge les fils Matrix natifs à la fois pour les réponses automatiques et pour les envois avec l’outil de messages. -- `dm.sessionScope: "per-user"` (par défaut) conserve le routage des messages privés Matrix au niveau de l’expéditeur, de sorte que plusieurs salons de message privé peuvent partager une même session lorsqu’ils se résolvent vers le même pair. -- `dm.sessionScope: "per-room"` isole chaque salon de message privé Matrix dans sa propre clé de session tout en utilisant les vérifications normales d’authentification et de liste d’autorisation des messages privés. -- Les associations de conversation Matrix explicites restent prioritaires sur `dm.sessionScope`, donc les salons et fils associés conservent leur session cible choisie. -- `threadReplies: "off"` conserve les réponses au niveau supérieur et laisse les messages entrants en fil sur la session parente. -- `threadReplies: "inbound"` répond dans un fil uniquement lorsque le message entrant était déjà dans ce fil. -- `threadReplies: "always"` conserve les réponses de salon dans un fil enraciné sur le message déclencheur et fait passer cette conversation par la session à portée de fil correspondante dès le premier message déclencheur. -- `dm.threadReplies` remplace le paramètre de niveau supérieur pour les messages privés uniquement. Par exemple, vous pouvez garder les fils de salon isolés tout en gardant les messages privés à plat. -- Les messages entrants en fil incluent le message racine du fil comme contexte supplémentaire pour l’agent. -- Les envois de l’outil de message héritent automatiquement du fil Matrix actuel lorsque la cible est le même salon, ou le même utilisateur cible en message privé, sauf si un `threadId` explicite est fourni. -- La réutilisation de la même session pour un utilisateur cible en message privé ne s’active que lorsque les métadonnées de la session actuelle prouvent qu’il s’agit du même pair de message privé sur le même compte Matrix ; sinon OpenClaw revient au routage normal à portée utilisateur. -- Lorsque OpenClaw voit un salon de message privé Matrix entrer en collision avec un autre salon de message privé sur la même session partagée de message privé Matrix, il publie une seule fois un `m.notice` dans ce salon avec l’échappatoire `/focus` lorsque les associations de fils sont activées et l’indication `dm.sessionScope`. -- Les associations de fils à l’exécution sont prises en charge pour Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` et `/acp spawn` associé à un fil fonctionnent dans les salons et messages privés Matrix. -- Le `/focus` de niveau supérieur dans un salon/message privé Matrix crée un nouveau fil Matrix et l’associe à la session cible lorsque `threadBindings.spawnSubagentSessions=true`. -- Exécuter `/focus` ou `/acp spawn --thread here` à l’intérieur d’un fil Matrix existant associe ce fil actuel à la place. +- `dm.sessionScope: "per-user"` (par défaut) conserve le routage DM Matrix limité à l’expéditeur, de sorte que plusieurs salons DM puissent partager une session lorsqu’ils se résolvent vers le même pair. +- `dm.sessionScope: "per-room"` isole chaque salon DM Matrix dans sa propre clé de session tout en utilisant l’authentification DM normale et les vérifications de liste d’autorisation. +- Les liaisons explicites de conversation Matrix ont toujours priorité sur `dm.sessionScope`, de sorte que les salons et fils liés conservent leur session cible choisie. +- `threadReplies: "off"` conserve les réponses au niveau supérieur et maintient les messages entrants en fil sur la session parente. +- `threadReplies: "inbound"` répond dans un fil uniquement lorsque le message entrant se trouvait déjà dans ce fil. +- `threadReplies: "always"` conserve les réponses de salon dans un fil enraciné sur le message déclencheur et route cette conversation via la session limitée au fil correspondante à partir du premier message déclencheur. +- `dm.threadReplies` remplace le paramètre de niveau supérieur pour les DM uniquement. Par exemple, vous pouvez conserver des fils de salon isolés tout en gardant les DM à plat. +- Les messages entrants en fil incluent le message racine du fil comme contexte agent supplémentaire. +- Les envois avec l’outil de messages héritent automatiquement du fil Matrix actuel lorsque la cible est le même salon, ou la même cible utilisateur en DM, sauf si un `threadId` explicite est fourni. +- La réutilisation de cible utilisateur DM dans la même session ne s’active que lorsque les métadonnées de la session actuelle prouvent le même pair DM sur le même compte Matrix ; sinon OpenClaw revient au routage normal limité à l’utilisateur. +- Lorsque OpenClaw détecte qu’un salon DM Matrix entre en collision avec un autre salon DM sur la même session DM Matrix partagée, il publie un `m.notice` unique dans ce salon avec l’échappatoire `/focus` lorsque les liaisons de fils sont activées et l’indication `dm.sessionScope`. +- Les liaisons de fils d’exécution sont prises en charge pour Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` et `/acp spawn` lié à un fil fonctionnent dans les salons et DM Matrix. +- Le `/focus` d’un salon/DM Matrix au niveau supérieur crée un nouveau fil Matrix et le lie à la session cible lorsque `threadBindings.spawnSubagentSessions=true`. +- Exécuter `/focus` ou `/acp spawn --thread here` à l’intérieur d’un fil Matrix existant lie ce fil actuel à la place. -## Associations de conversation ACP +## Liaisons de conversation ACP -Les salons, messages privés et fils Matrix existants peuvent être transformés en espaces de travail ACP durables sans changer la surface de chat. +Les salons, DM et fils Matrix existants peuvent être transformés en espaces de travail ACP durables sans changer la surface de chat. -Flux opérateur rapide : +Flux opérateur rapide : -- Exécutez `/acp spawn codex --bind here` dans le message privé Matrix, le salon ou le fil existant que vous voulez continuer à utiliser. -- Dans un message privé ou un salon Matrix de niveau supérieur, le message privé/salon actuel reste la surface de chat et les futurs messages sont routés vers la session ACP créée. -- À l’intérieur d’un fil Matrix existant, `--bind here` associe ce fil actuel sur place. -- `/new` et `/reset` réinitialisent sur place la même session ACP associée. -- `/acp close` ferme la session ACP et supprime l’association. +- Exécutez `/acp spawn codex --bind here` dans le DM, salon ou fil Matrix existant que vous souhaitez continuer à utiliser. +- Dans un DM ou un salon Matrix de niveau supérieur, le DM/salon actuel reste la surface de chat et les futurs messages sont routés vers la session ACP créée. +- À l’intérieur d’un fil Matrix existant, `--bind here` lie ce fil actuel sur place. +- `/new` et `/reset` réinitialisent sur place la même session ACP liée. +- `/acp close` ferme la session ACP et supprime la liaison. -Remarques : +Remarques : - `--bind here` ne crée pas de fil Matrix enfant. -- `threadBindings.spawnAcpSessions` n’est requis que pour `/acp spawn --thread auto|here`, lorsque OpenClaw doit créer ou associer un fil Matrix enfant. +- `threadBindings.spawnAcpSessions` n’est requis que pour `/acp spawn --thread auto|here`, lorsque OpenClaw doit créer ou lier un fil Matrix enfant. -### Configuration des associations de fils +### Configuration de liaison de fils -Matrix hérite des valeurs globales par défaut depuis `session.threadBindings` et prend aussi en charge des surcharges par canal : +Matrix hérite des valeurs par défaut globales depuis `session.threadBindings` et prend aussi en charge des surcharges par canal : - `threadBindings.enabled` - `threadBindings.idleHours` @@ -731,66 +732,66 @@ Matrix hérite des valeurs globales par défaut depuis `session.threadBindings` - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Les indicateurs de création liés aux fils Matrix sont optionnels : +Les indicateurs de création liée à un fil Matrix sont opt-in : -- Définissez `threadBindings.spawnSubagentSessions: true` pour permettre à `/focus` de niveau supérieur de créer et d’associer de nouveaux fils Matrix. -- Définissez `threadBindings.spawnAcpSessions: true` pour permettre à `/acp spawn --thread auto|here` d’associer des sessions ACP à des fils Matrix. +- Définissez `threadBindings.spawnSubagentSessions: true` pour permettre à `/focus` de niveau supérieur de créer et lier de nouveaux fils Matrix. +- Définissez `threadBindings.spawnAcpSessions: true` pour permettre à `/acp spawn --thread auto|here` de lier des sessions ACP à des fils Matrix. ## Réactions Matrix prend en charge les actions de réaction sortantes, les notifications de réaction entrantes et les réactions d’accusé de réception entrantes. -- L’outillage de réaction sortante est contrôlé par `channels["matrix"].actions.reactions`. +- L’outillage des réactions sortantes est contrôlé par `channels["matrix"].actions.reactions`. - `react` ajoute une réaction à un événement Matrix spécifique. - `reactions` liste le résumé actuel des réactions pour un événement Matrix spécifique. -- `emoji=""` supprime les réactions propres au compte bot sur cet événement. -- `remove: true` supprime uniquement la réaction avec l’emoji spécifié du compte bot. +- `emoji=""` supprime les propres réactions du compte bot sur cet événement. +- `remove: true` supprime uniquement la réaction avec l’emoji indiqué du compte bot. -La portée des réactions d’accusé de réception se résout dans cet ordre : +La portée des réactions d’accusé de réception suit l’ordre de résolution standard d’OpenClaw : - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- repli sur l’emoji d’identité de l’agent +- repli vers l’emoji d’identité de l’agent -La portée de la réaction d’accusé de réception se résout dans cet ordre : +La portée des réactions d’accusé de réception se résout dans cet ordre : - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Le mode de notification de réaction se résout dans cet ordre : +Le mode de notification des réactions se résout dans cet ordre : - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- valeur par défaut : `own` +- défaut : `own` -Comportement : +Comportement : -- `reactionNotifications: "own"` transmet les événements `m.reaction` ajoutés lorsqu’ils ciblent des messages Matrix rédigés par le bot. +- `reactionNotifications: "own"` transmet les événements `m.reaction` ajoutés lorsqu’ils ciblent des messages Matrix écrits par le bot. - `reactionNotifications: "off"` désactive les événements système de réaction. -- Les suppressions de réaction ne sont pas synthétisées en événements système, car Matrix les expose comme des rédactions, pas comme des suppressions autonomes de `m.reaction`. +- Les suppressions de réactions ne sont pas synthétisées en événements système car Matrix les expose comme des redactions, et non comme des suppressions autonomes de `m.reaction`. ## Contexte d’historique -- `channels.matrix.historyLimit` contrôle combien de messages récents du salon sont inclus comme `InboundHistory` lorsqu’un message de salon Matrix déclenche l’agent. Revient à `messages.groupChat.historyLimit` ; si les deux ne sont pas définis, la valeur effective par défaut est `0`. Définissez `0` pour désactiver. -- L’historique des salons Matrix est limité au salon. Les messages privés continuent d’utiliser l’historique normal de session. -- L’historique des salons Matrix est limité aux messages en attente : OpenClaw met en mémoire tampon les messages du salon qui n’ont pas encore déclenché de réponse, puis capture cette fenêtre lorsqu’une mention ou un autre déclencheur arrive. -- Le message déclencheur actuel n’est pas inclus dans `InboundHistory` ; il reste dans le corps entrant principal pour ce tour. -- Les nouvelles tentatives du même événement Matrix réutilisent l’instantané d’historique d’origine au lieu de dériver vers des messages de salon plus récents. +- `channels.matrix.historyLimit` contrôle combien de messages récents de salon sont inclus comme `InboundHistory` lorsqu’un message de salon Matrix déclenche l’agent. Retombe sur `messages.groupChat.historyLimit` ; si les deux ne sont pas définis, la valeur effective par défaut est `0`. Définissez `0` pour désactiver. +- L’historique des salons Matrix est limité au salon. Les DM continuent d’utiliser l’historique normal de session. +- L’historique des salons Matrix est pending-only : OpenClaw met en mémoire tampon les messages de salon qui n’ont pas encore déclenché de réponse, puis prend un snapshot de cette fenêtre lorsqu’une mention ou un autre déclencheur arrive. +- Le message déclencheur actuel n’est pas inclus dans `InboundHistory` ; il reste dans le corps entrant principal pour ce tour. +- Les nouvelles tentatives du même événement Matrix réutilisent le snapshot d’historique d’origine au lieu de dériver vers des messages de salon plus récents. ## Visibilité du contexte -Matrix prend en charge le contrôle partagé `contextVisibility` pour le contexte de salon supplémentaire comme le texte de réponse récupéré, les racines de fil et l’historique en attente. +Matrix prend en charge le contrôle partagé `contextVisibility` pour le contexte de salon supplémentaire, comme le texte de réponse récupéré, les racines de fil et l’historique en attente. -- `contextVisibility: "all"` est la valeur par défaut. Le contexte supplémentaire est conservé tel que reçu. -- `contextVisibility: "allowlist"` filtre le contexte supplémentaire vers les expéditeurs autorisés par les vérifications actives de liste d’autorisation de salon/utilisateur. -- `contextVisibility: "allowlist_quote"` se comporte comme `allowlist`, mais conserve tout de même une réponse citée explicite. +- `contextVisibility: "all"` est la valeur par défaut. Le contexte supplémentaire est conservé tel qu’il est reçu. +- `contextVisibility: "allowlist"` filtre le contexte supplémentaire aux expéditeurs autorisés par les vérifications actives de liste d’autorisation de salon/utilisateur. +- `contextVisibility: "allowlist_quote"` se comporte comme `allowlist`, mais conserve quand même une réponse citée explicite. -Ce paramètre affecte la visibilité du contexte supplémentaire, pas la capacité du message entrant lui-même à déclencher une réponse. -L’autorisation du déclencheur provient toujours de `groupPolicy`, `groups`, `groupAllowFrom` et des paramètres de politique des messages privés. +Ce paramètre affecte la visibilité du contexte supplémentaire, pas le fait que le message entrant lui-même puisse déclencher une réponse. +L’autorisation de déclenchement provient toujours de `groupPolicy`, `groups`, `groupAllowFrom` et des paramètres de politique DM. -## Politique de message privé et de salon +## Politique des DM et des salons ```json5 { @@ -813,82 +814,82 @@ L’autorisation du déclencheur provient toujours de `groupPolicy`, `groups`, ` } ``` -Voir [Groups](/fr/channels/groups) pour le comportement de filtrage par mention et de liste d’autorisation. +Voir [Groups](/fr/channels/groups) pour le filtrage par mention et le comportement de liste d’autorisation. -Exemple d’appairage pour les messages privés Matrix : +Exemple d’appairage pour les DM Matrix : ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Si un utilisateur Matrix non approuvé continue à vous envoyer des messages avant approbation, OpenClaw réutilise le même code d’appairage en attente et peut renvoyer une réponse de rappel après un court délai au lieu de créer un nouveau code. +Si un utilisateur Matrix non approuvé continue à vous envoyer des messages avant l’approbation, OpenClaw réutilise le même code d’appairage en attente et peut renvoyer une réponse de rappel après un court délai au lieu de générer un nouveau code. -Voir [Pairing](/fr/channels/pairing) pour le flux partagé d’appairage des messages privés et la disposition du stockage. +Voir [Pairing](/fr/channels/pairing) pour le flux d’appairage DM partagé et la disposition du stockage. -## Réparation directe de salon +## Réparation de salon direct -Si l’état des messages directs se désynchronise, OpenClaw peut se retrouver avec des associations `m.direct` obsolètes qui pointent vers d’anciens salons solo au lieu du message privé actif. Inspectez l’association actuelle pour un pair avec : +Si l’état des messages directs se désynchronise, OpenClaw peut se retrouver avec des mappings `m.direct` obsolètes pointant vers d’anciens salons solo au lieu du DM actif. Inspectez le mapping actuel pour un pair avec : ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Réparez-la avec : +Réparez-le avec : ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -Le flux de réparation : +Le flux de réparation : -- préfère un message privé strict 1:1 déjà associé dans `m.direct` -- retombe sur n’importe quel message privé strict 1:1 actuellement rejoint avec cet utilisateur -- crée un nouveau salon direct et réécrit `m.direct` si aucun message privé sain n’existe +- préfère un DM strict 1:1 déjà mappé dans `m.direct` +- retombe sur tout DM strict 1:1 actuellement rejoint avec cet utilisateur +- crée un nouveau salon direct et réécrit `m.direct` si aucun DM sain n’existe -Le flux de réparation ne supprime pas automatiquement les anciens salons. Il sélectionne seulement le message privé sain et met à jour l’association afin que les nouveaux envois Matrix, les avis de vérification et les autres flux de message direct ciblent de nouveau le bon salon. +Le flux de réparation ne supprime pas automatiquement les anciens salons. Il choisit seulement le DM sain et met à jour le mapping afin que les nouveaux envois Matrix, les avis de vérification et les autres flux de messages directs ciblent à nouveau le bon salon. ## Approbations exec Matrix peut agir comme client d’approbation natif pour un compte Matrix. Les réglages natifs -de routage des messages privés/canaux restent sous la configuration des approbations exec : +de routage DM/canal restent sous la configuration des approbations exec : - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (facultatif ; revient à `channels.matrix.dm.allowFrom`) -- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, défaut : `dm`) +- `channels.matrix.execApprovals.approvers` (facultatif ; retombe sur `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, défaut : `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Les approbateurs doivent être des ID utilisateur Matrix comme `@owner:example.org`. Matrix active automatiquement les approbations natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un approbateur peut être résolu. Les approbations exec utilisent d’abord `execApprovals.approvers` et peuvent revenir à `channels.matrix.dm.allowFrom`. Les approbations de Plugin sont autorisées via `channels.matrix.dm.allowFrom`. Définissez `enabled: false` pour désactiver explicitement Matrix comme client d’approbation natif. Sinon, les demandes d’approbation reviennent vers d’autres routes d’approbation configurées ou vers la politique de repli des approbations. +Les approbateurs doivent être des ID utilisateur Matrix tels que `@owner:example.org`. Matrix active automatiquement les approbations natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un approbateur peut être résolu. Les approbations exec utilisent d’abord `execApprovals.approvers` et peuvent retomber sur `channels.matrix.dm.allowFrom`. Les approbations de Plugin s’autorisent via `channels.matrix.dm.allowFrom`. Définissez `enabled: false` pour désactiver explicitement Matrix comme client d’approbation natif. Sinon, les demandes d’approbation retombent sur d’autres routes d’approbation configurées ou sur la politique de repli des approbations. -Le routage natif Matrix prend en charge les deux types d’approbation : +Le routage natif Matrix prend en charge les deux types d’approbation : -- `channels.matrix.execApprovals.*` contrôle le mode natif de diffusion vers message privé/canal pour les invites d’approbation Matrix. -- Les approbations exec utilisent l’ensemble d’approbateurs exec défini par `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`. -- Les approbations de Plugin utilisent la liste d’autorisation des messages privés Matrix de `channels.matrix.dm.allowFrom`. -- Les raccourcis par réaction Matrix et les mises à jour de message s’appliquent aux approbations exec comme aux approbations de Plugin. +- `channels.matrix.execApprovals.*` contrôle le mode natif de diffusion DM/canal des invites d’approbation Matrix. +- Les approbations exec utilisent l’ensemble des approbateurs exec défini par `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`. +- Les approbations de Plugin utilisent la liste d’autorisation DM Matrix définie par `channels.matrix.dm.allowFrom`. +- Les raccourcis par réaction Matrix et les mises à jour de messages s’appliquent aux approbations exec comme aux approbations de Plugin. -Règles de livraison : +Règles de livraison : -- `target: "dm"` envoie les invites d’approbation dans les messages privés des approbateurs -- `target: "channel"` renvoie l’invite dans le salon ou message privé Matrix d’origine -- `target: "both"` envoie vers les messages privés des approbateurs et vers le salon ou message privé Matrix d’origine +- `target: "dm"` envoie les invites d’approbation dans les DM des approbateurs +- `target: "channel"` renvoie l’invite dans le salon ou DM Matrix d’origine +- `target: "both"` envoie aux DM des approbateurs et au salon ou DM Matrix d’origine -Les invites d’approbation Matrix initialisent des raccourcis par réaction sur le message principal d’approbation : +Les invites d’approbation Matrix amorcent des raccourcis de réaction sur le message d’approbation principal : - `✅` = autoriser une fois - `❌` = refuser - `♾️` = toujours autoriser lorsque cette décision est permise par la politique exec effective -Les approbateurs peuvent réagir à ce message ou utiliser les commandes slash de repli : `/approve allow-once`, `/approve allow-always`, ou `/approve deny`. +Les approbateurs peuvent réagir sur ce message ou utiliser les commandes slash de repli : `/approve allow-once`, `/approve allow-always` ou `/approve deny`. -Seuls les approbateurs résolus peuvent autoriser ou refuser. Pour les approbations exec, la livraison dans le canal inclut le texte de commande ; n’activez donc `channel` ou `both` que dans des salons de confiance. +Seuls les approbateurs résolus peuvent autoriser ou refuser. Pour les approbations exec, la livraison dans le canal inclut le texte de la commande ; n’activez donc `channel` ou `both` que dans des salons de confiance. -Surcharge par compte : +Surcharge par compte : - `channels.matrix.accounts..execApprovals` -Documentation connexe : [Exec approvals](/fr/tools/exec-approvals) +Documentation associée : [Approbations exec](/fr/tools/exec-approvals) ## Multi-comptes @@ -920,25 +921,25 @@ Documentation connexe : [Exec approvals](/fr/tools/exec-approvals) } ``` -Les valeurs de niveau supérieur `channels.matrix` servent de valeurs par défaut pour les comptes nommés, sauf si un compte les remplace. -Vous pouvez limiter les entrées de salon héritées à un seul compte Matrix avec `groups..account`. +Les valeurs de niveau supérieur dans `channels.matrix` servent de valeurs par défaut pour les comptes nommés, sauf si un compte les remplace. +Vous pouvez limiter les entrées de salon héritées à un compte Matrix avec `groups..account`. Les entrées sans `account` restent partagées entre tous les comptes Matrix, et les entrées avec `account: "default"` continuent de fonctionner lorsque le compte par défaut est configuré directement au niveau supérieur dans `channels.matrix.*`. -Les valeurs par défaut d’authentification partagées partielles ne créent pas à elles seules un compte par défaut implicite distinct. OpenClaw ne synthétise le compte `default` de niveau supérieur que lorsque ce compte par défaut dispose d’une authentification récente (`homeserver` plus `accessToken`, ou `homeserver` plus `userId` et `password`) ; les comptes nommés peuvent toujours rester détectables à partir de `homeserver` plus `userId` lorsque des identifiants mis en cache satisfont l’authentification plus tard. -Si Matrix a déjà exactement un compte nommé, ou si `defaultAccount` pointe vers une clé de compte nommé existante, la promotion réparation/configuration d’un seul compte vers plusieurs comptes préserve ce compte au lieu de créer une nouvelle entrée `accounts.default`. Seules les clés d’authentification/d’initialisation Matrix sont déplacées dans ce compte promu ; les clés de politique de livraison partagées restent au niveau supérieur. +Les valeurs par défaut d’authentification partagées partielles ne créent pas à elles seules un compte implicite par défaut distinct. OpenClaw ne synthétise le compte `default` de niveau supérieur que lorsque ce compte par défaut a une authentification valide (`homeserver` plus `accessToken`, ou `homeserver` plus `userId` et `password`) ; les comptes nommés peuvent quand même rester détectables à partir de `homeserver` plus `userId` lorsque les informations d’identification mises en cache satisfont l’authentification plus tard. +Si Matrix a déjà exactement un compte nommé, ou si `defaultAccount` pointe vers une clé de compte nommé existante, la promotion réparation/configuration d’un compte unique vers plusieurs comptes préserve ce compte au lieu de créer une nouvelle entrée `accounts.default`. Seules les clés d’authentification/d’initialisation Matrix sont déplacées dans ce compte promu ; les clés partagées de politique de livraison restent au niveau supérieur. Définissez `defaultAccount` lorsque vous voulez qu’OpenClaw privilégie un compte Matrix nommé pour le routage implicite, les sondes et les opérations CLI. -Si plusieurs comptes Matrix sont configurés et que l’un des ID de compte est `default`, OpenClaw utilise ce compte implicitement même si `defaultAccount` n’est pas défini. -Si vous configurez plusieurs comptes nommés, définissez `defaultAccount` ou passez `--account ` pour les commandes CLI qui reposent sur une sélection implicite du compte. -Passez `--account ` à `openclaw matrix verify ...` et `openclaw matrix devices ...` lorsque vous voulez remplacer cette sélection implicite pour une commande donnée. +Si plusieurs comptes Matrix sont configurés et que l’un des ID de compte est `default`, OpenClaw utilise ce compte implicitement même lorsque `defaultAccount` n’est pas défini. +Si vous configurez plusieurs comptes nommés, définissez `defaultAccount` ou passez `--account ` pour les commandes CLI qui dépendent d’une sélection implicite de compte. +Passez `--account ` à `openclaw matrix verify ...` et `openclaw matrix devices ...` lorsque vous voulez remplacer cette sélection implicite pour une commande. -Voir [Référence de configuration](/fr/gateway/configuration-reference#multi-account-all-channels) pour le modèle multi-comptes partagé. +Voir [Référence de configuration](/fr/gateway/configuration-reference#multi-account-all-channels) pour le modèle multi-compte partagé. ## Homeservers privés/LAN Par défaut, OpenClaw bloque les homeservers Matrix privés/internes pour la protection SSRF, sauf si vous -les autorisez explicitement compte par compte. +activez explicitement cela pour chaque compte. -Si votre homeserver fonctionne sur localhost, une IP LAN/Tailscale ou un nom d’hôte interne, activez -`network.dangerouslyAllowPrivateNetwork` pour ce compte Matrix : +Si votre homeserver s’exécute sur localhost, une IP LAN/Tailscale ou un nom d’hôte interne, activez +`network.dangerouslyAllowPrivateNetwork` pour ce compte Matrix : ```json5 { @@ -954,7 +955,7 @@ Si votre homeserver fonctionne sur localhost, une IP LAN/Tailscale ou un nom d } ``` -Exemple de configuration via CLI : +Exemple de configuration via CLI : ```bash openclaw matrix account add \ @@ -964,12 +965,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Cette activation explicite n’autorise que les cibles privées/internes de confiance. Les homeservers publics en clair comme -`http://matrix.example.org:8008` restent bloqués. Préférez `https://` chaque fois que possible. +Cette activation explicite n’autorise que les cibles privées/internes de confiance. Les homeservers publics en clair tels que +`http://matrix.example.org:8008` restent bloqués. Préférez `https://` lorsque c’est possible. -## Utiliser un proxy pour le trafic Matrix +## Proxy du trafic Matrix -Si votre déploiement Matrix nécessite un proxy HTTP(S) sortant explicite, définissez `channels.matrix.proxy` : +Si votre déploiement Matrix a besoin d’un proxy HTTP(S) sortant explicite, définissez `channels.matrix.proxy` : ```json5 { @@ -984,85 +985,85 @@ Si votre déploiement Matrix nécessite un proxy HTTP(S) sortant explicite, déf ``` Les comptes nommés peuvent remplacer la valeur par défaut de niveau supérieur avec `channels.matrix.accounts..proxy`. -OpenClaw utilise le même paramètre de proxy pour le trafic Matrix à l’exécution et pour les sondes d’état du compte. +OpenClaw utilise le même paramètre de proxy pour le trafic Matrix à l’exécution et pour les sondes d’état des comptes. -## Résolution des cibles +## Résolution de cible -Matrix accepte ces formats de cible partout où OpenClaw vous demande une cible de salon ou d’utilisateur : +Matrix accepte ces formes de cible partout où OpenClaw vous demande une cible de salon ou d’utilisateur : -- Utilisateurs : `@user:server`, `user:@user:server` ou `matrix:user:@user:server` -- Salons : `!room:server`, `room:!room:server` ou `matrix:room:!room:server` -- Alias : `#alias:server`, `channel:#alias:server` ou `matrix:channel:#alias:server` +- Utilisateurs : `@user:server`, `user:@user:server` ou `matrix:user:@user:server` +- Salons : `!room:server`, `room:!room:server` ou `matrix:room:!room:server` +- Alias : `#alias:server`, `channel:#alias:server` ou `matrix:channel:#alias:server` -La recherche en direct dans l’annuaire utilise le compte Matrix connecté : +La recherche en direct dans l’annuaire utilise le compte Matrix connecté : - Les recherches d’utilisateur interrogent l’annuaire des utilisateurs Matrix sur ce homeserver. -- Les recherches de salon acceptent directement les ID et alias de salon explicites, puis se replient sur la recherche dans les noms des salons rejoints pour ce compte. -- La recherche par nom de salon rejoint est effectuée au mieux. Si un nom de salon ne peut pas être résolu en ID ou alias, il est ignoré lors de la résolution de la liste d’autorisation à l’exécution. +- Les recherches de salon acceptent directement les ID et alias de salon explicites, puis retombent sur la recherche par nom parmi les salons rejoints pour ce compte. +- La recherche par nom dans les salons rejoints est best-effort. Si un nom de salon ne peut pas être résolu en ID ou alias, il est ignoré lors de la résolution de la liste d’autorisation à l’exécution. ## Référence de configuration -- `enabled` : active ou désactive le canal. -- `name` : libellé facultatif du compte. -- `defaultAccount` : ID de compte préféré lorsque plusieurs comptes Matrix sont configurés. -- `homeserver` : URL du homeserver, par exemple `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork` : autorise ce compte Matrix à se connecter à des homeservers privés/internes. Activez cette option lorsque le homeserver se résout vers `localhost`, une IP LAN/Tailscale ou un hôte interne tel que `matrix-synapse`. -- `proxy` : URL facultative de proxy HTTP(S) pour le trafic Matrix. Les comptes nommés peuvent remplacer la valeur par défaut de niveau supérieur avec leur propre `proxy`. -- `userId` : ID utilisateur Matrix complet, par exemple `@bot:example.org`. -- `accessToken` : jeton d’accès pour l’authentification basée sur un jeton. Les valeurs en texte brut et les valeurs SecretRef sont prises en charge pour `channels.matrix.accessToken` et `channels.matrix.accounts..accessToken` via les fournisseurs env/file/exec. Voir [Gestion des secrets](/fr/gateway/secrets). -- `password` : mot de passe pour la connexion basée sur un mot de passe. Les valeurs en texte brut et les valeurs SecretRef sont prises en charge. -- `deviceId` : ID explicite de l’appareil Matrix. -- `deviceName` : nom d’affichage de l’appareil pour la connexion par mot de passe. -- `avatarUrl` : URL d’avatar personnel stockée pour la synchronisation du profil et les mises à jour `profile set`. -- `initialSyncLimit` : nombre maximal d’événements récupérés pendant la synchronisation au démarrage. -- `encryption` : active le chiffrement de bout en bout. -- `allowlistOnly` : lorsque `true`, convertit la politique de salon `open` en `allowlist`, et force toutes les politiques de message privé actives sauf `disabled` (y compris `pairing` et `open`) à `allowlist`. N’affecte pas les politiques `disabled`. -- `allowBots` : autorise les messages provenant d’autres comptes Matrix OpenClaw configurés (`true` ou `"mentions"`). -- `groupPolicy` : `open`, `allowlist` ou `disabled`. -- `contextVisibility` : mode de visibilité du contexte supplémentaire du salon (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom` : liste d’autorisation des ID utilisateur pour le trafic de salon. Les entrées doivent être des ID utilisateur Matrix complets ; les noms non résolus sont ignorés à l’exécution. -- `historyLimit` : nombre maximal de messages de salon à inclure comme contexte d’historique de groupe. Revient à `messages.groupChat.historyLimit` ; si les deux ne sont pas définis, la valeur effective par défaut est `0`. Définissez `0` pour désactiver. -- `replyToMode` : `off`, `first`, `all` ou `batched`. -- `markdown` : configuration facultative du rendu Markdown pour le texte Matrix sortant. -- `streaming` : `off` (par défaut), `"partial"`, `"quiet"`, `true` ou `false`. `"partial"` et `true` activent les mises à jour de brouillon avec aperçu initial via des messages texte Matrix normaux. `"quiet"` utilise des avis d’aperçu sans notification pour les configurations auto-hébergées avec règles push. `false` est équivalent à `"off"`. -- `blockStreaming` : `true` active des messages de progression séparés pour les blocs d’assistant terminés pendant que le streaming d’aperçu de brouillon est actif. -- `threadReplies` : `off`, `inbound` ou `always`. -- `threadBindings` : surcharges par canal pour le routage et le cycle de vie des sessions associées à un fil. -- `startupVerification` : mode automatique de demande d’auto-vérification au démarrage (`if-unverified`, `off`). -- `startupVerificationCooldownHours` : délai d’attente avant de réessayer les demandes automatiques de vérification au démarrage. -- `textChunkLimit` : taille des segments de message sortant en caractères (s’applique lorsque `chunkMode` est `length`). -- `chunkMode` : `length` découpe les messages par nombre de caractères ; `newline` découpe aux limites de ligne. -- `responsePrefix` : chaîne facultative ajoutée au début de toutes les réponses sortantes pour ce canal. -- `ackReaction` : surcharge facultative de réaction d’accusé de réception pour ce canal/compte. -- `ackReactionScope` : surcharge facultative de portée de réaction d’accusé de réception (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). -- `reactionNotifications` : mode de notification de réaction entrante (`own`, `off`). -- `mediaMaxMb` : limite de taille des médias en Mo pour les envois sortants et le traitement des médias entrants. -- `autoJoin` : politique de jonction automatique sur invitation (`always`, `allowlist`, `off`). Par défaut : `off`. S’applique à toutes les invitations Matrix, y compris les invitations de type message privé. -- `autoJoinAllowlist` : salons/alias autorisés lorsque `autoJoin` est `allowlist`. Les entrées d’alias sont résolues en ID de salon lors du traitement de l’invitation ; OpenClaw ne se fie pas à l’état d’alias revendiqué par le salon invité. -- `dm` : bloc de politique des messages privés (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy` : contrôle l’accès aux messages privés après qu’OpenClaw a rejoint le salon et l’a classé comme message privé. Cela ne change pas si une invitation est rejointe automatiquement. -- `dm.allowFrom` : les entrées doivent être des ID utilisateur Matrix complets, sauf si vous les avez déjà résolues via la recherche en direct dans l’annuaire. -- `dm.sessionScope` : `per-user` (par défaut) ou `per-room`. Utilisez `per-room` lorsque vous voulez que chaque salon de message privé Matrix conserve un contexte distinct même si le pair est le même. -- `dm.threadReplies` : surcharge de politique de fil pour les messages privés uniquement (`off`, `inbound`, `always`). Elle remplace le paramètre `threadReplies` de niveau supérieur à la fois pour le placement des réponses et pour l’isolation de session dans les messages privés. -- `execApprovals` : livraison native des approbations exec Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers` : ID utilisateur Matrix autorisés à approuver les demandes exec. Facultatif lorsque `dm.allowFrom` identifie déjà les approbateurs. -- `execApprovals.target` : `dm | channel | both` (par défaut : `dm`). -- `accounts` : surcharges nommées par compte. Les valeurs `channels.matrix` de niveau supérieur servent de valeurs par défaut pour ces entrées. -- `groups` : mappage de politique par salon. Préférez les ID ou alias de salon ; les noms de salon non résolus sont ignorés à l’exécution. L’identité de session/groupe utilise l’ID de salon stable après résolution. -- `groups..account` : restreint une entrée de salon héritée à un compte Matrix spécifique dans les configurations multi-comptes. -- `groups..allowBots` : surcharge au niveau du salon pour les expéditeurs de bots configurés (`true` ou `"mentions"`). -- `groups..users` : liste d’autorisation des expéditeurs par salon. -- `groups..tools` : surcharges d’autorisation/interdiction d’outils par salon. -- `groups..autoReply` : surcharge de filtrage par mention au niveau du salon. `true` désactive les exigences de mention pour ce salon ; `false` les réactive de force. -- `groups..skills` : filtre facultatif de Skills au niveau du salon. -- `groups..systemPrompt` : extrait facultatif de prompt système au niveau du salon. -- `rooms` : alias hérité pour `groups`. -- `actions` : contrôle d’accès par action pour les outils (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `enabled` : active ou désactive le canal. +- `name` : étiquette facultative pour le compte. +- `defaultAccount` : ID de compte préféré lorsque plusieurs comptes Matrix sont configurés. +- `homeserver` : URL du homeserver, par exemple `https://matrix.example.org`. +- `network.dangerouslyAllowPrivateNetwork` : autorise ce compte Matrix à se connecter à des homeservers privés/internes. Activez ceci lorsque le homeserver se résout vers `localhost`, une IP LAN/Tailscale ou un hôte interne tel que `matrix-synapse`. +- `proxy` : URL facultative d’un proxy HTTP(S) pour le trafic Matrix. Les comptes nommés peuvent remplacer la valeur par défaut de niveau supérieur avec leur propre `proxy`. +- `userId` : ID utilisateur Matrix complet, par exemple `@bot:example.org`. +- `accessToken` : jeton d’accès pour une authentification basée sur jeton. Les valeurs en clair et les valeurs SecretRef sont prises en charge pour `channels.matrix.accessToken` et `channels.matrix.accounts..accessToken` via les fournisseurs env/file/exec. Voir [Gestion des secrets](/fr/gateway/secrets). +- `password` : mot de passe pour une connexion basée sur mot de passe. Les valeurs en clair et les valeurs SecretRef sont prises en charge. +- `deviceId` : ID d’appareil Matrix explicite. +- `deviceName` : nom d’affichage de l’appareil pour la connexion par mot de passe. +- `avatarUrl` : URL d’avatar propre stockée pour la synchronisation de profil et les mises à jour `profile set`. +- `initialSyncLimit` : nombre maximal d’événements récupérés pendant la synchronisation au démarrage. +- `encryption` : active le chiffrement de bout en bout. +- `allowlistOnly` : lorsque `true`, convertit la politique de salon `open` en `allowlist`, et force toutes les politiques DM actives sauf `disabled` (y compris `pairing` et `open`) en `allowlist`. N’affecte pas les politiques `disabled`. +- `allowBots` : autorise les messages provenant d’autres comptes Matrix OpenClaw configurés (`true` ou `"mentions"`). +- `groupPolicy` : `open`, `allowlist` ou `disabled`. +- `contextVisibility` : mode de visibilité du contexte supplémentaire de salon (`all`, `allowlist`, `allowlist_quote`). +- `groupAllowFrom` : liste d’autorisation des ID utilisateur pour le trafic de salon. Les entrées doivent être des ID utilisateur Matrix complets ; les noms non résolus sont ignorés à l’exécution. +- `historyLimit` : nombre maximal de messages de salon à inclure comme contexte d’historique de groupe. Retombe sur `messages.groupChat.historyLimit` ; si les deux ne sont pas définis, la valeur effective par défaut est `0`. Définissez `0` pour désactiver. +- `replyToMode` : `off`, `first`, `all` ou `batched`. +- `markdown` : configuration facultative du rendu Markdown pour le texte Matrix sortant. +- `streaming` : `off` (par défaut), `"partial"`, `"quiet"`, `true` ou `false`. `"partial"` et `true` activent les mises à jour de brouillon en aperçu d’abord avec des messages texte Matrix normaux. `"quiet"` utilise des avis d’aperçu sans notification pour les configurations auto-hébergées avec règles push. `false` est équivalent à `"off"`. +- `blockStreaming` : `true` active des messages de progression séparés pour les blocs assistant terminés pendant que le streaming d’aperçu de brouillon est actif. +- `threadReplies` : `off`, `inbound` ou `always`. +- `threadBindings` : surcharges par canal pour le routage et le cycle de vie des sessions liées à des fils. +- `startupVerification` : mode automatique de demande d’auto-vérification au démarrage (`if-unverified`, `off`). +- `startupVerificationCooldownHours` : délai avant une nouvelle tentative des demandes automatiques de vérification au démarrage. +- `textChunkLimit` : taille des segments de message sortant en caractères (s’applique lorsque `chunkMode` vaut `length`). +- `chunkMode` : `length` divise les messages par nombre de caractères ; `newline` les divise aux limites de ligne. +- `responsePrefix` : chaîne facultative ajoutée au début de toutes les réponses sortantes pour ce canal. +- `ackReaction` : surcharge facultative de réaction d’accusé de réception pour ce canal/compte. +- `ackReactionScope` : surcharge facultative de portée des réactions d’accusé de réception (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `reactionNotifications` : mode de notification des réactions entrantes (`own`, `off`). +- `mediaMaxMb` : limite de taille des médias en Mo pour les envois sortants et le traitement des médias entrants. +- `autoJoin` : politique d’adhésion automatique aux invitations (`always`, `allowlist`, `off`). Par défaut : `off`. S’applique à toutes les invitations Matrix, y compris aux invitations de type message privé. +- `autoJoinAllowlist` : salons/alias autorisés lorsque `autoJoin` vaut `allowlist`. Les entrées d’alias sont résolues en ID de salon pendant le traitement des invitations ; OpenClaw ne fait pas confiance à l’état d’alias déclaré par le salon invité. +- `dm` : bloc de politique DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy` : contrôle l’accès DM après qu’OpenClaw a rejoint le salon et l’a classé comme DM. Cela ne change pas le fait qu’une invitation soit rejointe automatiquement ou non. +- `dm.allowFrom` : les entrées doivent être des ID utilisateur Matrix complets, sauf si vous les avez déjà résolues via la recherche en direct dans l’annuaire. +- `dm.sessionScope` : `per-user` (par défaut) ou `per-room`. Utilisez `per-room` lorsque vous voulez que chaque salon DM Matrix conserve un contexte séparé même si le pair est le même. +- `dm.threadReplies` : surcharge de politique de fil DM uniquement (`off`, `inbound`, `always`). Elle remplace le paramètre `threadReplies` de niveau supérieur pour le placement des réponses comme pour l’isolation de session dans les DM. +- `execApprovals` : livraison native des approbations exec Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers` : ID utilisateur Matrix autorisés à approuver les demandes exec. Facultatif lorsque `dm.allowFrom` identifie déjà les approbateurs. +- `execApprovals.target` : `dm | channel | both` (par défaut : `dm`). +- `accounts` : surcharges nommées par compte. Les valeurs de niveau supérieur dans `channels.matrix` servent de valeurs par défaut pour ces entrées. +- `groups` : map de politique par salon. Préférez les ID ou alias de salon ; les noms de salon non résolus sont ignorés à l’exécution. L’identité de session/groupe utilise l’ID de salon stable après résolution. +- `groups..account` : limite une entrée de salon héritée à un compte Matrix spécifique dans les configurations multi-comptes. +- `groups..allowBots` : surcharge au niveau du salon pour les expéditeurs de bots configurés (`true` ou `"mentions"`). +- `groups..users` : liste d’autorisation des expéditeurs par salon. +- `groups..tools` : surcharges d’autorisation/refus d’outils par salon. +- `groups..autoReply` : surcharge de filtrage par mention au niveau du salon. `true` désactive l’exigence de mention pour ce salon ; `false` la réactive de force. +- `groups..skills` : filtre facultatif de Skills au niveau du salon. +- `groups..systemPrompt` : extrait facultatif d’invite système au niveau du salon. +- `rooms` : alias hérité pour `groups`. +- `actions` : contrôle d’accès par action (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). -## Liens connexes +## Lié - [Vue d’ensemble des canaux](/fr/channels) — tous les canaux pris en charge -- [Appairage](/fr/channels/pairing) — authentification des messages privés et flux d’appairage +- [Appairage](/fr/channels/pairing) — authentification DM et flux d’appairage - [Groups](/fr/channels/groups) — comportement du chat de groupe et filtrage par mention - [Routage des canaux](/fr/channels/channel-routing) — routage de session pour les messages - [Sécurité](/fr/gateway/security) — modèle d’accès et durcissement diff --git a/docs/fr/concepts/system-prompt.md b/docs/fr/concepts/system-prompt.md index 4f040ea56..b702b626d 100644 --- a/docs/fr/concepts/system-prompt.md +++ b/docs/fr/concepts/system-prompt.md @@ -1,99 +1,99 @@ --- read_when: - - Modification du texte du prompt système, de la liste des outils ou des sections heure/pulsation - - Modification du comportement d’amorçage de l’espace de travail ou d’injection des Skills + - Modification du texte du prompt système, de la liste des outils ou des sections d’heure/Heartbeat + - Modification du bootstrap de l’espace de travail ou du comportement d’injection des Skills summary: Ce que contient le prompt système d’OpenClaw et comment il est assemblé title: Prompt système x-i18n: - generated_at: "2026-04-12T06:49:38Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f + source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 source_path: concepts/system-prompt.md workflow: 15 --- # Prompt système -OpenClaw construit un prompt système personnalisé pour chaque exécution d’agent. Le prompt est **géré par OpenClaw** et n’utilise pas le prompt par défaut de pi-coding-agent. +OpenClaw construit un prompt système personnalisé pour chaque exécution d’agent. Le prompt appartient à **OpenClaw** et n’utilise pas le prompt par défaut de pi-coding-agent. Le prompt est assemblé par OpenClaw et injecté dans chaque exécution d’agent. -Les plugins de fournisseur peuvent apporter des indications de prompt compatibles avec le cache sans remplacer l’intégralité du prompt géré par OpenClaw. Le runtime du fournisseur peut : +Les plugins de fournisseur peuvent apporter des indications de prompt compatibles avec le cache sans remplacer l’intégralité du prompt détenu par OpenClaw. Le runtime du fournisseur peut : -- remplacer un petit ensemble de sections principales nommées (`interaction_style`, +- remplacer un petit ensemble de sections cœur nommées (`interaction_style`, `tool_call_style`, `execution_bias`) -- injecter un **préfixe stable** au-dessus de la limite de cache du prompt -- injecter un **suffixe dynamique** au-dessous de la limite de cache du prompt +- injecter un **préfixe stable** au-dessus de la limite du cache de prompt +- injecter un **suffixe dynamique** en dessous de la limite du cache de prompt -Utilisez les contributions gérées par le fournisseur pour l’ajustement spécifique à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour de véritables modifications globales du prompt, pas pour le comportement normal d’un fournisseur. +Utilisez des contributions détenues par le fournisseur pour les ajustements spécifiques à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour des changements de prompt réellement globaux, pas pour le comportement normal d’un fournisseur. ## Structure -Le prompt est volontairement compact et utilise des sections fixes : +Le prompt est volontairement compact et utilise des sections fixes : -- **Outils** : rappel structuré de la source de vérité des outils, plus indications d’exécution pour l’utilisation des outils. -- **Sécurité** : court rappel des garde-fous pour éviter les comportements de recherche de pouvoir ou le contournement de la supervision. -- **Skills** (lorsqu’elles sont disponibles) : indique au modèle comment charger les instructions des Skills à la demande. -- **Auto-mise à jour d’OpenClaw** : explique comment inspecter la configuration en toute sécurité avec - `config.schema.lookup`, corriger la configuration avec `config.patch`, remplacer l’intégralité de la - configuration avec `config.apply`, et exécuter `update.run` uniquement sur demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse également de réécrire +- **Tooling** : rappel de la source de vérité des outils structurés, plus indications d’utilisation des outils au runtime. +- **Safety** : court rappel de garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision. +- **Skills** (lorsqu’ils sont disponibles) : indique au modèle comment charger à la demande les instructions des Skills. +- **OpenClaw Self-Update** : comment inspecter la configuration en toute sécurité avec + `config.schema.lookup`, corriger la configuration avec `config.patch`, remplacer la + configuration complète avec `config.apply`, et exécuter `update.run` uniquement sur demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse également de réécrire `tools.exec.ask` / `tools.exec.security`, y compris les alias hérités `tools.bash.*` qui se normalisent vers ces chemins exec protégés. -- **Espace de travail** : répertoire de travail (`agents.defaults.workspace`). -- **Documentation** : chemin local vers la documentation OpenClaw (dépôt ou package npm) et moment où la lire. -- **Fichiers de l’espace de travail (injectés)** : indique que les fichiers d’amorçage sont inclus ci-dessous. -- **Sandbox** (lorsqu’elle est activée) : indique l’environnement d’exécution isolé, les chemins de sandbox et si l’exécution élevée est disponible. -- **Date et heure actuelles** : heure locale de l’utilisateur, fuseau horaire et format d’heure. -- **Balises de réponse** : syntaxe facultative des balises de réponse pour les fournisseurs pris en charge. -- **Pulsations** : prompt de pulsation et comportement d’accusé de réception, lorsque les pulsations sont activées pour l’agent par défaut. -- **Runtime** : hôte, OS, node, racine du dépôt (lorsqu’elle est détectée), niveau de réflexion (une ligne). -- **Raisonnement** : niveau de visibilité actuel + indication de bascule `/reasoning`. +- **Workspace** : répertoire de travail (`agents.defaults.workspace`). +- **Documentation** : chemin local vers la documentation OpenClaw (dépôt ou package npm) et quand la lire. +- **Workspace Files (injected)** : indique que les fichiers de bootstrap sont inclus ci-dessous. +- **Sandbox** (lorsqu’elle est activée) : indique le runtime sandboxé, les chemins de la sandbox et si l’exécution élevée est disponible. +- **Current Date & Time** : heure locale de l’utilisateur, fuseau horaire et format horaire. +- **Reply Tags** : syntaxe facultative des balises de réponse pour les fournisseurs pris en charge. +- **Heartbeats** : prompt de Heartbeat et comportement d’accusé de réception, lorsque les Heartbeats sont activés pour l’agent par défaut. +- **Runtime** : hôte, OS, node, modèle, racine du dépôt (lorsqu’elle est détectée), niveau de réflexion (une ligne). +- **Reasoning** : niveau de visibilité actuel + indication de bascule /reasoning. -La section Outils comprend également des indications d’exécution pour les tâches de longue durée : +La section Tooling inclut également des indications d’exécution pour les tâches longues : -- utiliser cron pour un suivi ultérieur (`check back later`, rappels, travail récurrent) - au lieu de boucles `exec` avec veille, d’astuces de délai `yieldMs` ou d’un sondage répété de `process` -- utiliser `exec` / `process` uniquement pour les commandes qui démarrent maintenant et continuent à s’exécuter +- utiliser Cron pour un suivi ultérieur (`check back later`, rappels, travail récurrent) + au lieu de boucles de veille `exec`, d’astuces de délai `yieldMs` ou de sondages `process` + répétés +- utiliser `exec` / `process` uniquement pour des commandes qui démarrent maintenant et continuent à s’exécuter en arrière-plan - lorsque le réveil automatique à la fin est activé, démarrer la commande une seule fois et s’appuyer sur - le chemin de réveil push lorsqu’elle émet une sortie ou échoue -- utiliser `process` pour les journaux, le statut, l’entrée ou l’intervention lorsque vous devez + le mécanisme de réveil push lorsqu’elle produit une sortie ou échoue +- utiliser `process` pour les journaux, l’état, l’entrée ou l’intervention lorsque vous devez inspecter une commande en cours d’exécution -- si la tâche est plus importante, préférer `sessions_spawn` ; la fin d’un sous-agent est - pilotée par push et réannoncée automatiquement au demandeur +- si la tâche est plus importante, préférer `sessions_spawn` ; la fin des sous-agents est + signalée par push et réannoncée automatiquement au demandeur - ne pas sonder `subagents list` / `sessions_list` en boucle uniquement pour attendre la fin -Lorsque l’outil expérimental `update_plan` est activé, la section Outils indique également au -modèle de l’utiliser uniquement pour les tâches non triviales en plusieurs étapes, de conserver exactement une étape -`in_progress`, et d’éviter de répéter l’intégralité du plan après chaque mise à jour. +Lorsque l’outil expérimental `update_plan` est activé, Tooling indique également au +modèle de ne l’utiliser que pour un travail non trivial en plusieurs étapes, de conserver exactement une étape +`in_progress`, et d’éviter de répéter le plan entier après chaque mise à jour. -Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations exec, le sandboxing et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception. +Les garde-fous de Safety dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations exec, la sandbox et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception. -Sur les canaux avec cartes ou boutons d’approbation natifs, le prompt d’exécution indique désormais à -l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle -`/approve` que lorsque le résultat de l’outil indique que les approbations dans le chat ne sont pas disponibles ou -que l’approbation manuelle est la seule possibilité. +Sur les canaux disposant de cartes/boutons d’approbation natifs, le prompt runtime indique désormais à l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle +`/approve` que lorsque le résultat de l’outil indique que les approbations dans le chat ne sont pas disponibles ou que l’approbation manuelle est la seule option. ## Modes de prompt -OpenClaw peut produire des prompts système plus petits pour les sous-agents. Le runtime définit un -`promptMode` pour chaque exécution (ce n’est pas une configuration visible par l’utilisateur) : +OpenClaw peut générer des prompts système plus petits pour les sous-agents. Le runtime définit un +`promptMode` pour chaque exécution (pas une configuration destinée à l’utilisateur) : -- `full` (par défaut) : inclut toutes les sections ci-dessus. -- `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Rappel mémoire**, **Auto-mise à jour d’OpenClaw**, **Alias de modèles**, **Identité de l’utilisateur**, **Balises de réponse**, - **Messagerie**, **Réponses silencieuses** et **Pulsations**. Outils, **Sécurité**, - Espace de travail, Sandbox, Date et heure actuelles (lorsqu’elles sont connues), Runtime et le contexte +- `full` (par défaut) : inclut toutes les sections ci-dessus. +- `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Memory Recall**, **OpenClaw + Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, + **Messaging**, **Silent Replies** et **Heartbeats**. Tooling, **Safety**, + Workspace, Sandbox, Current Date & Time (lorsqu’ils sont connus), Runtime et le contexte injecté restent disponibles. -- `none` : renvoie uniquement la ligne d’identité de base. +- `none` : renvoie uniquement la ligne d’identité de base. -Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont libellés **Contexte du sous-agent** -au lieu de **Contexte du chat de groupe**. +Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont étiquetés **Subagent +Context** au lieu de **Group Chat Context**. -## Injection de l’amorçage de l’espace de travail +## Injection du bootstrap de l’espace de travail -Les fichiers d’amorçage sont tronqués et ajoutés sous **Contexte du projet** afin que le modèle voie le contexte d’identité et de profil sans nécessiter de lectures explicites : +Les fichiers de bootstrap sont tronqués et ajoutés sous **Project Context** afin que le modèle voie le contexte d’identité et de profil sans avoir besoin de lectures explicites : - `AGENTS.md` - `SOUL.md` @@ -101,68 +101,68 @@ Les fichiers d’amorçage sont tronqués et ajoutés sous **Contexte du projet* - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (uniquement dans les tout nouveaux espaces de travail) +- `BOOTSTRAP.md` (uniquement dans les espaces de travail tout neufs) - `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de repli en minuscules Tous ces fichiers sont **injectés dans la fenêtre de contexte** à chaque tour, sauf si -un garde-fou spécifique au fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque -les pulsations sont désactivées pour l’agent par défaut ou lorsque +une condition spécifique au fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque +les Heartbeats sont désactivés pour l’agent par défaut ou que `agents.defaults.heartbeat.includeSystemPromptSection` vaut false. Gardez les fichiers injectés concis — en particulier `MEMORY.md`, qui peut grossir avec le temps et entraîner -une utilisation du contexte étonnamment élevée ainsi que des compactages plus fréquents. +une utilisation du contexte étonnamment élevée ainsi qu’une Compaction plus fréquente. -> **Remarque :** les fichiers quotidiens `memory/*.md` ne font **pas** partie du -> **Contexte du projet** d’amorçage normal. Lors des tours ordinaires, on y accède à la demande via les outils +> **Remarque :** les fichiers quotidiens `memory/*.md` ne font **pas** partie du +> Project Context de bootstrap normal. Lors des tours ordinaires, ils sont consultés à la demande via les outils > `memory_search` et `memory_get`, de sorte qu’ils ne comptent pas dans la -> fenêtre de contexte à moins que le modèle ne les lise explicitement. Les tours simples `/new` et -> `/reset` constituent l’exception : le runtime peut préfixer la mémoire quotidienne récente -> sous la forme d’un bloc ponctuel de contexte de démarrage pour ce premier tour. +> fenêtre de contexte sauf si le modèle les lit explicitement. Les tours `/new` et +> `/reset` seuls constituent l’exception : le runtime peut préfixer de la mémoire quotidienne récente +> comme bloc de contexte de démarrage à usage unique pour ce premier tour. Les fichiers volumineux sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par -`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total d’amorçage injecté +`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total du bootstrap injecté sur l’ensemble des fichiers est plafonné par `agents.defaults.bootstrapTotalMaxChars` -(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. Lorsqu’une troncature -se produit, OpenClaw peut injecter un bloc d’avertissement dans Contexte du projet ; contrôlez cela avec -`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; -par défaut : `once`). +(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. En cas de troncature, +OpenClaw peut injecter un bloc d’avertissement dans Project Context ; contrôlez cela avec +`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; +par défaut : `once`). -Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers d’amorçage +Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers de bootstrap sont filtrés pour garder le contexte du sous-agent réduit). Les hooks internes peuvent intercepter cette étape via `agent:bootstrap` pour modifier ou remplacer -les fichiers d’amorçage injectés (par exemple en remplaçant `SOUL.md` par une persona alternative). +les fichiers de bootstrap injectés (par exemple en remplaçant `SOUL.md` par un persona alternatif). -Si vous souhaitez rendre l’agent moins générique, commencez par le +Si vous souhaitez que l’agent paraisse moins générique, commencez par [Guide de personnalité SOUL.md](/fr/concepts/soul). -Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge du schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context). +Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge de schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context). ## Gestion du temps -Le prompt système inclut une section dédiée **Date et heure actuelles** lorsque le -fuseau horaire de l’utilisateur est connu. Pour garder le cache du prompt stable, elle n’inclut désormais que le -**fuseau horaire** (pas d’horloge dynamique ni de format d’heure). +Le prompt système inclut une section dédiée **Current Date & Time** lorsque le +fuseau horaire de l’utilisateur est connu. Pour garder le cache de prompt stable, il n’inclut désormais que le +**fuseau horaire** (sans horloge dynamique ni format horaire). -Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte d’état -inclut une ligne d’horodatage. Le même outil peut aussi définir une substitution de modèle par session -(`model=default` la supprime). +Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte d’état +inclut une ligne d’horodatage. Le même outil peut aussi définir un remplacement de modèle par session +(`model=default` l’efface). -Configurez avec : +Configurez avec : - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Voir [Date et heure](/fr/date-time) pour tous les détails du comportement. +Voir [Date & Time](/fr/date-time) pour tous les détails de comportement. ## Skills -Lorsque des Skills éligibles existent, OpenClaw injecte une **liste compacte des Skills disponibles** -(`formatSkillsForPrompt`) qui inclut le **chemin du fichier** pour chaque Skill. Le +Lorsque des Skills admissibles existent, OpenClaw injecte une **liste compacte des Skills disponibles** +(`formatSkillsForPrompt`) qui inclut le **chemin de fichier** pour chaque Skill. Le prompt indique au modèle d’utiliser `read` pour charger le SKILL.md à l’emplacement indiqué -(espace de travail, géré ou intégré). Si aucune Skill n’est éligible, la section -Skills est omise. +(espace de travail, géré ou intégré). Si aucun Skill n’est admissible, la +section Skills est omise. -L’éligibilité comprend les garde-fous des métadonnées des Skills, les vérifications d’environnement/configuration d’exécution, +L’admissibilité inclut les conditions des métadonnées des Skills, les vérifications de l’environnement/configuration du runtime, et la liste d’autorisation effective des Skills de l’agent lorsque `agents.defaults.skills` ou `agents.list[].skills` est configuré. @@ -176,13 +176,26 @@ et la liste d’autorisation effective des Skills de l’agent lorsque `agents.d ``` -Cela maintient un prompt de base réduit tout en permettant une utilisation ciblée des Skills. +Cela permet de conserver un prompt de base réduit tout en rendant possible une utilisation ciblée des Skills. + +Le budget de la liste des Skills appartient au sous-système des Skills : + +- Valeur globale par défaut : `skills.limits.maxSkillsPromptChars` +- Remplacement par agent : `agents.list[].skillsLimits.maxSkillsPromptChars` + +Les extraits runtime génériques bornés utilisent une autre surface : + +- `agents.defaults.contextLimits.*` +- `agents.list[].contextLimits.*` + +Cette séparation permet de découpler le dimensionnement des Skills de celui de la lecture/injection au runtime +comme `memory_get`, les résultats d’outil en direct et les actualisations de `AGENTS.md` après Compaction. ## Documentation -Lorsque disponible, le prompt système inclut une section **Documentation** qui pointe vers le -répertoire local de documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du +Lorsqu’elle est disponible, le prompt système inclut une section **Documentation** qui pointe vers le +répertoire local de la documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du package npm intégré) et mentionne également le miroir public, le dépôt source, le Discord de la communauté et ClawHub ([https://clawhub.ai](https://clawhub.ai)) pour la découverte des Skills. Le prompt indique au modèle de consulter d’abord la documentation locale pour le comportement, les commandes, la configuration ou l’architecture d’OpenClaw, et d’exécuter -`openclaw status` lui-même lorsque c’est possible (en demandant à l’utilisateur seulement lorsqu’il n’y a pas accès). +lui-même `openclaw status` lorsque c’est possible (en ne demandant à l’utilisateur que lorsqu’il n’y a pas accès). diff --git a/docs/fr/gateway/configuration-reference.md b/docs/fr/gateway/configuration-reference.md index b57c7e9b9..abb8b312d 100644 --- a/docs/fr/gateway/configuration-reference.md +++ b/docs/fr/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Vous avez besoin de la sémantique exacte de la configuration au niveau des champs ou des valeurs par défaut. - - Vous validez des blocs de configuration de canal, de modèle, de Gateway ou d’outil. -summary: Référence de configuration du Gateway pour les clés 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 configuration au niveau des champs ou des valeurs par défaut + - Vous validez des blocs de configuration de canal, de modèle, de Gateway ou d’outil +summary: Référence de configuration de Gateway pour les clés OpenClaw principales, les valeurs par défaut et les liens vers les références dédiées des sous-systèmes title: Référence de configuration x-i18n: - generated_at: "2026-04-15T14:40:31Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba + source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: Référence de configuration principale pour `~/.openclaw/openclaw.json`. Pour une vue d’ensemble orientée tâches, voir [Configuration](/fr/gateway/configuration). -Cette page couvre les principales surfaces de configuration d’OpenClaw et renvoie vers d’autres pages lorsqu’un sous-système dispose de sa propre référence plus détaillée. Elle **n’essaie pas** d’intégrer sur une seule page l’intégralité du catalogue de commandes propre à chaque canal/Plugin, ni tous les réglages avancé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 possède sa propre référence plus détaillée. Elle **n’essaie pas** d’inclure sur une seule page chaque catalogue de commandes propre à un canal/Plugin ni chaque paramètre avancé de mémoire/QMD. 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 fusionnées des bundles/Plugins/canaux lorsqu’elles sont disponibles +- `openclaw config schema` affiche le JSON Schema en direct utilisé pour la validation et l’interface utilisateur de contrôle, avec les métadonnées des éléments groupés/Plugin/canaux fusionnées lorsqu’elles sont disponibles - `config.schema.lookup` renvoie un nœud de schéma limité à un chemin pour les outils d’exploration détaillée -- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hash de référence des docs de configuration par rapport à la surface de schéma actuelle +- `pnpm config:docs:check` / `pnpm config:docs:gen` valident le hachage de référence de la documentation de configuration par rapport à la surface de schéma actuelle Références détaillées dédiées : -- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` et la configuration de Dreaming sous `plugins.entries.memory-core.config.dreaming` -- [Commandes slash](/fr/tools/slash-commands) pour le catalogue actuel des commandes intégrées + bundle -- pages du canal/Plugin propriétaire pour les surfaces de commandes spécifiques à un canal +- [Référence de configuration de la mémoire](/fr/reference/memory-config) pour `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, et la configuration de Dreaming sous `plugins.entries.memory-core.config.dreaming` +- [Commandes Slash](/fr/tools/slash-commands) pour le catalogue actuel des commandes intégrées + groupées +- pages du canal/Plugin propriétaire pour les surfaces de commandes spécifiques au canal -Le format de configuration est **JSON5** (commentaires + virgules finales autorisés). Tous les champs sont facultatifs — OpenClaw utilise des valeurs par défaut sûres lorsqu’ils sont omis. +Le format de configuration est **JSON5** (commentaires + virgules finales autorisés). Tous les champs sont facultatifs — OpenClaw utilise des valeurs par défaut sûres lorsqu’ils sont omis. --- @@ -39,32 +39,32 @@ Le format de configuration est **JSON5** (commentaires + virgules finales autori Chaque canal démarre automatiquement lorsque sa section de configuration existe (sauf si `enabled: false`). -### Accès DM et groupe +### Accès aux messages privés et aux groupes -Tous les canaux prennent en charge des politiques pour les DM et des politiques pour les groupes : +Tous les canaux prennent en charge des politiques pour les messages privés et les groupes : -| 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 stockage d’autorisations appairées) | -| `open` | Autoriser tous les DM entrants (nécessite `allowFrom: ["*"]`) | -| `disabled` | Ignorer tous les DM entrants | +| Politique de MP | Comportement | +| -------------------- | --------------------------------------------------------------- | +| `pairing` (par défaut) | Les expéditeurs inconnus reçoivent un code d’association à usage unique ; le propriétaire doit approuver | +| `allowlist` | Uniquement les expéditeurs dans `allowFrom` (ou dans le stockage d’autorisation associé) | +| `open` | Autoriser tous les MP entrants (nécessite `allowFrom: ["*"]`) | +| `disabled` | Ignorer tous les MP entrants | | Politique de groupe | Comportement | | ---------------------- | ------------------------------------------------------ | -| `allowlist` (par défaut) | Uniquement les groupes correspondant à la liste d’autorisations configurée | -| `open` | Contourner les listes d’autorisations de groupe (le filtrage par mention s’applique toujours) | +| `allowlist` (par défaut) | Uniquement les groupes correspondant à la liste d’autorisation configurée | +| `open` | Contourner les listes d’autorisation de groupe (le filtrage par mention s’applique toujours) | | `disabled` | Bloquer tous les messages de groupe/salon | -`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 de fournisseur est entièrement absent (`channels.` absent), la politique de groupe d’exécution revient à `allowlist` (échec fermé) avec un avertissement au démarrage. +`channels.defaults.groupPolicy` définit la valeur par défaut lorsque `groupPolicy` d’un fournisseur n’est pas défini. +Les codes d’association expirent après 1 heure. Les demandes d’association de MP en attente sont limitées à **3 par canal**. +Si un bloc de fournisseur est entièrement absent (`channels.` absent), la politique de groupe à l’exécution revient à `allowlist` (échec sécurisé) avec un avertissement au démarrage. ### 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 mapping de canal s’applique lorsqu’une session n’a pas déjà de remplacement de modèle (par exemple défini via `/model`). +Utilisez `channels.modelByChannel` pour épingler des ID de canal spécifiques à un modèle. Les valeurs acceptent `provider/model` ou des alias de modèle configurés. Le mappage du canal s’applique lorsqu’une session n’a pas déjà un remplacement de modèle (par exemple défini via `/model`). ```json5 { @@ -106,14 +106,14 @@ Utilisez `channels.defaults` pour le comportement partagé de politique de group ``` - `channels.defaults.groupPolicy` : politique de groupe de repli lorsqu’un `groupPolicy` au niveau du fournisseur n’est pas défini. -- `channels.defaults.contextVisibility` : mode par défaut de visibilité du contexte supplémentaire pour tous les canaux. Valeurs : `all` (par défaut, inclure tout le contexte cité/de fil/d’historique), `allowlist` (inclure uniquement le contexte des expéditeurs autorisés), `allowlist_quote` (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk` : inclure les statuts de canaux sains dans la sortie du Heartbeat. -- `channels.defaults.heartbeat.showAlerts` : inclure les statuts dégradés/en erreur dans la sortie du Heartbeat. -- `channels.defaults.heartbeat.useIndicator` : afficher une sortie de Heartbeat compacte de type indicateur. +- `channels.defaults.contextVisibility` : mode de visibilité du contexte supplémentaire par défaut pour tous les canaux. Valeurs : `all` (par défaut, inclure tout le contexte cité/de fil/d’historique), `allowlist` (inclure uniquement le contexte des expéditeurs autorisés), `allowlist_quote` (identique à allowlist mais conserve le contexte explicite de citation/réponse). Remplacement par canal : `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk` : inclure les états de canaux sains dans la sortie Heartbeat. +- `channels.defaults.heartbeat.showAlerts` : inclure les états dégradés/en erreur dans la sortie Heartbeat. +- `channels.defaults.heartbeat.useIndicator` : afficher une sortie Heartbeat compacte sous forme d’indicateur. ### WhatsApp -WhatsApp s’exécute via le canal web du Gateway (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. +WhatsApp fonctionne via le canal web de la Gateway (Baileys Web). Il démarre automatiquement lorsqu’une session liée existe. ```json5 { @@ -124,7 +124,7 @@ WhatsApp s’exécute via le canal web du Gateway (Baileys Web). Il démarre aut textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // coches bleues (false en mode discussion avec soi-même) groups: { "*": { requireMention: true }, }, @@ -165,8 +165,8 @@ WhatsApp s’exécute via le canal web du Gateway (Baileys Web). Il démarre aut ``` - 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 du compte par défaut de repli lorsqu’il correspond à un ID de compte configuré. -- L’ancien répertoire d’authentification Baileys à compte unique est migré par `openclaw doctor` vers `whatsapp/default`. +- `channels.whatsapp.defaultAccount` facultatif remplace cette sélection de compte par défaut de repli lorsqu’il correspond à un ID de compte configuré. +- 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 du Gateway (Baileys Web). Il démarre aut } ``` -- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier classique uniquement ; les liens symboliques sont rejetés), avec `TELEGRAM_BOT_TOKEN` comme repli pour le compte par défaut. +- Jeton du bot : `channels.telegram.botToken` ou `channels.telegram.tokenFile` (fichier normal uniquement ; les liens symboliques sont refusés), avec `TELEGRAM_BOT_TOKEN` comme repli pour le compte par défaut. - `channels.telegram.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. -- Dans les configurations multi-comptes (2 ID de compte ou plus), définissez une valeur par défaut explicite (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) pour éviter le routage de repli ; `openclaw doctor` émet un avertissement lorsque cela est manquant ou invalide. -- `configWrites: false` bloque les écritures de configuration initiées par Telegram (migrations d’ID de supergroupe, `/config set|unset`). -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les sujets de forum (utilisez le format canonique `chatId:topic:topicId` dans `match.peer.id`). La sémantique des champs est partagée dans [ACP Agents](/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 repli ; `openclaw doctor` avertit lorsque cela est absent ou invalide. +- `configWrites: false` bloque les écritures de configuration déclenchées depuis Telegram (migrations d’ID de supergroupe, `/config set|unset`). +- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les sujets de forum (utilisez le format canonique `chatId:topic:topicId` dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings). - Les aperçus de flux Telegram utilisent `sendMessage` + `editMessageText` (fonctionne dans les discussions directes et de groupe). - Politique de nouvelle tentative : voir [Politique de nouvelle tentative](/fr/concepts/retry). @@ -336,33 +336,33 @@ WhatsApp s’exécute via le canal web du Gateway (Baileys Web). Il démarre aut - Jeton : `channels.discord.token`, avec `DISCORD_BOT_TOKEN` comme repli pour le compte par défaut. - Les appels sortants directs qui fournissent un `token` Discord explicite utilisent ce jeton pour l’appel ; les paramètres de nouvelle tentative/politique du compte proviennent toujours du compte sélectionné dans l’instantané d’exécution actif. - `channels.discord.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. -- Utilisez `user:` (DM) ou `channel:` (canal de guilde) pour les cibles de livraison ; les ID numériques bruts sont rejetés. -- Les slugs de guilde 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 guilde. -- Les messages rédigés par des bots sont ignorés par défaut. `allowBots: true` les active ; utilisez `allowBots: "mentions"` pour n’accepter que les messages de bot 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 hauts même lorsqu’ils font moins de 2000 caractères. +- Utilisez `user:` (MP) ou `channel:` (canal de serveur) comme cibles de livraison ; les ID numériques nus sont refusés. +- Les slugs de serveur sont en minuscules avec les espaces remplacés par `-` ; les clés de canal utilisent le nom sous forme de slug (sans `#`). Préférez les ID de serveur. +- Les messages rédigés par des bots sont ignorés par défaut. `allowBots: true` les active ; utilisez `allowBots: "mentions"` pour n’accepter que les messages de bots qui mentionnent le bot (les propres messages restent filtrés). +- `channels.discord.guilds..ignoreOtherMentions` (et les remplacements de canal) ignore les messages qui mentionnent un autre utilisateur ou rôle mais pas le bot (à l’exclusion de @everyone/@here). +- `maxLinesPerMessage` (17 par défaut) découpe les messages trop longs en lignes, même lorsqu’ils font moins de 2000 caractères. - `channels.discord.threadBindings` contrôle le routage lié aux fils Discord : - `enabled` : remplacement Discord pour les fonctionnalités de session liées aux fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, ainsi que la livraison/le routage liés) - `idleHours` : remplacement Discord pour le retrait automatique du focus après inactivité, en heures (`0` désactive) - - `maxAgeHours` : remplacement Discord pour l’âge maximal strict en heures (`0` désactive) - - `spawnSubagentSessions` : option d’activation pour la création/la liaison automatiques de fils avec `sessions_spawn({ thread: true })` -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et les fils (utilisez l’ID du canal/fil dans `match.peer.id`). La sémantique des champs est partagée dans [ACP Agents](/fr/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` définit la couleur d’accentuation pour les conteneurs Discord components v2. -- `channels.discord.voice` active les conversations dans les canaux vocaux Discord ainsi que les remplacements facultatifs d’auto-jonction et de TTS. + - `maxAgeHours` : remplacement Discord pour l’âge maximal strict, en heures (`0` désactive) + - `spawnSubagentSessions` : option d’activation pour la création/liaison automatique de fils par `sessions_spawn({ thread: true })` +- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` configurent des liaisons ACP persistantes pour les canaux et fils (utilisez l’ID du canal/fil dans `match.peer.id`). La sémantique des champs est partagée dans [Agents ACP](/fr/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` définit la couleur d’accentuation des conteneurs de composants Discord v2. +- `channels.discord.voice` active les conversations dans les canaux vocaux Discord ainsi que les remplacements facultatifs d’auto-jonction + TTS. - `channels.discord.voice.daveEncryption` et `channels.discord.voice.decryptionFailureTolerance` sont transmis aux options DAVE de `@discordjs/voice` (`true` et `24` par défaut). -- OpenClaw tente également une récupération de la réception vocale en quittant puis en rejoignant à nouveau une session vocale après des échecs répétés de déchiffrement. +- OpenClaw tente également une récupération de la réception vocale en quittant/rejoignant une session vocale après des échecs répétés de déchiffrement. - `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é d’exécution à la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et autorise des remplacements facultatifs du texte de statut. -- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag mutable (mode de compatibilité d’urgence). -- `channels.discord.execApprovals` : livraison d’approbation exec native à Discord et autorisation des approbateurs. - - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations exec s’activent lorsque les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers` : ID d’utilisateurs Discord autorisés à approuver les requêtes exec. Revient à `commands.ownerAllowFrom` lorsqu’il est omis. - - `agentFilter` : liste d’autorisations facultative d’ID d’agents. Omettez-le pour transférer les approbations pour tous les agents. +- `channels.discord.autoPresence` mappe la disponibilité à l’exécution à la présence du bot (healthy => online, degraded => idle, exhausted => dnd) et permet des remplacements facultatifs du texte d’état. +- `channels.discord.dangerouslyAllowNameMatching` réactive la correspondance par nom/tag mutable (mode de compatibilité de dernier recours). +- `channels.discord.execApprovals` : livraison native Discord des approbations d’exécution et autorisation des approbateurs. + - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations d’exécution s’activent lorsque les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers` : ID d’utilisateurs Discord autorisés à approuver les demandes d’exécution. Utilise `commands.ownerAllowFrom` comme repli lorsqu’il est omis. + - `agentFilter` : liste d’autorisation facultative des ID d’agent. Omettez-le pour transférer les approbations pour tous les agents. - `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex). - - `target` : emplacement d’envoi des invites d’approbation. `"dm"` (par défaut) les envoie aux DM des approbateurs, `"channel"` les envoie au canal d’origine, `"both"` les envoie aux deux. Lorsque la cible inclut `"channel"`, les boutons ne peuvent être utilisés que par les approbateurs résolus. - - `cleanupAfterResolve` : lorsqu’il vaut `true`, supprime les DM d’approbation après approbation, refus ou expiration. + - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut) envoie aux MP des approbateurs, `"channel"` envoie au canal d’origine, `"both"` envoie aux deux. Lorsque la cible inclut `"channel"`, les boutons ne sont utilisables que par les approbateurs résolus. + - `cleanupAfterResolve` : lorsque `true`, supprime les MP d’approbation après approbation, refus ou expiration. -**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 de réaction :** `off` (aucune), `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 du Gateway (Baileys Web). Il démarre aut } ``` -- JSON du compte de service : inline (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`). -- Le SecretRef du compte de service est également pris en charge (`serviceAccountRef`). +- JSON de compte de service : en ligne (`serviceAccount`) ou basé sur un fichier (`serviceAccountFile`). +- SecretRef de compte de service également pris en charge (`serviceAccountRef`). - Variables d’environnement de repli : `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Utilisez `spaces/` ou `users/` pour les cibles de livraison. -- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance mutable du principal d’e-mail (mode de compatibilité d’urgence). +- Utilisez `spaces/` ou `users/` comme cibles de livraison. +- `channels.googlechat.dangerouslyAllowNameMatching` réactive la correspondance mutable du principal d’e-mail (mode de compatibilité de dernier recours). ### Slack @@ -464,34 +464,39 @@ WhatsApp s’exécute via le canal web du Gateway (Baileys Web). Il démarre aut } ``` -- Le **mode Socket** nécessite à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le repli d’environnement du compte par défaut). +- Le **mode socket** nécessite à la fois `botToken` et `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` pour le repli par variable d’environnement du compte par défaut). - Le **mode HTTP** nécessite `botToken` plus `signingSecret` (à la racine ou par compte). -- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes 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 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 par Slack. +- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes de caractères en clair + ou des objets SecretRef. +- Les instantanés de compte Slack exposent des champs de source/statut par identifiant + tels que `botTokenSource`, `botTokenStatus`, `appTokenStatus` et, en mode HTTP, + `signingSecretStatus`. `configured_unavailable` signifie que le compte est + configuré via SecretRef mais que le chemin actuel de commande/d’exécution n’a pas pu + résoudre la valeur du secret. +- `configWrites: false` bloque les écritures de configuration déclenchées depuis Slack. - `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 streaming natif de Slack. Les anciennes valeurs `streamMode`, booléennes `streaming` et `nativeStreaming` sont migrées automatiquement. -- Utilisez `user:` (DM) ou `channel:` pour les cibles de livraison. +- `channels.slack.streaming.mode` est la clé canonique du mode de flux Slack. `channels.slack.streaming.nativeTransport` contrôle le transport de flux natif de Slack. Les anciennes valeurs `streamMode`, booléennes `streaming` et `nativeStreaming` sont migrées automatiquement. +- Utilisez `user:` (MP) ou `channel:` pour les cibles de livraison. **Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). -**Isolation de session de fil :** `thread.historyScope` est par fil (par défaut) ou partagé à l’échelle du canal. `thread.inheritParent` copie la transcription du canal parent dans les nouveaux fils. +**Isolation de session de fil :** `thread.historyScope` est par fil (par défaut) ou partagé avec le canal. `thread.inheritParent` copie la transcription du canal parent vers les nouveaux fils. -- Le streaming natif Slack ainsi que le statut de fil Slack de type assistant « is typing... » nécessitent une cible de réponse en 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. +- Le flux natif Slack ainsi que l’état de fil de type assistant Slack « is typing... » nécessitent une cible de réponse dans un fil. Les MP de niveau supérieur restent hors fil par défaut ; ils utilisent donc `typingReaction` ou la livraison normale au lieu de l’aperçu de style fil. - `typingReaction` ajoute une réaction temporaire au message Slack entrant pendant qu’une réponse est en cours, puis la supprime à la fin. Utilisez un shortcode d’emoji Slack tel que `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals` : livraison d’approbation exec native à Slack et autorisation des approbateurs. Même schéma que Discord : `enabled` (`true`/`false`/`"auto"`), `approvers` (ID d’utilisateurs Slack), `agentFilter`, `sessionFilter` et `target` (`"dm"`, `"channel"` ou `"both"`). +- `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 | | ---------------- | ---------- | ------------------------ | | reactions | activé | Réagir + lister les réactions | | messages | activé | Lire/envoyer/modifier/supprimer | | pins | activé | Épingler/désépingler/lister | -| memberInfo | activé | Informations de membre | -| emojiList | activé | Liste d’emoji personnalisés | +| memberInfo | activé | Informations sur le membre | +| emojiList | activé | Liste des emoji personnalisés | ### Mattermost -Mattermost est fourni comme Plugin : `openclaw plugins install @openclaw/mattermost`. +Mattermost est distribué comme un Plugin : `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -521,16 +526,21 @@ Mattermost est fourni comme Plugin : `openclaw plugins install @openclaw/matter } ``` -Modes de chat : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe de déclenchement). +Modes de discussion : `oncall` (répond sur @-mention, par défaut), `onmessage` (chaque message), `onchar` (messages commençant par un préfixe de déclenchement). 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 se résoudre vers le point de terminaison du Gateway OpenClaw et être accessible depuis le serveur Mattermost. -- Les callbacks slash natifs sont authentifiés avec les jetons par commande renvoyés par Mattermost lors de l’enregistrement de la commande slash. Si l’enregistrement échoue ou si aucune commande n’est activée, OpenClaw rejette les callbacks avec `Unauthorized: invalid command token.` -- Pour les hôtes de callback privés/tailnet/internes, Mattermost peut exiger que `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/le domaine du callback. Utilisez des valeurs d’hôte/domaine, pas des URL complètes. -- `channels.mattermost.configWrites` : autorise ou refuse les écritures de configuration initiées par Mattermost. -- `channels.mattermost.requireMention` : exige `@mention` avant de répondre dans les canaux. +- `commands.callbackUrl` doit pointer vers le point de terminaison Gateway OpenClaw et être accessible depuis le serveur Mattermost. +- Les rappels slash natifs sont authentifiés avec les jetons par commande renvoyés + par Mattermost lors de l’enregistrement des commandes slash. Si l’enregistrement échoue ou si aucune + commande n’est activée, OpenClaw rejette les rappels avec + `Unauthorized: invalid command token.` +- Pour les hôtes de rappel privés/tailnet/internes, Mattermost peut nécessiter que + `ServiceSettings.AllowedUntrustedInternalConnections` inclue l’hôte/le domaine de rappel. + Utilisez des valeurs d’hôte/domaine, pas des URL complètes. +- `channels.mattermost.configWrites` : autoriser ou refuser les écritures de configuration déclenchées depuis Mattermost. +- `channels.mattermost.requireMention` : exiger une `@mention` avant de répondre dans les canaux. - `channels.mattermost.groups..requireMention` : remplacement du filtrage par mention par canal (`"*"` pour la valeur par défaut). - `channels.mattermost.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. @@ -556,12 +566,12 @@ Lorsque les commandes natives Mattermost sont activées : **Modes de notification de réaction :** `off`, `own` (par défaut), `all`, `allowlist` (depuis `reactionAllowlist`). - `channels.signal.account` : épingle le démarrage du canal à une identité de compte Signal spécifique. -- `channels.signal.configWrites` : autorise ou refuse les écritures de configuration initiées par Signal. +- `channels.signal.configWrites` : autorise ou refuse les écritures de configuration déclenché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 -BlueBubbles est le chemin iMessage recommandé (pris en charge par Plugin, configuré sous `channels.bluebubbles`). +BlueBubbles est le chemin iMessage recommandé (pris en charge par un Plugin, configuré sous `channels.bluebubbles`). ```json5 { @@ -578,12 +588,12 @@ 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 des conversations BlueBubbles à des sessions ACP persistantes. Utilisez un handle BlueBubbles ou une chaîne cible (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique de champ partagée : [ACP Agents](/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 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). - La configuration complète du canal BlueBubbles est documentée dans [BlueBubbles](/fr/channels/bluebubbles). ### iMessage -OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun daemon ni port n’est requis. +OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun démon ni port requis. ```json5 { @@ -611,11 +621,11 @@ OpenClaw lance `imsg rpc` (JSON-RPC sur stdio). Aucun daemon 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 via SCP. -- `attachmentRoots` et `remoteAttachmentRoots` restreignent les chemins des pièces jointes entrantes (par défaut : `/Users/*/Library/Messages/Attachments`). +- `cliPath` peut pointer vers un wrapper SSH ; définissez `remoteHost` (`host` ou `user@host`) pour la récupération des pièces jointes par SCP. +- `attachmentRoots` et `remoteAttachmentRoots` limitent les chemins des pièces jointes entrantes (par défaut : `/Users/*/Library/Messages/Attachments`). - SCP utilise une vérification stricte de la clé d’hôte ; assurez-vous donc que la clé d’hôte du relais existe déjà dans `~/.ssh/known_hosts`. -- `channels.imessage.configWrites` : autorise ou refuse les écritures de configuration initiées par iMessage. -- Les entrées `bindings[]` de niveau supérieur avec `type: "acp"` peuvent lier des conversations iMessage à des sessions ACP persistantes. Utilisez un handle normalisé ou une cible de discussion explicite (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dans `match.peer.id`. Sémantique de champ partagée : [ACP Agents](/fr/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites` : autorise ou refuse les écritures de configuration déclenché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). @@ -628,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix est pris en charge par extension et configuré sous `channels.matrix`. +Matrix est pris en charge par une extension et configuré sous `channels.matrix`. ```json5 { @@ -659,24 +669,24 @@ Matrix est pris en charge par extension et configuré sous `channels.matrix`. ``` - L’authentification par jeton utilise `accessToken` ; l’authentification par mot de passe utilise `userId` + `password`. -- `channels.matrix.proxy` route le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette activation réseau sont des contrôles indépendants. +- `channels.matrix.proxy` achemine le trafic HTTP Matrix via un proxy HTTP(S) explicite. Les comptes nommés peuvent le remplacer avec `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` autorise les homeservers privés/internes. `proxy` et cette option réseau explicite 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`, donc les salons invités et les nouvelles invitations de type DM sont ignorés tant que vous ne définissez pas `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals` : livraison d’approbation exec native à Matrix et autorisation des approbateurs. - - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations exec s’activent lorsque les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers` : ID d’utilisateurs Matrix (par exemple `@owner:example.org`) autorisés à approuver les requêtes exec. - - `agentFilter` : liste d’autorisations facultative d’ID d’agents. Omettez-le pour transférer les approbations pour tous les agents. +- `channels.matrix.autoJoin` vaut `off` par défaut ; ainsi, les salons invités et les nouvelles invitations de type MP sont ignorés jusqu’à ce que vous définissiez `autoJoin: "allowlist"` avec `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals` : livraison native Matrix des approbations d’exécution et autorisation des approbateurs. + - `enabled` : `true`, `false` ou `"auto"` (par défaut). En mode auto, les approbations d’exécution s’activent lorsque les approbateurs peuvent être résolus à partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers` : ID d’utilisateurs Matrix (par ex. `@owner:example.org`) autorisés à approuver les demandes d’exécution. + - `agentFilter` : liste d’autorisation facultative des ID d’agent. Omettez-le pour transférer les approbations pour tous les agents. - `sessionFilter` : motifs facultatifs de clé de session (sous-chaîne ou regex). - - `target` : emplacement d’envoi des invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`. + - `target` : où envoyer les invites d’approbation. `"dm"` (par défaut), `"channel"` (salon d’origine) ou `"both"`. - Remplacements par compte : `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` contrôle la manière dont les DM Matrix sont groupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon DM. -- Les sondes d’état Matrix et les recherches de répertoire en direct utilisent la même politique de proxy que le trafic d’exécution. +- `channels.matrix.dm.sessionScope` contrôle la manière dont les MP Matrix sont regroupés en sessions : `per-user` (par défaut) partage par pair routé, tandis que `per-room` isole chaque salon de MP. +- Les sondes d’état Matrix et les recherches en direct dans l’annuaire utilisent la même politique de proxy que le trafic d’exécution. - La configuration complète de Matrix, les règles de ciblage et des exemples d’installation sont documentés dans [Matrix](/fr/channels/matrix). ### Microsoft Teams -Microsoft Teams est pris en charge par extension et configuré sous `channels.msteams`. +Microsoft Teams est pris en charge par une extension et configuré sous `channels.msteams`. ```json5 { @@ -692,11 +702,11 @@ Microsoft Teams est pris en charge par extension et configuré sous `channels.ms ``` - Chemins de clés principaux couverts ici : `channels.msteams`, `channels.msteams.configWrites`. -- La configuration complète de Teams (identifiants, webhook, politique DM/groupe, remplacements par équipe/par canal) est documentée dans [Microsoft Teams](/fr/channels/msteams). +- La configuration complète de Teams (identifiants, Webhook, politique MP/groupe, remplacements par équipe/par canal) est documentée dans [Microsoft Teams](/fr/channels/msteams). ### IRC -IRC est pris en charge par extension et configuré sous `channels.irc`. +IRC est pris en charge par une extension et configuré sous `channels.irc`. ```json5 { @@ -719,9 +729,9 @@ IRC est pris en charge par extension et configuré sous `channels.irc`. - Chemins de clés principaux couverts ici : `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. - `channels.irc.defaultAccount` facultatif remplace la sélection du compte par défaut lorsqu’il correspond à un ID de compte configuré. -- La configuration complète du canal IRC (hôte/port/TLS/canaux/listes d’autorisations/filtrage par mention) est documentée dans [IRC](/fr/channels/irc). +- La configuration complète du canal IRC (hôte/port/TLS/canaux/listes d’autorisation/filtrage par mention) est documentée dans [IRC](/fr/channels/irc). -### Multi-comptes (tous les canaux) +### Multi-compte (tous les canaux) Exécutez plusieurs comptes par canal (chacun avec son propre `accountId`) : @@ -745,12 +755,12 @@ Exécutez plusieurs comptes par canal (chacun avec son propre `accountId`) : ``` - `default` est utilisé lorsque `accountId` est omis (CLI + routage). -- Les jetons d’environnement s’appliquent uniquement au compte **default**. -- Les paramètres de canal de base s’appliquent à tous les comptes sauf remplacement par compte. +- Les jetons d’environnement ne s’appliquent qu’au compte **default**. +- Les paramètres de base du canal s’appliquent à tous les comptes sauf remplacement par compte. - Utilisez `bindings[].match.accountId` pour router chaque compte vers un agent différent. -- Si vous ajoutez un compte non par défaut via `openclaw channels add` (ou l’onboarding de canal) tout en étant encore sur une configuration de canal à compte unique de niveau supérieur, OpenClaw promeut d’abord les valeurs à compte unique de niveau supérieur à portée de compte dans le mapping de comptes du canal afin que le compte d’origine continue de fonctionner. La plupart des canaux les déplacent vers `channels..accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante. -- Les liaisons existantes au niveau canal uniquement (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons à portée de compte restent facultatives. -- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs à compte unique de niveau supérieur à portée de compte vers le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante. +- Si vous ajoutez un compte non par défaut via `openclaw channels add` (ou l’onboarding du canal) alors que vous êtes encore sur une configuration de canal mono-compte au niveau supérieur, OpenClaw promeut d’abord les valeurs mono-compte de niveau supérieur à portée de compte dans la map des comptes du canal afin que le compte d’origine continue à fonctionner. La plupart des canaux les déplacent vers `channels..accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante. +- Les liaisons existantes propres au canal (sans `accountId`) continuent de correspondre au compte par défaut ; les liaisons à portée de compte restent facultatives. +- `openclaw doctor --fix` répare également les formes mixtes en déplaçant les valeurs mono-compte de niveau supérieur à portée de compte vers le compte promu choisi pour ce canal. La plupart des canaux utilisent `accounts.default` ; Matrix peut à la place conserver une cible nommée/par défaut existante correspondante. ### Autres canaux d’extension @@ -759,12 +769,12 @@ Voir 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** (mention de métadonnées ou motifs regex sûrs). S’applique aux discussions de groupe WhatsApp, Telegram, Discord, Google Chat et iMessage. +Par défaut, les messages de groupe **nécessitent une mention** (mention dans les 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 self-chat 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 dans les métadonnées** : mentions @ natives de la plateforme. Ignorées en mode discussion avec soi-même sur WhatsApp. +- **Motifs textuels** : motifs regex sûrs dans `agents.list[].groupChat.mentionPatterns`. Les motifs invalides et les répétitions imbriquées non sûres sont ignorés. - Le filtrage par mention n’est appliqué que lorsque la détection est possible (mentions natives ou au moins un motif). ```json5 @@ -778,9 +788,9 @@ Les messages de groupe exigent par défaut une **mention requise** (mention de m } ``` -`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 la désactiver. -#### Limites d’historique des DM +#### Limites d’historique des MP ```json5 { @@ -795,13 +805,13 @@ Les messages de groupe exigent par défaut une **mention requise** (mention de m } ``` -Résolution : remplacement par DM → valeur par défaut du fournisseur → aucune limite (tout est conservé). +Résolution : remplacement par MP → valeur par défaut du fournisseur → aucune limite (tout est conservé). Pris en charge : `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Mode self-chat +#### Mode discussion avec soi-même -Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ignore les @-mentions natives, répond uniquement aux motifs de texte) : +Incluez votre propre numéro dans `allowFrom` pour activer le mode discussion avec soi-même (ignore les mentions @ natives, répond uniquement aux motifs textuels) : ```json5 { @@ -822,7 +832,7 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ig } ``` -### Commandes (gestion des commandes de chat) +### Commands (gestion des commandes de discussion) ```json5 { @@ -851,30 +861,30 @@ Incluez votre propre numéro dans `allowFrom` pour activer le mode self-chat (ig -- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + bundle, voir [Commandes slash](/fr/tools/slash-commands). -- Cette page est une **référence des clés de configuration**, pas le catalogue complet des commandes. Les commandes propres à un canal/Plugin comme QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` et Talk `/voice` sont documentées dans leurs pages de canal/Plugin ainsi que dans [Commandes slash](/fr/tools/slash-commands). -- Les commandes textuelles doivent être des messages **autonomes** avec un `/` en tête. -- `native: "auto"` active les commandes natives pour Discord/Telegram, et laisse Slack désactivé. -- `nativeSkills: "auto"` active les commandes natives de Skills pour Discord/Telegram, et laisse Slack désactivé. +- Ce bloc configure les surfaces de commande. Pour le catalogue actuel des commandes intégrées + groupées, voir [Commandes Slash](/fr/tools/slash-commands). +- Cette page est une **référence des clés de configuration**, pas le catalogue complet des commandes. Les commandes propres à un canal/Plugin, telles que QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` et Talk `/voice`, sont documentées dans leurs pages de canal/Plugin ainsi que dans [Commandes Slash](/fr/tools/slash-commands). +- Les commandes textuelles doivent être des messages **autonomes** avec un `/` initial. +- `native: "auto"` active les commandes natives pour Discord/Telegram, laisse Slack désactivé. +- `nativeSkills: "auto"` active les commandes natives de Skills pour Discord/Telegram, laisse Slack désactivé. - 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 Gateway `chat.send`, 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 du serveur MCP gérée par OpenClaw sous `mcp.servers`. -- `plugins: true` active `/plugins` pour la découverte de Plugin, l’installation et les contrôles d’activation/désactivation. +- `bash: true` active `! ` pour le shell hôte. Nécessite `tools.elevated.enabled` et un expéditeur présent dans `tools.elevated.allowFrom.`. +- `config: true` active `/config` (lit/écrit `openclaw.json`). Pour les clients Gateway `chat.send`, les écritures persistantes `/config set|unset` nécessitent aussi `operator.admin` ; la commande en lecture seule `/config show` reste disponible pour les clients opérateur normaux avec portée d’écriture. +- `mcp: true` active `/mcp` pour la configuration du serveur MCP géré par OpenClaw sous `mcp.servers`. +- `plugins: true` active `/plugins` pour la découverte, l’installation, et les contrôles d’activation/désactivation des plugins. - `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 qui ciblent ce compte (par exemple `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `restart: false` désactive `/restart` et les actions d’outil de redémarrage du Gateway. 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 du propriétaire dans le prompt système. Définissez `ownerDisplaySecret` pour contrôler le hachage. -- `allowFrom` est par fournisseur. Lorsqu’il est défini, c’est la **seule** source d’autorisation (les listes d’autorisations/appairages de canal et `useAccessGroups` sont ignorés). -- `useAccessGroups: false` permet aux commandes de contourner les politiques de groupes d’accès lorsque `allowFrom` n’est pas défini. +- Pour les canaux multi-comptes, `channels..accounts..configWrites` contrôle aussi les écritures qui ciblent ce compte (par exemple `/allowlist --config --account ` ou `/config set channels..accounts....`). +- `restart: false` désactive `/restart` et les actions de l’outil de redémarrage de Gateway. Par défaut : `true`. +- `ownerAllowFrom` est la liste d’autorisation explicite du propriétaire pour les commandes/outils réservés au propriétaire. Elle est distincte de `allowFrom`. +- `ownerDisplay: "hash"` hache les ID de propriétaire dans l’invite système. Définissez `ownerDisplaySecret` pour contrôler le hachage. +- `allowFrom` est défini par fournisseur. Lorsqu’il est défini, c’est la **seule** source d’autorisation (les listes d’autorisation/l’association du canal et `useAccessGroups` sont ignorés). +- `useAccessGroups: false` permet aux commandes de contourner les politiques de groupe d’accès lorsque `allowFrom` n’est pas défini. - Cartographie de la documentation des commandes : - - catalogue intégré + bundle : [Commandes slash](/fr/tools/slash-commands) - - surfaces de commande spécifiques à un canal : [Canaux](/fr/channels) + - catalogue intégré + groupé : [Commandes Slash](/fr/tools/slash-commands) + - surfaces de commande propres au canal : [Canaux](/fr/channels) - commandes QQ Bot : [QQ Bot](/fr/channels/qqbot) - - commandes d’appairage : [Appairage](/fr/channels/pairing) + - commandes d’association : [Pairing](/fr/channels/pairing) - commande de carte LINE : [LINE](/fr/channels/line) - dreaming de memory : [Dreaming](/fr/concepts/dreaming) @@ -896,7 +906,7 @@ Par défaut : `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Racine de dépôt facultative affichée dans la ligne Runtime du prompt système. Si elle n’est pas définie, OpenClaw la détecte automatiquement en remontant depuis le workspace. +Racine de dépôt facultative affichée dans la ligne Runtime de l’invite système. Si elle n’est pas définie, OpenClaw la détecte automatiquement en remontant depuis l’espace de travail. ```json5 { @@ -906,7 +916,7 @@ Racine de dépôt facultative affichée dans la ligne Runtime du prompt système ### `agents.defaults.skills` -Liste d’autorisations par défaut facultative de Skills pour les agents qui ne définissent pas +Liste d’autorisation par défaut facultative de Skills pour les agents qui ne définissent pas `agents.list[].skills`. ```json5 @@ -922,15 +932,15 @@ Liste d’autorisations par défaut facultative de Skills pour les agents qui ne } ``` -- Omettez `agents.defaults.skills` pour des Skills non restreintes 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 aucune Skills. -- Une liste `agents.list[].skills` non vide constitue l’ensemble final pour cet agent ; elle +- Définissez `agents.list[].skills: []` pour n’avoir aucun Skills. +- Une liste non vide dans `agents.list[].skills` est l’ensemble final pour cet agent ; elle ne fusionne pas avec les valeurs par défaut. ### `agents.defaults.skipBootstrap` -Désactive la création automatique des fichiers bootstrap du workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Désactive la création automatique des fichiers bootstrap de l’espace de travail (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -940,9 +950,9 @@ Désactive la création automatique des fichiers bootstrap du workspace (`AGENTS ### `agents.defaults.contextInjection` -Contrôle quand les fichiers bootstrap du workspace sont injectés dans le prompt système. Valeur par défaut : `"always"`. +Contrôle à quel moment les fichiers bootstrap de l’espace de travail sont injectés dans l’invite système. 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 du workspace, ce qui réduit la taille du prompt. Les exécutions Heartbeat et les nouvelles tentatives après Compaction reconstruisent toujours le contexte. +- `"continuation-skip"` : les tours de continuation sûrs (après une réponse terminée de l’assistant) ignorent la réinjection du bootstrap de l’espace de travail, ce qui réduit la taille de l’invite. Les exécutions Heartbeat et les nouvelles tentatives après Compaction reconstruisent toujours le contexte. ```json5 { @@ -952,7 +962,7 @@ Contrôle quand les fichiers bootstrap du workspace sont injectés dans le promp ### `agents.defaults.bootstrapMaxChars` -Nombre maximal de caractères par fichier bootstrap du workspace avant troncature. Valeur par défaut : `20000`. +Nombre maximal de caractères par fichier bootstrap de l’espace de travail avant troncature. Par défaut : `20000`. ```json5 { @@ -962,7 +972,7 @@ Nombre maximal de caractères par fichier bootstrap du workspace avant troncatur ### `agents.defaults.bootstrapTotalMaxChars` -Nombre total maximal de caractères injectés dans l’ensemble des fichiers bootstrap du workspace. Valeur par défaut : `150000`. +Nombre total maximal de caractères injectés sur l’ensemble des fichiers bootstrap de l’espace de travail. Par défaut : `150000`. ```json5 { @@ -973,11 +983,11 @@ Nombre total maximal de caractères injectés dans l’ensemble des fichiers boo ### `agents.defaults.bootstrapPromptTruncationWarning` Contrôle le texte d’avertissement visible par l’agent lorsque le contexte bootstrap est tronqué. -Valeur par défaut : `"once"`. +Par défaut : `"once"`. -- `"off"` : ne jamais injecter de texte d’avertissement dans le prompt système. -- `"once"` : injecter l’avertissement une fois par signature de troncature unique (recommandé). -- `"always"` : injecter l’avertissement à chaque exécution lorsqu’une troncature existe. +- `"off"` : n’injecte jamais de texte d’avertissement dans l’invite système. +- `"once"` : injecte l’avertissement une fois par signature de troncature unique (recommandé). +- `"always"` : injecte l’avertissement à chaque exécution lorsqu’une troncature existe. ```json5 { @@ -985,10 +995,146 @@ Valeur par défaut : `"once"`. } ``` +### Cartographie de propriété du budget de contexte + +OpenClaw possède plusieurs budgets de prompt/contexte à fort volume, et ils sont +volontairement répartis par sous-système au lieu de tous passer par un unique +paramètre générique. + +- `agents.defaults.bootstrapMaxChars` / + `agents.defaults.bootstrapTotalMaxChars` : + injection bootstrap normale de l’espace de travail. +- `agents.defaults.startupContext.*` : + prélude de démarrage ponctuel pour `/new` et `/reset`, y compris les fichiers + récents `memory/*.md` quotidiens. +- `skills.limits.*` : + la liste compacte de Skills injectée dans l’invite système. +- `agents.defaults.contextLimits.*` : + extraits bornés à l’exécution et blocs injectés appartenant à l’exécution. +- `memory.qmd.limits.*` : + dimensionnement des extraits et de l’injection de recherche mémoire indexée. + +Utilisez le remplacement correspondant par agent uniquement lorsqu’un agent a besoin d’un +budget différent : + +- `agents.list[].skillsLimits.maxSkillsPromptChars` +- `agents.list[].contextLimits.*` + +#### `agents.defaults.startupContext` + +Contrôle le prélude de démarrage du premier tour injecté lors des exécutions +simples `/new` et `/reset`. + +```json5 +{ + agents: { + defaults: { + startupContext: { + enabled: true, + applyOn: ["new", "reset"], + dailyMemoryDays: 2, + maxFileBytes: 16384, + maxFileChars: 1200, + maxTotalChars: 2800, + }, + }, + }, +} +``` + +#### `agents.defaults.contextLimits` + +Valeurs partagées par défaut pour les surfaces de contexte bornées à l’exécution. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + memoryGetDefaultLines: 120, + toolResultMaxChars: 16000, + postCompactionMaxChars: 1800, + }, + }, + }, +} +``` + +- `memoryGetMaxChars` : plafond par défaut de l’extrait `memory_get` avant l’ajout + des métadonnées de troncature et de l’avis de continuation. +- `memoryGetDefaultLines` : fenêtre de lignes par défaut de `memory_get` lorsque `lines` est + omis. +- `toolResultMaxChars` : plafond des résultats d’outil en direct utilisé pour les résultats persistés et + la récupération en cas de débordement. +- `postCompactionMaxChars` : plafond d’extrait AGENTS.md utilisé lors de l’injection + d’actualisation après Compaction. + +#### `agents.list[].contextLimits` + +Remplacement par agent pour les paramètres partagés `contextLimits`. Les champs omis héritent +de `agents.defaults.contextLimits`. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + toolResultMaxChars: 16000, + }, + }, + list: [ + { + id: "tiny-local", + contextLimits: { + memoryGetMaxChars: 6000, + toolResultMaxChars: 8000, + }, + }, + ], + }, +} +``` + +#### `skills.limits.maxSkillsPromptChars` + +Plafond global pour la liste compacte de Skills injectée dans l’invite système. Cela +n’affecte pas la lecture à la demande des fichiers `SKILL.md`. + +```json5 +{ + skills: { + limits: { + maxSkillsPromptChars: 18000, + }, + }, +} +``` + +#### `agents.list[].skillsLimits.maxSkillsPromptChars` + +Remplacement par agent pour le budget d’invite des Skills. + +```json5 +{ + agents: { + list: [ + { + id: "tiny-local", + skillsLimits: { + maxSkillsPromptChars: 6000, + }, + }, + ], + }, +} +``` + ### `agents.defaults.imageMaxDimensionPx` -Taille maximale en pixels du côté le plus long d’une image dans les blocs d’image de transcription/d’outil avant les appels au fournisseur. -Valeur par défaut : `1200`. +Taille maximale en pixels du plus long côté de l’image dans les blocs image de transcription/d’outil avant les appels fournisseur. +Par défaut : `1200`. Des valeurs plus faibles réduisent généralement l’utilisation de jetons de vision et la taille de la charge utile des requêtes pour les exécutions riches en captures d’écran. Des valeurs plus élevées préservent davantage de détails visuels. @@ -1001,7 +1147,7 @@ Des valeurs plus élevées préservent davantage de détails visuels. ### `agents.defaults.userTimezone` -Fuseau horaire pour le contexte du prompt système (pas pour les horodatages des messages). Revient au fuseau horaire de l’hôte. +Fuseau horaire pour le contexte de l’invite système (pas les horodatages des messages). Revient au fuseau horaire de l’hôte. ```json5 { @@ -1011,7 +1157,7 @@ Fuseau horaire pour le contexte du prompt système (pas pour les horodatages des ### `agents.defaults.timeFormat` -Format d’heure dans le prompt système. Valeur par défaut : `auto` (préférence de l’OS). +Format d’heure dans l’invite système. Par défaut : `auto` (préférence du système). ```json5 { @@ -1069,47 +1215,48 @@ Format d’heure dans le prompt système. Valeur par défaut : `auto` (préfér ``` - `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 chaîne ne définit que le modèle principal. - La forme objet définit le modèle principal ainsi que les modèles de basculement ordonnés. - `imageModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - Utilisé par le chemin d’outil `image` comme configuration de modèle de vision. - Également utilisé comme routage de repli lorsque le modèle sélectionné/par défaut ne peut pas accepter d’entrée image. - `imageGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par la capacité partagée de génération d’images et toute future surface d’outil/Plugin qui génère des images. - - Valeurs typiques : `google/gemini-3.1-flash-image-preview` pour la génération d’images Gemini native, `fal/fal-ai/flux/dev` pour fal, ou `openai/gpt-image-1` pour OpenAI Images. - - 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/*`). - - S’il est omis, `image_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’images enregistrés, dans l’ordre des ID de fournisseur. + - Utilisé par la capacité partagée de génération d’image et par toute future surface d’outil/Plugin qui génère des images. + - Valeurs typiques : `google/gemini-3.1-flash-image-preview` pour la génération d’image Gemini native, `fal/fal-ai/flux/dev` pour fal, ou `openai/gpt-image-1` pour OpenAI Images. + - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification/la clé API du fournisseur correspondant (par exemple `GEMINI_API_KEY` ou `GOOGLE_API_KEY` pour `google/*`, `OPENAI_API_KEY` pour `openai/*`, `FAL_KEY` pour `fal/*`). + - Si omis, `image_generate` peut quand même déduire une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération d’image enregistrés restants dans l’ordre des ID de fournisseur. - `musicGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par la capacité partagée de génération musicale et l’outil intégré `music_generate`. + - Utilisé par la capacité partagée de génération musicale et par l’outil intégré `music_generate`. - Valeurs typiques : `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.5+`. - - S’il est omis, `music_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale enregistrés, dans l’ordre des ID de fournisseur. - - Si vous sélectionnez directement un provider/model, configurez aussi l’authentification/la clé API du fournisseur correspondant. + - Si omis, `music_generate` peut quand même déduire une valeur par défaut de fournisseur adossée à une authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération musicale enregistrés restants dans l’ordre des ID de fournisseur. + - Si vous sélectionnez directement un fournisseur/modèle, configurez aussi l’authentification/la clé API du fournisseur correspondant. - `videoGenerationModel` : accepte soit une chaîne (`"provider/model"`), soit un objet (`{ primary, fallbacks }`). - - Utilisé par la capacité partagée de génération vidéo et l’outil intégré `video_generate`. + - Utilisé par la capacité partagée de génération vidéo et par l’outil intégré `video_generate`. - Valeurs typiques : `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`. - - S’il est omis, `video_generate` peut quand même déduire une valeur par défaut de fournisseur avec authentification. Il essaie d’abord le fournisseur par défaut actuel, puis les autres fournisseurs de génération vidéo enregistrés, dans l’ordre des ID de fournisseur. - - Si vous sélectionnez directement un 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 au niveau fournisseur `size`, `aspectRatio`, `resolution`, `audio` et `watermark`. + - 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 au niveau du 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. - - S’il est omis, l’outil PDF revient à `imageModel`, puis au modèle de session/par défaut résolu. + - Si omis, l’outil PDF revient à `imageModel`, puis au modèle de session/par défaut résolu. - `pdfMaxBytesMb` : limite de taille PDF par défaut pour l’outil `pdf` lorsque `maxBytesMb` n’est pas transmis au moment de l’appel. -- `pdfMaxPages` : nombre maximal de pages par défaut prises en compte par le mode de repli d’extraction dans l’outil `pdf`. -- `verboseDefault` : niveau verbose par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`. +- `pdfMaxPages` : nombre maximal de pages considéré par défaut par le mode de repli d’extraction dans l’outil `pdf`. +- `verboseDefault` : niveau verbeux par défaut pour les agents. Valeurs : `"off"`, `"on"`, `"full"`. Par défaut : `"off"`. - `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 un fournisseur configuré unique correspondant exactement à cet ID de modèle, 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 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`). +- `model.primary` : format `provider/model` (par ex. `openai/gpt-5.4`). Si vous omettez le fournisseur, OpenClaw essaie d’abord un alias, puis une correspondance unique de fournisseur configuré pour cet ID de modèle exact, et seulement ensuite revient au fournisseur par défaut configuré (comportement de compatibilité obsolète, il est donc préférable d’utiliser explicitement `provider/model`). Si ce fournisseur n’expose plus le modèle par défaut configuré, OpenClaw revient au premier fournisseur/modèle configuré au lieu d’exposer une valeur par défaut obsolète d’un fournisseur supprimé. +- `models` : catalogue et liste d’autorisation des modèles configurés pour `/model`. Chaque entrée peut inclure `alias` (raccourci) et `params` (spécifiques au fournisseur, par exemple `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params` : paramètres globaux par défaut du fournisseur appliqués à tous les modèles. Définis dans `agents.defaults.params` (par ex. `{ cacheRetention: "long" }`). -- Priorité de fusion de `params` (configuration) : `agents.defaults.params` (base globale) est remplacé par `agents.defaults.models["provider/model"].params` (par modèle), puis `agents.list[].params` (ID d’agent correspondant) remplace par clé. Voir [Prompt Caching](/fr/reference/prompt-caching) pour les détails. -- `embeddedHarness` : politique par défaut d’exécution d’agent embarqué de bas niveau. Utilisez `runtime: "auto"` pour laisser les harness de Plugin enregistrés revendiquer les modèles pris en charge, `runtime: "pi"` pour forcer le harness PI intégré, ou un ID de harness enregistré tel que `runtime: "codex"`. Définissez `fallback: "none"` pour désactiver le repli automatique vers PI. -- Les auteurs de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de repli) enregistrent la forme canonique objet et préservent les listes de repli existantes lorsque c’est possible. -- `maxConcurrent` : nombre maximal d’exécutions parallèles d’agents entre les sessions (chaque session reste sérialisée). Par défaut : 4. +- Priorité de fusion de `params` (configuration) : `agents.defaults.params` (base globale) est remplacé par `agents.defaults.models["provider/model"].params` (par modèle), puis `agents.list[].params` (ID d’agent correspondant) remplace par clé. Voir [Mise en cache des invites](/fr/reference/prompt-caching) pour les détails. +- `embeddedHarness` : politique par défaut du runtime d’agent intégré de bas niveau. Utilisez `runtime: "auto"` pour laisser les harnesses de Plugin enregistrés revendiquer les modèles pris en charge, `runtime: "pi"` pour forcer le harness PI intégré, ou un ID de harness enregistré tel que `runtime: "codex"`. Définissez `fallback: "none"` pour désactiver le repli automatique sur PI. +- Les rédacteurs de configuration qui modifient ces champs (par exemple `/models set`, `/models set-image` et les commandes d’ajout/suppression de repli) enregistrent la forme objet canonique et préservent les listes de repli existantes lorsque c’est possible. +- `maxConcurrent` : nombre maximal d’exécutions parallèles d’agents entre les sessions (chaque session reste tout de même sérialisée). Par défaut : 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` contrôle quel exécuteur de 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 intégrés. La plupart des déploiements devraient conserver la valeur par défaut `{ runtime: "auto", fallback: "pi" }`. -Utilisez-le lorsqu’un Plugin de confiance fournit un harness natif, comme le harness d’app-server Codex groupé. +Utilisez-le lorsqu’un Plugin de confiance fournit un harness natif, comme le harness +groupé du serveur d’application Codex. ```json5 { @@ -1126,33 +1273,33 @@ Utilisez-le lorsqu’un Plugin de confiance fournit un harness natif, comme le h ``` - `runtime` : `"auto"`, `"pi"` ou un ID de harness de Plugin enregistré. Le Plugin Codex groupé enregistre `codex`. -- `fallback` : `"pi"` ou `"none"`. `"pi"` conserve le harness PI intégré comme repli de compatibilité. `"none"` fait échouer une sélection de harness de Plugin manquante ou non prise en charge au lieu d’utiliser PI silencieusement. +- `fallback` : `"pi"` ou `"none"`. `"pi"` conserve le harness PI intégré comme repli de compatibilité. `"none"` fait échouer une sélection de harness de Plugin absente ou non prise en charge au lieu d’utiliser silencieusement PI. - Remplacements par variables d’environnement : `OPENCLAW_AGENT_RUNTIME=` remplace `runtime` ; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` désactive le repli PI pour ce processus. - 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 chat embarqué. La génération de médias, la vision, PDF, la musique, la vidéo et TTS utilisent toujours leurs paramètres provider/model. +- Cela ne contrôle que le harness de discussion intégré. La génération de médias, la vision, le PDF, la musique, la vidéo et la TTS utilisent toujours leurs paramètres fournisseur/modèle. -**Raccourcis d’alias intégrés** (ne s’appliquent que lorsque le modèle est dans `agents.defaults.models`) : +**Alias raccourcis intégrés** (ne s’appliquent que lorsque le modèle est dans `agents.defaults.models`) : -| Alias | Modèle | -| ------------------- | ------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| Alias | Modèle | +| ------------------- | -------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | Vos alias configurés ont toujours priorité sur les valeurs par défaut. -Les modèles Z.AI GLM-4.x activent automatiquement le mode thinking sauf si vous définissez `--thinking off` ou définissez vous-même `agents.defaults.models["zai/"].params.thinking`. +Les modèles Z.AI GLM-4.x activent automatiquement le mode thinking sauf si vous définissez `--thinking off` ou si vous définissez vous-même `agents.defaults.models["zai/"].params.thinking`. Les modèles Z.AI activent `tool_stream` par défaut pour le streaming des appels d’outil. Définissez `agents.defaults.models["zai/"].params.tool_stream` sur `false` pour le désactiver. -Les modèles Anthropic Claude 4.6 utilisent par défaut le mode thinking `adaptive` lorsqu’aucun niveau de thinking explicite n’est défini. +Les modèles Anthropic Claude 4.6 utilisent par défaut le mode thinking `adaptive` lorsqu’aucun niveau explicite de thinking n’est défini. ### `agents.defaults.cliBackends` -Backends CLI facultatifs pour les exécutions de repli en mode texte uniquement (sans appels d’outil). Utiles comme solution de secours lorsque les fournisseurs d’API échouent. +Backends CLI facultatifs pour les exécutions de repli texte uniquement (sans appels d’outil). Utiles comme solution de secours lorsque les fournisseurs d’API échouent. ```json5 { @@ -1182,11 +1329,11 @@ Backends CLI facultatifs pour les exécutions de repli en mode texte uniquement - Les backends CLI sont d’abord orientés texte ; les outils sont toujours désactivés. - Les sessions sont prises en charge lorsque `sessionArg` est défini. -- Le passage direct des images est pris en charge lorsque `imageArg` accepte des chemins de fichiers. +- Le passage direct 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 contrôlées sur les prompts. +Remplace l’intégralité de l’invite système assemblée par OpenClaw par une chaîne fixe. À définir au niveau par défaut (`agents.defaults.systemPromptOverride`) ou par agent (`agents.list[].systemPromptOverride`). Les valeurs par agent ont priorité ; une valeur vide ou composée uniquement d’espaces est ignorée. Utile pour des expériences d’invite contrôlées. ```json5 { @@ -1200,7 +1347,7 @@ Remplace tout le prompt système assemblé par OpenClaw par une chaîne fixe. À ### `agents.defaults.heartbeat` -Exécutions périodiques de Heartbeat. +Exécutions périodiques Heartbeat. ```json5 { @@ -1228,14 +1375,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` : lorsqu’il vaut false, omet la section Heartbeat du prompt système et ignore l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Par défaut : `true`. -- `suppressToolErrorWarnings` : lorsqu’il vaut true, supprime les charges utiles d’avertissement d’erreur d’outil pendant les exécutions Heartbeat. -- `timeoutSeconds` : durée maximale en secondes autorisée pour un tour d’agent Heartbeat avant interruption. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. -- `directPolicy` : politique de livraison directe/DM. `allow` (par défaut) autorise la livraison vers une cible directe. `block` supprime la livraison vers une cible directe et émet `reason=dm-blocked`. -- `lightContext` : lorsqu’il vaut true, les exécutions Heartbeat utilisent un contexte bootstrap léger et ne conservent que `HEARTBEAT.md` parmi les fichiers bootstrap du workspace. -- `isolatedSession` : lorsqu’il vaut true, chaque exécution 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 à environ 2–5K jetons. -- Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent quelconque définit `heartbeat`, **seuls ces agents** exécutent des Heartbeat. -- Les Heartbeat exécutent des tours d’agent complets — des intervalles plus courts consomment davantage de jetons. +- `includeSystemPromptSection` : lorsque false, omet la section Heartbeat de l’invite système et ignore l’injection de `HEARTBEAT.md` dans le contexte bootstrap. Par défaut : `true`. +- `suppressToolErrorWarnings` : lorsque true, supprime les charges utiles d’avertissement d’erreur d’outil lors des exécutions Heartbeat. +- `timeoutSeconds` : durée maximale en secondes autorisée pour un tour d’agent Heartbeat avant son interruption. Laissez non défini pour utiliser `agents.defaults.timeoutSeconds`. +- `directPolicy` : politique de livraison directe/MP. `allow` (par défaut) autorise la livraison à cible directe. `block` supprime la livraison à cible directe et émet `reason=dm-blocked`. +- `lightContext` : lorsque true, les exécutions Heartbeat utilisent un contexte bootstrap léger et ne conservent que `HEARTBEAT.md` parmi les fichiers bootstrap de l’espace de travail. +- `isolatedSession` : lorsque true, chaque exécution Heartbeat s’exécute dans une session fraîche sans historique de conversation antérieur. Même modèle d’isolation que le Cron `sessionTarget: "isolated"`. Réduit le coût en jetons par Heartbeat d’environ 100K à environ 2-5K jetons. +- Par agent : définissez `agents.list[].heartbeat`. Lorsqu’un agent définit `heartbeat`, **seuls ces agents** exécutent des Heartbeats. +- Les Heartbeats exécutent des tours complets d’agent — des intervalles plus courts consomment davantage de jetons. ### `agents.defaults.compaction` @@ -1265,19 +1412,19 @@ Exécutions périodiques de Heartbeat. } ``` -- `mode` : `default` ou `safeguard` (résumé par morceaux pour les historiques longs). Voir [Compaction](/fr/concepts/compaction). -- `provider` : ID d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, la fonction `summarize()` du fournisseur est appelée au lieu du résumé LLM intégré. Revient au mode intégré 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 instructions intégrées de conservation des identifiants opaques pendant le résumé de Compaction. +- `mode` : `default` ou `safeguard` (résumé par morceaux pour les longs historiques). Voir [Compaction](/fr/concepts/compaction). +- `provider` : ID d’un Plugin fournisseur de Compaction enregistré. Lorsqu’il est défini, le `summarize()` du fournisseur est appelé au lieu du résumé LLM intégré. Revient à l’implémentation intégrée en cas d’échec. Définir un fournisseur force `mode: "safeguard"`. Voir [Compaction](/fr/concepts/compaction). +- `timeoutSeconds` : nombre maximal de secondes autorisées pour une seule opération de Compaction avant qu’OpenClaw ne l’interrompe. Par défaut : `900`. +- `identifierPolicy` : `strict` (par défaut), `off` ou `custom`. `strict` préfixe des consignes intégrées de conservation des identifiants opaques pendant le résumé de Compaction. - `identifierInstructions` : texte facultatif personnalisé de préservation des identifiants utilisé lorsque `identifierPolicy=custom`. -- `postCompactionSections` : noms facultatifs de sections H2/H3 d’AGENTS.md à réinjecter après Compaction. Valeur par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il n’est pas défini ou est explicitement défini sur cette paire par défaut, les anciens titres `Every Session`/`Safety` sont également acceptés comme solution de repli héritée. -- `model` : remplacement facultatif `provider/model-id` pour le résumé de Compaction uniquement. Utilisez-le lorsque la session principale doit conserver un modèle mais que les résumés de Compaction doivent s’exécuter sur un autre ; lorsqu’il n’est pas défini, la Compaction utilise le modèle principal de la session. -- `notifyUser` : lorsque `true`, envoie un bref avis à l’utilisateur lorsque la Compaction démarre (par exemple, « Compacting context... »). Désactivé par défaut pour garder la Compaction silencieuse. -- `memoryFlush` : tour agentique silencieux avant l’auto-Compaction pour stocker des mémoires durables. Ignoré lorsque le workspace est en lecture seule. +- `postCompactionSections` : noms facultatifs de sections H2/H3 d’AGENTS.md à réinjecter après Compaction. Par défaut : `["Session Startup", "Red Lines"]` ; définissez `[]` pour désactiver la réinjection. Lorsqu’il n’est pas défini ou qu’il est explicitement défini sur cette paire par défaut, les anciens en-têtes `Every Session`/`Safety` sont également acceptés comme solution de repli héritée. +- `model` : remplacement facultatif `provider/model-id` uniquement pour le résumé de Compaction. Utilisez-le lorsque la session principale doit conserver un modèle mais que les résumés de Compaction doivent s’exécuter sur un autre ; lorsqu’il n’est pas défini, la Compaction utilise le modèle principal de la session. +- `notifyUser` : lorsque `true`, envoie une brève notification à l’utilisateur au démarrage de la Compaction (par exemple, « Compacting context... »). Désactivé par défaut pour garder la Compaction silencieuse. +- `memoryFlush` : tour agentique silencieux avant l’auto-Compaction pour stocker des souvenirs durables. Ignoré lorsque l’espace de travail est en lecture seule. ### `agents.defaults.contextPruning` -Élague les **anciens résultats d’outils** du contexte en mémoire avant l’envoi au LLM. **Ne modifie pas** l’historique de session sur disque. +Élague les **anciens résultats d’outil** du contexte en mémoire avant l’envoi au LLM. **Ne modifie pas** l’historique de session sur disque. ```json5 { @@ -1302,22 +1449,22 @@ Exécutions périodiques de Heartbeat. - `mode: "cache-ttl"` active les passes d’élagage. -- `ttl` contrôle la fréquence à laquelle l’élagage peut de nouveau s’exécuter (après la dernière mise à jour du cache). -- L’élagage tronque d’abord légèrement les résultats d’outils surdimensionnés, puis efface complètement les anciens résultats d’outils si nécessaire. +- `ttl` contrôle la fréquence à laquelle l’élagage peut à nouveau s’exécuter (après le dernier contact avec le cache). +- L’élagage raccourcit d’abord légèrement les résultats d’outil trop volumineux, puis efface complètement les anciens résultats d’outil si nécessaire. -**Le tronquage léger** conserve le début + la fin et insère `...` au milieu. +**Soft-trim** conserve le début + la fin et insère `...` au milieu. -**L’effacement complet** remplace l’intégralité du résultat de l’outil par l’espace réservé. +**Hard-clear** remplace l’intégralité du résultat d’outil par le texte de remplacement. Remarques : -- Les blocs d’image ne sont jamais tronqués/effacés. -- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptes exacts de jetons. -- Si le nombre de messages d’assistant est inférieur à `keepLastAssistants`, l’élagage est ignoré. +- Les blocs d’image ne sont jamais raccourcis ni effacés. +- Les ratios sont basés sur les caractères (approximatifs), pas sur des comptages exacts de jetons. +- S’il existe moins de `keepLastAssistants` messages d’assistant, l’élagage est ignoré. -Voir [Élagage de session](/fr/concepts/session-pruning) pour les détails du comportement. +Voir [Élagage de session](/fr/concepts/session-pruning) pour le détail du comportement. ### Streaming par blocs @@ -1335,9 +1482,9 @@ 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. +- Les canaux autres que Telegram nécessitent un `*.blockStreaming: true` explicite pour activer les réponses par blocs. - Remplacements par canal : `channels..blockStreamingCoalesce` (et variantes par compte). Signal/Slack/Discord/Google Chat utilisent par défaut `minChars: 1500`. -- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500ms. Remplacement par agent : `agents.list[].humanDelay`. +- `humanDelay` : pause aléatoire entre les réponses par blocs. `natural` = 800–2500 ms. Remplacement par agent : `agents.list[].humanDelay`. Voir [Streaming](/fr/concepts/streaming) pour le comportement + les détails de découpage. @@ -1363,7 +1510,7 @@ Voir [Indicateurs de saisie](/fr/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sandboxing) pour le guide complet. +Sandboxing facultatif pour l’agent intégré. Voir [Sandboxing](/fr/gateway/sandboxing) pour le guide complet. ```json5 { @@ -1462,48 +1609,48 @@ Sandboxing facultatif pour l’agent embarqué. Voir [Sandboxing](/fr/gateway/sa **Backend :** -- `docker` : environnement Docker local (par défaut) -- `ssh` : environnement distant générique basé sur SSH -- `openshell` : environnement OpenShell +- `docker` : runtime Docker local (par défaut) +- `ssh` : runtime distant générique basé sur SSH +- `openshell` : runtime OpenShell -Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques à l’environnement 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 au format `user@host[:port]` -- `command` : commande client SSH (par défaut : `ssh`) -- `workspaceRoot` : racine distante absolue utilisée pour les workspaces par portée -- `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants transmis à OpenSSH -- `identityData` / `certificateData` / `knownHostsData` : contenus inline ou SecretRefs qu’OpenClaw matérialise en fichiers temporaires à l’exécution -- `strictHostKeyChecking` / `updateHostKeys` : options de politique de clé d’hôte OpenSSH +- `command` : commande du client SSH (par défaut : `ssh`) +- `workspaceRoot` : racine distante absolue utilisée pour les espaces de travail par portée +- `identityFile` / `certificateFile` / `knownHostsFile` : fichiers locaux existants passés à OpenSSH +- `identityData` / `certificateData` / `knownHostsData` : contenus en ligne ou SecretRefs qu’OpenClaw matérialise en fichiers temporaires à l’exécution +- `strictHostKeyChecking` / `updateHostKeys` : paramètres de politique de clé d’hôte OpenSSH -**Priorité d’authentification SSH :** +**Priorité de l’authentification SSH :** - `identityData` a priorité sur `identityFile` - `certificateData` a priorité sur `certificateFile` - `knownHostsData` a priorité sur `knownHostsFile` -- Les valeurs `*Data` appuyées sur SecretRef sont résolues à partir de l’instantané actif du runtime des secrets avant le démarrage de la session sandbox +- 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 **Comportement du backend SSH :** -- initialise le workspace distant une fois après création ou recréation -- conserve ensuite le workspace SSH distant comme canonique -- route `exec`, les outils de fichiers et les chemins média via SSH -- ne resynchronise pas automatiquement les modifications distantes vers l’hôte +- amorce l’espace de travail distant une fois après sa création ou recréation +- conserve ensuite l’espace de travail SSH distant comme source canonique +- route `exec`, les outils de fichier et les chemins de média via SSH +- ne synchronise pas automatiquement les modifications distantes vers l’hôte - ne prend pas en charge les conteneurs de navigateur sandbox -**Accès au workspace :** +**Accès à l’espace de travail :** -- `none` : workspace sandbox par portée sous `~/.openclaw/sandboxes` -- `ro` : workspace sandbox sur `/workspace`, workspace agent monté en lecture seule sur `/agent` -- `rw` : workspace agent monté en lecture/écriture sur `/workspace` +- `none` : espace de travail sandbox par portée sous `~/.openclaw/sandboxes` +- `ro` : espace de travail sandbox à `/workspace`, espace de travail de l’agent monté en lecture seule à `/agent` +- `rw` : espace de travail de l’agent monté en lecture/écriture à `/workspace` **Portée :** -- `session` : conteneur + workspace par session -- `agent` : un conteneur + workspace par agent (par défaut) -- `shared` : conteneur et workspace partagés (aucune isolation entre sessions) +- `session` : conteneur + espace de travail par session +- `agent` : un conteneur + espace de travail par agent (par défaut) +- `shared` : conteneur et espace de travail partagés (aucune isolation entre sessions) **Configuration du Plugin OpenShell :** @@ -1533,30 +1680,30 @@ Lorsque `backend: "openshell"` est sélectionné, les paramètres spécifiques **Mode OpenShell :** -- `mirror` : initialise le distant depuis le local avant `exec`, resynchronise après `exec` ; le workspace local reste canonique -- `remote` : initialise le distant une seule fois lors de la création du sandbox, puis conserve le workspace distant comme canonique +- `mirror` : amorce le distant depuis le local avant `exec`, resynchronise après `exec` ; l’espace de travail local reste canonique +- `remote` : amorce le distant une fois lors de la création du sandbox, puis conserve l’espace de travail distant comme canonique -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 vers le sandbox OpenShell, mais le Plugin possède le cycle de vie du sandbox et la synchronisation miroir facultative. +En mode `remote`, les modifications locales sur l’hôte effectuées hors d’OpenClaw ne sont pas synchronisées automatiquement dans le sandbox après l’étape d’amorçage. +Le transport se fait via SSH vers le sandbox OpenShell, mais le Plugin gère le cycle de vie du sandbox et la synchronisation miroir facultative. -**`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` (mesure d’urgence). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (mode de dernier recours). -**Les pièces jointes entrantes** sont placées dans `media/inbound/*` dans le workspace actif. +**Les pièces jointes entrantes** sont préparées dans `media/inbound/*` dans l’espace de travail actif. -**`docker.binds`** monte des répertoires d’hôte supplémentaires ; les montages globaux et par agent sont fusionnés. +**`docker.binds`** monte des répertoires hôtes 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`. +**Navigateur sandboxé** (`sandbox.browser.enabled`) : Chromium + CDP dans un conteneur. L’URL noVNC est injectée dans l’invite système. Ne nécessite pas `browser.enabled` dans `openclaw.json`. L’accès observateur noVNC utilise l’authentification VNC par défaut et OpenClaw émet une URL à jeton de courte durée (au lieu d’exposer le mot de passe dans l’URL partagée). - `allowHostControl: false` (par défaut) empêche les sessions sandboxées de cibler le navigateur de l’hôte. - `network` vaut par défaut `openclaw-sandbox-browser` (réseau bridge dédié). Définissez `bridge` uniquement lorsque vous souhaitez explicitement une connectivité bridge globale. - `cdpSourceRange` restreint éventuellement l’entrée CDP à la périphérie du conteneur à une plage CIDR (par exemple `172.21.0.1/32`). -- `sandbox.browser.binds` monte des répertoires d’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 conteneurisés : +- `sandbox.browser.binds` monte des répertoires hôtes supplémentaires uniquement dans le conteneur du navigateur sandboxé. Lorsqu’il est défini (y compris `[]`), il remplace `docker.binds` pour le conteneur du navigateur. +- Les valeurs de lancement par défaut sont définies dans `scripts/sandbox-browser-entrypoint.sh` et ajustées pour les hôtes de conteneurs : - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1576,18 +1723,18 @@ L’accès observateur noVNC utilise l’authentification VNC par défaut et Ope - `--disable-extensions` (activé par défaut) - `--disable-3d-apis`, `--disable-software-rasterizer` et `--disable-gpu` sont activés par défaut et peuvent être désactivés avec - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si l’usage WebGL/3D l’exige. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` réactive les extensions si votre workflow + `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 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 sont la base de l’image conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur. + - plus `--no-sandbox` et `--disable-setuid-sandbox` lorsque `noSandbox` est activé. + - Les valeurs par défaut constituent la ligne de base de l’image conteneur ; utilisez une image de navigateur personnalisée avec un point d’entrée personnalisé pour modifier les valeurs par défaut du conteneur. -Le sandboxing du navigateur et `sandbox.docker.binds` sont disponibles uniquement avec Docker. +Le sandboxing du navigateur et `sandbox.docker.binds` sont pris en charge uniquement avec Docker. Construire les images : @@ -1646,26 +1793,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id` : ID d’agent stable (obligatoire). -- `default` : lorsque plusieurs valeurs sont définies, la première gagne (avertissement journalisé). Si aucune n’est définie, la première entrée de la liste est la valeur par défaut. -- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les replis globaux). Les tâches Cron qui ne remplacent que `primary` héritent toujours des replis par défaut sauf si vous définissez `fallbacks: []`. -- `params` : paramètres de flux par agent fusionnés au-dessus de l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez-les pour des remplacements spécifiques à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer tout le catalogue de modèles. -- `skills` : liste d’autorisations facultative de Skills par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsqu’il est défini ; une liste explicite remplace les valeurs par défaut au lieu de fusionner, et `[]` signifie aucune Skills. -- `thinkingDefault` : niveau de 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 par session n’est défini. -- `reasoningDefault` : visibilité de reasoning facultative par défaut par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement de reasoning par message ou par session n’est défini. -- `fastModeDefault` : valeur par défaut facultative par agent pour le mode rapide (`true | false`). S’applique lorsqu’aucun remplacement de mode rapide par message ou par session n’est défini. -- `embeddedHarness` : remplacement facultatif par agent de la politique de harness de bas niveau. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent Codex-only tandis que les autres agents conservent le repli 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 au workspace, URL `http(s)` ou URI `data:`. -- `identity` dérive les valeurs par défaut : `ackReaction` depuis `emoji`, `mentionPatterns` depuis `name`/`emoji`. -- `subagents.allowAgents` : liste d’autorisations des ID d’agent pour `sessions_spawn` (`["*"]` = tous ; par défaut : même agent uniquement). -- Garde-fou d’héritage sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans sandbox. -- `subagents.requireAgentId` : lorsqu’il vaut true, bloque les appels `sessions_spawn` qui omettent `agentId` (force la sélection explicite du profil ; par défaut : false). +- `default` : lorsque plusieurs sont définis, le premier l’emporte (un avertissement est journalisé). Si aucun n’est défini, la première entrée de la liste est utilisée par défaut. +- `model` : la forme chaîne remplace uniquement `primary` ; la forme objet `{ primary, fallbacks }` remplace les deux (`[]` désactive les valeurs de repli globales). Les tâches Cron qui ne remplacent que `primary` héritent toujours des valeurs de repli par défaut sauf si vous définissez `fallbacks: []`. +- `params` : paramètres de flux par agent fusionnés par-dessus l’entrée de modèle sélectionnée dans `agents.defaults.models`. Utilisez cela pour des remplacements spécifiques à l’agent comme `cacheRetention`, `temperature` ou `maxTokens` sans dupliquer l’ensemble du catalogue de modèles. +- `skills` : liste d’autorisation facultative de Skills par agent. Si elle est omise, l’agent hérite de `agents.defaults.skills` lorsqu’elle est définie ; une liste explicite remplace les valeurs par défaut au lieu d’être fusionnée, et `[]` signifie aucun Skills. +- `thinkingDefault` : niveau par défaut facultatif de thinking par agent (`off | minimal | low | medium | high | xhigh | adaptive`). Remplace `agents.defaults.thinkingDefault` pour cet agent lorsqu’aucun remplacement par message ou session n’est défini. +- `reasoningDefault` : visibilité par défaut facultative du reasoning par agent (`on | off | stream`). S’applique lorsqu’aucun remplacement de reasoning par message ou session n’est défini. +- `fastModeDefault` : valeur par défaut facultative du mode rapide par agent (`true | false`). S’applique lorsqu’aucun remplacement de mode rapide par message ou session n’est défini. +- `embeddedHarness` : remplacement facultatif de politique de harness de bas niveau par agent. Utilisez `{ runtime: "codex", fallback: "none" }` pour rendre un agent réservé à Codex tandis que les autres agents conservent le repli PI par défaut. +- `runtime` : descripteur facultatif du runtime par agent. Utilisez `type: "acp"` avec les valeurs par défaut `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) lorsque l’agent doit utiliser par défaut des sessions harness ACP. +- `identity.avatar` : chemin relatif à l’espace de travail, URL `http(s)` ou URI `data:`. +- `identity` dérive des valeurs par défaut : `ackReaction` depuis `emoji`, `mentionPatterns` depuis `name`/`emoji`. +- `subagents.allowAgents` : liste d’autorisation des ID d’agent pour `sessions_spawn` (`["*"]` = tous ; par défaut : même agent uniquement). +- Garde-fou d’héritage du sandbox : si la session requérante est sandboxée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans sandbox. +- `subagents.requireAgentId` : lorsque true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite de profil ; par défaut : false). --- -## Routage multi-agents +## Routage multi-agent -Exécutez plusieurs agents isolés à l’intérieur d’un seul Gateway. Voir [Multi-Agent](/fr/concepts/multi-agent). +Exécutez plusieurs agents isolés dans une seule Gateway. Voir [Multi-Agent](/fr/concepts/multi-agent). ```json5 { @@ -1684,9 +1831,9 @@ Exécutez plusieurs agents isolés à l’intérieur d’un seul Gateway. Voir [ ### Champs de correspondance des liaisons -- `type` (facultatif) : `route` pour le routage normal (l’absence de type vaut 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 ; `*` = tout compte ; omis = compte par défaut) +- `match.accountId` (facultatif ; `*` = n’importe quel compte ; omis = compte par défaut) - `match.peer` (facultatif ; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (facultatif ; spécifique au canal) - `acp` (facultatif ; uniquement pour `type: "acp"`) : `{ mode, label, cwd, backend }` @@ -1696,13 +1843,13 @@ Exécutez plusieurs agents isolés à l’intérieur d’un seul Gateway. Voir [ 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exact, sans pair/guilde/équipe) +4. `match.accountId` (exact, sans pair/serveur/équipe) 5. `match.accountId: "*"` (à l’échelle du canal) 6. Agent par défaut -À l’intérieur de chaque niveau, la première entrée `bindings` correspondante gagne. +À l’intérieur de chaque niveau, la première entrée correspondante de `bindings` 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 de niveau des liaisons de routage ci-dessus. +Pour les entrées `type: "acp"`, OpenClaw résout selon l’identité exacte de la conversation (`match.channel` + compte + `match.peer.id`) et n’utilise pas l’ordre de niveaux de liaison de routage ci-dessus. ### Profils d’accès par agent @@ -1724,7 +1871,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conver - + ```json5 { @@ -1799,7 +1946,7 @@ Pour les entrées `type: "acp"`, OpenClaw résout par identité exacte de conver -Voir [Sandbox et outils multi-agents](/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 le détail des priorités. --- @@ -1852,35 +1999,35 @@ Voir [Sandbox et outils multi-agents](/fr/tools/multi-agent-sandbox-tools) pour -- **`scope`** : stratégie de groupement de session de base pour les contextes de discussion de groupe. +- **`scope`** : stratégie de base de regroupement des sessions pour les contextes de discussion de groupe. - `per-sender` (par défaut) : chaque expéditeur obtient une session isolée dans un contexte de canal. - - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsqu’un contexte partagé est souhaité). -- **`dmScope`** : manière dont les DM sont groupés. - - `main` : tous les DM partagent la session principale. + - `global` : tous les participants d’un contexte de canal partagent une seule session (à utiliser uniquement lorsqu’un contexte partagé est intentionnel). +- **`dmScope`** : manière dont les MP sont regroupés. + - `main` : tous les MP partagent la session principale. - `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 les ID canoniques vers des pairs préfixés par fournisseur pour le partage de session inter-canaux. -- **`reset`** : politique de réinitialisation principale. `daily` réinitialise à `atHour` heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte. +- **`identityLinks`** : mappe des ID canoniques vers des pairs préfixés par fournisseur pour le partage de session inter-canal. +- **`reset`** : politique principale de réinitialisation. `daily` réinitialise à `atHour` selon l’heure locale ; `idle` réinitialise après `idleMinutes`. Lorsque les deux sont configurés, celui qui expire en premier l’emporte. - **`resetByType`** : remplacements par type (`direct`, `group`, `thread`). L’ancien `dm` est accepté comme alias de `direct`. -- **`parentForkMaxTokens`** : `totalTokens` maximal de la session parente autorisé lors de la création d’une session de fil forkée (par défaut `100000`). - - Si le `totalTokens` parent est supérieur à cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription parent. - - Définissez `0` pour désactiver cette protection et toujours autoriser le fork parent. +- **`parentForkMaxTokens`** : valeur maximale de `totalTokens` de la session parente autorisée lors de la création d’une session de fil bifurquée (par défaut `100000`). + - Si le `totalTokens` parent est au-dessus de cette valeur, OpenClaw démarre une nouvelle session de fil au lieu d’hériter de l’historique de transcription parent. + - Définissez `0` pour désactiver cette protection et toujours autoriser la bifurcation depuis le parent. - **`mainKey`** : champ hérité. Le runtime utilise toujours `"main"` pour le compartiment principal de discussion directe. -- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse réciproque entre agents lors des échanges agent-à-agent (entier, plage : `0`–`5`). `0` désactive l’enchaînement ping-pong. +- **`agentToAgent.maxPingPongTurns`** : nombre maximal de tours de réponse entre agents pendant les échanges agent à agent (entier, plage : `0`–`5`). `0` désactive l’enchaînement ping-pong. - **`sendPolicy`** : correspondance par `channel`, `chatType` (`direct|group|channel`, avec l’ancien alias `dm`), `keyPrefix` ou `rawKeyPrefix`. Le premier refus l’emporte. -- **`maintenance`** : contrôles de nettoyage + rétention du stockage de session. +- **`maintenance`** : contrôles de nettoyage + rétention du magasin de sessions. - `mode` : `warn` émet uniquement des avertissements ; `enforce` applique le nettoyage. - `pruneAfter` : seuil d’ancienneté pour les entrées obsolètes (par défaut `30d`). - `maxEntries` : nombre maximal d’entrées dans `sessions.json` (par défaut `500`). - - `rotateBytes` : fait tourner `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`). - - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Par défaut, prend `pruneAfter` ; définissez `false` pour désactiver. - - `maxDiskBytes` : budget disque facultatif pour le répertoire des sessions. En mode `warn`, cela journalise des avertissements ; en mode `enforce`, cela supprime d’abord les artefacts/sessions les plus anciens. - - `highWaterBytes` : cible facultative après nettoyage du budget. Par défaut, vaut `80%` de `maxDiskBytes`. + - `rotateBytes` : effectue une rotation de `sessions.json` lorsqu’il dépasse cette taille (par défaut `10mb`). + - `resetArchiveRetention` : rétention des archives de transcription `*.reset.`. Par défaut, utilise `pruneAfter` ; définissez `false` pour désactiver. + - `maxDiskBytes` : budget disque facultatif pour le répertoire des sessions. En mode `warn`, il journalise des avertissements ; en mode `enforce`, il supprime d’abord les artefacts/sessions les plus anciens. + - `highWaterBytes` : cible facultative après nettoyage du budget. Par défaut, `80%` de `maxDiskBytes`. - **`threadBindings`** : valeurs par défaut globales pour les fonctionnalités de session liées aux fils. - - `enabled` : interrupteur maître par défaut (les fournisseurs peuvent remplacer ; Discord utilise `channels.discord.threadBindings.enabled`) - - `idleHours` : valeur par défaut du retrait automatique du focus après inactivité, en heures (`0` désactive ; les fournisseurs peuvent remplacer) - - `maxAgeHours` : valeur par défaut de l’âge maximal strict en heures (`0` désactive ; les fournisseurs peuvent remplacer) + - `enabled` : interrupteur maître par défaut (les fournisseurs peuvent le remplacer ; Discord utilise `channels.discord.threadBindings.enabled`) + - `idleHours` : retrait automatique du focus par défaut après inactivité, en heures (`0` désactive ; les fournisseurs peuvent remplacer) + - `maxAgeHours` : âge maximal strict par défaut, en heures (`0` désactive ; les fournisseurs peuvent remplacer) @@ -1924,30 +2071,30 @@ Résolution (le plus spécifique l’emporte) : compte → canal → global. `" **Variables de modèle :** -| Variable | Description | Exemple | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nom court du modèle | `claude-opus-4-6` | +| Variable | Description | Exemple | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | Nom court du modèle | `claude-opus-4-6` | | `{modelFull}` | Identifiant complet du modèle | `anthropic/claude-opus-4-6` | -| `{provider}` | Nom du fournisseur | `anthropic` | -| `{thinkingLevel}` | Niveau de thinking actuel | `high`, `low`, `off` | -| `{identity.name}` | Nom d’identité de l’agent | (identique à `"auto"`) | +| `{provider}` | Nom du fournisseur | `anthropic` | +| `{thinkingLevel}` | Niveau actuel de thinking | `high`, `low`, `off` | +| `{identity.name}` | Nom de l’identité de l’agent | (identique à `"auto"`) | Les variables sont insensibles à la casse. `{think}` est un alias de `{thinkingLevel}`. -### Réaction d’accusé +### Réaction d’accusé de réception -- Vaut par défaut l’`identity.emoji` de l’agent actif, sinon `"👀"`. Définissez `""` pour désactiver. +- Par défaut, utilise `identity.emoji` de l’agent actif, sinon `"👀"`. Définissez `""` pour désactiver. - Remplacements par canal : `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordre de résolution : compte → canal → `messages.ackReaction` → repli d’identité. +- Ordre de résolution : compte → canal → `messages.ackReaction` → repli sur l’identité. - Portée : `group-mentions` (par défaut), `group-all`, `direct`, `all`. -- `removeAckAfterReply` : supprime l’accusé après la réponse sur Slack, Discord et Telegram. -- `messages.statusReactions.enabled` : active les réactions de statut de cycle de vie sur Slack, Discord et Telegram. - Sur Slack et Discord, lorsque non défini, les réactions de statut restent activées lorsque les réactions d’accusé sont actives. - Sur Telegram, définissez-le explicitement sur `true` pour activer les réactions de statut de cycle de vie. +- `removeAckAfterReply` : supprime l’accusé de réception après la réponse sur Slack, Discord et Telegram. +- `messages.statusReactions.enabled` : active les réactions d’état de cycle de vie sur Slack, Discord et Telegram. + Sur Slack et Discord, non défini conserve les réactions d’état activées lorsque les réactions d’accusé de réception sont actives. + Sur Telegram, définissez-le explicitement à `true` pour activer les réactions d’état de cycle de vie. -### Debounce entrant +### Anti-rebond entrant -Regroupe les messages rapides en texte seul d’un 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. +Regroupe les messages texte rapides provenant du même expéditeur en un seul tour d’agent. Les médias/pièces jointes déclenchent un envoi immédiat. Les commandes de contrôle contournent l’anti-rebond. ### TTS (synthèse vocale) @@ -1994,14 +2141,14 @@ Regroupe les messages rapides en texte seul d’un même expéditeur en un seul - `summaryModel` remplace `agents.defaults.model.primary` pour le résumé automatique. - `modelOverrides` est activé par défaut ; `modelOverrides.allowProvider` vaut par défaut `false` (activation explicite requise). - Les clés API reviennent à `ELEVENLABS_API_KEY`/`XI_API_KEY` et `OPENAI_API_KEY`. -- `openai.baseUrl` remplace le point de terminaison TTS OpenAI. L’ordre de résolution est la configuration, puis `OPENAI_TTS_BASE_URL`, puis `https://api.openai.com/v1`. -- Lorsque `openai.baseUrl` pointe vers un point de terminaison autre qu’OpenAI, OpenClaw le traite comme un serveur TTS compatible OpenAI et assouplit la validation du modèle/de la voix. +- `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. --- ## Talk -Valeurs par défaut du mode Talk (macOS/iOS/Android). +Valeurs par défaut pour le mode Talk (macOS/iOS/Android). ```json5 { @@ -2025,13 +2172,13 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android). } ``` -- `talk.provider` doit correspondre à une clé de `talk.providers` lorsque plusieurs fournisseurs Talk sont configurés. -- Les anciennes clés Talk plates (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sont uniquement maintenues pour compatibilité et sont automatiquement migrées vers `talk.providers.`. +- `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 reviennent à `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. -- `providers.*.apiKey` accepte des chaînes en texte brut ou des objets SecretRef. -- Le repli `ELEVENLABS_API_KEY` s’applique uniquement lorsqu’aucune clé API Talk n’est configurée. +- `providers.*.apiKey` accepte des chaînes en clair ou des objets SecretRef. +- Le repli `ELEVENLABS_API_KEY` ne s’applique que lorsqu’aucune clé API Talk n’est configurée. - `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. Lorsqu’il n’est pas défini, la fenêtre de pause par défaut de la plateforme est conservée (`700 ms sur macOS et Android, 900 ms sur iOS`). +- `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 conserve la fenêtre de pause par défaut de la plateforme (`700 ms sur macOS et Android, 900 ms sur iOS`). --- @@ -2039,33 +2186,33 @@ Valeurs par défaut du mode Talk (macOS/iOS/Android). ### Profils d’outils -`tools.profile` définit une liste d’autorisations de base avant `tools.allow`/`tools.deny` : +`tools.profile` définit une liste d’autorisation de base avant `tools.allow`/`tools.deny` : L’onboarding local définit par défaut les nouvelles configurations locales sur `tools.profile: "coding"` lorsqu’il n’est pas défini (les profils explicites existants sont conservés). -| Profil | Inclut | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | `session_status` uniquement | +| Profil | Inclut | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `minimal` | `session_status` uniquement | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Aucune restriction (identique à non défini) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Aucune restriction (identique à non défini) | ### Groupes d’outils -| Groupe | Outils | -| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` est accepté comme alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Groupe | Outils | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` est accepté comme alias de `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Tous les outils intégrés (exclut les Plugins de fournisseur) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Tous les outils intégrés (hors plugins fournisseur) | ### `tools.allow` / `tools.deny` @@ -2079,7 +2226,7 @@ Politique globale d’autorisation/refus des outils (le refus l’emporte). Inse ### `tools.byProvider` -Restreint davantage les outils pour des fournisseurs ou modèles spécifiques. Ordre : profil de base → profil 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 { @@ -2112,7 +2259,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 inline s’appliquent à un seul message. +- `/elevated on|off|ask|full` stocke l’état par session ; les directives en ligne s’appliquent à un seul message. - `exec` élevé contourne le sandboxing et utilise le chemin d’échappement configuré (`gateway` par défaut, ou `node` lorsque la cible `exec` est `node`). ### `tools.exec` @@ -2159,13 +2306,13 @@ 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. +- `historySize` : historique maximal des appels d’outil conservé pour l’analyse de boucle. - `warningThreshold` : seuil de motif répétitif sans progression pour les avertissements. - `criticalThreshold` : seuil répétitif plus élevé pour bloquer les boucles critiques. -- `globalCircuitBreakerThreshold` : seuil d’arrêt dur pour toute exécution sans progression. +- `globalCircuitBreakerThreshold` : seuil d’arrêt brutal pour toute exécution sans progression. - `detectors.genericRepeat` : avertit en cas d’appels répétés au même outil/avec les mêmes arguments. -- `detectors.knownPollNoProgress` : avertit/bloque les outils de polling connus (`process.poll`, `command_status`, etc.). -- `detectors.pingPong` : avertit/bloque les motifs alternés sans progression par paires. +- `detectors.knownPollNoProgress` : avertit/bloque sur des outils de sondage connus (`process.poll`, `command_status`, etc.). +- `detectors.pingPong` : avertit/bloque sur des motifs alternés de paires sans progression. - Si `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, la validation échoue. ### `tools.web` @@ -2236,28 +2383,28 @@ Configure la compréhension des médias entrants (image/audio/vidéo) : **Entrée fournisseur** (`type: "provider"` ou omis) : -- `provider` : ID du fournisseur d’API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model` : remplacement de l’ID du modèle -- `profile` / `preferredProfile` : sélection du profil `auth-profiles.json` +- `provider` : ID du fournisseur API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) +- `model` : remplacement d’ID de modèle +- `profile` / `preferredProfile` : sélection de profil `auth-profiles.json` **Entrée CLI** (`type: "cli"`) : - `command` : exécutable à lancer -- `args` : arguments à gabarit (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) +- `args` : arguments avec modèle (prend en charge `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) **Champs communs :** - `capabilities` : liste facultative (`image`, `audio`, `video`). Valeurs par défaut : `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language` : remplacements par entrée. -- En cas d’échec, bascule vers l’entrée suivante. +- Les échecs reviennent à l’entrée suivante. L’authentification du fournisseur suit l’ordre standard : `auth-profiles.json` → variables d’environnement → `models.providers.*.apiKey`. -**Champs de fin asynchrone :** +**Champs d’achèvement asynchrone :** -- `asyncCompletion.directSend` : lorsqu’il vaut `true`, les tâches asynchrones terminées `music_generate` - et `video_generate` essaient d’abord une livraison directe au canal. Par défaut : `false` - (ancien chemin de réveil de session demandeuse/livraison du modèle). +- `asyncCompletion.directSend` : lorsque `true`, les tâches `music_generate` + et `video_generate` asynchrones terminées tentent d’abord une livraison directe au canal. Par défaut : `false` + (ancien chemin de réveil de session du demandeur/livraison par modèle). @@ -2278,7 +2425,7 @@ L’authentification du fournisseur suit l’ordre standard : `auth-profiles.js 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 créées par elle, telles que les sous-agents). +Par défaut : `tree` (session actuelle + sessions engendrées par elle, comme les sous-agents). ```json5 { @@ -2294,14 +2441,14 @@ Par défaut : `tree` (session actuelle + sessions créées par elle, telles que Remarques : - `self` : uniquement la clé de session actuelle. -- `tree` : session actuelle + sessions créées par la session actuelle (sous-agents). +- `tree` : session actuelle + sessions engendrées par la session actuelle (sous-agents). - `agent` : toute session appartenant à l’ID d’agent actuel (peut inclure d’autres utilisateurs si vous exécutez des sessions par expéditeur sous le même ID d’agent). -- `all` : toute session. Le ciblage inter-agents nécessite toujours `tools.agentToAgent`. -- Limitation sandbox : lorsque la session actuelle est sandboxée et que `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilité est forcée à `tree` même si `tools.sessions.visibility="all"`. +- `all` : toute session. Le ciblage inter-agent nécessite toujours `tools.agentToAgent`. +- Limitation du sandbox : lorsque la session actuelle est sandboxée et que `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilité est forcée à `tree` même si `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Contrôle la prise en charge des pièces jointes inline pour `sessions_spawn`. +Contrôle la prise en charge des pièces jointes en ligne pour `sessions_spawn`. ```json5 { @@ -2321,16 +2468,16 @@ Contrôle la prise en charge des pièces jointes inline pour `sessions_spawn`. Remarques : -- Les pièces jointes sont prises en charge uniquement pour `runtime: "subagent"`. Le runtime ACP les rejette. -- Les fichiers sont matérialisés dans le workspace enfant sous `.openclaw/attachments//` avec un `.manifest.json`. +- Les pièces jointes ne sont prises en charge que pour `runtime: "subagent"`. Le runtime ACP les rejette. +- Les fichiers sont matérialisés dans l’espace de travail enfant à `.openclaw/attachments//` avec un `.manifest.json`. - Le contenu des pièces jointes est automatiquement expurgé de la persistance de la transcription. -- Les entrées Base64 sont validées avec des vérifications strictes d’alphabet/de padding et une protection de taille avant décodage. +- Les entrées Base64 sont validées avec des vérifications strictes d’alphabet/remplissage et une protection de taille avant décodage. - Les permissions de fichier sont `0700` pour les répertoires et `0600` pour les fichiers. - Le nettoyage suit la politique `cleanup` : `delete` supprime toujours les pièces jointes ; `keep` ne les conserve que lorsque `retainOnSessionKeep: true`. ### `tools.experimental` -Indicateurs expérimentaux des 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 si une règle d’auto-activation stricte agentique GPT-5 s’applique. ```json5 { @@ -2344,9 +2491,9 @@ Indicateurs expérimentaux des outils intégrés. Désactivés par défaut sauf Remarques : -- `planTool` : active l’outil structuré expérimental `update_plan` pour le suivi des tâches non triviales 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 périmètre, 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 conséquent et ne conserve au plus qu’une seule étape `in_progress`. +- `planTool` : active l’outil structuré `update_plan` pour le suivi des travaux non triviaux en plusieurs étapes. +- Par défaut : `false` sauf si `agents.defaults.embeddedPi.executionContract` (ou un remplacement par agent) est défini sur `"strict-agentic"` pour une exécution OpenAI ou OpenAI Codex de la famille GPT-5. Définissez `true` pour forcer l’activation de l’outil en dehors de ce cadre, ou `false` pour le garder désactivé même pour les exécutions GPT-5 strict-agentiques. +- Lorsqu’il est activé, l’invite système ajoute aussi des consignes d’utilisation afin que le modèle ne l’utilise que pour un travail substantiel et conserve au plus une étape `in_progress`. ### `agents.defaults.subagents` @@ -2366,14 +2513,14 @@ Remarques : } ``` -- `model` : modèle par défaut pour les sous-agents créés. Lorsqu’il est 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` (`["*"]` = tous ; par défaut : même agent uniquement). -- `runTimeoutSeconds` : délai maximal par défaut (en secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai. +- `model` : modèle par défaut pour les sous-agents engendrés. S’il est omis, les sous-agents héritent du modèle de l’appelant. +- `allowAgents` : liste d’autorisation par défaut des ID d’agent cibles pour `sessions_spawn` lorsque l’agent demandeur ne définit pas son propre `subagents.allowAgents` (`["*"]` = n’importe lequel ; par défaut : même agent uniquement). +- `runTimeoutSeconds` : délai maximal par défaut (secondes) pour `sessions_spawn` lorsque l’appel d’outil omet `runTimeoutSeconds`. `0` signifie aucun délai maximal. - Politique d’outils par sous-agent : `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Fournisseurs personnalisés et URLs de base +## Fournisseurs personnalisés et URL de base OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs personnalisés via `models.providers` dans la configuration ou `~/.openclaw/agents//agent/models.json`. @@ -2405,45 +2552,45 @@ OpenClaw utilise le catalogue de modèles intégré. Ajoutez des fournisseurs pe ``` - Utilisez `authHeader: true` + `headers` pour les besoins d’authentification personnalisés. -- Remplacez la racine de configuration de l’agent avec `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, 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 depuis les marqueurs source (`ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec) au lieu de persister les secrets résolus. - - Les valeurs d’en-tête du fournisseur gérées par SecretRef sont actualisées depuis les marqueurs source (`secretref-env:ENV_VAR_NAME` pour les références env, `secretref-managed` pour les références fichier/exec). + - Les valeurs non vides de `baseUrl` dans `models.json` de l’agent l’emportent. + - Les valeurs non vides de `apiKey` de l’agent ne l’emportent que lorsque ce fournisseur n’est pas géré par SecretRef dans le contexte actuel de configuration/profil d’authentification. + - Les valeurs `apiKey` de fournisseur gérées par SecretRef sont actualisées depuis les marqueurs source (`ENV_VAR_NAME` pour les références d’environnement, `secretref-managed` pour les références fichier/exec) au lieu de persister les secrets résolus. + - Les valeurs d’en-tête de fournisseur gérées par SecretRef sont actualisées depuis les marqueurs source (`secretref-env:ENV_VAR_NAME` pour les références d’environnement, `secretref-managed` pour les références fichier/exec). - Les valeurs `apiKey`/`baseUrl` d’agent vides ou absentes reviennent à `models.providers` dans la configuration. - Les valeurs `contextWindow`/`maxTokens` du modèle correspondant utilisent la valeur la plus élevée entre la configuration explicite et les valeurs implicites du catalogue. - - Les valeurs `contextTokens` du modèle correspondant conservent une limite d’exécution explicite lorsqu’elle est présente ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle. + - Les valeurs `contextTokens` du modèle correspondant conservent une limite explicite du runtime lorsqu’elle est présente ; utilisez-la pour limiter le contexte effectif sans modifier les métadonnées natives du modèle. - Utilisez `models.mode: "replace"` lorsque vous voulez que la configuration réécrive entièrement `models.json`. - - La persistance des marqueurs est pilotée par la source : les marqueurs sont écrits à partir de l’instantané actif de configuration source (avant résolution), et non à partir des valeurs de secret résolues à l’exécution. + - La persistance des marqueurs est pilotée par la source : les marqueurs sont écrits à partir de l’instantané actif de configuration source (pré-résolution), et non à partir des valeurs secrètes résolues à l’exécution. ### Détails des champs du fournisseur - `models.mode` : comportement du catalogue de fournisseurs (`merge` ou `replace`). -- `models.providers` : mapping de fournisseurs personnalisés indexé par ID de fournisseur. +- `models.providers` : map 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 env). +- `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 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 de fournisseur de modèle. +- `models.providers.*.baseUrl` : URL de base de l’API en amont. +- `models.providers.*.headers` : en-têtes statiques supplémentaires pour le routage proxy/locataire. +- `models.providers.*.request` : remplacements de transport pour les requêtes HTTP du fournisseur de modèles. - `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 la stratégie d’authentification. Modes : `"provider-default"` (utiliser l’authentification intégrée du fournisseur), `"authorization-bearer"` (avec `token`), `"header"` (avec `headerName`, `value`, `prefix` facultatif). - - `request.proxy` : remplacement 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 `tls` facultatif. + - `request.auth` : remplacement de stratégie d’authentification. Modes : `"provider-default"` (utiliser l’authentification intégrée du fournisseur), `"authorization-bearer"` (avec `token`), `"header"` (avec `headerName`, `value`, `prefix` facultatif). + - `request.proxy` : remplacement de proxy HTTP. Modes : `"env-proxy"` (utiliser les variables d’environnement `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (avec `url`). Les deux modes acceptent un sous-objet `tls` facultatif. - `request.tls` : remplacement TLS pour les connexions directes. Champs : `ca`, `cert`, `key`, `passphrase` (tous acceptent SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork` : lorsqu’il vaut `true`, autorise HTTPS vers `baseUrl` lorsque la résolution DNS pointe vers des plages privées, CGNAT ou similaires, via la protection de récupération HTTP du fournisseur (activation explicite opérateur pour les points de terminaison OpenAI-compatibles auto-hébergés de confiance). WebSocket utilise le même `request` pour les en-têtes/TLS mais pas cette protection SSRF de récupération. Par défaut `false`. + - `request.allowPrivateNetwork` : lorsque `true`, autorise HTTPS vers `baseUrl` lorsque le DNS se résout vers des plages privées, CGNAT ou similaires, via la protection de récupération HTTP SSRF du fournisseur (activation explicite opérateur pour des points de terminaison compatibles OpenAI auto-hébergés de confiance). WebSocket utilise le même `request` pour les en-têtes/TLS mais pas cette protection SSRF côté récupération. Par défaut `false`. - `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` : limite de contexte d’exécution facultative. Utilisez-la lorsque vous voulez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle. -- `models.providers.*.models.*.compat.supportsDeveloperRole` : indice de compatibilité facultatif. Pour `api: "openai-completions"` avec un `baseUrl` non natif non vide (hôte différent de `api.openai.com`), OpenClaw force cette valeur à `false` à l’exécution. Un `baseUrl` vide/omis conserve le comportement OpenAI par défaut. -- `models.providers.*.models.*.compat.requiresStringContent` : indice de compatibilité facultatif pour les points de terminaison de chat OpenAI-compatibles n’acceptant que des chaînes. Lorsqu’il vaut `true`, OpenClaw aplatit en chaînes simples les tableaux `messages[].content` purement textuels avant d’envoyer la requête. +- `models.providers.*.models.*.contextTokens` : plafond facultatif de contexte à l’exécution. Utilisez-le lorsque vous voulez un budget de contexte effectif plus petit que le `contextWindow` natif du modèle. +- `models.providers.*.models.*.compat.supportsDeveloperRole` : indication facultative de compatibilité. Pour `api: "openai-completions"` avec un `baseUrl` non vide et non natif (hôte différent de `api.openai.com`), OpenClaw force cette valeur à `false` à l’exécution. Un `baseUrl` vide/omis conserve le comportement OpenAI par défaut. +- `models.providers.*.models.*.compat.requiresStringContent` : indication facultative de compatibilité pour les points de terminaison de discussion compatibles OpenAI acceptant uniquement des chaînes. Lorsque `true`, OpenClaw aplatit les tableaux `messages[].content` purement textuels en chaînes simples avant d’envoyer la requête. - `plugins.entries.amazon-bedrock.config.discovery` : racine des paramètres d’auto-découverte Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled` : active/désactive la découverte implicite. - `plugins.entries.amazon-bedrock.config.discovery.region` : région AWS pour la découverte. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter` : filtre facultatif d’ID de fournisseur pour une découverte ciblée. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour l’actualisation de la découverte. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval` : intervalle d’interrogation pour le rafraîchissement de la découverte. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow` : fenêtre de contexte de repli pour les modèles découverts. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens` : nombre maximal de jetons de sortie de repli pour les modèles découverts. @@ -2500,7 +2647,7 @@ Utilisez `cerebras/zai-glm-4.7` pour Cerebras ; `zai/glm-4.7` pour Z.AI direct. } ``` -Définissez `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Utilisez des références `opencode/...` pour le catalogue Zen ou 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`. @@ -2517,11 +2664,11 @@ Définissez `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Utilisez des référ } ``` -Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont des alias acceptés. Raccourci : `openclaw onboard --auth-choice zai-api-key`. +Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont acceptés comme alias. Raccourci : `openclaw onboard --auth-choice zai-api-key`. - Point de terminaison général : `https://api.z.ai/api/paas/v4` -- Point de terminaison de développement (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 le remplacement de l’URL de base. +- Point de terminaison de code (par défaut) : `https://api.z.ai/api/coding/paas/v4` +- Pour le point de terminaison général, définissez un fournisseur personnalisé avec remplacement de l’URL de base. @@ -2562,9 +2709,9 @@ Définissez `ZAI_API_KEY`. `z.ai/*` et `z-ai/*` sont des alias acceptés. Raccou Pour le point de terminaison Chine : `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. -Les points de terminaison Moonshot natifs annoncent une compatibilité d’usage du streaming sur le transport partagé -`openai-completions`, et OpenClaw s’appuie sur ces capacités de point de terminaison -plutôt que sur le seul ID de fournisseur intégré. +Les points de terminaison Moonshot natifs annoncent une compatibilité d’utilisation du streaming sur le transport partagé +`openai-completions`, et OpenClaw se base sur les capacités du point de terminaison +plutôt que sur le seul ID du fournisseur intégré. @@ -2664,7 +2811,7 @@ 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 vaut par défaut M2.7 uniquement. +Le catalogue de modèles utilise par défaut uniquement M2.7. Sur le chemin de streaming compatible Anthropic, OpenClaw désactive par défaut le thinking de MiniMax sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou `params.fastMode: true` réécrit `MiniMax-M2.7` en @@ -2674,7 +2821,7 @@ sauf si vous définissez explicitement `thinking` vous-même. `/fast on` ou -Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand modèle local via l’API Responses de LM Studio sur un matériel sérieux ; conservez les modèles hébergés fusionnés pour le repli. +Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand modèle local via l’API LM Studio Responses sur un matériel sérieux ; conservez les modèles hébergés fusionnés comme solution de repli. @@ -2705,14 +2852,14 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand } ``` -- `allowBundled` : liste d’autorisations facultative pour les Skills groupées uniquement (les Skills gérées/de workspace ne sont pas affectées). -- `load.extraDirs` : racines supplémentaires de Skills partagées (priorité la plus basse). +- `allowBundled` : liste d’autorisation facultative pour les Skills groupés uniquement (les Skills gérés/de l’espace de travail ne sont pas affectés). +- `load.extraDirs` : racines partagées supplémentaires de Skills (priorité la plus faible). - `install.preferBrew` : lorsque true, préfère les installateurs Homebrew lorsque `brew` est - disponible avant de revenir à d’autres types d’installateur. + disponible avant de revenir à d’autres types d’installateurs. - `install.nodeManager` : préférence de gestionnaire Node pour les spécifications `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` désactive une Skills même si elle est groupée/installée. -- `entries..apiKey` : raccourci pour les Skills qui déclarent une variable d’environnement principale (chaîne en texte brut ou objet SecretRef). +- `entries..enabled: false` désactive un Skills même s’il est groupé/installé. +- `entries..apiKey` : raccourci pratique pour les Skills déclarant une variable d’environnement principale (chaîne en clair ou objet SecretRef). --- @@ -2740,39 +2887,39 @@ Voir [Modèles locaux](/fr/gateway/local-models). En bref : exécutez un grand } ``` -- Chargé depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, ainsi que `plugins.load.paths`. -- La découverte accepte les Plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude sans manifeste avec disposition par défaut. -- **Les modifications de configuration nécessitent un redémarrage du Gateway.** -- `allow` : liste d’autorisations facultative (seuls les Plugins listés sont chargés). `deny` l’emporte. -- `plugins.entries..apiKey` : champ pratique de clé API au niveau Plugin (lorsqu’il est pris en charge par le Plugin). -- `plugins.entries..env` : mapping de variables d’environnement à portée du Plugin. -- `plugins.entries..hooks.allowPromptInjection` : lorsqu’il vaut `false`, le cœur bloque `before_prompt_build` et ignore les champs modifiant le prompt de l’ancien `before_agent_start`, tout en préservant les anciens `modelOverride` et `providerOverride`. S’applique aux hooks de Plugin natifs et aux répertoires de hooks fournis par bundle pris en charge. -- `plugins.entries..subagent.allowModelOverride` : fait explicitement confiance à ce Plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions de sous-agents en arrière-plan. -- `plugins.entries..subagent.allowedModels` : liste d’autorisations facultative des cibles canoniques `provider/model` pour les remplacements de sous-agents de confiance. Utilisez `"*"` uniquement lorsque vous voulez intentionnellement autoriser n’importe quel modèle. -- `plugins.entries..config` : objet de configuration défini par le Plugin (validé par le schéma du Plugin OpenClaw natif lorsque disponible). -- `plugins.entries.firecrawl.config.webFetch` : paramètres du fournisseur web-fetch 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`. +- Chargés depuis `~/.openclaw/extensions`, `/.openclaw/extensions`, ainsi que `plugins.load.paths`. +- La découverte accepte les plugins OpenClaw natifs ainsi que les bundles Codex compatibles et les bundles Claude, y compris les bundles Claude sans manifeste avec disposition par défaut. +- **Les changements de configuration nécessitent un redémarrage de la Gateway.** +- `allow` : liste d’autorisation facultative (seuls les plugins listés se chargent). `deny` l’emporte. +- `plugins.entries..apiKey` : champ pratique de clé API au niveau du plugin (lorsque pris en charge par le plugin). +- `plugins.entries..env` : map de variables d’environnement à portée du plugin. +- `plugins.entries..hooks.allowPromptInjection` : lorsque `false`, le noyau bloque `before_prompt_build` et ignore les champs de mutation d’invite issus de l’ancien `before_agent_start`, tout en conservant les anciens `modelOverride` et `providerOverride`. S’applique aux hooks de plugins natifs et aux répertoires de hooks fournis par bundle pris en charge. +- `plugins.entries..subagent.allowModelOverride` : fait explicitement confiance à ce plugin pour demander des remplacements `provider` et `model` par exécution pour les exécutions en arrière-plan de sous-agent. +- `plugins.entries..subagent.allowedModels` : liste d’autorisation facultative des cibles canoniques `provider/model` pour les remplacements de sous-agent de confiance. Utilisez `"*"` uniquement lorsque vous souhaitez intentionnellement autoriser n’importe quel modèle. +- `plugins.entries..config` : objet de configuration défini par le plugin (validé par le schéma de plugin OpenClaw natif lorsqu’il est disponible). +- `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`. - `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`). - - `maxAgeMs` : ancienneté maximale du cache en millisecondes (par défaut : `172800000` / 2 jours). - - `timeoutSeconds` : délai maximal des requêtes de scraping en secondes (par défaut : `60`). + - `onlyMainContent` : extrait uniquement le contenu principal des pages (par défaut : `true`). + - `maxAgeMs` : âge maximal du cache en millisecondes (par défaut : `172800000` / 2 jours). + - `timeoutSeconds` : délai maximal de la requête d’exploration en secondes (par défaut : `60`). - `plugins.entries.xai.config.xSearch` : paramètres de xAI X Search (recherche web Grok). - `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. Voir [Dreaming](/fr/concepts/dreaming) pour les phases et les seuils. +- `plugins.entries.memory-core.config.dreaming` : paramètres de dreaming de memory. Voir [Dreaming](/fr/concepts/dreaming) pour les phases et seuils. - `enabled` : interrupteur maître de Dreaming (par défaut `false`). - - `frequency` : cadence Cron pour chaque balayage complet de Dreaming (par défaut `"0 3 * * *"`). + - `frequency` : cadence Cron pour chaque cycle complet de dreaming (`"0 3 * * *"` par défaut). - la politique de phase et les seuils sont des détails d’implémentation (pas des clés de configuration destinées à l’utilisateur). -- La configuration complète de la mémoire se trouve dans [Référence de configuration de la mémoire](/fr/reference/memory-config) : +- La configuration complète de memory 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 des valeurs par défaut Pi embarquées à partir de `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 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 bundle Claude activés peuvent aussi contribuer des valeurs par défaut intégrées pour Pi depuis `settings.json` ; OpenClaw les applique comme paramètres d’agent assainis, et non comme correctifs bruts de configuration OpenClaw. +- `plugins.slots.memory` : choisit l’ID du plugin memory actif, ou `"none"` pour désactiver les plugins memory. +- `plugins.slots.contextEngine` : choisit l’ID du plugin de moteur de contexte actif ; vaut par défaut `"legacy"` sauf si vous installez et sélectionnez un autre moteur. +- `plugins.installs` : métadonnées d’installation gérées par la CLI, utilisées par `openclaw plugins update`. - 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. @@ -2817,29 +2964,28 @@ Voir [Plugins](/fr/tools/plugin). ``` - `evaluateEnabled: false` désactive `act:evaluate` et `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini, donc la navigation du navigateur reste stricte par défaut. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé lorsqu’il n’est pas défini, de sorte que la navigation du navigateur reste stricte par défaut. - Définissez `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` uniquement lorsque vous faites intentionnellement confiance à la navigation du navigateur sur réseau privé. -- En mode strict, les points de terminaison de profil CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage de réseau privé pendant les vérifications d’accessibilité/découverte. +- En mode strict, les points de terminaison de profils CDP distants (`profiles.*.cdpUrl`) sont soumis au même blocage des réseaux privés lors des vérifications d’accessibilité/découverte. - `ssrfPolicy.allowPrivateNetwork` reste pris en charge comme ancien alias. - En mode strict, utilisez `ssrfPolicy.hostnameAllowlist` et `ssrfPolicy.allowedHostnames` pour des exceptions explicites. -- Les profils distants sont en mode attachement uniquement (start/stop/reset désactivés). +- Les profils distants sont en mode attachement seul (démarrage/arrêt/réinitialisation désactivés). - `profiles.*.cdpUrl` accepte `http://`, `https://`, `ws://` et `wss://`. Utilisez HTTP(S) lorsque vous voulez qu’OpenClaw découvre `/json/version` ; utilisez WS(S) lorsque votre fournisseur vous donne une URL WebSocket DevTools directe. -- Les profils `existing-session` sont réservés à l’hôte et utilisent Chrome MCP au lieu de CDP. +- 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 de navigateur basé sur Chromium, comme Brave ou Edge. -- Les profils `existing-session` conservent les limites actuelles de la route Chrome MCP : - actions pilotées par snapshot/référence au lieu du ciblage par sélecteur CSS, hooks - de téléversement à un seul fichier, pas de remplacements de délai pour les boîtes de dialogue, - pas de `wait --load networkidle`, ni de `responsebody`, export PDF, interception de téléchargement - ou actions par lots. -- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; ne définissez - `cdpUrl` explicitement que pour le CDP distant. + de navigateur basé sur Chromium spécifique tel que Brave ou Edge. +- Les profils `existing-session` conservent les limites actuelles de route Chrome MCP : + actions pilotées par instantané/référence au lieu d’un ciblage par sélecteur CSS, hooks de téléversement + à fichier unique, aucun remplacement de délai maximal de boîte de dialogue, aucun `wait --load networkidle`, + et pas de `responsebody`, d’export PDF, d’interception de téléchargement, ni d’actions par lots. +- Les profils `openclaw` gérés localement attribuent automatiquement `cdpPort` et `cdpUrl` ; définissez + `cdpUrl` explicitement uniquement pour un CDP distant. - 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). --- @@ -2857,8 +3003,8 @@ Voir [Plugins](/fr/tools/plugin). } ``` -- `seamColor` : couleur d’accentuation de l’interface native de l’application (teinte de bulle du mode Talk, etc.). -- `assistant` : remplacement d’identité pour l’interface de contrôle. Revient à l’identité de l’agent actif. +- `seamColor` : couleur d’accentuation de l’interface native de l’application (teinte de la bulle du mode Talk, etc.). +- `assistant` : remplacement d’identité de l’interface de contrôle. Revient à l’identité de l’agent actif. --- @@ -2925,45 +3071,45 @@ Voir [Plugins](/fr/tools/plugin). } ``` - + -- `mode` : `local` (exécuter le Gateway) ou `remote` (se connecter à un Gateway distant). Le Gateway refuse de démarrer sauf en mode `local`. +- `mode` : `local` (exécuter la Gateway) ou `remote` (se connecter à une Gateway distante). La Gateway refuse de démarrer sauf en mode `local`. - `port` : port multiplexé unique pour WS + HTTP. Priorité : `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind` : `auto`, `loopback` (par défaut), `lan` (`0.0.0.0`), `tailnet` (IP Tailscale uniquement) ou `custom`. - **Anciens alias de bind** : utilisez les valeurs de mode bind dans `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), et non les alias d’hôte (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Remarque Docker** : le bind `loopback` par défaut écoute sur `127.0.0.1` dans le conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc le Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. -- **Auth** : requise par défaut. Les binds non-loopback nécessitent une authentification Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse conscient de l’identité avec `gateway.auth.mode: "trusted-proxy"`. L’assistant d’onboarding génère un jeton par défaut. +- **Remarque Docker** : le bind `loopback` par défaut écoute sur `127.0.0.1` à l’intérieur du conteneur. Avec le réseau bridge Docker (`-p 18789:18789`), le trafic arrive sur `eth0`, donc la Gateway est inaccessible. Utilisez `--network host`, ou définissez `bind: "lan"` (ou `bind: "custom"` avec `customBindHost: "0.0.0.0"`) pour écouter sur toutes les interfaces. +- **Auth** : requise par défaut. Les binds non-loopback nécessitent l’authentification de Gateway. En pratique, cela signifie un jeton/mot de passe partagé ou un proxy inverse conscient de l’identité avec `gateway.auth.mode: "trusted-proxy"`. L’assistant d’onboarding génère un jeton par défaut. - Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés (y compris via SecretRef), définissez explicitement `gateway.auth.mode` sur `token` ou `password`. Les flux de démarrage et d’installation/réparation du service échouent lorsque les deux sont configurés et que le mode n’est pas défini. -- `gateway.auth.mode: "none"` : mode explicite sans auth. À utiliser uniquement pour des configurations loopback locales de confiance ; 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 proxies inverses loopback sur le même hôte ne satisfont pas l’authentification trusted-proxy. -- `gateway.auth.allowTailscale` : lorsqu’il vaut `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’authentification de l’interface de contrôle/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison d’API HTTP n’utilisent **pas** cette auth par en-tête Tailscale ; ils suivent à la place le mode d’auth HTTP normal du Gateway. Ce flux sans jeton suppose que l’hôte Gateway 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 loopback locales de confiance ; cette option n’est volontairement pas proposée par les invites d’onboarding. +- `gateway.auth.mode: "trusted-proxy"` : délègue l’authentification à un proxy inverse conscient de l’identité et fait confiance aux en-têtes d’identité issus de `gateway.trustedProxies` (voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth)). Ce mode attend une source proxy **non-loopback** ; les proxies inverses loopback sur le même hôte ne satisfont pas l’authentification trusted-proxy. +- `gateway.auth.allowTailscale` : lorsque `true`, les en-têtes d’identité Tailscale Serve peuvent satisfaire l’authentification de l’interface de contrôle/WebSocket (vérifiée via `tailscale whois`). Les points de terminaison d’API HTTP **n’utilisent pas** cette authentification d’en-tête Tailscale ; ils suivent à la place le mode d’authentification HTTP normal de la Gateway. Ce flux sans jeton suppose que l’hôte de la Gateway est de confiance. Vaut par défaut `true` lorsque `tailscale.mode = "serve"`. - `gateway.auth.rateLimit` : limite facultative des échecs d’authentification. S’applique par IP cliente et par portée d’authentification (secret partagé et jeton d’appareil sont suivis indépendamment). Les tentatives bloquées renvoient `429` + `Retry-After`. - - Sur le chemin asynchrone Tailscale Serve de l’interface de contrôle, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives concurrentes invalides d’un même client peuvent donc déclencher le limiteur dès la deuxième requête au lieu que les deux passent en course comme de simples non-correspondances. - - `gateway.auth.rateLimit.exemptLoopback` vaut par défaut `true` ; définissez `false` lorsque vous voulez intentionnellement appliquer aussi la limitation de débit au trafic localhost (pour des configurations de test ou des déploiements proxy stricts). -- Les tentatives d’auth WS d’origine navigateur sont toujours limitées avec exemption loopback désactivée (défense en profondeur contre la force brute localhost depuis le navigateur). + - Sur le chemin asynchrone de l’interface de contrôle Tailscale Serve, les tentatives échouées pour le même `{scope, clientIp}` sont sérialisées avant l’écriture de l’échec. Des tentatives incorrectes concurrentes provenant du même client peuvent donc déclencher le limiteur à la deuxième requête au lieu de laisser les deux passer comme de simples non-correspondances. + - `gateway.auth.rateLimit.exemptLoopback` vaut par défaut `true` ; définissez `false` lorsque vous souhaitez intentionnellement que le trafic localhost soit également limité (pour les configurations de test ou les déploiements proxy stricts). +- Les tentatives d’authentification WS d’origine navigateur sont toujours limitées, avec exemption loopback désactivée (défense en profondeur contre la force brute localhost depuis le navigateur). - En loopback, ces verrouillages d’origine navigateur sont isolés par valeur `Origin` normalisée, de sorte que des échecs répétés depuis une origine localhost ne verrouillent pas automatiquement une autre origine. -- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite une auth). -- `controlUi.allowedOrigins` : liste d’autorisations explicite des origines navigateur pour les connexions WebSocket Gateway. Requise lorsque des clients navigateur sont attendus depuis des origines non-loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le repli d’origine basé sur l’en-tête Host pour les déploiements qui s’appuient intentionnellement sur cette politique d’origine. +- `tailscale.mode` : `serve` (tailnet uniquement, bind loopback) ou `funnel` (public, nécessite une authentification). +- `controlUi.allowedOrigins` : liste d’autorisation explicite des origines navigateur pour les connexions WebSocket Gateway. Requise lorsque des clients navigateur sont attendus depuis des origines non-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback` : mode dangereux qui active le repli d’origine basé sur l’en-tête Host pour les déploiements qui s’appuient intentionnellement sur la politique d’origine basée sur Host. - `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 côté client de type break-glass qui autorise `ws://` en clair vers des IP de réseau privé de confiance ; par défaut, le clair reste limité au loopback. -- `gateway.remote.token` / `.password` sont des champs d’identifiants du client distant. Ils ne configurent pas à eux seuls l’authentification du Gateway. -- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après publication des inscriptions relay-backed vers le Gateway. Cette URL doit correspondre à l’URL du relais compilée dans le build iOS. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` : remplacement de dernier recours côté client qui autorise `ws://` en clair vers des IP de réseau privé de confiance ; par défaut, le texte en clair reste limité au loopback. +- `gateway.remote.token` / `.password` sont des champs d’identifiants client distant. Ils ne configurent pas à eux seuls l’authentification de Gateway. +- `gateway.push.apns.relay.baseUrl` : URL HTTPS de base du relais APNs externe utilisé par les builds iOS officiels/TestFlight après publication des enregistrements appuyés sur un relais vers la Gateway. Cette URL doit correspondre à l’URL de relais compilée dans le build iOS. - `gateway.push.apns.relay.timeoutMs` : délai maximal d’envoi Gateway-vers-relais en millisecondes. Par défaut : `10000`. -- Les inscriptions relay-backed sont déléguées à une identité Gateway spécifique. L’app iOS appairée récupère `gateway.identity.get`, inclut cette identité dans l’inscription au relais et transmet au Gateway une autorisation d’envoi à portée de l’inscription. Un autre Gateway ne peut pas réutiliser cette inscription stockée. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements temporaires par variables d’environnement pour la configuration de relais ci-dessus. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` : échappatoire réservée au développement pour les URLs de relais HTTP en loopback. Les URLs de relais de production doivent rester en HTTPS. +- Les enregistrements adossés au relais sont délégués à une identité Gateway spécifique. L’application iOS associée récupère `gateway.identity.get`, inclut cette identité dans l’enregistrement du relais et transmet à la Gateway une autorisation d’envoi à portée d’enregistrement. Une autre Gateway ne peut pas réutiliser cet enregistrement stocké. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS` : remplacements temporaires par variable d’environnement pour la configuration de relais ci-dessus. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` : échappatoire de développement uniquement pour les URL de relais HTTP loopback. Les URL de relais de production doivent rester en HTTPS. - `gateway.channelHealthCheckMinutes` : intervalle du moniteur de santé des canaux en minutes. Définissez `0` pour désactiver globalement les redémarrages du moniteur de santé. Par défaut : `5`. -- `gateway.channelStaleEventThresholdMinutes` : seuil de socket obsolète en minutes. Gardez cette valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`. +- `gateway.channelStaleEventThresholdMinutes` : seuil de socket obsolète en minutes. Conservez cette valeur supérieure ou égale à `gateway.channelHealthCheckMinutes`. Par défaut : `30`. - `gateway.channelMaxRestartsPerHour` : nombre maximal de redémarrages du moniteur de santé par canal/compte sur une heure glissante. Par défaut : `10`. -- `channels..healthMonitor.enabled` : désactivation facultative par canal des redémarrages du moniteur de santé tout en gardant le moniteur global activé. -- `channels..accounts..healthMonitor.enabled` : remplacement par compte pour les canaux multi-comptes. Lorsqu’il est défini, il a priorité sur le remplacement au niveau du canal. -- Les chemins d’appel Gateway locaux peuvent utiliser `gateway.remote.*` comme repli uniquement lorsque `gateway.auth.*` n’est pas défini. -- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en mode fermé (aucun repli distant ne masque cela). -- `trustedProxies` : IP de proxies inverses qui terminent TLS ou injectent des en-têtes de client transféré. Ne listez que les 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` : lorsqu’il vaut `true`, le Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement en échec fermé. +- `channels..healthMonitor.enabled` : désactivation facultative par canal des redémarrages du moniteur de santé, tout en conservant le moniteur global activé. +- `channels..accounts..healthMonitor.enabled` : remplacement par compte pour les canaux multi-comptes. Lorsqu’il est défini, il prend priorité sur le remplacement au niveau du canal. +- Les chemins d’appel de Gateway locale peuvent utiliser `gateway.remote.*` comme repli uniquement lorsque `gateway.auth.*` n’est pas défini. +- Si `gateway.auth.token` / `gateway.auth.password` est explicitement configuré via SecretRef et non résolu, la résolution échoue en mode fermé (aucun repli distant masquant). +- `trustedProxies` : IP des proxies inverses qui terminent TLS ou injectent des en-têtes client transférés. Ne listez que des proxies que vous contrôlez. Les entrées loopback restent valides pour les configurations de détection locale/proxy sur le même hôte (par exemple Tailscale Serve ou un proxy inverse local), mais elles ne rendent **pas** les requêtes loopback éligibles à `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback` : lorsque `true`, la Gateway accepte `X-Real-IP` si `X-Forwarded-For` est absent. Par défaut `false` pour un comportement en échec sécurisé. - `gateway.tools.deny` : noms d’outils supplémentaires bloqués pour HTTP `POST /tools/invoke` (étend la liste de refus par défaut). - `gateway.tools.allow` : retire des noms d’outils de la liste de refus HTTP par défaut. @@ -2971,20 +3117,20 @@ 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` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Les listes d’autorisations vides sont traitées comme non définies ; utilisez `gateway.http.endpoints.responses.files.allowUrl=false` + Les listes d’autorisation vides sont traitées comme non définies ; utilisez `gateway.http.endpoints.responses.files.allowUrl=false` et/ou `gateway.http.endpoints.responses.images.allowUrl=false` pour désactiver la récupération d’URL. - En-tête facultatif de renforcement des réponses : - - `gateway.http.securityHeaders.strictTransportSecurity` (à définir uniquement pour 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 les origines HTTPS que vous contrôlez ; voir [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolation multi-instance -Exécutez plusieurs Gateway sur un même hôte avec des ports et répertoires d’état uniques : +Exécutez plusieurs Gateways sur un même hôte avec des ports et des répertoires d’état uniques : ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2992,9 +3138,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Indicateurs pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). +Drapeaux pratiques : `--dev` (utilise `~/.openclaw-dev` + port `19001`), `--profile ` (utilise `~/.openclaw-`). -Voir [Passerelles multiples](/fr/gateway/multiple-gateways). +Voir [Gateways multiples](/fr/gateway/multiple-gateways). ### `gateway.tls` @@ -3013,10 +3159,10 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). ``` - `enabled` : active la terminaison TLS au niveau de l’écouteur Gateway (HTTPS/WSS) (par défaut : `false`). -- `autoGenerate` : génère automatiquement une paire cert/key auto-signée locale lorsque des fichiers explicites ne sont pas configurés ; réservé à un usage local/dev. -- `certPath` : chemin système de fichiers vers le certificat TLS. -- `keyPath` : chemin système de fichiers vers la clé privée TLS ; gardez des permissions restreintes. -- `caPath` : chemin facultatif du bundle CA pour la vérification client ou les chaînes de confiance personnalisées. +- `autoGenerate` : génère automatiquement une paire locale certifié/clé auto-signée lorsque des fichiers explicites ne sont pas configurés ; pour un usage local/dev uniquement. +- `certPath` : chemin du système de fichiers vers le fichier de certificat TLS. +- `keyPath` : chemin du système de fichiers vers le fichier de clé privée TLS ; conservez des permissions restreintes. +- `caPath` : chemin facultatif du bundle CA pour la vérification client ou des chaînes de confiance personnalisées. ### `gateway.reload` @@ -3035,10 +3181,10 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). - `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 Gateway lors d’un changement de configuration. - - `"hot"` : applique les changements dans le processus sans redémarrer. - - `"hybrid"` (par défaut) : essaie d’abord le rechargement à chaud ; revient au redémarrage si nécessaire. -- `debounceMs` : fenêtre de debounce en ms avant l’application des changements de configuration (entier non négatif). -- `deferralTimeoutMs` : temps maximal en ms d’attente des opérations en vol avant de forcer un redémarrage (par défaut : `300000` = 5 minutes). + - `"hot"` : applique les changements dans le processus sans redémarrage. + - `"hybrid"` (par défaut) : tente d’abord le rechargement à chaud ; revient au redémarrage si nécessaire. +- `debounceMs` : fenêtre d’anti-rebond en ms avant l’application des changements de configuration (entier non négatif). +- `deferralTimeoutMs` : durée maximale en ms d’attente des opérations en cours avant de forcer un redémarrage (par défaut : `300000` = 5 minutes). --- @@ -3076,34 +3222,34 @@ Voir [Passerelles multiples](/fr/gateway/multiple-gateways). ``` Auth : `Authorization: Bearer ` ou `x-openclaw-token: `. -Les jetons de hook dans la chaîne de requête sont rejetés. +Les jetons de hook dans la chaîne de requête sont refusés. -Notes de validation et de sécurité : +Remarques de validation et de sécurité : - `hooks.enabled=true` nécessite un `hooks.token` non vide. -- `hooks.token` doit être **distinct** de `gateway.auth.token` ; la réutilisation du jeton Gateway est rejetée. +- `hooks.token` doit être **distinct** de `gateway.auth.token` ; la réutilisation du jeton Gateway est refusée. - `hooks.path` ne peut pas être `/` ; utilisez un sous-chemin dédié tel que `/hooks`. -- Si `hooks.allowRequestSessionKey=true`, 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` depuis la charge utile de requête n’est accepté que lorsque `hooks.allowRequestSessionKey=true` (par défaut : `false`). + - `sessionKey` issu 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. -- Des modèles comme `{{messages[0].subject}}` lisent depuis la charge utile. +- Les modèles comme `{{messages[0].subject}}` lisent depuis la charge utile. - `transform` peut pointer vers un module JS/TS renvoyant une action de hook. - - `transform.module` doit être un chemin relatif et reste dans `hooks.transformsDir` (les chemins absolus et la traversée sont rejetés). + - `transform.module` doit être un chemin relatif et rester dans `hooks.transformsDir` (les chemins absolus et la traversée sont refusés). - `agentId` route vers un agent spécifique ; les ID inconnus reviennent à l’agent par défaut. - `allowedAgentIds` : restreint le routage explicite (`*` ou omis = tout autoriser, `[]` = tout refuser). -- `defaultSessionKey` : clé de session fixe facultative pour les exécutions d’agent hook sans `sessionKey` explicite. -- `allowRequestSessionKey` : autorise les appelants de `/hooks/agent` à définir `sessionKey` (par défaut : `false`). -- `allowedSessionKeyPrefixes` : liste d’autorisations facultative des préfixes pour les valeurs explicites `sessionKey` (requête + mapping), par ex. `["hook:"]`. +- `defaultSessionKey` : clé de session fixe facultative pour les exécutions d’agent de hook sans `sessionKey` explicite. +- `allowRequestSessionKey` : permet aux appelants de `/hooks/agent` de définir `sessionKey` (par défaut : `false`). +- `allowedSessionKeyPrefixes` : liste d’autorisation facultative des préfixes pour les valeurs `sessionKey` explicites (requête + mappage), par ex. `["hook:"]`. - `deliver: true` envoie la réponse finale à un canal ; `channel` vaut par défaut `last`. - `model` remplace le LLM pour cette exécution de hook (doit être autorisé si le catalogue de modèles est défini). @@ -3132,8 +3278,8 @@ Notes de validation et de sécurité : } ``` -- Le Gateway démarre automatiquement `gog gmail watch serve` au démarrage lorsqu’il est configuré. Définissez `OPENCLAW_SKIP_GMAIL_WATCHER=1` pour le désactiver. -- N’exécutez pas un `gog gmail watch serve` séparé en parallèle du Gateway. +- La Gateway démarre automatiquement `gog gmail watch serve` au démarrage lorsqu’il est configuré. Définissez `OPENCLAW_SKIP_GMAIL_WATCHER=1` pour le désactiver. +- N’exécutez pas un `gog gmail watch serve` distinct en parallèle de la Gateway. --- @@ -3149,18 +3295,18 @@ Notes de validation et de sécurité : } ``` -- Sert du HTML/CSS/JS modifiable par agent et A2UI en HTTP sous le port Gateway : +- Sert du HTML/CSS/JS modifiable par l’agent et A2UI sur HTTP sous le port Gateway : - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Local uniquement : conservez `gateway.bind: "loopback"` (par défaut). -- Binds non-loopback : les routes canvas nécessitent l’authentification Gateway (token/password/trusted-proxy), comme les autres surfaces HTTP Gateway. -- Les Node WebViews n’envoient généralement pas d’en-têtes d’authentification ; une fois qu’un node est appairé et connecté, le Gateway annonce des URLs de capacité à portée du node pour l’accès canvas/A2UI. -- Les URLs de capacité sont liées à la session WS du node active et expirent rapidement. Le repli basé sur l’IP n’est pas utilisé. -- Injecte un client live-reload dans le HTML servi. -- Crée automatiquement un `index.html` de démarrage lorsqu’il est vide. -- Sert également A2UI à `/__openclaw__/a2ui/`. -- Les modifications nécessitent un redémarrage du Gateway. -- Désactivez le live reload pour les grands répertoires ou les erreurs `EMFILE`. +- Binds non-loopback : les routes canvas nécessitent l’authentification Gateway (jeton/mot de passe/trusted-proxy), comme les autres surfaces HTTP Gateway. +- Les Node WebViews n’envoient généralement pas d’en-têtes d’authentification ; une fois qu’un node est appairé et connecté, la Gateway annonce des URL de capacité à portée de node pour l’accès à canvas/A2UI. +- Les URL de capacité sont liées à la session WS active du node et expirent rapidement. Aucun repli basé sur l’IP n’est utilisé. +- Injecte un client de rechargement en direct dans le HTML servi. +- Crée automatiquement un `index.html` de démarrage lorsque le répertoire est vide. +- Sert aussi A2UI à `/__openclaw__/a2ui/`. +- Les changements nécessitent un redémarrage de la Gateway. +- Désactivez le rechargement en direct pour les grands répertoires ou en cas d’erreurs `EMFILE`. --- @@ -3192,7 +3338,7 @@ Notes de validation et de sécurité : } ``` -Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour la découverte inter-réseaux, combinez cela avec un serveur DNS (CoreDNS recommandé) + DNS fractionné Tailscale. +Écrit une zone DNS-SD unicast sous `~/.openclaw/dns/`. Pour une découverte inter-réseaux, combinez-la avec un serveur DNS (CoreDNS recommandé) + DNS fractionné Tailscale. Installation : `openclaw dns setup --apply`. @@ -3200,7 +3346,7 @@ Installation : `openclaw dns setup --apply`. ## Environnement -### `env` (variables d’environnement inline) +### `env` (variables d’environnement en ligne) ```json5 { @@ -3217,9 +3363,9 @@ Installation : `openclaw dns setup --apply`. } ``` -- Les variables d’environnement inline ne sont appliquées que si l’environnement du processus ne contient pas déjà la clé. -- Fichiers `.env` : `.env` du CWD + `~/.openclaw/.env` (aucun ne remplace les variables existantes). -- `shellEnv` : importe les clés attendues manquantes depuis le profil de votre shell de connexion. +- Les variables d’environnement en ligne ne sont appliquées que si l’environnement du processus ne contient pas déjà la clé. +- Fichiers `.env` : `.env` du répertoire de travail actuel + `~/.openclaw/.env` (aucun des deux ne remplace des variables existantes). +- `shellEnv` : importe les clés attendues manquantes depuis votre profil de shell de connexion. - Voir [Environnement](/fr/help/environment) pour l’ordre de priorité complet. ### Substitution de variables d’environnement @@ -3234,16 +3380,16 @@ Référencez des variables d’environnement dans n’importe quelle chaîne de } ``` -- Seuls les noms en majuscules sont pris en charge : `[A-Z_][A-Z0-9_]*`. +- Seuls les noms en majuscules sont reconnus : `[A-Z_][A-Z0-9_]*`. - Les variables manquantes/vides provoquent une erreur au chargement de la configuration. -- Échappez avec `$${VAR}` pour obtenir un `${VAR}` littéral. +- Échappez avec `$${VAR}` pour obtenir un littéral `${VAR}`. - Fonctionne avec `$include`. --- ## Secrets -Les références de secret sont additives : les valeurs en texte brut continuent de fonctionner. +Les références de secret sont additives : les valeurs en clair fonctionnent toujours. ### `SecretRef` @@ -3255,17 +3401,17 @@ Utilisez une seule forme d’objet : Validation : -- motif `provider` : `^[a-z][a-z0-9_-]{0,63}$` -- motif `source: "env"` pour `id` : `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` pour `id` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) -- motif `source: "exec"` pour `id` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- les `id` avec `source: "exec"` ne doivent pas contenir de segments de chemin `/` délimités `.` ou `..` (par exemple `a/../b` est rejeté) +- motif de `provider` : `^[a-z][a-z0-9_-]{0,63}$` +- motif de `id` pour `source: "env"` : `^[A-Z][A-Z0-9_]{0,127}$` +- `id` pour `source: "file"` : pointeur JSON absolu (par exemple `"/providers/openai/apiKey"`) +- motif de `id` pour `source: "exec"` : `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- les `id` avec `source: "exec"` ne doivent pas contenir de segments de chemin séparés par `/` égaux à `.` ou `..` (par exemple `a/../b` est refusé) ### Surface d’identifiants prise en charge -- Matrice canonique : [Surface d’identifiants SecretRef](/fr/reference/secretref-credential-surface) -- `secrets apply` cible les chemins d’identifiants pris en charge de `openclaw.json`. -- Les références `auth-profiles.json` sont incluses dans la résolution d’exécution et la couverture d’audit. +- Matrice canonique : [Surface des identifiants SecretRef](/fr/reference/secretref-credential-surface) +- `secrets apply` cible les chemins d’identifiants pris en charge dans `openclaw.json`. +- Les références `auth-profiles.json` sont incluses dans la résolution à l’exécution et dans la couverture d’audit. ### Configuration des fournisseurs de secrets @@ -3299,15 +3445,15 @@ Remarques : - Le fournisseur `file` prend en charge `mode: "json"` et `mode: "singleValue"` (`id` doit être `"value"` en mode singleValue). - Le fournisseur `exec` nécessite un chemin `command` absolu et utilise des charges utiles de protocole sur stdin/stdout. -- Par défaut, les chemins de commande symlink sont rejetés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symlink tout en validant le chemin de la cible résolue. -- Si `trustedDirs` est configuré, la vérification des répertoires de confiance s’applique au chemin de la cible résolue. +- Par défaut, les chemins de commande symboliques sont refusés. Définissez `allowSymlinkCommand: true` pour autoriser les chemins symboliques tout en validant le chemin cible résolu. +- Si `trustedDirs` est configuré, la vérification des répertoires de confiance s’applique au chemin cible résolu. - L’environnement enfant `exec` est minimal par défaut ; transmettez explicitement les variables requises avec `passEnv`. -- Les références de secret sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête lisent uniquement cet instantané. -- Le filtrage de surface active s’applique pendant l’activation : les références non résolues sur des surfaces actives font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec diagnostics. +- Les références de secret sont résolues au moment de l’activation dans un instantané en mémoire, puis les chemins de requête ne lisent que cet instantané. +- Le filtrage de surface active s’applique pendant l’activation : les références non résolues sur des surfaces activées font échouer le démarrage/rechargement, tandis que les surfaces inactives sont ignorées avec des diagnostics. --- -## Stockage Auth +## Stockage d’authentification ```json5 { @@ -3326,12 +3472,12 @@ Remarques : ``` - Les profils par agent sont stockés dans `/auth-profiles.json`. -- `auth-profiles.json` prend en charge des références au niveau valeur (`keyRef` pour `api_key`, `tokenRef` pour `token`) pour les modes d’identifiants statiques. -- Les profils en mode OAuth (`auth.profiles..mode = "oauth"`) ne prennent pas en charge les identifiants `auth-profile` appuyés sur SecretRef. -- Les identifiants statiques d’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. -- Les imports OAuth hérités proviennent de `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` prend en charge les références au niveau des valeurs (`keyRef` pour `api_key`, `tokenRef` pour `token`) pour les modes d’identifiants statiques. +- Les profils en mode OAuth (`auth.profiles..mode = "oauth"`) ne prennent pas en charge les identifiants de profil d’authentification adossés à SecretRef. +- Les identifiants statiques à l’exécution proviennent d’instantanés résolus en mémoire ; les anciennes entrées statiques `auth.json` sont nettoyées lorsqu’elles sont découvertes. +- Les anciennes importations OAuth proviennent de `~/.openclaw/credentials/oauth.json`. - Voir [OAuth](/fr/concepts/oauth). -- Comportement d’exécution des secrets et outils `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). +- Comportement du runtime des secrets et outillage `audit/configure/apply` : [Gestion des secrets](/fr/gateway/secrets). ### `auth.cooldowns` @@ -3353,20 +3499,21 @@ Remarques : } ``` -- `billingBackoffHours` : backoff de base en heures lorsqu’un profil échoue à cause de vraies +- `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 tomber ici même sur des réponses `401`/`403`, mais les - matchers de texte spécifiques au fournisseur restent limités au fournisseur qui les possède (par exemple OpenRouter - `Key limit exceeded`). Les messages retryable HTTP `402` de fenêtre d’utilisation ou de - limite de dépense d’organisation/workspace restent à la place dans le chemin `rate_limit`. -- `billingBackoffHoursByProvider` : remplacements facultatifs par fournisseur pour les heures de backoff de facturation. -- `billingMaxHours` : plafond en heures pour la croissance exponentielle du backoff de facturation (par défaut : `24`). -- `authPermanentBackoffMinutes` : backoff de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`). -- `authPermanentMaxMinutes` : plafond en minutes pour la croissance du backoff `auth_permanent` (par défaut : `60`). -- `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de backoff (par défaut : `24`). -- `overloadedProfileRotations` : nombre maximal de rotations de profil auth chez le même fournisseur pour des erreurs de surcharge avant de basculer vers le repli de modèle (par défaut : `1`). Des formes de fournisseur occupé telles que `ModelNotReadyException` tombent ici. -- `overloadedBackoffMs` : délai fixe avant une nouvelle tentative de rotation de profil/fournisseur surchargé (par défaut : `0`). -- `rateLimitedProfileRotations` : nombre maximal de rotations de profil auth chez le même fournisseur pour des erreurs de limitation de débit avant de basculer vers le repli de modèle (par défaut : `1`). Ce compartiment de limitation de débit inclut des textes typiques de fournisseur tels que `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. + toujours arriver ici même sur des réponses `401`/`403`, mais les + correspondances textuelles spécifiques au fournisseur restent limitées au fournisseur qui les possède (par exemple OpenRouter + `Key limit exceeded`). Les messages HTTP `402` de fenêtre d’utilisation ou de + limite de dépense d’organisation/espace de travail qui peuvent être réessayés restent dans le chemin `rate_limit` + à la place. +- `billingBackoffHoursByProvider` : remplacements facultatifs par fournisseur pour le délai de repli de facturation en heures. +- `billingMaxHours` : plafond en heures pour la croissance exponentielle du délai de repli de facturation (par défaut : `24`). +- `authPermanentBackoffMinutes` : délai de repli de base en minutes pour les échecs `auth_permanent` à forte confiance (par défaut : `10`). +- `authPermanentMaxMinutes` : plafond en minutes pour la croissance du délai de repli `auth_permanent` (par défaut : `60`). +- `failureWindowHours` : fenêtre glissante en heures utilisée pour les compteurs de délai de repli (par défaut : `24`). +- `overloadedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas d’erreurs de surcharge avant de basculer vers le modèle de repli (par défaut : `1`). Les formes indiquant un fournisseur occupé comme `ModelNotReadyException` arrivent ici. +- `overloadedBackoffMs` : délai fixe avant nouvelle tentative d’une rotation de profil/fournisseur surchargé (par défaut : `0`). +- `rateLimitedProfileRotations` : nombre maximal de rotations de profil d’authentification pour un même fournisseur en cas d’erreurs de limite de débit avant de basculer vers le modèle de repli (par défaut : `1`). Cette catégorie de limite de débit inclut des textes typiques du fournisseur comme `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` et `resource exhausted`. --- @@ -3388,7 +3535,7 @@ Remarques : - Fichier journal par défaut : `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Définissez `logging.file` pour un chemin stable. - `consoleLevel` passe à `debug` avec `--verbose`. -- `maxFileBytes` : taille maximale du fichier journal en octets avant suppression des écritures (entier positif ; par défaut : `524288000` = 500 MB). Utilisez une rotation externe des journaux pour les déploiements de production. +- `maxFileBytes` : taille maximale du fichier journal en octets avant que les écritures soient supprimées (entier positif ; par défaut : `524288000` = 500 MB). Utilisez une rotation externe des journaux pour les déploiements de production. --- @@ -3426,18 +3573,18 @@ Remarques : ``` - `enabled` : interrupteur maître de sortie d’instrumentation (par défaut : `true`). -- `flags` : tableau de chaînes de drapeaux activant une sortie de journal ciblée (prend en charge des jokers comme `"telegram.*"` ou `"*"`). +- `flags` : tableau de chaînes de drapeaux activant une sortie journal ciblée (prend en charge des jokers comme `"telegram.*"` ou `"*"`). - `stuckSessionWarnMs` : seuil d’ancienneté en ms pour émettre des avertissements de session bloquée tant qu’une session reste à l’état de traitement. - `otel.enabled` : active le pipeline d’export OpenTelemetry (par défaut : `false`). - `otel.endpoint` : URL du collecteur pour l’export OTel. - `otel.protocol` : `"http/protobuf"` (par défaut) ou `"grpc"`. - `otel.headers` : en-têtes de métadonnées HTTP/gRPC supplémentaires envoyés avec les requêtes d’export OTel. - `otel.serviceName` : nom de service pour les attributs de ressource. -- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export de traces, de métriques ou de journaux. +- `otel.traces` / `otel.metrics` / `otel.logs` : active l’export de traces, métriques ou journaux. - `otel.sampleRate` : taux d’échantillonnage des traces `0`–`1`. - `otel.flushIntervalMs` : intervalle périodique de vidage de télémétrie en ms. -- `cacheTrace.enabled` : journalise les instantanés de trace de cache pour les exécutions embarquées (par défaut : `false`). -- `cacheTrace.filePath` : chemin de sortie du JSONL de trace de cache (par défaut : `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.enabled` : journalise des instantanés de trace de cache pour les exécutions intégrées (par défaut : `false`). +- `cacheTrace.filePath` : chemin de sortie pour le JSONL de trace de cache (par défaut : `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem` : contrôlent ce qui est inclus dans la sortie de trace de cache (tous à `true` par défaut). --- @@ -3461,11 +3608,11 @@ Remarques : ``` - `channel` : canal de publication pour les installations npm/git — `"stable"`, `"beta"` ou `"dev"`. -- `checkOnStart` : vérifie les mises à jour npm au démarrage du Gateway (par défaut : `true`). -- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations de package (par défaut : `false`). +- `checkOnStart` : vérifie les mises à jour npm au démarrage de la Gateway (par défaut : `true`). +- `auto.enabled` : active la mise à jour automatique en arrière-plan pour les installations par paquet (par défaut : `false`). - `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 des vérifications sur le canal bêta en heures (par défaut : `1` ; max : `24`). +- `auto.stableJitterHours` : fenêtre supplémentaire de répartition du déploiement sur le canal stable en heures (par défaut : `12` ; max : `168`). +- `auto.betaCheckIntervalHours` : fréquence d’exécution des vérifications du canal bêta en heures (par défaut : `1` ; max : `24`). --- @@ -3498,22 +3645,22 @@ Remarques : } ``` -- `enabled` : gate de fonctionnalité ACP globale (par défaut : `false`). -- `dispatch.enabled` : gate indépendante pour la distribution des tours de session ACP (par défaut : `true`). Définissez `false` pour garder les commandes ACP disponibles tout en bloquant l’exécution. -- `backend` : ID backend d’exécution ACP par défaut (doit correspondre à un Plugin d’exécution ACP enregistré). -- `defaultAgent` : ID d’agent cible ACP de repli lorsque les créations ne spécifient pas de cible explicite. -- `allowedAgents` : liste d’autorisations des ID d’agents permis pour les sessions d’exécution ACP ; vide signifie aucune restriction supplémentaire. +- `enabled` : garde-fou global de fonctionnalité ACP (par défaut : `false`). +- `dispatch.enabled` : garde-fou indépendant pour la distribution des tours de session ACP (par défaut : `true`). Définissez `false` pour conserver les commandes ACP disponibles tout en bloquant l’exécution. +- `backend` : ID du backend de runtime ACP par défaut (doit correspondre à un Plugin de runtime ACP enregistré). +- `defaultAgent` : ID d’agent ACP cible de repli lorsque les créations ne spécifient pas de cible explicite. +- `allowedAgents` : liste d’autorisation des ID d’agent permis pour les sessions de runtime ACP ; vide signifie aucune restriction supplémentaire. - `maxConcurrentSessions` : nombre maximal de sessions ACP actives simultanément. -- `stream.coalesceIdleMs` : fenêtre de flush à l’inactivité en ms pour le texte diffusé. -- `stream.maxChunkChars` : taille maximale d’un morceau avant division de la projection du bloc diffusé. -- `stream.repeatSuppression` : supprime les lignes répétées de statut/d’outil par tour (par défaut : `true`). -- `stream.deliveryMode` : `"live"` diffuse progressivement ; `"final_only"` met en mémoire tampon jusqu’aux événements terminaux du tour. +- `stream.coalesceIdleMs` : fenêtre de vidage à l’inactivité en ms pour le texte diffusé en continu. +- `stream.maxChunkChars` : taille maximale de bloc avant découpage de la projection de bloc diffusé en continu. +- `stream.repeatSuppression` : supprime les lignes répétées de statut/outil par tour (par défaut : `true`). +- `stream.deliveryMode` : `"live"` diffuse progressivement ; `"final_only"` met en tampon jusqu’aux événements terminaux du tour. - `stream.hiddenBoundarySeparator` : séparateur avant le texte visible après des événements d’outil cachés (par défaut : `"paragraph"`). - `stream.maxOutputChars` : nombre maximal de caractères de sortie assistant projetés par tour ACP. - `stream.maxSessionUpdateChars` : nombre maximal de caractères pour les lignes projetées de statut/mise à jour ACP. -- `stream.tagVisibility` : enregistrement des noms de balises vers des remplacements booléens de visibilité pour les événements diffusés. -- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant qu’ils soient éligibles au nettoyage. -- `runtime.installCommand` : commande d’installation facultative à exécuter lors du bootstrap d’un environnement d’exécution ACP. +- `stream.tagVisibility` : enregistrement des noms de balise vers des remplacements booléens de visibilité pour les événements diffusés. +- `runtime.ttlMinutes` : TTL d’inactivité en minutes pour les workers de session ACP avant éligibilité au nettoyage. +- `runtime.installCommand` : commande d’installation facultative à exécuter lors de l’amorçage d’un environnement de runtime ACP. --- @@ -3529,17 +3676,17 @@ Remarques : } ``` -- `cli.banner.taglineMode` contrôle le style du slogan de bannière : - - `"random"` (par défaut) : slogans tournants, amusants/de saison. +- `cli.banner.taglineMode` contrôle le style du slogan de la bannière : + - `"random"` (par défaut) : slogans tournants humoristiques/de saison. - `"default"` : slogan neutre fixe (`All your chats, one OpenClaw.`). - - `"off"` : aucun texte de slogan (le titre/la version de la bannière restent affichés). -- Pour masquer toute la bannière (pas seulement les slogans), définissez la variable d’environnement `OPENCLAW_HIDE_BANNER=1`. + - `"off"` : aucun texte de slogan (le titre/version de la bannière reste affiché). +- Pour masquer toute la bannière (et pas seulement les slogans), définissez la variable d’environnement `OPENCLAW_HIDE_BANNER=1`. --- -## Wizard +## Assistant -Métadonnées écrites par les flux d’installation guidée de la CLI (`onboard`, `configure`, `doctor`) : +Métadonnées écrites par les flux d’installation guidée CLI (`onboard`, `configure`, `doctor`) : ```json5 { @@ -3563,9 +3710,9 @@ Voir les champs d’identité de `agents.list` sous [Valeurs par défaut des age ## Bridge (hérité, supprimé) -Les builds actuels n’incluent plus le bridge TCP. Les nodes se connectent via le WebSocket Gateway. Les clés `bridge.*` ne font plus partie du schéma de configuration (la validation échoue tant qu’elles ne sont pas supprimées ; `openclaw doctor --fix` peut retirer les clés inconnues). +Les versions actuelles n’incluent plus le bridge TCP. Les nodes se connectent via le WebSocket Gateway. Les clés `bridge.*` ne font plus partie du schéma de configuration (la validation échoue tant qu’elles ne sont pas supprimées ; `openclaw doctor --fix` peut retirer les clés inconnues). - + ```json { @@ -3603,11 +3750,11 @@ Les builds actuels n’incluent plus le bridge TCP. Les nodes se connectent via } ``` -- `sessionRetention` : durée de conservation des sessions d’exécution Cron isolées terminées avant élagage de `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 isolées terminées d’exécution Cron avant leur élagage de `sessions.json`. Contrôle également le nettoyage des transcriptions Cron supprimées archivées. Par défaut : `24h` ; définissez `false` pour désactiver. - `runLog.maxBytes` : taille maximale par fichier journal d’exécution (`cron/runs/.jsonl`) avant élagage. Par défaut : `2_000_000` octets. -- `runLog.keepLines` : nombre de 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"`) ; s’il est omis, aucun en-tête d’authentification n’est envoyé. -- `webhook` : URL Webhook de repli héritée obsolète (http/https) utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. +- `runLog.keepLines` : plus récentes lignes conservées lorsque l’élagage du journal d’exécution est déclenché. Par défaut : `2000`. +- `webhookToken` : jeton bearer utilisé pour la livraison POST Webhook de Cron (`delivery.mode = "webhook"`) ; s’il est omis, aucun en-tête d’authentification n’est envoyé. +- `webhook` : URL Webhook héritée de repli obsolète (http/https), utilisée uniquement pour les tâches stockées qui ont encore `notify: true`. ### `cron.retry` @@ -3623,11 +3770,11 @@ Les builds actuels n’incluent plus le bridge TCP. Les nodes se connectent via } ``` -- `maxAttempts` : nombre maximal de nouvelles tentatives pour les tâches ponctuelles sur erreurs transitoires (par défaut : `3` ; plage : `0`–`10`). -- `backoffMs` : tableau de délais de backoff 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 ce champ pour réessayer tous les types transitoires. +- `maxAttempts` : nombre maximal de nouvelles tentatives pour les tâches ponctuelles en cas d’erreurs transitoires (par défaut : `3` ; plage : `0`–`10`). +- `backoffMs` : tableau des délais de repli en ms pour chaque tentative de nouvelle exécution (par défaut : `[30000, 60000, 300000]` ; 1 à 10 entrées). +- `retryOn` : types d’erreur qui déclenchent des nouvelles tentatives — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omettez pour réessayer tous les types transitoires. -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 distincte des échecs. ### `cron.failureAlert` @@ -3646,10 +3793,10 @@ S’applique uniquement aux tâches Cron ponctuelles. Les tâches récurrentes u ``` - `enabled` : active les alertes d’échec pour les tâches Cron (par défaut : `false`). -- `after` : nombre d’échecs consécutifs avant le déclenchement d’une alerte (entier positif, min : `1`). +- `after` : nombre d’échecs consécutifs avant déclenchement d’une alerte (entier positif, min : `1`). - `cooldownMs` : nombre minimal de millisecondes entre des alertes répétées pour la même tâche (entier non négatif). - `mode` : mode de livraison — `"announce"` envoie via un message de canal ; `"webhook"` publie vers le Webhook configuré. -- `accountId` : ID facultatif de compte ou de canal pour limiter la portée de la livraison d’alerte. +- `accountId` : ID facultatif de compte ou de canal pour limiter la portée de la livraison de l’alerte. ### `cron.failureDestination` @@ -3666,16 +3813,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"` lorsqu’il existe assez de données de cible. -- `channel` : remplacement du canal pour la livraison announce. `"last"` réutilise le dernier canal de livraison connu. -- `to` : cible announce explicite ou URL Webhook. Obligatoire en mode Webhook. +- Destination par défaut pour les notifications d’échec Cron sur l’ensemble des tâches. +- `mode` : `"announce"` ou `"webhook"` ; vaut par défaut `"announce"` lorsque suffisamment de données de cible existent. +- `channel` : remplacement de canal pour la livraison par annonce. `"last"` réutilise le dernier canal de livraison connu. +- `to` : cible explicite d’annonce ou URL Webhook. Obligatoire pour le mode webhook. - `accountId` : remplacement facultatif du compte pour la livraison. -- `delivery.failureDestination` par tâche remplace cette valeur par défaut globale. -- 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"`. +- `delivery.failureDestination` par tâche remplace cette valeur globale par défaut. +- Lorsqu’aucune destination d’échec globale ou par tâche n’est définie, les tâches qui livrent déjà via `announce` reviennent, en cas d’échec, à cette cible d’annonce principale. +- `delivery.failureDestination` n’est pris en charge que pour les tâches `sessionTarget="isolated"`, sauf si le `delivery.mode` principal de la tâche est `"webhook"`. -Voir [Tâches Cron](/fr/automation/cron-jobs). Les exécutions Cron isolées sont suivies comme des [tâches en arrière-plan](/fr/automation/tasks). +Voir [Tâches Cron](/fr/automation/cron-jobs). Les exécutions Cron isolées sont suivies comme des [tâches d’arrière-plan](/fr/automation/tasks). --- @@ -3686,7 +3833,7 @@ Espaces réservés de modèle développés dans `tools.media.models[].args` : | Variable | Description | | ------------------ | ------------------------------------------------- | | `{{Body}}` | Corps complet du message entrant | -| `{{RawBody}}` | Corps brut (sans wrappers d’historique/d’expéditeur) | +| `{{RawBody}}` | Corps brut (sans historique/enveloppes d’expéditeur) | | `{{BodyStripped}}` | Corps avec les mentions de groupe supprimées | | `{{From}}` | Identifiant de l’expéditeur | | `{{To}}` | Identifiant de destination | @@ -3697,20 +3844,20 @@ Espaces réservés de modèle développés dans `tools.media.models[].args` : | `{{MediaPath}}` | chemin local du média | | `{{MediaType}}` | type de média (image/audio/document/…) | | `{{Transcript}}` | transcription audio | -| `{{Prompt}}` | 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 | +| `{{Prompt}}` | invite média résolue pour les entrées CLI | +| `{{MaxChars}}` | nombre maximal résolu de caractères de sortie pour les entrées CLI | | `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | sujet du groupe (au mieux) | -| `{{GroupMembers}}` | aperçu des membres du groupe (au mieux) | -| `{{SenderName}}` | nom d’affichage de l’expéditeur (au mieux) | -| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (au mieux) | -| `{{Provider}}` | indication de fournisseur (whatsapp, telegram, discord, etc.) | +| `{{GroupSubject}}` | sujet du groupe (meilleur effort) | +| `{{GroupMembers}}` | aperçu des membres du groupe (meilleur effort) | +| `{{SenderName}}` | nom d’affichage de l’expéditeur (meilleur effort) | +| `{{SenderE164}}` | numéro de téléphone de l’expéditeur (meilleur effort) | +| `{{Provider}}` | indication du fournisseur (whatsapp, telegram, discord, etc.) | --- -## Inclusions de configuration (`$include`) +## Includes de configuration (`$include`) -Divisez la configuration en plusieurs fichiers : +Scindez la configuration en plusieurs fichiers : ```json5 // ~/.openclaw/openclaw.json @@ -3727,10 +3874,10 @@ Divisez la configuration en plusieurs fichiers : - 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. +- Clés sœurs : fusionnées après les includes (remplacent les valeurs incluses). +- Includes imbriqués : jusqu’à 10 niveaux de profondeur. - Chemins : résolus relativement au fichier incluant, mais doivent rester dans le répertoire de configuration de niveau supérieur (`dirname` de `openclaw.json`). Les formes absolues/`../` sont autorisées uniquement si elles se résolvent toujours à l’intérieur de cette limite. -- Erreurs : messages clairs pour les fichiers manquants, les erreurs d’analyse et les inclusions circulaires. +- Erreurs : messages clairs pour les fichiers manquants, les erreurs d’analyse et les includes circulaires. --- diff --git a/docs/fr/plugins/sdk-channel-plugins.md b/docs/fr/plugins/sdk-channel-plugins.md index 4752e3e73..2a7bc9006 100644 --- a/docs/fr/plugins/sdk-channel-plugins.md +++ b/docs/fr/plugins/sdk-channel-plugins.md @@ -1,16 +1,16 @@ --- read_when: - - Vous créez un nouveau Plugin de canal de messagerie. - - Vous souhaitez connecter OpenClaw à une plateforme de messagerie. - - Vous devez comprendre la surface d’adaptation de `ChannelPlugin` + - Vous créez un nouveau Plugin de canal de messagerie + - Vous souhaitez connecter OpenClaw à une plateforme de messagerie + - Vous devez comprendre la surface d’adaptation de ChannelPlugin sidebarTitle: Channel Plugins summary: Guide étape par étape pour créer un Plugin de canal de messagerie pour OpenClaw title: Créer des Plugins de canal x-i18n: - generated_at: "2026-04-15T06:56:34Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 + source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- @@ -18,93 +18,106 @@ x-i18n: # Créer des Plugins de canal Ce guide explique comment créer un Plugin de canal qui connecte OpenClaw à une -plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec la sécurité des DM, -l’appairage, le fil des réponses et la messagerie sortante. +plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec +la sécurité des messages privés, l’appairage, le fil de réponse et la +messagerie sortante. - Si vous n’avez encore créé aucun Plugin OpenClaw, lisez d’abord - [Getting Started](/fr/plugins/building-plugins) pour la structure de package - de base et la configuration du manifeste. + Si vous n’avez encore jamais créé de Plugin OpenClaw, lisez d’abord + [Getting Started](/fr/plugins/building-plugins) pour comprendre la structure de + package de base et la configuration du manifeste. ## Fonctionnement des Plugins de canal -Les Plugins de canal n’ont pas besoin de leurs propres outils d’envoi/modification/réaction. OpenClaw conserve un -outil `message` partagé dans le cœur. Votre Plugin gère : +Les Plugins de canal n’ont pas besoin de leurs propres outils send/edit/react. +OpenClaw conserve un seul outil `message` partagé dans le cœur. Votre Plugin +gère : -- **Configuration** — résolution de compte et assistant de configuration -- **Sécurité** — politique DM et listes d’autorisation -- **Appairage** — flux d’approbation des DM -- **Grammaire de session** — comment les identifiants de conversation propres au fournisseur sont mappés vers les discussions de base, les identifiants de fil et les solutions de repli parent +- **Configuration** — résolution du compte et assistant de configuration +- **Sécurité** — politique des messages privés et listes d’autorisation +- **Appairage** — flux d’approbation des messages privés +- **Grammaire de session** — comment les identifiants de conversation spécifiques au fournisseur sont mappés vers les discussions de base, les identifiants de fil et les solutions de repli parent - **Sortant** — envoi de texte, de médias et de sondages vers la plateforme -- **Fil des réponses** — comment les réponses sont organisées en fil +- **Fil de discussion** — comment les réponses sont organisées en fil -Le cœur gère l’outil de message partagé, le câblage des prompts, la forme externe de la clé de session, -la gestion générique `:thread:` et la distribution. +Le cœur gère l’outil de message partagé, le câblage des prompts, la forme +externe de la clé de session, le suivi générique `:thread:` et la répartition. -Si votre canal ajoute des paramètres d’outil de message qui transportent des sources média, exposez ces -noms de paramètres via `describeMessageTool(...).mediaSourceParams`. Le cœur utilise -cette liste explicite pour la normalisation des chemins du sandbox et la politique -d’accès aux médias sortants, afin que les Plugins n’aient pas besoin de cas particuliers dans le cœur partagé pour des -paramètres spécifiques au fournisseur comme l’avatar, la pièce jointe ou l’image de couverture. -Préférez renvoyer une map indexée par action comme -`{ "set-profile": ["avatarUrl", "avatarPath"] }` afin que des actions sans lien n’héritent pas des arguments média d’une autre action. Un tableau plat fonctionne aussi pour des paramètres -volontairement partagés par chaque action exposée. +Si votre canal ajoute des paramètres d’outil de message qui transportent des +sources de médias, exposez ces noms de paramètres via +`describeMessageTool(...).mediaSourceParams`. Le cœur utilise +cette liste explicite pour la normalisation des chemins du bac à sable et la +politique d’accès aux médias sortants. Les Plugins n’ont donc pas besoin de cas +particuliers dans le cœur partagé pour les paramètres spécifiques au +fournisseur, comme l’avatar, les pièces jointes ou l’image de couverture. +Préférez renvoyer une map indexée par action, comme +`{ "set-profile": ["avatarUrl", "avatarPath"] }`, afin que des actions sans +rapport n’héritent pas des arguments média d’une autre action. Un tableau plat +fonctionne également pour des paramètres volontairement partagés par toutes les +actions exposées. -Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, conservez cette analyse -dans le Plugin avec `messaging.resolveSessionConversation(...)`. C’est le -hook canonique pour mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil optionnel, -`baseConversationId` explicite, et tout `parentConversationCandidates`. -Lorsque vous renvoyez `parentConversationCandidates`, conservez leur ordre du -parent le plus spécifique vers la conversation parente la plus large/de base. +Si votre plateforme stocke une portée supplémentaire dans les identifiants de +conversation, conservez cette logique d’analyse dans le Plugin avec +`messaging.resolveSessionConversation(...)`. Il s’agit du hook canonique pour +mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil +facultatif, l’éventuel `baseConversationId` et tous les +`parentConversationCandidates`. +Lorsque vous renvoyez `parentConversationCandidates`, gardez-les ordonnés du +parent le plus spécifique au parent le plus large ou à la conversation de base. -Les Plugins groupés qui ont besoin de la même analyse avant le démarrage du registre des canaux -peuvent aussi exposer un fichier de premier niveau `session-key-api.ts` avec un -export `resolveSessionConversation(...)` correspondant. Le cœur utilise cette surface sûre au démarrage -uniquement lorsque le registre de Plugin d’exécution n’est pas encore disponible. +Les Plugins intégrés qui ont besoin de la même analyse avant le démarrage du +registre de canaux peuvent aussi exposer un fichier `session-key-api.ts` de +niveau supérieur avec un export `resolveSessionConversation(...)` +correspondant. Le cœur utilise cette surface sûre pour l’amorçage uniquement +lorsque le registre de Plugin d’exécution n’est pas encore disponible. -`messaging.resolveParentConversationCandidates(...)` reste disponible comme solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin de solutions de repli parent qu’au-dessus de l’identifiant générique/brut. Si les deux hooks existent, le cœur utilise -d’abord `resolveSessionConversation(...).parentConversationCandidates` et ne -revient à `resolveParentConversationCandidates(...)` que lorsque le hook canonique -les omet. +`messaging.resolveParentConversationCandidates(...)` reste disponible comme +solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin que de +solutions de repli parent au-dessus de l’identifiant générique ou brut. Si les +deux hooks existent, le cœur utilise d’abord +`resolveSessionConversation(...).parentConversationCandidates` et ne se rabat +sur `resolveParentConversationCandidates(...)` que lorsque le hook canonique ne +les fournit pas. -## Approbations et capacités de canal +## Approbations et capacités des canaux -La plupart des Plugins de canal n’ont pas besoin de code spécifique aux approbations. +La plupart des Plugins de canal n’ont pas besoin de code spécifique aux +approbations. - Le cœur gère `/approve` dans la même discussion, les charges utiles de bouton d’approbation partagées et la livraison de repli générique. -- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal a besoin d’un comportement spécifique aux approbations. -- `ChannelPlugin.approvals` est supprimé. Placez les informations de livraison/rendu/authentification natives de l’approbation dans `approvalCapability`. -- `plugin.auth` concerne uniquement login/logout ; le cœur ne lit plus les hooks d’authentification des approbations depuis cet objet. +- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal nécessite un comportement spécifique aux approbations. +- `ChannelPlugin.approvals` a été supprimé. Placez les informations de livraison, native, rendu et authentification des approbations dans `approvalCapability`. +- `plugin.auth` est réservé à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation depuis cet objet. - `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la jonction canonique pour l’authentification des approbations. -- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification des approbations dans la même discussion. -- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface initiatrice/du client natif lorsqu’il diffère de l’authentification des approbations dans la même discussion. Le cœur utilise ce hook spécifique à exec pour distinguer `enabled` de `disabled`, déterminer si le canal initiateur prend en charge les approbations d’exécution natives, et inclure le canal dans les indications de repli du client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit ce rôle pour le cas courant. -- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, par exemple masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison. -- Utilisez `approvalCapability.delivery` uniquement pour le routage des approbations natives ou la suppression du repli. -- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation native gérées par le canal. Gardez-le paresseux sur les points d’entrée chauds du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module d’exécution à la demande tout en permettant au cœur d’assembler le cycle de vie de l’approbation. +- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans la même discussion. +- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface initiatrice ou du client natif lorsqu’il diffère de l’authentification d’approbation dans la même discussion. Le cœur utilise ce hook spécifique à l’exécution pour distinguer `enabled` et `disabled`, décider si le canal initiateur prend en charge les approbations d’exécution natives et inclure le canal dans les indications de repli du client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit ce rôle pour le cas courant. +- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, comme masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison. +- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression du repli. +- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation native gérées par le canal. Gardez-le paresseux sur les points d’entrée critiques du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module d’exécution à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations. - Utilisez `approvalCapability.render` uniquement lorsqu’un canal a réellement besoin de charges utiles d’approbation personnalisées au lieu du moteur de rendu partagé. -- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal souhaite que la réponse du chemin désactivé explique les paramètres de configuration exacts nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent afficher des chemins à portée de compte tels que `channels..accounts..execApprovals.*` au lieu de valeurs par défaut de premier niveau. -- Si un canal peut déduire des identités DM stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans la même discussion sans ajouter de logique du cœur spécifique aux approbations. -- Si un canal a besoin d’une livraison d’approbation native, faites en sorte que le code du canal reste centré sur la normalisation de la cible ainsi que sur les informations de transport/de présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et gérer lui-même le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage externe. `nativeRuntime` est divisé en quelques jonctions plus petites : -- `availability` — si le compte est configuré et si une requête doit être traitée -- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente/résolues/expirées ou des actions finales -- `transport` — préparer les cibles puis envoyer/mettre à jour/supprimer des messages d’approbation natifs -- `interactions` — hooks facultatifs bind/unbind/clear-action pour les boutons ou réactions natifs +- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse du chemin désactivé explique exactement quels paramètres de configuration sont nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent afficher des chemins à portée de compte comme `channels..accounts..execApprovals.*` au lieu de valeurs par défaut de niveau supérieur. +- Si un canal peut déduire des identités de messages privés stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans la même discussion sans ajouter de logique spécifique aux approbations dans le cœur. +- Si un canal a besoin de la livraison d’approbations natives, gardez le code du canal centré sur la normalisation de la cible ainsi que sur les informations de transport et de présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les notifications de routage ailleurs. `nativeRuntime` est divisé en quelques jonctions plus petites : +- `availability` — si le compte est configuré et si une requête doit être prise en charge +- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente, résolues, expirées ou vers des actions finales +- `transport` — préparer les cibles puis envoyer, mettre à jour ou supprimer les messages d’approbation natifs +- `interactions` — hooks facultatifs pour lier, délier ou effacer des actions pour les boutons ou réactions natifs - `observe` — hooks facultatifs de diagnostic de livraison -- Si le canal a besoin d’objets gérés par l’exécution comme un client, un jeton, une app Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte d’exécution permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de colle d’encapsulation spécifique aux approbations. -- Utilisez les niveaux inférieurs `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` uniquement lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive. -- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` par ces helpers. `accountId` permet de garder la politique d’approbation multi-compte limitée au bon compte de bot, et `approvalKind` rend disponible au canal le comportement d’approbation exec vs Plugin sans branches codées en dur dans le cœur. -- Le cœur gère désormais aussi les avis de reroutage d’approbation. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation a été envoyée vers les DM / un autre canal » depuis `createChannelNativeApprovalRuntime` ; exposez plutôt un routage précis de l’origine + des DM de l’approbateur via les helpers de capacité d’approbation partagés et laissez le cœur agréger les livraisons réelles avant de publier un éventuel avis dans la discussion initiatrice. -- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas - deviner ou réécrire le routage des approbations exec vs Plugin à partir d’un état local au canal. -- Différents types d’approbation peuvent intentionnellement exposer différentes surfaces natives. - Exemples groupés actuels : - - Slack maintient le routage d’approbation native disponible à la fois pour les identifiants exec et Plugin. - - Matrix conserve le même routage natif DM/canal et la même UX par réaction pour les approbations exec - et Plugin, tout en permettant à l’authentification de différer selon le type d’approbation. -- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme encapsulation de compatibilité, mais le nouveau code doit préférer le constructeur de capacité et exposer `approvalCapability` sur le Plugin. +- Si le canal a besoin d’objets gérés par l’exécution, comme un client, un jeton, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte d’exécution permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de colle d’enveloppe spécifique aux approbations. +- N’utilisez le niveau plus bas `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` que lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive. +- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` via ces helpers. `accountId` conserve la portée de la politique d’approbation multi-compte sur le bon compte de bot, et `approvalKind` conserve le comportement d’approbation d’exécution par rapport au Plugin disponible pour le canal sans branches codées en dur dans le cœur. +- Le cœur gère désormais aussi les notifications de reroutage des approbations. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi du type « l’approbation est allée dans les messages privés / un autre canal » depuis `createChannelNativeApprovalRuntime` ; à la place, exposez un routage précis de l’origine et des messages privés de l’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier toute notification dans la discussion initiatrice. +- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas deviner ni réécrire le routage des approbations d’exécution par rapport aux approbations de Plugin à partir d’un état local au canal. +- Différents types d’approbation peuvent volontairement exposer différentes surfaces natives. + Exemples intégrés actuels : + - Slack conserve le routage d’approbation native disponible à la fois pour les identifiants d’exécution et de Plugin. + - Matrix conserve le même routage natif en messages privés ou canal et la même UX basée sur les réactions pour les approbations d’exécution et de Plugin, tout en permettant à l’authentification de différer selon le type d’approbation. +- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme enveloppe de compatibilité, mais le nouveau code doit préférer le constructeur de capacités et exposer `approvalCapability` sur le Plugin. -Pour les points d’entrée chauds du canal, préférez les sous-chemins d’exécution plus étroits lorsque vous n’avez besoin que d’une seule partie de cette famille : +Pour les points d’entrée critiques du canal, préférez les sous-chemins +d’exécution plus étroits lorsque vous n’avez besoin que d’une seule partie de +cette famille : - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -120,91 +133,91 @@ De même, préférez `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, -`openclaw/plugin-sdk/reply-reference`, et -`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la surface -parapluie plus large. +`openclaw/plugin-sdk/reply-reference` et +`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la +surface englobante plus large. Pour la configuration en particulier : -- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution : - adaptateurs de patch de configuration sûrs à l’import (`createPatchedAccountSetupAdapter`, - `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), sortie de note de recherche, - `promptResolvedAllowFrom`, `splitSetupEntries`, et les constructeurs - de proxy de configuration déléguée -- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite sensible à l’environnement - pour `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration avec installation facultative - ainsi que quelques primitives sûres pour la configuration : +- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution : adaptateurs de patch de configuration sûrs à l’importation (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), sortie des notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries` et les constructeurs de proxy de configuration déléguée +- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite, consciente de l’environnement, pour `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration d’installation facultative ainsi que quelques primitives sûres pour la configuration : `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Si votre canal prend en charge une configuration ou une authentification pilotée par l’environnement et que les flux génériques de démarrage/configuration doivent connaître ces noms de variables d’environnement avant le chargement de l’exécution, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`. Conservez les `envVars` d’exécution du canal ou les constantes locales uniquement pour le texte destiné aux opérateurs. +Si votre canal prend en charge une configuration ou une authentification pilotée +par des variables d’environnement et que les flux génériques de démarrage ou de +configuration doivent connaître ces noms de variables avant le chargement de +l’exécution, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`. +Conservez `envVars` de l’exécution du canal ou des constantes locales +uniquement pour le texte destiné aux opérateurs. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, -`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, et +`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` et `splitSetupEntries` -- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez également besoin des - helpers partagés plus lourds de configuration/config tels que - `moveSingleAccountChannelSectionToDefaultAccount(...)` +- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez aussi besoin des helpers partagés de configuration plus lourds, comme `moveSingleAccountChannelSectionToDefaultAccount(...)` Si votre canal veut seulement annoncer « installez d’abord ce Plugin » dans les -surfaces de configuration, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur/assistant généré échoue de manière fermée sur les écritures de configuration et la finalisation, et il réutilise -le même message « installation requise » pour la validation, la finalisation et le texte -du lien vers la documentation. +surfaces de configuration, préférez +`createOptionalChannelSetupSurface(...)`. L’adaptateur et l’assistant générés +échouent en mode fermé sur les écritures de configuration et la finalisation, et +ils réutilisent le même message « installation requise » dans la validation, la +finalisation et le texte du lien vers la documentation. -Pour les autres chemins chauds du canal, préférez les helpers étroits aux surfaces héritées plus larges : +Pour les autres chemins critiques du canal, préférez les helpers étroits aux +surfaces héritées plus larges : - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, - `openclaw/plugin-sdk/account-resolution`, et + `openclaw/plugin-sdk/account-resolution` et `openclaw/plugin-sdk/account-helpers` pour la configuration multi-compte et - le repli vers le compte par défaut + la solution de repli du compte par défaut - `openclaw/plugin-sdk/inbound-envelope` et - `openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de route/enveloppe entrante et - d’enregistrement-et-distribution -- `openclaw/plugin-sdk/messaging-targets` pour l’analyse/la correspondance des cibles + `openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de la route ou + de l’enveloppe entrante ainsi que de l’enregistrement et de la répartition +- `openclaw/plugin-sdk/messaging-targets` pour l’analyse et la correspondance + des cibles - `openclaw/plugin-sdk/outbound-media` et - `openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que les - délégations d’identité/d’envoi sortants -- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des liaisons de fil - et l’enregistrement des adaptateurs -- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champ de charge utile agent/média héritée - est encore requise -- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des commandes personnalisées Telegram, - la validation des doublons/conflits et un contrat de configuration de commandes - stable en repli + `openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que + les délégués d’identité et d’envoi sortants +- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des + liaisons de fil et l’enregistrement des adaptateurs +- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition + héritée des champs de charge utile agent/média est encore nécessaire +- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des + commandes personnalisées Telegram, la validation des doublons ou conflits, et + un contrat de configuration de commande stable en solution de repli -Les canaux uniquement basés sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes/d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de chat personnalisés doivent utiliser les helpers natifs partagés au lieu d’implémenter leur propre cycle de vie d’approbation. +Les canaux basés uniquement sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes et d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de discussion personnalisés doivent utiliser les helpers natifs partagés au lieu de créer leur propre cycle de vie d’approbation. ## Politique des mentions entrantes -Conservez la gestion des mentions entrantes séparée en deux couches : +Conservez la gestion des mentions entrantes répartie en deux couches : -- collecte d’éléments de preuve gérée par le Plugin +- collecte de preuves gérée par le Plugin - évaluation de politique partagée Utilisez `openclaw/plugin-sdk/channel-inbound` pour la couche partagée. -Convient bien à la logique locale au Plugin : +Bon cas d’usage pour la logique locale au Plugin : -- détection des réponses au bot -- détection des citations du bot +- détection de réponse au bot +- détection de citation du bot - vérifications de participation au fil -- exclusions des messages de service/système +- exclusions de messages de service ou système - caches natifs à la plateforme nécessaires pour prouver la participation du bot -Convient bien au helper partagé : +Bon cas d’usage pour le helper partagé : - `requireMention` - résultat de mention explicite - liste d’autorisation de mention implicite - contournement de commande -- décision finale d’ignorance +- décision finale d’ignorer Flux recommandé : -1. Calculez les éléments factuels locaux sur les mentions. -2. Passez ces éléments à `resolveInboundMentionDecision({ facts, policy })`. +1. Calculez les faits de mention locaux. +2. Transmettez ces faits à `resolveInboundMentionDecision({ facts, policy })`. 3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde d’entrée. ```typescript @@ -245,7 +258,7 @@ if (decision.shouldSkip) return; ``` `api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour -les Plugins de canal groupés qui dépendent déjà de l’injection d’exécution : +les Plugins de canal intégrés qui dépendent déjà de l’injection d’exécution : - `buildMentionRegexes` - `matchesMentionPatterns` @@ -253,18 +266,20 @@ les Plugins de canal groupés qui dépendent déjà de l’injection d’exécut - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Les anciens helpers `resolveMentionGating*` restent présents dans -`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité. Le nouveau code -doit utiliser `resolveInboundMentionDecision({ facts, policy })`. +Les anciens helpers `resolveMentionGating*` restent dans +`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité. +Le nouveau code doit utiliser +`resolveInboundMentionDecision({ facts, policy })`. -## Guide pas à pas +## Procédure pas à pas - Créez les fichiers standards du Plugin. Le champ `channel` dans `package.json` - est ce qui en fait un Plugin de canal. Pour la surface complète des métadonnées du package, - voir [Plugin Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) : + Créez les fichiers de Plugin standard. Le champ `channel` dans `package.json` + est ce qui en fait un Plugin de canal. Pour la surface complète des + métadonnées de package, consultez + [Plugin Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) : ```json package.json @@ -290,7 +305,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Plugin de canal Acme Chat", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -314,8 +329,9 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. - L’interface `ChannelPlugin` comporte de nombreuses surfaces d’adaptateur optionnelles. Commencez par - le minimum — `id` et `setup` — puis ajoutez des adaptateurs selon vos besoins. + L’interface `ChannelPlugin` possède de nombreuses surfaces d’adaptation + facultatives. Commencez par le minimum — `id` et `setup` — puis ajoutez des + adaptateurs selon vos besoins. Créez `src/channel.ts` : @@ -325,7 +341,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // votre client API de plateforme + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -366,7 +382,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. }, }), - // Sécurité DM : qui peut envoyer des messages au bot + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -376,21 +392,21 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. }, }, - // Appairage : flux d’approbation pour les nouveaux contacts DM + // Pairing: approval flow for new DM contacts pairing: { text: { - idLabel: "nom d’utilisateur Acme Chat", - message: "Envoyez ce code pour vérifier votre identité :", + idLabel: "Acme Chat username", + message: "Send this code to verify your identity:", notify: async ({ target, code }) => { await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // Fil des réponses : comment les réponses sont livrées + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // Sortant : envoyer des messages vers la plateforme + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -411,23 +427,24 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. ``` - Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas niveau, vous passez - des options déclaratives et le constructeur les compose : + Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas + niveau, vous fournissez des options déclaratives et le constructeur les + compose : - | Option | Ce qu’elle câble | + | Option | Ce qu’elle connecte | | --- | --- | - | `security.dm` | Résolveur de sécurité DM à portée limitée depuis les champs de configuration | - | `pairing.text` | Flux d’appairage DM basé sur du texte avec échange de code | + | `security.dm` | Résolveur de sécurité des messages privés à portée limitée depuis les champs de configuration | + | `pairing.text` | Flux d’appairage de messages privés basé sur du texte avec échange de code | | `threading` | Résolveur de mode de réponse (fixe, à portée de compte ou personnalisé) | | `outbound.attachedResults` | Fonctions d’envoi qui renvoient des métadonnées de résultat (identifiants de message) | - Vous pouvez aussi passer des objets d’adaptateur bruts au lieu des options déclaratives - si vous avez besoin d’un contrôle total. + Vous pouvez aussi transmettre des objets d’adaptateur bruts au lieu des + options déclaratives si vous avez besoin d’un contrôle total. - + Créez `index.ts` : ```typescript index.ts @@ -437,20 +454,20 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. export default defineChannelPluginEntry({ id: "acme-chat", name: "Acme Chat", - description: "Plugin de canal Acme Chat", + description: "Acme Chat channel plugin", plugin: acmeChatPlugin, registerCliMetadata(api) { api.registerCli( ({ program }) => { program .command("acme-chat") - .description("Gestion Acme Chat"); + .description("Acme Chat management"); }, { descriptors: [ { name: "acme-chat", - description: "Gestion Acme Chat", + description: "Acme Chat management", hasSubcommands: false, }, ], @@ -463,17 +480,20 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Placez les descripteurs CLI propres au canal dans `registerCliMetadata(...)` afin qu’OpenClaw - puisse les afficher dans l’aide racine sans activer l’exécution complète du canal, - tandis que les chargements complets normaux récupèrent toujours les mêmes descripteurs pour le véritable enregistrement - des commandes. Réservez `registerFull(...)` au travail réservé à l’exécution. + Placez les descripteurs CLI gérés par le canal dans + `registerCliMetadata(...)` afin qu’OpenClaw puisse les afficher dans l’aide + racine sans activer l’exécution complète du canal, tandis que les + chargements complets normaux récupèrent toujours les mêmes descripteurs pour + l’enregistrement réel des commandes. Conservez `registerFull(...)` pour le + travail réservé à l’exécution. Si `registerFull(...)` enregistre des méthodes RPC Gateway, utilisez un - préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et se - résolvent toujours vers `operator.admin`. - `defineChannelPluginEntry` gère automatiquement la séparation des modes d’enregistrement. Voir - [Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour toutes les - options. + préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur + (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés + et se résolvent toujours vers `operator.admin`. + `defineChannelPluginEntry` gère automatiquement cette séparation des modes + d’enregistrement. Consultez + [Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour + toutes les options. @@ -487,28 +507,36 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw charge ceci au lieu de l’entrée complète lorsque le canal est désactivé - ou non configuré. Cela évite de charger du code d’exécution lourd pendant les flux de configuration. - Voir [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de détails. + OpenClaw charge ceci à la place du point d’entrée complet lorsque le canal + est désactivé ou non configuré. Cela évite de charger du code d’exécution + lourd pendant les flux de configuration. + Consultez [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de + détails. + + Les canaux d’espace de travail intégrés qui répartissent les exports sûrs + pour la configuration dans des modules annexes peuvent utiliser + `defineBundledChannelSetupEntry(...)` depuis + `openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont aussi besoin + d’un setter d’exécution explicite au moment de la configuration. - Votre Plugin doit recevoir les messages depuis la plateforme et les transmettre à - OpenClaw. Le modèle habituel est un Webhook qui vérifie la requête et - la distribue via le gestionnaire entrant de votre canal : + Votre Plugin doit recevoir les messages depuis la plateforme et les + transférer vers OpenClaw. Le modèle habituel est un Webhook qui vérifie la + requête et la distribue via le gestionnaire entrant de votre canal : ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // authentification gérée par le Plugin (vérifiez vous-même les signatures) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Votre gestionnaire entrant distribue le message à OpenClaw. - // Le câblage exact dépend de votre SDK de plateforme — - // voir un exemple réel dans le package Plugin groupé Microsoft Teams ou Google Chat. + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -520,9 +548,10 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. ``` - La gestion des messages entrants est spécifique au canal. Chaque Plugin de canal gère - son propre pipeline entrant. Consultez les Plugins de canal groupés - (par exemple le package Plugin Microsoft Teams ou Google Chat) pour voir des modèles réels. + La gestion des messages entrants est spécifique au canal. Chaque Plugin de + canal gère son propre pipeline entrant. Examinez les Plugins de canal + intégrés (par exemple le package Plugin Microsoft Teams ou Google Chat) + pour voir des modèles réels. @@ -567,7 +596,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. pnpm test -- /acme-chat/ ``` - Pour les helpers de test partagés, voir [Testing](/fr/plugins/sdk-testing). + Pour les helpers de test partagés, consultez [Testing](/fr/plugins/sdk-testing). @@ -592,30 +621,31 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`. ## Sujets avancés - + Modes de réponse fixes, à portée de compte ou personnalisés - describeMessageTool et découverte des actions + describeMessageTool et découverte d’action inferTargetChatType, looksLikeId, resolveTarget - TTS, STT, média, sous-agent via api.runtime + TTS, STT, médias, sous-agent via api.runtime -Certaines jonctions de helpers groupés existent encore pour la maintenance et la -compatibilité des Plugins groupés. Elles ne constituent pas le modèle recommandé pour les nouveaux Plugins de canal ; -préférez les sous-chemins génériques channel/setup/reply/runtime de la surface SDK -commune, sauf si vous maintenez directement cette famille de Plugins groupés. +Certaines jonctions de helpers intégrés existent encore pour la maintenance et +la compatibilité des Plugins intégrés. Ce n’est pas le modèle recommandé pour +les nouveaux Plugins de canal ; préférez les sous-chemins génériques +channel/setup/reply/runtime de la surface SDK commune, sauf si vous maintenez +directement cette famille de Plugins intégrés. ## Étapes suivantes -- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles -- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin -- [Tests du SDK](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat -- [Manifeste de Plugin](/fr/plugins/manifest) — schéma complet du manifeste +- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles +- [SDK Overview](/fr/plugins/sdk-overview) — référence complète des imports de sous-chemins +- [SDK Testing](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat +- [Plugin Manifest](/fr/plugins/manifest) — schéma complet du manifeste diff --git a/docs/fr/plugins/sdk-entrypoints.md b/docs/fr/plugins/sdk-entrypoints.md index 5ac161b76..838e916dd 100644 --- a/docs/fr/plugins/sdk-entrypoints.md +++ b/docs/fr/plugins/sdk-entrypoints.md @@ -1,33 +1,33 @@ --- read_when: - - Vous avez besoin de la signature de type exacte de `definePluginEntry` ou `defineChannelPluginEntry` - - Vous voulez comprendre le mode d’enregistrement (full vs setup vs métadonnées CLI) - - Vous recherchez les options des points d’entrée + - Vous avez besoin de la signature de type exacte de definePluginEntry ou de defineChannelPluginEntry + - Vous souhaitez comprendre le mode d’enregistrement (complet vs configuration vs métadonnées CLI) + - Vous recherchez les options de point d’entrée sidebarTitle: Entry Points -summary: Référence pour `definePluginEntry`, `defineChannelPluginEntry` et `defineSetupPluginEntry` -title: Points d’entrée de plugin +summary: Référence pour definePluginEntry, defineChannelPluginEntry et defineSetupPluginEntry +title: Points d’entrée du Plugin x-i18n: - generated_at: "2026-04-05T12:49:58Z" + generated_at: "2026-04-15T19:41:43Z" model: gpt-5.4 provider: openai - source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f + source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4 source_path: plugins/sdk-entrypoints.md workflow: 15 --- -# Points d’entrée de plugin +# Points d’entrée du Plugin Chaque plugin exporte un objet d’entrée par défaut. Le SDK fournit trois helpers pour les créer. - **Vous cherchez un guide pas à pas ?** Voir [Plugins de canal](/plugins/sdk-channel-plugins) - ou [Plugins de fournisseur](/plugins/sdk-provider-plugins) pour des guides étape par étape. + **Vous cherchez un guide pas à pas ?** Consultez [Channel Plugins](/fr/plugins/sdk-channel-plugins) + ou [Provider Plugins](/fr/plugins/sdk-provider-plugins) pour des guides étape par étape. ## `definePluginEntry` -**Import :** `openclaw/plugin-sdk/plugin-entry` +**Importation :** `openclaw/plugin-sdk/plugin-entry` Pour les plugins de fournisseur, les plugins d’outils, les plugins de hooks, et tout ce qui **n’est pas** un canal de messagerie. @@ -60,17 +60,18 @@ export default definePluginEntry({ | `register` | `(api: OpenClawPluginApi) => void` | Oui | — | - `id` doit correspondre à votre manifeste `openclaw.plugin.json`. -- `kind` sert pour les emplacements exclusifs : `"memory"` ou `"context-engine"`. +- `kind` est utilisé pour les emplacements exclusifs : `"memory"` ou `"context-engine"`. - `configSchema` peut être une fonction pour une évaluation paresseuse. -- OpenClaw résout et met ce schéma en cache lors du premier accès, de sorte que les constructeurs de schéma coûteux +- OpenClaw résout et mémorise ce schéma lors du premier accès, donc les générateurs de schéma coûteux ne s’exécutent qu’une seule fois. ## `defineChannelPluginEntry` -**Import :** `openclaw/plugin-sdk/channel-core` +**Importation :** `openclaw/plugin-sdk/channel-core` -Encapsule `definePluginEntry` avec le câblage spécifique aux canaux. Appelle automatiquement -`api.registerChannel({ plugin })`, expose une couture facultative de métadonnées CLI d’aide racine, et conditionne `registerFull` au mode d’enregistrement. +Encapsule `definePluginEntry` avec un câblage spécifique aux canaux. Appelle automatiquement +`api.registerChannel({ plugin })`, expose une jonction facultative de métadonnées CLI +pour l’aide racine, et conditionne `registerFull` selon le mode d’enregistrement. ```typescript import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -101,33 +102,33 @@ export default defineChannelPluginEntry({ | `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Non | — | | `registerFull` | `(api: OpenClawPluginApi) => void` | Non | — | -- `setRuntime` est appelé pendant l’enregistrement afin que vous puissiez stocker la référence de runtime +- `setRuntime` est appelé pendant l’enregistrement afin que vous puissiez stocker la référence d’exécution (généralement via `createPluginRuntimeStore`). Il est ignoré pendant la capture - de métadonnées CLI. + des métadonnées CLI. - `registerCliMetadata` s’exécute à la fois lorsque `api.registrationMode === "cli-metadata"` et lorsque `api.registrationMode === "full"`. - Utilisez-le comme emplacement canonique pour les descripteurs CLI détenus par le canal afin que l’aide racine - reste non activante tout en gardant l’enregistrement normal des commandes CLI compatible + Utilisez-le comme emplacement canonique pour les descripteurs CLI possédés par le canal afin que l’aide racine + reste non activante tout en conservant la compatibilité de l’enregistrement normal des commandes CLI avec les chargements complets de plugins. - `registerFull` ne s’exécute que lorsque `api.registrationMode === "full"`. Il est ignoré - lors du chargement setup-only. + lors du chargement pour la configuration uniquement. - Comme pour `definePluginEntry`, `configSchema` peut être une fabrique paresseuse et OpenClaw - met en cache le schéma résolu lors du premier accès. -- Pour les commandes CLI racine détenues par le plugin, préférez `api.registerCli(..., { descriptors: [...] })` - lorsque vous voulez que la commande reste chargée paresseusement sans disparaître de - l’arbre d’analyse de la CLI racine. Pour les plugins de canal, préférez enregistrer ces descripteurs - depuis `registerCliMetadata(...)` et gardez `registerFull(...)` concentré sur le travail réservé au runtime. -- Si `registerFull(...)` enregistre aussi des méthodes Gateway RPC, gardez-les sur un - préfixe spécifique au plugin. Les espaces de noms d’administration réservés au cœur (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) sont toujours forcés à + mémorise le schéma résolu lors du premier accès. +- Pour les commandes CLI racine appartenant au plugin, préférez `api.registerCli(..., { descriptors: [...] })` + lorsque vous voulez que la commande reste chargée paresseusement sans disparaître de l’arbre + d’analyse de la CLI racine. Pour les plugins de canal, préférez enregistrer ces descripteurs + depuis `registerCliMetadata(...)` et gardez `registerFull(...)` centré sur le travail réservé à l’exécution. +- Si `registerFull(...)` enregistre aussi des méthodes RPC Gateway, conservez-les avec un + préfixe spécifique au plugin. Les espaces de noms d’administration du cœur réservés (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) sont toujours forcés en `operator.admin`. ## `defineSetupPluginEntry` -**Import :** `openclaw/plugin-sdk/channel-core` +**Importation :** `openclaw/plugin-sdk/channel-core` -Pour le fichier léger `setup-entry.ts`. Renvoie simplement `{ plugin }` sans -câblage runtime ni CLI. +Pour le fichier léger `setup-entry.ts`. Retourne simplement `{ plugin }` sans +câblage d’exécution ni de CLI. ```typescript import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -135,33 +136,59 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; export default defineSetupPluginEntry(myChannelPlugin); ``` -OpenClaw charge ceci à la place de l’entrée complète lorsqu’un canal est désactivé, -non configuré, ou lorsque le chargement différé est activé. Voir -[Setup et configuration](/plugins/sdk-setup#setup-entry) pour savoir quand cela compte. +OpenClaw charge ceci au lieu du point d’entrée complet lorsqu’un canal est désactivé, +non configuré, ou lorsque le chargement différé est activé. Consultez +[Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour savoir quand cela a de l’importance. -En pratique, associez `defineSetupPluginEntry(...)` aux familles étroites de helpers setup : +En pratique, associez `defineSetupPluginEntry(...)` aux familles étroites de helpers de configuration : -- `openclaw/plugin-sdk/setup-runtime` pour des helpers setup sûrs côté runtime tels que - les adaptateurs de patch setup import-safe, la sortie lookup-note, - `promptResolvedAllowFrom`, `splitSetupEntries`, et les proxys setup délégués -- `openclaw/plugin-sdk/channel-setup` pour les surfaces setup à installation facultative -- `openclaw/plugin-sdk/setup-tools` pour les helpers setup/install CLI/archive/docs +- `openclaw/plugin-sdk/setup-runtime` pour les helpers de configuration sûrs à l’exécution, tels que + les adaptateurs de patch de configuration sûrs à l’importation, la sortie de notes de recherche, + `promptResolvedAllowFrom`, `splitSetupEntries`, et les proxys de configuration délégués +- `openclaw/plugin-sdk/channel-setup` pour les surfaces de configuration d’installation facultative +- `openclaw/plugin-sdk/setup-tools` pour les helpers de CLI/archive/documentation de configuration et d’installation -Gardez les SDK lourds, l’enregistrement CLI et les services runtime longue durée dans l’entrée complète. +Conservez les SDK lourds, l’enregistrement CLI et les services d’exécution de longue durée dans le point +d’entrée complet. + +Les canaux de l’espace de travail groupé qui séparent les surfaces de configuration et d’exécution peuvent utiliser +`defineBundledChannelSetupEntry(...)` depuis +`openclaw/plugin-sdk/channel-entry-contract` à la place. Ce contrat permet au point d’entrée +de configuration de conserver des exportations de plugin/secrets sûres pour la configuration tout en exposant +un setter d’exécution : + +```typescript +import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract"; + +export default defineBundledChannelSetupEntry({ + importMetaUrl: import.meta.url, + plugin: { + specifier: "./channel-plugin-api.js", + exportName: "myChannelPlugin", + }, + runtime: { + specifier: "./runtime-api.js", + exportName: "setMyChannelRuntime", + }, +}); +``` + +Utilisez ce contrat groupé uniquement lorsque les flux de configuration ont réellement besoin d’un setter +d’exécution léger avant le chargement du point d’entrée complet du canal. ## Mode d’enregistrement `api.registrationMode` indique à votre plugin comment il a été chargé : -| Mode | Quand | Ce qu’il faut enregistrer | -| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------- | -| `"full"` | Démarrage normal de Gateway | Tout | -| `"setup-only"` | Canal désactivé/non configuré | Enregistrement du canal uniquement | -| `"setup-runtime"` | Flux setup avec runtime disponible | Enregistrement du canal plus uniquement le runtime léger nécessaire avant le chargement de l’entrée complète | -| `"cli-metadata"` | Aide racine / capture de métadonnées CLI | Descripteurs CLI uniquement | +| Mode | Quand | Ce qu’il faut enregistrer | +| ----------------- | --------------------------------- | --------------------------------------------------------------------------------------- | +| `"full"` | Démarrage normal de Gateway | Tout | +| `"setup-only"` | Canal désactivé/non configuré | Enregistrement du canal uniquement | +| `"setup-runtime"` | Flux de configuration avec exécution disponible | Enregistrement du canal plus uniquement l’exécution légère nécessaire avant le chargement du point d’entrée complet | +| `"cli-metadata"` | Capture de l’aide racine / des métadonnées CLI | Descripteurs CLI uniquement | `defineChannelPluginEntry` gère automatiquement cette séparation. Si vous utilisez -`definePluginEntry` directement pour un canal, vérifiez vous-même le mode : +`definePluginEntry` directement pour un canal, vérifiez le mode vous-même : ```typescript register(api) { @@ -173,23 +200,23 @@ register(api) { api.registerChannel({ plugin: myPlugin }); if (api.registrationMode !== "full") return; - // Enregistrements lourds réservés au runtime + // Heavy runtime-only registrations api.registerService(/* ... */); } ``` -Traitez `"setup-runtime"` comme la fenêtre où les surfaces de démarrage setup-only doivent -exister sans réentrer dans le runtime complet du canal intégré. Les bonnes utilisations sont -l’enregistrement du canal, les routes HTTP setup-safe, les méthodes gateway setup-safe, et -les helpers setup délégués. Les services d’arrière-plan lourds, les enregistreurs CLI et -les bootstrap SDK fournisseur/client appartiennent toujours à `"full"`. +Traitez `"setup-runtime"` comme la fenêtre dans laquelle les surfaces de démarrage réservées à la configuration doivent +exister sans réintégrer l’exécution complète du canal groupé. Les bons cas d’usage sont +l’enregistrement du canal, les routes HTTP sûres pour la configuration, les méthodes Gateway sûres pour la configuration, et +les helpers de configuration délégués. Les services d’arrière-plan lourds, les enregistreurs CLI, et +les initialisations de SDK fournisseur/client appartiennent toujours à `"full"`. Pour les enregistreurs CLI en particulier : - utilisez `descriptors` lorsque l’enregistreur possède une ou plusieurs commandes racine et que vous - voulez qu’OpenClaw charge paresseusement le vrai module CLI à la première invocation + voulez qu’OpenClaw charge paresseusement le vrai module CLI lors de la première invocation - assurez-vous que ces descripteurs couvrent chaque racine de commande de premier niveau exposée par l’enregistreur -- utilisez `commands` seul uniquement pour des chemins de compatibilité eager +- utilisez `commands` seul uniquement pour les chemins de compatibilité eager ## Formes de plugin @@ -197,17 +224,17 @@ OpenClaw classe les plugins chargés selon leur comportement d’enregistrement | Forme | Description | | --------------------- | -------------------------------------------------- | -| **plain-capability** | Un seul type de capacité (par ex. fournisseur seul) | -| **hybrid-capability** | Plusieurs types de capacité (par ex. fournisseur + speech) | +| **plain-capability** | Un seul type de capacité (par ex. fournisseur uniquement) | +| **hybrid-capability** | Plusieurs types de capacité (par ex. fournisseur + parole) | | **hook-only** | Seulement des hooks, aucune capacité | | **non-capability** | Outils/commandes/services mais aucune capacité | Utilisez `openclaw plugins inspect ` pour voir la forme d’un plugin. -## Liens associés +## Voir aussi -- [Vue d’ensemble du SDK](/plugins/sdk-overview) — API d’enregistrement et référence des sous-chemins -- [Helpers runtime](/plugins/sdk-runtime) — `api.runtime` et `createPluginRuntimeStore` -- [Setup et configuration](/plugins/sdk-setup) — manifeste, entrée setup, chargement différé -- [Plugins de canal](/plugins/sdk-channel-plugins) — construction de l’objet `ChannelPlugin` -- [Plugins de fournisseur](/plugins/sdk-provider-plugins) — enregistrement du fournisseur et hooks +- [SDK Overview](/fr/plugins/sdk-overview) — API d’enregistrement et référence des sous-chemins +- [Runtime Helpers](/fr/plugins/sdk-runtime) — `api.runtime` et `createPluginRuntimeStore` +- [Setup and Config](/fr/plugins/sdk-setup) — manifeste, point d’entrée de configuration, chargement différé +- [Channel Plugins](/fr/plugins/sdk-channel-plugins) — construction de l’objet `ChannelPlugin` +- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — enregistrement des fournisseurs et hooks diff --git a/docs/fr/plugins/sdk-runtime.md b/docs/fr/plugins/sdk-runtime.md index 9fad8203b..5c8fae5c6 100644 --- a/docs/fr/plugins/sdk-runtime.md +++ b/docs/fr/plugins/sdk-runtime.md @@ -1,29 +1,29 @@ --- read_when: - - Vous devez appeler des assistants core depuis un plugin (TTS, STT, génération d’images, recherche web, sous-agent) + - Vous devez appeler des assistants du cœur depuis un plugin (TTS, STT, génération d’images, recherche web, sous-agent) - Vous voulez comprendre ce que `api.runtime` expose - - Vous accédez à des assistants de configuration, d’agent ou de médias depuis le code du plugin + - Vous accédez à des assistants de configuration, d’agent ou de média depuis le code du plugin sidebarTitle: Runtime Helpers -summary: api.runtime -- les assistants runtime injectés disponibles pour les plugins -title: Assistants runtime des plugins +summary: api.runtime -- les assistants d’exécution injectés disponibles pour les plugins +title: Assistants d’exécution du Plugin x-i18n: - generated_at: "2026-04-11T02:46:53Z" + generated_at: "2026-04-15T19:41:44Z" model: gpt-5.4 provider: openai - source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be + source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8 source_path: plugins/sdk-runtime.md workflow: 15 --- -# Assistants runtime des plugins +# Assistants d’exécution du Plugin Référence pour l’objet `api.runtime` injecté dans chaque plugin pendant -l’enregistrement. Utilisez ces assistants au lieu d’importer directement les internes de l’hôte. +l’enregistrement. Utilisez ces assistants au lieu d’importer directement les composants internes de l’hôte. - **Vous cherchez une procédure détaillée ?** Consultez [Plugins de canaux](/fr/plugins/sdk-channel-plugins) - ou [Plugins fournisseurs](/fr/plugins/sdk-provider-plugins) pour des guides pas à pas - montrant ces assistants dans leur contexte. + **Vous cherchez un guide pas à pas ?** Consultez [Plugins de canal](/fr/plugins/sdk-channel-plugins) + ou [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) pour des guides étape par étape + qui montrent ces assistants dans leur contexte. ```typescript @@ -32,7 +32,7 @@ register(api) { } ``` -## Espaces de noms runtime +## Espaces de noms d’exécution ### `api.runtime.agent` @@ -70,12 +70,12 @@ const result = await api.runtime.agent.runEmbeddedAgent({ ``` `runEmbeddedAgent(...)` est l’assistant neutre pour démarrer un tour d’agent OpenClaw -normal depuis le code du plugin. Il utilise la même résolution fournisseur/modèle et -la même sélection d’agent harness que les réponses déclenchées par canal. +normal depuis le code du plugin. Il utilise la même résolution de fournisseur/modèle et +la même sélection du harnais d’agent que les réponses déclenchées par un canal. `runEmbeddedPiAgent(...)` reste un alias de compatibilité. -Les **assistants de stockage de session** se trouvent sous `api.runtime.agent.session` : +Les **assistants du magasin de sessions** se trouvent sous `api.runtime.agent.session` : ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -86,11 +86,11 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId ### `api.runtime.agent.defaults` -Constantes de fournisseur et de modèle par défaut : +Constantes de modèle et de fournisseur par défaut : ```typescript -const model = api.runtime.agent.defaults.model; // ex. "anthropic/claude-sonnet-4-6" -const provider = api.runtime.agent.defaults.provider; // ex. "anthropic" +const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" +const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic" ``` ### `api.runtime.subagent` @@ -123,15 +123,15 @@ await api.runtime.subagent.deleteSession({ ``` - Les remplacements de modèle (`provider`/`model`) nécessitent l’activation explicite de l’opérateur via + Les remplacements de modèle (`provider`/`model`) nécessitent un opt-in de l’opérateur via `plugins.entries..subagent.allowModelOverride: true` dans la configuration. Les plugins non fiables peuvent toujours exécuter des sous-agents, mais les demandes de remplacement sont rejetées. ### `api.runtime.taskFlow` -Lier un runtime Task Flow à une clé de session OpenClaw existante ou à un contexte -d’outil de confiance, puis créer et gérer des Task Flows sans passer un propriétaire à chaque appel. +Lier un runtime TaskFlow à une clé de session OpenClaw existante ou à un contexte +d’outil de confiance, puis créer et gérer des TaskFlow sans transmettre un propriétaire à chaque appel. ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); @@ -158,8 +158,8 @@ const waiting = taskFlow.setWaiting({ }); ``` -Utilisez `bindSession({ sessionKey, requesterOrigin })` lorsque vous avez déjà une -clé de session OpenClaw de confiance issue de votre propre couche de liaison. Ne liez pas à partir d’une entrée utilisateur brute. +Utilisez `bindSession({ sessionKey, requesterOrigin })` lorsque vous disposez déjà d’une +clé de session OpenClaw de confiance provenant de votre propre couche de liaison. N’effectuez pas de liaison à partir d’une entrée utilisateur brute. ### `api.runtime.tts` @@ -185,8 +185,8 @@ const voices = await api.runtime.tts.listVoices({ }); ``` -Utilise la configuration core `messages.tts` et la sélection du fournisseur. Renvoie un tampon audio PCM -et un taux d’échantillonnage. +Utilise la configuration centrale `messages.tts` et la sélection de fournisseur. Renvoie un +tampon audio PCM + une fréquence d’échantillonnage. ### `api.runtime.mediaUnderstanding` @@ -340,10 +340,10 @@ api.runtime.tools.registerMemoryCli(/* ... */); ### `api.runtime.channel` -Assistants runtime spécifiques aux canaux (disponibles lorsqu’un plugin de canal est chargé). +Assistants d’exécution spécifiques au canal (disponibles lorsqu’un plugin de canal est chargé). -`api.runtime.channel.mentions` est la surface partagée de politique de mention entrante pour -les plugins de canaux intégrés qui utilisent l’injection runtime : +`api.runtime.channel.mentions` est la surface partagée de stratégie de mention entrante pour les +plugins de canal intégrés qui utilisent l’injection du runtime : ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -382,16 +382,19 @@ Assistants de mention disponibles : assistants de compatibilité `resolveMentionGating*`. Préférez le chemin normalisé `{ facts, policy }`. -## Stocker des références runtime +## Stockage des références de runtime -Utilisez `createPluginRuntimeStore` pour stocker la référence runtime afin de l’utiliser en dehors +Utilisez `createPluginRuntimeStore` pour stocker la référence du runtime en vue d’une utilisation en dehors du callback `register` : ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("my-plugin runtime not initialized"); +const store = createPluginRuntimeStore({ + pluginId: "my-plugin", + errorMessage: "my-plugin runtime not initialized", +}); // In your entry point export default defineChannelPluginEntry({ @@ -412,22 +415,25 @@ export function tryGetRuntime() { } ``` +Préférez `pluginId` pour l’identité du runtime-store. La forme de niveau inférieur `key` est +destinée aux cas peu courants où un plugin a intentionnellement besoin de plus d’un emplacement de runtime. + ## Autres champs `api` de niveau supérieur -Au-delà de `api.runtime`, l’objet API fournit également : +Au-delà de `api.runtime`, l’objet API fournit aussi : | Champ | Type | Description | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Identifiant du plugin | -| `api.name` | `string` | Nom d’affichage du plugin | -| `api.config` | `OpenClawConfig` | Instantané actuel de la configuration (instantané runtime actif en mémoire lorsqu’il est disponible) | -| `api.pluginConfig` | `Record` | Configuration spécifique au plugin provenant de `plugins.entries..config` | -| `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) | +| `api.id` | `string` | ID du Plugin | +| `api.name` | `string` | Nom d’affichage du Plugin | +| `api.config` | `OpenClawConfig` | Instantané actuel de la configuration (instantané actif du runtime en mémoire lorsqu’il est disponible) | +| `api.pluginConfig` | `Record` | Configuration spécifique au Plugin provenant de `plugins.entries..config` | +| `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant l’entrée complète | -| `api.resolvePath(input)` | `(string) => string` | Résoudre un chemin relatif à la racine du plugin | +| `api.resolvePath(input)` | `(string) => string` | Résout un chemin relatif à la racine du Plugin | -## Voir aussi +## Lié -- [Aperçu du SDK](/fr/plugins/sdk-overview) -- référence de sous-chemin +- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) -- référence des sous-chemins - [Points d’entrée du SDK](/fr/plugins/sdk-entrypoints) -- options de `definePluginEntry` -- [Internes des plugins](/fr/plugins/architecture) -- modèle de capacités et registre +- [Composants internes du Plugin](/fr/plugins/architecture) -- modèle de capacités et registre diff --git a/docs/fr/plugins/sdk-setup.md b/docs/fr/plugins/sdk-setup.md index 18a20ccc7..325599f0f 100644 --- a/docs/fr/plugins/sdk-setup.md +++ b/docs/fr/plugins/sdk-setup.md @@ -1,35 +1,35 @@ --- read_when: - - Vous ajoutez un assistant de configuration à un plugin - - Vous devez comprendre setup-entry.ts par rapport à index.ts - - Vous définissez des schémas de configuration de plugin ou des métadonnées `openclaw` dans package.json + - Vous ajoutez un assistant de configuration à un Plugin + - Vous devez comprendre `setup-entry.ts` par rapport à `index.ts` + - Vous définissez des schémas de configuration du Plugin ou des métadonnées `openclaw` dans `package.json` sidebarTitle: Setup and Config -summary: Assistants de configuration, setup-entry.ts, schémas de configuration et métadonnées package.json -title: Configuration et setup des plugins +summary: Assistants de configuration, `setup-entry.ts`, schémas de configuration et métadonnées de `package.json` +title: Configuration et config du Plugin x-i18n: - generated_at: "2026-04-06T03:10:26Z" + generated_at: "2026-04-15T19:41:55Z" model: gpt-5.4 provider: openai - source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9 + source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b source_path: plugins/sdk-setup.md workflow: 15 --- -# Configuration et setup des plugins +# Configuration et config du Plugin -Référence pour le packaging des plugins (métadonnées `package.json`), les manifestes -(`openclaw.plugin.json`), les entrées de setup et les schémas de configuration. +Référence pour le packaging des Plugins (métadonnées `package.json`), les manifestes +(`openclaw.plugin.json`), les entrées de configuration et les schémas de config. **Vous cherchez un guide pas à pas ?** Les guides pratiques couvrent le packaging dans son contexte : - [Plugins de canal](/fr/plugins/sdk-channel-plugins#step-1-package-and-manifest) et - [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins#step-1-package-and-manifest). + [Plugins de canaux](/fr/plugins/sdk-channel-plugins#step-1-package-and-manifest) et + [Plugins de fournisseurs](/fr/plugins/sdk-provider-plugins#step-1-package-and-manifest). ## Métadonnées du package -Votre `package.json` doit contenir un champ `openclaw` qui indique au système de plugins ce -que fournit votre plugin : +Votre `package.json` doit contenir un champ `openclaw` qui indique au système de Plugin ce +que votre Plugin fournit : **Plugin de canal :** @@ -50,7 +50,7 @@ que fournit votre plugin : } ``` -**Plugin de fournisseur / base de publication ClawHub :** +**Plugin de fournisseur / référence de publication ClawHub :** ```json openclaw-clawhub-package.json { @@ -71,7 +71,7 @@ que fournit votre plugin : } ``` -Si vous publiez le plugin en externe sur ClawHub, ces champs `compat` et `build` +Si vous publiez le Plugin en externe sur ClawHub, ces champs `compat` et `build` sont obligatoires. Les extraits canoniques de publication se trouvent dans `docs/snippets/plugin-publish/`. @@ -80,38 +80,38 @@ sont obligatoires. Les extraits canoniques de publication se trouvent dans | Champ | Type | Description | | ------------ | ---------- | -------------------------------------------------------------------------------------------------------- | | `extensions` | `string[]` | Fichiers de point d’entrée (relatifs à la racine du package) | -| `setupEntry` | `string` | Entrée légère réservée au setup (facultative) | -| `channel` | `object` | Métadonnées du catalogue de canaux pour les surfaces de setup, de sélection, de démarrage rapide et d’état | -| `providers` | `string[]` | Identifiants de fournisseurs enregistrés par ce plugin | +| `setupEntry` | `string` | Entrée légère réservée à la configuration (facultatif) | +| `channel` | `object` | Métadonnées du catalogue de canaux pour les surfaces de configuration, de sélection, de démarrage rapide et d’état | +| `providers` | `string[]` | Identifiants de fournisseurs enregistrés par ce Plugin | | `install` | `object` | Indications d’installation : `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Drapeaux de comportement au démarrage | +| `startup` | `object` | Indicateurs de comportement au démarrage | ### `openclaw.channel` -`openclaw.channel` contient des métadonnées légères du package pour les surfaces de découverte et de setup -des canaux avant le chargement de l’exécution. +`openclaw.channel` correspond à des métadonnées de package peu coûteuses pour la découverte des canaux et les +surfaces de configuration avant le chargement de l’exécution. -| Champ | Type | Signification | -| -------------------------------------- | ---------- | -------------------------------------------------------------------------------- | -| `id` | `string` | Identifiant canonique du canal. | -| `label` | `string` | Libellé principal du canal. | -| `selectionLabel` | `string` | Libellé de sélection/setup lorsqu’il doit différer de `label`. | +| Champ | Type | Signification | +| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ | +| `id` | `string` | Identifiant canonique du canal. | +| `label` | `string` | Libellé principal du canal. | +| `selectionLabel` | `string` | Libellé du sélecteur/de la configuration lorsqu’il doit différer de `label`. | | `detailLabel` | `string` | Libellé de détail secondaire pour des catalogues de canaux et surfaces d’état plus riches. | -| `docsPath` | `string` | Chemin de documentation pour les liens de setup et de sélection. | -| `docsLabel` | `string` | Libellé de remplacement utilisé pour les liens de documentation lorsqu’il doit différer de l’identifiant du canal. | -| `blurb` | `string` | Courte description d’onboarding/catalogue. | -| `order` | `number` | Ordre de tri dans les catalogues de canaux. | -| `aliases` | `string[]` | Alias supplémentaires pour la sélection du canal. | -| `preferOver` | `string[]` | Identifiants de plugin/canal de priorité plus basse que ce canal doit surpasser. | -| `systemImage` | `string` | Nom facultatif d’icône/system-image pour les catalogues UI de canaux. | -| `selectionDocsPrefix` | `string` | Texte préfixe avant les liens de documentation dans les surfaces de sélection. | -| `selectionDocsOmitLabel` | `boolean` | Afficher directement le chemin de documentation au lieu d’un lien documenté avec libellé dans le texte de sélection. | -| `selectionExtras` | `string[]` | Courtes chaînes supplémentaires ajoutées dans le texte de sélection. | -| `markdownCapable` | `boolean` | Marque le canal comme compatible Markdown pour les décisions de formatage sortant. | -| `exposure` | `object` | Contrôles de visibilité du canal pour les surfaces de setup, de listes configurées et de documentation. | -| `quickstartAllowFrom` | `boolean` | Fait participer ce canal au flux standard de setup rapide `allowFrom`. | -| `forceAccountBinding` | `boolean` | Exige un rattachement de compte explicite même lorsqu’un seul compte existe. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Privilégie la recherche de session lors de la résolution des cibles d’annonce pour ce canal. | +| `docsPath` | `string` | Chemin de documentation pour les liens de configuration et de sélection. | +| `docsLabel` | `string` | Libellé de remplacement utilisé pour les liens vers la documentation lorsqu’il doit différer de l’identifiant du canal. | +| `blurb` | `string` | Brève description d’onboarding/de catalogue. | +| `order` | `number` | Ordre de tri dans les catalogues de canaux. | +| `aliases` | `string[]` | Alias de recherche supplémentaires pour la sélection du canal. | +| `preferOver` | `string[]` | Identifiants de Plugin/canal de priorité inférieure que ce canal doit dépasser. | +| `systemImage` | `string` | Nom facultatif d’icône/d’image système pour les catalogues d’interface des canaux. | +| `selectionDocsPrefix` | `string` | Texte préfixe avant les liens vers la documentation dans les surfaces de sélection. | +| `selectionDocsOmitLabel` | `boolean` | Affiche directement le chemin de documentation au lieu d’un lien libellé dans le texte de sélection. | +| `selectionExtras` | `string[]` | Chaînes courtes supplémentaires ajoutées dans le texte de sélection. | +| `markdownCapable` | `boolean` | Indique que le canal prend en charge le Markdown pour les décisions de mise en forme sortante. | +| `exposure` | `object` | Contrôles de visibilité du canal pour la configuration, les listes configurées et les surfaces de documentation. | +| `quickstartAllowFrom` | `boolean` | Active pour ce canal le flux standard de configuration rapide `allowFrom`. | +| `forceAccountBinding` | `boolean` | Exige une liaison explicite de compte même lorsqu’un seul compte existe. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Préfère la recherche de session lors de la résolution des cibles d’annonce pour ce canal. | Exemple : @@ -146,36 +146,35 @@ Exemple : `exposure` prend en charge : - `configured` : inclure le canal dans les surfaces de liste de type configuré/état -- `setup` : inclure le canal dans les sélecteurs interactifs de setup/configuration -- `docs` : marquer le canal comme orienté public dans les surfaces de documentation/navigation +- `setup` : inclure le canal dans les sélecteurs interactifs de configuration/configurer +- `docs` : marquer le canal comme visible publiquement dans les surfaces de documentation/navigation -`showConfigured` et `showInSetup` restent pris en charge comme alias historiques. Préférez +`showConfigured` et `showInSetup` restent pris en charge comme alias hérités. Préférez `exposure`. ### `openclaw.install` `openclaw.install` est une métadonnée de package, pas une métadonnée de manifeste. -| Champ | Type | Signification | -| ---------------------------- | -------------------- | ----------------------------------------------------------------------------------- | -| `npmSpec` | `string` | Spécification npm canonique pour les flux d’installation/mise à jour. | -| `localPath` | `string` | Chemin d’installation local de développement ou groupé. | -| `defaultChoice` | `"npm"` \| `"local"` | Source d’installation préférée lorsque les deux sont disponibles. | -| `minHostVersion` | `string` | Version minimale d’OpenClaw prise en charge, sous la forme `>=x.y.z`. | -| `allowInvalidConfigRecovery` | `boolean` | Permet aux flux de réinstallation de plugin groupé de récupérer après certains échecs dus à une configuration obsolète. | +| Champ | Type | Signification | +| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- | +| `npmSpec` | `string` | Spécification npm canonique pour les flux d’installation/de mise à jour. | +| `localPath` | `string` | Chemin d’installation local de développement ou intégré. | +| `defaultChoice` | `"npm"` \| `"local"` | Source d’installation préférée lorsque les deux sont disponibles. | +| `minHostVersion` | `string` | Version minimale prise en charge d’OpenClaw sous la forme `>=x.y.z`. | +| `allowInvalidConfigRecovery` | `boolean` | Permet aux flux de réinstallation de Plugins intégrés de récupérer de certaines erreurs de configuration obsolète. | -Si `minHostVersion` est défini, l’installation et le chargement du registre de manifestes -l’appliquent tous deux. Les hôtes plus anciens ignorent le plugin ; les chaînes de version invalides sont rejetées. +Si `minHostVersion` est défini, l’installation et le chargement du registre de manifestes l’appliquent tous deux. +Les hôtes plus anciens ignorent le Plugin ; les chaînes de version invalides sont rejetées. -`allowInvalidConfigRecovery` n’est pas un contournement général des configurations cassées. Il sert -uniquement à la récupération étroite de plugins groupés, afin que la réinstallation/le setup puisse réparer des restes -connus de mise à niveau comme un chemin de plugin groupé manquant ou une entrée `channels.` -obsolète pour ce même plugin. Si la configuration est cassée pour des raisons non liées, l’installation -échoue quand même de façon fermée et indique à l’opérateur d’exécuter `openclaw doctor --fix`. +`allowInvalidConfigRecovery` n’est pas un contournement général pour des configurations cassées. Il sert +uniquement à une récupération ciblée pour les Plugins intégrés, afin que la réinstallation/la configuration puisse corriger des restes connus de mise à niveau comme un chemin de Plugin intégré manquant ou une entrée `channels.` +obsolète pour ce même Plugin. Si la configuration est cassée pour des raisons sans rapport, l’installation +échoue quand même de manière sûre et indique à l’opérateur d’exécuter `openclaw doctor --fix`. ### Chargement complet différé -Les plugins de canal peuvent choisir le chargement différé avec : +Les Plugins de canaux peuvent activer le chargement différé avec : ```json { @@ -189,26 +188,25 @@ Les plugins de canal peuvent choisir le chargement différé avec : } ``` -Lorsqu’il est activé, OpenClaw ne charge que `setupEntry` pendant la phase de démarrage -précédant l’écoute, même pour les canaux déjà configurés. L’entrée complète est chargée après -le début de l’écoute de la gateway. +Lorsqu’elle est activée, OpenClaw charge uniquement `setupEntry` pendant la phase de démarrage avant l’écoute, +même pour les canaux déjà configurés. Le point d’entrée complet est chargé une fois que la Gateway commence à écouter. N’activez le chargement différé que si votre `setupEntry` enregistre tout ce dont la - gateway a besoin avant de commencer à écouter (enregistrement du canal, routes HTTP, - méthodes de gateway). Si l’entrée complète possède des capacités requises au démarrage, conservez + Gateway a besoin avant de commencer à écouter (enregistrement du canal, routes HTTP, + méthodes Gateway). Si le point d’entrée complet possède des capacités de démarrage requises, conservez le comportement par défaut. -Si votre setup/entrée complète enregistre des méthodes RPC de gateway, conservez-les sur un -préfixe spécifique au plugin. Les espaces de noms d’administration du noyau réservés (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) restent possédés par le noyau et sont toujours résolus +Si votre entrée de configuration/complète enregistre des méthodes RPC Gateway, conservez-les sur un +préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur réservés (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) restent la propriété du cœur et sont toujours résolus vers `operator.admin`. -## Manifeste du plugin +## Manifeste du Plugin -Chaque plugin natif doit livrer un `openclaw.plugin.json` à la racine du package. -OpenClaw l’utilise pour valider la configuration sans exécuter le code du plugin. +Chaque Plugin natif doit fournir un `openclaw.plugin.json` à la racine du package. +OpenClaw l’utilise pour valider la configuration sans exécuter le code du Plugin. ```json { @@ -228,7 +226,7 @@ OpenClaw l’utilise pour valider la configuration sans exécuter le code du plu } ``` -Pour les plugins de canal, ajoutez `kind` et `channels` : +Pour les Plugins de canaux, ajoutez `kind` et `channels` : ```json { @@ -243,7 +241,7 @@ Pour les plugins de canal, ajoutez `kind` et `channels` : } ``` -Même les plugins sans configuration doivent livrer un schéma. Un schéma vide est valide : +Même les Plugins sans configuration doivent fournir un schéma. Un schéma vide est valide : ```json { @@ -255,25 +253,25 @@ Même les plugins sans configuration doivent livrer un schéma. Un schéma vide } ``` -Voir [Manifeste de plugin](/fr/plugins/manifest) pour la référence complète du schéma. +Voir [Manifeste du Plugin](/fr/plugins/manifest) pour la référence complète du schéma. -## Publication sur ClawHub +## Publication ClawHub -Pour les packages de plugins, utilisez la commande ClawHub spécifique au package : +Pour les packages de Plugin, utilisez la commande ClawHub spécifique au package : ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -L’ancien alias de publication réservé aux skills concerne les skills. Les packages de plugins doivent +L’ancien alias de publication réservé aux Skills concerne les Skills. Les packages de Plugin doivent toujours utiliser `clawhub package publish`. -## Entrée de setup +## Entrée de configuration Le fichier `setup-entry.ts` est une alternative légère à `index.ts` que -OpenClaw charge lorsqu’il n’a besoin que des surfaces de setup (onboarding, réparation de configuration, -inspection de canal désactivé). +OpenClaw charge lorsqu’il n’a besoin que des surfaces de configuration (onboarding, réparation de config, +inspection des canaux désactivés). ```typescript // setup-entry.ts @@ -284,75 +282,79 @@ export default defineSetupPluginEntry(myChannelPlugin); ``` Cela évite de charger du code d’exécution lourd (bibliothèques de chiffrement, enregistrements CLI, -services d’arrière-plan) pendant les flux de setup. +services en arrière-plan) pendant les flux de configuration. -**Quand OpenClaw utilise `setupEntry` au lieu de l’entrée complète :** +Les canaux d’espace de travail intégrés qui conservent des exports sûrs pour la configuration dans des modules annexes peuvent +utiliser `defineBundledChannelSetupEntry(...)` depuis +`openclaw/plugin-sdk/channel-entry-contract` au lieu de +`defineSetupPluginEntry(...)`. Ce contrat intégré prend également en charge un export `runtime` +facultatif afin que le câblage de l’exécution au moment de la configuration reste léger et explicite. -- Le canal est désactivé mais a besoin des surfaces de setup/onboarding +**Quand OpenClaw utilise `setupEntry` au lieu du point d’entrée complet :** + +- Le canal est désactivé mais a besoin de surfaces de configuration/d’onboarding - Le canal est activé mais non configuré - Le chargement différé est activé (`deferConfiguredChannelFullLoadUntilAfterListen`) **Ce que `setupEntry` doit enregistrer :** -- L’objet plugin de canal (via `defineSetupPluginEntry`) -- Toute route HTTP requise avant l’écoute de la gateway -- Toute méthode de gateway nécessaire au démarrage +- L’objet Plugin de canal (via `defineSetupPluginEntry`) +- Toute route HTTP requise avant l’écoute de la Gateway +- Toute méthode Gateway nécessaire au démarrage -Ces méthodes de gateway de démarrage doivent toujours éviter les espaces de noms -d’administration du noyau réservés comme `config.*` ou `update.*`. +Ces méthodes Gateway de démarrage doivent toujours éviter les espaces de noms d’administration du cœur +réservés tels que `config.*` ou `update.*`. **Ce que `setupEntry` ne doit PAS inclure :** - Enregistrements CLI -- Services d’arrière-plan -- Imports d’exécution lourds (crypto, SDK) -- Méthodes de gateway nécessaires uniquement après le démarrage +- Services en arrière-plan +- Imports d’exécution lourds (chiffrement, SDK) +- Méthodes Gateway nécessaires uniquement après le démarrage -### Imports d’assistants de setup étroits +### Imports d’assistants de configuration ciblés -Pour les chemins chauds réservés au setup, préférez les points d’accès étroits des assistants de setup plutôt que le point d’accès plus large -`plugin-sdk/setup` lorsque vous n’avez besoin que d’une partie de la surface de setup : +Pour les chemins critiques réservés à la configuration, préférez les points d’accès d’assistants de configuration ciblés plutôt que le point d’accès plus large +`plugin-sdk/setup` lorsque vous n’avez besoin que d’une partie de la surface de configuration : -| Chemin d’import | À utiliser pour | Exports clés | -| ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | assistants d’exécution au moment du setup qui restent disponibles dans `setupEntry` / démarrage différé de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | adaptateurs de setup de compte sensibles à l’environnement | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | assistants setup/install CLI/archive/documentation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| Chemin d’import | À utiliser pour | Exports clés | +| ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | assistants d’exécution au moment de la configuration qui restent disponibles dans `setupEntry` / le démarrage différé du canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | adaptateurs de configuration de compte sensibles à l’environnement | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | assistants CLI/archive/documentation de configuration/installation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -Utilisez le point d’accès plus large `plugin-sdk/setup` lorsque vous voulez la boîte à outils de setup partagée complète, -y compris les assistants de patch de configuration tels que +Utilisez le point d’accès plus large `plugin-sdk/setup` lorsque vous souhaitez l’ensemble complet de la boîte à outils de configuration partagée, y compris les assistants de correctif de configuration tels que `moveSingleAccountChannelSectionToDefaultAccount(...)`. -Les adaptateurs de patch de setup restent sûrs pour le chemin chaud à l’import. Leur recherche groupée -de surface de contrat de promotion de compte unique est paresseuse, donc l’import de -`plugin-sdk/setup-runtime` ne charge pas de manière anticipée la découverte de surface de contrat groupée avant que l’adaptateur soit réellement utilisé. +Les adaptateurs de correctif de configuration restent sûrs à l’importation sur les chemins critiques. Leur +recherche de surface de contrat de promotion de compte unique intégrée est paresseuse ; ainsi, l’import de +`plugin-sdk/setup-runtime` ne charge pas de manière anticipée la découverte de surface de contrat intégrée avant l’utilisation effective de l’adaptateur. -### Promotion de compte unique possédée par le canal +### Promotion de compte unique gérée par le canal -Lorsqu’un canal passe d’une configuration de niveau supérieur à compte unique vers +Lorsqu’un canal passe d’une config de niveau supérieur à compte unique à `channels..accounts.*`, le comportement partagé par défaut consiste à déplacer les -valeurs promues à portée de compte dans `accounts.default`. +valeurs promues de portée compte dans `accounts.default`. -Les canaux groupés peuvent restreindre ou remplacer cette promotion via leur surface de contrat -de setup : +Les canaux intégrés peuvent restreindre ou remplacer cette promotion via leur surface de contrat de configuration : -- `singleAccountKeysToMove` : clés supplémentaires de niveau supérieur qui doivent être déplacées dans le +- `singleAccountKeysToMove` : clés supplémentaires de niveau supérieur qui doivent être déplacées vers le compte promu - `namedAccountPromotionKeys` : lorsque des comptes nommés existent déjà, seules ces - clés sont déplacées dans le compte promu ; les clés partagées de politique/livraison restent à la - racine du canal + clés sont déplacées vers le compte promu ; les clés partagées de stratégie/de distribution restent à la racine + du canal - `resolveSingleAccountPromotionTarget(...)` : choisit quel compte existant reçoit les valeurs promues -Matrix est l’exemple groupé actuel. Si exactement un compte Matrix nommé -existe déjà, ou si `defaultAccount` pointe vers une clé existante non canonique -telle que `Ops`, la promotion conserve ce compte au lieu de créer une nouvelle +Matrix est l’exemple intégré actuel. Si exactement un compte Matrix nommé existe déjà, +ou si `defaultAccount` pointe vers une clé existante non canonique telle que +`Ops`, la promotion préserve ce compte au lieu de créer une nouvelle entrée `accounts.default`. -## Schéma de configuration +## Schéma de config -La configuration du plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs -configurent les plugins via : +La config du Plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs +configurent les Plugins via : ```json5 { @@ -368,9 +370,9 @@ configurent les plugins via : } ``` -Votre plugin reçoit cette configuration sous la forme `api.pluginConfig` pendant l’enregistrement. +Votre Plugin reçoit cette config sous la forme de `api.pluginConfig` lors de l’enregistrement. -Pour une configuration spécifique à un canal, utilisez plutôt la section de configuration du canal : +Pour une config spécifique au canal, utilisez plutôt la section de config du canal : ```json5 { @@ -383,10 +385,10 @@ Pour une configuration spécifique à un canal, utilisez plutôt la section de c } ``` -### Construire des schémas de configuration de canal +### Création de schémas de config de canal Utilisez `buildChannelConfigSchema` depuis `openclaw/plugin-sdk/core` pour convertir un -schéma Zod dans l’enveloppe `ChannelConfigSchema` qu’OpenClaw valide : +schéma Zod en l’enveloppe `ChannelConfigSchema` que OpenClaw valide : ```typescript import { z } from "zod"; @@ -404,7 +406,7 @@ const configSchema = buildChannelConfigSchema(accountSchema); ## Assistants de configuration -Les plugins de canal peuvent fournir des assistants de configuration interactifs pour `openclaw onboard`. +Les Plugins de canaux peuvent fournir des assistants de configuration interactifs pour `openclaw onboard`. L’assistant est un objet `ChannelSetupWizard` sur le `ChannelPlugin` : ```typescript @@ -439,22 +441,21 @@ const setupWizard: ChannelSetupWizard = { ``` Le type `ChannelSetupWizard` prend en charge `credentials`, `textInputs`, -`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, etc. -Consultez les packages de plugins groupés (par exemple le plugin Discord `src/channel.setup.ts`) pour +`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, et plus encore. +Consultez les packages de Plugins intégrés (par exemple le Plugin Discord `src/channel.setup.ts`) pour des exemples complets. -Pour les invites de liste d’autorisation DM qui n’ont besoin que du flux standard -`note -> prompt -> parse -> merge -> patch`, préférez les assistants de setup partagés -de `openclaw/plugin-sdk/setup` : `createPromptParsedAllowFromForAccount(...)`, -`createTopLevelChannelParsedAllowFromPrompt(...)` et +Pour les invites de liste d’autorisation de message direct qui n’ont besoin que du flux standard +`note -> prompt -> parse -> merge -> patch`, préférez les assistants de configuration partagés depuis `openclaw/plugin-sdk/setup` : `createPromptParsedAllowFromForAccount(...)`, +`createTopLevelChannelParsedAllowFromPrompt(...)`, et `createNestedChannelParsedAllowFromPrompt(...)`. -Pour les blocs d’état de setup de canal qui ne varient que par les libellés, les scores et d’éventuelles +Pour les blocs d’état de configuration de canal qui ne varient que par les libellés, les scores et d’éventuelles lignes supplémentaires, préférez `createStandardChannelSetupStatus(...)` depuis `openclaw/plugin-sdk/setup` au lieu de recréer à la main le même objet `status` dans -chaque plugin. +chaque Plugin. -Pour les surfaces de setup facultatives qui ne doivent apparaître que dans certains contextes, utilisez +Pour les surfaces de configuration facultatives qui ne doivent apparaître que dans certains contextes, utilisez `createOptionalChannelSetupSurface` depuis `openclaw/plugin-sdk/channel-setup` : ```typescript @@ -474,19 +475,19 @@ const setupSurface = createOptionalChannelSetupSurface({ `createOptionalChannelSetupWizard(...)` lorsque vous n’avez besoin que d’une moitié de cette surface d’installation facultative. -L’adaptateur/l’assistant facultatif généré échoue de manière fermée sur les vraies écritures de configuration. Ils -réutilisent un message unique d’installation requise dans `validateInput`, -`applyAccountConfig` et `finalize`, et ajoutent un lien de documentation lorsque `docsPath` est +L’adaptateur/l’assistant facultatif généré échoue de manière sûre sur les vraies écritures de config. Ils +réutilisent un message unique indiquant qu’une installation est requise dans `validateInput`, +`applyAccountConfig`, et `finalize`, et ajoutent un lien vers la documentation lorsque `docsPath` est défini. -Pour les UI de setup pilotées par binaire, préférez les assistants partagés délégués au lieu de -copier la même logique de binaire/état dans chaque canal : +Pour les interfaces de configuration adossées à un binaire, préférez les assistants délégués partagés au lieu de +copier la même logique de binaire/d’état dans chaque canal : - `createDetectedBinaryStatus(...)` pour les blocs d’état qui ne varient que par les libellés, - indications, scores et détection de binaire -- `createCliPathTextInput(...)` pour les entrées texte adossées à un chemin + les indications, les scores et la détection du binaire +- `createCliPathTextInput(...)` pour les entrées de texte adossées à un chemin - `createDelegatedSetupWizardStatusResolvers(...)`, - `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` et + `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)`, et `createDelegatedResolveConfigured(...)` lorsque `setupEntry` doit transférer vers un assistant complet plus lourd de manière paresseuse - `createDelegatedTextInputShouldPrompt(...)` lorsque `setupEntry` n’a besoin que de @@ -500,22 +501,22 @@ copier la même logique de binaire/état dans chaque canal : openclaw plugins install @myorg/openclaw-my-plugin ``` -OpenClaw essaie d’abord ClawHub puis bascule automatiquement vers npm. Vous pouvez aussi +OpenClaw essaie d’abord ClawHub puis bascule automatiquement sur npm. Vous pouvez aussi forcer explicitement ClawHub : ```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub uniquement +openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only ``` -Il n’existe pas de remplacement `npm:` correspondant. Utilisez la spécification de package npm normale lorsque vous +Il n’existe pas d’équivalent pour le remplacement `npm:`. Utilisez la spécification normale du package npm lorsque vous voulez le chemin npm après le repli ClawHub : ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -**Plugins dans le dépôt :** placez-les sous l’arborescence de workspace des plugins groupés et ils seront automatiquement -détectés pendant le build. +**Plugins dans le dépôt :** placez-les dans l’arborescence d’espace de travail des Plugins intégrés et ils seront automatiquement +découverts pendant la compilation. **Les utilisateurs peuvent installer :** @@ -524,13 +525,13 @@ openclaw plugins install ``` - Pour les installations issues de npm, `openclaw plugins install` exécute - `npm install --ignore-scripts` (sans scripts de cycle de vie). Conservez des arbres de dépendances de plugin - purs JS/TS et évitez les packages qui nécessitent des builds `postinstall`. + Pour les installations depuis npm, `openclaw plugins install` exécute + `npm install --ignore-scripts` (aucun script de cycle de vie). Gardez les arborescences de dépendances des Plugins + en pur JS/TS et évitez les packages qui nécessitent des compilations `postinstall`. ## Lié -- [Points d’entrée du SDK](/fr/plugins/sdk-entrypoints) -- `definePluginEntry` et `defineChannelPluginEntry` -- [Manifeste de plugin](/fr/plugins/manifest) -- référence complète du schéma de manifeste -- [Créer des plugins](/fr/plugins/building-plugins) -- guide pas à pas pour démarrer +- [Points d’entrée SDK](/fr/plugins/sdk-entrypoints) -- `definePluginEntry` et `defineChannelPluginEntry` +- [Manifeste du Plugin](/fr/plugins/manifest) -- référence complète du schéma du manifeste +- [Création de Plugins](/fr/plugins/building-plugins) -- guide de démarrage pas à pas diff --git a/docs/fr/plugins/sdk-testing.md b/docs/fr/plugins/sdk-testing.md index eb4a7a791..7e47e467b 100644 --- a/docs/fr/plugins/sdk-testing.md +++ b/docs/fr/plugins/sdk-testing.md @@ -1,34 +1,34 @@ --- read_when: - Vous écrivez des tests pour un plugin - - Vous avez besoin d’utilitaires de test du SDK plugin - - Vous voulez comprendre les tests de contrat pour les plugins intégrés + - Vous avez besoin d’utilitaires de test du SDK du Plugin + - Vous souhaitez comprendre les tests de contrat pour les plugins intégrés sidebarTitle: Testing summary: Utilitaires et modèles de test pour les plugins OpenClaw -title: Tests de plugins +title: Tests du Plugin x-i18n: - generated_at: "2026-04-05T12:50:44Z" + generated_at: "2026-04-15T19:41:46Z" model: gpt-5.4 provider: openai - source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe + source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09 source_path: plugins/sdk-testing.md workflow: 15 --- -# Tests de plugins +# Tests du Plugin -Référence pour les utilitaires de test, les modèles et l’application des règles lint pour les +Référence pour les utilitaires de test, les modèles et l’application des règles de lint pour les plugins OpenClaw. - **Vous cherchez des exemples de tests ?** Les guides pratiques incluent des exemples de tests détaillés : - [Tests de plugin de canal](/plugins/sdk-channel-plugins#step-6-test) et - [Tests de plugin de provider](/plugins/sdk-provider-plugins#step-6-test). + **Vous cherchez des exemples de test ?** Les guides pratiques incluent des exemples de test complets : + [Tests de plugins de canal](/fr/plugins/sdk-channel-plugins#step-6-test) et + [Tests de plugins de fournisseur](/fr/plugins/sdk-provider-plugins#step-6-test). ## Utilitaires de test -**Import :** `openclaw/plugin-sdk/testing` +**Importation :** `openclaw/plugin-sdk/testing` Le sous-chemin de test exporte un ensemble restreint d’assistants pour les auteurs de plugins : @@ -42,15 +42,15 @@ import { ### Exports disponibles -| Export | But | -| -------------------------------------- | ----------------------------------------------------- | +| Export | But | +| -------------------------------------- | ------------------------------------------------------ | | `installCommonResolveTargetErrorCases` | Cas de test partagés pour la gestion des erreurs de résolution de cible | -| `shouldAckReaction` | Vérifie si un canal doit ajouter une réaction d’ack | -| `removeAckReactionAfterReply` | Supprime la réaction d’ack après la livraison de la réponse | +| `shouldAckReaction` | Vérifier si un canal doit ajouter une réaction d’accusé de réception | +| `removeAckReactionAfterReply` | Supprimer la réaction d’accusé de réception après l’envoi de la réponse | ### Types -Le sous-chemin de test réexporte également des types utiles dans les fichiers de test : +Le sous-chemin de test réexporte aussi des types utiles dans les fichiers de test : ```typescript import type { @@ -65,23 +65,23 @@ import type { ## Tester la résolution de cible -Utilisez `installCommonResolveTargetErrorCases` pour ajouter des cas d’erreur standard à la -résolution de cible d’un canal : +Utilisez `installCommonResolveTargetErrorCases` pour ajouter des cas d’erreur standard pour la +résolution de cible de canal : ```typescript import { describe } from "vitest"; import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing"; -describe("résolution de cible my-channel", () => { +describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // Logique de résolution de cible de votre canal + // Your channel's target resolution logic return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // Ajouter des cas de test spécifiques au canal + // Add channel-specific test cases it("should resolve @username targets", () => { // ... }); @@ -90,12 +90,12 @@ describe("résolution de cible my-channel", () => { ## Modèles de test -### Tester unitaire un plugin de canal +### Test unitaire d’un Plugin de canal ```typescript import { describe, it, expect, vi } from "vitest"; -describe("plugin my-channel", () => { +describe("my-channel plugin", () => { it("should resolve account from config", () => { const cfg = { channels: { @@ -120,22 +120,22 @@ describe("plugin my-channel", () => { const inspection = myPlugin.setup.inspectAccount(cfg, undefined); expect(inspection.configured).toBe(true); expect(inspection.tokenStatus).toBe("available"); - // Aucune valeur de jeton exposée + // No token value exposed expect(inspection).not.toHaveProperty("token"); }); }); ``` -### Tester unitaire un plugin de provider +### Test unitaire d’un Plugin de fournisseur ```typescript import { describe, it, expect } from "vitest"; -describe("plugin my-provider", () => { +describe("my-provider plugin", () => { it("should resolve dynamic models", () => { const model = myProvider.resolveDynamicModel({ modelId: "custom-model-v2", - // ... contexte + // ... context }); expect(model.id).toBe("custom-model-v2"); @@ -146,7 +146,7 @@ describe("plugin my-provider", () => { it("should return catalog when API key is available", async () => { const result = await myProvider.catalog.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), - // ... contexte + // ... context }); expect(result?.provider?.models).toHaveLength(2); @@ -154,7 +154,7 @@ describe("plugin my-provider", () => { }); ``` -### Simuler le runtime du plugin +### Simuler le runtime du Plugin Pour le code qui utilise `createPluginRuntimeStore`, simulez le runtime dans les tests : @@ -162,43 +162,46 @@ Pour le code qui utilise `createPluginRuntimeStore`, simulez le runtime dans les import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("test runtime not set"); +const store = createPluginRuntimeStore({ + pluginId: "test-plugin", + errorMessage: "test runtime not set", +}); -// Dans la configuration du test +// In test setup const mockRuntime = { agent: { resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"), - // ... autres simulations + // ... other mocks }, config: { loadConfig: vi.fn(), writeConfigFile: vi.fn(), }, - // ... autres espaces de noms + // ... other namespaces } as unknown as PluginRuntime; store.setRuntime(mockRuntime); -// Après les tests +// After tests store.clearRuntime(); ``` ### Tester avec des stubs par instance -Préférez les stubs par instance à la mutation de prototype : +Préférez les stubs par instance à la mutation du prototype : ```typescript -// Préféré : stub par instance +// Preferred: per-instance stub const client = new MyChannelClient(); client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); -// À éviter : mutation du prototype +// Avoid: prototype mutation // MyChannelClient.prototype.sendMessage = vi.fn(); ``` -## Tests de contrat (plugins dans le dépôt) +## Tests de contrat (plugins du dépôt) -Les plugins intégrés ont des tests de contrat qui vérifient la propriété de l’enregistrement : +Les plugins intégrés disposent de tests de contrat qui vérifient la propriété de l’enregistrement : ```bash pnpm test -- src/plugins/contracts/ @@ -206,10 +209,10 @@ pnpm test -- src/plugins/contracts/ Ces tests vérifient : -- Quels plugins enregistrent quels providers -- Quels plugins enregistrent quels providers de parole -- La correction de la forme d’enregistrement -- La conformité du contrat d’exécution +- Quels plugins enregistrent quels fournisseurs +- Quels plugins enregistrent quels fournisseurs vocaux +- La justesse de la forme d’enregistrement +- La conformité au contrat d’exécution ### Exécuter des tests ciblés @@ -227,32 +230,32 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Application des règles lint (plugins dans le dépôt) +## Application des règles de lint (plugins du dépôt) -Trois règles sont appliquées par `pnpm check` pour les plugins dans le dépôt : +Trois règles sont appliquées par `pnpm check` pour les plugins du dépôt : -1. **Pas d’imports racine monolithiques** -- la racine `openclaw/plugin-sdk` est rejetée -2. **Pas d’imports directs `src/`** -- les plugins ne peuvent pas importer directement `../../src/` +1. **Pas d’imports racine monolithiques** -- le barrel racine `openclaw/plugin-sdk` est rejeté +2. **Pas d’imports directs depuis `src/`** -- les plugins ne peuvent pas importer `../../src/` directement 3. **Pas d’auto-imports** -- les plugins ne peuvent pas importer leur propre sous-chemin `plugin-sdk/` -Les plugins externes ne sont pas soumis à ces règles lint, mais il est recommandé de suivre les mêmes +Les plugins externes ne sont pas soumis à ces règles de lint, mais il est recommandé de suivre les mêmes modèles. ## Configuration des tests -OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugin : +OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugins : ```bash -# Exécuter tous les tests +# Run all tests pnpm test -# Exécuter les tests d’un plugin spécifique +# Run specific plugin tests pnpm test -- /my-channel/src/channel.test.ts -# Exécuter avec un filtre sur un nom de test spécifique +# Run with a specific test name filter pnpm test -- /my-channel/ -t "resolves account" -# Exécuter avec la couverture +# Run with coverage pnpm test:coverage ``` @@ -262,9 +265,9 @@ Si les exécutions locales provoquent une pression mémoire : OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ``` -## Liens associés +## Voir aussi -- [SDK Overview](/plugins/sdk-overview) -- conventions d’import -- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- interface des plugins de canal -- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- hooks des plugins de provider -- [Building Plugins](/plugins/building-plugins) -- guide de démarrage +- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) -- conventions d’importation +- [SDK Channel Plugins](/fr/plugins/sdk-channel-plugins) -- interface de Plugin de canal +- [SDK Provider Plugins](/fr/plugins/sdk-provider-plugins) -- hooks de Plugin de fournisseur +- [Création de plugins](/fr/plugins/building-plugins) -- guide de démarrage diff --git a/docs/fr/reference/token-use.md b/docs/fr/reference/token-use.md index 5e9ea2764..b7a3be09c 100644 --- a/docs/fr/reference/token-use.md +++ b/docs/fr/reference/token-use.md @@ -1,35 +1,39 @@ --- read_when: - Expliquer l’utilisation des tokens, les coûts ou les fenêtres de contexte - - Déboguer la croissance du contexte ou le comportement de compactage -summary: Comment OpenClaw construit le contexte du prompt et rapporte l’utilisation des tokens ainsi que les coûts + - Déboguer la croissance du contexte ou le comportement de Compaction +summary: Comment OpenClaw construit le contexte du prompt et rapporte l’utilisation des tokens et les coûts title: Utilisation des tokens et coûts x-i18n: - generated_at: "2026-04-12T06:50:09Z" + generated_at: "2026-04-15T19:42:15Z" model: gpt-5.4 provider: openai - source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb + source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5 source_path: reference/token-use.md workflow: 15 --- # Utilisation des tokens et coûts -OpenClaw suit les **tokens**, pas les caractères. Les tokens sont spécifiques au modèle, mais la plupart des modèles de style OpenAI ont une moyenne d’environ 4 caractères par token pour le texte anglais. +OpenClaw suit les **tokens**, pas les caractères. Les tokens dépendent du modèle, mais la plupart +des modèles de style OpenAI font en moyenne ~4 caractères par token pour le texte en anglais. ## Comment le prompt système est construit -OpenClaw assemble son propre prompt système à chaque exécution. Il inclut : +OpenClaw assemble son propre prompt système à chaque exécution. Il comprend : - Liste des outils + courtes descriptions -- Liste des Skills (métadonnées uniquement ; les instructions sont chargées à la demande avec `read`) -- Instructions d’auto-mise à jour -- Fichiers de l’espace de travail + d’initialisation (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` lorsqu’il est nouveau, ainsi que `MEMORY.md` lorsqu’il est présent ou `memory.md` comme solution de secours en minuscules). Les fichiers volumineux sont tronqués par `agents.defaults.bootstrapMaxChars` (par défaut : 20000), et l’injection totale d’initialisation est plafonnée par `agents.defaults.bootstrapTotalMaxChars` (par défaut : 150000). Les fichiers quotidiens `memory/*.md` ne font pas partie du prompt d’initialisation normal ; ils restent accessibles à la demande via les outils de mémoire lors des tours ordinaires, mais `/new` et `/reset` seuls peuvent préfixer un bloc de contexte de démarrage à usage unique avec la mémoire quotidienne récente pour ce premier tour. Ce préambule de démarrage est contrôlé par `agents.defaults.startupContext`. +- Liste des Skills (métadonnées uniquement ; les instructions sont chargées à la demande avec `read`). + Le bloc compact des Skills est limité par `skills.limits.maxSkillsPromptChars`, + avec une surcharge facultative par agent dans + `agents.list[].skillsLimits.maxSkillsPromptChars`. +- Instructions de mise à jour automatique +- Fichiers d’espace de travail + d’amorçage (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quand ils sont nouveaux, ainsi que `MEMORY.md` lorsqu’il est présent ou `memory.md` comme solution de repli en minuscules). Les fichiers volumineux sont tronqués par `agents.defaults.bootstrapMaxChars` (par défaut : 12000), et l’injection totale d’amorçage est plafonnée par `agents.defaults.bootstrapTotalMaxChars` (par défaut : 60000). Les fichiers quotidiens `memory/*.md` ne font pas partie du prompt d’amorçage normal ; ils restent accessibles à la demande via les outils de mémoire lors des tours ordinaires, mais les commandes `/new` et `/reset` sans argument peuvent préfixer un bloc de contexte de démarrage à usage unique avec la mémoire quotidienne récente pour ce premier tour. Ce préambule de démarrage est contrôlé par `agents.defaults.startupContext`. - Heure (UTC + fuseau horaire de l’utilisateur) -- Balises de réponse + comportement heartbeat +- Balises de réponse + comportement Heartbeat - Métadonnées d’exécution (hôte/OS/modèle/réflexion) -Voir le détail complet dans [Prompt système](/fr/concepts/system-prompt). +Consultez la ventilation complète dans [Prompt système](/fr/concepts/system-prompt). ## Ce qui compte dans la fenêtre de contexte @@ -39,53 +43,66 @@ Tout ce que le modèle reçoit compte dans la limite de contexte : - Historique de conversation (messages utilisateur + assistant) - Appels d’outils et résultats d’outils - Pièces jointes/transcriptions (images, audio, fichiers) -- Résumés de compactage et artefacts d’élagage -- Wrappers fournisseur ou en-têtes de sécurité (non visibles, mais quand même comptés) +- Résumés de Compaction et artefacts d’élagage +- Wrappers de fournisseur ou en-têtes de sécurité (non visibles, mais quand même comptabilisés) -Pour les images, OpenClaw réduit la taille des charges utiles d’image des transcriptions/outils avant les appels au fournisseur. +Certaines surfaces d’exécution volumineuses ont leurs propres limites explicites : + +- `agents.defaults.contextLimits.memoryGetMaxChars` +- `agents.defaults.contextLimits.memoryGetDefaultLines` +- `agents.defaults.contextLimits.toolResultMaxChars` +- `agents.defaults.contextLimits.postCompactionMaxChars` + +Les surcharges par agent se trouvent sous `agents.list[].contextLimits`. Ces paramètres +servent pour les extraits d’exécution limités et les blocs injectés appartenant à l’exécution. +Ils sont distincts des limites d’amorçage, des limites de contexte de démarrage et des limites +du prompt des Skills. + +Pour les images, OpenClaw réduit les payloads d’image de transcription/d’outil avant les appels au fournisseur. Utilisez `agents.defaults.imageMaxDimensionPx` (par défaut : `1200`) pour ajuster cela : -- Des valeurs plus faibles réduisent généralement l’utilisation de vision tokens et la taille des charges utiles. -- Des valeurs plus élevées préservent davantage de détails visuels pour l’OCR/les captures d’écran d’interface lourdes. +- Des valeurs plus basses réduisent généralement l’utilisation des vision-tokens et la taille des payloads. +- Des valeurs plus élevées préservent davantage de détails visuels pour l’OCR/les captures d’écran riches en UI. -Pour un découpage pratique (par fichier injecté, outils, Skills et taille du prompt système), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context). +Pour une ventilation pratique (par fichier injecté, outils, Skills et taille du prompt système), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context). ## Comment voir l’utilisation actuelle des tokens Utilisez ceci dans le chat : -- `/status` → **carte d’état riche en emoji** avec le modèle de session, l’utilisation du contexte, les tokens d’entrée/sortie de la dernière réponse et le **coût estimé** (clé API uniquement). +- `/status` → **carte d’état riche en emoji** avec le modèle de session, l’utilisation du contexte, + les tokens d’entrée/sortie de la dernière réponse et le **coût estimé** (clé API uniquement). - `/usage off|tokens|full` → ajoute un **pied de page d’utilisation par réponse** à chaque réponse. - - Persiste par session (stocké comme `responseUsage`). - - L’auth OAuth **masque le coût** (tokens uniquement). + - Persistant par session (stocké comme `responseUsage`). + - L’authentification OAuth **masque le coût** (tokens uniquement). - `/usage cost` → affiche un résumé local des coûts à partir des journaux de session OpenClaw. -Autres interfaces : +Autres surfaces : - **TUI/Web TUI :** `/status` + `/usage` sont pris en charge. - **CLI :** `openclaw status --usage` et `openclaw channels list` affichent - des fenêtres de quota fournisseur normalisées (`X% restants`, pas les coûts par réponse). - Fournisseurs actuels avec fenêtre d’utilisation : Anthropic, GitHub Copilot, Gemini CLI, + des fenêtres de quota fournisseur normalisées (`X% left`, et non des coûts par réponse). + Fournisseurs actuels de fenêtre d’utilisation : Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi et z.ai. -Les interfaces d’utilisation normalisent les alias de champs natifs des fournisseurs avant affichage. -Pour le trafic OpenAI-family Responses, cela inclut à la fois `input_tokens` / -`output_tokens` et `prompt_tokens` / `completion_tokens`, afin que les noms de champs -spécifiques au transport ne modifient pas `/status`, `/usage` ni les résumés de session. -L’utilisation JSON de Gemini CLI est également normalisée : le texte de réponse vient de `response`, et -`stats.cached` est mappé à `cacheRead`, avec `stats.input_tokens - stats.cached` +Les surfaces d’utilisation normalisent les alias courants des champs natifs des fournisseurs avant l’affichage. +Pour le trafic Responses de la famille OpenAI, cela inclut à la fois `input_tokens` / +`output_tokens` et `prompt_tokens` / `completion_tokens`, afin que les noms de champs propres +au transport ne modifient pas `/status`, `/usage` ou les résumés de session. +L’utilisation JSON de Gemini CLI est également normalisée : le texte de réponse provient de `response`, et +`stats.cached` est mappé vers `cacheRead`, avec `stats.input_tokens - stats.cached` utilisé lorsque la CLI omet un champ explicite `stats.input`. -Pour le trafic natif OpenAI-family Responses, les alias d’utilisation WebSocket/SSE sont -normalisés de la même manière, et les totaux retombent sur les valeurs normalisées d’entrée + sortie lorsque +Pour le trafic Responses natif de la famille OpenAI, les alias d’utilisation WebSocket/SSE sont +normalisés de la même manière, et les totaux reviennent à l’entrée + sortie normalisées lorsque `total_tokens` est absent ou vaut `0`. -Lorsque l’instantané de la session en cours est peu détaillé, `/status` et `session_status` peuvent +Lorsque l’instantané de la session actuelle est incomplet, `/status` et `session_status` peuvent également récupérer les compteurs de tokens/cache et l’étiquette du modèle d’exécution actif à partir du -journal d’utilisation de transcription le plus récent. Les valeurs actives non nulles existantes restent prioritaires -sur les valeurs de secours issues de la transcription, et des totaux de transcription plus élevés -orientés prompt peuvent l’emporter lorsque les totaux stockés sont absents ou plus faibles. -L’authentification d’utilisation pour les fenêtres de quota fournisseur provient de hooks spécifiques au fournisseur lorsque -disponible ; sinon OpenClaw retombe sur les identifiants OAuth/clé API correspondants provenant des profils d’authentification, -de l’environnement ou de la configuration. +journal d’utilisation de transcription le plus récent. Les valeurs actives non nulles existantes +restent prioritaires sur les valeurs de repli issues de la transcription, et des totaux de transcription +plus élevés orientés prompt peuvent l’emporter lorsque les totaux stockés sont absents ou plus faibles. +L’authentification d’utilisation pour les fenêtres de quota fournisseur provient de hooks spécifiques +au fournisseur lorsqu’ils sont disponibles ; sinon OpenClaw se replie sur des identifiants OAuth/clé API +correspondants issus des profils d’authentification, de l’environnement ou de la configuration. ## Estimation des coûts (lorsqu’elle est affichée) @@ -95,35 +112,36 @@ Les coûts sont estimés à partir de votre configuration tarifaire de modèle : models.providers..models[].cost ``` -Il s’agit de **USD par 1M tokens** pour `input`, `output`, `cacheRead` et +Ce sont des **USD par 1M de tokens** pour `input`, `output`, `cacheRead` et `cacheWrite`. Si la tarification est absente, OpenClaw n’affiche que les tokens. Les tokens OAuth n’affichent jamais de coût en dollars. ## Impact du TTL du cache et de l’élagage -La mise en cache des prompts fournisseur ne s’applique que dans la fenêtre TTL du cache. OpenClaw peut +Le cache de prompt du fournisseur ne s’applique que dans la fenêtre TTL du cache. OpenClaw peut facultativement exécuter un **élagage cache-ttl** : il élague la session une fois le TTL du cache expiré, puis réinitialise la fenêtre de cache afin que les requêtes suivantes puissent réutiliser le -contexte fraîchement mis en cache au lieu de remettre en cache tout l’historique. Cela permet de limiter les -coûts d’écriture dans le cache lorsqu’une session reste inactive au-delà du TTL. +contexte fraîchement mis en cache au lieu de remettre en cache tout l’historique. Cela permet de +maintenir des coûts d’écriture de cache plus faibles lorsqu’une session reste inactive au-delà du TTL. -Configurez cela dans [Configuration de la gateway](/fr/gateway/configuration) et consultez les +Configurez cela dans [Configuration du Gateway](/fr/gateway/configuration) et consultez les détails du comportement dans [Élagage de session](/fr/concepts/session-pruning). -Heartbeat peut maintenir le cache **chaud** pendant les périodes d’inactivité. Si le TTL de cache de votre modèle -est de `1h`, régler l’intervalle heartbeat juste en dessous (par exemple `55m`) peut éviter de -remettre en cache l’intégralité du prompt, ce qui réduit les coûts d’écriture dans le cache. +Heartbeat peut garder le cache **chaud** pendant les périodes d’inactivité. Si le TTL du cache de votre modèle +est `1h`, définir l’intervalle Heartbeat juste en dessous (par ex. `55m`) peut éviter de remettre en cache +le prompt complet, ce qui réduit les coûts d’écriture du cache. -Dans les configurations multi-agent, vous pouvez conserver une configuration de modèle partagée et ajuster le comportement du cache +Dans les configurations multi-agents, vous pouvez conserver une configuration de modèle partagée et ajuster le comportement du cache par agent avec `agents.list[].params.cacheRetention`. -Pour un guide complet paramètre par paramètre, voir [Prompt Caching](/fr/reference/prompt-caching). +Pour un guide complet paramètre par paramètre, voir [Cache de prompt](/fr/reference/prompt-caching). -Pour la tarification de l’API Anthropic, les lectures du cache sont significativement moins chères que les -tokens d’entrée, tandis que les écritures du cache sont facturées avec un multiplicateur plus élevé. Consultez la tarification Anthropic du prompt caching pour connaître les tarifs et multiplicateurs TTL les plus récents : +Pour la tarification de l’API Anthropic, les lectures de cache sont nettement moins coûteuses que les tokens +d’entrée, tandis que les écritures de cache sont facturées avec un multiplicateur plus élevé. Consultez la tarification +du cache de prompt d’Anthropic pour connaître les derniers tarifs et multiplicateurs TTL : [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### Exemple : garder un cache de 1h chaud avec heartbeat +### Exemple : garder un cache de 1h chaud avec Heartbeat ```yaml agents: @@ -153,19 +171,19 @@ agents: - id: "research" default: true heartbeat: - every: "55m" # garde le cache long chaud pour les sessions approfondies + every: "55m" # garder le cache long chaud pour les sessions profondes - id: "alerts" params: - cacheRetention: "none" # évite les écritures de cache pour les notifications par rafales + cacheRetention: "none" # éviter les écritures de cache pour les notifications en rafales ``` -`agents.list[].params` fusionne au-dessus des `params` du modèle sélectionné, ce qui vous permet -de ne remplacer que `cacheRetention` et d’hériter inchangés des autres paramètres par défaut du modèle. +`agents.list[].params` est fusionné par-dessus le `params` du modèle sélectionné, ce qui vous permet +de surcharger uniquement `cacheRetention` et d’hériter inchangés des autres paramètres par défaut du modèle. -### Exemple : activer l’en-tête bêta Anthropic 1M context +### Exemple : activer l’en-tête bêta Anthropic de contexte 1M -La fenêtre de contexte Anthropic de 1M est actuellement protégée par une bêta. OpenClaw peut injecter la -valeur `anthropic-beta` requise lorsque vous activez `context1m` sur les modèles Opus +La fenêtre de contexte 1M d’Anthropic est actuellement protégée par une bêta. OpenClaw peut injecter la +valeur `anthropic-beta` requise lorsque vous activez `context1m` sur des modèles Opus ou Sonnet pris en charge. ```yaml @@ -177,23 +195,23 @@ agents: context1m: true ``` -Cela correspond à l’en-tête bêta Anthropic `context-1m-2025-08-07`. +Cela correspond à l’en-tête bêta `context-1m-2025-08-07` d’Anthropic. -Cela s’applique uniquement lorsque `context1m: true` est défini sur cette entrée de modèle. +Cela ne s’applique que lorsque `context1m: true` est défini sur cette entrée de modèle. -Exigence : l’identifiant doit être éligible à l’utilisation long contexte. Dans le cas contraire, +Exigence : l’identifiant doit être éligible à l’utilisation de contexte long. Sinon, Anthropic répond avec une erreur de limitation de débit côté fournisseur pour cette requête. Si vous authentifiez Anthropic avec des tokens OAuth/d’abonnement (`sk-ant-oat-*`), OpenClaw ignore l’en-tête bêta `context-1m-*` car Anthropic rejette actuellement -cette combinaison avec une erreur HTTP 401. +cette combinaison avec HTTP 401. -## Conseils pour réduire la pression sur les tokens +## Conseils pour réduire la pression des tokens - Utilisez `/compact` pour résumer les longues sessions. - Réduisez les sorties d’outils volumineuses dans vos workflows. - Diminuez `agents.defaults.imageMaxDimensionPx` pour les sessions riches en captures d’écran. - Gardez les descriptions de Skills courtes (la liste des Skills est injectée dans le prompt). -- Préférez des modèles plus petits pour le travail verbeux et exploratoire. +- Préférez des modèles plus petits pour un travail verbeux et exploratoire. Voir [Skills](/fr/tools/skills) pour la formule exacte de surcharge de la liste des Skills.