diff --git a/docs/fr/automation/cron-jobs.md b/docs/fr/automation/cron-jobs.md index 40ab292ca..d99ac94cf 100644 --- a/docs/fr/automation/cron-jobs.md +++ b/docs/fr/automation/cron-jobs.md @@ -1,27 +1,27 @@ --- read_when: - - Planification de tâches en arrière-plan ou de réveils + - Planification de tâches d’arrière-plan ou de réveils - Intégration de déclencheurs externes (webhooks, Gmail) dans OpenClaw - Choisir entre heartbeat et cron pour les tâches planifiées -summary: Tâches planifiées, webhooks et déclencheurs Gmail PubSub pour le planificateur du Gateway +summary: Tâches planifiées, webhooks et déclencheurs Gmail PubSub pour le planificateur de Gateway title: Tâches planifiées x-i18n: - generated_at: "2026-04-11T02:44:20Z" + generated_at: "2026-04-12T06:49:36Z" model: gpt-5.4 provider: openai - source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 + source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f source_path: automation/cron-jobs.md workflow: 15 --- # Tâches planifiées (Cron) -Cron est le planificateur intégré du Gateway. Il conserve les tâches, réveille l’agent au bon moment et peut renvoyer la sortie vers un canal de chat ou un endpoint webhook. +Cron est le planificateur intégré de la Gateway. Il persiste les tâches, réveille l’agent au bon moment et peut renvoyer la sortie vers un canal de chat ou un point de terminaison webhook. ## Démarrage rapide ```bash -# Ajouter un rappel ponctuel +# Ajouter un rappel à exécution unique openclaw cron add \ --name "Reminder" \ --at "2026-02-01T16:00:00Z" \ @@ -40,89 +40,100 @@ openclaw cron runs --id ## Fonctionnement de cron - Cron s’exécute **dans le processus Gateway** (pas dans le modèle). -- Les tâches sont conservées dans `~/.openclaw/cron/jobs.json`, donc les redémarrages ne font pas perdre les planifications. -- Toutes les exécutions cron créent des enregistrements de [tâche en arrière-plan](/fr/automation/tasks). -- Les tâches ponctuelles (`--at`) sont supprimées automatiquement après réussite par défaut. -- Les exécutions cron isolées ferment au mieux les onglets/processus de navigateur suivis pour leur session `cron:` lorsque l’exécution se termine, afin que l’automatisation de navigateur détachée ne laisse pas de processus orphelins derrière elle. -- Les exécutions cron isolées protègent également contre les réponses d’accusé de réception obsolètes. Si le premier résultat n’est qu’une mise à jour de statut intermédiaire (`on it`, `pulling everything -together` et indications similaires) et qu’aucune exécution de sous-agent descendante n’est encore responsable de la réponse finale, OpenClaw relance une fois pour obtenir le résultat réel avant la livraison. +- Les tâches sont persistées dans `~/.openclaw/cron/jobs.json`, donc les redémarrages ne font pas perdre les planifications. +- Toutes les exécutions cron créent des enregistrements de [tâche d’arrière-plan](/fr/automation/tasks). +- Les tâches à exécution unique (`--at`) sont supprimées automatiquement après réussite par défaut. +- Les exécutions cron isolées ferment au mieux les onglets/processus de navigateur suivis pour leur session `cron:` lorsque l’exécution se termine, afin que l’automatisation de navigateur détachée ne laisse pas de processus orphelins. +- Les exécutions cron isolées se protègent aussi contre les réponses d’accusé de réception obsolètes. Si le premier résultat n’est qu’une mise à jour d’état intermédiaire (`on it`, `pulling everything together` et indices similaires) et qu’aucune exécution de sous-agent descendante n’est encore responsable de la réponse finale, OpenClaw relance une invite une fois pour obtenir le résultat réel avant la livraison. -La réconciliation des tâches pour cron est gérée par le runtime : une tâche cron active reste active tant que le runtime cron suit encore cette tâche comme étant en cours d’exécution, même si une ancienne ligne de session enfant existe encore. -Une fois que le runtime ne gère plus la tâche et que la fenêtre de grâce de 5 minutes expire, la maintenance peut marquer la tâche comme `lost`. +La réconciliation des tâches pour cron est gérée par le runtime : une tâche cron active reste vivante tant que le runtime cron suit encore cette tâche comme étant en cours d’exécution, même si une ancienne ligne de session enfant existe encore. +Une fois que le runtime ne gère plus la tâche et que la fenêtre de grâce de 5 minutes a expiré, la maintenance peut marquer la tâche comme `lost`. ## Types de planification -| Type | Option CLI | Description | -| ------- | ---------- | ------------------------------------------------------------ | -| `at` | `--at` | Horodatage ponctuel (ISO 8601 ou relatif, comme `20m`) | -| `every` | `--every` | Intervalle fixe | -| `cron` | `--cron` | Expression cron à 5 ou 6 champs avec `--tz` facultatif | +| Type | Option CLI | Description | +| ------- | ---------- | -------------------------------------------------------------- | +| `at` | `--at` | Horodatage à exécution unique (ISO 8601 ou relatif comme `20m`) | +| `every` | `--every` | Intervalle fixe | +| `cron` | `--cron` | Expression cron à 5 ou 6 champs avec `--tz` optionnel | -Les horodatages sans fuseau horaire sont traités comme UTC. Ajoutez `--tz America/New_York` pour une planification selon l’heure locale. +Les horodatages sans fuseau horaire sont traités comme étant en UTC. Ajoutez `--tz America/New_York` pour une planification locale à l’heure murale. -Les expressions récurrentes au début de chaque heure sont automatiquement décalées jusqu’à 5 minutes afin de réduire les pics de charge. Utilisez `--exact` pour imposer un timing précis ou `--stagger 30s` pour une fenêtre explicite. +Les expressions récurrentes au début de chaque heure sont automatiquement décalées jusqu’à 5 minutes pour réduire les pics de charge. Utilisez `--exact` pour imposer un timing précis ou `--stagger 30s` pour une fenêtre explicite. + +### Le jour du mois et le jour de la semaine utilisent une logique OR + +Les expressions cron sont analysées par [croner](https://github.com/Hexagon/croner). Lorsque les champs jour du mois et jour de la semaine ne sont pas des jokers, croner fait correspondre lorsque **l’un ou l’autre** des champs correspond — pas les deux. C’est le comportement standard de Vixie cron. + +``` +# Intention : "9 h le 15, seulement si c'est un lundi" +# Réalité : "9 h chaque 15, ET 9 h chaque lundi" +0 9 15 * 1 +``` + +Cela se déclenche environ 5 à 6 fois par mois au lieu de 0 à 1 fois par mois. OpenClaw utilise ici le comportement OR par défaut de Croner. Pour exiger les deux conditions, utilisez le modificateur jour-de-semaine `+` de Croner (`0 9 15 * +1`) ou planifiez sur un seul champ et vérifiez l’autre dans l’invite ou la commande de votre tâche. ## Styles d’exécution -| Style | Valeur de `--session` | S’exécute dans | Idéal pour | -| ---------------- | --------------------- | ---------------------- | -------------------------------- | -| Session principale | `main` | Prochain tour heartbeat | Rappels, événements système | -| Isolée | `isolated` | `cron:` dédié | Rapports, tâches d’arrière-plan | -| Session actuelle | `current` | Liée au moment de la création | Travail récurrent sensible au contexte | -| Session personnalisée | `session:custom-id` | Session nommée persistante | Workflows qui s’appuient sur l’historique | +| Style | Valeur `--session` | S’exécute dans | Idéal pour | +| --------------- | -------------------- | ------------------------- | --------------------------------- | +| Session principale | `main` | Prochain tour heartbeat | Rappels, événements système | +| Isolé | `isolated` | `cron:` dédié | Rapports, tâches d’arrière-plan | +| Session actuelle | `current` | Liée au moment de la création | Travail récurrent sensible au contexte | +| Session personnalisée | `session:custom-id` | Session nommée persistante | Flux de travail qui s’appuient sur l’historique | -Les tâches en **session principale** mettent en file un événement système et peuvent éventuellement réveiller le heartbeat (`--wake now` ou `--wake next-heartbeat`). Les tâches **isolées** exécutent un tour d’agent dédié avec une nouvelle session. Les **sessions personnalisées** (`session:xxx`) conservent le contexte entre les exécutions, ce qui permet des workflows comme des points quotidiens qui s’appuient sur des résumés précédents. +Les tâches en **session principale** mettent en file un événement système et peuvent éventuellement réveiller le heartbeat (`--wake now` ou `--wake next-heartbeat`). Les tâches **isolées** exécutent un tour d’agent dédié avec une session fraîche. Les **sessions personnalisées** (`session:xxx`) conservent le contexte d’une exécution à l’autre, ce qui permet des flux de travail comme des points quotidiens qui s’appuient sur les résumés précédents. -Pour les tâches isolées, l’arrêt du runtime inclut désormais un nettoyage du navigateur au mieux pour cette session cron. Les échecs de nettoyage sont ignorés afin que le résultat cron réel reste prioritaire. +Pour les tâches isolées, le démontage du runtime inclut désormais un nettoyage du navigateur au mieux pour cette session cron. Les échecs de nettoyage sont ignorés afin que le résultat réel de cron reste prioritaire. -Lorsque des exécutions cron isolées orchestrent des sous-agents, la livraison privilégie également la sortie finale descendante au texte intermédiaire obsolète du parent. Si des descendants sont encore en cours d’exécution, OpenClaw supprime cette mise à jour partielle du parent au lieu de l’annoncer. +Lorsque des exécutions cron isolées orchestrent des sous-agents, la livraison privilégie également la sortie finale descendante plutôt qu’un texte intermédiaire obsolète du parent. Si des descendants sont encore en cours d’exécution, OpenClaw supprime cette mise à jour partielle du parent au lieu de l’annoncer. -### Options de charge utile pour les tâches isolées +### Options de payload pour les tâches isolées -- `--message` : texte du prompt (obligatoire pour les tâches isolées) +- `--message` : texte de l’invite (obligatoire pour l’isolé) - `--model` / `--thinking` : remplacements du modèle et du niveau de réflexion -- `--light-context` : ignorer l’injection des fichiers bootstrap de l’espace de travail -- `--tools exec,read` : limiter les outils que la tâche peut utiliser +- `--light-context` : ignorer l’injection des fichiers d’initialisation du workspace +- `--tools exec,read` : restreindre les outils que la tâche peut utiliser -`--model` utilise le modèle autorisé sélectionné pour cette tâche. Si le modèle demandé n’est pas autorisé, cron enregistre un avertissement et revient à la sélection du modèle de l’agent/par défaut pour la tâche. Les chaînes de repli configurées s’appliquent toujours, mais un simple remplacement de modèle sans liste de repli explicite par tâche n’ajoute plus le modèle principal de l’agent comme cible de nouvelle tentative supplémentaire cachée. +`--model` utilise le modèle autorisé sélectionné pour cette tâche. Si le modèle demandé n’est pas autorisé, cron enregistre un avertissement et revient à la sélection du modèle de l’agent/par défaut pour cette tâche. Les chaînes de repli configurées continuent de s’appliquer, mais un simple remplacement de modèle sans liste de repli explicite par tâche n’ajoute plus le primaire de l’agent comme cible de nouvelle tentative cachée supplémentaire. L’ordre de priorité de sélection du modèle pour les tâches isolées est le suivant : -1. Remplacement de modèle du hook Gmail (lorsque l’exécution vient de Gmail et que ce remplacement est autorisé) -2. `model` de la charge utile par tâche -3. Remplacement du modèle de session cron stocké +1. Remplacement de modèle du hook Gmail (lorsque l’exécution provient de Gmail et que ce remplacement est autorisé) +2. `model` du payload par tâche +3. Remplacement de modèle de session cron stocké 4. Sélection du modèle de l’agent/par défaut -Le mode rapide suit également la sélection active résolue. Si la configuration du modèle sélectionné a `params.fastMode`, cron isolé l’utilise par défaut. Un remplacement `fastMode` de session stocké reste prioritaire sur la configuration dans les deux sens. +Le mode rapide suit aussi la sélection active résolue. Si la configuration du modèle sélectionné a `params.fastMode`, le cron isolé l’utilise par défaut. Un remplacement `fastMode` stocké dans la session reste prioritaire sur la configuration dans les deux sens. -Si une exécution isolée rencontre un transfert en direct de changement de modèle, cron réessaie avec le provider/modèle remplacé et conserve cette sélection active avant de réessayer. Lorsque le changement transporte aussi un nouveau profil d’authentification, cron conserve également ce remplacement de profil d’authentification. Les nouvelles tentatives sont limitées : après la tentative initiale plus 2 nouvelles tentatives de changement, cron abandonne au lieu de boucler indéfiniment. +Si une exécution isolée rencontre un basculement actif de modèle en direct, cron réessaie avec le fournisseur/modèle basculé et persiste cette sélection active avant de réessayer. Lorsque le basculement transporte aussi un nouveau profil d’authentification, cron persiste également ce remplacement de profil d’authentification. Les nouvelles tentatives sont limitées : après la tentative initiale plus 2 nouvelles tentatives de basculement, cron abandonne au lieu de boucler indéfiniment. ## Livraison et sortie -| Mode | Ce qui se passe | -| --------- | --------------------------------------------------------- | -| `announce` | Livre un résumé au canal cible (par défaut pour les tâches isolées) | -| `webhook` | Envoie par POST la charge utile de l’événement terminé vers une URL | -| `none` | Interne uniquement, pas de livraison | +| Mode | Ce qui se passe | +| ---------- | ------------------------------------------------------- | +| `announce` | Livrer le résumé au canal cible (par défaut pour l’isolé) | +| `webhook` | POST du payload d’événement terminé vers une URL | +| `none` | Interne uniquement, pas de livraison | Utilisez `--announce --channel telegram --to "-1001234567890"` pour une livraison vers un canal. Pour les sujets de forum Telegram, utilisez `-1001234567890:topic:123`. Les cibles Slack/Discord/Mattermost doivent utiliser des préfixes explicites (`channel:`, `user:`). -Pour les tâches isolées gérées par cron, le runner gère le chemin final de livraison. L’agent reçoit pour instruction de renvoyer un résumé en texte brut, et ce résumé est ensuite envoyé via `announce`, `webhook`, ou conservé en interne pour `none`. `--no-deliver` ne redonne pas la livraison à l’agent ; il conserve l’exécution en interne. +Pour les tâches isolées gérées par cron, le runner possède le chemin de livraison final. Une invite est envoyée à l’agent pour qu’il renvoie un résumé en texte brut, puis ce résumé est envoyé via `announce`, `webhook` ou conservé en interne pour `none`. `--no-deliver` ne redonne pas la livraison à l’agent ; cela conserve l’exécution en interne. -Si la tâche d’origine indique explicitement d’envoyer un message à un destinataire externe, l’agent doit indiquer dans sa sortie à qui/où ce message doit aller au lieu d’essayer de l’envoyer directement. +Si la tâche d’origine indique explicitement d’envoyer un message à un destinataire externe, l’agent doit indiquer qui/où ce message doit être envoyé dans sa sortie au lieu d’essayer de l’envoyer directement. Les notifications d’échec suivent un chemin de destination distinct : - `cron.failureDestination` définit une valeur par défaut globale pour les notifications d’échec. -- `job.delivery.failureDestination` remplace cela par tâche. -- Si aucun des deux n’est défini et que la tâche livre déjà via `announce`, les notifications d’échec reviennent désormais à cette cible principale `announce`. -- `delivery.failureDestination` est pris en charge uniquement sur les tâches `sessionTarget="isolated"`, sauf si le mode principal de livraison est `webhook`. +- `job.delivery.failureDestination` la remplace par tâche. +- Si aucun des deux n’est défini et que la tâche livre déjà via `announce`, les notifications d’échec reviennent désormais à cette cible d’annonce principale. +- `delivery.failureDestination` n’est pris en charge que sur les tâches `sessionTarget="isolated"` sauf si le mode de livraison principal est `webhook`. ## Exemples CLI -Rappel ponctuel (session principale) : +Rappel à exécution unique (session principale) : ```bash openclaw cron add \ @@ -147,7 +158,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Tâche isolée avec remplacement de modèle et de réflexion : +Tâche isolée avec remplacement du modèle et du niveau de réflexion : ```bash openclaw cron add \ @@ -163,7 +174,7 @@ openclaw cron add \ ## Webhooks -Gateway peut exposer des endpoints webhook HTTP pour des déclencheurs externes. Activez-les dans la configuration : +La Gateway peut exposer des points de terminaison HTTP webhook pour des déclencheurs externes. Activez-les dans la configuration : ```json5 { @@ -177,12 +188,12 @@ Gateway peut exposer des endpoints webhook HTTP pour des déclencheurs externes. ### Authentification -Chaque requête doit inclure le token du hook via un en-tête : +Chaque requête doit inclure le jeton du hook via un en-tête : - `Authorization: Bearer ` (recommandé) - `x-openclaw-token: ` -Les tokens dans la chaîne de requête sont rejetés. +Les jetons dans la chaîne de requête sont rejetés. ### POST /hooks/wake @@ -196,7 +207,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ``` - `text` (obligatoire) : description de l’événement -- `mode` (facultatif) : `now` (par défaut) ou `next-heartbeat` +- `mode` (optionnel) : `now` (par défaut) ou `next-heartbeat` ### POST /hooks/agent @@ -213,35 +224,35 @@ Champs : `message` (obligatoire), `name`, `agentId`, `wakeMode`, `deliver`, `cha ### Hooks mappés (POST /hooks/\) -Les noms de hook personnalisés sont résolus via `hooks.mappings` dans la configuration. Les mappings peuvent transformer des charges utiles arbitraires en actions `wake` ou `agent` avec des modèles ou des transformations par code. +Les noms de hook personnalisés sont résolus via `hooks.mappings` dans la configuration. Les mappings peuvent transformer des payloads arbitraires en actions `wake` ou `agent` avec des modèles ou des transformations par code. ### Sécurité -- Gardez les endpoints de hook derrière loopback, tailnet ou un proxy inverse de confiance. -- Utilisez un token de hook dédié ; ne réutilisez pas les tokens d’authentification du gateway. +- Gardez les points de terminaison de hook derrière loopback, tailnet ou un reverse proxy de confiance. +- Utilisez un jeton de hook dédié ; ne réutilisez pas les jetons d’authentification de gateway. - Gardez `hooks.path` sur un sous-chemin dédié ; `/` est rejeté. -- Définissez `hooks.allowedAgentIds` pour limiter le routage explicite via `agentId`. +- Définissez `hooks.allowedAgentIds` pour limiter le routage explicite `agentId`. - Gardez `hooks.allowRequestSessionKey=false` sauf si vous avez besoin de sessions sélectionnées par l’appelant. -- Si vous activez `hooks.allowRequestSessionKey`, définissez également `hooks.allowedSessionKeyPrefixes` pour contraindre les formes de clés de session autorisées. -- Les charges utiles des hooks sont encapsulées avec des limites de sécurité par défaut. +- Si vous activez `hooks.allowRequestSessionKey`, définissez aussi `hooks.allowedSessionKeyPrefixes` pour contraindre les formes de clés de session autorisées. +- Les payloads de hook sont encapsulés avec des limites de sécurité par défaut. ## Intégration Gmail PubSub Reliez les déclencheurs de boîte de réception Gmail à OpenClaw via Google PubSub. -**Prérequis** : CLI `gcloud`, `gog` (gogcli), hooks OpenClaw activés, Tailscale pour l’endpoint HTTPS public. +**Prérequis** : CLI `gcloud`, `gog` (gogcli), hooks OpenClaw activés, Tailscale pour le point de terminaison HTTPS public. -### Configuration via assistant (recommandée) +### Configuration avec assistant (recommandée) ```bash openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Cela écrit la configuration `hooks.gmail`, active le preset Gmail et utilise Tailscale Funnel pour l’endpoint push. +Cela écrit la configuration `hooks.gmail`, active le preset Gmail et utilise Tailscale Funnel pour le point de terminaison push. -### Démarrage automatique du Gateway +### Démarrage automatique de la Gateway -Lorsque `hooks.enabled=true` et que `hooks.gmail.account` est défini, le Gateway démarre `gog gmail watch serve` au démarrage et renouvelle automatiquement la surveillance. Définissez `OPENCLAW_SKIP_GMAIL_WATCHER=1` pour désactiver cela. +Lorsque `hooks.enabled=true` et que `hooks.gmail.account` est défini, la Gateway démarre `gog gmail watch serve` au démarrage et renouvelle automatiquement le watch. Définissez `OPENCLAW_SKIP_GMAIL_WATCHER=1` pour désactiver ce comportement. ### Configuration manuelle ponctuelle @@ -253,7 +264,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. Créez le topic et accordez l’accès push à Gmail : +2. Créez le topic et accordez à Gmail l’accès push : ```bash gcloud pubsub topics create gog-gmail-watch @@ -262,7 +273,7 @@ gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ --role=roles/pubsub.publisher ``` -3. Démarrez la surveillance : +3. Démarrez le watch : ```bash gog gmail watch start \ @@ -284,7 +295,7 @@ gog gmail watch start \ } ``` -## Gestion des tâches +## Gérer les tâches ```bash # Lister toutes les tâches @@ -293,10 +304,10 @@ openclaw cron list # Modifier une tâche openclaw cron edit --message "Updated prompt" --model "opus" -# Forcer l’exécution immédiate d’une tâche +# Forcer l’exécution d’une tâche maintenant openclaw cron run -# Exécuter seulement si l’échéance est atteinte +# Exécuter uniquement si due openclaw cron run --due # Voir l’historique d’exécution @@ -305,17 +316,17 @@ openclaw cron runs --id --limit 50 # Supprimer une tâche openclaw cron remove -# Sélection d’agent (configurations multi-agents) +# Sélection de l’agent (configurations multi-agents) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` -Remarque sur le remplacement de modèle : +Remarque sur le remplacement du modèle : - `openclaw cron add|edit --model ...` modifie le modèle sélectionné de la tâche. -- Si le modèle est autorisé, ce provider/modèle exact est transmis à l’exécution de l’agent isolé. -- S’il n’est pas autorisé, cron émet un avertissement et revient à la sélection du modèle de l’agent/par défaut pour la tâche. -- Les chaînes de repli configurées s’appliquent toujours, mais un simple remplacement `--model` sans liste de repli explicite par tâche ne retombe plus sur le modèle principal de l’agent comme cible de nouvelle tentative supplémentaire silencieuse. +- Si le modèle est autorisé, ce fournisseur/modèle exact est transmis à l’exécution de l’agent isolé. +- S’il n’est pas autorisé, cron émet un avertissement et revient à la sélection du modèle de l’agent/par défaut de la tâche. +- Les chaînes de repli configurées continuent de s’appliquer, mais un simple remplacement `--model` sans liste de repli explicite par tâche ne bascule plus vers le primaire de l’agent comme cible supplémentaire de nouvelle tentative silencieuse. ## Configuration @@ -339,11 +350,11 @@ Remarque sur le remplacement de modèle : Désactiver cron : `cron.enabled: false` ou `OPENCLAW_SKIP_CRON=1`. -**Nouvelle tentative pour une tâche ponctuelle** : les erreurs temporaires (limite de débit, surcharge, réseau, erreur serveur) sont réessayées jusqu’à 3 fois avec un backoff exponentiel. Les erreurs permanentes désactivent immédiatement la tâche. +**Nouvelle tentative pour exécution unique** : les erreurs transitoires (limitation de débit, surcharge, réseau, erreur serveur) sont retentées jusqu’à 3 fois avec un backoff exponentiel. Les erreurs permanentes sont désactivées immédiatement. -**Nouvelle tentative pour une tâche récurrente** : backoff exponentiel (de 30 s à 60 min) entre les nouvelles tentatives. Le backoff est réinitialisé après la prochaine exécution réussie. +**Nouvelle tentative récurrente** : backoff exponentiel (de 30 s à 60 min) entre les nouvelles tentatives. Le backoff est réinitialisé après la prochaine exécution réussie. -**Maintenance** : `cron.sessionRetention` (par défaut `24h`) supprime les entrées de session d’exécution isolée. `cron.runLog.maxBytes` / `cron.runLog.keepLines` élaguent automatiquement les fichiers journaux d’exécution. +**Maintenance** : `cron.sessionRetention` (par défaut `24h`) purge les entrées de session d’exécution isolée. `cron.runLog.maxBytes` / `cron.runLog.keepLines` purgent automatiquement les fichiers de journal d’exécution. ## Dépannage @@ -363,27 +374,27 @@ openclaw doctor ### Cron ne se déclenche pas - Vérifiez `cron.enabled` et la variable d’environnement `OPENCLAW_SKIP_CRON`. -- Confirmez que le Gateway fonctionne en continu. +- Confirmez que la Gateway fonctionne en continu. - Pour les planifications `cron`, vérifiez le fuseau horaire (`--tz`) par rapport au fuseau horaire de l’hôte. -- `reason: not-due` dans la sortie d’exécution signifie que l’exécution manuelle a été vérifiée avec `openclaw cron run --due` et que l’échéance de la tâche n’était pas encore atteinte. +- `reason: not-due` dans la sortie d’exécution signifie que l’exécution manuelle a été vérifiée avec `openclaw cron run --due` et que la tâche n’était pas encore due. ### Cron s’est déclenché mais aucune livraison - Le mode de livraison `none` signifie qu’aucun message externe n’est attendu. - Une cible de livraison manquante/invalide (`channel`/`to`) signifie que l’envoi sortant a été ignoré. -- Les erreurs d’authentification du canal (`unauthorized`, `Forbidden`) signifient que la livraison a été bloquée par les identifiants. -- Si l’exécution isolée renvoie uniquement le jeton silencieux (`NO_REPLY` / `no_reply`), OpenClaw supprime la livraison sortante directe ainsi que le chemin de résumé mis en file de secours, donc rien n’est renvoyé dans le chat. -- Pour les tâches isolées gérées par cron, ne vous attendez pas à ce que l’agent utilise l’outil de messagerie comme solution de secours. Le runner gère la livraison finale ; `--no-deliver` la conserve en interne au lieu d’autoriser un envoi direct. +- Des erreurs d’authentification du canal (`unauthorized`, `Forbidden`) signifient que la livraison a été bloquée par les identifiants. +- Si l’exécution isolée ne renvoie que le jeton silencieux (`NO_REPLY` / `no_reply`), OpenClaw supprime la livraison sortante directe ainsi que le chemin de résumé mis en file de secours, donc rien n’est renvoyé dans le chat. +- Pour les tâches isolées gérées par cron, n’attendez pas que l’agent utilise l’outil de message comme solution de secours. Le runner gère la livraison finale ; `--no-deliver` la conserve en interne au lieu d’autoriser un envoi direct. ### Pièges liés au fuseau horaire -- Cron sans `--tz` utilise le fuseau horaire de l’hôte du gateway. +- Cron sans `--tz` utilise le fuseau horaire de l’hôte de gateway. - Les planifications `at` sans fuseau horaire sont traitées comme UTC. - `activeHours` de heartbeat utilise la résolution de fuseau horaire configurée. -## Liens associés +## Lié -- [Automatisation et tâches](/fr/automation) — aperçu de tous les mécanismes d’automatisation -- [Tâches en arrière-plan](/fr/automation/tasks) — journal des tâches pour les exécutions cron +- [Automatisation et tâches](/fr/automation) — tous les mécanismes d’automatisation en un coup d’œil +- [Tâches d’arrière-plan](/fr/automation/tasks) — registre des tâches pour les exécutions cron - [Heartbeat](/fr/gateway/heartbeat) — tours périodiques de la session principale - [Fuseau horaire](/fr/concepts/timezone) — configuration du fuseau horaire diff --git a/docs/fr/channels/slack.md b/docs/fr/channels/slack.md index c647d641c..c17b5e32c 100644 --- a/docs/fr/channels/slack.md +++ b/docs/fr/channels/slack.md @@ -4,21 +4,21 @@ read_when: summary: Configuration de Slack et comportement à l’exécution (Socket Mode + URL de requête HTTP) title: Slack x-i18n: - generated_at: "2026-04-08T06:02:06Z" + generated_at: "2026-04-12T06:49:39Z" model: gpt-5.4 provider: openai - source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942 + source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b source_path: channels/slack.md workflow: 15 --- # Slack -Statut : prêt pour la production pour les messages privés et les canaux via les intégrations d’app Slack. Le mode par défaut est Socket Mode ; les URL de requête HTTP sont également prises en charge. +Statut : prêt pour la production pour les messages privés + les canaux via les intégrations d’application Slack. Le mode par défaut est Socket Mode ; les URL de requête HTTP sont également prises en charge. - - Les messages privés Slack utilisent par défaut le mode d’association. + + Les messages privés Slack utilisent par défaut le mode d’appairage. Comportement natif des commandes et catalogue des commandes. @@ -31,15 +31,15 @@ Statut : prêt pour la production pour les messages privés et les canaux via l ## Configuration rapide - + - - Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** : + + Dans les paramètres de l’application Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** : - - choisissez **from a manifest** et sélectionnez un espace de travail pour votre app - - collez le [manifeste d’exemple](#manifest-and-scope-checklist) ci-dessous et continuez pour la créer + - choisissez **from a manifest** et sélectionnez un espace de travail pour votre application + - collez le [manifeste d’exemple](#manifest-and-scope-checklist) ci-dessous, puis poursuivez la création - générez un **App-Level Token** (`xapp-...`) avec `connections:write` - - installez l’app et copiez le **Bot Token** (`xoxb-...`) affiché + - installez l’application et copiez le **Bot Token** (`xoxb-...`) affiché @@ -57,7 +57,7 @@ Statut : prêt pour la production pour les messages privés et les canaux via l } ``` - Variable d’environnement de secours (compte par défaut uniquement) : + Variable d’environnement de secours (compte par défaut uniquement) : ```bash SLACK_APP_TOKEN=xapp-... @@ -77,15 +77,15 @@ openclaw gateway - + - - Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** : + + Dans les paramètres de l’application Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** : - - choisissez **from a manifest** et sélectionnez un espace de travail pour votre app - - collez le [manifeste d’exemple](#manifest-and-scope-checklist) et mettez à jour les URL avant de créer l’app + - choisissez **from a manifest** et sélectionnez un espace de travail pour votre application + - collez le [manifeste d’exemple](#manifest-and-scope-checklist) et mettez à jour les URL avant de créer - enregistrez le **Signing Secret** pour la vérification des requêtes - - installez l’app et copiez le **Bot Token** (`xoxb-...`) affiché + - installez l’application et copiez le **Bot Token** (`xoxb-...`) affiché @@ -125,16 +125,16 @@ openclaw gateway -## Liste de vérification du manifeste et des portées +## Liste de vérification du manifeste et des scopes - + ```json { "display_information": { "name": "OpenClaw", - "description": "Slack connector for OpenClaw" + "description": "Connecteur Slack pour OpenClaw" }, "features": { "bot_user": { @@ -148,7 +148,7 @@ openclaw gateway "slash_commands": [ { "command": "/openclaw", - "description": "Send a message to OpenClaw", + "description": "Envoyer un message à OpenClaw", "should_escape": false } ] @@ -205,13 +205,13 @@ openclaw gateway - + ```json { "display_information": { "name": "OpenClaw", - "description": "Slack connector for OpenClaw" + "description": "Connecteur Slack pour OpenClaw" }, "features": { "bot_user": { @@ -225,7 +225,7 @@ openclaw gateway "slash_commands": [ { "command": "/openclaw", - "description": "Send a message to OpenClaw", + "description": "Envoyer un message à OpenClaw", "should_escape": false, "url": "https://gateway-host.example.com/slack/events" } @@ -289,15 +289,287 @@ openclaw gateway - - - Ajoutez la portée bot `chat:write.customize` si vous souhaitez que les messages sortants utilisent l’identité de l’agent actif (nom d’utilisateur et icône personnalisés) au lieu de l’identité par défaut de l’app Slack. +### Paramètres de manifeste supplémentaires - Si vous utilisez une icône emoji, Slack attend une syntaxe `:emoji_name:`. +Présentez différentes fonctionnalités qui étendent les valeurs par défaut ci-dessus. + + + + + Plusieurs [commandes slash natives](#commands-and-slash-behavior) peuvent être utilisées à la place d’une seule commande configurée, avec quelques subtilités : + + - Utilisez `/agentstatus` au lieu de `/status`, car la commande `/status` est réservée. + - Il n’est pas possible de rendre disponibles plus de 25 commandes slash à la fois. + + Remplacez votre section `features.slash_commands` existante par un sous-ensemble des [commandes disponibles](/fr/tools/slash-commands#command-list) : + + + + +```json + "slash_commands": [ + { + "command": "/new", + "description": "Démarrer une nouvelle session", + "usage_hint": "[model]" + }, + { + "command": "/reset", + "description": "Réinitialiser la session actuelle" + }, + { + "command": "/compact", + "description": "Compacter le contexte de la session", + "usage_hint": "[instructions]" + }, + { + "command": "/stop", + "description": "Arrêter l’exécution en cours" + }, + { + "command": "/session", + "description": "Gérer l’expiration de la liaison de fil", + "usage_hint": "idle or max-age " + }, + { + "command": "/think", + "description": "Définir le niveau de réflexion", + "usage_hint": "" + }, + { + "command": "/verbose", + "description": "Activer ou désactiver la sortie détaillée", + "usage_hint": "on|off|full" + }, + { + "command": "/fast", + "description": "Afficher ou définir le mode rapide", + "usage_hint": "[status|on|off]" + }, + { + "command": "/reasoning", + "description": "Activer ou désactiver la visibilité du raisonnement", + "usage_hint": "[on|off|stream]" + }, + { + "command": "/elevated", + "description": "Activer ou désactiver le mode élevé", + "usage_hint": "[on|off|ask|full]" + }, + { + "command": "/exec", + "description": "Afficher ou définir les valeurs par défaut d’exécution", + "usage_hint": "host= security= ask= node=" + }, + { + "command": "/model", + "description": "Afficher ou définir le modèle", + "usage_hint": "[name|#|status]" + }, + { + "command": "/models", + "description": "Lister les fournisseurs ou les modèles d’un fournisseur", + "usage_hint": "[provider] [page] [limit=|size=|all]" + }, + { + "command": "/help", + "description": "Afficher le résumé d’aide court" + }, + { + "command": "/commands", + "description": "Afficher le catalogue de commandes généré" + }, + { + "command": "/tools", + "description": "Afficher ce que l’agent actuel peut utiliser en ce moment", + "usage_hint": "[compact|verbose]" + }, + { + "command": "/agentstatus", + "description": "Afficher l’état d’exécution, y compris l’utilisation/le quota du fournisseur lorsque disponible" + }, + { + "command": "/tasks", + "description": "Lister les tâches d’arrière-plan actives/récentes pour la session actuelle" + }, + { + "command": "/context", + "description": "Expliquer comment le contexte est assemblé", + "usage_hint": "[list|detail|json]" + }, + { + "command": "/whoami", + "description": "Afficher votre identité d’expéditeur" + }, + { + "command": "/skill", + "description": "Exécuter une compétence par son nom", + "usage_hint": " [input]" + }, + { + "command": "/btw", + "description": "Poser une question secondaire sans modifier le contexte de la session", + "usage_hint": "" + }, + { + "command": "/usage", + "description": "Contrôler le pied de page d’utilisation ou afficher le résumé des coûts", + "usage_hint": "off|tokens|full|cost" + } + ] +``` + + + + +```json + "slash_commands": [ + { + "command": "/new", + "description": "Démarrer une nouvelle session", + "usage_hint": "[model]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/reset", + "description": "Réinitialiser la session actuelle", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/compact", + "description": "Compacter le contexte de la session", + "usage_hint": "[instructions]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/stop", + "description": "Arrêter l’exécution en cours", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/session", + "description": "Gérer l’expiration de la liaison de fil", + "usage_hint": "idle or max-age ", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/think", + "description": "Définir le niveau de réflexion", + "usage_hint": "", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/verbose", + "description": "Activer ou désactiver la sortie détaillée", + "usage_hint": "on|off|full", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/fast", + "description": "Afficher ou définir le mode rapide", + "usage_hint": "[status|on|off]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/reasoning", + "description": "Activer ou désactiver la visibilité du raisonnement", + "usage_hint": "[on|off|stream]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/elevated", + "description": "Activer ou désactiver le mode élevé", + "usage_hint": "[on|off|ask|full]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/exec", + "description": "Afficher ou définir les valeurs par défaut d’exécution", + "usage_hint": "host= security= ask= node=", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/model", + "description": "Afficher ou définir le modèle", + "usage_hint": "[name|#|status]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/models", + "description": "Lister les fournisseurs ou les modèles d’un fournisseur", + "usage_hint": "[provider] [page] [limit=|size=|all]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/help", + "description": "Afficher le résumé d’aide court", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/commands", + "description": "Afficher le catalogue de commandes généré", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/tools", + "description": "Afficher ce que l’agent actuel peut utiliser en ce moment", + "usage_hint": "[compact|verbose]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/agentstatus", + "description": "Afficher l’état d’exécution, y compris l’utilisation/le quota du fournisseur lorsque disponible", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/tasks", + "description": "Lister les tâches d’arrière-plan actives/récentes pour la session actuelle", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/context", + "description": "Expliquer comment le contexte est assemblé", + "usage_hint": "[list|detail|json]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/whoami", + "description": "Afficher votre identité d’expéditeur", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/skill", + "description": "Exécuter une compétence par son nom", + "usage_hint": " [input]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/btw", + "description": "Poser une question secondaire sans modifier le contexte de la session", + "usage_hint": "", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/usage", + "description": "Contrôler le pied de page d’utilisation ou afficher le résumé des coûts", + "usage_hint": "off|tokens|full|cost", + "url": "https://gateway-host.example.com/slack/events" + } + ] +``` + + + - - Si vous configurez `channels.slack.userToken`, les portées de lecture courantes sont : + + Ajoutez le scope bot `chat:write.customize` si vous souhaitez que les messages sortants utilisent l’identité de l’agent actif (nom d’utilisateur et icône personnalisés) au lieu de l’identité par défaut de l’application Slack. + + Si vous utilisez une icône emoji, Slack attend la syntaxe `:emoji_name:`. + + + + Si vous configurez `channels.slack.userToken`, les scopes de lecture typiques sont : - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -310,44 +582,44 @@ openclaw gateway -## Modèle de jeton +## Modèle de jetons - `botToken` + `appToken` sont requis pour Socket Mode. - Le mode HTTP nécessite `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes - en clair ou des objets SecretRef. +- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes en texte brut + ou des objets SecretRef. - Les jetons de config remplacent la variable d’environnement de secours. - La variable d’environnement de secours `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` s’applique uniquement au compte par défaut. -- `userToken` (`xoxp-...`) est uniquement configurable dans la config (pas de variable d’environnement de secours) et adopte par défaut un comportement en lecture seule (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) est uniquement configurable dans la config (pas de variable d’environnement de secours) et utilise par défaut un comportement en lecture seule (`userTokenReadOnly: true`). -Comportement de l’instantané d’état : +Comportement de l’instantané d’état : -- L’inspection du compte Slack suit, pour chaque identifiant, les champs - `*Source` et `*Status` (`botToken`, `appToken`, `signingSecret`, `userToken`). +- L’inspection du compte Slack suit les champs `*Source` et `*Status` + par identifiant (`botToken`, `appToken`, `signingSecret`, `userToken`). - L’état est `available`, `configured_unavailable` ou `missing`. - `configured_unavailable` signifie que le compte est configuré via SecretRef - ou une autre source de secret non inline, mais que le chemin de commande ou - d’exécution actuel n’a pas pu résoudre la valeur réelle. -- En mode HTTP, `signingSecretStatus` est inclus ; en Socket Mode, la + ou une autre source de secret non inline, mais que le chemin de commande/d’exécution actuel + n’a pas pu résoudre la valeur réelle. +- En mode HTTP, `signingSecretStatus` est inclus ; en Socket Mode, la paire requise est `botTokenStatus` + `appTokenStatus`. -Pour les actions et les lectures d’annuaire, le jeton utilisateur peut être préféré lorsqu’il est configuré. Pour les écritures, le jeton bot reste prioritaire ; les écritures avec jeton utilisateur ne sont autorisées que si `userTokenReadOnly: false` et que le jeton bot n’est pas disponible. +Pour les lectures d’actions/répertoires, le jeton utilisateur peut être privilégié lorsqu’il est configuré. Pour les écritures, le jeton bot reste privilégié ; les écritures avec jeton utilisateur ne sont autorisées que lorsque `userTokenReadOnly: false` et que le jeton bot n’est pas disponible. -## Actions et garde-fous +## Actions et contrôles Les actions Slack sont contrôlées par `channels.slack.actions.*`. -Groupes d’actions disponibles dans l’outillage Slack actuel : +Groupes d’actions disponibles dans l’outillage Slack actuel : -| Groupe | Par défaut | -| ---------- | ---------- | -| messages | activé | -| reactions | activé | -| pins | activé | -| memberInfo | activé | -| emojiList | activé | +| Group | Default | +| ---------- | ------- | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | Les actions de message Slack actuelles incluent `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` et `emoji-list`. @@ -355,60 +627,60 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download - `channels.slack.dmPolicy` contrôle l’accès aux messages privés (hérité : `channels.slack.dm.policy`) : + `channels.slack.dmPolicy` contrôle l’accès aux messages privés (héritage : `channels.slack.dm.policy`) : - `pairing` (par défaut) - `allowlist` - - `open` (nécessite que `channels.slack.allowFrom` inclue `"*"` ; hérité : `channels.slack.dm.allowFrom`) + - `open` (nécessite que `channels.slack.allowFrom` inclue `"*"` ; héritage : `channels.slack.dm.allowFrom`) - `disabled` - Indicateurs des messages privés : + Indicateurs de messages privés : - `dm.enabled` (true par défaut) - `channels.slack.allowFrom` (préféré) - - `dm.allowFrom` (hérité) - - `dm.groupEnabled` (messages privés de groupe désactivés par défaut) + - `dm.allowFrom` (héritage) + - `dm.groupEnabled` (messages privés de groupe false par défaut) - `dm.groupChannels` (liste d’autorisation MPIM facultative) - Priorité multi-compte : + Priorité multi-compte : - `channels.slack.accounts.default.allowFrom` s’applique uniquement au compte `default`. - Les comptes nommés héritent de `channels.slack.allowFrom` lorsque leur propre `allowFrom` n’est pas défini. - Les comptes nommés n’héritent pas de `channels.slack.accounts.default.allowFrom`. - L’association dans les messages privés utilise `openclaw pairing approve slack `. + L’appairage dans les messages privés utilise `openclaw pairing approve slack `. - `channels.slack.groupPolicy` contrôle la gestion des canaux : + `channels.slack.groupPolicy` contrôle la gestion des canaux : - `open` - `allowlist` - `disabled` - La liste d’autorisation des canaux se trouve sous `channels.slack.channels` et doit utiliser des ID de canal stables. + La liste d’autorisation des canaux se trouve sous `channels.slack.channels` et doit utiliser des identifiants de canal stables. - Remarque d’exécution : si `channels.slack` est totalement absent (configuration via variables d’environnement uniquement), l’exécution utilise `groupPolicy="allowlist"` comme repli et journalise un avertissement (même si `channels.defaults.groupPolicy` est défini). + Note d’exécution : si `channels.slack` est complètement absent (configuration par variables d’environnement uniquement), l’exécution revient à `groupPolicy="allowlist"` et journalise un avertissement (même si `channels.defaults.groupPolicy` est défini). - Résolution nom/ID : + Résolution nom/ID : - - les entrées de liste d’autorisation de canal et de messages privés sont résolues au démarrage lorsque l’accès par jeton le permet - - les entrées de nom de canal non résolues sont conservées telles que configurées, mais ignorées par défaut pour le routage - - l’autorisation entrante et le routage des canaux reposent d’abord sur les ID par défaut ; la correspondance directe sur nom d’utilisateur/slug nécessite `channels.slack.dangerouslyAllowNameMatching: true` + - les entrées de liste d’autorisation de canaux et les entrées de liste d’autorisation de messages privés sont résolues au démarrage lorsque l’accès au jeton le permet + - les entrées de nom de canal non résolues sont conservées telles que configurées mais ignorées pour le routage par défaut + - l’autorisation entrante et le routage des canaux utilisent par défaut les ID en priorité ; la correspondance directe sur nom d’utilisateur/slug nécessite `channels.slack.dangerouslyAllowNameMatching: true` - Les messages de canal sont soumis par défaut à un garde-fou sur les mentions. + Les messages de canal sont contrôlés par mention par défaut. - Sources de mention : + Sources de mention : - - mention explicite de l’app (`<@botId>`) - - motifs regex de mention (`agents.list[].groupChat.mentionPatterns`, avec repli sur `messages.groupChat.mentionPatterns`) - - comportement implicite de réponse dans le fil au bot (désactivé lorsque `thread.requireExplicitMention` vaut `true`) + - mention explicite de l’application (`<@botId>`) + - motifs regex de mention (`agents.list[].groupChat.mentionPatterns`, repli sur `messages.groupChat.mentionPatterns`) + - comportement implicite de réponse à un fil du bot (désactivé lorsque `thread.requireExplicitMention` est `true`) - Contrôles par canal (`channels.slack.channels.` ; noms uniquement via résolution au démarrage ou `dangerouslyAllowNameMatching`) : + Contrôles par canal (`channels.slack.channels.` ; noms uniquement via résolution au démarrage ou `dangerouslyAllowNameMatching`) : - `requireMention` - `users` (liste d’autorisation) @@ -416,7 +688,7 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - format de clé `toolsBySender` : `id:`, `e164:`, `username:`, `name:` ou joker `"*"` + - format de clé `toolsBySender` : `id:`, `e164:`, `username:`, `name:` ou joker `"*"` (les clés héritées sans préfixe sont toujours mappées uniquement vers `id:`) @@ -424,61 +696,61 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download ## Fils, sessions et balises de réponse -- Les messages privés sont routés comme `direct` ; les canaux comme `channel` ; les MPIM comme `group`. +- Les messages privés sont routés comme `direct` ; les canaux comme `channel` ; les MPIM comme `group`. - Avec la valeur par défaut `session.dmScope=main`, les messages privés Slack sont regroupés dans la session principale de l’agent. -- Sessions de canal : `agent::slack:channel:`. -- Les réponses dans les fils peuvent créer des suffixes de session de fil (`:thread:`) lorsque c’est applicable. -- La valeur par défaut de `channels.slack.thread.historyScope` est `thread` ; celle de `thread.inheritParent` est `false`. -- `channels.slack.thread.initialHistoryLimit` contrôle le nombre de messages existants du fil récupérés au démarrage d’une nouvelle session de fil (valeur par défaut `20` ; définissez `0` pour désactiver). -- `channels.slack.thread.requireExplicitMention` (par défaut `false`) : quand `true`, supprime les mentions implicites dans les fils afin que le bot ne réponde qu’aux mentions explicites `@bot` dans les fils, même s’il a déjà participé au fil. Sans cela, les réponses dans un fil auquel le bot a participé contournent le garde-fou `requireMention`. +- Sessions de canal : `agent::slack:channel:`. +- Les réponses dans les fils peuvent créer des suffixes de session de fil (`:thread:`) lorsque cela s’applique. +- La valeur par défaut de `channels.slack.thread.historyScope` est `thread` ; la valeur par défaut de `thread.inheritParent` est `false`. +- `channels.slack.thread.initialHistoryLimit` contrôle le nombre de messages de fil existants récupérés lorsqu’une nouvelle session de fil démarre (valeur par défaut `20` ; définissez `0` pour désactiver). +- `channels.slack.thread.requireExplicitMention` (par défaut `false`) : lorsque `true`, supprime les mentions implicites dans les fils afin que le bot ne réponde qu’aux mentions explicites `@bot` à l’intérieur des fils, même lorsque le bot a déjà participé au fil. Sans cela, les réponses dans un fil auquel le bot a participé contournent le contrôle `requireMention`. -Contrôles de fil de réponse : +Contrôles de fil de réponse : - `channels.slack.replyToMode`: `off|first|all|batched` (par défaut `off`) - `channels.slack.replyToModeByChatType`: par `direct|group|channel` -- repli hérité pour les discussions directes : `channels.slack.dm.replyToMode` +- repli hérité pour les discussions directes : `channels.slack.dm.replyToMode` -Les balises de réponse manuelle sont prises en charge : +Les balises de réponse manuelles sont prises en charge : - `[[reply_to_current]]` - `[[reply_to:]]` -Remarque : `replyToMode="off"` désactive **tout** le fil de réponse dans Slack, y compris les balises explicites `[[reply_to_*]]`. Cela diffère de Telegram, où les balises explicites sont toujours respectées en mode `"off"`. Cette différence reflète les modèles de fil propres aux plateformes : dans Slack, les fils masquent les messages du canal, tandis que dans Telegram, les réponses restent visibles dans le flux principal de discussion. +Remarque : `replyToMode="off"` désactive **tout** le fil de réponse dans Slack, y compris les balises explicites `[[reply_to_*]]`. Cela diffère de Telegram, où les balises explicites sont toujours honorées en mode `"off"`. La différence reflète les modèles de fil des plateformes : les fils Slack masquent les messages du canal, tandis que les réponses Telegram restent visibles dans le flux principal de discussion. ## Réactions d’accusé de réception `ackReaction` envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant. -Ordre de résolution : +Ordre de résolution : - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀") +- repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon `"👀"`) -Remarques : +Remarques : - Slack attend des shortcodes (par exemple `"eyes"`). - Utilisez `""` pour désactiver la réaction pour le compte Slack ou globalement. ## Streaming de texte -`channels.slack.streaming` contrôle le comportement de l’aperçu en direct : +`channels.slack.streaming` contrôle le comportement d’aperçu en direct : -- `off` : désactiver le streaming de l’aperçu en direct. -- `partial` (par défaut) : remplacer le texte d’aperçu par la dernière sortie partielle. -- `block` : ajouter des mises à jour d’aperçu par blocs. -- `progress` : afficher un texte de progression pendant la génération, puis envoyer le texte final. +- `off` : désactiver le streaming d’aperçu en direct. +- `partial` (par défaut) : remplacer le texte d’aperçu par la dernière sortie partielle. +- `block` : ajouter des mises à jour d’aperçu par blocs. +- `progress` : afficher un texte d’état de progression pendant la génération, puis envoyer le texte final. -`channels.slack.streaming.nativeTransport` contrôle le streaming de texte natif Slack lorsque `channels.slack.streaming.mode` vaut `partial` (par défaut : `true`). +`channels.slack.streaming.nativeTransport` contrôle le streaming de texte natif de Slack lorsque `channels.slack.streaming.mode` est `partial` (par défaut : `true`). -- Un fil de réponse doit être disponible pour que le streaming de texte natif et l’état du fil assistant Slack s’affichent. La sélection du fil continue toutefois de suivre `replyToMode`. -- Les racines de canaux et de discussions de groupe peuvent toujours utiliser l’aperçu brouillon normal lorsque le streaming natif n’est pas disponible. -- Les messages privés Slack de niveau supérieur restent hors fil par défaut, ils n’affichent donc pas l’aperçu de style fil ; utilisez des réponses en fil ou `typingReaction` si vous souhaitez y afficher une progression visible. +- Un fil de réponse doit être disponible pour que le streaming de texte natif et l’état du fil assistant Slack apparaissent. La sélection du fil suit toujours `replyToMode`. +- Les racines de canaux et de discussions de groupe peuvent toujours utiliser l’aperçu de brouillon normal lorsque le streaming natif n’est pas disponible. +- Les messages privés Slack de niveau supérieur restent hors fil par défaut ; ils n’affichent donc pas l’aperçu de style fil. Utilisez des réponses dans des fils ou `typingReaction` si vous souhaitez y afficher une progression visible. - Les médias et les charges utiles non textuelles reviennent à la livraison normale. -- Si le streaming échoue en cours de réponse, OpenClaw revient à la livraison normale pour les charges utiles restantes. +- Si le streaming échoue au milieu d’une réponse, OpenClaw revient à la livraison normale pour les charges utiles restantes. -Utiliser l’aperçu brouillon au lieu du streaming de texte natif Slack : +Utiliser l’aperçu de brouillon au lieu du streaming de texte natif de Slack : ```json5 { @@ -493,25 +765,25 @@ Utiliser l’aperçu brouillon au lieu du streaming de texte natif Slack : } ``` -Clés héritées : +Clés héritées : - `channels.slack.streamMode` (`replace | status_final | append`) est migré automatiquement vers `channels.slack.streaming.mode`. - le booléen `channels.slack.streaming` est migré automatiquement vers `channels.slack.streaming.mode` et `channels.slack.streaming.nativeTransport`. -- la clé héritée `channels.slack.nativeStreaming` est migrée automatiquement vers `channels.slack.streaming.nativeTransport`. +- l’ancienne clé `channels.slack.nativeStreaming` est migrée automatiquement vers `channels.slack.streaming.nativeTransport`. -## Repli de réaction de saisie +## Repli avec réaction de saisie -`typingReaction` ajoute une réaction temporaire au message Slack entrant pendant qu’OpenClaw traite une réponse, puis la retire à la fin de l’exécution. C’est surtout utile hors des réponses en fil, qui utilisent un indicateur d’état par défaut « is typing... ». +`typingReaction` ajoute une réaction temporaire au message Slack entrant pendant qu’OpenClaw traite une réponse, puis la supprime lorsque l’exécution se termine. Cela est particulièrement utile en dehors des réponses dans des fils, qui utilisent un indicateur d’état par défaut « is typing... ». -Ordre de résolution : +Ordre de résolution : - `channels.slack.accounts..typingReaction` - `channels.slack.typingReaction` -Remarques : +Remarques : - Slack attend des shortcodes (par exemple `"hourglass_flowing_sand"`). -- La réaction est appliquée au mieux et son nettoyage est tenté automatiquement une fois la réponse ou le chemin d’échec terminé. +- La réaction est effectuée au mieux, et le nettoyage est tenté automatiquement une fois la réponse envoyée ou en cas d’échec. ## Médias, découpage et livraison @@ -519,19 +791,19 @@ Remarques : Les pièces jointes Slack sont téléchargées depuis des URL privées hébergées par Slack (flux de requêtes authentifiées par jeton) et écrites dans le stockage média lorsque la récupération réussit et que les limites de taille le permettent. - Le plafond de taille entrante à l’exécution est de `20MB` par défaut, sauf remplacement par `channels.slack.mediaMaxMb`. + Le plafond de taille d’entrée à l’exécution est de `20MB` par défaut, sauf remplacement par `channels.slack.mediaMaxMb`. - - les blocs de texte utilisent `channels.slack.textChunkLimit` (valeur par défaut 4000) - - `channels.slack.chunkMode="newline"` active un découpage privilégiant d’abord les paragraphes - - les envois de fichiers utilisent les API d’upload Slack et peuvent inclure des réponses en fil (`thread_ts`) - - le plafond média sortant suit `channels.slack.mediaMaxMb` lorsqu’il est configuré ; sinon, les envois par canal utilisent les valeurs par défaut par type MIME du pipeline média + - les morceaux de texte utilisent `channels.slack.textChunkLimit` (par défaut 4000) + - `channels.slack.chunkMode="newline"` active le découpage prioritairement par paragraphe + - les envois de fichiers utilisent les API d’upload Slack et peuvent inclure des réponses dans des fils (`thread_ts`) + - le plafond média sortant suit `channels.slack.mediaMaxMb` lorsqu’il est configuré ; sinon, les envois de canal utilisent les valeurs par défaut par type MIME du pipeline média - Cibles explicites préférées : + Cibles explicites préférées : - `user:` pour les messages privés - `channel:` pour les canaux @@ -541,38 +813,45 @@ Remarques : -## Commandes et comportement des slash commands +## Commandes et comportement des commandes slash -- Le mode automatique des commandes natives est **désactivé** pour Slack (`commands.native: "auto"` n’active pas les commandes natives Slack). -- Activez les gestionnaires de commandes Slack natives avec `channels.slack.commands.native: true` (ou globalement `commands.native: true`). -- Lorsque les commandes natives sont activées, enregistrez les slash commands correspondantes dans Slack (noms `/`), avec une exception : - - enregistrez `/agentstatus` pour la commande d’état (Slack réserve `/status`) -- Si les commandes natives ne sont pas activées, vous pouvez exécuter une seule slash command configurée via `channels.slack.slashCommand`. -- Les menus d’arguments natifs adaptent désormais leur stratégie de rendu : - - jusqu’à 5 options : blocs de boutons - - 6 à 100 options : menu de sélection statique - - plus de 100 options : sélection externe avec filtrage asynchrone des options lorsque des gestionnaires d’options d’interactivité sont disponibles - - si les valeurs d’option encodées dépassent les limites de Slack, le flux revient aux boutons -- Pour les longues charges utiles d’options, les menus d’arguments des slash commands utilisent une boîte de dialogue de confirmation avant d’envoyer une valeur sélectionnée. - -Paramètres par défaut des slash commands : +Les commandes slash apparaissent dans Slack soit comme une seule commande configurée, soit comme plusieurs commandes natives. Configurez `channels.slack.slashCommand` pour modifier les valeurs par défaut des commandes : - `enabled: false` - `name: "openclaw"` - `sessionPrefix: "slack:slash"` - `ephemeral: true` -Les sessions slash utilisent des clés isolées : +```txt +/openclaw /help +``` -- `agent::slack:slash:` +Les commandes natives nécessitent des [paramètres de manifeste supplémentaires](#additional-manifest-settings) dans votre application Slack et sont activées avec `channels.slack.commands.native: true` ou `commands.native: true` dans les configurations globales. -et continuent malgré tout à router l’exécution de la commande vers la session de conversation cible (`CommandTargetSessionKey`). +- Le mode automatique des commandes natives est **désactivé** pour Slack, donc `commands.native: "auto"` n’active pas les commandes natives Slack. + +```txt +/help +``` + +Les menus d’arguments natifs utilisent une stratégie de rendu adaptative qui affiche une fenêtre modale de confirmation avant d’envoyer la valeur d’option sélectionnée : + +- jusqu’à 5 options : blocs de boutons +- de 6 à 100 options : menu de sélection statique +- plus de 100 options : sélection externe avec filtrage asynchrone des options lorsque des gestionnaires d’options d’interactivité sont disponibles +- limites Slack dépassées : les valeurs d’option encodées reviennent à des boutons + +```txt +/think +``` + +Les sessions de commandes slash utilisent des clés isolées comme `agent::slack:slash:` et continuent à router les exécutions de commandes vers la session de conversation cible en utilisant `CommandTargetSessionKey`. ## Réponses interactives Slack peut afficher des contrôles de réponse interactive rédigés par l’agent, mais cette fonctionnalité est désactivée par défaut. -L’activer globalement : +L’activer globalement : ```json5 { @@ -586,7 +865,7 @@ L’activer globalement : } ``` -Ou l’activer pour un seul compte Slack : +Ou l’activer pour un seul compte Slack : ```json5 { @@ -604,44 +883,44 @@ Ou l’activer pour un seul compte Slack : } ``` -Lorsque cette fonctionnalité est activée, les agents peuvent émettre des directives de réponse réservées à Slack : +Lorsqu’elle est activée, les agents peuvent émettre des directives de réponse propres à Slack : - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Ces directives sont compilées en Slack Block Kit et les clics ou sélections sont renvoyés via le chemin d’événement d’interaction Slack existant. +Ces directives sont compilées en Slack Block Kit et renvoient les clics ou sélections via le chemin d’événements d’interaction Slack existant. -Remarques : +Remarques : -- Il s’agit d’une UI spécifique à Slack. Les autres canaux ne traduisent pas les directives Slack Block Kit vers leurs propres systèmes de boutons. +- Il s’agit d’une interface propre à Slack. Les autres canaux ne traduisent pas les directives Slack Block Kit dans leurs propres systèmes de boutons. - Les valeurs de rappel interactif sont des jetons opaques générés par OpenClaw, et non des valeurs brutes rédigées par l’agent. - Si les blocs interactifs générés dépassent les limites de Slack Block Kit, OpenClaw revient à la réponse texte d’origine au lieu d’envoyer une charge utile de blocs invalide. ## Approbations exec dans Slack -Slack peut agir comme client d’approbation natif avec des boutons interactifs et des interactions, au lieu de revenir à la Web UI ou au terminal. +Slack peut agir comme un client d’approbation natif avec boutons interactifs et interactions, au lieu de revenir à l’interface Web ou au terminal. - Les approbations exec utilisent `channels.slack.execApprovals.*` pour le routage natif en message privé/canal. -- Les approbations de plugin peuvent toujours être résolues via la même surface de boutons native Slack lorsque la demande arrive déjà dans Slack et que le type d’ID d’approbation est `plugin:`. -- L’autorisation des approbateurs reste appliquée : seuls les utilisateurs identifiés comme approbateurs peuvent approuver ou refuser des demandes via Slack. +- Les approbations de plugin peuvent toujours être résolues via la même surface de boutons native Slack lorsque la demande arrive déjà dans Slack et que le type d’identifiant d’approbation est `plugin:`. +- L’autorisation des approbateurs est toujours appliquée : seuls les utilisateurs identifiés comme approbateurs peuvent approuver ou refuser des demandes via Slack. -Cela utilise la même surface partagée de boutons d’approbation que les autres canaux. Lorsque `interactivity` est activé dans les paramètres de votre app Slack, les invites d’approbation s’affichent directement sous forme de boutons Block Kit dans la conversation. -Lorsque ces boutons sont présents, ils constituent l’UX d’approbation principale ; OpenClaw -ne devrait inclure une commande manuelle `/approve` que lorsque le résultat de l’outil indique que les -approbations par discussion ne sont pas disponibles ou que l’approbation manuelle est la seule voie. +Cela utilise la même surface de boutons d’approbation partagée que les autres canaux. Lorsque `interactivity` est activé dans les paramètres de votre application Slack, les invites d’approbation s’affichent comme des boutons Block Kit directement dans la conversation. +Lorsque ces boutons sont présents, ils constituent l’expérience utilisateur d’approbation principale ; OpenClaw +ne doit inclure une commande manuelle `/approve` que lorsque le résultat de l’outil indique que les +approbations par chat ne sont pas disponibles ou que l’approbation manuelle est la seule voie possible. -Chemin de configuration : +Chemin de config : - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (facultatif ; utilise `commands.ownerAllowFrom` comme repli lorsque possible) -- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, valeur par défaut : `dm`) +- `channels.slack.execApprovals.approvers` (facultatif ; revient à `commands.ownerAllowFrom` lorsque possible) +- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, par défaut : `dm`) - `agentFilter`, `sessionFilter` Slack active automatiquement les approbations exec natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un approbateur est résolu. Définissez `enabled: false` pour désactiver explicitement Slack comme client d’approbation natif. -Définissez `enabled: true` pour forcer les approbations natives lorsque des approbateurs sont résolus. +Définissez `enabled: true` pour forcer l’activation des approbations natives lorsque des approbateurs sont résolus. -Comportement par défaut sans configuration explicite d’approbation exec Slack : +Comportement par défaut sans configuration explicite des approbations exec Slack : ```json5 { @@ -651,8 +930,8 @@ Comportement par défaut sans configuration explicite d’approbation exec Slack } ``` -Une configuration native Slack explicite n’est nécessaire que si vous souhaitez remplacer les approbateurs, ajouter des filtres, ou -opter pour une livraison vers la discussion d’origine : +Une configuration native Slack explicite n’est nécessaire que lorsque vous souhaitez remplacer les approbateurs, ajouter des filtres ou +opter pour la livraison dans le chat d’origine : ```json5 { @@ -670,50 +949,50 @@ opter pour une livraison vers la discussion d’origine : Le transfert partagé `approvals.exec` est distinct. Utilisez-le uniquement lorsque les invites d’approbation exec doivent aussi être routées vers d’autres discussions ou des cibles explicites hors bande. Le transfert partagé `approvals.plugin` est également -distinct ; les boutons natifs Slack peuvent toujours résoudre les approbations de plugin lorsque ces demandes arrivent déjà +distinct ; les boutons natifs Slack peuvent toujours résoudre les approbations de plugin lorsque ces demandes arrivent déjà dans Slack. -`/approve` dans la même discussion fonctionne aussi dans les canaux et messages privés Slack qui prennent déjà en charge les commandes. Voir [Approbations exec](/fr/tools/exec-approvals) pour le modèle complet de transfert des approbations. +La commande `/approve` dans le même chat fonctionne aussi dans les canaux et messages privés Slack qui prennent déjà en charge les commandes. Voir [Approbations exec](/fr/tools/exec-approvals) pour le modèle complet de transfert des approbations. ## Événements et comportement opérationnel -- Les modifications/suppressions de messages et les diffusions de fil sont mappées en événements système. -- Les événements d’ajout/suppression de réaction sont mappés en événements système. -- Les événements d’arrivée/départ de membre, de création/renommage de canal et d’ajout/suppression d’épingle sont mappés en événements système. +- Les modifications/suppressions de messages et les diffusions de fils sont mappées en événements système. +- Les événements d’ajout/suppression de réactions sont mappés en événements système. +- Les événements de jonction/départ de membres, de création/renommage de canaux et d’ajout/suppression d’épingles sont mappés en événements système. - `channel_id_changed` peut migrer les clés de configuration de canal lorsque `configWrites` est activé. -- Les métadonnées de sujet/objectifs de canal sont traitées comme un contexte non fiable et peuvent être injectées dans le contexte de routage. -- Le message initial du fil et l’amorçage initial du contexte d’historique du fil sont filtrés selon les listes d’autorisation d’expéditeur configurées, lorsque applicable. -- Les actions de bloc et les interactions modales émettent des événements système structurés `Slack interaction: ...` avec des champs riches de charge utile : - - actions de bloc : valeurs sélectionnées, libellés, valeurs du sélecteur et métadonnées `workflow_*` +- Les métadonnées de sujet/objectif de canal sont traitées comme un contexte non fiable et peuvent être injectées dans le contexte de routage. +- L’auteur du fil et l’initialisation du contexte d’historique du fil sont filtrés par les listes d’autorisation d’expéditeurs configurées lorsque cela s’applique. +- Les actions de bloc et interactions modales émettent des événements système structurés `Slack interaction: ...` avec des champs de charge utile riches : + - actions de bloc : valeurs sélectionnées, libellés, valeurs de sélecteur et métadonnées `workflow_*` - événements modaux `view_submission` et `view_closed` avec métadonnées de canal routées et entrées de formulaire -## Pointeurs vers la référence de configuration +## Pointeurs de référence de configuration -Référence principale : +Référence principale : - [Référence de configuration - Slack](/fr/gateway/configuration-reference#slack) - Champs Slack à fort signal : - - mode/auth : `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - - accès aux messages privés : `dm.enabled`, `dmPolicy`, `allowFrom` (hérité : `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - option de compatibilité : `dangerouslyAllowNameMatching` (dernier recours ; laissez-la désactivée sauf nécessité) - - accès aux canaux : `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - - fils/historique : `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - - livraison : `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` - - opérations/fonctionnalités : `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` + Champs Slack à fort signal : + - mode/auth : `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + - accès DM : `dm.enabled`, `dmPolicy`, `allowFrom` (héritage : `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` + - interrupteur de compatibilité : `dangerouslyAllowNameMatching` (option de dernier recours ; laissez-le désactivé sauf nécessité) + - accès aux canaux : `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - fils/historique : `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` + - livraison : `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` + - opérations/fonctionnalités : `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## Dépannage - Vérifiez, dans l’ordre : + Vérifiez, dans l’ordre : - `groupPolicy` - liste d’autorisation des canaux (`channels.slack.channels`) - `requireMention` - liste d’autorisation `users` par canal - Commandes utiles : + Commandes utiles : ```bash openclaw channels status --probe @@ -724,11 +1003,11 @@ openclaw doctor - Vérifiez : + Vérifiez : - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (ou l’hérité `channels.slack.dm.policy`) - - approbations d’association / entrées de liste d’autorisation + - `channels.slack.dmPolicy` (ou l’ancienne clé `channels.slack.dm.policy`) + - approbations d’appairage / entrées de liste d’autorisation ```bash openclaw pairing list slack @@ -737,43 +1016,43 @@ openclaw pairing list slack - Validez les jetons bot + app et l’activation de Socket Mode dans les paramètres de l’app Slack. + Validez les jetons bot + app et l’activation de Socket Mode dans les paramètres de l’application Slack. Si `openclaw channels status --probe --json` affiche `botTokenStatus` ou `appTokenStatus: "configured_unavailable"`, le compte Slack est - configuré mais l’exécution actuelle n’a pas pu résoudre la valeur - fournie via SecretRef. + configuré, mais l’exécution actuelle n’a pas pu résoudre la + valeur adossée à SecretRef. - Validez : + Validez : - signing secret - - chemin webhook - - URL de requête Slack (Events + Interactivity + Slash Commands) + - chemin de webhook + - URL de requête Slack (événements + interactivité + commandes slash) - `webhookPath` unique par compte HTTP - Si `signingSecretStatus: "configured_unavailable"` apparaît dans les - instantanés de compte, le compte HTTP est configuré mais l’exécution actuelle n’a pas pu - résoudre le signing secret fourni via SecretRef. + Si `signingSecretStatus: "configured_unavailable"` apparaît dans les instantanés de compte, + le compte HTTP est configuré, mais l’exécution actuelle n’a pas pu + résoudre le signing secret adossé à SecretRef. - Vérifiez ce que vous vouliez utiliser : + Vérifiez si vous vouliez : - - le mode de commande native (`channels.slack.commands.native: true`) avec les slash commands correspondantes enregistrées dans Slack - - ou le mode de commande slash unique (`channels.slack.slashCommand.enabled: true`) + - le mode de commandes natives (`channels.slack.commands.native: true`) avec les commandes slash correspondantes enregistrées dans Slack + - ou le mode à commande slash unique (`channels.slack.slashCommand.enabled: true`) - Vérifiez également `commands.useAccessGroups` et les listes d’autorisation de canaux/utilisateurs. + Vérifiez également `commands.useAccessGroups` ainsi que les listes d’autorisation de canaux/utilisateurs. -## Liens connexes +## Associé -- [Association](/fr/channels/pairing) +- [Appairage](/fr/channels/pairing) - [Groupes](/fr/channels/groups) - [Sécurité](/fr/gateway/security) - [Routage des canaux](/fr/channels/channel-routing) diff --git a/docs/fr/concepts/active-memory.md b/docs/fr/concepts/active-memory.md index 01cf439fc..b596cd90a 100644 --- a/docs/fr/concepts/active-memory.md +++ b/docs/fr/concepts/active-memory.md @@ -6,22 +6,22 @@ read_when: summary: Un sous-agent de mémoire bloquante appartenant au plugin qui injecte la mémoire pertinente dans les sessions de chat interactives title: Mémoire active x-i18n: - generated_at: "2026-04-11T06:40:23Z" + generated_at: "2026-04-12T06:49:37Z" model: gpt-5.4 provider: openai - source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5 + source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84 source_path: concepts/active-memory.md workflow: 15 --- # Mémoire active -La mémoire active est un sous-agent de mémoire bloquant optionnel appartenant au plugin qui s’exécute +La mémoire active est un sous-agent de mémoire bloquante optionnel appartenant au plugin qui s’exécute avant la réponse principale pour les sessions conversationnelles éligibles. -Elle existe parce que la plupart des systèmes de mémoire sont capables mais réactifs. Ils s’appuient sur +Elle existe parce que la plupart des systèmes de mémoire sont performants, mais réactifs. Ils s’appuient sur l’agent principal pour décider quand rechercher dans la mémoire, ou sur l’utilisateur pour dire des choses -comme « souviens-toi de ceci » ou « recherche dans la mémoire ». À ce stade, le moment où la mémoire aurait +comme « souviens-toi de ceci » ou « cherche dans la mémoire ». À ce moment-là, l’instant où la mémoire aurait rendu la réponse naturelle est déjà passé. La mémoire active donne au système une occasion limitée de faire remonter une mémoire pertinente @@ -30,7 +30,7 @@ avant que la réponse principale ne soit générée. ## Collez ceci dans votre agent Collez ceci dans votre agent si vous voulez activer la mémoire active avec une -configuration autonome et sûre par défaut : +configuration autonome et sûre par défaut : ```json5 { @@ -42,7 +42,7 @@ configuration autonome et sûre par défaut : enabled: true, agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -57,16 +57,16 @@ configuration autonome et sûre par défaut : ``` Cela active le plugin pour l’agent `main`, le limite par défaut aux sessions -de type message direct, lui permet d’hériter d’abord du modèle de la session en cours, -et autorise toujours le fallback distant intégré si aucun modèle explicite ou hérité n’est disponible. +de type message direct, lui permet d’hériter d’abord du modèle de la session en cours, et +utilise le modèle de secours configuré uniquement si aucun modèle explicite ou hérité n’est disponible. -Après cela, redémarrez la passerelle : +Ensuite, redémarrez la passerelle : ```bash openclaw gateway ``` -Pour l’inspecter en direct dans une conversation : +Pour l’inspecter en direct dans une conversation : ```text /verbose on @@ -74,13 +74,13 @@ Pour l’inspecter en direct dans une conversation : ## Activer la mémoire active -La configuration la plus sûre est : +La configuration la plus sûre est la suivante : 1. activer le plugin 2. cibler un agent conversationnel -3. garder la journalisation activée uniquement pendant le réglage +3. laisser la journalisation activée uniquement pendant le réglage -Commencez par ceci dans `openclaw.json` : +Commencez avec ceci dans `openclaw.json` : ```json5 { @@ -91,7 +91,7 @@ Commencez par ceci dans `openclaw.json` : config: { agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -105,23 +105,23 @@ Commencez par ceci dans `openclaw.json` : } ``` -Redémarrez ensuite la passerelle : +Puis redémarrez la passerelle : ```bash openclaw gateway ``` -Ce que cela signifie : +Ce que cela signifie : - `plugins.entries.active-memory.enabled: true` active le plugin - `config.agents: ["main"]` n’active la mémoire active que pour l’agent `main` - `config.allowedChatTypes: ["direct"]` limite par défaut la mémoire active aux sessions de type message direct - si `config.model` n’est pas défini, la mémoire active hérite d’abord du modèle de la session en cours -- `config.modelFallbackPolicy: "default-remote"` conserve le fallback distant intégré par défaut lorsqu’aucun modèle explicite ou hérité n’est disponible -- `config.promptStyle: "balanced"` utilise le style d’invite polyvalent par défaut pour le mode `recent` -- la mémoire active ne s’exécute toujours que sur les sessions de chat interactives persistantes éligibles +- `config.modelFallback` fournit éventuellement votre propre fournisseur/modèle de secours pour le rappel +- `config.promptStyle: "balanced"` utilise le style d’invite généraliste par défaut pour le mode `recent` +- la mémoire active ne s’exécute toujours que sur les sessions de chat persistantes interactives éligibles -## Comment l’afficher +## Comment la voir La mémoire active injecte un contexte système caché pour le modèle. Elle n’expose pas les balises brutes `...` au client. @@ -129,7 +129,7 @@ les balises brutes `...` au client. ## Bascule de session Utilisez la commande du plugin lorsque vous voulez mettre en pause ou reprendre la mémoire active pour la -session de chat en cours sans modifier la configuration : +session de chat en cours sans modifier la configuration : ```text /active-memory status @@ -137,12 +137,12 @@ session de chat en cours sans modifier la configuration : /active-memory on ``` -Cette action est limitée à la session. Elle ne modifie pas -`plugins.entries.active-memory.enabled`, le ciblage des agents ni une autre -configuration globale. +Ceci est limité à la session. Cela ne modifie pas +`plugins.entries.active-memory.enabled`, le ciblage d’agent, ni les autres +configurations globales. Si vous voulez que la commande écrive la configuration et mette en pause ou reprenne la mémoire active pour -toutes les sessions, utilisez la forme globale explicite : +toutes les sessions, utilisez la forme globale explicite : ```text /active-memory status --global @@ -152,37 +152,37 @@ toutes les sessions, utilisez la forme globale explicite : La forme globale écrit `plugins.entries.active-memory.config.enabled`. Elle laisse `plugins.entries.active-memory.enabled` activé afin que la commande reste disponible pour -réactiver plus tard la mémoire active. +réactiver la mémoire active plus tard. -Si vous voulez voir ce que fait la mémoire active dans une session active, activez le mode verbeux -pour cette session : +Si vous voulez voir ce que fait la mémoire active dans une session en direct, activez le mode verbeux +pour cette session : ```text /verbose on ``` -Avec le mode verbeux activé, OpenClaw peut afficher : +Avec le mode verbeux activé, OpenClaw peut afficher : -- une ligne d’état de la mémoire active telle que `Active Memory: ok 842ms recent 34 chars` +- une ligne d’état de mémoire active telle que `Active Memory: ok 842ms recent 34 chars` - un résumé de débogage lisible tel que `Active Memory Debug: Lemon pepper wings with blue cheese.` -Ces lignes sont dérivées du même passage de mémoire active qui alimente le contexte système -caché, mais elles sont formatées pour des humains au lieu d’exposer le balisage brut de l’invite. +Ces lignes proviennent de la même passe de mémoire active qui alimente le contexte système +caché, mais elles sont formatées pour les humains au lieu d’exposer le balisage brut de l’invite. -Par défaut, la transcription du sous-agent de mémoire bloquant est temporaire et supprimée +Par défaut, le transcript du sous-agent de mémoire bloquante est temporaire et supprimé une fois l’exécution terminée. -Exemple de flux : +Exemple de flux : ```text /verbose on -quelles ailes de poulet devrais-je commander ? +what wings should i order? ``` -Forme attendue de la réponse visible : +Forme attendue de la réponse visible : ```text -...réponse normale de l’assistant... +...normal assistant reply... 🧩 Active Memory: ok 842ms recent 34 chars 🔎 Active Memory Debug: Lemon pepper wings with blue cheese. @@ -190,36 +190,36 @@ Forme attendue de la réponse visible : ## Quand elle s’exécute -La mémoire active utilise deux mécanismes de contrôle : +La mémoire active utilise deux contrôles : -1. **Activation par configuration** - Le plugin doit être activé, et l’identifiant de l’agent en cours doit apparaître dans +1. **Activation explicite par la configuration** + Le plugin doit être activé, et l’identifiant de l’agent courant doit apparaître dans `plugins.entries.active-memory.config.agents`. -2. **Éligibilité stricte à l’exécution** +2. **Éligibilité d’exécution stricte** Même lorsqu’elle est activée et ciblée, la mémoire active ne s’exécute que pour les - sessions de chat interactives persistantes éligibles. + sessions de chat persistantes interactives éligibles. -La règle réelle est : +La règle réelle est la suivante : ```text -plugin activé +plugin enabled + -identifiant d’agent ciblé +agent id targeted + -type de chat autorisé +allowed chat type + -session de chat interactive persistante éligible +eligible interactive persistent chat session = -la mémoire active s’exécute +active memory runs ``` Si l’une de ces conditions échoue, la mémoire active ne s’exécute pas. ## Types de session -`config.allowedChatTypes` contrôle quels types de conversations peuvent exécuter la mémoire active. +`config.allowedChatTypes` contrôle les types de conversations pouvant exécuter la mémoire active. -La valeur par défaut est : +La valeur par défaut est : ```json5 allowedChatTypes: ["direct"] @@ -228,7 +228,7 @@ allowedChatTypes: ["direct"] Cela signifie que la mémoire active s’exécute par défaut dans les sessions de type message direct, mais pas dans les sessions de groupe ou de canal, sauf si vous les activez explicitement. -Exemples : +Exemples : ```json5 allowedChatTypes: ["direct"] @@ -247,50 +247,50 @@ allowedChatTypes: ["direct", "group", "channel"] La mémoire active est une fonctionnalité d’enrichissement conversationnel, pas une fonctionnalité d’inférence à l’échelle de la plateforme. -| Surface | La mémoire active s’exécute ? | +| Surface | La mémoire active s’exécute ? | | ------------------------------------------------------------------- | ------------------------------------------------------- | -| Sessions persistantes Control UI / chat web | Oui, si le plugin est activé et que l’agent est ciblé | -| Autres sessions de canal interactives sur le même chemin de chat persistant | Oui, si le plugin est activé et que l’agent est ciblé | -| Exécutions sans interface en un seul appel | Non | -| Exécutions heartbeat/arrière-plan | Non | +| Sessions persistantes de chat Control UI / web chat | Oui, si le plugin est activé et que l’agent est ciblé | +| Autres sessions de canal interactives sur le même chemin de chat persistant | Oui, si le plugin est activé et que l’agent est ciblé | +| Exécutions ponctuelles sans interface | Non | +| Exécutions de heartbeat / en arrière-plan | Non | | Chemins internes génériques `agent-command` | Non | -| Exécution de sous-agent/helper interne | Non | +| Exécution de sous-agent / d’assistant interne | Non | ## Pourquoi l’utiliser -Utilisez la mémoire active lorsque : +Utilisez la mémoire active lorsque : -- la session est persistante et destinée à l’utilisateur -- l’agent dispose d’une mémoire à long terme significative à consulter +- la session est persistante et orientée utilisateur +- l’agent dispose d’une mémoire à long terme utile à interroger - la continuité et la personnalisation comptent plus que le déterminisme brut de l’invite -Elle fonctionne particulièrement bien pour : +Elle fonctionne particulièrement bien pour : - les préférences stables - les habitudes récurrentes - le contexte utilisateur à long terme qui doit émerger naturellement -Elle convient mal à : +Elle convient mal à : - l’automatisation - les workers internes -- les tâches API en un seul appel +- les tâches API ponctuelles - les endroits où une personnalisation cachée serait surprenante -## Fonctionnement +## Comment elle fonctionne -La forme d’exécution est : +La forme d’exécution est la suivante : ```mermaid flowchart LR U["Message utilisateur"] --> Q["Construire la requête mémoire"] - Q --> R["Sous-agent de mémoire bloquant de mémoire active"] + Q --> R["Sous-agent de mémoire bloquante de mémoire active"] R -->|NONE or empty| M["Réponse principale"] R -->|relevant summary| I["Ajouter un contexte système caché active_memory_plugin"] I --> M["Réponse principale"] ``` -Le sous-agent de mémoire bloquant peut utiliser uniquement : +Le sous-agent de mémoire bloquante ne peut utiliser que : - `memory_search` - `memory_get` @@ -299,23 +299,23 @@ Si la connexion est faible, il doit renvoyer `NONE`. ## Modes de requête -`config.queryMode` contrôle la quantité de conversation que voit le sous-agent de mémoire bloquant. +`config.queryMode` contrôle la quantité de conversation que voit le sous-agent de mémoire bloquante. ## Styles d’invite -`config.promptStyle` contrôle à quel point le sous-agent de mémoire bloquant est -volontaire ou strict lorsqu’il décide de renvoyer une mémoire. +`config.promptStyle` contrôle à quel point le sous-agent de mémoire bloquante est +enclin ou strict lorsqu’il décide de renvoyer de la mémoire. -Styles disponibles : +Styles disponibles : -- `balanced` : valeur par défaut polyvalente pour le mode `recent` -- `strict` : le moins volontaire ; idéal lorsque vous voulez très peu de contamination par le contexte proche -- `contextual` : le plus favorable à la continuité ; idéal lorsque l’historique de conversation doit davantage compter -- `recall-heavy` : plus disposé à faire remonter une mémoire sur des correspondances plus souples mais toujours plausibles -- `precision-heavy` : privilégie agressivement `NONE` sauf si la correspondance est évidente -- `preference-only` : optimisé pour les favoris, les habitudes, les routines, les goûts et les faits personnels récurrents +- `balanced`: valeur par défaut généraliste pour le mode `recent` +- `strict`: le moins enclin ; idéal lorsque vous voulez très peu d’influence du contexte proche +- `contextual`: le plus favorable à la continuité ; idéal lorsque l’historique de conversation doit compter davantage +- `recall-heavy`: plus enclin à faire remonter la mémoire pour des correspondances plus souples mais toujours plausibles +- `precision-heavy`: préfère fortement `NONE` sauf si la correspondance est évidente +- `preference-only`: optimisé pour les favoris, habitudes, routines, goûts et faits personnels récurrents -Correspondance par défaut lorsque `config.promptStyle` n’est pas défini : +Correspondance par défaut lorsque `config.promptStyle` n’est pas défini : ```text message -> strict @@ -323,71 +323,67 @@ recent -> balanced full -> contextual ``` -Si vous définissez `config.promptStyle` explicitement, cette valeur de remplacement l’emporte. +Si vous définissez `config.promptStyle` explicitement, cette valeur prioritaire s’applique. -Exemple : +Exemple : ```json5 promptStyle: "preference-only" ``` -## Politique de fallback du modèle +## Politique de modèle de secours -Si `config.model` n’est pas défini, la mémoire active tente de résoudre un modèle dans cet ordre : +Si `config.model` n’est pas défini, la mémoire active essaie de résoudre un modèle dans cet ordre : ```text -modèle explicite du plugin --> modèle de la session en cours --> modèle principal de l’agent --> fallback distant intégré optionnel +explicit plugin model +-> current session model +-> agent primary model +-> optional configured fallback model ``` -`config.modelFallbackPolicy` contrôle la dernière étape. +`config.modelFallback` contrôle l’étape de secours configurée. -Valeur par défaut : +Secours personnalisé optionnel : ```json5 -modelFallbackPolicy: "default-remote" +modelFallback: "google/gemini-3-flash" ``` -Autre option : +Si aucun modèle explicite, hérité ou de secours configuré n’est résolu, la mémoire active +ignore le rappel pour ce tour. -```json5 -modelFallbackPolicy: "resolved-only" -``` +`config.modelFallbackPolicy` n’est conservé que comme champ de compatibilité obsolète +pour les anciennes configurations. Il ne modifie plus le comportement à l’exécution. -Utilisez `resolved-only` si vous voulez que la mémoire active ignore le rappel au lieu d’utiliser -par défaut le mode distant intégré lorsqu’aucun modèle explicite ou hérité n’est -disponible. - -## Échappatoires avancées +## Options avancées d’échappement Ces options ne font volontairement pas partie de la configuration recommandée. -`config.thinking` peut remplacer le niveau de réflexion du sous-agent de mémoire bloquant : +`config.thinking` peut remplacer le niveau de réflexion du sous-agent de mémoire bloquante : ```json5 thinking: "medium" ``` -Valeur par défaut : +Valeur par défaut : ```json5 thinking: "off" ``` -Ne l’activez pas par défaut. La mémoire active s’exécute sur le chemin de réponse, donc le temps de -réflexion supplémentaire augmente directement la latence visible par l’utilisateur. +Ne l’activez pas par défaut. La mémoire active s’exécute dans le chemin de réponse, donc un temps +de réflexion supplémentaire augmente directement la latence visible par l’utilisateur. -`config.promptAppend` ajoute des instructions opérateur supplémentaires après l’invite par défaut de la mémoire active -et avant le contexte de conversation : +`config.promptAppend` ajoute des instructions opérateur supplémentaires après l’invite +par défaut de la mémoire active et avant le contexte de conversation : ```json5 -promptAppend: "Préférez les préférences stables à long terme aux événements ponctuels." +promptAppend: "Prefer stable long-term preferences over one-off events." ``` `config.promptOverride` remplace l’invite par défaut de la mémoire active. OpenClaw -ajoute toujours ensuite le contexte de conversation : +ajoute toujours ensuite le contexte de conversation : ```json5 promptOverride: "You are a memory search agent. Return NONE or one compact user fact." @@ -395,90 +391,90 @@ promptOverride: "You are a memory search agent. Return NONE or one compact user La personnalisation de l’invite n’est pas recommandée, sauf si vous testez délibérément un contrat de rappel différent. L’invite par défaut est réglée pour renvoyer soit `NONE`, -soit un contexte compact de fait utilisateur pour le modèle principal. +soit un contexte compact de faits utilisateur pour le modèle principal. ### `message` Seul le dernier message utilisateur est envoyé. ```text -Dernier message utilisateur uniquement +Latest user message only ``` -Utilisez ceci lorsque : +Utilisez ce mode lorsque : - vous voulez le comportement le plus rapide - vous voulez le biais le plus fort vers le rappel de préférences stables - les tours de suivi n’ont pas besoin de contexte conversationnel -Délai d’expiration recommandé : +Délai d’expiration recommandé : - commencez autour de `3000` à `5000` ms ### `recent` -Le dernier message utilisateur ainsi qu’une petite queue de conversation récente sont envoyés. +Le dernier message utilisateur plus une petite queue récente de conversation sont envoyés. ```text -Queue de conversation récente : +Recent conversation tail: user: ... assistant: ... user: ... -Dernier message utilisateur : +Latest user message: ... ``` -Utilisez ceci lorsque : +Utilisez ce mode lorsque : - vous voulez un meilleur équilibre entre vitesse et ancrage conversationnel - les questions de suivi dépendent souvent des derniers tours -Délai d’expiration recommandé : +Délai d’expiration recommandé : - commencez autour de `15000` ms ### `full` -La conversation complète est envoyée au sous-agent de mémoire bloquant. +La conversation complète est envoyée au sous-agent de mémoire bloquante. ```text -Contexte complet de la conversation : +Full conversation context: user: ... assistant: ... user: ... ... ``` -Utilisez ceci lorsque : +Utilisez ce mode lorsque : -- la meilleure qualité de rappel compte davantage que la latence -- la conversation contient des éléments de préparation importants loin dans le fil +- la meilleure qualité de rappel compte plus que la latence +- la conversation contient des éléments de contexte importants loin dans le fil -Délai d’expiration recommandé : +Délai d’expiration recommandé : -- augmentez-le sensiblement par rapport à `message` ou `recent` +- augmentez-le nettement par rapport à `message` ou `recent` - commencez autour de `15000` ms ou plus selon la taille du fil -En général, le délai d’expiration doit augmenter avec la taille du contexte : +En général, le délai d’expiration doit augmenter avec la taille du contexte : ```text message < recent < full ``` -## Persistance des transcriptions +## Persistance des transcripts -Les exécutions du sous-agent de mémoire bloquant de la mémoire active créent une véritable transcription `session.jsonl` -pendant l’appel du sous-agent de mémoire bloquant. +Les exécutions du sous-agent de mémoire bloquante de mémoire active créent un véritable +transcript `session.jsonl` pendant l’appel du sous-agent de mémoire bloquante. -Par défaut, cette transcription est temporaire : +Par défaut, ce transcript est temporaire : -- elle est écrite dans un répertoire temporaire -- elle est utilisée uniquement pour l’exécution du sous-agent de mémoire bloquant -- elle est supprimée immédiatement une fois l’exécution terminée +- il est écrit dans un répertoire temporaire +- il est utilisé uniquement pour l’exécution du sous-agent de mémoire bloquante +- il est supprimé immédiatement une fois l’exécution terminée -Si vous voulez conserver ces transcriptions du sous-agent de mémoire bloquant sur le disque pour le débogage ou -l’inspection, activez explicitement la persistance : +Si vous voulez conserver ces transcripts du sous-agent de mémoire bloquante sur le disque à des fins de débogage ou +d’inspection, activez explicitement la persistance : ```json5 { @@ -497,11 +493,11 @@ l’inspection, activez explicitement la persistance : } ``` -Lorsqu’elle est activée, la mémoire active stocke les transcriptions dans un répertoire distinct sous le -dossier de sessions de l’agent cible, et non dans le chemin principal de transcription de la conversation +Lorsqu’elle est activée, la mémoire active stocke les transcripts dans un répertoire séparé sous le +dossier de sessions de l’agent cible, et non dans le chemin principal du transcript de la conversation utilisateur. -La disposition par défaut est, de manière conceptuelle : +La structure par défaut est conceptuellement la suivante : ```text agents//sessions/active-memory/.jsonl @@ -509,48 +505,48 @@ agents//sessions/active-memory/.jso Vous pouvez modifier le sous-répertoire relatif avec `config.transcriptDir`. -Utilisez cela avec précaution : +Utilisez cela avec précaution : -- les transcriptions du sous-agent de mémoire bloquant peuvent s’accumuler rapidement dans les sessions actives -- le mode de requête `full` peut dupliquer une grande quantité de contexte de conversation -- ces transcriptions contiennent un contexte d’invite caché et des mémoires rappelées +- les transcripts du sous-agent de mémoire bloquante peuvent s’accumuler rapidement sur les sessions chargées +- le mode de requête `full` peut dupliquer beaucoup de contexte conversationnel +- ces transcripts contiennent un contexte d’invite caché et des souvenirs rappelés ## Configuration -Toute la configuration de la mémoire active se trouve sous : +Toute la configuration de la mémoire active se trouve sous : ```text plugins.entries.active-memory ``` -Les champs les plus importants sont : +Les champs les plus importants sont : | Clé | Type | Signification | | --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `enabled` | `boolean` | Active le plugin lui-même | -| `config.agents` | `string[]` | Identifiants d’agent pouvant utiliser la mémoire active | -| `config.model` | `string` | Référence de modèle optionnelle du sous-agent de mémoire bloquant ; si elle n’est pas définie, la mémoire active utilise le modèle de la session en cours | -| `config.queryMode` | `"message" \| "recent" \| "full"` | Contrôle la quantité de conversation vue par le sous-agent de mémoire bloquant | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Contrôle à quel point le sous-agent de mémoire bloquant est volontaire ou strict lorsqu’il décide de renvoyer une mémoire | -| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Remplacement avancé du niveau de réflexion pour le sous-agent de mémoire bloquant ; valeur par défaut `off` pour la vitesse | -| `config.promptOverride` | `string` | Remplacement avancé de l’invite complète ; non recommandé pour un usage normal | +| `config.agents` | `string[]` | Identifiants d’agents pouvant utiliser la mémoire active | +| `config.model` | `string` | Référence de modèle optionnelle pour le sous-agent de mémoire bloquante ; si elle n’est pas définie, la mémoire active utilise le modèle de la session en cours | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Contrôle la quantité de conversation que voit le sous-agent de mémoire bloquante | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Contrôle à quel point le sous-agent de mémoire bloquante est enclin ou strict lorsqu’il décide de renvoyer de la mémoire | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Remplacement avancé du niveau de réflexion pour le sous-agent de mémoire bloquante ; valeur par défaut `off` pour la rapidité | +| `config.promptOverride` | `string` | Remplacement complet avancé de l’invite ; non recommandé pour un usage normal | | `config.promptAppend` | `string` | Instructions supplémentaires avancées ajoutées à l’invite par défaut ou remplacée | -| `config.timeoutMs` | `number` | Délai d’expiration strict pour le sous-agent de mémoire bloquant | -| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé active-memory | +| `config.timeoutMs` | `number` | Délai d’expiration strict pour le sous-agent de mémoire bloquante | +| `config.maxSummaryChars` | `number` | Nombre total maximal de caractères autorisés dans le résumé de mémoire active | | `config.logging` | `boolean` | Émet des journaux de mémoire active pendant le réglage | -| `config.persistTranscripts` | `boolean` | Conserve les transcriptions du sous-agent de mémoire bloquant sur le disque au lieu de supprimer les fichiers temporaires | -| `config.transcriptDir` | `string` | Répertoire relatif des transcriptions du sous-agent de mémoire bloquant sous le dossier de sessions de l’agent | +| `config.persistTranscripts` | `boolean` | Conserve les transcripts du sous-agent de mémoire bloquante sur le disque au lieu de supprimer les fichiers temporaires | +| `config.transcriptDir` | `string` | Répertoire relatif des transcripts du sous-agent de mémoire bloquante sous le dossier de sessions de l’agent | -Champs de réglage utiles : +Champs de réglage utiles : | Clé | Type | Signification | | ----------------------------- | -------- | ------------------------------------------------------------ | -| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé active-memory | -| `config.recentUserTurns` | `number` | Tours utilisateur précédents à inclure lorsque `queryMode` vaut `recent` | -| `config.recentAssistantTurns` | `number` | Tours assistant précédents à inclure lorsque `queryMode` vaut `recent` | +| `config.maxSummaryChars` | `number` | Nombre total maximal de caractères autorisés dans le résumé de mémoire active | +| `config.recentUserTurns` | `number` | Tours utilisateur précédents à inclure lorsque `queryMode` est `recent` | +| `config.recentAssistantTurns` | `number` | Tours assistant précédents à inclure lorsque `queryMode` est `recent` | | `config.recentUserChars` | `number` | Nombre maximal de caractères par tour utilisateur récent | | `config.recentAssistantChars` | `number` | Nombre maximal de caractères par tour assistant récent | -| `config.cacheTtlMs` | `number` | Réutilisation du cache pour des requêtes identiques répétées | +| `config.cacheTtlMs` | `number` | Réutilisation du cache pour les requêtes identiques répétées | ## Configuration recommandée @@ -577,28 +573,28 @@ Commencez avec `recent`. ``` Si vous voulez inspecter le comportement en direct pendant le réglage, utilisez `/verbose on` dans la -session au lieu de chercher une commande de débogage active-memory distincte. +session au lieu de chercher une commande de débogage active-memory séparée. -Passez ensuite à : +Ensuite, passez à : - `message` si vous voulez une latence plus faible -- `full` si vous décidez qu’un contexte supplémentaire vaut un sous-agent de mémoire bloquant plus lent +- `full` si vous décidez qu’un contexte supplémentaire vaut le sous-agent de mémoire bloquante plus lent ## Débogage -Si la mémoire active n’apparaît pas là où vous l’attendez : +Si la mémoire active n’apparaît pas là où vous l’attendez : -1. Vérifiez que le plugin est activé sous `plugins.entries.active-memory.enabled`. -2. Vérifiez que l’identifiant de l’agent en cours figure dans `config.agents`. -3. Vérifiez que vous testez via une session de chat interactive persistante. +1. Confirmez que le plugin est activé sous `plugins.entries.active-memory.enabled`. +2. Confirmez que l’identifiant de l’agent courant figure dans `config.agents`. +3. Confirmez que vous testez via une session de chat persistante interactive. 4. Activez `config.logging: true` et surveillez les journaux de la passerelle. 5. Vérifiez que la recherche mémoire elle-même fonctionne avec `openclaw memory status --deep`. -Si les résultats mémoire sont trop bruités, resserrez : +Si les correspondances mémoire sont trop bruyantes, resserrez : - `maxSummaryChars` -Si la mémoire active est trop lente : +Si la mémoire active est trop lente : - réduisez `queryMode` - réduisez `timeoutMs` @@ -609,4 +605,4 @@ Si la mémoire active est trop lente : - [Recherche mémoire](/fr/concepts/memory-search) - [Référence de configuration de la mémoire](/fr/reference/memory-config) -- [Configuration du Plugin SDK](/fr/plugins/sdk-setup) +- [Configuration du SDK de plugin](/fr/plugins/sdk-setup) diff --git a/docs/fr/concepts/system-prompt.md b/docs/fr/concepts/system-prompt.md index d6a5a83a6..4f040ea56 100644 --- a/docs/fr/concepts/system-prompt.md +++ b/docs/fr/concepts/system-prompt.md @@ -1,100 +1,99 @@ --- read_when: - - Modification du texte du prompt système, de la liste d’outils, ou des sections de temps/de heartbeat - - Modification du bootstrap de l’espace de travail ou du comportement d’injection des Skills + - Modification du texte du prompt système, de la liste des outils ou des sections heure/pulsation + - Modification du comportement d’amorçage de l’espace de travail ou d’injection des Skills summary: Ce que contient le prompt système d’OpenClaw et comment il est assemblé title: Prompt système x-i18n: - generated_at: "2026-04-08T02:14:18Z" + generated_at: "2026-04-12T06:49:38Z" model: gpt-5.4 provider: openai - source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a + source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f source_path: concepts/system-prompt.md workflow: 15 --- # Prompt système -OpenClaw crée 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. +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. Le prompt est assemblé par OpenClaw et injecté dans chaque exécution d’agent. -Les plugins de fournisseur peuvent contribuer des consignes de prompt compatibles avec le cache sans remplacer l’intégralité du prompt appartenant à 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 géré par OpenClaw. Le runtime du fournisseur peut : - remplacer un petit ensemble de sections principales nommées (`interaction_style`, `tool_call_style`, `execution_bias`) -- injecter un **préfixe stable** au-dessus de la limite du cache de prompt -- injecter un **suffixe dynamique** au-dessous de la limite du cache de prompt +- injecter un **préfixe stable** au-dessus de la limite de cache du prompt +- injecter un **suffixe dynamique** au-dessous de la limite de cache du prompt -Utilisez des contributions appartenant au 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 modifications de prompt réellement globales, pas pour le comportement normal d’un fournisseur. +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. ## 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 consignes d’exécution concernant l’utilisation des outils. -- **Sécurité** : bref rappel des garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision. -- **Skills** (quand disponibles) : indique au modèle comment charger les instructions des Skills à la demande. -- **Auto-mise à jour d’OpenClaw** : 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 aussi de réécrire +- **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 `tools.exec.ask` / `tools.exec.security`, y compris les alias hérités `tools.bash.*` - qui sont normalisés 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 quand la lire. -- **Fichiers de l’espace de travail (injectés)** : indique que les fichiers de bootstrap sont inclus ci-dessous. -- **Sandbox** (quand activée) : indique le runtime sandboxé, les chemins de la sandbox, et si l’exécution avec privilèges élevés est disponible. -- **Date et heure actuelles** : heure locale de l’utilisateur, fuseau horaire et format de l’heure. -- **Balises de réponse** : 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, racine du dépôt (quand détectée), niveau de réflexion (une ligne). -- **Raisonnement** : niveau de visibilité actuel + indication de la bascule /reasoning. + 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`. -La section Outils inclut aussi des consignes d’exécution pour les travaux de longue durée : +La section Outils comprend également des indications d’exécution pour les tâches de longue durée : -- utiliser cron pour les suivis futurs (`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 +- 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 en arrière-plan - lorsque le réveil automatique à la fin est activé, démarrer la commande une seule fois et s’appuyer sur - le mécanisme de réveil push lorsqu’elle produit une sortie ou échoue -- utiliser `process` pour les journaux, le statut, l’entrée, ou une intervention lorsque vous devez + 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 inspecter une commande en cours d’exécution -- si la tâche est plus importante, préférer `sessions_spawn` ; la fin des sous-agents est - pilotée par push et annoncée automatiquement au demandeur -- ne pas sonder `subagents list` / `sessions_list` en boucle simplement pour attendre +- 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 +- 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 aussi au -modèle de ne l’utiliser que pour un travail non trivial en plusieurs étapes, de conserver exactement une étape +Lorsque l’outil expérimental `update_plan` est activé, 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. -Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils orientent le comportement du modèle, mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations d’exécution, la sandbox et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception. +Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas 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. -Sur les canaux avec cartes/boutons d’approbation natifs, le prompt d’exécution indique maintenant à l’agent de -s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle -`/approve` que 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 voie possible. +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é. ## Modes de prompt -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 visible par l’utilisateur) : +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) : -- `full` (par défaut) : inclut toutes les sections ci-dessus. -- `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Rappel de mémoire**, **Auto-mise à jour d’OpenClaw**, **Alias de modèles**, **Identité de l’utilisateur**, **Balises de réponse**, - **Messagerie**, **Réponses silencieuses**, et **Heartbeats**. Outils, **Sécurité**, - Espace de travail, Sandbox, Date et heure actuelles (lorsqu’elles sont connues), Runtime, et le - contexte injecté restent disponibles. -- `none` : renvoie uniquement la ligne d’identité de base. +- `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 + injecté restent disponibles. +- `none` : renvoie uniquement la ligne d’identité de base. -Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont étiquetés **Contexte du sous-agent** -au lieu de **Contexte de discussion de groupe**. +Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont libellés **Contexte du sous-agent** +au lieu de **Contexte du chat de groupe**. -## Injection du bootstrap de l’espace de travail +## Injection de l’amorçage de l’espace de travail -Les fichiers de bootstrap sont tronqués puis ajoutés sous **Contexte du projet** afin que le modèle voie l’identité et le contexte du profil sans nécessiter de lectures explicites : +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 : - `AGENTS.md` - `SOUL.md` @@ -102,65 +101,68 @@ Les fichiers de bootstrap sont tronqués puis ajoutés sous **Contexte du projet - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (uniquement dans les espaces de travail tout juste créés) -- `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de secours en minuscules +- `BOOTSTRAP.md` (uniquement dans les tout nouveaux espaces de travail) +- `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de repli en minuscules Tous ces fichiers sont **injectés dans la fenêtre de contexte** à chaque tour, sauf si -une condition spécifique à un fichier s’applique. `HEARTBEAT.md` est omis dans les 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 — surtout `MEMORY.md`, qui peut grossir avec le temps et entraîner -une utilisation du contexte étonnamment élevée ainsi qu’une compaction plus fréquente. +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 +`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. -> **Remarque :** les fichiers quotidiens `memory/*.md` ne sont **pas** injectés automatiquement. Ils -> sont consultés à la demande via les outils `memory_search` et `memory_get`, et ils -> ne comptent donc pas dans la fenêtre de contexte tant que le modèle ne les lit pas explicitement. +> **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 +> `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. Les fichiers volumineux sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par -`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total du bootstrap injecté +`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total d’amorçage 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. En cas de troncature, -OpenClaw peut injecter un bloc d’avertissement dans le 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. 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`). -Les sessions de sous-agents n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers de bootstrap -sont filtrés afin de garder un petit contexte pour le sous-agent). +Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers d’amorçage +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 de bootstrap injectés (par exemple en remplaçant `SOUL.md` par un persona alternatif). +les fichiers d’amorçage injectés (par exemple en remplaçant `SOUL.md` par une persona alternative). -Si vous souhaitez que l’agent paraisse moins générique, commencez par le +Si vous souhaitez rendre l’agent moins générique, commencez par le [Guide de personnalité SOUL.md](/fr/concepts/soul). -Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus la 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 du 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, il n’inclut maintenant que -le **fuseau horaire** (sans horloge dynamique ni format de l’heure). +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). -Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte de statut -inclut une ligne d’horodatage. Le même outil peut aussi définir un remplacement de modèle par session -(`model=default` l’efface). +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). -Configurez avec : +Configurez avec : - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Voir [Date & Time](/fr/date-time) pour le détail complet du comportement. +Voir [Date et heure](/fr/date-time) pour tous les détails du 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 -prompt demande au modèle d’utiliser `read` pour charger le SKILL.md à l’emplacement indiqué -(espace de travail, géré, ou intégré). Si aucun Skill n’est éligible, la section +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. -L’éligibilité inclut les conditions des métadonnées du Skill, les vérifications de l’environnement/de la configuration d’exécution, +L’éligibilité comprend les garde-fous des métadonnées des Skills, les vérifications d’environnement/configuration d’exécution, et la liste d’autorisation effective des Skills de l’agent lorsque `agents.defaults.skills` ou `agents.list[].skills` est configuré. @@ -174,13 +176,13 @@ et la liste d’autorisation effective des Skills de l’agent lorsque `agents.d ``` -Cela permet de garder le prompt de base compact tout en activant un usage ciblé des Skills. +Cela maintient un prompt de base réduit tout en permettant une utilisation ciblée des Skills. ## Documentation -Lorsqu’elle est disponible, le prompt système inclut une section **Documentation** qui pointe vers le -répertoire local de la documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation intégrée du -package npm) et mentionne aussi 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 demande au modèle de consulter d’abord la documentation locale +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 +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 ne demandant à l’utilisateur que lorsqu’il n’y a pas accès). +`openclaw status` lui-même lorsque c’est possible (en demandant à l’utilisateur seulement lorsqu’il n’y a pas accès). diff --git a/docs/fr/plugins/architecture.md b/docs/fr/plugins/architecture.md index bc687317c..07e50cfb2 100644 --- a/docs/fr/plugins/architecture.md +++ b/docs/fr/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Création ou débogage des plugins OpenClaw natifs + - Créer ou déboguer des plugins OpenClaw natifs - Comprendre le modèle de capacités des plugins ou les limites de propriété - Travailler sur le pipeline de chargement des plugins ou le registre - Implémenter des hooks d’exécution de fournisseur ou des plugins de canal sidebarTitle: Internals -summary: 'Composants internes des plugins : modèle de capacités, propriété, contrats, pipeline de chargement et assistants d’exécution' +summary: 'Composants internes des plugins : modèle de capacités, propriété, contrats, pipeline de chargement et helpers d’exécution' title: Composants internes des plugins x-i18n: - generated_at: "2026-04-11T15:16:02Z" + generated_at: "2026-04-12T06:49:37Z" model: gpt-5.4 provider: openai - source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 + source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0 source_path: plugins/architecture.md workflow: 15 --- @@ -24,152 +24,172 @@ x-i18n: - [Premiers pas](/fr/plugins/building-plugins) — premier tutoriel de plugin - [Plugins de canal](/fr/plugins/sdk-channel-plugins) — créer un canal de messagerie - [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — créer un fournisseur de modèles - - [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — carte des imports et API d’enregistrement + - [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — table d’imports et API d’enregistrement -Cette page couvre l’architecture interne du système de plugins OpenClaw. +Cette page couvre l’architecture interne du système de plugins d’OpenClaw. ## Modèle de capacités public Les capacités constituent le modèle public des **plugins natifs** dans OpenClaw. Chaque -plugin OpenClaw natif s’enregistre pour un ou plusieurs types de capacités : +plugin OpenClaw natif s’enregistre auprès d’un ou de plusieurs types de capacités : -| Capability | Registration method | Example plugins | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| Inférence de texte | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend d’inférence CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Parole | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Transcription en temps réel | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voix en temps réel | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Compréhension des médias | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Génération d’images | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Génération musicale | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Génération de vidéos | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Récupération web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Recherche web | `api.registerWebSearchProvider(...)` | `google` | -| Canal / messagerie | `api.registerChannel(...)` | `msteams`, `matrix` | +| Capacité | Méthode d’enregistrement | Exemples de plugins | +| ---------------------- | ----------------------------------------------- | ------------------------------------ | +| Inférence de texte | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend d’inférence CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Voix | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Transcription en temps réel | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Voix en temps réel | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Compréhension des médias | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Génération d’images | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Génération de musique | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Génération de vidéo | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Récupération web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Recherche web | `api.registerWebSearchProvider(...)` | `google` | +| Canal / messagerie | `api.registerChannel(...)` | `msteams`, `matrix` | Un plugin qui enregistre zéro capacité mais fournit des hooks, des outils ou des services est un plugin **legacy hook-only**. Ce modèle reste entièrement pris en charge. ### Position de compatibilité externe -Le modèle de capacités est intégré au cœur et utilisé par les plugins -bundled/natifs aujourd’hui, mais la compatibilité des plugins externes exige -encore un niveau d’exigence plus élevé que « c’est exporté, donc c’est figé ». +Le modèle de capacités est intégré au cœur et utilisé aujourd’hui par les plugins +bundled/natifs, mais la compatibilité des plugins externes exige encore une barre +plus stricte que « c’est exporté, donc c’est figé ». -Recommandations actuelles : +Recommandation actuelle : -- **plugins externes existants :** conserver le fonctionnement des intégrations basées sur des hooks ; traiter cela comme la base de compatibilité -- **nouveaux plugins bundled/natifs :** préférer un enregistrement explicite des capacités plutôt que des accès spécifiques à un fournisseur ou de nouveaux modèles hook-only -- **plugins externes adoptant l’enregistrement des capacités :** autorisés, mais considérer les surfaces d’assistance spécifiques aux capacités comme évolutives, sauf si la documentation marque explicitement un contrat comme stable +- **plugins externes existants :** conserver le bon fonctionnement des + intégrations basées sur des hooks ; les considérer comme la base de compatibilité +- **nouveaux plugins bundled/natifs :** préférer un enregistrement explicite des + capacités plutôt que des accès internes spécifiques à un fournisseur ou de + nouveaux modèles hook-only +- **plugins externes qui adoptent l’enregistrement de capacités :** autorisé, + mais considérer les surfaces helper spécifiques aux capacités comme évolutives, + sauf si la documentation marque explicitement un contrat comme stable Règle pratique : -- les API d’enregistrement des capacités sont l’orientation voulue -- les hooks legacy restent la voie la plus sûre pour éviter les ruptures pour les plugins externes pendant la transition -- tous les sous-chemins d’assistance exportés ne se valent pas ; préférez le contrat documenté étroit, et non des exports d’assistance accessoires +- les API d’enregistrement de capacités sont la direction prévue +- les hooks legacy restent le chemin le plus sûr pour éviter toute rupture pour + les plugins externes pendant la transition +- tous les sous-chemins helper exportés ne se valent pas ; préférez le contrat + étroit et documenté, pas des exports helper accessoires -### Formes de plugins +### Formes de plugin -OpenClaw classe chaque plugin chargé selon une forme basée sur son comportement -réel d’enregistrement (et non uniquement sur des métadonnées statiques) : +OpenClaw classe chaque plugin chargé dans une forme selon son comportement +d’enregistrement réel (et pas seulement selon des métadonnées statiques) : -- **plain-capability** -- enregistre exactement un type de capacité (par exemple un plugin de fournisseur uniquement comme `mistral`) -- **hybrid-capability** -- enregistre plusieurs types de capacités (par exemple `openai` possède l’inférence de texte, la parole, la compréhension des médias et la génération d’images) -- **hook-only** -- enregistre uniquement des hooks (typés ou personnalisés), sans capacités, outils, commandes ni services -- **non-capability** -- enregistre des outils, commandes, services ou routes, mais aucune capacité +- **plain-capability** -- enregistre exactement un type de capacité (par exemple, + un plugin uniquement fournisseur comme `mistral`) +- **hybrid-capability** -- enregistre plusieurs types de capacités (par exemple, + `openai` possède l’inférence de texte, la voix, la compréhension des médias et la + génération d’images) +- **hook-only** -- enregistre uniquement des hooks (typés ou personnalisés), sans + capacités, outils, commandes ni services +- **non-capability** -- enregistre des outils, commandes, services ou routes, mais + aucune capacité -Utilisez `openclaw plugins inspect ` pour voir la forme d’un plugin et le -détail de ses capacités. Voir [Référence CLI](/cli/plugins#inspect) pour plus de détails. +Utilisez `openclaw plugins inspect ` pour voir la forme d’un plugin et la +répartition de ses capacités. Voir la [référence CLI](/cli/plugins#inspect) pour plus de détails. ### Hooks legacy -Le hook `before_agent_start` reste pris en charge comme voie de compatibilité pour -les plugins hook-only. Des plugins legacy utilisés en conditions réelles en dépendent encore. +Le hook `before_agent_start` reste pris en charge comme chemin de compatibilité +pour les plugins hook-only. Des plugins legacy réels en dépendent encore. Orientation : - le conserver fonctionnel - le documenter comme legacy - préférer `before_model_resolve` pour le travail de substitution de modèle/fournisseur -- préférer `before_prompt_build` pour le travail de mutation de prompt -- ne le supprimer qu’après baisse de l’usage réel et lorsque la couverture des fixtures prouve la sécurité de la migration +- préférer `before_prompt_build` pour le travail de mutation des prompts +- le supprimer seulement après baisse de l’usage réel et quand la couverture par + fixtures prouve la sécurité de la migration ### Signaux de compatibilité -Lorsque vous exécutez `openclaw doctor` ou `openclaw plugins inspect `, vous pouvez voir -l’un de ces libellés : +Lorsque vous exécutez `openclaw doctor` ou `openclaw plugins inspect `, vous +pouvez voir l’un de ces libellés : -| Signal | Signification | -| -------------------------- | -------------------------------------------------------------- | -| **config valid** | La configuration est analysée correctement et les plugins se résolvent | -| **compatibility advisory** | Le plugin utilise un modèle pris en charge mais plus ancien (par ex. `hook-only`) | -| **legacy warning** | Le plugin utilise `before_agent_start`, qui est obsolète | +| Signal | Signification | +| -------------------------- | ----------------------------------------------------------- | +| **config valid** | La configuration est analysée correctement et les plugins sont résolus | +| **compatibility advisory** | Le plugin utilise un modèle ancien mais pris en charge (par ex. `hook-only`) | +| **legacy warning** | Le plugin utilise `before_agent_start`, qui est obsolète | | **hard error** | La configuration est invalide ou le plugin n’a pas pu être chargé | Ni `hook-only` ni `before_agent_start` ne casseront votre plugin aujourd’hui -- -`hook-only` est un avis, et `before_agent_start` ne déclenche qu’un avertissement. Ces -signaux apparaissent aussi dans `openclaw status --all` et `openclaw plugins doctor`. +`hook-only` est informatif, et `before_agent_start` ne déclenche qu’un +avertissement. Ces signaux apparaissent aussi dans `openclaw status --all` et +`openclaw plugins doctor`. ## Vue d’ensemble de l’architecture Le système de plugins d’OpenClaw comporte quatre couches : -1. **Manifeste + découverte** - OpenClaw trouve les plugins candidats à partir des chemins configurés, des racines d’espace de travail, - des racines globales d’extensions et des extensions bundled. La découverte lit d’abord - les manifestes natifs `openclaw.plugin.json` ainsi que les manifestes de bundle pris en charge. +1. **Manifest + découverte** + OpenClaw trouve les plugins candidats à partir des chemins configurés, des + racines d’espace de travail, des racines globales d’extensions et des + extensions bundled. La découverte lit d’abord les manifests natifs + `openclaw.plugin.json` ainsi que les manifests de bundles pris en charge. 2. **Activation + validation** Le cœur décide si un plugin découvert est activé, désactivé, bloqué ou sélectionné pour un emplacement exclusif comme la mémoire. 3. **Chargement à l’exécution** - Les plugins OpenClaw natifs sont chargés dans le processus via jiti et enregistrent - des capacités dans un registre central. Les bundles compatibles sont normalisés en - enregistrements de registre sans importer de code d’exécution. + Les plugins OpenClaw natifs sont chargés dans le processus via jiti et + enregistrent des capacités dans un registre central. Les bundles compatibles + sont normalisés en entrées de registre sans importer de code d’exécution. 4. **Consommation des surfaces** - Le reste d’OpenClaw lit le registre pour exposer les outils, canaux, configuration des fournisseurs, - hooks, routes HTTP, commandes CLI et services. + Le reste d’OpenClaw lit le registre pour exposer les outils, canaux, configuration + des fournisseurs, hooks, routes HTTP, commandes CLI et services. -Pour la CLI des plugins en particulier, la découverte des commandes racine est divisée en deux phases : +Pour la CLI des plugins en particulier, la découverte des commandes racine est +divisée en deux phases : -- les métadonnées au moment de l’analyse viennent de `registerCli(..., { descriptors: [...] })` +- les métadonnées au moment de l’analyse proviennent de `registerCli(..., { descriptors: [...] })` - le véritable module CLI du plugin peut rester paresseux et s’enregistrer lors de la première invocation -Cela permet de conserver le code CLI appartenant au plugin dans le plugin tout en laissant OpenClaw -réserver les noms de commandes racine avant l’analyse. +Cela permet de garder le code CLI appartenant au plugin à l’intérieur du plugin +tout en laissant OpenClaw réserver les noms de commandes racine avant l’analyse. La limite de conception importante : -- la découverte + validation de la configuration doivent fonctionner à partir des **métadonnées de manifeste/schéma** - sans exécuter de code de plugin -- le comportement d’exécution natif provient du chemin `register(api)` du module du plugin +- la découverte + la validation de configuration doivent fonctionner à partir des + **métadonnées de manifest/schéma** sans exécuter de code de plugin +- le comportement natif à l’exécution provient du chemin `register(api)` du module du plugin -Cette séparation permet à OpenClaw de valider la configuration, d’expliquer les plugins manquants/désactivés et -de construire des indications d’interface/schéma avant que l’exécution complète ne soit active. +Cette séparation permet à OpenClaw de valider la configuration, d’expliquer les +plugins manquants/désactivés et de construire des indications d’interface/schéma +avant que l’exécution complète ne soit active. ### Plugins de canal et outil de message partagé -Les plugins de canal n’ont pas besoin d’enregistrer un outil séparé d’envoi/édition/réaction pour -les actions de chat normales. OpenClaw conserve un outil `message` partagé dans le cœur, et -les plugins de canal possèdent la découverte et l’exécution spécifiques au canal qui se trouvent derrière. +Les plugins de canal n’ont pas besoin d’enregistrer un outil séparé +d’envoi/modification/réaction pour les actions de chat normales. OpenClaw conserve +un unique outil `message` partagé dans le cœur, et les plugins de canal possèdent +la découverte et l’exécution spécifiques au canal derrière celui-ci. La limite actuelle est la suivante : - le cœur possède l’hôte de l’outil `message` partagé, le câblage des prompts, la - tenue des sessions/fils et la répartition de l’exécution -- les plugins de canal possèdent la découverte d’actions délimitées, la découverte des - capacités et tout fragment de schéma spécifique au canal -- les plugins de canal possèdent la grammaire de conversation de session spécifique au fournisseur, comme - la manière dont les identifiants de conversation encodent les identifiants de fil ou héritent des conversations parentes + tenue de session/thread et la répartition de l’exécution +- les plugins de canal possèdent la découverte des actions à portée, la + découverte des capacités et tous les fragments de schéma spécifiques au canal +- les plugins de canal possèdent la grammaire de conversation de session + spécifique au fournisseur, comme la façon dont les identifiants de conversation + encodent les identifiants de thread ou héritent des conversations parentes - les plugins de canal exécutent l’action finale via leur adaptateur d’action Pour les plugins de canal, la surface SDK est -`ChannelMessageActionAdapter.describeMessageTool(...)`. Cet appel de découverte unifié -permet à un plugin de renvoyer ensemble ses actions visibles, ses capacités et ses contributions au schéma, -afin que ces éléments ne divergent pas. +`ChannelMessageActionAdapter.describeMessageTool(...)`. Cet appel de découverte +unifié permet à un plugin de renvoyer ensemble ses actions visibles, ses +capacités et ses contributions au schéma afin que ces éléments ne divergent pas. -Le cœur transmet la portée d’exécution à cette étape de découverte. Les champs importants incluent : +Le cœur transmet la portée d’exécution à cette étape de découverte. Les champs +importants incluent : - `accountId` - `currentChannelId` @@ -178,115 +198,136 @@ Le cœur transmet la portée d’exécution à cette étape de découverte. Les - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` entrant approuvé +- `requesterSenderId` entrant de confiance -C’est important pour les plugins sensibles au contexte. Un canal peut masquer ou exposer -des actions de message en fonction du compte actif, de la salle/du fil/du message courant, ou de -l’identité de demandeur approuvée, sans coder en dur des branches spécifiques au canal dans -l’outil `message` du cœur. +C’est important pour les plugins sensibles au contexte. Un canal peut masquer ou +exposer des actions de message selon le compte actif, la salle/le thread/le +message actuel, ou l’identité fiable du demandeur, sans coder en dur des branches +spécifiques à un canal dans l’outil `message` du cœur. -C’est pourquoi les modifications de routage de l’embedded-runner restent du travail de plugin : le runner est -responsable de transmettre l’identité actuelle du chat/de la session à la limite de découverte du plugin afin que -l’outil `message` partagé expose la bonne surface appartenant au canal pour le tour courant. +C’est pourquoi les changements de routage embedded-runner restent du travail de +plugin : le runner est responsable de transmettre l’identité actuelle du +chat/de la session à la limite de découverte du plugin afin que l’outil `message` +partagé expose la bonne surface appartenant au canal pour le tour courant. -Pour les assistants d’exécution appartenant aux canaux, les plugins bundled doivent conserver l’exécution -dans leurs propres modules d’extension. Le cœur ne possède plus les environnements d’exécution d’actions de message -Discord, Slack, Telegram ou WhatsApp sous `src/agents/tools`. -Nous ne publions pas de sous-chemins `plugin-sdk/*-action-runtime` séparés, et les plugins bundled -doivent importer directement leur propre code d’exécution local depuis leurs -modules appartenant à l’extension. +Pour les helpers d’exécution appartenant au canal, les plugins bundled doivent +conserver le runtime d’exécution dans leurs propres modules d’extension. Le cœur +ne possède plus les runtimes d’actions de message Discord, Slack, Telegram ou +WhatsApp sous `src/agents/tools`. +Nous ne publions pas de sous-chemins `plugin-sdk/*-action-runtime` séparés, et les +plugins bundled doivent importer directement leur propre code d’exécution local +depuis leurs modules appartenant à l’extension. -La même limite s’applique de manière générale aux points d’intégration SDK nommés d’après un fournisseur : -le cœur ne doit pas importer de barils de commodité spécifiques à un canal pour Slack, Discord, Signal, -WhatsApp ou des extensions similaires. Si le cœur a besoin d’un comportement, il doit soit consommer -le propre baril `api.ts` / `runtime-api.ts` du plugin bundled, soit faire évoluer le besoin -vers une capacité générique étroite dans le SDK partagé. +La même limite s’applique en général aux coutures SDK nommées par fournisseur : +le cœur ne doit pas importer de barrels pratiques spécifiques à un canal pour +Slack, Discord, Signal, WhatsApp ou des extensions similaires. Si le cœur a +besoin d’un comportement, soit il consomme le barrel `api.ts` / `runtime-api.ts` +du plugin bundled lui-même, soit il promeut ce besoin en une capacité générique +étroite dans le SDK partagé. Pour les sondages en particulier, il existe deux chemins d’exécution : -- `outbound.sendPoll` est la base partagée pour les canaux qui correspondent au modèle de sondage commun -- `actions.handleAction("poll")` est le chemin préféré pour la sémantique de sondage spécifique au canal ou pour des paramètres de sondage supplémentaires +- `outbound.sendPoll` est la base partagée pour les canaux qui correspondent au + modèle commun de sondage +- `actions.handleAction("poll")` est le chemin privilégié pour la sémantique de + sondage spécifique à un canal ou pour des paramètres de sondage supplémentaires -Le cœur diffère désormais l’analyse partagée des sondages jusqu’à ce que la répartition du sondage par plugin décline -l’action, afin que les gestionnaires de sondages appartenant au plugin puissent accepter des champs -de sondage spécifiques au canal sans être bloqués d’abord par l’analyseur générique de sondages. +Le cœur reporte désormais l’analyse partagée des sondages jusqu’à ce que la +répartition des sondages du plugin refuse l’action, afin que les gestionnaires +de sondage appartenant au plugin puissent accepter des champs de sondage +spécifiques au canal sans être bloqués d’abord par l’analyseur générique de sondages. Voir [Pipeline de chargement](#load-pipeline) pour la séquence complète de démarrage. ## Modèle de propriété des capacités -OpenClaw considère un plugin natif comme la limite de propriété pour une **entreprise** ou une -**fonctionnalité**, et non comme un regroupement d’intégrations sans lien. +OpenClaw traite un plugin natif comme la limite de propriété pour une **entreprise** +ou une **fonctionnalité**, et non comme un fourre-tout d’intégrations sans lien. Cela signifie : -- un plugin d’entreprise doit généralement posséder toutes les surfaces OpenClaw de cette entreprise -- un plugin de fonctionnalité doit généralement posséder l’ensemble de la surface de la fonctionnalité qu’il introduit -- les canaux doivent consommer les capacités partagées du cœur au lieu de réimplémenter de manière ad hoc le comportement des fournisseurs +- un plugin d’entreprise devrait généralement posséder toutes les surfaces + OpenClaw orientées vers cette entreprise +- un plugin de fonctionnalité devrait généralement posséder toute la surface de + la fonctionnalité qu’il introduit +- les canaux devraient consommer les capacités partagées du cœur au lieu de + réimplémenter de manière ad hoc le comportement des fournisseurs Exemples : -- le plugin bundled `openai` possède le comportement de fournisseur de modèles OpenAI et le comportement OpenAI pour la parole + la voix en temps réel + la compréhension des médias + la génération d’images -- le plugin bundled `elevenlabs` possède le comportement de parole ElevenLabs -- le plugin bundled `microsoft` possède le comportement de parole Microsoft -- le plugin bundled `google` possède le comportement de fournisseur de modèles Google ainsi que les comportements Google de compréhension des médias + génération d’images + recherche web +- le plugin bundled `openai` possède le comportement de fournisseur de modèles OpenAI + et le comportement OpenAI de voix + voix en temps réel + compréhension des médias + + génération d’images +- le plugin bundled `elevenlabs` possède le comportement de voix ElevenLabs +- le plugin bundled `microsoft` possède le comportement de voix Microsoft +- le plugin bundled `google` possède le comportement de fournisseur de modèles Google + ainsi que le comportement Google de compréhension des médias + génération d’images + + recherche web - le plugin bundled `firecrawl` possède le comportement de récupération web Firecrawl -- les plugins bundled `minimax`, `mistral`, `moonshot` et `zai` possèdent leurs backends de compréhension des médias -- le plugin bundled `qwen` possède le comportement de fournisseur de texte Qwen ainsi que les comportements de compréhension des médias et de génération de vidéos -- le plugin `voice-call` est un plugin de fonctionnalité : il possède le transport d’appel, les outils, - la CLI, les routes et le pontage de flux média Twilio, mais il consomme les capacités partagées de parole, - plus la transcription en temps réel et la voix en temps réel au lieu d’importer directement les plugins fournisseurs +- les plugins bundled `minimax`, `mistral`, `moonshot` et `zai` possèdent leurs + backends de compréhension des médias +- le plugin bundled `qwen` possède le comportement de fournisseur de texte Qwen ainsi + que les comportements de compréhension des médias et de génération de vidéo +- le plugin `voice-call` est un plugin de fonctionnalité : il possède le + transport d’appel, les outils, la CLI, les routes et le pont Twilio media-stream, + mais il consomme les capacités partagées de voix ainsi que de transcription en + temps réel et de voix en temps réel au lieu d’importer directement des plugins fournisseurs L’état final visé est : -- OpenAI se trouve dans un seul plugin même s’il couvre les modèles de texte, la parole, les images et, à l’avenir, la vidéo -- un autre fournisseur peut faire de même pour sa propre surface fonctionnelle -- les canaux ne se soucient pas du plugin fournisseur qui possède le fournisseur ; ils consomment le contrat de capacité partagé exposé par le cœur +- OpenAI vit dans un seul plugin même s’il couvre les modèles de texte, la + voix, les images et la future vidéo +- un autre fournisseur peut faire de même pour sa propre surface +- les canaux ne se préoccupent pas de savoir quel plugin fournisseur possède le + provider ; ils consomment le contrat de capacité partagé exposé par le cœur C’est la distinction clé : - **plugin** = limite de propriété - **capability** = contrat du cœur que plusieurs plugins peuvent implémenter ou consommer -Ainsi, si OpenClaw ajoute un nouveau domaine comme la vidéo, la première question n’est pas -« quel fournisseur doit coder en dur la gestion de la vidéo ? » La première question est « quel est -le contrat de capacité vidéo du cœur ? » Une fois ce contrat en place, les plugins fournisseurs -peuvent s’y enregistrer et les plugins de canal/de fonctionnalité peuvent le consommer. +Donc, si OpenClaw ajoute un nouveau domaine comme la vidéo, la première question +n’est pas +« quel fournisseur devrait coder en dur la gestion de la vidéo ? » La première +question est « quel est le contrat de capacité vidéo du cœur ? » Une fois ce +contrat en place, les plugins fournisseurs peuvent s’y enregistrer et les +plugins de canal/fonctionnalité peuvent le consommer. Si la capacité n’existe pas encore, la bonne démarche est généralement : 1. définir la capacité manquante dans le cœur -2. l’exposer de manière typée via l’API/l’exécution des plugins +2. l’exposer de manière typée via l’API/runtime des plugins 3. raccorder les canaux/fonctionnalités à cette capacité -4. laisser les plugins fournisseurs enregistrer les implémentations +4. laisser les plugins fournisseurs enregistrer des implémentations -Cela permet de garder une propriété explicite tout en évitant un comportement du cœur qui dépend -d’un seul fournisseur ou d’un chemin de code spécifique à un plugin ponctuel. +Cela garde une propriété explicite tout en évitant un comportement du cœur qui +dépend d’un seul fournisseur ou d’un chemin de code spécifique à un plugin +ponctuel. -### Stratification des capacités +### Superposition des capacités Utilisez ce modèle mental pour décider où le code doit se trouver : -- **couche de capacité du cœur** : orchestration partagée, politique, repli, - règles de fusion de configuration, sémantique de livraison et contrats typés -- **couche de plugin fournisseur** : API spécifiques au fournisseur, authentification, catalogues de modèles, synthèse vocale, - génération d’images, backends vidéo futurs, points de terminaison d’usage +- **couche de capacité du cœur** : orchestration partagée, politique, fallback, règles de + fusion de configuration, sémantique de livraison et contrats typés +- **couche de plugin fournisseur** : API spécifiques au fournisseur, authentification, catalogues de + modèles, synthèse vocale, génération d’images, futurs backends vidéo, points de terminaison d’usage - **couche de plugin de canal/fonctionnalité** : intégration Slack/Discord/voice-call/etc. qui consomme les capacités du cœur et les présente sur une surface -Par exemple, la synthèse vocale suit cette forme : +Par exemple, la TTS suit cette forme : -- le cœur possède la politique TTS au moment de la réponse, l’ordre de repli, les préférences et la livraison au canal +- le cœur possède la politique TTS au moment de la réponse, l’ordre de fallback, les préférences et la livraison par canal - `openai`, `elevenlabs` et `microsoft` possèdent les implémentations de synthèse -- `voice-call` consomme l’assistant d’exécution TTS de téléphonie +- `voice-call` consomme le helper d’exécution TTS de téléphonie -Ce même schéma doit être privilégié pour les capacités futures. +Ce même modèle doit être préféré pour les futures capacités. ### Exemple de plugin d’entreprise multi-capacités -Un plugin d’entreprise doit sembler cohérent de l’extérieur. Si OpenClaw a des -contrats partagés pour les modèles, la parole, la transcription en temps réel, la voix en temps réel, la -compréhension des médias, la génération d’images, la génération de vidéos, la récupération web et la recherche web, +Un plugin d’entreprise doit sembler cohérent vu de l’extérieur. Si OpenClaw a des +contrats partagés pour les modèles, la voix, la transcription en temps réel, la voix en temps réel, la +compréhension des médias, la génération d’images, la génération de vidéo, la récupération web et la recherche web, un fournisseur peut posséder toutes ses surfaces au même endroit : ```ts @@ -302,12 +343,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hooks d’authentification/de catalogue de modèles/d’exécution + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // config de parole du fournisseur — implémente directement l’interface SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -332,7 +373,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // logique d’identifiants + de récupération + // credential + fetch logic }), ); }, @@ -341,62 +382,64 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Ce qui compte, ce ne sont pas les noms exacts des assistants. C’est la forme qui compte : +Ce qui importe n’est pas le nom exact des helpers. C’est la forme qui compte : - un seul plugin possède la surface du fournisseur - le cœur possède toujours les contrats de capacité -- les canaux et plugins de fonctionnalité consomment les assistants `api.runtime.*`, pas le code du fournisseur +- les plugins de canal et de fonctionnalité consomment les helpers `api.runtime.*`, pas du code fournisseur - les tests de contrat peuvent vérifier que le plugin a enregistré les capacités qu’il prétend posséder ### Exemple de capacité : compréhension vidéo -OpenClaw traite déjà la compréhension d’image/audio/vidéo comme une seule -capacité partagée. Le même modèle de propriété s’y applique : +OpenClaw traite déjà la compréhension des images, de l’audio et de la vidéo comme une +capacité partagée unique. Le même modèle de propriété s’y applique : 1. le cœur définit le contrat de compréhension des médias 2. les plugins fournisseurs enregistrent `describeImage`, `transcribeAudio` et `describeVideo` selon le cas -3. les canaux et plugins de fonctionnalité consomment le comportement partagé du cœur au lieu de +3. les plugins de canal et de fonctionnalité consomment le comportement partagé du cœur au lieu de se raccorder directement au code du fournisseur -Cela évite d’intégrer dans le cœur les hypothèses vidéo d’un seul fournisseur. Le plugin possède -la surface du fournisseur ; le cœur possède le contrat de capacité et le comportement de repli. +Cela évite d’intégrer dans le cœur les hypothèses vidéo d’un fournisseur en particulier. Le plugin possède +la surface du fournisseur ; le cœur possède le contrat de capacité et le comportement de fallback. -La génération vidéo utilise déjà cette même séquence : le cœur possède le -contrat de capacité typé et l’assistant d’exécution, et les plugins fournisseurs enregistrent -des implémentations `api.registerVideoGenerationProvider(...)` sur cette base. +La génération de vidéo suit déjà cette même séquence : le cœur possède le contrat de +capacité typé et le helper d’exécution, et les plugins fournisseurs enregistrent +des implémentations `api.registerVideoGenerationProvider(...)` dessus. -Besoin d’une liste de déploiement concrète ? Voir -[Recettes de capacités](/fr/plugins/architecture). +Besoin d’une checklist de déploiement concrète ? Voir +[Recueil de recettes des capacités](/fr/plugins/architecture). ## Contrats et application -La surface de l’API des plugins est intentionnellement typée et centralisée dans +La surface de l’API des plugins est volontairement typée et centralisée dans `OpenClawPluginApi`. Ce contrat définit les points d’enregistrement pris en charge et -les assistants d’exécution sur lesquels un plugin peut s’appuyer. +les helpers d’exécution sur lesquels un plugin peut s’appuyer. Pourquoi c’est important : -- les auteurs de plugins bénéficient d’une norme interne stable -- le cœur peut rejeter une propriété en double, par exemple deux plugins enregistrant le même identifiant de fournisseur +- les auteurs de plugins disposent d’une norme interne stable unique +- le cœur peut rejeter les propriétés dupliquées, comme deux plugins qui enregistrent le même + id de provider - le démarrage peut afficher des diagnostics exploitables pour un enregistrement mal formé -- les tests de contrat peuvent imposer la propriété des plugins bundled et éviter les dérives silencieuses +- les tests de contrat peuvent faire respecter la propriété des plugins bundled et empêcher toute dérive silencieuse Il existe deux couches d’application : 1. **application de l’enregistrement à l’exécution** - Le registre des plugins valide les enregistrements à mesure que les plugins se chargent. Exemples : - les identifiants de fournisseurs en double, les identifiants de fournisseurs de parole en double, et les + Le registre des plugins valide les enregistrements au chargement des plugins. Exemples : + des ids de provider dupliqués, des ids de fournisseur vocal dupliqués et des enregistrements mal formés produisent des diagnostics de plugin au lieu d’un comportement indéfini. 2. **tests de contrat** Les plugins bundled sont capturés dans des registres de contrat pendant les exécutions de test afin - qu’OpenClaw puisse affirmer explicitement la propriété. Aujourd’hui, cela est utilisé pour les - fournisseurs de modèles, fournisseurs de parole, fournisseurs de recherche web et la propriété de l’enregistrement bundled. + qu’OpenClaw puisse vérifier explicitement la propriété. Aujourd’hui, cela est utilisé pour les + fournisseurs de modèles, les fournisseurs vocaux, les fournisseurs de recherche web et la propriété + d’enregistrement bundled. L’effet pratique est qu’OpenClaw sait, dès le départ, quel plugin possède quelle -surface. Cela permet au cœur et aux canaux de se composer de manière fluide parce que la propriété est -déclarée, typée et testable plutôt qu’implicite. +surface. Cela permet au cœur et aux canaux de se composer sans friction, car la +propriété est déclarée, typée et testable plutôt qu’implicite. ### Ce qui a sa place dans un contrat @@ -407,18 +450,18 @@ Les bons contrats de plugin sont : - spécifiques à une capacité - possédés par le cœur - réutilisables par plusieurs plugins -- consommables par les canaux/fonctionnalités sans connaissance d’un fournisseur +- consommables par des canaux/fonctionnalités sans connaissance du fournisseur Les mauvais contrats de plugin sont : -- une politique spécifique au fournisseur cachée dans le cœur -- des échappatoires ponctuelles de plugin qui contournent le registre -- du code de canal qui accède directement à une implémentation de fournisseur -- des objets d’exécution ad hoc qui ne font pas partie de `OpenClawPluginApi` ou de - `api.runtime` +- une politique spécifique à un fournisseur cachée dans le cœur +- des échappatoires ponctuelles pour un plugin qui contournent le registre +- du code de canal qui accède directement à une implémentation fournisseur +- des objets d’exécution ad hoc qui ne font pas partie de `OpenClawPluginApi` ou + de `api.runtime` -En cas de doute, élevez le niveau d’abstraction : définissez d’abord la capacité, puis -laissez les plugins s’y brancher. +En cas de doute, augmentez le niveau d’abstraction : définissez d’abord la +capacité, puis laissez les plugins s’y brancher. ## Modèle d’exécution @@ -430,51 +473,52 @@ Implications : - un plugin natif peut enregistrer des outils, des gestionnaires réseau, des hooks et des services - un bug dans un plugin natif peut faire planter ou déstabiliser la gateway -- un plugin natif malveillant équivaut à une exécution de code arbitraire dans le processus OpenClaw +- un plugin natif malveillant équivaut à une exécution de code arbitraire dans + le processus OpenClaw Les bundles compatibles sont plus sûrs par défaut parce qu’OpenClaw les traite actuellement -comme des packs de métadonnées/contenu. Dans les versions actuelles, cela signifie surtout des +comme des packs de métadonnées/de contenu. Dans les versions actuelles, cela signifie surtout des Skills bundled. -Utilisez des listes d’autorisation et des chemins d’installation/de chargement explicites pour les plugins non bundled. Traitez -les plugins d’espace de travail comme du code de développement, et non comme des valeurs par défaut de production. +Utilisez des listes d’autorisation et des chemins explicites d’installation/chargement pour les plugins non bundled. Considérez +les plugins d’espace de travail comme du code de développement, pas comme des valeurs par défaut de production. -Pour les noms de packages d’espace de travail bundled, gardez l’identifiant du plugin ancré dans le nom npm : -`@openclaw/` par défaut, ou un suffixe typé approuvé tel que -`-provider`, `-plugin`, `-speech`, `-sandbox` ou `-media-understanding` lorsque +Pour les noms de packages bundled de l’espace de travail, gardez l’id du plugin ancré dans le nom npm : +`@openclaw/` par défaut, ou un suffixe typé approuvé comme +`-provider`, `-plugin`, `-speech`, `-sandbox` ou `-media-understanding` quand le package expose intentionnellement un rôle de plugin plus étroit. Note de confiance importante : -- `plugins.allow` fait confiance aux **identifiants de plugin**, et non à la provenance de la source. -- Un plugin d’espace de travail portant le même identifiant qu’un plugin bundled masque intentionnellement - la copie bundled lorsque ce plugin d’espace de travail est activé/sur liste d’autorisation. -- C’est normal et utile pour le développement local, les tests de correctifs et les correctifs urgents. +- `plugins.allow` fait confiance aux **ids de plugin**, pas à la provenance de la source. +- Un plugin d’espace de travail avec le même id qu’un plugin bundled masque + intentionnellement la copie bundled lorsque ce plugin d’espace de travail est activé/autorisé. +- C’est normal et utile pour le développement local, les tests de correctifs et les hotfixes. ## Limite d’export OpenClaw exporte des capacités, pas des commodités d’implémentation. -Gardez l’enregistrement des capacités public. Réduisez les exports d’assistance hors contrat : +Conservez public l’enregistrement des capacités. Réduisez les exports helper hors contrat : -- sous-chemins d’assistance spécifiques à un plugin bundled -- sous-chemins de plomberie d’exécution non destinés à l’API publique -- assistants de commodité spécifiques à un fournisseur -- assistants de configuration/d’onboarding qui sont des détails d’implémentation +- sous-chemins helpers spécifiques à des plugins bundled +- sous-chemins de plomberie d’exécution non destinés à être une API publique +- helpers pratiques spécifiques à un fournisseur +- helpers de configuration/d’onboarding qui sont des détails d’implémentation -Certains sous-chemins d’assistance de plugins bundled restent encore présents dans la carte d’exports SDK générée +Certains sous-chemins helpers de plugins bundled restent encore dans la table d’exports générée du SDK pour des raisons de compatibilité et de maintenance des plugins bundled. Exemples actuels : `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup`, et plusieurs points d’intégration `plugin-sdk/matrix*`. Traitez-les comme des -exports réservés de détail d’implémentation, et non comme le modèle SDK recommandé pour -de nouveaux plugins tiers. +`plugin-sdk/zalo-setup` et plusieurs coutures `plugin-sdk/matrix*`. Considérez-les comme +des exports réservés de détail d’implémentation, et non comme le modèle SDK recommandé pour +les nouveaux plugins tiers. ## Pipeline de chargement -Au démarrage, OpenClaw fait grosso modo ceci : +Au démarrage, OpenClaw fait globalement ceci : -1. découvre les racines de plugins candidates -2. lit les manifestes natifs ou de bundles compatibles et les métadonnées de package +1. découvre les racines candidates des plugins +2. lit les manifests natifs ou les manifests de bundles compatibles et les métadonnées de package 3. rejette les candidats non sûrs 4. normalise la configuration des plugins (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) @@ -484,42 +528,48 @@ Au démarrage, OpenClaw fait grosso modo ceci : 8. expose le registre aux surfaces de commandes/d’exécution -`activate` est un alias legacy de `register` — le chargeur résout celui qui est présent (`def.register ?? def.activate`) et l’appelle au même moment. Tous les plugins bundled utilisent `register` ; préférez `register` pour les nouveaux plugins. +`activate` est un alias legacy de `register` — le chargeur résout celui qui est présent (`def.register ?? def.activate`) et l’appelle au même point. Tous les plugins bundled utilisent `register` ; préférez `register` pour les nouveaux plugins. -Les barrières de sécurité interviennent **avant** l’exécution à l’exécution. Les candidats sont bloqués -lorsque le point d’entrée sort de la racine du plugin, que le chemin est accessible en écriture par tout le monde, ou que la propriété du chemin semble suspecte pour les plugins non bundled. +Les garde-fous de sécurité s’appliquent **avant** l’exécution du runtime. Les candidats sont bloqués +lorsque l’entrée s’échappe de la racine du plugin, que le chemin est accessible en écriture par tous, ou que la propriété du chemin semble suspecte pour les plugins non bundled. ### Comportement manifest-first -Le manifeste est la source de vérité du plan de contrôle. OpenClaw l’utilise pour : +Le manifest est la source de vérité du plan de contrôle. OpenClaw l’utilise pour : - identifier le plugin - découvrir les canaux/Skills/schéma de configuration déclarés ou les capacités de bundle - valider `plugins.entries..config` -- enrichir les libellés/placeholders de l’interface de contrôle +- enrichir les libellés/placeholders de l’interface Control UI - afficher les métadonnées d’installation/de catalogue -- conserver des descripteurs bon marché d’activation et de configuration sans charger l’exécution du plugin +- préserver des descripteurs légers d’activation et de configuration sans charger le runtime du plugin -Pour les plugins natifs, le module d’exécution est la partie plan de données. Il enregistre le -comportement réel tel que hooks, outils, commandes ou flux de fournisseur. +Pour les plugins natifs, le module runtime est la partie plan de données. Il enregistre le +comportement réel comme les hooks, outils, commandes ou flux de fournisseur. -Les blocs facultatifs `activation` et `setup` du manifeste restent sur le plan de contrôle. -Ce sont des descripteurs de métadonnées uniquement pour la planification d’activation et la découverte de configuration ; -ils ne remplacent pas l’enregistrement d’exécution, `register(...)` ou `setupEntry`. +Les blocs optionnels `activation` et `setup` du manifest restent dans le plan de contrôle. +Ce sont uniquement des descripteurs de métadonnées pour la planification d’activation et la découverte de configuration ; +ils ne remplacent ni l’enregistrement au runtime, ni `register(...)`, ni `setupEntry`. + +La découverte de configuration préfère désormais les ids appartenant aux descripteurs comme +`setup.providers` et `setup.cliBackends` afin de restreindre les plugins candidats avant de revenir à +`setup-api` pour les plugins qui ont encore besoin de hooks runtime au moment de la configuration. Si plus +d’un plugin découvert revendique le même id normalisé de fournisseur de configuration ou de backend CLI, +la recherche de configuration refuse ce propriétaire ambigu au lieu de s’appuyer sur l’ordre de découverte. ### Ce que le chargeur met en cache OpenClaw conserve de courts caches en processus pour : - les résultats de découverte -- les données du registre de manifestes +- les données du registre de manifests - les registres de plugins chargés -Ces caches réduisent les démarrages brusques et la surcharge des commandes répétées. On peut les considérer sans danger -comme des caches de performance à courte durée de vie, et non comme de la persistance. +Ces caches réduisent les pointes de démarrage et le coût des commandes répétées. Il faut les considérer +comme des caches de performance de courte durée, pas comme une persistance. -Note sur les performances : +Note de performance : - Définissez `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` ou `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` pour désactiver ces caches. @@ -528,37 +578,38 @@ Note sur les performances : ## Modèle de registre -Les plugins chargés ne mutent pas directement des variables globales arbitraires du cœur. Ils s’enregistrent dans un +Les plugins chargés ne modifient pas directement des globales arbitraires du cœur. Ils s’enregistrent dans un registre central des plugins. Le registre suit : -- les enregistrements de plugins (identité, source, origine, statut, diagnostics) +- les enregistrements de plugin (identité, source, origine, statut, diagnostics) - les outils -- les hooks legacy et hooks typés +- les hooks legacy et les hooks typés - les canaux -- les fournisseurs -- les gestionnaires Gateway RPC +- les providers +- les gestionnaires RPC Gateway - les routes HTTP -- les enregistreurs CLI -- les services d’arrière-plan +- les registrars CLI +- les services en arrière-plan - les commandes appartenant au plugin Les fonctionnalités du cœur lisent ensuite ce registre au lieu de parler directement aux modules de plugin. -Cela maintient un chargement à sens unique : +Cela garde le chargement à sens unique : - module de plugin -> enregistrement dans le registre -- exécution du cœur -> consommation du registre +- runtime du cœur -> consommation du registre -Cette séparation est importante pour la maintenabilité. Cela signifie que la plupart des surfaces du cœur n’ont besoin -que d’un seul point d’intégration : « lire le registre », et non « traiter spécialement chaque module de plugin ». +Cette séparation est importante pour la maintenabilité. Elle signifie que la plupart des surfaces du cœur +n’ont besoin que d’un seul point d’intégration : « lire le registre », et non « traiter spécialement chaque module +de plugin ». ## Callbacks de liaison de conversation Les plugins qui lient une conversation peuvent réagir lorsqu’une approbation est résolue. Utilisez `api.onConversationBindingResolved(...)` pour recevoir un callback après qu’une requête de liaison -est approuvée ou refusée : +a été approuvée ou refusée : ```ts export default { @@ -566,12 +617,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Une liaison existe maintenant pour ce plugin + cette conversation. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // La requête a été refusée ; effacez tout état local en attente. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, @@ -580,25 +631,25 @@ export default { Champs de la charge utile du callback : -- `status`: `"approved"` ou `"denied"` -- `decision`: `"allow-once"`, `"allow-always"` ou `"deny"` -- `binding`: la liaison résolue pour les requêtes approuvées -- `request`: le résumé de la requête d’origine, l’indication de détachement, l’identifiant de l’expéditeur et +- `status` : `"approved"` ou `"denied"` +- `decision` : `"allow-once"`, `"allow-always"` ou `"deny"` +- `binding` : la liaison résolue pour les requêtes approuvées +- `request` : le résumé de la requête d’origine, l’indication de détachement, l’id de l’expéditeur et les métadonnées de conversation -Ce callback est uniquement une notification. Il ne modifie pas qui est autorisé à lier une +Ce callback sert uniquement de notification. Il ne modifie pas qui est autorisé à lier une conversation, et il s’exécute une fois le traitement d’approbation du cœur terminé. -## Hooks d’exécution du fournisseur +## Hooks d’exécution des fournisseurs -Les plugins de fournisseur ont désormais deux couches : +Les plugins fournisseurs ont désormais deux couches : -- métadonnées de manifeste : `providerAuthEnvVars` pour une recherche légère de l’authentification du fournisseur par variable d’environnement - avant le chargement de l’exécution, `providerAuthAliases` pour les variantes de fournisseur qui partagent - l’authentification, `channelEnvVars` pour une recherche légère de l’environnement/de la configuration du canal avant le - chargement de l’exécution, ainsi que `providerAuthChoices` pour des libellés légers d’onboarding/de choix d’authentification et - des métadonnées d’indicateurs CLI avant le chargement de l’exécution -- hooks au moment de la configuration : `catalog` / ancien `discovery` plus `applyConfigDefaults` +- métadonnées de manifest : `providerAuthEnvVars` pour une recherche légère de l’authentification fournisseur via variables d’environnement + avant le chargement du runtime, `providerAuthAliases` pour les variantes de fournisseur qui partagent + l’authentification, `channelEnvVars` pour une recherche légère de l’environnement/de la configuration du canal avant le chargement + du runtime, ainsi que `providerAuthChoices` pour des libellés légers d’onboarding/de choix d’authentification et + des métadonnées d’options CLI avant le chargement du runtime +- hooks au moment de la configuration : `catalog` / ancien `discovery` ainsi que `applyConfigDefaults` - hooks d’exécution : `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -619,87 +670,88 @@ Les plugins de fournisseur ont désormais deux couches : `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw possède toujours la boucle d’agent générique, le basculement, la gestion des transcriptions et +OpenClaw possède toujours la boucle d’agent générique, le failover, la gestion des transcriptions et la politique des outils. Ces hooks constituent la surface d’extension pour le comportement spécifique au fournisseur sans avoir besoin d’un transport d’inférence entièrement personnalisé. -Utilisez le `providerAuthEnvVars` du manifeste lorsque le fournisseur dispose d’identifiants basés sur l’environnement -que les chemins génériques d’authentification/statut/sélecteur de modèle doivent voir sans charger l’exécution du plugin. -Utilisez `providerAuthAliases` du manifeste lorsqu’un identifiant de fournisseur doit réutiliser -les variables d’environnement, profils d’authentification, authentification basée sur la configuration et choix d’onboarding par clé API d’un autre identifiant de fournisseur. -Utilisez `providerAuthChoices` du manifeste lorsque les -surfaces CLI d’onboarding/de choix d’authentification doivent connaître l’identifiant de choix du fournisseur, les libellés de groupe et le câblage simple d’authentification par indicateur unique sans charger l’exécution du fournisseur. Conservez `envVars` de l’exécution du fournisseur pour les indications destinées à l’opérateur, comme les libellés d’onboarding ou les -variables de configuration de client OAuth `client-id`/`client-secret`. +Utilisez le `providerAuthEnvVars` du manifest lorsque le fournisseur dispose d’identifiants basés sur des variables d’environnement +que les chemins génériques d’authentification/statut/sélecteur de modèles doivent voir sans charger le runtime du plugin. +Utilisez `providerAuthAliases` du manifest lorsqu’un id de provider doit réutiliser les variables d’environnement, +les profils d’authentification, l’authentification adossée à la configuration et le choix d’onboarding par clé API d’un autre id de provider. +Utilisez `providerAuthChoices` du manifest lorsque les surfaces CLI d’onboarding/de choix d’authentification +doivent connaître l’id de choix du fournisseur, les libellés de groupe et un câblage simple d’authentification à une seule option +sans charger le runtime du fournisseur. Conservez `envVars` dans le runtime du fournisseur pour les indications destinées aux opérateurs, +comme les libellés d’onboarding ou les variables de configuration de client-id/client-secret OAuth. -Utilisez `channelEnvVars` du manifeste lorsqu’un canal possède une authentification ou une configuration pilotée par l’environnement -que le repli générique sur l’environnement shell, les vérifications config/statut ou les invites de configuration doivent voir -sans charger l’exécution du canal. +Utilisez `channelEnvVars` du manifest lorsqu’un canal a une authentification ou une configuration pilotée par environnement que +le fallback générique de shell-env, les vérifications de configuration/statut ou les invites de configuration doivent voir +sans charger le runtime du canal. ### Ordre et usage des hooks -Pour les plugins de modèle/fournisseur, OpenClaw appelle les hooks approximativement dans cet ordre. -La colonne « Quand l’utiliser » sert de guide rapide de décision. +Pour les plugins de modèle/fournisseur, OpenClaw appelle les hooks dans cet ordre approximatif. +La colonne « Quand l’utiliser » est le guide rapide de décision. -| # | Hook | Ce qu’il fait | Quand l’utiliser | -| --- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publie la configuration du fournisseur dans `models.providers` pendant la génération de `models.json` | Le fournisseur possède un catalogue ou des valeurs par défaut de base URL | -| 2 | `applyConfigDefaults` | Applique les valeurs par défaut globales de configuration appartenant au fournisseur pendant la matérialisation de la configuration | Les valeurs par défaut dépendent du mode d’authentification, de l’environnement ou de la sémantique de famille de modèles du fournisseur | -| -- | _(recherche de modèle intégrée)_ | OpenClaw essaie d’abord le chemin normal registre/catalogue | _(pas un hook de plugin)_ | -| 3 | `normalizeModelId` | Normalise les alias legacy ou de préversion des identifiants de modèle avant la recherche | Le fournisseur possède le nettoyage des alias avant la résolution canonique du modèle | -| 4 | `normalizeTransport` | Normalise `api` / `baseUrl` d’une famille de fournisseurs avant l’assemblage générique du modèle | Le fournisseur possède le nettoyage du transport pour des identifiants de fournisseurs personnalisés dans la même famille de transport | -| 5 | `normalizeConfig` | Normalise `models.providers.` avant la résolution d’exécution/du fournisseur | Le fournisseur a besoin d’un nettoyage de configuration qui doit vivre avec le plugin ; les assistants bundled de la famille Google servent aussi de solution de secours pour les entrées de configuration Google prises en charge | -| 6 | `applyNativeStreamingUsageCompat` | Applique aux fournisseurs de configuration des réécritures de compatibilité d’usage en streaming natif | Le fournisseur a besoin de correctifs de métadonnées d’usage en streaming natif pilotés par le point de terminaison | -| 7 | `resolveConfigApiKey` | Résout l’authentification par marqueur d’environnement pour les fournisseurs de configuration avant le chargement de l’authentification d’exécution | Le fournisseur possède sa propre résolution de clé API par marqueur d’environnement ; `amazon-bedrock` a aussi ici un résolveur intégré de marqueur d’environnement AWS | -| 8 | `resolveSyntheticAuth` | Expose une authentification locale/autohébergée ou adossée à la configuration sans persister du texte brut | Le fournisseur peut fonctionner avec un marqueur d’identifiants synthétiques/locaux | -| 9 | `resolveExternalAuthProfiles` | Superpose des profils d’authentification externe appartenant au fournisseur ; `persistence` vaut par défaut `runtime-only` pour les identifiants détenus par la CLI/l’application | Le fournisseur réutilise des identifiants d’authentification externes sans persister de jetons d’actualisation copiés | -| 10 | `shouldDeferSyntheticProfileAuth` | Fait passer les placeholders de profils synthétiques stockés après l’authentification adossée à l’environnement/à la configuration | Le fournisseur stocke des profils placeholders synthétiques qui ne doivent pas avoir la priorité | -| 11 | `resolveDynamicModel` | Repli synchrone pour les identifiants de modèle appartenant au fournisseur qui ne sont pas encore dans le registre local | Le fournisseur accepte des identifiants de modèle amont arbitraires | -| 12 | `prepareDynamicModel` | Préchauffage asynchrone, puis `resolveDynamicModel` s’exécute à nouveau | Le fournisseur a besoin de métadonnées réseau avant de résoudre des identifiants inconnus | -| 13 | `normalizeResolvedModel` | Réécriture finale avant que l’embedded runner n’utilise le modèle résolu | Le fournisseur a besoin de réécritures de transport tout en utilisant toujours un transport du cœur | -| 14 | `contributeResolvedModelCompat` | Contribue des drapeaux de compatibilité pour des modèles fournisseurs derrière un autre transport compatible | Le fournisseur reconnaît ses propres modèles sur des transports proxy sans prendre le contrôle du fournisseur | -| 15 | `capabilities` | Métadonnées de transcription/d’outillage appartenant au fournisseur utilisées par la logique partagée du cœur | Le fournisseur a besoin de particularités de transcription/de famille de fournisseurs | -| 16 | `normalizeToolSchemas` | Normalise les schémas d’outils avant que l’embedded runner ne les voie | Le fournisseur a besoin d’un nettoyage de schéma propre à une famille de transport | -| 17 | `inspectToolSchemas` | Expose des diagnostics de schéma appartenant au fournisseur après normalisation | Le fournisseur veut des avertissements sur les mots-clés sans enseigner au cœur des règles spécifiques au fournisseur | -| 18 | `resolveReasoningOutputMode` | Sélectionne le contrat de sortie de raisonnement natif ou balisé | Le fournisseur a besoin d’une sortie raisonnement/finale balisée au lieu de champs natifs | -| 19 | `prepareExtraParams` | Normalisation des paramètres de requête avant les wrappers génériques d’options de flux | Le fournisseur a besoin de paramètres de requête par défaut ou d’un nettoyage de paramètres par fournisseur | -| 20 | `createStreamFn` | Remplace entièrement le chemin de flux normal par un transport personnalisé | Le fournisseur a besoin d’un protocole filaire personnalisé, et pas seulement d’un wrapper | -| 21 | `wrapStreamFn` | Wrapper de flux après application des wrappers génériques | Le fournisseur a besoin de wrappers de compatibilité pour en-têtes/corps/modèle de requête sans transport personnalisé | -| 22 | `resolveTransportTurnState` | Attache des en-têtes ou métadonnées de transport natives par tour | Le fournisseur veut que les transports génériques envoient une identité de tour native au fournisseur | -| 23 | `resolveWebSocketSessionPolicy` | Attache des en-têtes WebSocket natifs ou une politique de refroidissement de session | Le fournisseur veut que les transports WS génériques ajustent les en-têtes de session ou la politique de repli | -| 24 | `formatApiKey` | Formateur de profil d’authentification : le profil stocké devient la chaîne `apiKey` à l’exécution | Le fournisseur stocke des métadonnées d’authentification supplémentaires et a besoin d’une forme de jeton d’exécution personnalisée | -| 25 | `refreshOAuth` | Remplacement de l’actualisation OAuth pour des points de terminaison d’actualisation personnalisés ou une politique d’échec d’actualisation | Le fournisseur ne correspond pas aux actualisateurs partagés `pi-ai` | -| 26 | `buildAuthDoctorHint` | Indication de réparation ajoutée lorsque l’actualisation OAuth échoue | Le fournisseur a besoin de conseils de réparation d’authentification lui appartenant après l’échec d’actualisation | -| 27 | `matchesContextOverflowError` | Détecteur appartenant au fournisseur des débordements de fenêtre de contexte | Le fournisseur possède des erreurs brutes de débordement que les heuristiques génériques manqueraient | -| 28 | `classifyFailoverReason` | Classification appartenant au fournisseur des raisons de basculement | Le fournisseur peut mapper les erreurs brutes d’API/de transport vers limitation de débit/surcharge/etc. | -| 29 | `isCacheTtlEligible` | Politique de cache de prompt pour les fournisseurs proxy/backhaul | Le fournisseur a besoin d’une régulation TTL du cache spécifique au proxy | -| 30 | `buildMissingAuthMessage` | Remplacement du message générique de récupération en cas d’authentification manquante | Le fournisseur a besoin d’une indication de récupération spécifique au fournisseur en cas d’authentification manquante | -| 31 | `suppressBuiltInModel` | Suppression des modèles amont obsolètes avec indication d’erreur facultative destinée à l’utilisateur | Le fournisseur doit masquer des lignes amont obsolètes ou les remplacer par une indication fournisseur | -| 32 | `augmentModelCatalog` | Lignes de catalogue synthétiques/finales ajoutées après la découverte | Le fournisseur a besoin de lignes synthétiques compatibles vers l’avant dans `models list` et les sélecteurs | -| 33 | `isBinaryThinking` | Bascule de raisonnement marche/arrêt pour les fournisseurs à raisonnement binaire | Le fournisseur n’expose qu’un raisonnement binaire activé/désactivé | -| 34 | `supportsXHighThinking` | Prise en charge du raisonnement `xhigh` pour certains modèles | Le fournisseur veut `xhigh` uniquement sur un sous-ensemble de modèles | -| 35 | `resolveDefaultThinkingLevel` | Niveau `/think` par défaut pour une famille de modèles spécifique | Le fournisseur possède la politique `/think` par défaut pour une famille de modèles | -| 36 | `isModernModelRef` | Détecteur de modèles modernes pour les filtres de profils live et la sélection smoke | Le fournisseur possède la logique de correspondance des modèles préférés live/smoke | -| 37 | `prepareRuntimeAuth` | Échange un identifiant configuré contre le véritable jeton/clé d’exécution juste avant l’inférence | Le fournisseur a besoin d’un échange de jeton ou d’un identifiant de requête de courte durée | -| 38 | `resolveUsageAuth` | Résout les identifiants d’usage/facturation pour `/usage` et les surfaces de statut associées | Le fournisseur a besoin d’une analyse personnalisée des jetons d’usage/de quota ou d’un identifiant d’usage différent | -| 39 | `fetchUsageSnapshot` | Récupère et normalise des instantanés d’usage/de quota spécifiques au fournisseur une fois l’authentification résolue | Le fournisseur a besoin d’un point de terminaison d’usage spécifique au fournisseur ou d’un analyseur de charge utile | -| 40 | `createEmbeddingProvider` | Construit un adaptateur d’embedding appartenant au fournisseur pour la mémoire/la recherche | Le comportement d’embedding mémoire appartient au plugin fournisseur | -| 41 | `buildReplayPolicy` | Renvoie une politique de rejeu qui contrôle la gestion des transcriptions pour le fournisseur | Le fournisseur a besoin d’une politique de transcription personnalisée (par exemple, suppression des blocs de réflexion) | -| 42 | `sanitizeReplayHistory` | Réécrit l’historique de rejeu après le nettoyage générique des transcriptions | Le fournisseur a besoin de réécritures de rejeu spécifiques au fournisseur au-delà des assistants partagés de compaction | -| 43 | `validateReplayTurns` | Validation finale ou remodelage des tours de rejeu avant l’embedded runner | Le transport du fournisseur a besoin d’une validation plus stricte des tours après l’assainissement générique | -| 44 | `onModelSelected` | Exécute des effets de bord post-sélection appartenant au fournisseur | Le fournisseur a besoin de télémétrie ou d’un état appartenant au fournisseur lorsqu’un modèle devient actif | +| # | Hook | Ce qu’il fait | Quand l’utiliser | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Publie la configuration du provider dans `models.providers` pendant la génération de `models.json` | Le provider possède un catalogue ou des valeurs par défaut d’URL de base | +| 2 | `applyConfigDefaults` | Applique les valeurs par défaut globales appartenant au provider pendant la matérialisation de la configuration | Les valeurs par défaut dépendent du mode d’authentification, de l’environnement ou de la sémantique de famille de modèles du provider | +| -- | _(built-in model lookup)_ | OpenClaw essaie d’abord le chemin normal registre/catalogue | _(pas un hook de plugin)_ | +| 3 | `normalizeModelId` | Normalise les alias legacy ou preview d’id de modèle avant la recherche | Le provider possède le nettoyage des alias avant la résolution canonique du modèle | +| 4 | `normalizeTransport` | Normalise `api` / `baseUrl` d’une famille de providers avant l’assemblage générique du modèle | Le provider possède le nettoyage du transport pour des ids de provider personnalisés dans la même famille de transport | +| 5 | `normalizeConfig` | Normalise `models.providers.` avant la résolution du runtime/du provider | Le provider a besoin d’un nettoyage de configuration qui doit vivre avec le plugin ; les helpers bundled de la famille Google servent aussi de filet de sécurité pour les entrées de configuration Google prises en charge | +| 6 | `applyNativeStreamingUsageCompat` | Applique des réécritures de compatibilité d’usage du streaming natif aux providers de configuration | Le provider a besoin de correctifs de métadonnées d’usage du streaming natif pilotés par les points de terminaison | +| 7 | `resolveConfigApiKey` | Résout l’authentification par marqueur d’environnement pour les providers de configuration avant le chargement de l’authentification runtime | Le provider possède sa propre résolution de clé API par marqueur d’environnement ; `amazon-bedrock` a aussi ici un résolveur intégré de marqueur d’environnement AWS | +| 8 | `resolveSyntheticAuth` | Expose une authentification locale/autohébergée ou adossée à la configuration sans persister de texte en clair | Le provider peut fonctionner avec un marqueur d’identifiant synthétique/local | +| 9 | `resolveExternalAuthProfiles` | Superpose des profils d’authentification externes appartenant au provider ; la valeur par défaut de `persistence` est `runtime-only` pour les identifiants appartenant à la CLI/l’application | Le provider réutilise des identifiants d’authentification externes sans persister de jetons d’actualisation copiés | +| 10 | `shouldDeferSyntheticProfileAuth` | Fait passer les placeholders synthétiques stockés derrière l’authentification adossée à l’environnement/à la configuration | Le provider stocke des profils placeholders synthétiques qui ne doivent pas être prioritaires | +| 11 | `resolveDynamicModel` | Fallback synchrone pour des ids de modèle appartenant au provider qui ne sont pas encore dans le registre local | Le provider accepte des ids de modèle arbitraires en amont | +| 12 | `prepareDynamicModel` | Préparation asynchrone, puis `resolveDynamicModel` s’exécute de nouveau | Le provider a besoin de métadonnées réseau avant de résoudre des ids inconnus | +| 13 | `normalizeResolvedModel` | Réécriture finale avant que l’embedded runner n’utilise le modèle résolu | Le provider a besoin de réécritures de transport tout en utilisant un transport du cœur | +| 14 | `contributeResolvedModelCompat` | Contribue des indicateurs de compatibilité pour des modèles fournisseurs derrière un autre transport compatible | Le provider reconnaît ses propres modèles sur des transports proxy sans prendre en charge le provider | +| 15 | `capabilities` | Métadonnées de transcription/d’outillage appartenant au provider utilisées par la logique partagée du cœur | Le provider a besoin de particularités de transcription/de famille de provider | +| 16 | `normalizeToolSchemas` | Normalise les schémas d’outils avant que l’embedded runner ne les voie | Le provider a besoin d’un nettoyage de schéma pour une famille de transports | +| 17 | `inspectToolSchemas` | Expose des diagnostics de schéma appartenant au provider après normalisation | Le provider veut des avertissements de mots-clés sans apprendre au cœur des règles spécifiques au provider | +| 18 | `resolveReasoningOutputMode` | Sélectionne le contrat de sortie de raisonnement natif ou balisé | Le provider a besoin d’une sortie raisonnement/finale balisée plutôt que de champs natifs | +| 19 | `prepareExtraParams` | Normalisation des paramètres de requête avant les wrappers génériques d’options de flux | Le provider a besoin de paramètres de requête par défaut ou d’un nettoyage de paramètres propre au provider | +| 20 | `createStreamFn` | Remplace entièrement le chemin de flux normal par un transport personnalisé | Le provider a besoin d’un protocole filaire personnalisé, pas seulement d’un wrapper | +| 21 | `wrapStreamFn` | Wrapper de flux après application des wrappers génériques | Le provider a besoin de wrappers de compatibilité pour en-têtes/corps de requête/modèle sans transport personnalisé | +| 22 | `resolveTransportTurnState` | Attache des en-têtes ou métadonnées natives par tour de transport | Le provider veut que les transports génériques envoient une identité de tour native au provider | +| 23 | `resolveWebSocketSessionPolicy` | Attache des en-têtes WebSocket natifs ou une politique de refroidissement de session | Le provider veut que les transports WebSocket génériques ajustent les en-têtes de session ou la politique de fallback | +| 24 | `formatApiKey` | Formateur de profil d’authentification : le profil stocké devient la chaîne `apiKey` du runtime | Le provider stocke des métadonnées d’authentification supplémentaires et a besoin d’une forme de jeton runtime personnalisée | +| 25 | `refreshOAuth` | Remplacement de l’actualisation OAuth pour des points de terminaison d’actualisation personnalisés ou une politique d’échec d’actualisation | Le provider ne correspond pas aux actualisateurs partagés `pi-ai` | +| 26 | `buildAuthDoctorHint` | Indice de réparation ajouté quand l’actualisation OAuth échoue | Le provider a besoin de consignes de réparation d’authentification qui lui appartiennent après un échec d’actualisation | +| 27 | `matchesContextOverflowError` | Détecteur d’erreur de débordement de fenêtre de contexte appartenant au provider | Le provider a des erreurs brutes de débordement que les heuristiques génériques ne verraient pas | +| 28 | `classifyFailoverReason` | Classification de raison de failover appartenant au provider | Le provider peut mapper des erreurs brutes d’API/de transport vers limite de débit/surcharge/etc. | +| 29 | `isCacheTtlEligible` | Politique de cache de prompt pour les providers proxy/backhaul | Le provider a besoin d’un filtrage TTL de cache spécifique au proxy | +| 30 | `buildMissingAuthMessage` | Remplacement du message générique de récupération d’authentification manquante | Le provider a besoin d’un indice de récupération d’authentification manquante spécifique au provider | +| 31 | `suppressBuiltInModel` | Suppression de modèles amont obsolètes plus indice d’erreur destiné à l’utilisateur en option | Le provider a besoin de masquer des lignes amont obsolètes ou de les remplacer par un indice fournisseur | +| 32 | `augmentModelCatalog` | Lignes de catalogue synthétiques/finales ajoutées après la découverte | Le provider a besoin de lignes synthétiques de compatibilité future dans `models list` et les sélecteurs | +| 33 | `isBinaryThinking` | Bascule de raisonnement marche/arrêt pour les providers à raisonnement binaire | Le provider n’expose qu’un raisonnement binaire activé/désactivé | +| 34 | `supportsXHighThinking` | Prise en charge du raisonnement `xhigh` pour certains modèles | Le provider veut `xhigh` seulement sur un sous-ensemble de modèles | +| 35 | `resolveDefaultThinkingLevel` | Niveau `/think` par défaut pour une famille de modèles spécifique | Le provider possède la politique `/think` par défaut pour une famille de modèles | +| 36 | `isModernModelRef` | Détecteur de modèle moderne pour les filtres de profils live et la sélection smoke | Le provider possède la correspondance du modèle préféré pour live/smoke | +| 37 | `prepareRuntimeAuth` | Échange un identifiant configuré contre le jeton/la clé runtime réel juste avant l’inférence | Le provider a besoin d’un échange de jeton ou d’un identifiant de requête de courte durée | +| 38 | `resolveUsageAuth` | Résout les identifiants d’usage/de facturation pour `/usage` et les surfaces de statut associées | Le provider a besoin d’une analyse personnalisée du jeton d’usage/quota ou d’un identifiant d’usage différent | +| 39 | `fetchUsageSnapshot` | Récupère et normalise des instantanés d’usage/de quota spécifiques au provider une fois l’authentification résolue | Le provider a besoin d’un point de terminaison d’usage spécifique au provider ou d’un analyseur de charge utile | +| 40 | `createEmbeddingProvider` | Construit un adaptateur d’embedding appartenant au provider pour la mémoire/la recherche | Le comportement d’embedding mémoire appartient au plugin provider | +| 41 | `buildReplayPolicy` | Renvoie une politique de replay qui contrôle la gestion des transcriptions pour le provider | Le provider a besoin d’une politique de transcription personnalisée (par exemple, suppression des blocs de raisonnement) | +| 42 | `sanitizeReplayHistory` | Réécrit l’historique de replay après le nettoyage générique des transcriptions | Le provider a besoin de réécritures de replay spécifiques au provider au-delà des helpers partagés de compaction | +| 43 | `validateReplayTurns` | Validation finale ou remaniement des tours de replay avant l’embedded runner | Le transport du provider a besoin d’une validation de tour plus stricte après l’assainissement générique | +| 44 | `onModelSelected` | Exécute des effets de bord post-sélection appartenant au provider | Le provider a besoin de télémétrie ou d’un état appartenant au provider lorsqu’un modèle devient actif | `normalizeModelId`, `normalizeTransport` et `normalizeConfig` vérifient d’abord le -plugin fournisseur correspondant, puis passent aux autres plugins fournisseurs compatibles avec les hooks -jusqu’à ce que l’un d’eux modifie réellement l’identifiant du modèle ou le transport/la configuration. Cela permet aux -shims d’alias/de fournisseurs compatibles de continuer à fonctionner sans obliger l’appelant à savoir quel -plugin bundled possède la réécriture. Si aucun hook fournisseur ne réécrit une entrée de configuration prise en charge de la famille -Google, le normaliseur de configuration Google bundled applique toujours ce nettoyage de compatibilité. +plugin fournisseur correspondant, puis passent aux autres plugins fournisseurs capables d’utiliser des hooks +jusqu’à ce que l’un d’eux modifie réellement l’id de modèle ou le transport/la configuration. Cela permet aux +shims de compatibilité de provider/alias de continuer à fonctionner sans obliger l’appelant à savoir +quel plugin bundled possède la réécriture. Si aucun hook de provider ne réécrit une entrée de configuration +Google-family prise en charge, le normaliseur de configuration Google bundled applique quand même ce nettoyage de compatibilité. -Si le fournisseur a besoin d’un protocole filaire entièrement personnalisé ou d’un exécuteur de requêtes personnalisé, -il s’agit d’une autre classe d’extension. Ces hooks concernent le comportement du fournisseur qui -s’exécute toujours sur la boucle d’inférence normale d’OpenClaw. +Si le provider a besoin d’un protocole filaire entièrement personnalisé ou d’un exécuteur de requêtes personnalisé, +il s’agit d’une autre classe d’extension. Ces hooks sont destinés au comportement fournisseur +qui s’exécute toujours dans la boucle d’inférence normale d’OpenClaw. -### Exemple de fournisseur +### Exemple de provider ```ts api.registerProvider({ @@ -758,111 +810,112 @@ api.registerProvider({ - Anthropic utilise `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - et `wrapStreamFn` parce qu’il possède la compatibilité ascendante de Claude 4.6, - les indications de famille de fournisseurs, les conseils de réparation de l’authentification, l’intégration du point de terminaison d’usage, - l’éligibilité du cache de prompt, les valeurs par défaut de configuration sensibles à l’authentification, la politique - par défaut/adaptative de réflexion de Claude, ainsi que la mise en forme de flux spécifique à Anthropic pour + et `wrapStreamFn` parce qu’il possède la compatibilité future de Claude 4.6, + les indications de famille de provider, les conseils de réparation d’authentification, l’intégration + au point de terminaison d’usage, l’éligibilité au cache de prompt, les valeurs par défaut de configuration tenant compte de l’authentification, la + politique de pensée par défaut/adaptative de Claude, ainsi que le façonnage de flux spécifique à Anthropic pour les en-têtes bêta, `/fast` / `serviceTier`, et `context1m`. -- Les assistants de flux spécifiques à Claude d’Anthropic restent pour l’instant dans le point d’intégration public +- Les helpers de flux spécifiques à Claude d’Anthropic restent pour l’instant dans la propre couture publique `api.ts` / `contract-api.ts` du plugin bundled. Cette surface de package exporte `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, ainsi que les constructeurs de wrappers Anthropic - de niveau inférieur, au lieu d’élargir le SDK générique autour des règles d’en-tête bêta d’un seul - fournisseur. -- OpenAI utilise `resolveDynamicModel`, `normalizeResolvedModel` et - `capabilities`, ainsi que `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking` et `isModernModelRef` - parce qu’il possède la compatibilité ascendante de GPT-5.4, la normalisation directe OpenAI - `openai-completions` -> `openai-responses`, les indications d’authentification adaptées à Codex, - la suppression de Spark, les lignes synthétiques de liste OpenAI, ainsi que la politique de réflexion / de modèle live de GPT-5 ; la famille de flux `openai-responses-defaults` - possède les wrappers natifs partagés OpenAI Responses pour les en-têtes d’attribution, - `/fast`/`serviceTier`, la verbosité du texte, la recherche web Codex native, - la mise en forme de charge utile compatible avec le raisonnement, et la gestion du contexte Responses. -- OpenRouter utilise `catalog`, ainsi que `resolveDynamicModel` et - `prepareDynamicModel`, parce que le fournisseur est en passthrough et peut exposer de nouveaux - identifiants de modèle avant la mise à jour du catalogue statique d’OpenClaw ; il utilise aussi - `capabilities`, `wrapStreamFn` et `isCacheTtlEligible` afin de maintenir hors du cœur - les en-têtes de requête spécifiques au fournisseur, les métadonnées de routage, les correctifs de raisonnement et - la politique de cache de prompt. Sa politique de rejeu vient de la - famille `passthrough-gemini`, tandis que la famille de flux `openrouter-thinking` - possède l’injection de raisonnement proxy et les omissions de modèles non pris en charge / `auto`. -- GitHub Copilot utilise `catalog`, `auth`, `resolveDynamicModel` et - `capabilities`, ainsi que `prepareRuntimeAuth` et `fetchUsageSnapshot`, car il - a besoin d’un login par appareil appartenant au fournisseur, d’un comportement de repli de modèle, des particularités de transcription Claude, - d’un échange de jeton GitHub -> jeton Copilot, ainsi que d’un point de terminaison d’usage appartenant au fournisseur. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, ainsi que les builders de wrapper Anthropic + de niveau inférieur, au lieu d’élargir le SDK générique autour des règles d’en-têtes bêta d’un seul + provider. +- OpenAI utilise `resolveDynamicModel`, `normalizeResolvedModel`, et + `capabilities` ainsi que `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `supportsXHighThinking`, et `isModernModelRef` + parce qu’il possède la compatibilité future GPT-5.4, la normalisation directe OpenAI + `openai-completions` -> `openai-responses`, les indications d’authentification compatibles Codex, + la suppression de Spark, les lignes de liste OpenAI synthétiques, et la politique GPT-5 de thinking / + modèle live ; la famille de flux `openai-responses-defaults` possède les wrappers partagés natifs OpenAI Responses pour les en-têtes d’attribution, + `/fast`/`serviceTier`, la verbosité du texte, la recherche web native Codex, + le façonnage de charge utile de compatibilité reasoning, et la gestion du contexte Responses. +- OpenRouter utilise `catalog` ainsi que `resolveDynamicModel` et + `prepareDynamicModel` parce que le provider est en pass-through et peut exposer de nouveaux + ids de modèle avant la mise à jour du catalogue statique d’OpenClaw ; il utilise aussi + `capabilities`, `wrapStreamFn`, et `isCacheTtlEligible` pour garder hors du cœur + les en-têtes de requête spécifiques au provider, les métadonnées de routage, les correctifs de reasoning et la politique + de cache de prompt. Sa politique de replay provient de la famille + `passthrough-gemini`, tandis que la famille de flux `openrouter-thinking` + possède l’injection proxy de reasoning ainsi que les sauts de modèles non pris en charge / `auto`. +- GitHub Copilot utilise `catalog`, `auth`, `resolveDynamicModel`, et + `capabilities` ainsi que `prepareRuntimeAuth` et `fetchUsageSnapshot` parce qu’il + a besoin d’une connexion par appareil appartenant au provider, d’un comportement de fallback de modèle, de particularités de transcription Claude, + d’un échange de jeton GitHub -> jeton Copilot, et d’un point de terminaison d’usage appartenant au provider. - OpenAI Codex utilise `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` et `augmentModelCatalog`, ainsi que - `prepareExtraParams`, `resolveUsageAuth` et `fetchUsageSnapshot`, parce qu’il - s’exécute encore sur les transports OpenAI du cœur mais possède sa normalisation de transport/base URL, - sa politique de repli d’actualisation OAuth, son choix de transport par défaut, - ses lignes synthétiques de catalogue Codex, ainsi que l’intégration du point de terminaison d’usage ChatGPT ; il - partage la même famille de flux `openai-responses-defaults` que l’OpenAI direct. + `normalizeResolvedModel`, `refreshOAuth`, et `augmentModelCatalog` ainsi que + `prepareExtraParams`, `resolveUsageAuth`, et `fetchUsageSnapshot` parce qu’il + s’exécute encore sur les transports OpenAI du cœur mais possède sa normalisation + de transport/d’URL de base, sa politique de fallback d’actualisation OAuth, le choix de transport par défaut, + les lignes synthétiques du catalogue Codex, et l’intégration au point de terminaison d’usage ChatGPT ; il + partage la même famille de flux `openai-responses-defaults` qu’OpenAI direct. - Google AI Studio et Gemini CLI OAuth utilisent `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` et `isModernModelRef` parce que la - famille de rejeu `google-gemini` possède le repli de compatibilité ascendante Gemini 3.1, - la validation native du rejeu Gemini, l’assainissement du rejeu au démarrage, le mode de sortie de raisonnement - balisé, ainsi que la correspondance des modèles modernes, tandis que la - famille de flux `google-thinking` possède la normalisation de charge utile de réflexion Gemini ; - Gemini CLI OAuth utilise aussi `formatApiKey`, `resolveUsageAuth` et - `fetchUsageSnapshot` pour la mise en forme des jetons, l’analyse des jetons et le - câblage du point de terminaison de quota. + `resolveReasoningOutputMode`, `wrapStreamFn`, et `isModernModelRef` parce que la + famille de replay `google-gemini` possède le fallback de compatibilité future Gemini 3.1, + la validation native de replay Gemini, l’assainissement du replay de bootstrap, le mode + de sortie reasoning balisé, et la correspondance de modèle moderne, tandis que la + famille de flux `google-thinking` possède la normalisation de charge utile thinking de Gemini ; + Gemini CLI OAuth utilise aussi `formatApiKey`, `resolveUsageAuth`, et + `fetchUsageSnapshot` pour le formatage des jetons, l’analyse des jetons et le câblage + du point de terminaison de quota. - Anthropic Vertex utilise `buildReplayPolicy` via la - famille de rejeu `anthropic-by-model` afin que le nettoyage du rejeu spécifique à Claude reste - limité aux identifiants Claude au lieu de tous les transports `anthropic-messages`. + famille de replay `anthropic-by-model` afin que le nettoyage de replay spécifique à Claude reste + limité aux ids Claude au lieu de tous les transports `anthropic-messages`. - Amazon Bedrock utilise `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` et `resolveDefaultThinkingLevel` parce qu’il possède - la classification spécifique à Bedrock des erreurs throttle/not-ready/context-overflow - pour le trafic Anthropic-sur-Bedrock ; sa politique de rejeu partage toujours la même - protection `anthropic-by-model` limitée à Claude. -- OpenRouter, Kilocode, Opencode et Opencode Go utilisent `buildReplayPolicy` - via la famille de rejeu `passthrough-gemini` parce qu’ils proxifient des modèles Gemini - au travers de transports compatibles OpenAI et ont besoin de l’assainissement de signature de pensée - Gemini sans validation native du rejeu Gemini ni réécritures au - démarrage. + `classifyFailoverReason`, et `resolveDefaultThinkingLevel` parce qu’il possède + la classification spécifique à Bedrock des erreurs de limitation, d’indisponibilité et de débordement de contexte + pour le trafic Anthropic-sur-Bedrock ; sa politique de replay partage toutefois encore la même + garde `anthropic-by-model` réservée à Claude. +- OpenRouter, Kilocode, Opencode, et Opencode Go utilisent `buildReplayPolicy` + via la famille de replay `passthrough-gemini` parce qu’ils proxifient les modèles Gemini + à travers des transports compatibles OpenAI et ont besoin d’un assainissement de + signature de pensée Gemini sans validation native du replay Gemini ni réécritures + de bootstrap. - MiniMax utilise `buildReplayPolicy` via la - famille de rejeu `hybrid-anthropic-openai` parce qu’un seul fournisseur possède à la fois - la sémantique Anthropic-message et OpenAI-compatible ; il conserve - l’abandon des blocs de réflexion limités à Claude du côté Anthropic tout en remplaçant le mode de sortie - du raisonnement pour revenir au natif, et la famille de flux `minimax-fast-mode` possède + famille de replay `hybrid-anthropic-openai` parce qu’un provider possède à la fois des sémantiques + Anthropic-message et compatibles OpenAI ; cela conserve + l’abandon des blocs thinking réservé à Claude côté Anthropic tout en rétablissant le mode + de sortie reasoning en natif, et la famille de flux `minimax-fast-mode` possède les réécritures de modèles fast-mode sur le chemin de flux partagé. -- Moonshot utilise `catalog` ainsi que `wrapStreamFn` parce qu’il utilise toujours le - transport OpenAI partagé mais a besoin d’une normalisation de charge utile de réflexion appartenant au fournisseur ; la - famille de flux `moonshot-thinking` mappe la configuration ainsi que l’état `/think` sur sa - charge utile native de réflexion binaire. -- Kilocode utilise `catalog`, `capabilities`, `wrapStreamFn` et - `isCacheTtlEligible` parce qu’il a besoin d’en-têtes de requête appartenant au fournisseur, - de normalisation de charge utile de raisonnement, d’indications de transcription Gemini et d’une régulation - Anthropic du cache TTL ; la famille de flux `kilocode-thinking` conserve l’injection de réflexion Kilo +- Moonshot utilise `catalog` ainsi que `wrapStreamFn` parce qu’il utilise encore le transport + OpenAI partagé mais a besoin d’une normalisation de charge utile thinking appartenant au provider ; la + famille de flux `moonshot-thinking` mappe la configuration plus l’état `/think` sur sa + charge utile native binaire thinking. +- Kilocode utilise `catalog`, `capabilities`, `wrapStreamFn`, et + `isCacheTtlEligible` parce qu’il a besoin d’en-têtes de requête appartenant au provider, + d’une normalisation de charge utile reasoning, d’indications de transcription Gemini, et d’un filtrage TTL + du cache Anthropic ; la famille de flux `kilocode-thinking` conserve l’injection Kilo thinking sur le chemin de flux proxy partagé tout en ignorant `kilo/auto` et - d’autres identifiants de modèle proxy qui ne prennent pas en charge des charges utiles de raisonnement explicites. + d’autres ids de modèle proxy qui ne prennent pas en charge les charges utiles de reasoning explicites. - Z.AI utilise `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` et `fetchUsageSnapshot` parce qu’il possède le repli GLM-5, - les valeurs par défaut `tool_stream`, l’UX de réflexion binaire, la correspondance des modèles modernes, ainsi que - l’authentification d’usage et la récupération de quota ; la famille de flux `tool-stream-default-on` - maintient hors du code manuscrit par fournisseur le wrapper `tool_stream` activé par défaut. + `resolveUsageAuth`, et `fetchUsageSnapshot` parce qu’il possède le fallback GLM-5, + les valeurs par défaut `tool_stream`, l’expérience utilisateur de thinking binaire, la correspondance de modèle moderne, ainsi que + l’authentification d’usage et la récupération de quota ; la famille de flux `tool-stream-default-on` garde + le wrapper `tool_stream` activé par défaut hors du code glue manuscrit par provider. - xAI utilise `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, - `resolveSyntheticAuth`, `resolveDynamicModel` et `isModernModelRef` - parce qu’il possède la normalisation native du transport xAI Responses, les réécritures d’alias Grok fast-mode, le `tool_stream` par défaut, le nettoyage strict-tool / charge utile de raisonnement, - la réutilisation d’authentification de repli pour les outils appartenant au plugin, la résolution - compatible vers l’avant des modèles Grok, ainsi que des correctifs de compatibilité appartenant au fournisseur comme le profil de schéma d’outils xAI, - les mots-clés de schéma non pris en charge, le `web_search` natif, et le décodage des arguments d’appel d’outil - avec entités HTML. -- Mistral, OpenCode Zen et OpenCode Go utilisent uniquement `capabilities` pour maintenir hors du cœur - les particularités de transcription/d’outillage. -- Les fournisseurs bundled uniquement catalogue tels que `byteplus`, `cloudflare-ai-gateway`, + `resolveSyntheticAuth`, `resolveDynamicModel`, et `isModernModelRef` + parce qu’il possède la normalisation native du transport xAI Responses, les réécritures d’alias Grok fast-mode, + la valeur par défaut `tool_stream`, le nettoyage strict-tool / charge utile reasoning, + la réutilisation d’authentification de fallback pour les outils appartenant au plugin, la résolution de modèle Grok à compatibilité future, + et des correctifs de compatibilité appartenant au provider tels que le profil de schéma d’outil xAI, + les mots-clés de schéma non pris en charge, `web_search` natif, et le décodage d’arguments + d’appels d’outils en entités HTML. +- Mistral, OpenCode Zen, et OpenCode Go utilisent uniquement `capabilities` pour garder + hors du cœur les particularités de transcription/d’outillage. +- Les providers bundled à catalogue uniquement, comme `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, - `synthetic`, `together`, `venice`, `vercel-ai-gateway` et `volcengine` utilisent + `synthetic`, `together`, `venice`, `vercel-ai-gateway`, et `volcengine`, utilisent uniquement `catalog`. -- Qwen utilise `catalog` pour son fournisseur de texte ainsi que des enregistrements partagés de compréhension des médias et de génération de vidéos pour ses surfaces multimodales. -- MiniMax et Xiaomi utilisent `catalog` ainsi que les hooks d’usage parce que leur comportement `/usage` - appartient au plugin même si l’inférence s’exécute encore via les transports partagés. +- Qwen utilise `catalog` pour son provider de texte ainsi que les enregistrements partagés de compréhension des médias et de génération de vidéo pour ses surfaces multimodales. +- MiniMax et Xiaomi utilisent `catalog` ainsi que des hooks d’usage parce que leur comportement `/usage` + appartient au plugin, même si l’inférence passe encore par les transports partagés. -## Assistants d’exécution +## Helpers d’exécution -Les plugins peuvent accéder à certains assistants du cœur via `api.runtime`. Pour la synthèse vocale : +Les plugins peuvent accéder à certains helpers du cœur via `api.runtime`. Pour la TTS : ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -883,14 +936,14 @@ const voices = await api.runtime.tts.listVoices({ Remarques : -- `textToSpeech` renvoie la charge utile normale de sortie TTS du cœur pour les surfaces de fichier/note vocale. -- Utilise la configuration du cœur `messages.tts` et la sélection de fournisseur. -- Renvoie un tampon audio PCM + une fréquence d’échantillonnage. Les plugins doivent rééchantillonner/encoder pour les fournisseurs. -- `listVoices` est facultatif selon le fournisseur. Utilisez-le pour les sélecteurs de voix appartenant au fournisseur ou les flux de configuration. -- Les listes de voix peuvent inclure des métadonnées plus riches telles que la locale, le genre et des tags de personnalité pour des sélecteurs conscients du fournisseur. +- `textToSpeech` renvoie la charge utile normale de sortie TTS du cœur pour les surfaces fichier/note vocale. +- Utilise la configuration `messages.tts` du cœur et la sélection du provider. +- Renvoie un tampon audio PCM + la fréquence d’échantillonnage. Les plugins doivent rééchantillonner/encoder pour les providers. +- `listVoices` est facultatif selon le provider. Utilisez-le pour les sélecteurs de voix appartenant au fournisseur ou les flux de configuration. +- Les listes de voix peuvent inclure des métadonnées plus riches, comme les paramètres régionaux, le genre et les tags de personnalité pour les sélecteurs sensibles au provider. - OpenAI et ElevenLabs prennent aujourd’hui en charge la téléphonie. Microsoft non. -Les plugins peuvent également enregistrer des fournisseurs de parole via `api.registerSpeechProvider(...)`. +Les plugins peuvent aussi enregistrer des fournisseurs vocaux via `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -910,15 +963,15 @@ api.registerSpeechProvider({ Remarques : -- Conservez dans le cœur la politique TTS, le repli et la livraison des réponses. -- Utilisez les fournisseurs de parole pour le comportement de synthèse appartenant au fournisseur. -- L’entrée Microsoft legacy `edge` est normalisée vers l’identifiant de fournisseur `microsoft`. -- Le modèle de propriété privilégié est orienté entreprise : un même plugin fournisseur peut posséder - le texte, la parole, l’image et les futurs fournisseurs de médias à mesure qu’OpenClaw ajoute ces +- Conservez dans le cœur la politique TTS, le fallback et la livraison des réponses. +- Utilisez les fournisseurs vocaux pour le comportement de synthèse appartenant au fournisseur. +- L’entrée legacy Microsoft `edge` est normalisée vers l’id de provider `microsoft`. +- Le modèle de propriété préféré est orienté entreprise : un plugin fournisseur peut posséder + les providers de texte, de voix, d’image et de futurs médias à mesure qu’OpenClaw ajoute ces contrats de capacité. -Pour la compréhension d’image/audio/vidéo, les plugins enregistrent un fournisseur de -compréhension des médias typé au lieu d’un sac générique clé/valeur : +Pour la compréhension des images/de l’audio/de la vidéo, les plugins enregistrent un +provider typé unique de compréhension des médias plutôt qu’un sac clé/valeur générique : ```ts api.registerMediaUnderstandingProvider({ @@ -932,16 +985,16 @@ api.registerMediaUnderstandingProvider({ Remarques : -- Conservez dans le cœur l’orchestration, le repli, la configuration et le câblage des canaux. -- Conservez le comportement du fournisseur dans le plugin fournisseur. -- L’extension additive doit rester typée : nouvelles méthodes optionnelles, nouveaux champs de résultat - optionnels, nouvelles capacités optionnelles. -- La génération de vidéos suit déjà le même schéma : - - le cœur possède le contrat de capacité et l’assistant d’exécution +- Conservez dans le cœur l’orchestration, le fallback, la configuration et le câblage des canaux. +- Conservez le comportement fournisseur dans le plugin provider. +- L’extension additive doit rester typée : nouvelles méthodes facultatives, nouveaux champs de résultat + facultatifs, nouvelles capacités facultatives. +- La génération de vidéo suit déjà le même modèle : + - le cœur possède le contrat de capacité et le helper d’exécution - les plugins fournisseurs enregistrent `api.registerVideoGenerationProvider(...)` - - les plugins de fonctionnalité/de canal consomment `api.runtime.videoGeneration.*` + - les plugins de fonctionnalité/canal consomment `api.runtime.videoGeneration.*` -Pour les assistants d’exécution de compréhension des médias, les plugins peuvent appeler : +Pour les helpers d’exécution media-understanding, les plugins peuvent appeler : ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -956,14 +1009,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Pour la transcription audio, les plugins peuvent utiliser soit l’exécution media-understanding, -soit l’ancien alias STT : +Pour la transcription audio, les plugins peuvent utiliser soit le runtime +media-understanding, soit l’ancien alias STT : ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Facultatif lorsque le type MIME ne peut pas être déduit de façon fiable : + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -971,8 +1024,8 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Remarques : - `api.runtime.mediaUnderstanding.*` est la surface partagée privilégiée pour la - compréhension d’image/audio/vidéo. -- Utilise la configuration audio media-understanding du cœur (`tools.media.audio`) et l’ordre de repli du fournisseur. + compréhension des images/de l’audio/de la vidéo. +- Utilise la configuration audio media-understanding du cœur (`tools.media.audio`) et l’ordre de fallback des providers. - Renvoie `{ text: undefined }` lorsqu’aucune sortie de transcription n’est produite (par exemple entrée ignorée/non prise en charge). - `api.runtime.stt.transcribeAudioFile(...)` reste disponible comme alias de compatibilité. @@ -981,7 +1034,7 @@ Les plugins peuvent aussi lancer des exécutions de sous-agent en arrière-plan ```ts const result = await api.runtime.subagent.run({ sessionKey: "agent:main:subagent:search-helper", - message: "Développe cette requête en recherches de suivi ciblées.", + message: "Expand this query into focused follow-up searches.", provider: "openai", model: "gpt-4.1-mini", deliver: false, @@ -990,14 +1043,14 @@ const result = await api.runtime.subagent.run({ Remarques : -- `provider` et `model` sont des remplacements par exécution facultatifs, et non des modifications persistantes de session. -- OpenClaw n’honore ces champs de remplacement que pour les appelants de confiance. -- Pour les exécutions de repli appartenant au plugin, les opérateurs doivent activer explicitement `plugins.entries..subagent.allowModelOverride: true`. -- Utilisez `plugins.entries..subagent.allowedModels` pour limiter les plugins de confiance à des cibles canoniques `provider/model` spécifiques, ou `"*"` pour autoriser explicitement n’importe quelle cible. -- Les exécutions de sous-agent de plugins non fiables fonctionnent toujours, mais les demandes de remplacement sont rejetées au lieu d’entraîner silencieusement un repli. +- `provider` et `model` sont des remplacements facultatifs par exécution, pas des changements de session persistants. +- OpenClaw ne respecte ces champs de remplacement que pour les appelants de confiance. +- Pour les exécutions de fallback appartenant au plugin, les opérateurs doivent activer explicitement `plugins.entries..subagent.allowModelOverride: true`. +- Utilisez `plugins.entries..subagent.allowedModels` pour limiter les plugins de confiance à des cibles canoniques `provider/model` spécifiques, ou `"*"` pour autoriser explicitement toute cible. +- Les exécutions de sous-agent de plugins non fiables fonctionnent toujours, mais les demandes de remplacement sont rejetées au lieu de retomber silencieusement sur un fallback. -Pour la recherche web, les plugins peuvent consommer l’assistant d’exécution partagé au lieu -d’accéder directement au câblage de l’outil d’agent : +Pour la recherche web, les plugins peuvent consommer le helper d’exécution partagé au lieu +d’accéder directement au câblage de l’outil de l’agent : ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1007,27 +1060,27 @@ const providers = api.runtime.webSearch.listProviders({ const result = await api.runtime.webSearch.search({ config: api.config, args: { - query: "Assistants d’exécution des plugins OpenClaw", + query: "OpenClaw plugin runtime helpers", count: 5, }, }); ``` -Les plugins peuvent aussi enregistrer des fournisseurs de recherche web via +Les plugins peuvent aussi enregistrer des providers de recherche web via `api.registerWebSearchProvider(...)`. Remarques : -- Conservez dans le cœur la sélection du fournisseur, la résolution des identifiants et la sémantique partagée des requêtes. -- Utilisez les fournisseurs de recherche web pour les transports de recherche spécifiques à un fournisseur. -- `api.runtime.webSearch.*` est la surface partagée privilégiée pour les plugins de fonctionnalité/de canal qui ont besoin d’un comportement de recherche sans dépendre du wrapper de l’outil d’agent. +- Conservez dans le cœur la sélection du provider, la résolution des identifiants et la sémantique partagée des requêtes. +- Utilisez les providers de recherche web pour les transports de recherche spécifiques à un fournisseur. +- `api.runtime.webSearch.*` est la surface partagée privilégiée pour les plugins de fonctionnalité/canal qui ont besoin d’un comportement de recherche sans dépendre du wrapper d’outil de l’agent. ### `api.runtime.imageGeneration` ```ts const result = await api.runtime.imageGeneration.generate({ config: api.config, - args: { prompt: "Une mascotte homard amicale", size: "1024x1024" }, + args: { prompt: "A friendly lobster mascot", size: "1024x1024" }, }); const providers = api.runtime.imageGeneration.listProviders({ @@ -1035,8 +1088,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)` : génère une image en utilisant la chaîne configurée de fournisseurs de génération d’images. -- `listProviders(...)` : liste les fournisseurs de génération d’images disponibles et leurs capacités. +- `generate(...)` : génère une image en utilisant la chaîne de providers de génération d’images configurée. +- `listProviders(...)` : liste les providers de génération d’images disponibles et leurs capacités. ## Routes HTTP Gateway @@ -1057,35 +1110,35 @@ api.registerHttpRoute({ Champs de route : -- `path` : chemin de route sous le serveur HTTP Gateway. -- `auth` : obligatoire. Utilisez `"gateway"` pour exiger l’authentification normale de la gateway, ou `"plugin"` pour l’authentification/la vérification de webhook gérée par le plugin. +- `path` : chemin de route sous le serveur HTTP de la gateway. +- `auth` : obligatoire. Utilisez `"gateway"` pour exiger l’authentification normale de la gateway, ou `"plugin"` pour une authentification/validation de webhook gérée par le plugin. - `match` : facultatif. `"exact"` (par défaut) ou `"prefix"`. - `replaceExisting` : facultatif. Permet au même plugin de remplacer son propre enregistrement de route existant. -- `handler` : renvoie `true` lorsque la route a traité la requête. +- `handler` : renvoyez `true` lorsque la route a traité la requête. Remarques : - `api.registerHttpHandler(...)` a été supprimé et provoquera une erreur de chargement du plugin. Utilisez `api.registerHttpRoute(...)` à la place. -- Les routes de plugin doivent déclarer `auth` explicitement. +- Les routes de plugin doivent déclarer explicitement `auth`. - Les conflits exacts `path + match` sont rejetés sauf si `replaceExisting: true`, et un plugin ne peut pas remplacer la route d’un autre plugin. -- Les routes qui se chevauchent avec des niveaux `auth` différents sont rejetées. Gardez les chaînes de retombée `exact`/`prefix` uniquement au même niveau d’authentification. -- Les routes `auth: "plugin"` ne reçoivent **pas** automatiquement les portées d’exécution de l’opérateur. Elles sont destinées aux webhooks gérés par le plugin / à la vérification de signature, et non aux appels d’assistants Gateway privilégiés. -- Les routes `auth: "gateway"` s’exécutent dans une portée d’exécution de requête Gateway, mais cette portée est volontairement prudente : - - l’authentification bearer par secret partagé (`gateway.auth.mode = "token"` / `"password"`) maintient les portées d’exécution des routes de plugin fixées à `operator.write`, même si l’appelant envoie `x-openclaw-scopes` - - les modes HTTP de confiance avec identité (par exemple `trusted-proxy` ou `gateway.auth.mode = "none"` sur une entrée privée) n’honorent `x-openclaw-scopes` que lorsque l’en-tête est explicitement présent - - si `x-openclaw-scopes` est absent sur ces requêtes de route de plugin porteuses d’identité, la portée d’exécution retombe à `operator.write` -- Règle pratique : ne supposez pas qu’une route de plugin authentifiée par la gateway est implicitement une surface d’administration. Si votre route a besoin d’un comportement réservé à l’administrateur, exigez un mode d’authentification porteur d’identité et documentez le contrat explicite de l’en-tête `x-openclaw-scopes`. +- Les routes qui se chevauchent avec des niveaux `auth` différents sont rejetées. Conservez les chaînes de fallback `exact`/`prefix` uniquement au même niveau d’authentification. +- Les routes `auth: "plugin"` ne reçoivent **pas** automatiquement les portées runtime opérateur. Elles sont destinées aux webhooks/à la validation de signature gérés par le plugin, pas aux appels de helpers Gateway privilégiés. +- Les routes `auth: "gateway"` s’exécutent dans une portée runtime de requête Gateway, mais cette portée est volontairement prudente : + - l’authentification bearer par secret partagé (`gateway.auth.mode = "token"` / `"password"`) maintient les portées runtime des routes de plugin épinglées à `operator.write`, même si l’appelant envoie `x-openclaw-scopes` + - les modes HTTP fiables porteurs d’identité (par exemple `trusted-proxy` ou `gateway.auth.mode = "none"` sur une entrée privée) ne respectent `x-openclaw-scopes` que lorsque l’en-tête est explicitement présent + - si `x-openclaw-scopes` est absent sur ces requêtes de route de plugin porteuses d’identité, la portée runtime retombe sur `operator.write` +- Règle pratique : ne supposez pas qu’une route de plugin authentifiée par gateway constitue implicitement une surface d’administration. Si votre route a besoin d’un comportement réservé à l’administration, exigez un mode d’authentification porteur d’identité et documentez le contrat explicite de l’en-tête `x-openclaw-scopes`. -## Chemins d’import du SDK de plugin +## Chemins d’import du Plugin SDK Utilisez les sous-chemins du SDK au lieu de l’import monolithique `openclaw/plugin-sdk` lorsque -vous créez des plugins : +vous développez des plugins : -- `openclaw/plugin-sdk/plugin-entry` pour les primitives d’enregistrement des plugins. -- `openclaw/plugin-sdk/core` pour le contrat partagé générique côté plugin. +- `openclaw/plugin-sdk/plugin-entry` pour les primitives d’enregistrement de plugin. +- `openclaw/plugin-sdk/core` pour le contrat générique partagé orienté plugin. - `openclaw/plugin-sdk/config-schema` pour l’export du schéma Zod racine `openclaw.json` (`OpenClawSchema`). -- Primitives de canal stables telles que `openclaw/plugin-sdk/channel-setup`, +- Primitives de canal stables comme `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1098,17 +1151,17 @@ vous créez des plugins : `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input`, et `openclaw/plugin-sdk/webhook-ingress` pour le câblage partagé de configuration/authentification/réponse/webhook. - `channel-inbound` est la surface partagée pour l’anti-rebond, la correspondance des mentions, - les assistants de politique de mention entrante, le formatage d’enveloppe et les - assistants de contexte d’enveloppe entrante. - `channel-setup` est le point d’intégration étroit de configuration à installation facultative. + `channel-inbound` est l’emplacement partagé pour l’anti-rebond, la correspondance des mentions, + les helpers de politique de mention entrante, le formatage d’enveloppe et les helpers de contexte + d’enveloppe entrante. + `channel-setup` est la couture étroite de configuration à installation facultative. `setup-runtime` est la surface de configuration sûre à l’exécution utilisée par `setupEntry` / le démarrage différé, y compris les adaptateurs de patch de configuration sûrs à l’import. - `setup-adapter-runtime` est le point d’intégration des adaptateurs de configuration de compte sensibles à l’environnement. - `setup-tools` est le petit point d’intégration d’assistance CLI/archive/docs (`formatCliCommand`, + `setup-adapter-runtime` est la couture d’adaptateur de configuration de compte sensible à l’environnement. + `setup-tools` est la petite couture d’helpers CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Sous-chemins de domaine tels que `openclaw/plugin-sdk/channel-config-helpers`, +- Sous-chemins de domaine comme `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1126,128 +1179,124 @@ vous créez des plugins : `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store`, et - `openclaw/plugin-sdk/directory-runtime` pour les assistants partagés d’exécution/de configuration. - `telegram-command-config` est le point d’intégration public étroit pour la normalisation/validation des commandes personnalisées Telegram et reste disponible même si la surface de contrat Telegram bundled est temporairement indisponible. - `text-runtime` est la surface partagée pour le texte/Markdown/la journalisation, y compris - la suppression du texte visible par l’assistant, les assistants de rendu/de découpage Markdown, les assistants de rédaction, - les assistants de balises de directive et les utilitaires de texte sûr. -- Les points d’intégration de canal spécifiques à l’approbation doivent préférer un seul contrat `approvalCapability` - sur le plugin. Le cœur lit ensuite l’authentification, la livraison, le rendu, - le routage natif et le comportement paresseux du gestionnaire natif d’approbation via cette seule capacité - au lieu de mélanger le comportement d’approbation dans des champs de plugin sans lien. -- `openclaw/plugin-sdk/channel-runtime` est obsolète et ne subsiste que comme - shim de compatibilité pour les anciens plugins. Le nouveau code doit importer les primitives génériques - plus étroites à la place, et le code du dépôt ne doit pas ajouter de nouveaux imports du - shim. -- Les composants internes des extensions bundled restent privés. Les plugins externes doivent utiliser uniquement - les sous-chemins `openclaw/plugin-sdk/*`. Le code cœur/test d’OpenClaw peut utiliser les - points d’entrée publics du dépôt sous une racine de package de plugin tels que `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js`, et des fichiers à portée étroite tels que - `login-qr-api.js`. N’importez jamais `src/*` d’un package de plugin depuis le cœur ou depuis - une autre extension. -- Séparation des points d’entrée du dépôt : - `/api.js` est le baril d’assistants/types, - `/runtime-api.js` est le baril réservé à l’exécution, + `openclaw/plugin-sdk/directory-runtime` pour les helpers partagés d’exécution/de configuration. + `telegram-command-config` est la couture publique étroite pour la normalisation/validation des commandes personnalisées Telegram et reste disponible même si la surface de contrat Telegram bundled est temporairement indisponible. + `text-runtime` est la couture partagée texte/markdown/journalisation, y compris + la suppression du texte visible par l’assistant, les helpers de rendu/segmentation markdown, les helpers de rédaction, + les helpers de balises de directive, et les utilitaires de texte sûr. +- Les coutures de canal spécifiques à l’approbation devraient préférer un seul contrat `approvalCapability` + sur le plugin. Le cœur lit ensuite l’authentification d’approbation, la livraison, le rendu, + le routage natif et le comportement de gestionnaire natif paresseux à travers cette capacité unique + au lieu de mélanger le comportement d’approbation dans des champs de plugin sans rapport. +- `openclaw/plugin-sdk/channel-runtime` est obsolète et ne reste présent que comme + shim de compatibilité pour les anciens plugins. Le nouveau code doit importer les primitives génériques plus étroites à la place, et le code du dépôt ne doit pas ajouter de nouveaux imports de ce shim. +- Les composants internes des extensions bundled restent privés. Les plugins externes doivent utiliser uniquement les sous-chemins `openclaw/plugin-sdk/*`. Le code cœur/de test d’OpenClaw peut utiliser les points d’entrée publics du dépôt sous la racine d’un package de plugin, comme `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js`, et des fichiers à portée étroite comme + `login-qr-api.js`. N’importez jamais `src/*` d’un package de plugin depuis le cœur ou depuis une autre extension. +- Répartition des points d’entrée du dépôt : + `/api.js` est le barrel d’helpers/types, + `/runtime-api.js` est le barrel réservé au runtime, `/index.js` est le point d’entrée du plugin bundled, et `/setup-entry.js` est le point d’entrée du plugin de configuration. -- Exemples actuels de fournisseurs bundled : - - Anthropic utilise `api.js` / `contract-api.js` pour les assistants de flux Claude tels - que `wrapAnthropicProviderStream`, les assistants d’en-tête bêta et l’analyse de `service_tier`. - - OpenAI utilise `api.js` pour les constructeurs de fournisseur, les assistants de modèle par défaut et - les constructeurs de fournisseur en temps réel. - - OpenRouter utilise `api.js` pour son constructeur de fournisseur ainsi que des assistants d’onboarding/de configuration, - tandis que `register.runtime.js` peut toujours réexporter des assistants génériques +- Exemples actuels de providers bundled : + - Anthropic utilise `api.js` / `contract-api.js` pour des helpers de flux Claude tels + que `wrapAnthropicProviderStream`, les helpers d’en-têtes bêta et l’analyse de `service_tier`. + - OpenAI utilise `api.js` pour les builders de provider, les helpers de modèle par défaut, et + les builders de provider temps réel. + - OpenRouter utilise `api.js` pour son builder de provider ainsi que des helpers d’onboarding/de configuration, + tandis que `register.runtime.js` peut encore réexporter les helpers génériques `plugin-sdk/provider-stream` pour un usage local au dépôt. -- Les points d’entrée publics chargés par façade préfèrent l’instantané de configuration d’exécution actif - lorsqu’il existe, puis retombent sur le fichier de configuration résolu sur disque lorsque - OpenClaw ne sert pas encore d’instantané d’exécution. -- Les primitives génériques partagées restent le contrat public préféré du SDK. Un petit - ensemble réservé de compatibilité de points d’intégration d’assistance portant la marque de canaux bundled existe encore. Traitez-les comme des points d’intégration de maintenance bundled/de compatibilité, et non comme de nouvelles cibles d’import tierces ; les nouveaux contrats transversaux entre canaux doivent toujours être introduits sur des sous-chemins génériques `plugin-sdk/*` ou sur les barils locaux au plugin `api.js` / +- Les points d’entrée publics chargés via façade préfèrent l’instantané de configuration active du runtime + lorsqu’il existe, puis retombent sur le fichier de configuration résolu sur disque quand + OpenClaw ne sert pas encore d’instantané runtime. +- Les primitives génériques partagées restent le contrat SDK public privilégié. Un petit ensemble réservé de coutures helper encore marquées par des canaux bundled existe toujours. Considérez-les comme + des coutures de maintenance/compatibilité bundled, et non comme de nouvelles cibles d’import tierces ; les nouveaux contrats inter-canaux doivent toujours arriver sur des sous-chemins génériques `plugin-sdk/*` ou sur les barrels locaux au plugin `api.js` / `runtime-api.js`. Note de compatibilité : -- Évitez le baril racine `openclaw/plugin-sdk` pour le nouveau code. -- Préférez d’abord les primitives stables étroites. Les nouveaux sous-chemins setup/pairing/reply/ +- Évitez le barrel racine `openclaw/plugin-sdk` pour le nouveau code. +- Préférez d’abord les primitives stables étroites. Les sous-chemins plus récents setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool constituent le contrat prévu pour les nouveaux travaux de plugins - bundled et externes. + allowlist/status/message-tool constituent le contrat prévu pour le nouveau travail + sur les plugins bundled et externes. L’analyse/la correspondance des cibles appartient à `openclaw/plugin-sdk/channel-targets`. - Les barrières d’actions de message et les assistants d’identifiant de message de réaction appartiennent à + Les garde-fous d’action de message et les helpers d’id de message de réaction appartiennent à `openclaw/plugin-sdk/channel-actions`. -- Les barils d’assistance spécifiques à une extension bundled ne sont pas stables par défaut. Si un - assistant n’est nécessaire qu’à une extension bundled, conservez-le derrière le point d’intégration local - `api.js` ou `runtime-api.js` de l’extension au lieu de le promouvoir dans +- Les barrels helpers spécifiques aux extensions bundled ne sont pas stables par défaut. Si un + helper n’est nécessaire que pour une extension bundled, gardez-le derrière la + couture locale `api.js` ou `runtime-api.js` de l’extension au lieu de le promouvoir dans `openclaw/plugin-sdk/`. -- Les nouveaux points d’intégration d’assistance partagée doivent être génériques, et non marqués par un canal. L’analyse partagée des cibles - appartient à `openclaw/plugin-sdk/channel-targets` ; les composants internes spécifiques au canal - restent derrière le point d’intégration local `api.js` ou `runtime-api.js` du plugin propriétaire. -- Des sous-chemins spécifiques à une capacité tels que `image-generation`, - `media-understanding` et `speech` existent parce que les plugins bundled/natifs les utilisent - aujourd’hui. Leur présence ne signifie pas à elle seule que chaque assistant exporté constitue un contrat externe figé à long terme. +- Les nouvelles coutures de helper partagées doivent être génériques, et non marquées par un canal. L’analyse partagée + des cibles appartient à `openclaw/plugin-sdk/channel-targets` ; les composants internes spécifiques au canal + restent derrière la couture locale `api.js` ou `runtime-api.js` du plugin propriétaire. +- Des sous-chemins spécifiques à une capacité comme `image-generation`, + `media-understanding`, et `speech` existent parce que les plugins bundled/natifs les utilisent + aujourd’hui. Leur présence ne signifie pas à elle seule que chaque helper exporté soit un contrat externe figé à long terme. -## Schémas de l’outil de message +## Schémas d’outil de message -Les plugins doivent posséder les contributions de schéma `describeMessageTool(...)` spécifiques au canal. -Conservez les champs spécifiques au fournisseur dans le plugin, et non dans le cœur partagé. +Les plugins doivent posséder les contributions de schéma spécifiques au canal pour +`describeMessageTool(...)`. Conservez les champs spécifiques au provider dans le plugin, pas dans le cœur partagé. -Pour les fragments de schéma portables partagés, réutilisez les assistants génériques exportés via +Pour les fragments de schéma portables partagés, réutilisez les helpers génériques exportés via `openclaw/plugin-sdk/channel-actions` : -- `createMessageToolButtonsSchema()` pour les charges utiles de style grille de boutons -- `createMessageToolCardSchema()` pour les charges utiles de cartes structurées +- `createMessageToolButtonsSchema()` pour des charges utiles de style grille de boutons +- `createMessageToolCardSchema()` pour des charges utiles de carte structurée -Si une forme de schéma n’a de sens que pour un seul fournisseur, définissez-la dans les -sources propres à ce plugin au lieu de la promouvoir dans le SDK partagé. +Si une forme de schéma n’a de sens que pour un seul provider, définissez-la dans les +sources du plugin lui-même au lieu de la promouvoir dans le SDK partagé. ## Résolution de cible de canal -Les plugins de canal doivent posséder la sémantique de cible spécifique au canal. Gardez l’hôte -sortant partagé générique et utilisez la surface de l’adaptateur de messagerie pour les règles fournisseur : +Les plugins de canal doivent posséder la sémantique de cible spécifique au canal. Conservez l’hôte +sortant partagé générique et utilisez la surface de l’adaptateur de messagerie pour les règles du provider : - `messaging.inferTargetChatType({ to })` décide si une cible normalisée - doit être traitée comme `direct`, `group` ou `channel` avant la recherche dans l’annuaire. + doit être traitée comme `direct`, `group`, ou `channel` avant la recherche dans l’annuaire. - `messaging.targetResolver.looksLikeId(raw, normalized)` indique au cœur si une - entrée doit passer directement à une résolution de type identifiant au lieu d’une recherche dans l’annuaire. -- `messaging.targetResolver.resolveTarget(...)` est le repli du plugin lorsque le - cœur a besoin d’une résolution finale appartenant au fournisseur après normalisation ou après un + entrée doit passer directement à une résolution de type id au lieu d’une recherche dans l’annuaire. +- `messaging.targetResolver.resolveTarget(...)` est le fallback du plugin lorsque le + cœur a besoin d’une résolution finale appartenant au provider après normalisation ou après un échec de recherche dans l’annuaire. -- `messaging.resolveOutboundSessionRoute(...)` possède la construction de route de session - spécifique au fournisseur une fois qu’une cible est résolue. +- `messaging.resolveOutboundSessionRoute(...)` possède la construction de route de session spécifique au provider + une fois qu’une cible est résolue. Répartition recommandée : -- Utilisez `inferTargetChatType` pour les décisions de catégorie qui doivent intervenir avant la - recherche parmi pairs/groupes. -- Utilisez `looksLikeId` pour les vérifications de type « traiter ceci comme un identifiant de cible explicite/natif ». -- Utilisez `resolveTarget` pour le repli de normalisation spécifique au fournisseur, et non pour une - recherche large dans l’annuaire. -- Conservez les identifiants natifs du fournisseur comme les identifiants de chat, identifiants de fil, JID, handles et identifiants de salle - dans les valeurs `target` ou les paramètres spécifiques au fournisseur, pas dans des champs SDK génériques. +- Utilisez `inferTargetChatType` pour les décisions de catégorie qui doivent intervenir avant + la recherche dans les pairs/groupes. +- Utilisez `looksLikeId` pour les vérifications du type « traiter ceci comme un id de cible explicite/natif ». +- Utilisez `resolveTarget` pour le fallback de normalisation spécifique au provider, pas pour + une recherche large dans l’annuaire. +- Conservez les ids natifs du provider comme les ids de chat, ids de thread, JID, handles et ids de salon + dans les valeurs `target` ou dans des paramètres spécifiques au provider, pas dans des + champs SDK génériques. ## Annuaires adossés à la configuration Les plugins qui dérivent des entrées d’annuaire à partir de la configuration doivent conserver cette logique dans le -plugin et réutiliser les assistants partagés de +plugin et réutiliser les helpers partagés de `openclaw/plugin-sdk/directory-runtime`. -Utilisez cela lorsqu’un canal a besoin de pairs/groupes adossés à la configuration tels que : +Utilisez cela lorsqu’un canal a besoin de pairs/groupes adossés à la configuration comme : -- pairs de messages privés pilotés par liste d’autorisation -- mappages configurés de canaux/groupes -- replis d’annuaire statiques à portée de compte +- des pairs DM pilotés par liste d’autorisation +- des mappings configurés de canaux/groupes +- des fallbacks statiques d’annuaire à portée de compte -Les assistants partagés de `directory-runtime` ne gèrent que les opérations génériques : +Les helpers partagés de `directory-runtime` ne gèrent que des opérations génériques : - filtrage de requête -- application de limite -- assistants de déduplication/normalisation +- application de limites +- helpers de déduplication/normalisation - construction de `ChannelDirectoryEntry[]` -L’inspection de compte spécifique au canal et la normalisation des identifiants doivent rester dans +L’inspection de compte spécifique au canal et la normalisation des ids doivent rester dans l’implémentation du plugin. -## Catalogues de fournisseurs +## Catalogues de providers Les plugins fournisseurs peuvent définir des catalogues de modèles pour l’inférence avec `registerProvider({ catalog: { run(...) { ... } } })`. @@ -1255,22 +1304,22 @@ Les plugins fournisseurs peuvent définir des catalogues de modèles pour l’in `catalog.run(...)` renvoie la même forme que celle qu’OpenClaw écrit dans `models.providers` : -- `{ provider }` pour une entrée de fournisseur -- `{ providers }` pour plusieurs entrées de fournisseur +- `{ provider }` pour une entrée de provider +- `{ providers }` pour plusieurs entrées de provider -Utilisez `catalog` lorsque le plugin possède des identifiants de modèle spécifiques au fournisseur, des valeurs par défaut de base URL, +Utilisez `catalog` lorsque le plugin possède des ids de modèle spécifiques au provider, des valeurs par défaut d’URL de base, ou des métadonnées de modèle protégées par authentification. `catalog.order` contrôle le moment où le catalogue d’un plugin fusionne par rapport aux -fournisseurs implicites intégrés d’OpenClaw : +providers implicites intégrés d’OpenClaw : -- `simple` : fournisseurs simples pilotés par clé API ou environnement -- `profile` : fournisseurs qui apparaissent lorsque des profils d’authentification existent -- `paired` : fournisseurs qui synthétisent plusieurs entrées de fournisseur liées -- `late` : dernier passage, après les autres fournisseurs implicites +- `simple` : providers simples pilotés par clé API ou environnement +- `profile` : providers qui apparaissent lorsque des profils d’authentification existent +- `paired` : providers qui synthétisent plusieurs entrées de provider liées +- `late` : dernier passage, après les autres providers implicites -Les fournisseurs plus tardifs l’emportent en cas de collision de clé, ce qui permet aux plugins de remplacer intentionnellement une -entrée de fournisseur intégrée avec le même identifiant de fournisseur. +Les providers plus tardifs gagnent en cas de collision de clé, de sorte que les plugins peuvent +écraser intentionnellement une entrée de provider intégrée avec le même id de provider. Compatibilité : @@ -1285,26 +1334,26 @@ Si votre plugin enregistre un canal, préférez implémenter Pourquoi : - `resolveAccount(...)` est le chemin d’exécution. Il peut supposer que les identifiants - sont entièrement matérialisés et peut échouer rapidement si les secrets requis sont absents. -- Les chemins de commandes en lecture seule tels que `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, ainsi que les flux de réparation doctor/config - ne doivent pas avoir besoin de matérialiser les identifiants d’exécution juste pour + sont entièrement matérialisés et peut échouer rapidement lorsque les secrets requis sont absents. +- Les chemins de commande en lecture seule comme `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve`, et les flux doctor/réparation de configuration + ne devraient pas avoir besoin de matérialiser les identifiants runtime juste pour décrire la configuration. -Comportement recommandé de `inspectAccount(...)` : +Comportement recommandé pour `inspectAccount(...)` : -- Renvoyer uniquement un état descriptif du compte. +- Renvoyer uniquement un état de compte descriptif. - Préserver `enabled` et `configured`. -- Inclure les champs de source/statut des identifiants lorsque cela est pertinent, tels que : +- Inclure les champs de source/statut d’identifiants quand cela est pertinent, comme : - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Vous n’avez pas besoin de renvoyer les valeurs brutes de jeton simplement pour signaler une - disponibilité en lecture seule. Renvoyer `tokenStatus: "available"` (et le champ source correspondant) +- Vous n’avez pas besoin de renvoyer les valeurs brutes des jetons simplement pour signaler une + disponibilité en lecture seule. Renvoyer `tokenStatus: "available"` (et le champ de source correspondant) suffit pour les commandes de type statut. - Utilisez `configured_unavailable` lorsqu’un identifiant est configuré via SecretRef mais - indisponible dans le chemin de commande courant. + indisponible dans le chemin de commande actuel. Cela permet aux commandes en lecture seule d’indiquer « configuré mais indisponible dans ce chemin de commande » au lieu de planter ou de signaler à tort que le compte n’est pas configuré. @@ -1323,60 +1372,63 @@ Un répertoire de plugin peut inclure un `package.json` avec `openclaw.extension } ``` -Chaque entrée devient un plugin. Si le pack liste plusieurs extensions, l’identifiant du plugin +Chaque entrée devient un plugin. Si le pack liste plusieurs extensions, l’id du plugin devient `name/`. Si votre plugin importe des dépendances npm, installez-les dans ce répertoire afin que `node_modules` soit disponible (`npm install` / `pnpm install`). -Garde-fou de sécurité : chaque entrée `openclaw.extensions` doit rester dans le répertoire du plugin -après résolution des liens symboliques. Les entrées qui sortent du répertoire du package sont +Garde-fou de sécurité : chaque entrée `openclaw.extensions` doit rester à l’intérieur du répertoire du plugin +après résolution des liens symboliques. Les entrées qui s’échappent du répertoire du package sont rejetées. Note de sécurité : `openclaw plugins install` installe les dépendances du plugin avec -`npm install --omit=dev --ignore-scripts` (pas de scripts de cycle de vie, pas de dépendances de développement à l’exécution). Gardez les arbres de dépendances des plugins en -« JS/TS pur » et évitez les packages qui nécessitent des compilations `postinstall`. +`npm install --omit=dev --ignore-scripts` (pas de scripts de cycle de vie, pas de dépendances de développement à l’exécution). Gardez les arbres +de dépendances des plugins en « JS/TS pur » et évitez les packages qui nécessitent des builds `postinstall`. Facultatif : `openclaw.setupEntry` peut pointer vers un module léger réservé à la configuration. -Lorsque OpenClaw a besoin de surfaces de configuration pour un plugin de canal désactivé, ou +Quand OpenClaw a besoin de surfaces de configuration pour un plugin de canal désactivé, ou lorsqu’un plugin de canal est activé mais encore non configuré, il charge `setupEntry` au lieu du point d’entrée complet du plugin. Cela allège le démarrage et la configuration -lorsque le point d’entrée principal de votre plugin connecte aussi des outils, hooks ou tout autre code +lorsque le point d’entrée principal de votre plugin câble aussi des outils, hooks ou autre code réservé à l’exécution. Facultatif : `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -peut faire participer un plugin de canal au même chemin `setupEntry` pendant la -phase de démarrage pré-listen de la gateway, même lorsque le canal est déjà configuré. +peut faire opter un plugin de canal pour ce même chemin `setupEntry` pendant la phase +de démarrage pré-écoute de la gateway, même lorsque le canal est déjà configuré. -N’utilisez cela que si `setupEntry` couvre entièrement la surface de démarrage qui doit exister -avant que la gateway commence à écouter. En pratique, cela signifie que le point d’entrée de configuration -doit enregistrer chaque capacité appartenant au canal dont dépend le démarrage, comme : +Utilisez ceci uniquement si `setupEntry` couvre entièrement la surface de démarrage qui doit exister +avant que la gateway ne commence à écouter. En pratique, cela signifie que le point d’entrée de configuration +doit enregistrer chaque capacité appartenant au canal dont le démarrage dépend, comme : - l’enregistrement du canal lui-même -- toute route HTTP qui doit être disponible avant que la gateway commence à écouter -- toute méthode gateway, tout outil ou tout service qui doit exister pendant cette même fenêtre +- toute route HTTP qui doit être disponible avant que la gateway ne commence à écouter +- toutes méthodes Gateway, tous outils ou services qui doivent exister pendant cette même fenêtre Si votre point d’entrée complet possède encore une capacité de démarrage requise, n’activez pas ce drapeau. Conservez le comportement par défaut du plugin et laissez OpenClaw charger le -point d’entrée complet pendant le démarrage. +point d’entrée complet au démarrage. -Les canaux bundled peuvent aussi publier des assistants de surface de contrat réservés à la configuration que le cœur -peut consulter avant le chargement de l’exécution complète du canal. La surface actuelle de promotion de configuration est : +Les canaux bundled peuvent aussi publier des helpers de surface de contrat réservés à la configuration que le cœur +peut consulter avant le chargement du runtime complet du canal. La surface actuelle de promotion de configuration +est : - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Le cœur utilise cette surface lorsqu’il doit promouvoir une configuration de canal legacy à compte unique +Le cœur utilise cette surface lorsqu’il doit promouvoir une configuration legacy de canal à compte unique vers `channels..accounts.*` sans charger le point d’entrée complet du plugin. -Matrix est l’exemple bundled actuel : il ne déplace que les clés d’authentification/d’amorçage vers un +Matrix est l’exemple bundled actuel : il ne déplace que les clés d’authentification/bootstrap dans un compte promu nommé lorsque des comptes nommés existent déjà, et il peut préserver une -clé de compte par défaut configurée non canonique au lieu de toujours créer +clé configurée non canonique de compte par défaut au lieu de toujours créer `accounts.default`. -Ces adaptateurs de patch de configuration maintiennent la découverte de surface de contrat bundled de façon paresseuse. Le temps d’import reste léger ; la surface de promotion n’est chargée qu’au premier usage au lieu de réentrer dans le démarrage du canal bundled à l’import du module. +Ces adaptateurs de patch de configuration gardent la découverte de la surface de contrat bundled paresseuse. Le temps +d’import reste léger ; la surface de promotion n’est chargée qu’à la première utilisation au lieu de +réentrer dans le démarrage du canal bundled lors de l’import du module. -Lorsque ces surfaces de démarrage incluent des méthodes Gateway RPC, conservez-les sur un +Lorsque ces surfaces de démarrage incluent des méthodes RPC Gateway, conservez-les sur un préfixe spécifique au plugin. Les espaces de noms d’administration du cœur (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et se résolvent toujours vers `operator.admin`, même si un plugin demande une portée plus étroite. @@ -1399,7 +1451,7 @@ Exemple : ### Métadonnées de catalogue de canal Les plugins de canal peuvent annoncer des métadonnées de configuration/découverte via `openclaw.channel` et -des indications d’installation via `openclaw.install`. Cela permet au catalogue du cœur de rester sans données. +des indications d’installation via `openclaw.install`. Cela garde les données du catalogue hors du cœur. Exemple : @@ -1411,10 +1463,10 @@ Exemple : "channel": { "id": "nextcloud-talk", "label": "Nextcloud Talk", - "selectionLabel": "Nextcloud Talk (autohébergé)", + "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Chat autohébergé via des bots webhook Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1427,18 +1479,18 @@ Exemple : } ``` -Champs `openclaw.channel` utiles au-delà de l’exemple minimal : +Champs utiles de `openclaw.channel` au-delà de l’exemple minimal : - `detailLabel` : libellé secondaire pour des surfaces plus riches de catalogue/statut -- `docsLabel` : remplace le texte du lien de documentation -- `preferOver` : identifiants de plugin/canal de priorité inférieure que cette entrée de catalogue doit surpasser -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras` : contrôles de texte de la surface de sélection +- `docsLabel` : remplace le texte du lien vers la documentation +- `preferOver` : ids de plugin/canal de priorité plus basse que cette entrée de catalogue doit devancer +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras` : contrôles de copie pour la surface de sélection - `markdownCapable` : marque le canal comme compatible Markdown pour les décisions de formatage sortant -- `exposure.configured` : masque le canal des surfaces de liste de canaux configurés lorsqu’il est défini sur `false` -- `exposure.setup` : masque le canal des sélecteurs interactifs de configuration lorsqu’il est défini sur `false` +- `exposure.configured` : masque le canal des surfaces de liste de canaux configurés lorsqu’il est défini à `false` +- `exposure.setup` : masque le canal des sélecteurs interactifs de configuration lorsque défini à `false` - `exposure.docs` : marque le canal comme interne/privé pour les surfaces de navigation de documentation -- `showConfigured` / `showInSetup` : alias legacy encore acceptés pour compatibilité ; préférez `exposure` -- `quickstartAllowFrom` : fait participer le canal au flux standard `allowFrom` de démarrage rapide +- `showConfigured` / `showInSetup` : alias legacy toujours acceptés pour compatibilité ; préférez `exposure` +- `quickstartAllowFrom` : fait opter le canal dans le flux standard quickstart `allowFrom` - `forceAccountBinding` : exige une liaison explicite de compte même lorsqu’un seul compte existe - `preferSessionLookupForAnnounceTarget` : préfère la recherche de session lors de la résolution des cibles d’annonce @@ -1460,8 +1512,8 @@ et la compaction. Enregistrez-les depuis votre plugin avec `api.registerContextEngine(id, factory)`, puis sélectionnez le moteur actif avec `plugins.slots.contextEngine`. -Utilisez cela lorsque votre plugin a besoin de remplacer ou d’étendre le pipeline de contexte par défaut -plutôt que de simplement ajouter une recherche mémoire ou des hooks. +Utilisez ceci lorsque votre plugin doit remplacer ou étendre le pipeline de contexte par défaut +plutôt que simplement ajouter une recherche mémoire ou des hooks. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1489,7 +1541,7 @@ export default function (api) { } ``` -Si votre moteur ne possède **pas** l’algorithme de compaction, laissez `compact()` +Si votre moteur ne possède **pas** l’algorithme de compaction, gardez `compact()` implémenté et déléguez-le explicitement : ```ts @@ -1528,59 +1580,59 @@ export default function (api) { ## Ajouter une nouvelle capacité Lorsqu’un plugin a besoin d’un comportement qui ne correspond pas à l’API actuelle, ne contournez pas -le système de plugins avec un accès privé direct. Ajoutez la capacité manquante. +le système de plugins par un accès privé interne. Ajoutez la capacité manquante. Séquence recommandée : 1. définir le contrat du cœur - Décidez quel comportement partagé le cœur doit posséder : politique, repli, fusion de configuration, - cycle de vie, sémantique côté canal et forme de l’assistant d’exécution. + Décidez quel comportement partagé le cœur doit posséder : politique, fallback, fusion de configuration, + cycle de vie, sémantique orientée canal et forme du helper d’exécution. 2. ajouter des surfaces typées d’enregistrement/d’exécution des plugins - Étendez `OpenClawPluginApi` et/ou `api.runtime` avec la plus petite - surface de capacité typée utile. -3. raccorder le cœur + les consommateurs canal/fonctionnalité + Étendez `OpenClawPluginApi` et/ou `api.runtime` avec la plus petite surface de capacité + typée utile. +3. raccorder les consommateurs cœur + canal/fonctionnalité Les canaux et plugins de fonctionnalité doivent consommer la nouvelle capacité via le cœur, et non en important directement une implémentation fournisseur. -4. enregistrer les implémentations fournisseur - Les plugins fournisseurs enregistrent ensuite leurs backends sur cette capacité. +4. enregistrer les implémentations fournisseurs + Les plugins fournisseurs enregistrent ensuite leurs backends sur la capacité. 5. ajouter une couverture de contrat - Ajoutez des tests afin que la propriété et la forme d’enregistrement restent explicites au fil du temps. + Ajoutez des tests afin que la propriété et la forme de l’enregistrement restent explicites dans le temps. C’est ainsi qu’OpenClaw reste structuré sans devenir codé en dur selon la vision du monde -d’un seul fournisseur. Voir les [Recettes de capacités](/fr/plugins/architecture) -pour une liste concrète de fichiers et un exemple détaillé. +d’un seul fournisseur. Voir le [Recueil de recettes des capacités](/fr/plugins/architecture) +pour une checklist concrète de fichiers et un exemple détaillé. -### Liste de contrôle des capacités +### Checklist de capacité -Lorsque vous ajoutez une nouvelle capacité, l’implémentation doit généralement toucher ensemble ces -surfaces : +Lorsque vous ajoutez une nouvelle capacité, l’implémentation doit généralement toucher +ces surfaces ensemble : -- types de contrat du cœur dans `src//types.ts` -- runner du cœur/assistant d’exécution dans `src//runtime.ts` +- types du contrat cœur dans `src//types.ts` +- helper cœur de runner/runtime dans `src//runtime.ts` - surface d’enregistrement de l’API des plugins dans `src/plugins/types.ts` - câblage du registre des plugins dans `src/plugins/registry.ts` -- exposition de l’exécution des plugins dans `src/plugins/runtime/*` lorsque les plugins de fonctionnalité/de canal - doivent la consommer -- assistants de capture/test dans `src/test-utils/plugin-registration.ts` -- assertions de propriété/de contrat dans `src/plugins/contracts/registry.ts` +- exposition du runtime des plugins dans `src/plugins/runtime/*` lorsque les plugins de fonctionnalité/canal + doivent le consommer +- helpers de capture/test dans `src/test-utils/plugin-registration.ts` +- assertions de propriété/contrat dans `src/plugins/contracts/registry.ts` - documentation opérateur/plugin dans `docs/` Si l’une de ces surfaces manque, c’est généralement le signe que la capacité n’est -pas encore entièrement intégrée. +pas encore totalement intégrée. ### Modèle de capacité -Motif minimal : +Modèle minimal : ```ts -// contrat du cœur +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API du plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1589,14 +1641,14 @@ api.registerVideoGenerationProvider({ }, }); -// assistant d’exécution partagé pour les plugins de fonctionnalité/de canal +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ - prompt: "Montre le robot marchant dans le laboratoire.", + prompt: "Show the robot walking through the lab.", cfg, }); ``` -Motif de test de contrat : +Modèle de test de contrat : ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1606,5 +1658,5 @@ Cela garde la règle simple : - le cœur possède le contrat de capacité + l’orchestration - les plugins fournisseurs possèdent les implémentations fournisseur -- les plugins de fonctionnalité/de canal consomment les assistants d’exécution -- les tests de contrat gardent une propriété explicite +- les plugins de fonctionnalité/canal consomment les helpers d’exécution +- les tests de contrat gardent la propriété explicite diff --git a/docs/fr/plugins/manifest.md b/docs/fr/plugins/manifest.md index ead95204c..74175fe05 100644 --- a/docs/fr/plugins/manifest.md +++ b/docs/fr/plugins/manifest.md @@ -1,73 +1,73 @@ --- read_when: - Vous créez un plugin OpenClaw - - Vous devez fournir un schéma de configuration de plugin ou déboguer des erreurs de validation du plugin -summary: Exigences du manifeste de plugin + schéma JSON (validation stricte de la configuration) -title: Manifeste de plugin + - Vous devez fournir un schéma de configuration du plugin ou déboguer des erreurs de validation du plugin +summary: Exigences du manifeste du plugin + du schéma JSON (validation stricte de la configuration) +title: Manifeste du plugin x-i18n: - generated_at: "2026-04-11T15:16:01Z" + generated_at: "2026-04-12T06:49:41Z" model: gpt-5.4 provider: openai - source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 + source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91 source_path: plugins/manifest.md workflow: 15 --- -# Manifeste de plugin (`openclaw.plugin.json`) +# Manifeste du plugin (`openclaw.plugin.json`) -Cette page concerne uniquement le **manifeste de plugin natif OpenClaw**. +Cette page concerne uniquement le **manifeste natif de plugin OpenClaw**. Pour les dispositions de bundles compatibles, voir [Bundles de plugins](/fr/plugins/bundles). Les formats de bundle compatibles utilisent des fichiers de manifeste différents : - Bundle Codex : `.codex-plugin/plugin.json` -- Bundle Claude : `.claude-plugin/plugin.json` ou la disposition par défaut du composant Claude +- Bundle Claude : `.claude-plugin/plugin.json` ou la disposition par défaut des composants Claude sans manifeste - Bundle Cursor : `.cursor-plugin/plugin.json` OpenClaw détecte automatiquement ces dispositions de bundle également, mais elles ne sont pas validées par rapport au schéma `openclaw.plugin.json` décrit ici. -Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les -racines de compétences déclarées, les racines de commandes Claude, les valeurs par défaut de `settings.json` du bundle Claude, +Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les racines de +skills déclarées, les racines de commandes Claude, les valeurs par défaut de `settings.json` du bundle Claude, les valeurs par défaut LSP du bundle Claude, et les packs de hooks pris en charge lorsque la disposition correspond -aux attentes d’exécution d’OpenClaw. +aux attentes d'exécution d'OpenClaw. -Chaque plugin OpenClaw natif **doit** fournir un fichier `openclaw.plugin.json` dans la +Chaque plugin natif OpenClaw **doit** fournir un fichier `openclaw.plugin.json` dans la **racine du plugin**. OpenClaw utilise ce manifeste pour valider la configuration -**sans exécuter le code du plugin**. Les manifestes manquants ou invalides sont traités comme des -erreurs de plugin et bloquent la validation de la configuration. +**sans exécuter le code du plugin**. Les manifestes absents ou invalides sont traités comme +des erreurs de plugin et bloquent la validation de la configuration. -Consultez le guide complet du système de plugins : [Plugins](/fr/tools/plugin). -Pour le modèle de capacités natif et les recommandations actuelles de compatibilité externe : +Voir le guide complet du système de plugins : [Plugins](/fr/tools/plugin). +Pour le modèle natif de capacités et les recommandations actuelles de compatibilité externe : [Modèle de capacités](/fr/plugins/architecture#public-capability-model). ## À quoi sert ce fichier -`openclaw.plugin.json` contient les métadonnées qu’OpenClaw lit avant de charger le -code de votre plugin. +`openclaw.plugin.json` est la métadonnée qu'OpenClaw lit avant de charger le code de votre +plugin. Utilisez-le pour : -- l’identité du plugin +- l'identité du plugin - la validation de la configuration -- les métadonnées d’authentification et d’intégration qui doivent être disponibles sans démarrer l’exécution du plugin -- les indices d’activation légers que les surfaces du plan de contrôle peuvent inspecter avant le chargement de l’exécution -- les descripteurs de configuration légers que les surfaces de configuration/intégration peuvent inspecter avant le chargement de l’exécution -- les métadonnées d’alias et d’activation automatique qui doivent être résolues avant le chargement de l’exécution du plugin -- les métadonnées abrégées de propriété de famille de modèles qui doivent activer automatiquement le plugin avant le chargement de l’exécution -- les instantanés statiques de propriété de capacités utilisés pour le câblage de compatibilité groupée et la couverture des contrats -- les métadonnées de configuration spécifiques aux canaux qui doivent être fusionnées dans les surfaces de catalogue et de validation sans charger l’exécution -- les indices d’interface pour la configuration +- les métadonnées d'authentification et d'intégration qui doivent être disponibles sans démarrer l'environnement d'exécution du plugin +- les indices d'activation peu coûteux que les surfaces du plan de contrôle peuvent inspecter avant le chargement de l'environnement d'exécution +- les descripteurs de configuration peu coûteux que les surfaces de configuration/intégration peuvent inspecter avant le chargement de l'environnement d'exécution +- les métadonnées d'alias et d'activation automatique qui doivent être résolues avant le chargement de l'environnement d'exécution du plugin +- les métadonnées abrégées de propriété de familles de modèles qui doivent activer automatiquement le plugin avant le chargement de l'environnement d'exécution +- les instantanés statiques de propriété des capacités utilisés pour le câblage de compatibilité des plugins intégrés et la couverture des contrats +- les métadonnées de configuration spécifiques aux canaux qui doivent être fusionnées dans les surfaces de catalogue et de validation sans charger l'environnement d'exécution +- les indications d'interface utilisateur pour la configuration -Ne l’utilisez pas pour : +Ne l'utilisez pas pour : -- enregistrer le comportement d’exécution -- déclarer des points d’entrée de code -- les métadonnées d’installation npm +- enregistrer le comportement à l'exécution +- déclarer les points d'entrée du code +- les métadonnées d'installation npm -Ces éléments appartiennent au code de votre plugin et à `package.json`. +Ces éléments appartiennent à votre code de plugin et à `package.json`. ## Exemple minimal @@ -88,7 +88,7 @@ Ces éléments appartiennent au code de votre plugin et à `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin de fournisseur OpenRouter", + "description": "Plugin fournisseur OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -138,64 +138,64 @@ Ces éléments appartiennent au code de votre plugin et à `package.json`. } ``` -## Référence des champs de niveau supérieur +## Référence des champs de premier niveau -| Champ | Obligatoire | Type | Signification | -| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Oui | `string` | ID canonique du plugin. Il s’agit de l’ID utilisé dans `plugins.entries.`. | -| `configSchema` | Oui | `object` | Schéma JSON inline pour la configuration de ce plugin. | -| `enabledByDefault` | Non | `true` | Marque un plugin groupé comme activé par défaut. Omettez-le, ou définissez toute valeur autre que `true`, pour laisser le plugin désactivé par défaut. | -| `legacyPluginIds` | Non | `string[]` | IDs hérités qui sont normalisés vers cet ID canonique de plugin. | -| `autoEnableWhenConfiguredProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer automatiquement ce plugin lorsque l’authentification, la configuration ou les références de modèles les mentionnent. | +| Champ | Obligatoire | Type | Signification | +| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Oui | `string` | ID canonique du plugin. Il s'agit de l'ID utilisé dans `plugins.entries.`. | +| `configSchema` | Oui | `object` | Schéma JSON en ligne pour la configuration de ce plugin. | +| `enabledByDefault` | Non | `true` | Indique qu'un plugin intégré est activé par défaut. Omettez-le, ou définissez une valeur autre que `true`, pour laisser le plugin désactivé par défaut. | +| `legacyPluginIds` | Non | `string[]` | IDs hérités qui se normalisent vers cet ID canonique de plugin. | +| `autoEnableWhenConfiguredProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer automatiquement ce plugin lorsque l'authentification, la configuration ou les références de modèle les mentionnent. | | `kind` | Non | `"memory"` \| `"context-engine"` | Déclare un type exclusif de plugin utilisé par `plugins.slots.*`. | | `channels` | Non | `string[]` | IDs de canaux appartenant à ce plugin. Utilisés pour la découverte et la validation de la configuration. | -| `providers` | Non | `string[]` | IDs de fournisseurs appartenant à ce plugin. | -| `modelSupport` | Non | `object` | Métadonnées abrégées de famille de modèles possédées par le manifeste, utilisées pour charger automatiquement le plugin avant l’exécution. | -| `cliBackends` | Non | `string[]` | IDs de backends d’inférence CLI appartenant à ce plugin. Utilisés pour l’auto-activation au démarrage à partir de références de configuration explicites. | -| `commandAliases` | Non | `object[]` | Noms de commandes appartenant à ce plugin qui doivent produire une configuration sensible au plugin et des diagnostics CLI avant le chargement de l’exécution. | -| `providerAuthEnvVars` | Non | `Record` | Métadonnées légères de variables d’environnement d’authentification fournisseur qu’OpenClaw peut inspecter sans charger le code du plugin. | -| `providerAuthAliases` | Non | `Record` | IDs de fournisseurs qui doivent réutiliser un autre ID de fournisseur pour la recherche d’authentification, par exemple un fournisseur de code qui partage la clé API et les profils d’authentification du fournisseur de base. | -| `channelEnvVars` | Non | `Record` | Métadonnées légères de variables d’environnement de canal qu’OpenClaw peut inspecter sans charger le code du plugin. Utilisez-les pour les surfaces de configuration ou d’authentification de canaux pilotées par des variables d’environnement que les assistants génériques de démarrage/configuration doivent voir. | -| `providerAuthChoices` | Non | `object[]` | Métadonnées légères de choix d’authentification pour les sélecteurs d’intégration, la résolution du fournisseur préféré et le câblage simple des options CLI. | -| `activation` | Non | `object` | Indices d’activation légers pour le chargement déclenché par les fournisseurs, commandes, canaux, routes et capacités. Métadonnées uniquement ; l’exécution du plugin reste propriétaire du comportement réel. | -| `setup` | Non | `object` | Descripteurs légers de configuration/intégration que les surfaces de découverte et de configuration peuvent inspecter sans charger l’exécution du plugin. | -| `contracts` | Non | `object` | Instantané statique des capacités groupées pour la parole, la transcription en temps réel, la voix en temps réel, la compréhension des médias, la génération d’images, la génération de musique, la génération de vidéo, la récupération web, la recherche web et la propriété des outils. | -| `channelConfigs` | Non | `Record` | Métadonnées de configuration de canal possédées par le manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement de l’exécution. | -| `skills` | Non | `string[]` | Répertoires Skills à charger, relatifs à la racine du plugin. | -| `name` | Non | `string` | Nom lisible du plugin. | -| `description` | Non | `string` | Résumé court affiché dans les surfaces de plugin. | -| `version` | Non | `string` | Version informative du plugin. | -| `uiHints` | Non | `Record` | Libellés d’interface, espaces réservés et indices de sensibilité pour les champs de configuration. | +| `providers` | Non | `string[]` | IDs de fournisseurs appartenant à ce plugin. | +| `modelSupport` | Non | `object` | Métadonnées abrégées de familles de modèles détenues par le manifeste, utilisées pour charger automatiquement le plugin avant l'environnement d'exécution. | +| `cliBackends` | Non | `string[]` | IDs de backends d'inférence CLI appartenant à ce plugin. Utilisés pour l'activation automatique au démarrage à partir de références de configuration explicites. | +| `commandAliases` | Non | `object[]` | Noms de commandes appartenant à ce plugin qui doivent produire une configuration et des diagnostics CLI tenant compte du plugin avant le chargement de l'environnement d'exécution. | +| `providerAuthEnvVars` | Non | `Record` | Métadonnées légères d'environnement d'authentification fournisseur qu'OpenClaw peut inspecter sans charger le code du plugin. | +| `providerAuthAliases` | Non | `Record` | IDs de fournisseurs qui doivent réutiliser un autre ID de fournisseur pour la recherche d'authentification, par exemple un fournisseur de code qui partage la clé API et les profils d'authentification du fournisseur de base. | +| `channelEnvVars` | Non | `Record` | Métadonnées légères de variables d'environnement de canal qu'OpenClaw peut inspecter sans charger le code du plugin. Utilisez-les pour une configuration ou des surfaces d'authentification de canal pilotées par l'environnement que les aides génériques de démarrage/configuration doivent voir. | +| `providerAuthChoices` | Non | `object[]` | Métadonnées légères de choix d'authentification pour les sélecteurs d'intégration, la résolution des fournisseurs préférés et le raccordement simple des indicateurs CLI. | +| `activation` | Non | `object` | Indices d'activation peu coûteux pour le chargement déclenché par un fournisseur, une commande, un canal, une route ou une capacité. Métadonnées uniquement ; l'environnement d'exécution du plugin reste responsable du comportement réel. | +| `setup` | Non | `object` | Descripteurs légers de configuration/intégration que les surfaces de découverte et de configuration peuvent inspecter sans charger l'environnement d'exécution du plugin. | +| `contracts` | Non | `object` | Instantané statique de capacités intégrées pour la parole, la transcription en temps réel, la voix en temps réel, la compréhension des médias, la génération d'images, la génération de musique, la génération de vidéos, la récupération Web, la recherche Web, et la propriété des outils. | +| `channelConfigs` | Non | `Record` | Métadonnées de configuration de canal détenues par le manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement de l'environnement d'exécution. | +| `skills` | Non | `string[]` | Répertoires de Skills à charger, relatifs à la racine du plugin. | +| `name` | Non | `string` | Nom lisible du plugin. | +| `description` | Non | `string` | Résumé court affiché dans les surfaces de plugin. | +| `version` | Non | `string` | Version informative du plugin. | +| `uiHints` | Non | `Record` | Libellés d'interface, espaces réservés et indications de sensibilité pour les champs de configuration. | -## Référence de `providerAuthChoices` +## Référence `providerAuthChoices` -Chaque entrée `providerAuthChoices` décrit un choix d’intégration ou d’authentification. -OpenClaw lit ces informations avant le chargement de l’exécution du fournisseur. +Chaque entrée `providerAuthChoices` décrit un choix d'intégration ou d'authentification. +OpenClaw lit ceci avant le chargement de l'environnement d'exécution du fournisseur. | Champ | Obligatoire | Type | Signification | | --------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Oui | `string` | ID du fournisseur auquel appartient ce choix. | -| `method` | Oui | `string` | ID de méthode d’authentification vers lequel dispatcher. | -| `choiceId` | Oui | `string` | ID stable de choix d’authentification utilisé par les flux d’intégration et CLI. | -| `choiceLabel` | Non | `string` | Libellé visible par l’utilisateur. S’il est omis, OpenClaw utilise `choiceId` comme repli. | -| `choiceHint` | Non | `string` | Court texte d’aide pour le sélecteur. | -| `assistantPriority` | Non | `number` | Les valeurs plus basses sont triées plus tôt dans les sélecteurs interactifs pilotés par l’assistant. | -| `assistantVisibility` | Non | `"visible"` \| `"manual-only"` | Masque ce choix dans les sélecteurs de l’assistant tout en autorisant sa sélection manuelle via la CLI. | -| `deprecatedChoiceIds` | Non | `string[]` | IDs de choix hérités qui doivent rediriger les utilisateurs vers ce choix de remplacement. | +| `provider` | Oui | `string` | ID du fournisseur auquel ce choix appartient. | +| `method` | Oui | `string` | ID de la méthode d'authentification vers laquelle effectuer le routage. | +| `choiceId` | Oui | `string` | ID stable de choix d'authentification utilisé par les flux d'intégration et de CLI. | +| `choiceLabel` | Non | `string` | Libellé destiné à l'utilisateur. S'il est omis, OpenClaw utilise `choiceId` comme valeur de repli. | +| `choiceHint` | Non | `string` | Court texte d'aide pour le sélecteur. | +| `assistantPriority` | Non | `number` | Les valeurs les plus faibles sont triées en premier dans les sélecteurs interactifs pilotés par l'assistant. | +| `assistantVisibility` | Non | `"visible"` \| `"manual-only"` | Masque ce choix dans les sélecteurs de l'assistant tout en autorisant la sélection manuelle via la CLI. | +| `deprecatedChoiceIds` | Non | `string[]` | IDs hérités de choix qui doivent rediriger les utilisateurs vers ce choix de remplacement. | | `groupId` | Non | `string` | ID de groupe facultatif pour regrouper des choix liés. | -| `groupLabel` | Non | `string` | Libellé visible par l’utilisateur pour ce groupe. | -| `groupHint` | Non | `string` | Court texte d’aide pour le groupe. | -| `optionKey` | Non | `string` | Clé d’option interne pour les flux d’authentification simples à un seul drapeau. | -| `cliFlag` | Non | `string` | Nom du drapeau CLI, par exemple `--openrouter-api-key`. | -| `cliOption` | Non | `string` | Forme complète de l’option CLI, par exemple `--openrouter-api-key `. | -| `cliDescription` | Non | `string` | Description utilisée dans l’aide CLI. | -| `onboardingScopes` | Non | `Array<"text-inference" \| "image-generation">` | Sur quelles surfaces d’intégration ce choix doit apparaître. Si omis, la valeur par défaut est `["text-inference"]`. | +| `groupLabel` | Non | `string` | Libellé destiné à l'utilisateur pour ce groupe. | +| `groupHint` | Non | `string` | Court texte d'aide pour le groupe. | +| `optionKey` | Non | `string` | Clé d'option interne pour les flux d'authentification simples à un seul indicateur. | +| `cliFlag` | Non | `string` | Nom d'indicateur CLI, par exemple `--openrouter-api-key`. | +| `cliOption` | Non | `string` | Forme complète de l'option CLI, par exemple `--openrouter-api-key `. | +| `cliDescription` | Non | `string` | Description utilisée dans l'aide de la CLI. | +| `onboardingScopes` | Non | `Array<"text-inference" \| "image-generation">` | Sur quelles surfaces d'intégration ce choix doit apparaître. Si omis, la valeur par défaut est `["text-inference"]`. | -## Référence de `commandAliases` +## Référence `commandAliases` -Utilisez `commandAliases` lorsqu’un plugin possède un nom de commande d’exécution que les utilisateurs peuvent -mettre par erreur dans `plugins.allow` ou essayer d’exécuter comme commande CLI racine. OpenClaw -utilise ces métadonnées pour les diagnostics sans importer le code d’exécution du plugin. +Utilisez `commandAliases` lorsqu'un plugin possède un nom de commande d'exécution que les utilisateurs peuvent +par erreur placer dans `plugins.allow` ou essayer d'exécuter comme commande CLI racine. OpenClaw +utilise ces métadonnées pour les diagnostics sans importer le code d'exécution du plugin. ```json { @@ -209,19 +209,19 @@ utilise ces métadonnées pour les diagnostics sans importer le code d’exécut } ``` -| Champ | Obligatoire | Type | Signification | -| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Oui | `string` | Nom de commande qui appartient à ce plugin. | -| `kind` | Non | `"runtime-slash"` | Marque l’alias comme une commande slash de chat plutôt qu’une commande CLI racine. | +| Champ | Obligatoire | Type | Signification | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | +| `name` | Oui | `string` | Nom de commande appartenant à ce plugin. | +| `kind` | Non | `"runtime-slash"` | Indique que l'alias est une commande slash de chat plutôt qu'une commande CLI racine. | | `cliCommand` | Non | `string` | Commande CLI racine associée à suggérer pour les opérations CLI, si elle existe. | -## Référence de `activation` +## Référence `activation` Utilisez `activation` lorsque le plugin peut déclarer à faible coût quels événements du plan de contrôle -doivent l’activer plus tard. +doivent l'activer plus tard. -Ce bloc contient uniquement des métadonnées. Il n’enregistre pas de comportement d’exécution, et il -ne remplace pas `register(...)`, `setupEntry` ou d’autres points d’entrée d’exécution/plugin. +Ce bloc contient uniquement des métadonnées. Il n'enregistre pas de comportement à l'exécution, et il ne +remplace pas `register(...)`, `setupEntry`, ni d'autres points d'entrée d'exécution/de plugin. ```json { @@ -235,18 +235,18 @@ ne remplace pas `register(...)`, `setupEntry` ou d’autres points d’entrée d } ``` -| Champ | Obligatoire | Type | Signification | -| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------- | -| `onProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer ce plugin lorsqu’ils sont demandés. | -| `onCommands` | Non | `string[]` | IDs de commandes qui doivent activer ce plugin. | -| `onChannels` | Non | `string[]` | IDs de canaux qui doivent activer ce plugin. | -| `onRoutes` | Non | `string[]` | Types de routes qui doivent activer ce plugin. | -| `onCapabilities` | Non | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Indices généraux de capacités utilisés par la planification d’activation du plan de contrôle. | +| Champ | Obligatoire | Type | Signification | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ | +| `onProviders` | Non | `string[]` | IDs de fournisseurs qui doivent activer ce plugin lorsqu'ils sont demandés. | +| `onCommands` | Non | `string[]` | IDs de commandes qui doivent activer ce plugin. | +| `onChannels` | Non | `string[]` | IDs de canaux qui doivent activer ce plugin. | +| `onRoutes` | Non | `string[]` | Types de routes qui doivent activer ce plugin. | +| `onCapabilities` | Non | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Indices généraux de capacités utilisés par la planification d'activation du plan de contrôle. | -## Référence de `setup` +## Référence `setup` -Utilisez `setup` lorsque les surfaces de configuration et d’intégration ont besoin de métadonnées légères appartenant au plugin -avant le chargement de l’exécution. +Utilisez `setup` lorsque les surfaces de configuration et d'intégration ont besoin de métadonnées légères détenues par le plugin +avant le chargement de l'environnement d'exécution. ```json { @@ -265,30 +265,41 @@ avant le chargement de l’exécution. } ``` -Le champ `cliBackends` de niveau supérieur reste valide et continue de décrire les -backends d’inférence CLI. `setup.cliBackends` est la surface de descripteur spécifique à la configuration pour -les flux du plan de contrôle/de configuration qui doivent rester purement basés sur des métadonnées. +Le champ de premier niveau `cliBackends` reste valide et continue de décrire les +backends d'inférence CLI. `setup.cliBackends` est la surface de descripteur spécifique à la configuration pour les +flux de plan de contrôle/configuration qui doivent rester uniquement des métadonnées. -### Référence de `setup.providers` +Lorsqu'ils sont présents, `setup.providers` et `setup.cliBackends` sont la surface de recherche +préférée basée sur les descripteurs pour la découverte de la configuration. Si le descripteur ne fait +que restreindre le plugin candidat et que la configuration a encore besoin de hooks d'exécution plus riches au moment de la configuration, +définissez `requiresRuntime: true` et conservez `setup-api` comme +chemin d'exécution de repli. -| Champ | Obligatoire | Type | Signification | -| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | -| `id` | Oui | `string` | ID du fournisseur exposé pendant la configuration ou l’intégration. | -| `authMethods` | Non | `string[]` | IDs de méthodes de configuration/authentification que ce fournisseur prend en charge sans charger l’exécution complète. | -| `envVars` | Non | `string[]` | Variables d’environnement que les surfaces génériques de configuration/statut peuvent vérifier avant le chargement de l’exécution du plugin. | +Étant donné que la recherche de configuration peut exécuter du code `setup-api` détenu par le plugin, les valeurs normalisées +`setup.providers[].id` et `setup.cliBackends[]` doivent rester uniques parmi les plugins +découverts. Une propriété ambiguë échoue de manière fermée au lieu de choisir un +gagnant selon l'ordre de découverte. -### Champs de `setup` +### Référence `setup.providers` -| Champ | Obligatoire | Type | Signification | -| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------- | -| `providers` | Non | `object[]` | Descripteurs de configuration de fournisseur exposés pendant la configuration et l’intégration. | -| `cliBackends` | Non | `string[]` | IDs de backend disponibles au moment de la configuration sans activation complète de l’exécution. | -| `configMigrations` | Non | `string[]` | IDs de migration de configuration appartenant à la surface de configuration de ce plugin. | -| `requiresRuntime` | Non | `boolean` | Indique si la configuration nécessite encore l’exécution du plugin après la recherche du descripteur. | +| Champ | Obligatoire | Type | Signification | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Oui | `string` | ID du fournisseur exposé pendant la configuration ou l'intégration. Conservez des IDs normalisés globalement uniques. | +| `authMethods` | Non | `string[]` | IDs de méthodes de configuration/authentification que ce fournisseur prend en charge sans charger l'environnement d'exécution complet. | +| `envVars` | Non | `string[]` | Variables d'environnement que les surfaces génériques de configuration/statut peuvent vérifier avant le chargement de l'environnement d'exécution du plugin. | -## Référence de `uiHints` +### Champs `setup` -`uiHints` est une map des noms de champs de configuration vers de petits indices de rendu. +| Champ | Obligatoire | Type | Signification | +| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `providers` | Non | `object[]` | Descripteurs de configuration de fournisseurs exposés pendant la configuration et l'intégration. | +| `cliBackends` | Non | `string[]` | IDs de backends au moment de la configuration utilisés pour la recherche de configuration basée d'abord sur les descripteurs. Conservez des IDs normalisés globalement uniques. | +| `configMigrations` | Non | `string[]` | IDs de migration de configuration appartenant à la surface de configuration de ce plugin. | +| `requiresRuntime` | Non | `boolean` | Indique si la configuration nécessite encore l'exécution de `setup-api` après la recherche par descripteurs. | + +## Référence `uiHints` + +`uiHints` est une correspondance entre les noms de champs de configuration et de petites indications de rendu. ```json { @@ -303,21 +314,21 @@ les flux du plan de contrôle/de configuration qui doivent rester purement basé } ``` -Chaque indice de champ peut inclure : +Chaque indication de champ peut inclure : -| Champ | Type | Signification | -| ------------- | ---------- | -------------------------------------- | -| `label` | `string` | Libellé du champ visible par l’utilisateur. | -| `help` | `string` | Court texte d’aide. | -| `tags` | `string[]` | Étiquettes d’interface facultatives. | -| `advanced` | `boolean` | Marque le champ comme avancé. | +| Champ | Type | Signification | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Libellé du champ destiné à l'utilisateur. | +| `help` | `string` | Court texte d'aide. | +| `tags` | `string[]` | Balises d'interface facultatives. | +| `advanced` | `boolean` | Marque le champ comme avancé. | | `sensitive` | `boolean` | Marque le champ comme secret ou sensible. | -| `placeholder` | `string` | Texte d’espace réservé pour les champs de formulaire. | +| `placeholder` | `string` | Texte d'espace réservé pour les champs de formulaire. | -## Référence de `contracts` +## Référence `contracts` -Utilisez `contracts` uniquement pour les métadonnées statiques de propriété de capacités qu’OpenClaw peut -lire sans importer l’exécution du plugin. +Utilisez `contracts` uniquement pour les métadonnées statiques de propriété de capacités qu'OpenClaw peut +lire sans importer l'environnement d'exécution du plugin. ```json { @@ -337,22 +348,22 @@ lire sans importer l’exécution du plugin. Chaque liste est facultative : -| Champ | Type | Signification | -| -------------------------------- | ---------- | ------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs des fournisseurs de parole appartenant à ce plugin. | -| `realtimeTranscriptionProviders` | `string[]` | IDs des fournisseurs de transcription en temps réel appartenant à ce plugin. | -| `realtimeVoiceProviders` | `string[]` | IDs des fournisseurs de voix en temps réel appartenant à ce plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs des fournisseurs de compréhension des médias appartenant à ce plugin. | -| `imageGenerationProviders` | `string[]` | IDs des fournisseurs de génération d’images appartenant à ce plugin. | -| `videoGenerationProviders` | `string[]` | IDs des fournisseurs de génération de vidéo appartenant à ce plugin. | -| `webFetchProviders` | `string[]` | IDs des fournisseurs de récupération web appartenant à ce plugin. | -| `webSearchProviders` | `string[]` | IDs des fournisseurs de recherche web appartenant à ce plugin. | -| `tools` | `string[]` | Noms d’outils d’agent appartenant à ce plugin pour les vérifications de contrats groupés. | +| Champ | Type | Signification | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | IDs de fournisseurs vocaux appartenant à ce plugin. | +| `realtimeTranscriptionProviders` | `string[]` | IDs de fournisseurs de transcription en temps réel appartenant à ce plugin. | +| `realtimeVoiceProviders` | `string[]` | IDs de fournisseurs vocaux en temps réel appartenant à ce plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs de fournisseurs de compréhension des médias appartenant à ce plugin. | +| `imageGenerationProviders` | `string[]` | IDs de fournisseurs de génération d'images appartenant à ce plugin. | +| `videoGenerationProviders` | `string[]` | IDs de fournisseurs de génération de vidéos appartenant à ce plugin. | +| `webFetchProviders` | `string[]` | IDs de fournisseurs de récupération Web appartenant à ce plugin. | +| `webSearchProviders` | `string[]` | IDs de fournisseurs de recherche Web appartenant à ce plugin. | +| `tools` | `string[]` | Noms d'outils d'agent appartenant à ce plugin pour les vérifications de contrat des plugins intégrés. | -## Référence de `channelConfigs` +## Référence `channelConfigs` -Utilisez `channelConfigs` lorsqu’un plugin de canal a besoin de métadonnées de configuration légères avant -le chargement de l’exécution. +Utilisez `channelConfigs` lorsqu'un plugin de canal a besoin de métadonnées de configuration légères avant le +chargement de l'environnement d'exécution. ```json { @@ -381,18 +392,19 @@ le chargement de l’exécution. Chaque entrée de canal peut inclure : -| Champ | Type | Signification | -| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| Champ | Type | Signification | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | | `schema` | `object` | Schéma JSON pour `channels.`. Obligatoire pour chaque entrée déclarée de configuration de canal. | -| `uiHints` | `Record` | Libellés d’interface, espaces réservés et indices de sensibilité facultatifs pour cette section de configuration de canal. | -| `label` | `string` | Libellé du canal fusionné dans les surfaces de sélecteur et d’inspection lorsque les métadonnées d’exécution ne sont pas prêtes. | -| `description` | `string` | Brève description du canal pour les surfaces d’inspection et de catalogue. | -| `preferOver` | `string[]` | IDs de plugins hérités ou de priorité inférieure que ce canal doit surpasser dans les surfaces de sélection. | +| `uiHints` | `Record` | Libellés d'interface, espaces réservés et indications de sensibilité facultatifs pour cette section de configuration du canal. | +| `label` | `string` | Libellé du canal fusionné dans les surfaces de sélection et d'inspection lorsque les métadonnées d'exécution ne sont pas prêtes. | +| `description` | `string` | Description courte du canal pour les surfaces d'inspection et de catalogue. | +| `preferOver` | `string[]` | IDs de plugins hérités ou de priorité inférieure que ce canal doit supplanter dans les surfaces de sélection. | -## Référence de `modelSupport` +## Référence `modelSupport` -Utilisez `modelSupport` lorsqu’OpenClaw doit déduire votre plugin fournisseur à partir -d’IDs de modèles abrégés comme `gpt-5.4` ou `claude-sonnet-4.6` avant le chargement de l’exécution du plugin. +Utilisez `modelSupport` lorsqu'OpenClaw doit déduire votre plugin fournisseur à partir +d'IDs abrégés de modèles comme `gpt-5.4` ou `claude-sonnet-4.6` avant le chargement de l'environnement d'exécution +du plugin. ```json { @@ -405,74 +417,74 @@ d’IDs de modèles abrégés comme `gpt-5.4` ou `claude-sonnet-4.6` avant le ch OpenClaw applique cet ordre de priorité : -- les références explicites `provider/model` utilisent les métadonnées `providers` du manifeste propriétaire -- `modelPatterns` ont priorité sur `modelPrefixes` -- si un plugin non groupé et un plugin groupé correspondent tous deux, le plugin non groupé - l’emporte -- les ambiguïtés restantes sont ignorées jusqu’à ce que l’utilisateur ou la configuration spécifie un fournisseur +- les références explicites `provider/model` utilisent les métadonnées du manifeste `providers` propriétaire +- `modelPatterns` a priorité sur `modelPrefixes` +- si un plugin non intégré et un plugin intégré correspondent tous deux, le plugin non intégré + l'emporte +- les ambiguïtés restantes sont ignorées jusqu'à ce que l'utilisateur ou la configuration spécifie un fournisseur Champs : -| Champ | Type | Signification | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Préfixes comparés avec `startsWith` aux IDs de modèles abrégés. | -| `modelPatterns` | `string[]` | Sources regex comparées aux IDs de modèles abrégés après suppression du suffixe de profil. | +| Champ | Type | Signification | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Préfixes mis en correspondance avec `startsWith` par rapport aux IDs abrégés de modèles. | +| `modelPatterns` | `string[]` | Sources regex mises en correspondance avec les IDs abrégés de modèles après suppression du suffixe de profil. | -Les clés de capacité héritées au niveau supérieur sont obsolètes. Utilisez `openclaw doctor --fix` pour +Les clés héritées de capacités au niveau supérieur sont obsolètes. Utilisez `openclaw doctor --fix` pour déplacer `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` et `webSearchProviders` sous `contracts` ; le chargement normal -du manifeste ne traite plus ces champs de niveau supérieur comme de la -propriété de capacités. +du manifeste ne traite plus ces champs de niveau supérieur comme propriété +de capacités. ## Manifeste versus package.json -Les deux fichiers ont des rôles différents : +Les deux fichiers remplissent des rôles différents : -| Fichier | À utiliser pour | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | La découverte, la validation de la configuration, les métadonnées de choix d’authentification et les indices d’interface qui doivent exister avant l’exécution du code du plugin | -| `package.json` | Les métadonnées npm, l’installation des dépendances, et le bloc `openclaw` utilisé pour les points d’entrée, le contrôle d’installation, la configuration ou les métadonnées de catalogue | +| Fichier | Utilisation | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Découverte, validation de la configuration, métadonnées de choix d'authentification et indications d'interface qui doivent exister avant l'exécution du code du plugin | +| `package.json` | Métadonnées npm, installation des dépendances, et bloc `openclaw` utilisé pour les points d'entrée, le contrôle d'installation, la configuration ou les métadonnées de catalogue | -Si vous ne savez pas où placer une métadonnée, utilisez cette règle : +Si vous ne savez pas où une métadonnée doit aller, utilisez cette règle : -- si OpenClaw doit la connaître avant de charger le code du plugin, placez-la dans `openclaw.plugin.json` -- si elle concerne le packaging, les fichiers de point d’entrée ou le comportement d’installation npm, placez-la dans `package.json` +- si OpenClaw doit la connaître avant de charger le code du plugin, mettez-la dans `openclaw.plugin.json` +- si elle concerne le packaging, les fichiers d'entrée ou le comportement d'installation npm, mettez-la dans `package.json` -### Champs de `package.json` qui affectent la découverte +### Champs `package.json` qui affectent la découverte -Certaines métadonnées de plugin avant exécution vivent intentionnellement dans `package.json` sous le bloc -`openclaw` plutôt que dans `openclaw.plugin.json`. +Certaines métadonnées de plugin avant exécution résident intentionnellement dans `package.json` sous le +bloc `openclaw` plutôt que dans `openclaw.plugin.json`. Exemples importants : -| Champ | Signification | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Déclare les points d’entrée de plugins natifs. | -| `openclaw.setupEntry` | Point d’entrée léger réservé à la configuration utilisé pendant l’intégration et le démarrage différé des canaux. | -| `openclaw.channel` | Métadonnées légères du catalogue de canaux comme les libellés, les chemins de documentation, les alias et le texte de sélection. | -| `openclaw.channel.configuredState` | Métadonnées légères de vérification de l’état configuré qui peuvent répondre à « une configuration basée uniquement sur l’environnement existe-t-elle déjà ? » sans charger l’exécution complète du canal. | -| `openclaw.channel.persistedAuthState` | Métadonnées légères de vérification d’authentification persistée qui peuvent répondre à « quelque chose est-il déjà connecté ? » sans charger l’exécution complète du canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indices d’installation/mise à jour pour les plugins groupés et publiés en externe. | -| `openclaw.install.defaultChoice` | Chemin d’installation préféré lorsque plusieurs sources d’installation sont disponibles. | -| `openclaw.install.minHostVersion` | Version minimale prise en charge de l’hôte OpenClaw, en utilisant un plancher semver comme `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Autorise un chemin de récupération de réinstallation étroit pour les plugins groupés lorsque la configuration est invalide. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permet aux surfaces de canal réservées à la configuration de se charger avant le plugin de canal complet pendant le démarrage. | +| Champ | Signification | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Déclare les points d'entrée des plugins natifs. | +| `openclaw.setupEntry` | Point d'entrée léger réservé à la configuration, utilisé pendant l'intégration et le démarrage différé des canaux. | +| `openclaw.channel` | Métadonnées légères du catalogue de canaux comme les libellés, les chemins de documentation, les alias et le texte de sélection. | +| `openclaw.channel.configuredState` | Métadonnées légères du vérificateur d'état configuré pouvant répondre à « une configuration uniquement par variables d'environnement existe-t-elle déjà ? » sans charger l'environnement d'exécution complet du canal. | +| `openclaw.channel.persistedAuthState` | Métadonnées légères du vérificateur d'authentification persistée pouvant répondre à « existe-t-il déjà une session connectée ? » sans charger l'environnement d'exécution complet du canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indications d'installation/mise à jour pour les plugins intégrés et publiés en externe. | +| `openclaw.install.defaultChoice` | Chemin d'installation préféré lorsque plusieurs sources d'installation sont disponibles. | +| `openclaw.install.minHostVersion` | Version minimale prise en charge de l'hôte OpenClaw, utilisant un plancher semver comme `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Autorise un chemin étroit de réinstallation de récupération pour plugin intégré lorsque la configuration est invalide. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permet aux surfaces de canal réservées à la configuration de se charger avant le plugin de canal complet au démarrage. | -`openclaw.install.minHostVersion` est appliqué pendant l’installation et lors du chargement du registre -des manifestes. Les valeurs invalides sont rejetées ; les valeurs valides mais plus récentes ignorent le +`openclaw.install.minHostVersion` est appliqué pendant l'installation et le +chargement du registre de manifestes. Les valeurs invalides sont rejetées ; les valeurs plus récentes mais valides ignorent le plugin sur les hôtes plus anciens. -`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il -ne rend pas installables des configurations cassées arbitraires. Aujourd’hui, il permet seulement aux flux d’installation -de récupérer de certains échecs obsolètes de mise à niveau de plugins groupés, comme un -chemin de plugin groupé manquant ou une entrée `channels.` obsolète pour ce même -plugin groupé. Les erreurs de configuration sans rapport bloquent toujours l’installation et redirigent les opérateurs +`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il ne +rend pas installables des configurations arbitrairement cassées. Aujourd'hui, il permet seulement aux flux d'installation +de se rétablir après certains échecs obsolètes de mise à niveau de plugins intégrés, comme un +chemin de plugin intégré manquant ou une entrée `channels.` obsolète pour ce même +plugin intégré. Les erreurs de configuration non liées bloquent toujours l'installation et redirigent les opérateurs vers `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` est une métadonnée de package pour un petit -module de vérification : +`openclaw.channel.persistedAuthState` est une métadonnée de package pour un minuscule +module vérificateur : ```json { @@ -488,13 +500,13 @@ module de vérification : } ``` -Utilisez-le lorsque les flux de configuration, doctor ou d’état configuré ont besoin d’une -vérification légère oui/non de l’authentification avant le chargement du plugin de canal complet. L’export ciblé doit être une petite -fonction qui lit uniquement l’état persisté ; ne le faites pas passer par le barrel complet d’exécution du -canal. +Utilisez-le lorsque les flux de configuration, de doctor ou d'état configuré ont besoin d'une +sonde d'authentification légère oui/non avant le chargement du plugin de canal complet. L'export cible doit être une petite +fonction qui lit uniquement l'état persisté ; ne le faites pas passer par le barrel complet +de l'environnement d'exécution du canal. -`openclaw.channel.configuredState` suit la même forme pour des vérifications légères de l’état -configuré basées uniquement sur l’environnement : +`openclaw.channel.configuredState` suit la même forme pour les vérifications légères +d'état configuré uniquement par environnement : ```json { @@ -510,65 +522,64 @@ configuré basées uniquement sur l’environnement : } ``` -Utilisez-le lorsqu’un canal peut répondre à l’état configuré à partir de l’environnement ou d’autres petites -entrées hors exécution. Si la vérification nécessite la résolution complète de la configuration ou la véritable -exécution du canal, conservez cette logique dans le hook `config.hasConfiguredState` +Utilisez-le lorsqu'un canal peut répondre à l'état configuré à partir de l'environnement ou d'autres petites +entrées hors exécution. Si la vérification nécessite la résolution complète de la configuration ou le véritable +environnement d'exécution du canal, conservez plutôt cette logique dans le hook `config.hasConfiguredState` du plugin. ## Exigences du schéma JSON -- **Chaque plugin doit fournir un schéma JSON**, même s’il n’accepte aucune configuration. +- **Chaque plugin doit fournir un schéma JSON**, même s'il n'accepte aucune configuration. - Un schéma vide est acceptable (par exemple, `{ "type": "object", "additionalProperties": false }`). -- Les schémas sont validés au moment de la lecture/écriture de la configuration, pas à l’exécution. +- Les schémas sont validés au moment de la lecture/écriture de la configuration, pas à l'exécution. ## Comportement de validation -- Les clés inconnues `channels.*` sont des **erreurs**, sauf si l’ID du canal est déclaré par +- Les clés `channels.*` inconnues sont des **erreurs**, sauf si l'ID du canal est déclaré par un manifeste de plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` et `plugins.slots.*` doivent référencer des IDs de plugin **détectables**. Les IDs inconnus sont des **erreurs**. - Si un plugin est installé mais possède un manifeste ou un schéma manquant ou cassé, - la validation échoue et Doctor signale l’erreur du plugin. -- Si la configuration du plugin existe mais que le plugin est **désactivé**, la configuration est conservée et - un **avertissement** est affiché dans Doctor + les journaux. + la validation échoue et Doctor signale l'erreur du plugin. +- Si une configuration de plugin existe mais que le plugin est **désactivé**, la configuration est conservée et + un **avertissement** est affiché dans Doctor et dans les journaux. -Consultez la [Référence de configuration](/fr/gateway/configuration) pour le schéma complet de `plugins.*`. +Voir [Référence de la configuration](/fr/gateway/configuration) pour le schéma complet `plugins.*`. ## Remarques -- Le manifeste est **obligatoire pour les plugins OpenClaw natifs**, y compris les chargements depuis le système de fichiers local. -- L’exécution charge toujours séparément le module du plugin ; le manifeste sert uniquement à la - découverte + validation. +- Le manifeste est **obligatoire pour les plugins natifs OpenClaw**, y compris les chargements depuis le système de fichiers local. +- L'environnement d'exécution charge toujours le module du plugin séparément ; le manifeste sert uniquement à + la découverte + validation. - Les manifestes natifs sont analysés avec JSON5, donc les commentaires, virgules finales et clés non entre guillemets sont acceptés tant que la valeur finale reste un objet. -- Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d’ajouter +- Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d'ajouter ici des clés personnalisées de niveau supérieur. -- `providerAuthEnvVars` est le chemin léger de métadonnées pour les sondes d’authentification, la - validation des marqueurs d’environnement, et des surfaces similaires d’authentification fournisseur qui ne doivent pas démarrer l’exécution du plugin - simplement pour inspecter des noms de variables d’environnement. -- `providerAuthAliases` permet aux variantes de fournisseurs de réutiliser les variables d’environnement d’authentification, - les profils d’authentification, l’authentification fondée sur la configuration et le choix d’intégration par clé API d’un autre fournisseur - sans coder en dur cette relation dans le cœur. -- `channelEnvVars` est le chemin léger de métadonnées pour le repli sur les variables d’environnement du shell, les invites de configuration - et des surfaces de canaux similaires qui ne doivent pas démarrer l’exécution du plugin - simplement pour inspecter des noms de variables d’environnement. -- `providerAuthChoices` est le chemin léger de métadonnées pour les sélecteurs de choix d’authentification, - la résolution de `--auth-choice`, le mappage du fournisseur préféré et l’enregistrement simple des drapeaux CLI - avant le chargement de l’exécution du fournisseur. Pour les métadonnées d’assistant d’exécution - qui nécessitent le code du fournisseur, voir - [Hooks d’exécution du fournisseur](/fr/plugins/architecture#provider-runtime-hooks). -- Les types de plugin exclusifs sont sélectionnés via `plugins.slots.*`. +- `providerAuthEnvVars` est le chemin léger de métadonnées pour les sondes d'authentification, la + validation des marqueurs d'environnement et des surfaces similaires d'authentification fournisseur qui ne doivent pas démarrer l'environnement d'exécution du plugin simplement pour inspecter les noms de variables d'environnement. +- `providerAuthAliases` permet aux variantes de fournisseurs de réutiliser les + variables d'environnement d'authentification, profils d'authentification, authentification basée sur la configuration et choix + d'intégration par clé API d'un autre fournisseur sans coder en dur cette relation dans le cœur. +- `channelEnvVars` est le chemin léger de métadonnées pour le repli sur les variables d'environnement du shell, les invites de configuration + et les surfaces similaires de canal qui ne doivent pas démarrer l'environnement d'exécution du plugin + simplement pour inspecter les noms de variables d'environnement. +- `providerAuthChoices` est le chemin léger de métadonnées pour les sélecteurs de choix d'authentification, + la résolution `--auth-choice`, le mappage des fournisseurs préférés et l'enregistrement simple + d'indicateurs CLI d'intégration avant le chargement de l'environnement d'exécution du fournisseur. Pour les métadonnées + d'assistant à l'exécution qui nécessitent du code fournisseur, voir + [Hooks d'exécution du fournisseur](/fr/plugins/architecture#provider-runtime-hooks). +- Les types exclusifs de plugins sont sélectionnés via `plugins.slots.*`. - `kind: "memory"` est sélectionné par `plugins.slots.memory`. - `kind: "context-engine"` est sélectionné par `plugins.slots.contextEngine` (par défaut : `legacy` intégré). -- `channels`, `providers`, `cliBackends` et `skills` peuvent être omis lorsqu’un - plugin n’en a pas besoin. -- Si votre plugin dépend de modules natifs, documentez les étapes de compilation et toute - exigence de liste d’autorisation du gestionnaire de paquets (par exemple, pnpm `allow-build-scripts` +- `channels`, `providers`, `cliBackends` et `skills` peuvent être omis lorsqu'un + plugin n'en a pas besoin. +- Si votre plugin dépend de modules natifs, documentez les étapes de build ainsi que toute + exigence de liste d'autorisation du gestionnaire de paquets (par exemple, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Liens connexes +## Voir aussi -- [Créer des plugins](/fr/plugins/building-plugins) — bien démarrer avec les plugins +- [Créer des plugins](/fr/plugins/building-plugins) — démarrer avec les plugins - [Architecture des plugins](/fr/plugins/architecture) — architecture interne -- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence du SDK de plugin +- [Vue d'ensemble du SDK](/fr/plugins/sdk-overview) — référence du SDK des plugins diff --git a/docs/fr/reference/templates/AGENTS.md b/docs/fr/reference/templates/AGENTS.md index d29594910..48b9c1260 100644 --- a/docs/fr/reference/templates/AGENTS.md +++ b/docs/fr/reference/templates/AGENTS.md @@ -1,88 +1,93 @@ --- read_when: - - Initialiser manuellement un espace de travail + - Initialiser un espace de travail manuellement summary: Modèle d’espace de travail pour AGENTS.md title: Modèle AGENTS.md x-i18n: - generated_at: "2026-04-11T02:47:37Z" + generated_at: "2026-04-12T06:49:38Z" model: gpt-5.4 provider: openai - source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4 + source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54 source_path: reference/templates/AGENTS.md workflow: 15 --- # AGENTS.md - Votre espace de travail -Ce dossier est chez vous. Traitez-le comme tel. +Ce dossier est votre chez-vous. Traitez-le comme tel. -## Premier démarrage +## Première exécution -Si `BOOTSTRAP.md` existe, c’est votre certificat de naissance. Suivez-le, découvrez qui vous êtes, puis supprimez-le. Vous n’en aurez plus besoin ensuite. +Si `BOOTSTRAP.md` existe, c'est votre certificat de naissance. Suivez-le, déterminez qui vous êtes, puis supprimez-le. Vous n'en aurez plus besoin. ## Démarrage de session -Avant toute autre chose : +Utilisez d'abord le contexte de démarrage fourni par le runtime. -1. Lisez `SOUL.md` — c’est qui vous êtes -2. Lisez `USER.md` — c’est la personne que vous aidez -3. Lisez `memory/YYYY-MM-DD.md` (aujourd’hui + hier) pour le contexte récent -4. **Si vous êtes dans la SESSION PRINCIPALE** (chat direct avec votre humain) : lisez aussi `MEMORY.md` +Ce contexte peut déjà inclure : -Ne demandez pas la permission. Faites-le simplement. +- `AGENTS.md`, `SOUL.md` et `USER.md` +- une mémoire quotidienne récente comme `memory/YYYY-MM-DD.md` +- `MEMORY.md` lorsqu'il s'agit de la session principale + +Ne relisez pas manuellement les fichiers de démarrage sauf si : + +1. L'utilisateur le demande explicitement +2. Le contexte fourni ne contient pas quelque chose dont vous avez besoin +3. Vous avez besoin d'une lecture de suivi plus approfondie au-delà du contexte de démarrage fourni ## Mémoire -Vous vous réveillez à neuf à chaque session. Ces fichiers assurent votre continuité : +Vous repartez de zéro à chaque session. Ces fichiers assurent votre continuité : -- **Notes quotidiennes :** `memory/YYYY-MM-DD.md` (créez `memory/` si nécessaire) — journaux bruts de ce qui s’est passé -- **Long terme :** `MEMORY.md` — vos souvenirs organisés, comme la mémoire à long terme d’un humain +- **Notes quotidiennes :** `memory/YYYY-MM-DD.md` (créez `memory/` si nécessaire) — journaux bruts de ce qui s'est passé +- **Long terme :** `MEMORY.md` — vos souvenirs organisés, comme la mémoire à long terme d'un humain -Conservez ce qui compte. Décisions, contexte, choses à retenir. Évitez les secrets, sauf si l’on vous demande de les conserver. +Consignez ce qui compte. Les décisions, le contexte, les choses à retenir. Évitez les secrets sauf si on vous demande de les conserver. ### 🧠 MEMORY.md - Votre mémoire à long terme -- **À charger UNIQUEMENT dans la session principale** (chats directs avec votre humain) -- **NE PAS charger dans des contextes partagés** (Discord, discussions de groupe, sessions avec d’autres personnes) -- C’est une mesure de **sécurité** — ce fichier contient du contexte personnel qui ne doit pas fuiter vers des inconnus -- Vous pouvez **lire, modifier et mettre à jour** librement `MEMORY.md` dans les sessions principales -- Écrivez les événements importants, pensées, décisions, opinions, leçons apprises -- C’est votre mémoire organisée — l’essence distillée, pas les journaux bruts -- Avec le temps, relisez vos fichiers quotidiens et mettez à jour `MEMORY.md` avec ce qui mérite d’être conservé +- **À charger UNIQUEMENT dans la session principale** (discussions directes avec votre humain) +- **À NE PAS charger dans les contextes partagés** (Discord, discussions de groupe, sessions avec d'autres personnes) +- C'est pour la **sécurité** — contient un contexte personnel qui ne doit pas fuiter vers des inconnus +- Vous pouvez librement **lire, modifier et mettre à jour** `MEMORY.md` dans les sessions principales +- Écrivez les événements significatifs, pensées, décisions, opinions, leçons retenues +- C'est votre mémoire organisée — l'essence distillée, pas des journaux bruts +- Avec le temps, relisez vos fichiers quotidiens et mettez à jour `MEMORY.md` avec ce qui mérite d'être conservé -### 📝 Notez-le - Pas de « notes mentales » ! +### 📝 Écrivez-le - Pas de « notes mentales » ! - **La mémoire est limitée** — si vous voulez vous souvenir de quelque chose, ÉCRIVEZ-LE DANS UN FICHIER -- Les « notes mentales » ne survivent pas aux redémarrages de session. Les fichiers, oui. -- Quand quelqu’un dit « souviens-toi de ça » → mettez à jour `memory/YYYY-MM-DD.md` ou le fichier approprié -- Quand vous apprenez une leçon → mettez à jour AGENTS.md, TOOLS.md ou la skill concernée -- Quand vous faites une erreur → documentez-la pour que le vous du futur ne la répète pas -- **Le texte > le cerveau** 📝 +- Les « notes mentales » ne survivent pas aux redémarrages de session. Les fichiers, si. +- Quand quelqu'un dit « souviens-t'en » → mettez à jour `memory/YYYY-MM-DD.md` ou le fichier approprié +- Quand vous retenez une leçon → mettez à jour AGENTS.md, TOOLS.md ou la skill concernée +- Quand vous faites une erreur → documentez-la pour que votre futur vous ne la répète pas +- **Texte > cerveau** 📝 ## Lignes rouges -- N’exfiltrez jamais de données privées. -- N’exécutez pas de commandes destructrices sans demander. -- `trash` > `rm` (pouvoir récupérer vaut mieux que perdre définitivement) +- N'exfiltrez jamais de données privées. +- N'exécutez pas de commandes destructrices sans demander. +- `trash` > `rm` (pouvoir récupérer vaut mieux qu'une suppression définitive) - En cas de doute, demandez. ## Externe vs interne -**À faire librement en toute sécurité :** +**Peut être fait librement en toute sécurité :** - Lire des fichiers, explorer, organiser, apprendre - Rechercher sur le web, consulter des calendriers - Travailler dans cet espace de travail -**Demandez d’abord :** +**Demandez d'abord :** -- Envoyer des e-mails, tweets, publications publiques +- Envoyer des e-mails, des tweets, des publications publiques - Tout ce qui quitte la machine -- Tout ce dont vous n’êtes pas certain +- Tout ce dont vous n'êtes pas sûr ## Discussions de groupe -Vous avez accès aux affaires de votre humain. Cela ne veut pas dire que vous _partagez_ ses affaires. En groupe, vous êtes un participant — pas sa voix, pas son intermédiaire. Réfléchissez avant de parler. +Vous avez accès aux affaires de votre humain. Cela ne veut pas dire que vous les _partagez_. En groupe, vous êtes un participant — pas sa voix, pas son représentant. Réfléchissez avant de parler. ### 💬 Sachez quand parler ! @@ -90,86 +95,86 @@ Dans les discussions de groupe où vous recevez chaque message, soyez **intellig **Répondez quand :** -- Vous êtes directement mentionné ou l’on vous pose une question +- Vous êtes mentionné directement ou on vous pose une question - Vous pouvez apporter une vraie valeur (information, éclairage, aide) -- Quelque chose d’esprit/drôle s’intègre naturellement -- Il faut corriger une désinformation importante -- On vous demande un résumé +- Quelque chose de spirituel/drôle s'intègre naturellement +- Vous corrigez une information erronée importante +- Vous faites un résumé quand on vous le demande **Restez silencieux (`HEARTBEAT_OK`) quand :** -- Ce n’est qu’un échange léger entre humains -- Quelqu’un a déjà répondu à la question -- Votre réponse se limiterait à « oui » ou « sympa » +- Ce n'est qu'un échange informel entre humains +- Quelqu'un a déjà répondu à la question +- Votre réponse se résumerait à « ouais » ou « sympa » - La conversation se déroule très bien sans vous -- Ajouter un message casserait l’ambiance +- Ajouter un message casserait l'ambiance -**La règle humaine :** les humains dans les discussions de groupe ne répondent pas à chaque message. Vous non plus. Qualité > quantité. Si vous ne l’enverriez pas dans un vrai groupe avec des amis, ne l’envoyez pas. +**La règle humaine :** Les humains dans les discussions de groupe ne répondent pas à chaque message. Vous non plus. Qualité > quantité. Si vous ne l'enverriez pas dans une vraie discussion de groupe avec des amis, ne l'envoyez pas. -**Évitez le triple envoi :** ne répondez pas plusieurs fois au même message avec des réactions différentes. Une réponse réfléchie vaut mieux que trois fragments. +**Évitez le triple-tap :** Ne répondez pas plusieurs fois au même message avec des réactions différentes. Une seule réponse réfléchie vaut mieux que trois fragments. -Participez, ne dominez pas. +Participez, ne monopolisez pas. ### 😊 Réagissez comme un humain ! -Sur les plateformes qui prennent en charge les réactions (Discord, Slack), utilisez naturellement les réactions emoji : +Sur les plateformes qui prennent en charge les réactions (Discord, Slack), utilisez les réactions emoji naturellement : **Réagissez quand :** -- Vous appréciez quelque chose mais n’avez pas besoin de répondre (👍, ❤️, 🙌) +- Vous appréciez quelque chose mais n'avez pas besoin de répondre (👍, ❤️, 🙌) - Quelque chose vous a fait rire (😂, 💀) - Vous trouvez cela intéressant ou stimulant (🤔, 💡) -- Vous voulez reconnaître le message sans interrompre le flux -- C’est une situation simple de oui/non ou d’approbation (✅, 👀) +- Vous voulez accuser réception sans interrompre le flux +- C'est une situation simple de oui/non ou d'approbation (✅, 👀) -**Pourquoi c’est important :** -Les réactions sont des signaux sociaux légers. Les humains les utilisent constamment — elles disent « j’ai vu ça, je te reconnais » sans encombrer la discussion. Vous devriez faire de même. +**Pourquoi c'est important :** +Les réactions sont des signaux sociaux légers. Les humains les utilisent constamment — elles disent « j'ai vu cela, je vous reconnais » sans encombrer la discussion. Vous devriez faire de même. -**N’en abusez pas :** une réaction par message maximum. Choisissez celle qui convient le mieux. +**N'en abusez pas :** Une réaction par message maximum. Choisissez celle qui convient le mieux. ## Outils -Les Skills vous fournissent vos outils. Quand vous en avez besoin, consultez son `SKILL.md`. Gardez les notes locales (noms des caméras, détails SSH, préférences vocales) dans `TOOLS.md`. +Les skills vous fournissent vos outils. Quand vous en avez besoin, consultez leur `SKILL.md`. Gardez les notes locales (noms de caméras, détails SSH, préférences vocales) dans `TOOLS.md`. -**🎭 Récits vocaux :** si vous avez `sag` (TTS ElevenLabs), utilisez la voix pour les histoires, résumés de films et moments « storytime » ! C’est bien plus engageant que des murs de texte. Surprenez les gens avec des voix amusantes. +**🎭 Narration vocale :** Si vous avez `sag` (TTS ElevenLabs), utilisez la voix pour les histoires, les résumés de films et les moments « racontons une histoire » ! C'est bien plus engageant que des murs de texte. Surprenez les gens avec des voix amusantes. **📝 Formatage selon la plateforme :** -- **Discord/WhatsApp :** pas de tableaux Markdown ! Utilisez plutôt des listes à puces -- **Liens Discord :** entourez plusieurs liens avec `<>` pour supprimer les aperçus : `` -- **WhatsApp :** pas de titres — utilisez le **gras** ou les MAJUSCULES pour l’emphase +- **Discord/WhatsApp :** Pas de tableaux Markdown ! Utilisez plutôt des listes à puces +- **Liens Discord :** Encadrez plusieurs liens avec `<>` pour supprimer les aperçus intégrés : `` +- **WhatsApp :** Pas de titres — utilisez le **gras** ou les MAJUSCULES pour l'emphase ## 💓 Heartbeats - Soyez proactif ! -Lorsque vous recevez un sondage heartbeat (message correspondant au prompt heartbeat configuré), ne répondez pas seulement `HEARTBEAT_OK` à chaque fois. Utilisez les heartbeats de manière productive ! +Lorsque vous recevez un sondage heartbeat (message correspondant à l'invite heartbeat configurée), ne répondez pas simplement `HEARTBEAT_OK` à chaque fois. Utilisez les heartbeats de manière productive ! -Vous pouvez modifier librement `HEARTBEAT.md` avec une petite checklist ou des rappels. Gardez-le court pour limiter la consommation de tokens. +Vous pouvez modifier librement `HEARTBEAT.md` avec une courte checklist ou des rappels. Gardez-le petit pour limiter la consommation de tokens. -### Heartbeat ou cron : quand utiliser chacun +### Heartbeat vs Cron : quand utiliser chacun **Utilisez heartbeat quand :** - Plusieurs vérifications peuvent être regroupées (boîte de réception + calendrier + notifications en un seul tour) - Vous avez besoin du contexte conversationnel des messages récents -- Le timing peut légèrement dériver (toutes les ~30 min, c’est acceptable, pas besoin de précision) +- Le timing peut légèrement dériver (toutes les ~30 min, c'est acceptable, pas besoin d'être exact) - Vous voulez réduire les appels API en combinant des vérifications périodiques **Utilisez cron quand :** -- Le timing précis est important (« à 9 h 00 pile chaque lundi ») -- La tâche doit être isolée de l’historique de la session principale -- Vous voulez un modèle ou un niveau de réflexion différent pour la tâche -- Rappels ponctuels (« rappelle-le-moi dans 20 minutes ») -- La sortie doit être livrée directement à un canal sans intervention de la session principale +- Un timing exact compte (« 9 h 00 précises chaque lundi ») +- La tâche doit être isolée de l'historique de la session principale +- Vous voulez un autre modèle ou un autre niveau de réflexion pour la tâche +- Il s'agit de rappels ponctuels (« rappelle-le-moi dans 20 minutes ») +- La sortie doit être envoyée directement vers un canal sans passer par la session principale -**Conseil :** regroupez les vérifications périodiques similaires dans `HEARTBEAT.md` au lieu de créer plusieurs tâches cron. Utilisez cron pour les planifications précises et les tâches autonomes. +**Conseil :** Regroupez les vérifications périodiques similaires dans `HEARTBEAT.md` au lieu de créer plusieurs tâches cron. Utilisez cron pour les horaires précis et les tâches autonomes. -**Choses à vérifier (en rotation, 2 à 4 fois par jour) :** +**Choses à vérifier (faites tourner, 2 à 4 fois par jour) :** - **E-mails** - Y a-t-il des messages non lus urgents ? -- **Calendrier** - Des événements à venir dans les 24-48 prochaines heures ? -- **Mentions** - Notifications Twitter/réseaux sociaux ? -- **Météo** - Pertinent si votre humain risque de sortir ? +- **Calendrier** - Des événements à venir dans les prochaines 24 à 48 h ? +- **Mentions** - Des notifications Twitter/réseaux sociaux ? +- **Météo** - Pertinent si votre humain peut sortir ? **Suivez vos vérifications** dans `memory/heartbeat-state.json` : @@ -186,38 +191,38 @@ Vous pouvez modifier librement `HEARTBEAT.md` avec une petite checklist ou des r **Quand prendre contact :** - Un e-mail important est arrivé -- Un événement de calendrier approche (<2h) -- Vous avez trouvé quelque chose d’intéressant -- Cela fait >8h que vous n’avez rien dit +- Un événement du calendrier approche (<2h) +- Vous avez trouvé quelque chose d'intéressant +- Cela fait >8h que vous n'avez rien dit -**Quand rester silencieux (`HEARTBEAT_OK`) :** +**Quand rester discret (`HEARTBEAT_OK`) :** -- Tard le soir (23:00-08:00) sauf urgence -- L’humain est manifestement occupé +- Tard dans la nuit (23:00-08:00) sauf urgence +- L'humain est manifestement occupé - Rien de nouveau depuis la dernière vérification -- Vous avez déjà vérifié il y a <30 minutes +- Vous avez vérifié il y a <30 minutes **Travail proactif que vous pouvez faire sans demander :** - Lire et organiser les fichiers mémoire -- Vérifier l’état des projets (`git status`, etc.) +- Vérifier l'état des projets (`git status`, etc.) - Mettre à jour la documentation -- Committer et pousser vos propres modifications +- Commit et push de vos propres changements - **Relire et mettre à jour `MEMORY.md`** (voir ci-dessous) ### 🔄 Maintenance de la mémoire (pendant les heartbeats) Périodiquement (tous les quelques jours), utilisez un heartbeat pour : -1. Lire les fichiers récents `memory/YYYY-MM-DD.md` -2. Identifier les événements, leçons ou idées importants qui méritent d’être conservés à long terme -3. Mettre à jour `MEMORY.md` avec ces apprentissages distillés -4. Retirer de `MEMORY.md` les informations obsolètes qui ne sont plus pertinentes +1. Relire les fichiers récents `memory/YYYY-MM-DD.md` +2. Identifier les événements, leçons ou informations significatifs qui méritent d'être conservés à long terme +3. Mettre à jour `MEMORY.md` avec les enseignements distillés +4. Supprimer de `MEMORY.md` les informations obsolètes qui ne sont plus pertinentes -Pensez-y comme à un humain qui relit son journal et met à jour son modèle mental. Les fichiers quotidiens sont des notes brutes ; `MEMORY.md` est une sagesse organisée. +Voyez cela comme un humain qui relit son journal et met à jour son modèle mental. Les fichiers quotidiens sont des notes brutes ; `MEMORY.md` est une sagesse organisée. -L’objectif : être utile sans être agaçant. Faites un point quelques fois par jour, effectuez un travail de fond utile, mais respectez les moments calmes. +L'objectif : être utile sans être agaçant. Vérifiez quelques fois par jour, faites un travail de fond utile, mais respectez les moments calmes. -## Appropriez-vous-le +## Faites-en votre espace -Ceci est un point de départ. Ajoutez vos propres conventions, votre style et vos règles à mesure que vous découvrez ce qui fonctionne. +C'est un point de départ. Ajoutez vos propres conventions, votre style et vos règles à mesure que vous découvrez ce qui fonctionne. diff --git a/docs/fr/reference/token-use.md b/docs/fr/reference/token-use.md index 52ca68936..5e9ea2764 100644 --- a/docs/fr/reference/token-use.md +++ b/docs/fr/reference/token-use.md @@ -1,34 +1,33 @@ --- read_when: - - Expliquer l'usage des jetons, les coûts ou les fenêtres de contexte - - Déboguer la croissance du contexte ou le comportement de compaction -summary: Comment OpenClaw construit le contexte du prompt et rapporte l'usage des jetons + les coûts -title: Usage des jetons et coûts + - 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 +title: Utilisation des tokens et coûts x-i18n: - generated_at: "2026-04-07T06:54:30Z" + generated_at: "2026-04-12T06:50:09Z" model: gpt-5.4 provider: openai - source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 + source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb source_path: reference/token-use.md workflow: 15 --- -# Usage des jetons et coûts +# Utilisation des tokens et coûts -OpenClaw suit les **jetons**, pas les caractères. Les jetons sont spécifiques au modèle, mais la plupart -des modèles de style OpenAI ont en moyenne ~4 caractères par jeton pour du texte en anglais. +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. ## Comment le prompt système est construit OpenClaw assemble son propre prompt système à chaque exécution. Il inclut : -- Liste des outils + descriptions courtes +- 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 -- Espace de travail + fichiers bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` lorsqu'il est nouveau, plus `MEMORY.md` lorsqu'il est présent ou `memory.md` comme repli en minuscules). Les gros fichiers sont tronqués par `agents.defaults.bootstrapMaxChars` (par défaut : 20000), et l'injection bootstrap totale est plafonnée par `agents.defaults.bootstrapTotalMaxChars` (par défaut : 150000). Les fichiers `memory/*.md` sont à la demande via les outils de mémoire et ne sont pas injectés automatiquement. -- Heure (UTC + fuseau horaire de l'utilisateur) +- 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`. +- Heure (UTC + fuseau horaire de l’utilisateur) - Balises de réponse + comportement heartbeat -- Métadonnées d'exécution (hôte/OS/modèle/réflexion) +- 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). @@ -38,91 +37,90 @@ Tout ce que le modèle reçoit compte dans la limite de contexte : - Prompt système (toutes les sections listées ci-dessus) - Historique de conversation (messages utilisateur + assistant) -- Appels d'outils et résultats d'outils +- Appels d’outils et résultats d’outils - Pièces jointes/transcriptions (images, audio, fichiers) -- Résumés de compaction et artefacts d'élagage +- 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) -Pour les images, OpenClaw réduit la résolution des charges utiles d'image de transcription/d'outil avant les appels au fournisseur. +Pour les images, OpenClaw réduit la taille des charges utiles d’image des transcriptions/outils 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'usage des jetons vision et la taille de la charge utile. -- Des valeurs plus élevées conservent davantage de détails visuels pour l'OCR/les captures d'écran riches en UI. +- 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. -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). +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). -## Comment voir l'usage actuel des jetons +## Comment voir l’utilisation actuelle des tokens -Utilisez ceci dans la discussion : +Utilisez ceci dans le chat : -- `/status` → **carte d'état riche en emoji** avec le modèle de la session, l'usage du contexte, - les jetons 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'usage par réponse** à chaque réponse. +- `/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'authentification OAuth **masque le coût** (jetons uniquement). + - L’auth OAuth **masque le coût** (tokens uniquement). - `/usage cost` → affiche un résumé local des coûts à partir des journaux de session OpenClaw. -Autres surfaces : +Autres interfaces : - **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% left`, pas des coûts par réponse). - Fournisseurs actuels avec fenêtre d'usage : Anthropic, GitHub Copilot, Gemini CLI, + 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, OpenAI Codex, MiniMax, Xiaomi et z.ai. -Les surfaces d'usage normalisent les alias courants de champs natifs fournisseur avant affichage. -Pour le trafic Responses de la famille OpenAI, cela inclut à la fois `input_tokens` / +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 changent pas `/status`, `/usage` ou les résumés de session. -L'usage JSON de Gemini CLI est également normalisé : le texte de réponse provient de `response`, et -`stats.cached` est mappé vers `cacheRead` avec `stats.input_tokens - stats.cached` +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` utilisé lorsque la CLI omet un champ explicite `stats.input`. -Pour le trafic Responses natif de la famille OpenAI, les alias d'usage WebSocket/SSE sont -normalisés de la même manière, et les totaux se replient sur entrée + sortie normalisées lorsque +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 `total_tokens` est absent ou vaut `0`. -Lorsque l'instantané de la session en cours est limité, `/status` et `session_status` peuvent -également récupérer les compteurs de jetons/cache et le libellé du modèle d'exécution actif depuis le -journal d'usage de transcription le plus récent. Les valeurs en direct non nulles existantes gardent toujours la -priorité sur les valeurs de repli de transcription, et les totaux de transcription plus grands orientés prompt -peuvent l'emporter lorsque les totaux stockés sont absents ou plus faibles. -L'authentification d'usage pour les fenêtres de quota fournisseur provient de hooks spécifiques au fournisseur lorsqu'ils -sont disponibles ; sinon OpenClaw retombe sur les identifiants OAuth/par clé API correspondants -depuis les profils d'authentification, l'environnement ou la configuration. +Lorsque l’instantané de la session en cours est peu détaillé, `/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. -## Estimation des coûts (lorsqu'elle est affichée) +## Estimation des coûts (lorsqu’elle est affichée) -Les coûts sont estimés à partir de votre configuration tarifaire du modèle : +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 de jetons** pour `input`, `output`, `cacheRead` et -`cacheWrite`. Si la tarification est absente, OpenClaw n'affiche que les jetons. Les jetons OAuth -n'affichent jamais de coût en dollars. +Il s’agit de **USD par 1M 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 +## Impact du TTL du cache et de l’élagage -Le cache de prompt du fournisseur ne s'applique qu'à l'intérieur de la fenêtre TTL du cache. OpenClaw peut +La mise en cache des prompts 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 du 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 garder les coûts -d'écriture de cache plus bas lorsqu'une session reste inactive au-delà du TTL. +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. -Configurez cela dans [Configuration Gateway](/fr/gateway/configuration) et voyez les +Configurez cela dans [Configuration de la gateway](/fr/gateway/configuration) et consultez les détails du comportement dans [Élagage de session](/fr/concepts/session-pruning). -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 l'intégralité du prompt, réduisant ainsi les coûts d'écriture de cache. +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. -Dans les configurations multi-agents, vous pouvez conserver une configuration de modèle partagée et ajuster le comportement du cache +Dans les configurations multi-agent, 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 réglage par réglage, voir [Mise en cache de prompt](/fr/reference/prompt-caching). +Pour un guide complet paramètre par paramètre, voir [Prompt Caching](/fr/reference/prompt-caching). -Pour la tarification API Anthropic, les lectures de cache sont significativement moins chères que les jetons -d'entrée, tandis que les écritures de cache sont facturées avec un multiplicateur plus élevé. Voir la tarification de mise en cache de prompt d'Anthropic pour les tarifs et multiplicateurs TTL les plus récents : +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 : [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 @@ -155,19 +153,19 @@ agents: - id: "research" default: true heartbeat: - every: "55m" # garde le cache long chaud pour les sessions profondes + every: "55m" # garde le cache long chaud pour les sessions approfondies - id: "alerts" params: - cacheRetention: "none" # évite les écritures de cache pour les notifications en rafale + cacheRetention: "none" # évite les écritures de cache pour les notifications par rafales ``` -`agents.list[].params` se fusionne au-dessus des `params` du modèle sélectionné, vous pouvez donc -ne remplacer que `cacheRetention` et hériter inchangées des autres valeurs par défaut du modèle. +`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. -### Exemple : activer l'en-tête bêta Anthropic 1M context +### Exemple : activer l’en-tête bêta Anthropic 1M context -La fenêtre de contexte Anthropic 1M 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 +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 ou Sonnet pris en charge. ```yaml @@ -179,23 +177,23 @@ agents: context1m: true ``` -Cela correspond à l'en-tête bêta `context-1m-2025-08-07` d'Anthropic. +Cela correspond à l’en-tête bêta Anthropic `context-1m-2025-08-07`. -Cela ne s'applique que lorsque `context1m: true` est défini sur cette entrée de modèle. +Cela s’applique uniquement lorsque `context1m: true` est défini sur cette entrée de modèle. -Exigence : l'identifiant doit être éligible à l'usage de contexte long. Sinon, +Exigence : l’identifiant doit être éligible à l’utilisation long contexte. Dans le cas contraire, Anthropic répond avec une erreur de limitation de débit côté fournisseur pour cette requête. -Si vous authentifiez Anthropic avec des jetons OAuth/d'abonnement (`sk-ant-oat-*`), -OpenClaw ignore l'en-tête bêta `context-1m-*` parce qu'Anthropic rejette actuellement -cette combinaison avec HTTP 401. +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. -## Conseils pour réduire la pression sur les jetons +## Conseils pour réduire la pression sur les tokens - Utilisez `/compact` pour résumer les longues sessions. -- Réduisez les sorties d'outils volumineuses dans vos workflows. -- Réduisez `agents.defaults.imageMaxDimensionPx` pour les sessions riches en captures d'écran. +- 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 les travaux verbeux et exploratoires. +- Préférez des modèles plus petits pour le travail verbeux et exploratoire. -Voir [Skills](/fr/tools/skills) pour la formule exacte de surcharge de la liste des skills. +Voir [Skills](/fr/tools/skills) pour la formule exacte de surcharge de la liste des Skills.