openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh fr translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-12 06:54:13 +00:00
parent a507499eb7
commit 52c5259f57
8 changed files with 1922 additions and 1568 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
docs/fr/automation/cron-jobs.md
View File

@ -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 <job-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:<jobId>` 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:<jobId>` 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.
<a id="maintenance"></a>
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:<jobId>` 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:<jobId>` 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:<id>`, `user:<id>`).
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 <token>` (recommandé)
- `x-openclaw-token: <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/\<name\>)
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 <project-id>
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 <jobId> --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 <jobId>
# Exécuter seulement si l’échéance est atteinte
# Exécuter uniquement si due
openclaw cron run <jobId> --due
# Voir l’historique d’exécution
@ -305,17 +316,17 @@ openclaw cron runs --id <jobId> --limit 50
# Supprimer une tâche
openclaw cron remove <jobId>
# 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 <jobId> --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 <jobId> --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 <jobId> --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

649
docs/fr/channels/slack.md
View File

@ -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.
<CardGroup cols={3}>
<Card title="Association" icon="link" href="/fr/channels/pairing">
Les messages privés Slack utilisent par défaut le mode d’association.
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
Les messages privés Slack utilisent par défaut le mode d’appairage.
</Card>
<Card title="Commandes slash" icon="terminal" href="/fr/tools/slash-commands">
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
<Tabs>
<Tab title="Socket Mode (par défaut)">
<Tab title="Socket Mode (default)">
<Steps>
<Step title="Créer une nouvelle app Slack">
Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
<Step title="Créer une nouvelle application Slack">
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é
</Step>
<Step title="Configurer OpenClaw">
@ -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
</Tab>
<Tab title="URL de requête HTTP">
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Créer une nouvelle app Slack">
Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
<Step title="Créer une nouvelle application Slack">
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é
</Step>
@ -125,16 +125,16 @@ openclaw gateway
</Tab>
</Tabs>
## Liste de vérification du manifeste et des portées
## Liste de vérification du manifeste et des scopes
<Tabs>
<Tab title="Socket Mode (par défaut)">
<Tab title="Socket Mode (default)">
```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
</Tab>
<Tab title="URL de requête HTTP">
<Tab title="HTTP Request URLs">
```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
</Tab>
</Tabs>
<AccordionGroup>
<Accordion title="Portées d’attribution facultatives (opérations d’écriture)">
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.
<AccordionGroup>
<Accordion title="Commandes slash natives facultatives">
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) :
<Tabs>
<Tab title="Socket Mode (default)">
```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 <duration|off> or max-age <duration|off>"
},
{
"command": "/think",
"description": "Définir le niveau de réflexion",
"usage_hint": "<off|minimal|low|medium|high|xhigh>"
},
{
"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=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>"
},
{
"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=<n>|size=<n>|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": "<name> [input]"
},
{
"command": "/btw",
"description": "Poser une question secondaire sans modifier le contexte de la session",
"usage_hint": "<question>"
},
{
"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"
}
]
```
</Tab>
<Tab title="HTTP Request URLs">
```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 <duration|off> or max-age <duration|off>",
"url": "https://gateway-host.example.com/slack/events"
},
{
"command": "/think",
"description": "Définir le niveau de réflexion",
"usage_hint": "<off|minimal|low|medium|high|xhigh>",
"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=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>",
"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=<n>|size=<n>|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": "<name> [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": "<question>",
"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"
}
]
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="Portées facultatives du jeton utilisateur (opérations de lecture)">
Si vous configurez `channels.slack.userToken`, les portées de lecture courantes sont :
<Accordion title="Scopes d’auteur facultatifs (opérations d’écriture)">
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:`.
</Accordion>
<Accordion title="Scopes de jeton utilisateur facultatifs (opérations de lecture)">
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
</Accordion>
</AccordionGroup>
## 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`.
<Tip>
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.
</Tip>
## 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
<Tabs>
<Tab title="Politique des messages privés">
`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 <code>`.
L’appairage dans les messages privés utilise `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="Politique des canaux">
`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`
</Tab>
<Tab title="Mentions et utilisateurs de canal">
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.<id>` ; noms uniquement via résolution au démarrage ou `dangerouslyAllowNameMatching`) :
Contrôles par canal (`channels.slack.channels.<id>` ; 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:`)
</Tab>
@ -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:<agentId>:slack:channel:<channelId>`.
- Les réponses dans les fils peuvent créer des suffixes de session de fil (`:thread:<threadTs>`) 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:<agentId>:slack:channel:<channelId>`.
- Les réponses dans les fils peuvent créer des suffixes de session de fil (`:thread:<threadTs>`) 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:<id>]]`
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.<accountId>.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.<accountId>.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 :
<Accordion title="Pièces jointes entrantes">
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`.
</Accordion>
<Accordion title="Texte et fichiers sortants">
- 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
</Accordion>
<Accordion title="Cibles de livraison">
Cibles explicites préférées :
Cibles explicites préférées :
- `user:<id>` pour les messages privés
- `channel:<id>` pour les canaux
@ -541,38 +813,45 @@ Remarques :
</Accordion>
</AccordionGroup>
## 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 `/<command>`), 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:<agentId>:slack:slash:<userId>`
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:<agentId>:slack:slash:<userId>` 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
<AccordionGroup>
<Accordion title="Aucune réponse dans les canaux">
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
</Accordion>
<Accordion title="Messages privés ignorés">
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
</Accordion>
<Accordion title="Le mode socket ne se connecte pas">
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.
</Accordion>
<Accordion title="Le mode HTTP ne reçoit pas d’événements">
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.
</Accordion>
<Accordion title="Les commandes natives/slash ne se déclenchent pas">
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.
</Accordion>
</AccordionGroup>
## 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)

330
docs/fr/concepts/active-memory.md
View File

@ -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 `<active_memory_plugin>...</active_memory_plugin>` au client.
@ -129,7 +129,7 @@ les balises brutes `<active_memory_plugin>...</active_memory_plugin>` 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/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
@ -509,48 +505,48 @@ agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.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)

184
docs/fr/concepts/system-prompt.md
View File

@ -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
</available_skills>
```
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).

1310
docs/fr/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

483
docs/fr/plugins/manifest.md
View File

@ -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.<id>`. |
| `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.<id>`. |
| `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<string, string[]>` | 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<string, string>` | 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<string, string[]>` | 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<string, object>` | 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<string, object>` | 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<string, string[]>` | Métadonnées légères d'environnement d'authentification fournisseur qu'OpenClaw peut inspecter sans charger le code du plugin. |
| `providerAuthAliases` | Non | `Record<string, string>` | 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<string, string[]>` | 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<string, object>` | 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<string, object>` | 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 <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 <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.<id>`. Obligatoire pour chaque entrée déclarée de configuration de canal. |
| `uiHints` | `Record<string, object>` | 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<string, object>` | 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.<id>` 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.<id>` 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.<id>`, `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 <package>`).
## 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

187
docs/fr/reference/templates/AGENTS.md
View File

@ -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 : `<https://example.com>`
- **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 : `<https://example.com>`
- **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 (&lt;2h)
- Vous avez trouvé quelque chose d’intéressant
- Cela fait >8h que vous n’avez rien dit
- Un événement du calendrier approche (&lt;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 &lt;30 minutes
- Vous avez vérifié il y a &lt;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.

158
docs/fr/reference/token-use.md
View File

@ -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.<provider>.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.