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-21 19:22:22 +00:00
parent 9e1aa4eece
commit 6a20e3a8ab
9 changed files with 1077 additions and 964 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
docs/fr/automation/tasks.md
View File

@ -2,14 +2,14 @@
read_when:
- Inspection du travail en arrière-plan en cours ou récemment terminé
- Débogage des échecs de livraison pour les exécutions d’agent détachées
- Comprendre comment les exécutions en arrière-plan se rapportent aux sessions, à Cron et à Heartbeat
- Comprendre comment les exécutions en arrière-plan sont liées aux sessions, à Cron et au Heartbeat
summary: Suivi des tâches en arrière-plan pour les exécutions ACP, les sous-agents, les tâches Cron isolées et les opérations CLI
title: Tâches en arrière-plan
x-i18n:
generated_at: "2026-04-21T06:57:45Z"
generated_at: "2026-04-21T19:20:39Z"
model: gpt-5.4
provider: openai
source_hash: ba5511b1c421bdf505fc7d34f09e453ac44e85213fcb0f082078fa957aa91fe7
source_hash: a4cd666b3eaffde8df0b5e1533eb337e44a0824824af6f8a240f18a89f71b402
source_path: automation/tasks.md
workflow: 15
---
@ -19,47 +19,47 @@ x-i18n:
> **Vous cherchez la planification ?** Consultez [Automation & Tasks](/fr/automation) pour choisir le bon mécanisme. Cette page couvre le **suivi** du travail en arrière-plan, pas sa planification.
Les tâches en arrière-plan suivent le travail qui s’exécute **en dehors de votre session de conversation principale** :
exécutions ACP, lancements de sous-agents, exécutions isolées de tâches Cron et opérations initiées par la CLI.
les exécutions ACP, les lancements de sous-agents, les exécutions isolées de tâches Cron et les opérations lancées via la CLI.
Les tâches ne remplacent **pas** les sessions, les tâches Cron ni les heartbeats — elles constituent le **journal d’activité** qui enregistre quel travail détaché a eu lieu, quand il a eu lieu et s’il a réussi.
Les tâches ne remplacent **pas** les sessions, les tâches Cron ni les Heartbeats — elles constituent le **journal d’activité** qui enregistre quel travail détaché a eu lieu, quand, et s’il a réussi.
<Note>
Chaque exécution d’agent ne crée pas forcément une tâche. Les tours Heartbeat et le chat interactif normal n’en créent pas. En revanche, toutes les exécutions Cron, tous les lancements ACP, tous les lancements de sous-agents et toutes les commandes d’agent CLI en créent.
</Note>
## TL;DR
## En bref
- Les tâches sont des **enregistrements**, pas des planificateurs — Cron et Heartbeat décident _quand_ le travail s’exécute, les tâches suivent _ce qui s’est passé_.
- ACP, les sous-agents, toutes les tâches Cron et les opérations CLI créent des tâches. Les tours Heartbeat n’en créent pas.
- Chaque tâche passe par `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost).
- Les tâches Cron restent actives tant que l’environnement d’exécution Cron possède encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d’exécution propriétaire est encore actif.
- La finalisation est pilotée par push : le travail détaché peut notifier directement ou réveiller la session/Heartbeat demandeur lorsqu’il se termine ; les boucles d’interrogation d’état sont donc généralement une mauvaise approche.
- Les exécutions Cron isolées et les finalisations de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant le nettoyage final.
- La livraison des exécutions Cron isolées supprime les réponses intermédiaires parent obsolètes pendant que le travail des sous-agents descendants est encore en cours de vidage, et privilégie la sortie finale descendante lorsqu’elle arrive avant la livraison.
- Les notifications de fin sont envoyées directement à un canal ou mises en file pour le prochain Heartbeat.
- `openclaw tasks list` affiche toutes les tâches ; `openclaw tasks audit` fait remonter les problèmes.
- Chaque tâche passe par `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` ou `lost`).
- Les tâches Cron restent actives tant que le runtime Cron possède encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d’exécution propriétaire est encore actif.
- L’achèvement est piloté par push : le travail détaché peut notifier directement ou réveiller la session/le Heartbeat demandeur lorsqu’il se termine ; les boucles de sondage d’état sont donc généralement inadaptées.
- Les exécutions Cron isolées et les achèvements de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant le nettoyage final de comptabilisation.
- La livraison des exécutions Cron isolées supprime les réponses intermédiaires parentes obsolètes tant que le travail des sous-agents descendants est encore en cours, et privilégie la sortie finale descendante lorsqu’elle arrive avant la livraison.
- Les notifications d’achèvement sont envoyées directement à un canal ou mises en file d’attente pour le prochain Heartbeat.
- `openclaw tasks list` affiche toutes les tâches ; `openclaw tasks audit` fait ressortir les problèmes.
- Les enregistrements terminaux sont conservés pendant 7 jours, puis automatiquement supprimés.
## Démarrage rapide
```bash
# Lister toutes les tâches (des plus récentes aux plus anciennes)
# Lister toutes les tâches (de la plus récente à la plus ancienne)
openclaw tasks list
# Filtrer par environnement d’exécution ou par statut
# Filtrer par runtime ou par statut
openclaw tasks list --runtime acp
openclaw tasks list --status running
# Afficher les détails d’une tâche spécifique (par ID, ID d’exécution ou clé de session)
# Afficher les détails d'une tâche spécifique (par ID, run ID ou clé de session)
openclaw tasks show <lookup>
# Annuler une tâche en cours d’exécution (tue la session enfant)
# Annuler une tâche en cours d'exécution (tue la session enfant)
openclaw tasks cancel <lookup>
# Modifier la politique de notification d’une tâche
# Modifier la politique de notification d'une tâche
openclaw tasks notify <lookup> state_changes
# Exécuter un audit d’intégrité
# Exécuter un audit d’état
openclaw tasks audit
# Prévisualiser ou appliquer la maintenance
@ -74,19 +74,19 @@ openclaw tasks flow cancel <lookup>
## Ce qui crée une tâche
| Source | Type d’environnement d’exécution | Quand un enregistrement de tâche est créé | Politique de notification par défaut |
| ---------------------- | -------------------------------- | ----------------------------------------------------- | ------------------------------------ |
| Exécutions en arrière-plan ACP | `acp` | Lors du lancement d’une session enfant ACP | `done_only` |
| Orchestration de sous-agents | `subagent` | Lors du lancement d’un sous-agent via `sessions_spawn` | `done_only` |
| Tâches Cron (tous types) | `cron` | À chaque exécution Cron (session principale et isolée) | `silent` |
| Opérations CLI | `cli` | Commandes `openclaw agent` exécutées via la Gateway | `silent` |
| Tâches média d’agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
| Source | Type de runtime | Moment où un enregistrement de tâche est créé | Politique de notification par défaut |
| ---------------------- | --------------- | ---------------------------------------------------------- | ------------------------------------ |
| Exécutions ACP en arrière-plan | `acp` | Lancement d’une session enfant ACP | `done_only` |
| Orchestration de sous-agents | `subagent` | Lancement d’un sous-agent via `sessions_spawn` | `done_only` |
| Tâches Cron (tous types) | `cron` | Chaque exécution Cron (session principale et isolée) | `silent` |
| Opérations CLI | `cli` | Commandes `openclaw agent` exécutées via la Gateway | `silent` |
| Tâches média d’agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
Les tâches Cron de session principale utilisent par défaut la politique de notification `silent` — elles créent des enregistrements pour le suivi, mais ne génèrent pas de notifications. Les tâches Cron isolées utilisent aussi `silent` par défaut, mais sont plus visibles parce qu’elles s’exécutent dans leur propre session.
Les tâches Cron de session principale utilisent `silent` comme politique de notification par défaut — elles créent des enregistrements pour le suivi, mais ne génèrent pas de notifications. Les tâches Cron isolées utilisent aussi `silent` par défaut, mais sont plus visibles parce qu’elles s’exécutent dans leur propre session.
Les exécutions `video_generate` adossées à une session utilisent également la politique de notification `silent`. Elles créent quand même des enregistrements de tâche, mais la finalisation est renvoyée à la session d’agent d’origine sous forme de réveil interne, afin que l’agent puisse lui-même écrire le message de suivi et joindre la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les finalisations asynchrones de `music_generate` et `video_generate` essaient d’abord une livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
Les exécutions `video_generate` adossées à une session utilisent également `silent` comme politique de notification. Elles créent tout de même des enregistrements de tâche, mais l’achèvement est renvoyé à la session d’agent d’origine sous forme de réveil interne afin que l’agent puisse écrire le message de suivi et joindre lui-même la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les achèvements asynchrones de `music_generate` et `video_generate` essaient d’abord une livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
Tant qu’une tâche `video_generate` adossée à une session est encore active, l’outil agit aussi comme garde-fou : les appels répétés à `video_generate` dans cette même session renvoient le statut de la tâche active au lieu de démarrer une seconde génération concurrente. Utilisez `action: "status"` lorsque vous voulez une recherche explicite de progression/statut du côté de l’agent.
Tant qu’une tâche `video_generate` adossée à une session est encore active, l’outil sert aussi de garde-fou : les appels répétés à `video_generate` dans cette même session renvoient l’état de la tâche active au lieu de lancer une deuxième génération concurrente. Utilisez `action: "status"` lorsque vous voulez une consultation explicite de progression/statut côté agent.
**Ce qui ne crée pas de tâches :**
@ -99,59 +99,59 @@ Tant qu’une tâche `video_generate` adossée à une session est encore active,
```mermaid
stateDiagram-v2
[*] --> queued
queued --> running : agent starts
running --> succeeded : completes ok
running --> failed : error
running --> timed_out : timeout exceeded
running --> cancelled : operator cancels
queued --> lost : session gone > 5 min
running --> lost : session gone > 5 min
queued --> running : l’agent démarre
running --> succeeded : se termine correctement
running --> failed : erreur
running --> timed_out : délai dépassé
running --> cancelled : l’opérateur annule
queued --> lost : session disparue > 5 min
running --> lost : session disparue > 5 min
```
| Statut | Ce que cela signifie |
| ----------- | ------------------------------------------------------------------------ |
| `queued` | Créée, en attente du démarrage de l’agent |
| `running` | Le tour d’agent est en cours d’exécution |
| `succeeded` | Terminée avec succès |
| `failed` | Terminée avec une erreur |
| `timed_out` | A dépassé le délai configuré |
| `cancelled` | Arrêtée par l’opérateur via `openclaw tasks cancel` |
| `lost` | L’environnement d’exécution a perdu l’état de référence après un délai de grâce de 5 minutes |
| Statut | Signification |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Créée, en attente du démarrage de l’agent |
| `running` | Le tour de l’agent est en cours d’exécution |
| `succeeded` | Terminée avec succès |
| `failed` | Terminée avec une erreur |
| `timed_out` | A dépassé le délai configuré |
| `cancelled` | Arrêtée par l’opérateur via `openclaw tasks cancel` |
| `lost` | Le runtime a perdu l’état d’autorité sous-jacent après une période de grâce de 5 minutes |
Les transitions se produisent automatiquement — quand l’exécution d’agent associée se termine, le statut de la tâche se met à jour en conséquence.
Les transitions se produisent automatiquement — lorsque l’exécution d’agent associée se termine, le statut de la tâche est mis à jour en conséquence.
`lost` dépend de l’environnement d’exécution :
`lost` dépend du runtime :
- Tâches ACP : les métadonnées de la session enfant ACP ont disparu.
- Tâches de sous-agent : la session enfant de support a disparu du magasin d’agents cible.
- Tâches Cron : l’environnement d’exécution Cron ne suit plus la tâche comme active.
- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent plutôt le contexte d’exécution actif, de sorte que des lignes de session canal/groupe/direct persistantes ne les maintiennent pas actives.
- Tâches ACP : les métadonnées de session enfant ACP sous-jacentes ont disparu.
- Tâches de sous-agent : la session enfant sous-jacente a disparu du magasin d’agents cible.
- Tâches Cron : le runtime Cron ne suit plus la tâche comme active.
- Tâches CLI : les tâches isolées de session enfant utilisent la session enfant ; les tâches CLI adossées au chat utilisent à la place le contexte d’exécution actif, donc des lignes persistantes de session canal/groupe/direct ne les maintiennent pas actives.
## Livraison et notifications
Lorsqu’une tâche atteint un état terminal, OpenClaw vous notifie. Il existe deux chemins de livraison :
**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message de fin est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les finalisations de sous-agents, OpenClaw préserve aussi l’acheminement lié au fil/sujet lorsque c’est possible et peut compléter un `to` / compte manquant à partir de la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d’abandonner la livraison directe.
**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message d’achèvement est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les achèvements de sous-agents, OpenClaw préserve également le routage de fil/topic lié lorsqu’il est disponible et peut renseigner un `to` / compte manquant à partir de la route stockée dans la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d’abandonner la livraison directe.
**Livraison mise en file dans la session** — si la livraison directe échoue ou si aucune origine n’est définie, la mise à jour est mise en file comme événement système dans la session du demandeur et apparaît au prochain heartbeat.
**Livraison mise en file d’attente dans la session** — si la livraison directe échoue ou si aucune origine n’est définie, la mise à jour est mise en file d’attente comme événement système dans la session du demandeur et apparaît au prochain Heartbeat.
<Tip>
La finalisation d’une tâche déclenche un réveil Heartbeat immédiat afin que vous voyiez rapidement le résultat — vous n’avez pas à attendre le prochain tick Heartbeat planifié.
L’achèvement d’une tâche déclenche un réveil Heartbeat immédiat afin que vous voyiez rapidement le résultat — vous n’avez pas à attendre le prochain tick Heartbeat planifié.
</Tip>
Cela signifie que le flux de travail habituel est fondé sur le push : lancez une fois le travail détaché, puis laissez l’environnement d’exécution vous réveiller ou vous notifier à la fin. N’interrogez l’état d’une tâche que lorsque vous avez besoin de débogage, d’intervention ou d’un audit explicite.
Cela signifie que le flux habituel est piloté par push : démarrez le travail détaché une fois, puis laissez le runtime vous réveiller ou vous notifier à son achèvement. Ne sondez l’état d’une tâche que lorsque vous avez besoin de débogage, d’intervention ou d’un audit explicite.
### Politiques de notification
Contrôlez le niveau d’information reçu pour chaque tâche :
Contrôlez la quantité d’informations reçues pour chaque tâche :
| Politique | Ce qui est livré |
| --------------------- | ------------------------------------------------------------------------- |
| `done_only` (par défaut) | Uniquement l’état terminal (succeeded, failed, etc.) — **c’est le comportement par défaut** |
| `state_changes` | Chaque transition d’état et mise à jour de progression |
| `silent` | Rien du tout |
| Politique | Ce qui est livré |
| ---------------------- | ----------------------------------------------------------------------- |
| `done_only` (par défaut) | Seulement l’état terminal (`succeeded`, `failed`, etc.) — **c’est la valeur par défaut** |
| `state_changes` | Chaque transition d’état et mise à jour de progression |
| `silent` | Rien du tout |
Modifiez la politique pendant l’exécution d’une tâche :
Modifiez la politique pendant qu’une tâche est en cours d’exécution :
```bash
openclaw tasks notify <lookup> state_changes
@ -165,7 +165,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d’exécution, Session enfant, Résumé.
Colonnes de sortie : ID de tâche, type, statut, livraison, Run ID, session enfant, résumé.
### `tasks show`
@ -173,7 +173,7 @@ Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d’exécution, S
openclaw tasks show <lookup>
```
Le jeton de recherche accepte un ID de tâche, un ID d’exécution ou une clé de session. Affiche l’enregistrement complet, y compris la chronologie, l’état de livraison, l’erreur et le résumé terminal.
Le jeton de recherche accepte un ID de tâche, un Run ID ou une clé de session. Affiche l’enregistrement complet, y compris le timing, l’état de livraison, l’erreur et le résumé terminal.
### `tasks cancel`
@ -181,7 +181,7 @@ Le jeton de recherche accepte un ID de tâche, un ID d’exécution ou une clé
openclaw tasks cancel <lookup>
```
Pour les tâches ACP et de sous-agent, cela tue la session enfant. Pour les tâches suivies par la CLI, l’annulation est enregistrée dans le registre des tâches (il n’existe pas de handle d’environnement enfant distinct). Le statut passe à `cancelled` et une notification de livraison est envoyée le cas échéant.
Pour les tâches ACP et de sous-agent, cela tue la session enfant. Pour les tâches suivies par la CLI, l’annulation est enregistrée dans le registre des tâches (il n’existe pas de handle de runtime enfant distinct). Le statut passe à `cancelled` et une notification de livraison est envoyée le cas échéant.
### `tasks notify`
@ -195,16 +195,16 @@ openclaw tasks notify <lookup> <done_only|state_changes|silent>
openclaw tasks audit [--json]
```
Fait remonter les problèmes opérationnels. Les constats apparaissent aussi dans `openclaw status` lorsque des problèmes sont détectés.
Fait ressortir les problèmes opérationnels. Les constats apparaissent également dans `openclaw status` lorsque des problèmes sont détectés.
| Constat | Gravité | Déclencheur |
| ------------------------- | ------- | ----------------------------------------------------- |
| `stale_queued` | warn | En file d’attente depuis plus de 10 minutes |
| `stale_running` | error | En cours d’exécution depuis plus de 30 minutes |
| `lost` | error | La possession de la tâche adossée à l’environnement d’exécution a disparu |
| `delivery_failed` | warn | La livraison a échoué et la politique de notification n’est pas `silent` |
| `missing_cleanup` | warn | Tâche terminale sans horodatage de nettoyage |
| `inconsistent_timestamps` | warn | Violation de chronologie (par exemple terminée avant d’avoir commencé) |
| `stale_queued` | avertissement | En file d’attente depuis plus de 10 minutes |
| `stale_running` | erreur | En cours d’exécution depuis plus de 30 minutes |
| `lost` | erreur | La propriété de la tâche adossée au runtime a disparu |
| `delivery_failed` | avertissement | La livraison a échoué et la politique de notification n’est pas `silent` |
| `missing_cleanup` | avertissement | Tâche terminale sans horodatage de nettoyage |
| `inconsistent_timestamps` | avertissement | Violation de chronologie (par exemple, fin avant début) |
### `tasks maintenance`
@ -213,20 +213,20 @@ openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
Utilisez ceci pour prévisualiser ou appliquer la réconciliation, l’horodatage de nettoyage et l’élagage des tâches et de l’état de Task Flow.
Utilisez ceci pour prévisualiser ou appliquer la réconciliation, l’horodatage du nettoyage et la suppression pour les tâches et l’état de Task Flow.
La réconciliation dépend de l’environnement d’exécution :
La réconciliation dépend du runtime :
- Les tâches ACP/sous-agent vérifient leur session enfant de support.
- Les tâches Cron vérifient si l’environnement d’exécution Cron possède toujours la tâche.
- Les tâches CLI adossées au chat vérifient le contexte d’exécution actif propriétaire, pas seulement la ligne de session du chat.
- Les tâches ACP/sous-agent vérifient leur session enfant sous-jacente.
- Les tâches Cron vérifient si le runtime Cron possède encore la tâche.
- Les tâches CLI adossées au chat vérifient le contexte d’exécution actif propriétaire, et pas seulement la ligne de session de chat.
Le nettoyage de finalisation dépend aussi de l’environnement d’exécution :
Le nettoyage à l’achèvement dépend également du runtime :
- La finalisation des sous-agents ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage de l’annonce se poursuive.
- La finalisation des exécutions Cron isolées ferme au mieux les onglets/processus de navigateur suivis pour la session Cron avant que l’exécution ne soit totalement démontée.
- La livraison des exécutions Cron isolées attend si nécessaire la suite du travail des sous-agents descendants et supprime le texte d’accusé de réception parent obsolète au lieu de l’annoncer.
- La livraison de finalisation des sous-agents privilégie le dernier texte visible de l’assistant ; si celui-ci est vide, elle revient au dernier texte `tool`/`toolResult` nettoyé, et les exécutions limitées à un appel d’outil avec timeout peuvent se réduire à un court résumé de progression partielle.
- L’achèvement d’un sous-agent ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage de l’annonce ne continue.
- L’achèvement d’une exécution Cron isolée ferme au mieux les onglets/processus de navigateur suivis pour la session Cron avant que l’exécution ne se termine complètement.
- La livraison d’une exécution Cron isolée attend au besoin le suivi des sous-agents descendants et supprime le texte d’accusé de réception parent obsolète au lieu de l’annoncer.
- La livraison de l’achèvement d’un sous-agent privilégie le dernier texte visible de l’assistant ; si celui-ci est vide, elle revient au dernier texte assaini `tool`/`toolResult`, et les exécutions de simple appel d’outil expirées peuvent être réduites à un bref résumé de progression partielle. Les exécutions terminales en échec annoncent le statut d’échec sans rejouer le texte de réponse capturé.
- Les échecs de nettoyage ne masquent pas le résultat réel de la tâche.
### `tasks flow list|show|cancel`
@ -237,17 +237,18 @@ openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Utilisez ces commandes lorsque c’est le TaskFlow orchestrateur qui vous intéresse plutôt qu’un enregistrement individuel de tâche en arrière-plan.
Utilisez-les lorsque c’est le TaskFlow d’orchestration qui vous intéresse plutôt qu’un enregistrement individuel de tâche en arrière-plan.
## Tableau des tâches du chat (`/tasks`)
Utilisez `/tasks` dans n’importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche les tâches actives et récemment terminées avec l’environnement d’exécution, le statut, la chronologie et les détails de progression ou d’erreur.
Utilisez `/tasks` dans n’importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche les tâches actives et récemment terminées avec le runtime, le statut, le timing, ainsi que les détails de progression ou d’erreur.
Lorsque la session actuelle n’a aucune tâche liée visible, `/tasks` revient à des comptes de tâches locaux à l’agent afin que vous conserviez une vue d’ensemble sans divulguer les détails d’autres sessions.
Lorsque la session actuelle n’a aucune tâche liée visible, `/tasks` revient à des comptages de tâches locaux à l’agent
afin que vous ayez tout de même une vue d’ensemble sans divulguer de détails d’autres sessions.
Pour le journal opérateur complet, utilisez la CLI : `openclaw tasks list`.
## Intégration du statut (pression des tâches)
## Intégration au statut (pression des tâches)
`openclaw status` inclut un résumé des tâches visible en un coup d’œil :
@ -259,66 +260,66 @@ Le résumé indique :
- **active** — nombre de `queued` + `running`
- **failures** — nombre de `failed` + `timed_out` + `lost`
- **byRuntime** — répartition par `acp`, `subagent`, `cron`, `cli`
- **byRuntime** — ventilation par `acp`, `subagent`, `cron`, `cli`
`/status` comme l’outil `session_status` utilisent tous deux un instantané des tâches tenant compte du nettoyage : les tâches actives sont privilégiées, les lignes terminées obsolètes sont masquées, et les échecs récents n’apparaissent que lorsqu’il ne reste plus de travail actif.
Cela permet à la carte de statut de rester centrée sur ce qui compte maintenant.
`/status` comme l’outil `session_status` utilisent tous deux un instantané des tâches sensible au nettoyage : les tâches actives sont
privilégiées, les lignes terminées obsolètes sont masquées, et les échecs récents ne remontent que lorsqu’il ne reste plus de travail actif.
Cela permet à la carte de statut de rester centrée sur ce qui compte à l’instant présent.
## Stockage et maintenance
### Où vivent les tâches
### Emplacement des tâches
Les enregistrements de tâche persistent dans SQLite à l’emplacement suivant :
Les enregistrements de tâches persistent dans SQLite à l’emplacement suivant :
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Le registre est chargé en mémoire au démarrage de la Gateway et synchronise les écritures vers SQLite afin d’assurer la durabilité entre les redémarrages.
Le registre est chargé en mémoire au démarrage de la Gateway et synchronise les écritures vers SQLite pour garantir la durabilité entre les redémarrages.
### Maintenance automatique
Un processus de balayage s’exécute toutes les **60 secondes** et gère trois éléments :
Un balayage s’exécute toutes les **60 secondes** et gère trois éléments :
1. **Réconciliation** — vérifie si les tâches actives ont toujours un support d’exécution faisant autorité. Les tâches ACP/sous-agent utilisent l’état de la session enfant, les tâches Cron utilisent la possession active de la tâche, et les tâches CLI adossées au chat utilisent le contexte d’exécution propriétaire. Si cet état de support a disparu depuis plus de 5 minutes, la tâche est marquée `lost`.
1. **Réconciliation** — vérifie si les tâches actives ont encore un état d’autorité côté runtime. Les tâches ACP/sous-agent utilisent l’état de la session enfant, les tâches Cron utilisent la propriété de tâche active, et les tâches CLI adossées au chat utilisent le contexte d’exécution propriétaire. Si cet état sous-jacent a disparu pendant plus de 5 minutes, la tâche est marquée `lost`.
2. **Horodatage du nettoyage** — définit un horodatage `cleanupAfter` sur les tâches terminales (`endedAt + 7 days`).
3. **Élagage** — supprime les enregistrements ayant dépassé leur date `cleanupAfter`.
3. **Suppression** — supprime les enregistrements au-delà de leur date `cleanupAfter`.
**Rétention** : les enregistrements de tâche terminaux sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration nécessaire.
**Rétention** : les enregistrements de tâches terminales sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration n’est nécessaire.
## Comment les tâches se rapportent aux autres systèmes
### Tâches et Task Flow
[Task Flow](/fr/automation/taskflow) est la couche d’orchestration des flux au-dessus des tâches en arrière-plan. Un même flux peut coordonner plusieurs tâches au cours de sa durée de vie en utilisant des modes de synchronisation gérés ou mis en miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements de tâche individuels et `openclaw tasks flow` pour inspecter le flux orchestrateur.
[Task Flow](/fr/automation/taskflow) est la couche d’orchestration de flux située au-dessus des tâches en arrière-plan. Un même flux peut coordonner plusieurs tâches au cours de sa durée de vie à l’aide de modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements individuels de tâches et `openclaw tasks flow` pour inspecter le flux d’orchestration.
Voir [Task Flow](/fr/automation/taskflow) pour plus de détails.
Consultez [Task Flow](/fr/automation/taskflow) pour plus de détails.
### Tâches et cron
### Tâches et Cron
Une **définition** de tâche Cron se trouve dans `~/.openclaw/cron/jobs.json` ; l’état d’exécution se trouve à côté dans `~/.openclaw/cron/jobs-state.json`. **Chaque** exécution Cron crée un enregistrement de tâche — session principale comme session isolée. Les tâches Cron de session principale utilisent par défaut la politique de notification `silent`, ce qui permet leur suivi sans générer de notifications.
Une **définition** de tâche Cron se trouve dans `~/.openclaw/cron/jobs.json` ; l’état d’exécution du runtime se trouve à côté dans `~/.openclaw/cron/jobs-state.json`. **Chaque** exécution Cron crée un enregistrement de tâche — en session principale comme en mode isolé. Les tâches Cron de session principale utilisent `silent` comme politique de notification par défaut afin d’assurer le suivi sans générer de notifications.
Voir [Cron Jobs](/fr/automation/cron-jobs).
Consultez [Cron Jobs](/fr/automation/cron-jobs).
### Tâches et heartbeat
### Tâches et Heartbeat
Les exécutions Heartbeat sont des tours de session principale — elles ne créent pas d’enregistrements de tâche. Lorsqu’une tâche se termine, elle peut déclencher un réveil Heartbeat afin que vous voyiez rapidement le résultat.
Voir [Heartbeat](/fr/gateway/heartbeat).
Consultez [Heartbeat](/fr/gateway/heartbeat).
### Tâches et sessions
Une tâche peut référencer un `childSessionKey` (où le travail s’exécute) et un `requesterSessionKey` (qui l’a lancée). Les sessions correspondent au contexte de conversation ; les tâches ajoutent par-dessus un suivi de l’activité.
Une tâche peut référencer une `childSessionKey` (où le travail s’exécute) et une `requesterSessionKey` (qui l’a démarrée). Les sessions constituent le contexte de conversation ; les tâches assurent le suivi d’activité par-dessus.
### Tâches et exécutions d’agent
Le `runId` d’une tâche renvoie à l’exécution d’agent qui effectue le travail. Les événements du cycle de vie de l’agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n’avez pas besoin de gérer le cycle de vie manuellement.
Le `runId` d’une tâche pointe vers l’exécution d’agent qui effectue le travail. Les événements de cycle de vie de l’agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n’avez pas besoin de gérer le cycle de vie manuellement.
## Liens connexes
## Voir aussi
- [Automation & Tasks](/fr/automation) — tous les mécanismes d’automatisation en un coup d’œil
- [Task Flow](/fr/automation/taskflow) — orchestration des flux au-dessus des tâches
- [Task Flow](/fr/automation/taskflow) — orchestration de flux au-dessus des tâches
- [Scheduled Tasks](/fr/automation/cron-jobs) — planification du travail en arrière-plan
- [Heartbeat](/fr/gateway/heartbeat) — tours périodiques de session principale
- [CLI: Tasks](/cli/index#tasks) — référence des commandes CLI

97
docs/fr/channels/synology-chat.md
View File

@ -1,61 +1,61 @@
---
read_when:
- Configurer Synology Chat avec OpenClaw
- Déboguer le routage des webhooks Synology Chat
summary: Configuration du webhook Synology Chat et d’OpenClaw
- Configuration de Synology Chat avec OpenClaw
- Débogage du routage des Webhooks Synology Chat
summary: Configuration du Webhook Synology Chat et configuration d’OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-05T12:36:20Z"
generated_at: "2026-04-21T19:20:38Z"
model: gpt-5.4
provider: openai
source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81
source_hash: 7288e2aa873ee1a1f57861d839cfb44ff324e3d40a7f36da07c6ba43cbe1e6e6
source_path: channels/synology-chat.md
workflow: 15
---
# Synology Chat
Statut : plugin intégré de canal de message direct utilisant les webhooks Synology Chat.
Le plugin accepte les messages entrants des webhooks sortants Synology Chat et envoie les réponses
via un webhook entrant Synology Chat.
Statut : plugin groupé de canal de messages directs utilisant les Webhooks Synology Chat.
Le plugin accepte les messages entrants depuis les Webhooks sortants de Synology Chat et envoie les réponses
via un Webhook entrant Synology Chat.
## Plugin intégré
## Plugin groupé
Synology Chat est fourni comme plugin intégré dans les versions actuelles d’OpenClaw, donc les builds
empaquetés normaux n’ont pas besoin d’une installation séparée.
Synology Chat est livré comme plugin groupé dans les versions actuelles d’OpenClaw, donc les
builds empaquetés normaux n’ont pas besoin d’une installation séparée.
Si vous utilisez une version plus ancienne ou une installation personnalisée qui exclut Synology Chat,
Si vous utilisez une ancienne build ou une installation personnalisée qui exclut Synology Chat,
installez-le manuellement :
Installer depuis un checkout local :
Installer depuis une extraction locale :
```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
```
Détails : [Plugins](/tools/plugin)
Détails : [Plugins](/fr/tools/plugin)
## Configuration rapide
1. Assurez-vous que le plugin Synology Chat est disponible.
- Les versions empaquetées actuelles d’OpenClaw l’incluent déjà.
- Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement depuis un checkout source avec la commande ci-dessus.
- Les versions empaquetées actuelles d’OpenClaw l’intègrent déjà.
- Les installations anciennes/personnalisées peuvent l’ajouter manuellement depuis une extraction du code source avec la commande ci-dessus.
- `openclaw onboard` affiche désormais Synology Chat dans la même liste de configuration des canaux que `openclaw channels add`.
- Configuration non interactive : `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. Dans les intégrations Synology Chat :
- Créez un webhook entrant et copiez son URL.
- Créez un webhook sortant avec votre jeton secret.
3. Pointez l’URL du webhook sortant vers votre gateway OpenClaw :
- Créez un Webhook entrant et copiez son URL.
- Créez un Webhook sortant avec votre jeton secret.
3. Pointez l’URL du Webhook sortant vers votre Gateway OpenClaw :
- `https://gateway-host/webhook/synology` par défaut.
- Ou votre `channels.synology-chat.webhookPath` personnalisé.
4. Terminez la configuration dans OpenClaw.
- Guidé : `openclaw onboard`
- Direct : `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. Redémarrez la gateway et envoyez un message direct au bot Synology Chat.
5. Redémarrez la Gateway et envoyez un DM au bot Synology Chat.
Détails d’authentification du webhook :
Détails de l’authentification du Webhook :
- OpenClaw accepte le jeton du webhook sortant depuis `body.token`, puis
- OpenClaw accepte le jeton du Webhook sortant depuis `body.token`, puis
`?token=...`, puis les en-têtes.
- Formes d’en-tête acceptées :
- `x-synology-token`
@ -96,19 +96,19 @@ Pour le compte par défaut, vous pouvez utiliser des variables d’environnement
Les valeurs de configuration remplacent les variables d’environnement.
## Politique DM et contrôle d’accès
## Politique de DM et contrôle d’accès
- `dmPolicy: "allowlist"` est la valeur par défaut recommandée.
- `allowedUserIds` accepte une liste (ou une chaîne séparée par des virgules) d’identifiants utilisateur Synology.
- En mode `allowlist`, une liste `allowedUserIds` vide est traitée comme une mauvaise configuration et la route webhook ne démarrera pas (utilisez `dmPolicy: "open"` pour tout autoriser).
- En mode `allowlist`, une liste `allowedUserIds` vide est traitée comme une erreur de configuration et la route du Webhook ne démarrera pas (utilisez `dmPolicy: "open"` pour tout autoriser).
- `dmPolicy: "open"` autorise n’importe quel expéditeur.
- `dmPolicy: "disabled"` bloque les messages directs.
- La liaison du destinataire des réponses reste basée par défaut sur le `user_id` numérique stable. `channels.synology-chat.dangerouslyAllowNameMatching: true` est un mode de compatibilité de secours qui réactive la recherche basée sur un nom d’utilisateur/surnom mutable pour la remise des réponses.
- `dmPolicy: "disabled"` bloque les DM.
- La liaison du destinataire des réponses reste basée par défaut sur le `user_id` numérique stable. `channels.synology-chat.dangerouslyAllowNameMatching: true` est un mode de compatibilité de dernier recours qui réactive la recherche par nom d’utilisateur/surnom mutable pour la livraison des réponses.
- Les approbations d’appairage fonctionnent avec :
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## Remise sortante
## Livraison sortante
Utilisez des identifiants utilisateur Synology Chat numériques comme cibles.
@ -119,18 +119,19 @@ openclaw message send --channel synology-chat --target 123456 --text "Hello from
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
Les envois de médias sont pris en charge via la remise de fichiers basée sur URL.
Les envois de médias sont pris en charge par la livraison de fichiers basée sur URL.
Les URL de fichiers sortants doivent utiliser `http` ou `https`, et les cibles réseau privées ou autrement bloquées sont rejetées avant qu’OpenClaw ne transmette l’URL au Webhook NAS.
## Multi-comptes
Plusieurs comptes Synology Chat sont pris en charge sous `channels.synology-chat.accounts`.
Chaque compte peut surcharger le jeton, l’URL entrante, le chemin webhook, la politique DM et les limites.
Les sessions de message direct sont isolées par compte et par utilisateur ; ainsi, le même `user_id` numérique
Chaque compte peut remplacer le jeton, l’URL entrante, le chemin du Webhook, la politique de DM et les limites.
Les sessions de messages directs sont isolées par compte et par utilisateur, donc le même `user_id` numérique
sur deux comptes Synology différents ne partage pas l’état de transcription.
Attribuez à chaque compte activé un `webhookPath` distinct. OpenClaw rejette désormais les chemins exacts dupliqués
et refuse de démarrer les comptes nommés qui héritent uniquement d’un chemin webhook partagé dans les configurations multi-comptes.
Si vous avez intentionnellement besoin de l’héritage historique pour un compte nommé, définissez
`dangerouslyAllowInheritedWebhookPath: true` sur ce compte ou dans `channels.synology-chat`,
Donnez à chaque compte activé un `webhookPath` distinct. OpenClaw rejette désormais les chemins exacts dupliqués
et refuse de démarrer les comptes nommés qui n’héritent que d’un chemin de Webhook partagé dans les configurations multi-comptes.
Si vous avez intentionnellement besoin d’un héritage historique pour un compte nommé, définissez
`dangerouslyAllowInheritedWebhookPath: true` sur ce compte ou sur `channels.synology-chat`,
mais les chemins exacts dupliqués sont toujours rejetés en mode fermé. Préférez des chemins explicites par compte.
```json5
@ -160,33 +161,33 @@ mais les chemins exacts dupliqués sont toujours rejetés en mode fermé. Préf
- Gardez `token` secret et faites-le tourner en cas de fuite.
- Gardez `allowInsecureSsl: false` sauf si vous faites explicitement confiance à un certificat NAS local auto-signé.
- Les requêtes webhook entrantes sont vérifiées par jeton et limitées en débit par expéditeur.
- Les requêtes entrantes de Webhook sont vérifiées par jeton et limitées en débit par expéditeur.
- Les vérifications de jeton invalide utilisent une comparaison de secret en temps constant et échouent en mode fermé.
- Préférez `dmPolicy: "allowlist"` en production.
- Laissez `dangerouslyAllowNameMatching` désactivé sauf si vous avez explicitement besoin de la remise des réponses historique basée sur le nom d’utilisateur.
- Laissez `dangerouslyAllowInheritedWebhookPath` désactivé sauf si vous acceptez explicitement le risque de routage à chemin partagé dans une configuration multi-comptes.
- Gardez `dangerouslyAllowNameMatching` désactivé sauf si vous avez explicitement besoin d’une livraison de réponse historique basée sur le nom d’utilisateur.
- Gardez `dangerouslyAllowInheritedWebhookPath` désactivé sauf si vous acceptez explicitement le risque de routage à chemin partagé dans une configuration multi-comptes.
## Dépannage
- `Missing required fields (token, user_id, text)` :
- la charge utile du webhook sortant ne contient pas l’un des champs requis
- si Synology envoie le jeton dans les en-têtes, assurez-vous que la gateway/le proxy conserve ces en-têtes
- la charge utile du Webhook sortant ne contient pas l’un des champs requis
- si Synology envoie le jeton dans les en-têtes, assurez-vous que la Gateway/le proxy préserve ces en-têtes
- `Invalid token` :
- le secret du webhook sortant ne correspond pas à `channels.synology-chat.token`
- la requête atteint le mauvais compte/chemin webhook
- le secret du Webhook sortant ne correspond pas à `channels.synology-chat.token`
- la requête atteint le mauvais compte/chemin de Webhook
- un proxy inverse a supprimé l’en-tête du jeton avant que la requête n’atteigne OpenClaw
- `Rate limit exceeded` :
- trop de tentatives de jeton invalide depuis la même source peuvent temporairement bloquer cette source
- les expéditeurs authentifiés ont aussi une limite de débit de messages distincte par utilisateur
- les expéditeurs authentifiés ont aussi une limite de débit distincte par utilisateur pour les messages
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.` :
- `dmPolicy="allowlist"` est activé mais aucun utilisateur n’est configuré
- `User not authorized` :
- le `user_id` numérique de l’expéditeur n’est pas dans `allowedUserIds`
## Voir aussi
## Liens associés
- [Channels Overview](/channels) — tous les canaux pris en charge
- [Pairing](/channels/pairing) — authentification DM et flux d’appairage
- [Groups](/channels/groups) — comportement des discussions de groupe et filtrage par mention
- [Channel Routing](/channels/channel-routing) — routage de session pour les messages
- [Security](/gateway/security) — modèle d’accès et renforcement
- [Vue d’ensemble des canaux](/fr/channels) — tous les canaux pris en charge
- [Appairage](/fr/channels/pairing) — flux d’authentification DM et d’appairage
- [Groupes](/fr/channels/groups) — comportement du chat de groupe et contrôle des mentions
- [Routage des canaux](/fr/channels/channel-routing) — routage de session pour les messages
- [Sécurité](/fr/gateway/security) — modèle d’accès et durcissement

98
docs/fr/ci.md
View File

@ -1,89 +1,89 @@
---
read_when:
- Vous devez comprendre pourquoi un job CI s’est exécuté ou non
- Vous devez comprendre pourquoi une tâche CI s’est exécutée ou non
- Vous déboguez des vérifications GitHub Actions en échec
summary: Graphe des jobs CI, portes de portée et équivalents des commandes locales
summary: Graphe des tâches CI, portes de périmètre et équivalents des commandes locales
title: Pipeline CI
x-i18n:
generated_at: "2026-04-21T06:58:20Z"
generated_at: "2026-04-21T19:20:37Z"
model: gpt-5.4
provider: openai
source_hash: 88a98d777fd61be1603417b71779aaf42a24d602b2437ad549f0075f22494cec
source_hash: 4d01a178402976cdf7c3c864695e8a12d3f7d1d069a77ea1b02a8aef2a3497f7
source_path: ci.md
workflow: 15
---
# Pipeline CI
La CI s’exécute à chaque push vers `main` et sur chaque pull request. Elle utilise un cadrage intelligent pour ignorer les jobs coûteux lorsque seules des zones non liées ont changé.
La CI s’exécute à chaque push vers `main` et à chaque pull request. Elle utilise un cadrage intelligent pour ignorer les tâches coûteuses lorsque seules des zones non liées ont changé.
## Vue d’ensemble des jobs
## Vue d’ensemble des tâches
| Job | Objectif | Quand il s’exécute |
| Tâche | Objectif | Quand elle s’exécute |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | Détecter les changements docs-only, les portées modifiées, les extensions modifiées, et construire le manifeste CI | Toujours sur les pushs et PR non brouillons |
| `security-scm-fast` | Détection des clés privées et audit des workflows via `zizmor` | Toujours sur les pushs et PR non brouillons |
| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux avis npm | Toujours sur les pushs et PR non brouillons |
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs et PR non brouillons |
| `build-artifacts` | Construire `dist/` et l’interface Control UI une seule fois, puis téléverser des artefacts réutilisables pour les jobs en aval | Changements pertinents pour Node |
| `checks-fast-core` | Lanes Linux rapides de correction, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications shardées des contrats de canaux avec un résultat d’agrégation stable | Changements pertinents pour Node |
| `checks-node-extensions` | Shards complets de tests de plugins intégrés sur toute la suite d’extensions | Changements pertinents pour Node |
| `checks-node-core-test` | Shards de tests Node du cœur, hors lanes de canaux, bundles, contrats et extensions | Changements pertinents pour Node |
| `extension-fast` | Tests ciblés uniquement pour les plugins intégrés modifiés | Lorsque des changements d’extension sont détectés |
| `check` | Équivalent principal local shardé : types prod, lint, garde-fous, types de test et smoke strict | Changements pertinents pour Node |
| `check-additional` | Shards d’architecture, de frontières, de garde-fous de surface d’extension, de frontière de paquet et de surveillance gateway | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de la CLI construite et smoke de mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Lanes Linux Node restantes : tests de canaux et compatibilité Node 22 uniquement sur push | Changements pertinents pour Node |
| `check-docs` | Formatage, lint et vérification des liens cassés dans la documentation | Documentation modifiée |
| `skills-python` | Ruff + pytest pour les Skills basées sur Python | Changements pertinents pour les Skills Python |
| `checks-windows` | Lanes de test spécifiques à Windows | Changements pertinents pour Windows |
| `macos-node` | Lane de tests TypeScript sur macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `macos-swift` | Lint, build et tests Swift pour l’application macOS | Changements pertinents pour macOS |
| `android` | Matrice de build et de tests Android | Changements pertinents pour Android |
| `preflight` | Détecter les changements uniquement dans la doc, les périmètres modifiés, les extensions modifiées, et construire le manifeste CI | Toujours sur les pushes et PR non brouillons |
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushes et PR non brouillons |
| `security-dependency-audit` | Audit du lockfile de production sans dépendance par rapport aux avis npm | Toujours sur les pushes et PR non brouillons |
| `security-fast` | Agrégat requis pour les tâches de sécurité rapides | Toujours sur les pushes et PR non brouillons |
| `build-artifacts` | Construire `dist/` et l’UI Control une fois, puis téléverser des artefacts réutilisables pour les tâches en aval | Changements pertinents pour Node |
| `checks-fast-core` | Voies rapides de vérification Linux, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications shardées des contrats de channel avec un résultat de vérification agrégé stable | Changements pertinents pour Node |
| `checks-node-extensions` | Shards complets de tests des plugins groupés sur l’ensemble de la suite d’extensions | Changements pertinents pour Node |
| `checks-node-core-test` | Shards de tests Node du cœur, hors voies channel, bundled, contract et extension | Changements pertinents pour Node |
| `extension-fast` | Tests ciblés uniquement sur les plugins groupés modifiés | Quand des changements d’extension sont détectés |
| `check` | Équivalent local principal shardé : types prod, lint, garde-fous, types de test, et smoke strict | Changements pertinents pour Node |
| `check-additional` | Architecture, frontières, garde-fous de surface d’extension, frontières de package et shards gateway-watch | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de la CLI construite et smoke de mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Voies Linux Node restantes : tests de channel et compatibilité Node 22 seulement sur push | Changements pertinents pour Node |
| `check-docs` | Formatage, lint et vérification des liens cassés de la documentation | Documentation modifiée |
| `skills-python` | Ruff + pytest pour les Skills adossées à Python | Changements pertinents pour les Skills Python |
| `checks-windows` | Voies de test spécifiques à Windows | Changements pertinents pour Windows |
| `macos-node` | Voie de test TypeScript sur macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements pertinents pour macOS |
| `android` | Matrice de build et de test Android | Changements pertinents pour Android |
## Ordre fail-fast
Les jobs sont ordonnés afin que les vérifications peu coûteuses échouent avant le lancement des plus coûteuses :
Les tâches sont ordonnées de sorte que les vérifications peu coûteuses échouent avant que les plus coûteuses ne s’exécutent :
1. `preflight` décide quelles lanes existent réellement. La logique `docs-scope` et `changed-scope` correspond à des étapes à l’intérieur de ce job, pas à des jobs autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds d’artefacts et de matrices de plateforme.
3. `build-artifacts` se chevauche avec les lanes Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt.
4. Ensuite, les lanes plus lourdes de plateforme et d’exécution se déploient : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
1. `preflight` décide quelles voies existent tout court. La logique `docs-scope` et `changed-scope` correspond à des étapes dans cette tâche, pas à des tâches autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les artefacts plus lourds ni les tâches de matrice par plateforme.
3. `build-artifacts` s’exécute en parallèle avec les voies Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt.
4. Les voies plus lourdes, par plateforme et d’exécution, se déploient ensuite : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
La logique de portée se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`.
Le workflow séparé `install-smoke` réutilise le même script de portée via son propre job `preflight`. Il calcule `run_install_smoke` à partir du signal plus restreint changed-smoke, de sorte que le smoke Docker/install ne s’exécute que pour les changements pertinents pour l’installation, le packaging et les conteneurs.
La logique de périmètre se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`.
Le workflow séparé `install-smoke` réutilise le même script de périmètre via sa propre tâche `preflight`. Il calcule `run_install_smoke` à partir du signal plus étroit changed-smoke, de sorte que le smoke Docker/install ne s’exécute que pour les changements pertinents pour l’installation, le packaging et les conteneurs.
La logique locale des lanes modifiées se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte locale est plus stricte concernant les frontières d’architecture que la portée large des plateformes CI : les changements de production du cœur exécutent le typecheck prod du cœur ainsi que les tests du cœur, les changements limités aux tests du cœur n’exécutent que le typecheck/tests du cœur, les changements de production d’extensions exécutent le typecheck prod des extensions ainsi que les tests des extensions, et les changements limités aux tests d’extensions n’exécutent que le typecheck/tests des extensions. Les changements du Plugin SDK public ou des plugin-contracts étendent la validation aux extensions, car celles-ci dépendent de ces contrats du cœur. Les changements inconnus à la racine/configuration basculent prudemment vers toutes les lanes.
La logique locale des voies modifiées se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte locale est plus stricte sur les frontières d’architecture que le large périmètre CI par plateforme : les changements de production du cœur exécutent le typecheck prod du cœur ainsi que les tests du cœur, les changements limités aux tests du cœur n’exécutent que le typecheck/tests du cœur, les changements de production des extensions exécutent le typecheck prod des extensions ainsi que les tests des extensions, et les changements limités aux tests des extensions n’exécutent que le typecheck/tests des extensions. Les changements du Plugin SDK public ou du plugin-contract étendent la validation aux extensions, car celles-ci dépendent de ces contrats du cœur. Les changements inconnus à la racine/configuration activent par sécurité toutes les voies.
Lors des pushs, la matrice `checks` ajoute la lane `compat-node22`, uniquement sur push. Sur les pull requests, cette lane est ignorée et la matrice reste concentrée sur les lanes normales de test/canal.
Sur les pushes, la matrice `checks` ajoute la voie `compat-node22`, réservée aux pushes. Sur les pull requests, cette voie est ignorée et la matrice reste centrée sur les voies normales de test/channel.
Les familles de tests Node les plus lentes sont divisées en shards par fichiers inclus afin que chaque job reste réduit : les contrats de canaux divisent la couverture registry et core en huit shards pondérés chacun, les tests de commandes de réponse auto-reply sont divisés en quatre shards par motifs d’inclusion, et les autres grands groupes de préfixes de réponse auto-reply sont divisés en deux shards chacun. `check-additional` sépare également le travail de compilation/canari des frontières de paquets du travail de topologie d’exécution gateway/architecture.
Les familles de tests Node les plus lentes sont découpées en shards par fichiers inclus afin que chaque tâche reste petite : les contrats de channel séparent la couverture registry et core en huit shards pondérés chacun, les tests de commande de réponse auto-reply sont répartis en quatre shards par motifs d’inclusion, et les autres grands groupes de préfixes de réponse auto-reply sont répartis en deux shards chacun. `check-additional` sépare également le travail compile/canary des frontières de package du travail de topologie d’exécution gateway/architecture.
GitHub peut marquer des jobs remplacés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou la même référence `main`. Considérez cela comme du bruit CI, sauf si l’exécution la plus récente pour cette même référence échoue aussi. Les vérifications agrégées de shards signalent explicitement ce cas d’annulation afin de le distinguer plus facilement d’un échec de test.
GitHub peut marquer des tâches remplacées comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou la même référence `main`. Considérez cela comme du bruit CI, sauf si l’exécution la plus récente pour la même référence échoue aussi. Les vérifications agrégées des shards signalent explicitement ce cas d’annulation afin qu’il soit plus facile de le distinguer d’un échec de test.
## Exécuteurs
| Exécuteur | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, vérifications Linux, vérifications docs, Skills Python, `android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos-node`, `macos-swift` |
| Exécuteur | Tâches |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, vérifications Linux, vérifications de la documentation, Skills Python, `android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` sur `openclaw/openclaw` ; les forks reviennent à `macos-latest` |
## Équivalents locaux
```bash
pnpm changed:lanes # inspecter le classificateur local des lanes modifiées pour origin/main...HEAD
pnpm check:changed # porte locale intelligente : typecheck/lint/tests modifiés par lane de frontière
pnpm check # porte locale rapide : tsgo de production + lint shardé + garde-fous rapides en parallèle
pnpm changed:lanes # inspecter le classifieur local des voies modifiées pour origin/main...HEAD
pnpm check:changed # porte locale intelligente : typecheck/lint/tests modifiés par voie de frontière
pnpm check # porte locale rapide : tsgo de production + lint shardé + garde-fous rapides en parallèle
pnpm check:test-types
pnpm check:timed # même porte avec durées par étape
pnpm check:timed # même porte avec temporisations par étape
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # tests vitest
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # format + lint + liens cassés de la documentation
pnpm build # construire dist lorsque les lanes CI artifact/build-smoke sont pertinentes
pnpm check:docs # formatage de la documentation + lint + liens cassés
pnpm build # construire dist quand les voies CI artifact/build-smoke sont concernées
```

189
docs/fr/gateway/multiple-gateways.md
View File

@ -1,112 +1,74 @@
---
read_when:
- Exécution de plusieurs Gateway sur la même machine
- Exécuter plusieurs Gateway sur la même machine
- Vous avez besoin d’une configuration, d’un état et de ports isolés pour chaque Gateway
summary: Exécuter plusieurs Gateway OpenClaw sur un même hôte (isolation, ports et profils)
summary: Exécuter plusieurs Gateway OpenClaw sur un seul hôte (isolation, ports et profils)
title: Plusieurs Gateway
x-i18n:
generated_at: "2026-04-21T17:45:42Z"
generated_at: "2026-04-21T19:20:42Z"
model: gpt-5.4
provider: openai
source_hash: 8c3fcb921bc6596040e9249467964bd9dcd40ea7c16e958bb378247b0f994a7b
source_hash: 36796da339d5baea1704a7f42530030ea6ef4fa4bde43452ffec946b917ed4a3
source_path: gateway/multiple-gateways.md
workflow: 15
---
# Plusieurs Gateway (même hôte)
La plupart des configurations devraient utiliser un seul Gateway, car un Gateway unique peut gérer plusieurs connexions de messagerie et agents. Si vous avez besoin d’une isolation plus forte ou de redondance (par exemple, un bot de secours), exécutez des Gateway distincts avec des profils et des ports isolés.
La plupart des configurations devraient utiliser un seul Gateway, car un Gateway unique peut gérer plusieurs connexions de messagerie et agents. Si vous avez besoin d’une isolation plus forte ou de redondance (par exemple, un bot de secours), exécutez des Gateway séparés avec des profils/ports isolés.
## Liste de contrôle d’isolation (obligatoire)
## Configuration la plus recommandée
- `OPENCLAW_CONFIG_PATH` — fichier de configuration par instance
- `OPENCLAW_STATE_DIR` — sessions, identifiants et caches par instance
- `agents.defaults.workspace` — racine d’espace de travail par instance
- `gateway.port` (ou `--port`) — unique par instance
- Les ports dérivés (browser/canvas) ne doivent pas se chevaucher
Pour la plupart des utilisateurs, la configuration la plus simple pour un bot de secours est la suivante :
Si ces éléments sont partagés, vous rencontrerez des conflits de configuration et de ports.
- garder le bot principal sur le profil par défaut
- exécuter le bot de secours avec `--profile rescue`
- utiliser un bot Telegram complètement distinct pour le compte de secours
- garder le bot de secours sur un port de base différent, par exemple `19789`
## Recommandé : utilisez le profil par défaut pour le principal, un profil nommé pour le secours
Cela permet de garder le bot de secours isolé du bot principal afin qu’il puisse déboguer ou appliquer des modifications de configuration si le bot principal est indisponible. Laissez au moins 20 ports d’écart entre les ports de base afin que les ports dérivés browser/canvas/CDP n’entrent jamais en conflit.
Les profils appliquent automatiquement un périmètre à `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` et ajoutent un suffixe aux noms de service. Pour
la plupart des configurations de bot de secours, gardez le bot principal sur le profil par défaut et attribuez uniquement
au bot de secours un profil nommé tel que `rescue`.
## Démarrage rapide du bot de secours
Utilisez ceci comme chemin par défaut sauf si vous avez une raison importante de faire autrement :
```bash
# principal (profil par défaut)
openclaw setup
openclaw gateway --port 18789
# secours
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001
```
Services :
```bash
openclaw gateway install
openclaw --profile rescue gateway install
```
Si vous souhaitez que les deux Gateway utilisent des profils nommés, cela fonctionne aussi, mais ce n’est pas
obligatoire.
## Guide du bot de secours
Configuration recommandée :
- gardez le bot principal sur le profil par défaut
- exécutez le bot de secours avec `--profile rescue`
- utilisez un bot Telegram complètement distinct pour le compte de secours
- gardez le bot de secours sur un port de base différent, par exemple `19001`
Cela permet d’isoler le bot de secours du bot principal afin qu’il puisse déboguer ou appliquer
des modifications de configuration si le bot principal est indisponible. Laissez au moins 20 ports entre les
ports de base afin que les ports dérivés browser/canvas/CDP n’entrent jamais en collision.
### Canal/compte de secours recommandé
Pour la plupart des configurations, utilisez un bot Telegram complètement distinct pour le profil de secours.
Pourquoi Telegram :
- facile à réserver aux opérateurs uniquement
- jeton de bot et identité distincts
- indépendant de l’installation du canal/de l’application du bot principal
- chemin de récupération simple basé sur les messages privés lorsque le bot principal est défaillant
L’élément important est l’indépendance complète : compte de bot distinct, identifiants distincts, profil OpenClaw distinct, espace de travail distinct et port distinct.
### Flux d’installation recommandé
Utilisez ceci comme configuration par défaut, sauf si vous avez une raison solide de faire autrement :
```bash
# Bot principal (profil par défaut, port 18789)
openclaw onboard
openclaw gateway install
# Bot de secours (bot Telegram distinct, profil distinct, port 19001)
# Bot de secours (bot Telegram séparé, profil séparé, port 19789)
openclaw --profile rescue onboard
openclaw --profile rescue gateway install
openclaw --profile rescue gateway install --port 19789
```
Si votre bot principal fonctionne déjà, c’est généralement tout ce dont vous avez besoin.
Pendant `openclaw --profile rescue onboard` :
- utilisez le jeton du bot Telegram distinct
- utilisez le jeton du bot Telegram séparé
- conservez le profil `rescue`
- utilisez un port de base au moins 20 plus élevé que celui du bot principal
- acceptez l’espace de travail de secours par défaut, sauf si vous en gérez déjà un vous-même
- acceptez l’espace de travail de secours par défaut sauf si vous en gérez déjà un vous-même
Si l’onboarding a déjà installé le service de secours pour vous, le
`gateway install` final n’est pas nécessaire.
Si l’onboarding a déjà installé le service de secours pour vous, la commande finale `gateway install` n’est pas nécessaire.
### Ce que l’onboarding modifie
## Pourquoi cela fonctionne
`openclaw --profile rescue onboard` utilise le flux d’onboarding normal, mais
écrit tout dans un profil distinct.
Le bot de secours reste indépendant parce qu’il a son propre :
- profil/configuration
- répertoire d’état
- espace de travail
- port de base (plus les ports dérivés)
- jeton de bot Telegram
Pour la plupart des configurations, utilisez un bot Telegram complètement distinct pour le profil de secours :
- facile à réserver aux opérateurs
- jeton et identité de bot séparés
- indépendant de l’installation du canal/de l’application du bot principal
- chemin de récupération simple basé sur les messages privés lorsque le bot principal est cassé
## Ce que modifie `--profile rescue onboard`
`openclaw --profile rescue onboard` utilise le flux d’onboarding normal, mais écrit tout dans un profil séparé.
En pratique, cela signifie que le bot de secours obtient son propre :
@ -115,22 +77,69 @@ En pratique, cela signifie que le bot de secours obtient son propre :
- espace de travail (par défaut `~/.openclaw/workspace-rescue`)
- nom de service géré
Les invites sont par ailleurs les mêmes que pour un onboarding normal.
Les invites sont par ailleurs les mêmes que pour l’onboarding normal.
## Configuration générale multi-Gateway
La disposition du bot de secours ci-dessus est le choix par défaut le plus simple, mais le même modèle d’isolation fonctionne pour toute paire ou tout groupe de Gateway sur un même hôte.
Pour une configuration plus générale, donnez à chaque Gateway supplémentaire son propre profil nommé ainsi que son propre port de base :
```bash
# principal (profil par défaut)
openclaw setup
openclaw gateway --port 18789
# gateway supplémentaire
openclaw --profile ops setup
openclaw --profile ops gateway --port 19789
```
Si vous voulez que les deux Gateway utilisent des profils nommés, cela fonctionne aussi :
```bash
openclaw --profile main setup
openclaw --profile main gateway --port 18789
openclaw --profile ops setup
openclaw --profile ops gateway --port 19789
```
Les services suivent le même modèle :
```bash
openclaw gateway install
openclaw --profile ops gateway install --port 19789
```
Utilisez le démarrage rapide du bot de secours lorsque vous voulez une voie opérateur de secours. Utilisez le modèle général par profil lorsque vous voulez plusieurs Gateway persistants pour différents canaux, locataires, espaces de travail ou rôles opérationnels.
## Liste de contrôle d’isolation
Gardez les éléments suivants uniques pour chaque instance de Gateway :
- `OPENCLAW_CONFIG_PATH` — fichier de configuration par instance
- `OPENCLAW_STATE_DIR` — sessions, identifiants et caches par instance
- `agents.defaults.workspace` — racine d’espace de travail par instance
- `gateway.port` (ou `--port`) — unique par instance
- ports dérivés browser/canvas/CDP
Si ces éléments sont partagés, vous rencontrerez des conflits de configuration et de ports.
## Mappage des ports (dérivés)
Port de base = `gateway.port` (ou `OPENCLAW_GATEWAY_PORT` / `--port`).
- port du service de contrôle du browser = base + 2 (loopback uniquement)
- l’hôte canvas est servi sur le serveur HTTP Gateway (même port que `gateway.port`)
- les ports CDP du profil Browser sont alloués automatiquement à partir de `browser.controlPort + 9 .. + 108`
- port du service de contrôle du navigateur = port de base + 2 (loopback uniquement)
- l’hôte canvas est servi sur le serveur HTTP du Gateway (même port que `gateway.port`)
- les ports CDP du profil de navigateur sont alloués automatiquement à partir de `browser.controlPort + 9 .. + 108`
Si vous remplacez l’un de ces paramètres dans la configuration ou l’environnement, vous devez les garder uniques par instance.
Si vous remplacez l’un de ces éléments dans la configuration ou l’environnement, vous devez les garder uniques par instance.
## Notes browser/CDP (piège fréquent)
## Notes sur browser/CDP (piège courant)
- **N’épinglez pas** `browser.cdpUrl` aux mêmes valeurs sur plusieurs instances.
- Chaque instance a besoin de son propre port de contrôle browser et de sa propre plage CDP (dérivée de son port Gateway).
- **Ne** fixez **pas** `browser.cdpUrl` aux mêmes valeurs sur plusieurs instances.
- Chaque instance a besoin de son propre port de contrôle du navigateur et de sa propre plage CDP (dérivée de son port Gateway).
- Si vous avez besoin de ports CDP explicites, définissez `browser.profiles.<name>.cdpPort` par instance.
- Chrome distant : utilisez `browser.profiles.<name>.cdpUrl` (par profil, par instance).
@ -143,7 +152,7 @@ openclaw gateway --port 18789
OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
openclaw gateway --port 19001
openclaw gateway --port 19789
```
## Vérifications rapides
@ -159,5 +168,5 @@ openclaw --profile rescue browser status
Interprétation :
- `gateway status --deep` aide à détecter les services launchd/systemd/schtasks obsolètes issus d’anciennes installations.
- Le texte d’avertissement de `gateway probe`, tel que `multiple reachable gateways detected`, n’est attendu que lorsque vous exécutez intentionnellement plus d’un gateway isolé.
- `gateway status --deep` aide à détecter les services `launchd`/`systemd`/`schtasks` obsolètes provenant d’installations plus anciennes.
- Le texte d’avertissement de `gateway probe`, comme `multiple reachable gateways detected`, n’est attendu que lorsque vous exécutez intentionnellement plus d’un Gateway isolé.

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

@ -1,63 +1,75 @@
---
read_when:
- Vous créez un Plugin OpenClaw
- Vous devez fournir un schéma de configuration du plugin ou déboguer des erreurs de validation du plugin
summary: Exigences relatives au manifeste du Plugin + au schéma JSON (validation stricte de la configuration)
title: Manifeste du Plugin
- Vous créez un plugin OpenClaw
- Vous devez livrer un schéma de configuration de plugin ou déboguer des erreurs de validation du plugin
summary: Exigences du manifeste de Plugin + schéma JSON (validation stricte de la configuration)
title: Manifeste de Plugin
x-i18n:
generated_at: "2026-04-19T01:11:11Z"
generated_at: "2026-04-21T19:20:38Z"
model: gpt-5.4
provider: openai
source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181
source_hash: 304c08035724dfb1ce6349972729b621aafc00880d4d259db78c22b86e9056ba
source_path: plugins/manifest.md
workflow: 15
---
# Manifeste du Plugin (`openclaw.plugin.json`)
# Manifeste de Plugin (`openclaw.plugin.json`)
Cette page concerne uniquement le **manifeste natif de Plugin OpenClaw**.
Cette page concerne uniquement le **manifeste de plugin OpenClaw natif**.
Pour les dispositions de bundle compatibles, consultez [Bundles de Plugin](/fr/plugins/bundles).
Pour les mises en page 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 des composants Claude sans manifeste
- Bundle Claude : `.claude-plugin/plugin.json` ou la mise en page par défaut du composant Claude
sans manifeste
- Bundle Cursor : `.cursor-plugin/plugin.json`
OpenClaw détecte aussi automatiquement ces dispositions de bundle, mais elles ne sont pas validées par rapport au schéma `openclaw.plugin.json` décrit ici.
OpenClaw détecte automatiquement ces mises en page de bundle également, mais elles ne sont pas validées
par rapport au schéma `openclaw.plugin.json` décrit ici.
Pour les bundles compatibles, OpenClaw lit actuellement les métadonnées du bundle ainsi que les racines de skills déclarées, les racines de commandes Claude, les valeurs par défaut 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.
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` des bundles Claude,
les valeurs par défaut LSP des bundles Claude, et les packs de hooks pris en charge lorsque la mise en page correspond
aux attentes d'exécution d'OpenClaw.
Chaque Plugin OpenClaw natif **doit** fournir un fichier `openclaw.plugin.json` dans la **racine du plugin**. OpenClaw utilise ce manifeste pour valider la configuration **sans exécuter le code du plugin**. Les manifestes manquants ou invalides sont traités comme des erreurs de plugin et bloquent la validation de la configuration.
Chaque plugin OpenClaw natif **doit** inclure 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.
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 de capacités natif et les indications actuelles de compatibilité externe :
[Modèle de capacités](/fr/plugins/architecture#public-capability-model).
## Rôle de ce fichier
## Ce que fait ce fichier
`openclaw.plugin.json` contient les métadonnées qu’OpenClaw lit avant de charger le code de votre plugin.
`openclaw.plugin.json` contient les métadonnées qu'OpenClaw lit avant de charger le
code de votre plugin.
Utilisez-le pour :
- l’identité du plugin
- l'identité du plugin
- la validation de la configuration
- les métadonnées d’authentification et d’onboarding qui doivent être disponibles sans démarrer 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/onboarding 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é intégré et la couverture des contrats
- les métadonnées légères de l’exécuteur QA que l’hôte partagé `openclaw qa` peut inspecter avant le chargement de l’exécution du plugin
- 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 indications d’interface pour la configuration
- les métadonnées d'authentification et d'onboarding qui doivent être disponibles sans démarrer l'environnement d'exécution du plugin
- les indications d'activation peu coûteuses 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/onboarding 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 famille 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é de capacités utilisés pour le câblage de compatibilité des plugins intégrés et la couverture des contrats
- les métadonnées peu coûteuses du lanceur QA que l'hôte partagé `openclaw qa` peut inspecter
avant le chargement de l'environnement d'exécution du plugin
- 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 un comportement d’exécution
- déclarer des points d’entrée de code
- des métadonnées d’installation npm
- enregistrer le comportement d'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`.
@ -80,7 +92,7 @@ Ces éléments appartiennent au code de votre plugin et à `package.json`.
{
"id": "openrouter",
"name": "OpenRouter",
"description": "Plugin fournisseur OpenRouter",
"description": "OpenRouter provider plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@ -108,19 +120,19 @@ Ces éléments appartiennent au code de votre plugin et à `package.json`.
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "Clé API OpenRouter",
"choiceLabel": "OpenRouter API key",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "Clé API OpenRouter",
"cliDescription": "OpenRouter API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
"label": "Clé API",
"label": "API key",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -137,66 +149,68 @@ 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 intégré comme activé par défaut. Omettez-le, ou définissez toute valeur différente de `true`, pour laisser le plugin désactivé par défaut. |
| `legacyPluginIds` | Non | `string[]` | IDs hérités 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 des références de modèles les mentionnent. |
| `id` | Oui | `string` | ID canonique du plugin. C'est l'ID utilisé dans `plugins.entries.<id>`. |
| `configSchema` | Oui | `object` | Schéma JSON intégré 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 toute valeur différente de `true`, pour laisser le plugin désactivé par défaut. |
| `legacyPluginIds` | Non | `string[]` | IDs historiques normalisés vers cet ID de plugin canonique. |
| `autoEnableWhenConfiguredProviders` | Non | `string[]` | IDs de providers 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 de plugin exclusif 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 appartenant au manifeste, utilisées pour charger automatiquement le plugin avant l’exécution. |
| `providerEndpoints` | Non | `object[]` | Métadonnées d’hôte/baseUrl de point de terminaison appartenant au manifeste pour les routes de fournisseur que le cœur doit classer avant le chargement de l’exécution du fournisseur. |
| `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. |
| `syntheticAuthRefs` | Non | `string[]` | Références de fournisseur ou de backend CLI dont le hook d’authentification synthétique appartenant au plugin doit être sondé pendant la découverte à froid des modèles avant le chargement de l’exécution. |
| `nonSecretAuthMarkers` | Non | `string[]` | Valeurs d’espace réservé de clé API appartenant aux plugins intégrés qui représentent un état d’identifiants local, OAuth ou ambiant non secret. |
| `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 d’environnement d’authentification du 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 d’environnement de canal qu’OpenClaw peut inspecter sans charger le code du plugin. Utilisez ceci pour les surfaces de configuration ou d’authentification de canaux pilotés par 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’onboarding, la résolution du fournisseur préféré et le raccordement simple des options CLI. |
| `activation` | Non | `object` | Indices d’activation légers pour le chargement déclenché par un fournisseur, une commande, un canal, une route ou une capacité. Métadonnées uniquement ; l’exécution du plugin reste propriétaire du comportement réel. |
| `setup` | Non | `object` | Descripteurs légers de configuration/onboarding que les surfaces de découverte et de configuration peuvent inspecter sans charger l’exécution du plugin. |
| `qaRunners` | Non | `object[]` | Descripteurs légers d’exécuteurs QA utilisés par l’hôte partagé `openclaw qa` avant le chargement de l’exécution du plugin. |
| `contracts` | Non | `object` | Instantané statique des 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 musicale, la génération vidéo, `web-fetch`, la recherche Web et la propriété des outils. |
| `channelConfigs` | Non | `Record<string, object>` | Métadonnées de configuration de canal appartenant au manifeste, fusionnées dans les surfaces de découverte et de validation avant le chargement de l’exécution. |
| `providers` | Non | `string[]` | IDs de providers appartenant à ce plugin. |
| `modelSupport` | Non | `object` | Métadonnées abrégées de famille de modèles appartenant au manifeste, utilisées pour charger automatiquement le plugin avant l'environnement d'exécution. |
| `providerEndpoints` | Non | `object[]` | Métadonnées d'hôte/baseUrl d'endpoint appartenant au manifeste pour les routes de provider que le noyau doit classifier avant le chargement de l'environnement d'exécution du provider. |
| `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. |
| `syntheticAuthRefs` | Non | `string[]` | Références de provider ou de backend CLI dont le hook d'authentification synthétique appartenant au plugin doit être sondé pendant la découverte à froid des modèles avant le chargement de l'environnement d'exécution. |
| `nonSecretAuthMarkers` | Non | `string[]` | Valeurs d'espace réservé de clé API appartenant à un plugin intégré qui représentent un état d'identifiants local, OAuth ou ambiant non secret. |
| `commandAliases` | Non | `object[]` | Noms de commandes appartenant à ce plugin qui doivent produire une configuration tenant compte du plugin et des diagnostics CLI avant le chargement de l'environnement d'exécution. |
| `providerAuthEnvVars` | Non | `Record<string, string[]>` | Métadonnées légères de variables d'environnement d'authentification de provider qu'OpenClaw peut inspecter sans charger le code du plugin. |
| `providerAuthAliases` | Non | `Record<string, string>` | IDs de providers qui doivent réutiliser un autre ID de provider pour la recherche d'authentification, par exemple un provider de code qui partage la clé API et les profils d'authentification du provider de base. |
| `channelEnvVars` | Non | `Record<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 ceci pour la configuration de canal pilotée par env ou les surfaces d'authentification 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'onboarding, la résolution du provider préféré et le câblage simple des drapeaux CLI. |
| `activation` | Non | `object` | Indications légères d'activation pour le chargement déclenché par provider, commande, canal, route et 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/onboarding que les surfaces de découverte et de configuration peuvent inspecter sans charger l'environnement d'exécution du plugin. |
| `qaRunners` | Non | `object[]` | Descripteurs légers de lanceurs QA utilisés par l'hôte partagé `openclaw qa` avant le chargement de l'environnement d'exécution du plugin. |
| `contracts` | Non | `object` | Instantané statique des 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 appartenant au 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 du plugin lisible par l’humain. |
| `description` | Non | `string` | Bref résumé affiché dans les surfaces de plugin. |
| `version` | Non | `string` | Version informative du plugin. |
| `uiHints` | Non | `Record<string, object>` | Libellés d’interface, placeholders et indications de sensibilité pour les champs de configuration. |
| `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 utilisateur, espaces réservés et indications de sensibilité pour les champs de configuration. |
## Référence `providerAuthChoices`
Chaque entrée `providerAuthChoices` décrit un choix d’onboarding ou d’authentification.
OpenClaw lit cela avant le chargement de l’exécution du fournisseur.
Chaque entrée `providerAuthChoices` décrit un choix d'onboarding ou d'authentification.
OpenClaw lit ceci avant le chargement de l'environnement d'exécution du provider.
| Champ | Obligatoire | Type | Signification |
| --------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `provider` | Oui | `string` | ID du fournisseur auquel ce choix appartient. |
| `method` | Oui | `string` | ID de la méthode d’authentification vers laquelle dispatcher. |
| `choiceId` | Oui | `string` | ID stable du choix d’authentification utilisé par les flux d’onboarding et CLI. |
| `choiceLabel` | Non | `string` | Libellé destiné à l’utilisateur. S’il est omis, OpenClaw utilise `choiceId` par défaut. |
| `choiceHint` | Non | `string` | Court texte d’aide pour le sélecteur. |
| `assistantPriority` | Non | `number` | Les valeurs 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 encore la sélection manuelle en 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é 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 flag. |
| `cliFlag` | Non | `string` | Nom du flag CLI, tel que `--openrouter-api-key`. |
| `cliOption` | Non | `string` | Forme complète de l’option CLI, telle que `--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’onboarding ce choix doit apparaître. Si omis, la valeur par défaut est `["text-inference"]`. |
| Champ | Obligatoire | Type | Signification |
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `provider` | Oui | `string` | ID du provider auquel ce choix appartient. |
| `method` | Oui | `string` | ID de méthode d'authentification vers lequel répartir. |
| `choiceId` | Oui | `string` | ID stable de choix d'authentification utilisé par les flux d'onboarding et CLI. |
| `choiceLabel` | Non | `string` | Libellé destiné à l'utilisateur. S'il est omis, OpenClaw utilise `choiceId` comme repli. |
| `choiceHint` | Non | `string` | Court texte d'aide pour le sélecteur. |
| `assistantPriority` | Non | `number` | Les valeurs les plus faibles sont triées plus tôt dans les sélecteurs interactifs pilotés par l'assistant. |
| `assistantVisibility` | Non | `"visible"` \| `"manual-only"` | Masque le choix dans les sélecteurs de l'assistant tout en autorisant la sélection manuelle via la CLI. |
| `deprecatedChoiceIds` | Non | `string[]` | IDs historiques 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é 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 drapeau. |
| `cliFlag` | Non | `string` | Nom du drapeau CLI, tel que `--openrouter-api-key`. |
| `cliOption` | Non | `string` | Forme complète de l'option CLI, telle que `--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'onboarding ce choix doit apparaître. Si omis, la valeur par défaut est `["text-inference"]`. |
## Référence `commandAliases`
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 une 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
{
@ -212,36 +226,43 @@ Utilisez `commandAliases` lorsqu’un plugin possède un nom de commande d’ex
| Champ | Obligatoire | Type | Signification |
| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- |
| `name` | Oui | `string` | Nom de commande qui appartient à ce plugin. |
| `kind` | Non | `"runtime-slash"` | Marque l’alias comme une commande slash de chat plutôt qu’une commande CLI racine. |
| `cliCommand` | Non | `string` | Commande CLI racine associée à suggérer pour les opérations CLI, s’il en existe une. |
| `name` | Oui | `string` | Nom de commande appartenant à ce plugin. |
| `kind` | Non | `"runtime-slash"` | Marque l'alias comme une commande slash de chat plutôt qu'une commande CLI racine. |
| `cliCommand` | Non | `string` | Commande CLI racine liée à suggérer pour les opérations CLI, si elle existe. |
## 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.
Utilisez `activation` lorsque le plugin peut déclarer à faible coût quels événements du plan de contrôle
doivent l'activer plus tard.
## Référence `qaRunners`
Utilisez `qaRunners` lorsqu’un plugin fournit un ou plusieurs exécuteurs de transport sous la racine partagée `openclaw qa`. Conservez ces métadonnées légères et statiques ; l’exécution du plugin reste propriétaire de l’enregistrement CLI réel via une surface légère `runtime-api.ts` qui exporte `qaRunnerCliRegistrations`.
Utilisez `qaRunners` lorsqu'un plugin fournit un ou plusieurs lanceurs de transport sous la racine partagée
`openclaw qa`. Gardez ces métadonnées légères et statiques ; l'environnement d'exécution du plugin
reste responsable de l'enregistrement CLI réel via une surface légère
`runtime-api.ts` qui exporte `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "Exécuter la voie QA live Matrix, adossée à Docker, contre un homeserver jetable"
"description": "Exécuter la voie QA Matrix en direct, adossée à Docker, sur un homeserver jetable"
}
]
}
```
| Champ | Obligatoire | Type | Signification |
| ------------- | ----------- | -------- | -------------------------------------------------------------------- |
| `commandName` | Oui | `string` | Sous-commande montée sous `openclaw qa`, par exemple `matrix`. |
| `description` | Non | `string` | Texte d’aide de repli utilisé lorsque l’hôte partagé a besoin d’une commande factice. |
| Champ | Obligatoire | Type | Signification |
| ------------- | ----------- | -------- | ------------------------------------------------------------------- |
| `commandName` | Oui | `string` | Sous-commande montée sous `openclaw qa`, par exemple `matrix`. |
| `description` | Non | `string` | Texte d'aide de repli utilisé lorsque l'hôte partagé a besoin d'une commande factice. |
Ce bloc est uniquement constitué de métadonnées. Il n’enregistre pas de comportement d’exécution et ne remplace pas `register(...)`, `setupEntry` ni d’autres points d’entrée d’exécution/plugin.
Les consommateurs actuels l’utilisent comme indice de réduction avant un chargement plus large du plugin ; des métadonnées d’activation manquantes n’ont donc généralement qu’un coût de performance et ne devraient pas modifier le comportement correct tant que les mécanismes hérités de repli de propriété du manifeste existent encore.
Ce bloc ne contient que des métadonnées. Il n'enregistre pas de comportement d'exécution et
ne remplace pas `register(...)`, `setupEntry` ni les autres points d'entrée d'exécution/de plugin.
Les consommateurs actuels l'utilisent comme indication de réduction avant un chargement plus large du plugin, donc
l'absence de métadonnées d'activation ne coûte généralement que des performances ; elle ne devrait pas
modifier la correction tant que les mécanismes de repli historiques de propriété du manifeste existent encore.
```json
{
@ -255,26 +276,28 @@ Les consommateurs actuels l’utilisent comme indice de réduction avant un char
}
```
| 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é utilisés par la planification d’activation du plan de contrôle. |
| Champ | Obligatoire | Type | Signification |
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `onProviders` | Non | `string[]` | IDs de providers 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">` | Indications larges de capacité utilisées par la planification de l'activation du plan de contrôle. |
Consommateurs actifs actuels :
- la planification CLI déclenchée par une commande retombe sur les valeurs héritées
- la planification CLI déclenchée par commande revient en repli à
`commandAliases[].cliCommand` ou `commandAliases[].name`
- la planification de configuration/de canal déclenchée par un canal retombe sur la propriété héritée `channels[]`
lorsque les métadonnées explicites d’activation de canal sont absentes
- la planification de configuration/d’exécution déclenchée par un fournisseur retombe sur la propriété héritée
`providers[]` et `cliBackends[]` de niveau supérieur lorsque les métadonnées explicites d’activation de fournisseur sont absentes
- la planification de configuration/de canal déclenchée par canal revient en repli à la propriété historique
`channels[]` lorsque les métadonnées d'activation explicites du canal sont absentes
- la planification de configuration/d'exécution déclenchée par provider revient en repli à la propriété historique
`providers[]` et à la propriété de premier niveau `cliBackends[]` lorsque les métadonnées d'activation
explicites du provider sont absentes
## Référence `setup`
Utilisez `setup` lorsque les surfaces de configuration et d’onboarding 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'onboarding ont besoin de métadonnées légères appartenant au plugin
avant le chargement de l'environnement d'exécution.
```json
{
@ -293,28 +316,37 @@ Utilisez `setup` lorsque les surfaces de configuration et d’onboarding ont bes
}
```
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 de configuration/plan de contrôle qui doivent rester purement fondés sur des métadonnées.
La propriété 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.
Lorsqu’ils sont présents, `setup.providers` et `setup.cliBackends` constituent la surface de recherche privilégiée, d’abord fondé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.
Lorsqu'ils sont présents, `setup.providers` et `setup.cliBackends` sont la surface de recherche
préférée, orientée descripteur d'abord, pour la découverte de 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.
Comme la recherche de configuration peut exécuter du code `setup-api` appartenant au plugin, les valeurs normalisées de `setup.providers[].id` et `setup.cliBackends[]` doivent rester uniques parmi les plugins découverts. En cas de propriété ambiguë, le système échoue de manière fermée au lieu de choisir un gagnant selon l’ordre de découverte.
Comme la recherche de configuration peut exécuter le code `setup-api` appartenant au plugin,
les valeurs normalisées de `setup.providers[].id` et `setup.cliBackends[]` doivent rester uniques parmi
les plugins découverts. Une propriété ambiguë échoue en mode fermé au lieu de choisir un
gagnant selon l'ordre de découverte.
### Référence `setup.providers`
| Champ | Obligatoire | Type | Signification |
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | Oui | `string` | ID du fournisseur exposé pendant la configuration ou l’onboarding. Gardez les IDs normalisés globalement uniques. |
| `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. |
| Champ | Obligatoire | Type | Signification |
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------ |
| `id` | Oui | `string` | ID de provider exposé pendant la configuration ou l'onboarding. Gardez les IDs normalisés globalement uniques. |
| `authMethods` | Non | `string[]` | IDs de méthodes de configuration/authentification prises en charge par ce provider 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. |
### Champs `setup`
| Champ | Obligatoire | Type | Signification |
| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `providers` | Non | `object[]` | Descripteurs de configuration de fournisseur exposés pendant la configuration et l’onboarding. |
| `cliBackends` | Non | `string[]` | IDs de backend au moment de la configuration utilisés pour la recherche de configuration fondée d’abord sur les descripteurs. Gardez les 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 a encore besoin de l’exécution de `setup-api` après la recherche par descripteur. |
| Champ | Obligatoire | Type | Signification |
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `providers` | Non | `object[]` | Descripteurs de configuration de provider exposés pendant la configuration et l'onboarding. |
| `cliBackends` | Non | `string[]` | IDs de backend au moment de la configuration utilisés pour la recherche de configuration orientée descripteur d'abord. Gardez les 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 a encore besoin de l'exécution de `setup-api` après la recherche par descripteur. |
## Référence `uiHints`
@ -335,18 +367,19 @@ Comme la recherche de configuration peut exécuter du code `setup-api` appartena
Chaque indication de champ peut inclure :
| Champ | Type | Signification |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Libellé du champ destiné à l’utilisateur. |
| `help` | `string` | Court texte d’aide. |
| `tags` | `string[]` | Tags d’interface facultatifs. |
| `advanced` | `boolean` | Marque le champ comme avancé. |
| `sensitive` | `boolean` | Marque le champ comme secret ou sensible. |
| `placeholder` | `string` | Texte de placeholder pour les champs de formulaire. |
| Champ | Type | Signification |
| ------------- | ---------- | ------------------------------------------ |
| `label` | `string` | Libellé du champ destiné à l'utilisateur. |
| `help` | `string` | Court texte d'aide. |
| `tags` | `string[]` | Balises d'interface utilisateur facultatives. |
| `advanced` | `boolean` | Marque le champ comme avancé. |
| `sensitive` | `boolean` | Marque le champ comme secret ou sensible. |
| `placeholder` | `string` | Texte d'espace réservé pour les champs de formulaire. |
## Référence `contracts`
Utilisez `contracts` uniquement pour des 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é des capacités qu'OpenClaw peut
lire sans importer l'environnement d'exécution du plugin.
```json
{
@ -368,19 +401,20 @@ Chaque liste est facultative :
| Champ | Type | Signification |
| -------------------------------- | ---------- | -------------------------------------------------------------- |
| `speechProviders` | `string[]` | IDs de fournisseurs de parole appartenant à ce plugin. |
| `realtimeTranscriptionProviders` | `string[]` | IDs de fournisseurs de transcription en temps réel appartenant à ce plugin. |
| `realtimeVoiceProviders` | `string[]` | IDs de fournisseurs de voix 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 vidéo appartenant à ce plugin. |
| `webFetchProviders` | `string[]` | IDs de fournisseurs `web-fetch` 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 contrats intégrés. |
| `speechProviders` | `string[]` | IDs de providers de parole appartenant à ce plugin. |
| `realtimeTranscriptionProviders` | `string[]` | IDs de providers de transcription en temps réel appartenant à ce plugin. |
| `realtimeVoiceProviders` | `string[]` | IDs de providers de voix en temps réel appartenant à ce plugin. |
| `mediaUnderstandingProviders` | `string[]` | IDs de providers de compréhension des médias appartenant à ce plugin. |
| `imageGenerationProviders` | `string[]` | IDs de providers de génération d'images appartenant à ce plugin. |
| `videoGenerationProviders` | `string[]` | IDs de providers de génération de vidéos appartenant à ce plugin. |
| `webFetchProviders` | `string[]` | IDs de providers de récupération Web appartenant à ce plugin. |
| `webSearchProviders` | `string[]` | IDs de providers 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 `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
{
@ -412,14 +446,15 @@ Chaque entrée de canal peut inclure :
| Champ | Type | Signification |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
| `schema` | `object` | Schéma JSON pour `channels.<id>`. Obligatoire pour chaque entrée de configuration de canal déclarée. |
| `uiHints` | `Record<string, object>` | Libellés/placeholders/indications de sensibilité d’interface facultatifs pour cette section de configuration de canal. |
| `label` | `string` | Libellé du canal fusionné dans les surfaces de sélection et d’inspection lorsque les métadonnées d’exécution ne sont pas prêtes. |
| `description` | `string` | Courte 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 utilisateur/espaces réservés/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 historiques ou de priorité plus faible que ce canal doit devancer dans les surfaces de sélection. |
## 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 provider à partir
d'IDs de modèle abrégés comme `gpt-5.4` ou `claude-sonnet-4.6` avant le chargement de l'environnement d'exécution du plugin.
```json
{
@ -430,60 +465,81 @@ Utilisez `modelSupport` lorsqu’OpenClaw doit déduire votre plugin fournisseur
}
```
OpenClaw applique cet ordre de priorité :
OpenClaw applique cette priorité :
- les références explicites `provider/model` utilisent les métadonnées de manifeste `providers` du propriétaire
- `modelPatterns` l’emporte sur `modelPrefixes`
- si un plugin non intégré et un plugin intégré correspondent tous deux, le plugin non intégré l’emporte
- toute ambiguïté restante est ignorée jusqu’à ce que l’utilisateur ou la configuration spécifie un fournisseur
- `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
- toute ambiguïté restante est ignorée jusqu'à ce que l'utilisateur ou la configuration spécifie un provider
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. |
| `modelPrefixes` | `string[]` | Préfixes comparés avec `startsWith` aux IDs de modèle abrégés. |
| `modelPatterns` | `string[]` | Sources regex comparées aux IDs de modèle abrégés après suppression du suffixe de profil. |
Les clés de capacité héritées de 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 une propriété de capacité.
Les clés de capacité historiques de premier niveau sont obsolètes. Utilisez `openclaw doctor --fix` pour
déplacer `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
`webFetchProviders` et `webSearchProviders` sous `contracts` ; le chargement normal
du manifeste ne traite plus ces champs de premier niveau comme la propriété
de capacités.
## Manifeste versus package.json
Les deux fichiers ont des rôles différents :
| 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 |
| Fichier | Utilisation |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Découverte, validation de la configuration, métadonnées de choix d'authentification et indications d'interface utilisateur 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ù une métadonnée doit se trouver, appliquez 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 d’entrée ou le comportement d’installation npm, placez-la dans `package.json`
- si elle concerne le packaging, les fichiers de point d'entrée ou le comportement d'installation npm, placez-la dans `package.json`
### Champs `package.json` qui affectent la découverte
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 se trouvent intentionnellement dans `package.json` sous le bloc
`openclaw` plutôt que dans `openclaw.plugin.json`.
Exemples importants :
| Champ | Signification |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Déclare les points d’entrée des plugins natifs. |
| `openclaw.setupEntry` | Point d’entrée léger réservé à la configuration, utilisé pendant l’onboarding et le démarrage différé du canal. |
| `openclaw.extensions` | Déclare les points d'entrée de plugin natifs. |
| `openclaw.setupEntry` | Point d'entrée léger réservé à la configuration utilisé pendant l'onboarding, le démarrage différé des canaux et la découverte en lecture seule de l'état du canal/SecretRef. |
| `openclaw.channel` | Métadonnées légères du catalogue de canaux comme les libellés, chemins de documentation, alias et texte de sélection. |
| `openclaw.channel.configuredState` | Métadonnées légères du vérificateur d’état configuré pouvant répondre à « une configuration uniquement via 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 du vérificateur d’authentification persistée pouvant répondre à « y a-t-il déjà une session ouverte ? » sans charger l’exécution complète du canal. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indications d’installation/mise à jour pour les plugins intégrés et les plugins 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 étroit de réinstallation de 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.channel.configuredState` | Métadonnées légères de vérification de l'état configuré pouvant répondre à « une configuration uniquement par env existe-t-elle déjà ? » sans charger l'environnement d'exécution complet du canal. |
| `openclaw.channel.persistedAuthState` | Métadonnées légères de vérification de l'état d'authentification persistant pouvant répondre à « quelque chose est-il déjà connecté ? » 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, avec une borne semver comme `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Autorise un chemin étroit de récupération de réinstallation de 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 pendant le démarrage. |
`openclaw.install.minHostVersion` est appliqué pendant l’installation et le chargement du registre de manifestes. Les valeurs invalides sont rejetées ; les valeurs valides mais plus récentes ignorent le plugin sur les hôtes plus anciens.
`openclaw.install.minHostVersion` est appliqué lors de l'installation et du chargement du registre
de manifestes. Les valeurs invalides sont rejetées ; les valeurs valides mais plus récentes ignorent le
plugin sur les hôtes plus anciens.
`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il ne rend pas installables des configurations arbitrairement cassées. Aujourd’hui, il permet seulement aux flux d’installation de récupérer de certaines défaillances obsolètes de mise à niveau de plugin intégré, 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 continuent de bloquer l’installation et redirigent les opérateurs vers `openclaw doctor --fix`.
Les plugins de canal doivent fournir `openclaw.setupEntry` lorsque le statut, la liste des canaux
ou les analyses SecretRef doivent identifier les comptes configurés sans charger l'environnement d'exécution complet.
Le point d'entrée de configuration doit exposer les métadonnées du canal ainsi que des adaptateurs sûrs pour la configuration,
le statut et les secrets ; gardez les clients réseau, les écouteurs Gateway et les environnements d'exécution de transport
dans le point d'entrée principal de l'extension.
`openclaw.channel.persistedAuthState` est une métadonnée de package pour un minuscule module de vérification :
`openclaw.install.allowInvalidConfigRecovery` est volontairement limité. Il
ne rend pas installables des configurations arbitrairement cassées. Aujourd'hui, il permet uniquement aux flux d'installation
de récupérer de certains échecs anciens 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 sans rapport bloquent toujours l'installation et orientent les opérateurs
vers `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` est une métadonnée de package pour un minuscule module
de vérification :
```json
{
@ -499,9 +555,13 @@ Exemples importants :
}
```
Utilisez-le lorsque les flux de configuration, de Doctor ou d’état configuré ont besoin d’une sonde d’authentification oui/non légère avant le chargement du plugin de canal complet. L’export cible doit être une petite fonction qui lit uniquement l’état persistant ; ne le faites pas passer par le barrel d’exécution du canal complet.
Utilisez-le lorsque les flux de configuration, 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 persistant ; ne la faites pas passer par le barrel d'environnement d'exécution complet du
canal.
`openclaw.channel.configuredState` suit la même forme pour des vérifications légères d’état configuré uniquement via l’environnement :
`openclaw.channel.configuredState` suit la même structure pour des vérifications légères
d'état configuré uniquement par env :
```json
{
@ -517,47 +577,76 @@ Utilisez-le lorsque les flux de configuration, de Doctor ou d’état configuré
}
```
Utilisez-le lorsqu’un canal peut répondre à l’état configuré à partir de l’environnement ou d’autres entrées non liées à l’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 plutôt cette logique dans le hook `config.hasConfiguredState` du plugin.
Utilisez-le lorsqu'un canal peut répondre à l'état configuré à partir de env ou d'autres entrées minuscules
hors environnement d'exécution. Si la vérification a besoin de la résolution complète de la configuration ou du véritable
environnement d'exécution du canal, gardez cette logique dans le hook `config.hasConfiguredState`
du plugin à la place.
## Exigences du schéma JSON
- **Chaque plugin doit fournir un schéma JSON**, même s’il n’accepte aucune configuration.
- **Chaque plugin doit inclure 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 `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écouvrables**. Les IDs inconnus sont des **erreurs**.
- Si un plugin est installé mais possède un manifeste ou un schéma cassé ou manquant, la validation échoue et Doctor signale l’erreur du plugin.
- Si une configuration de plugin existe mais que le plugin est **désactivé**, la configuration est conservée et un **avertissement** apparaît dans Doctor + les logs.
- 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 cassé ou manquant,
la validation échoue et Doctor signale l'erreur du plugin.
- Si une configuration de plugin existe mais que le plugin est **désactivé**, la configuration est conservée et
un **avertissement** est remonté dans Doctor + les journaux.
Consultez la [Référence de configuration](/fr/gateway/configuration) pour le schéma complet `plugins.*`.
Voir [Référence de 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 le module du plugin séparément ; le manifeste sert uniquement à la découverte + à la validation.
- Les manifestes natifs sont analysés avec JSON5, donc les commentaires, les virgules finales et les clés non entre guillemets sont acceptés tant que la valeur finale reste un objet.
- Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d’ajouter ici des clés personnalisées de niveau supérieur.
- `providerAuthEnvVars` est le chemin de métadonnées léger pour les sondes d’authentification, la validation des marqueurs d’environnement et les 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 à des variantes de fournisseur de réutiliser les variables d’environnement d’authentification, les profils d’authentification, l’authentification adossée à la configuration et le choix d’onboarding de clé API d’un autre fournisseur sans coder cette relation en dur dans le cœur.
- `providerEndpoints` permet aux plugins fournisseurs d’être propriétaires de métadonnées simples de correspondance d’hôte/baseUrl de point de terminaison. Utilisez-le uniquement pour les classes de points de terminaison déjà prises en charge par le cœur ; le plugin reste propriétaire du comportement d’exécution.
- `syntheticAuthRefs` est le chemin de métadonnées léger pour les hooks d’authentification synthétique appartenant au fournisseur qui doivent être visibles pour la découverte à froid des modèles avant que le registre d’exécution n’existe. N’indiquez que les références dont le fournisseur d’exécution ou le backend CLI implémente réellement `resolveSyntheticAuth`.
- `nonSecretAuthMarkers` est le chemin de métadonnées léger pour les clés API d’espace réservé appartenant aux plugins intégrés, comme les marqueurs d’identifiants locaux, OAuth ou ambiants. Le cœur les traite comme non secrètes pour l’affichage de l’authentification et les audits de secrets sans coder en dur le fournisseur propriétaire.
- `channelEnvVars` est le chemin de métadonnées léger pour le repli via variables d’environnement du shell, les invites de configuration et les surfaces de canal 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 de métadonnées léger 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 de flags CLI d’onboarding avant le chargement de l’exécution du fournisseur. Pour les métadonnées d’assistant d’exécution qui nécessitent du code fournisseur, consultez
[Hooks d’exécution du fournisseur](/fr/plugins/architecture#provider-runtime-hooks).
- Les types de plugin exclusifs sont sélectionnés via `plugins.slots.*`.
- Le manifeste est **obligatoire pour les plugins OpenClaw natifs**, y compris les chargements depuis le système de fichiers local.
- L'environnement d'exécution charge toujours séparément le module du plugin ; le manifeste sert uniquement à la
découverte + validation.
- Les manifestes natifs sont analysés avec JSON5, donc les commentaires, virgules finales et
clés non entre guillemets sont acceptés tant que la valeur finale reste un objet.
- Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d'ajouter
ici des clés de premier niveau personnalisées.
- `providerAuthEnvVars` est le chemin de métadonnées léger pour les sondes d'authentification, la
validation des marqueurs env et les surfaces similaires d'authentification de provider qui ne doivent pas démarrer l'environnement d'exécution du plugin
uniquement pour inspecter les noms env.
- `providerAuthAliases` permet à des variantes de provider de réutiliser les variables d'environnement d'authentification,
profils d'authentification, authentification adossée à la configuration et choix d'onboarding par clé API d'un autre provider
sans coder en dur cette relation dans le noyau.
- `providerEndpoints` permet aux plugins provider de posséder de simples métadonnées de
correspondance d'hôte/baseUrl d'endpoint. Utilisez-le uniquement pour les classes d'endpoint déjà prises en charge par le noyau ;
le plugin reste responsable du comportement d'exécution.
- `syntheticAuthRefs` est le chemin de métadonnées léger pour les hooks d'authentification synthétique appartenant au provider
qui doivent être visibles pour la découverte à froid des modèles avant l'existence du registre d'exécution.
Ne listez que les références dont le provider d'exécution ou le backend CLI implémente réellement
`resolveSyntheticAuth`.
- `nonSecretAuthMarkers` est le chemin de métadonnées léger pour les clés API d'espace réservé appartenant à des plugins intégrés
telles que les marqueurs d'identifiants locaux, OAuth ou ambiants.
Le noyau les traite comme non secrètes pour l'affichage d'authentification et les audits de secrets sans
coder en dur le provider propriétaire.
- `channelEnvVars` est le chemin de métadonnées léger pour le repli shell-env, les invites de configuration
et les surfaces de canal similaires qui ne doivent pas démarrer l'environnement d'exécution du plugin
uniquement pour inspecter les noms env.
- `providerAuthChoices` est le chemin de métadonnées léger pour les sélecteurs de choix d'authentification,
la résolution de `--auth-choice`, le mappage du provider préféré et l'enregistrement simple
des drapeaux CLI d'onboarding avant le chargement de l'environnement d'exécution du provider. Pour les métadonnées
d'assistant d'exécution qui nécessitent du code provider, voir
[Hooks d'exécution du provider](/fr/plugins/architecture#provider-runtime-hooks).
- Les types exclusifs de plugin sont sélectionnés via `plugins.slots.*`.
- `kind: "memory"` est sélectionné par `plugins.slots.memory`.
- `kind: "context-engine"` est sélectionné par `plugins.slots.contextEngine`
(par défaut : `legacy` intégré).
- `channels`, `providers`, `cliBackends` et `skills` peuvent être omis lorsqu’un plugin n’en a pas besoin.
- Si votre plugin dépend de modules natifs, documentez les étapes de build et toute exigence 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 et toute
exigence de liste d'autorisation du gestionnaire de paquets (par exemple, pnpm `allow-build-scripts`
- `pnpm rebuild <package>`).
## Lié
- [Créer des Plugins](/fr/plugins/building-plugins) — bien démarrer avec les plugins
- [Architecture des Plugins](/fr/plugins/architecture) — architecture interne
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence du SDK de Plugin
- [Créer des plugins](/fr/plugins/building-plugins) — prise en main des 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

358
docs/fr/plugins/sdk-channel-plugins.md
View File

@ -1,108 +1,110 @@
---
read_when:
- Vous créez un nouveau Plugin de canal de messagerie
- Vous voulez connecter OpenClaw à une plateforme de messagerie
- Vous devez comprendre la surface d’adaptation ChannelPlugin
- Vous créez un nouveau plugin de canal de messagerie
- Vous souhaitez connecter OpenClaw à une plateforme de messagerie
- Vous devez comprendre la surface d’adaptation `ChannelPlugin`
sidebarTitle: Channel Plugins
summary: Guide étape par étape pour créer un Plugin de canal de messagerie pour OpenClaw
title: Créer des Plugins de canal
summary: Guide étape par étape pour créer un plugin de canal de messagerie pour OpenClaw
title: Création de plugins de canal
x-i18n:
generated_at: "2026-04-21T07:02:56Z"
generated_at: "2026-04-21T19:20:41Z"
model: gpt-5.4
provider: openai
source_hash: 569394aeefa0231ae3157a13406f91c97fe7eeff2b62df0d35a893f1ad4d5d05
source_hash: 35cae55c13b69f2219bd2f9bd3ee2f7d8c4075bd87f0be11c35a0fddb070fe1e
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# Créer des Plugins de canal
# Création de plugins de canal
Ce guide explique étape par étape comment créer un Plugin de canal qui connecte OpenClaw à une
plateforme de messagerie. À la fin, vous aurez un canal fonctionnel avec sécurité DM,
appairage, fil de réponses et messagerie sortante.
Ce guide explique pas à pas comment créer un plugin de canal qui connecte OpenClaw à une
plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec la sécurité des MP,
l’appairage, le fil de réponses et la messagerie sortante.
<Info>
Si vous n’avez encore jamais créé de Plugin OpenClaw, lisez d’abord
[Prise en main](/fr/plugins/building-plugins) pour la structure de paquet
Si vous n’avez encore créé aucun plugin OpenClaw, lisez d’abord
[Prise en main](/fr/plugins/building-plugins) pour comprendre la structure de package
de base et la configuration du manifeste.
</Info>
## Fonctionnement des Plugins de canal
## Fonctionnement des plugins de canal
Les Plugins de canal n’ont pas besoin de leurs propres outils send/edit/react. OpenClaw conserve un
outil `message` partagé dans le cœur. Votre Plugin possède :
Les plugins de canal n’ont pas besoin de leurs propres outils send/edit/react. OpenClaw conserve un
outil `message` partagé dans le cœur. Votre plugin gère :
- **Config** — résolution de compte et assistant de configuration
- **Sécurité** — politique DM et listes d’autorisation
- **Appairage** — flux d’approbation DM
- **Grammaire de session** — comment les identifiants de conversation spécifiques au fournisseur se mappent aux chats de base, identifiants de fil et replis parents
- **Configuration** — résolution de compte et assistant de configuration
- **Sécurité** — politique des MP et listes d’autorisation
- **Appairage** — flux d’approbation en MP
- **Grammaire de session** — comment les identifiants de conversation spécifiques au fournisseur sont mappés aux conversations de base, aux identifiants de fil et aux replis parent
- **Sortant** — envoi de texte, médias et sondages vers la plateforme
- **Fil de discussion** — comment les réponses sont enfilées
- **Fil de discussion** — comment les réponses sont organisées en fil
Le cœur possède l’outil message partagé, le câblage des prompts, la forme externe de la clé de session,
la gestion générique de `:thread:` et la répartition.
Le cœur gère l’outil de message partagé, le câblage des prompts, la forme externe de la clé de session,
la gestion générique de `:thread:` et la distribution.
Si votre canal ajoute des paramètres d’outil message qui transportent des sources média, exposez ces
Si votre canal ajoute des paramètres à l’outil de message qui transportent des sources média, exposez ces
noms de paramètres via `describeMessageTool(...).mediaSourceParams`. Le cœur utilise
cette liste explicite pour la normalisation des chemins du sandbox et la politique
d’accès média sortant, afin que les Plugins n’aient pas besoin de cas particuliers
dans le cœur partagé pour les paramètres spécifiques au fournisseur comme avatar, pièce jointe ou image de couverture.
Préférez renvoyer une map indexée par clé d’action telle que
`{ "set-profile": ["avatarUrl", "avatarPath"] }` pour que des actions sans rapport n’héritent pas des arguments média d’une autre action. Un tableau plat fonctionne toujours pour des paramètres qui sont intentionnellement partagés entre toutes les actions exposées.
cette liste explicite pour la normalisation des chemins sandbox et la politique d’accès aux médias sortants,
afin que les plugins n’aient pas besoin de cas particuliers dans le cœur partagé pour les paramètres
spécifiques au fournisseur comme les avatars, pièces jointes ou images de couverture.
Préférez renvoyer une map indexée par action telle que
`{ "set-profile": ["avatarUrl", "avatarPath"] }` afin que les actions non liées n’héritent pas des arguments média d’une autre action. Un tableau plat fonctionne aussi pour les paramètres volontairement partagés par chaque action exposée.
Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, gardez cette analyse
dans le Plugin avec `messaging.resolveSessionConversation(...)`. C’est le hook canonique
pour mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil optionnel,
`baseConversationId` explicite et d’éventuels `parentConversationCandidates`.
Quand vous renvoyez `parentConversationCandidates`, gardez-les ordonnés du parent
le plus étroit au plus large / conversation de base.
Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, gardez cette logique d’analyse
dans le plugin avec `messaging.resolveSessionConversation(...)`. Il s’agit du hook canonique pour mapper
`rawId` vers l’identifiant de conversation de base, l’identifiant de fil facultatif,
`baseConversationId` explicite, et d’éventuels `parentConversationCandidates`.
Quand vous renvoyez `parentConversationCandidates`, conservez leur ordre du
parent le plus spécifique au plus large / à la conversation de base.
Les Plugins fournis qui ont besoin de la même analyse avant le démarrage du registre de canaux
peuvent aussi exposer un fichier de premier niveau `session-key-api.ts` avec un export
Les plugins intégrés qui ont besoin de la même analyse avant que le registre de canaux ne démarre
peuvent aussi exposer un fichier `session-key-api.ts` de niveau supérieur avec un export
`resolveSessionConversation(...)` correspondant. Le cœur utilise cette surface sûre pour l’amorçage
uniquement lorsque le registre de Plugins runtime n’est pas encore disponible.
uniquement lorsque le registre de plugins à l’exécution n’est pas encore disponible.
`messaging.resolveParentConversationCandidates(...)` reste disponible comme repli de compatibilité hérité lorsqu’un Plugin n’a besoin que de replis parents au-dessus de l’identifiant générique/brut. Si les deux hooks existent, le cœur utilise d’abord
`resolveSessionConversation(...).parentConversationCandidates` et ne revient à `resolveParentConversationCandidates(...)` que lorsque le hook canonique
les omet.
`messaging.resolveParentConversationCandidates(...)` reste disponible comme solution de compatibilité héritée lorsqu’un plugin n’a besoin que
de replis parent au-dessus de l’identifiant générique / brut. Si les deux hooks existent, le cœur utilise
d’abord `resolveSessionConversation(...).parentConversationCandidates` et ne
revient à `resolveParentConversationCandidates(...)` que si le hook canonique
ne les fournit pas.
## Approbations et capacités de canal
La plupart des Plugins de canal n’ont pas besoin de code spécifique aux approbations.
La plupart des plugins de canal n’ont pas besoin de code spécifique aux approbations.
- Le cœur possède `/approve` dans le même chat, les charges utiles partagées des boutons d’approbation et la livraison de repli générique.
- Préférez un unique objet `approvalCapability` sur le Plugin de canal lorsque le canal a besoin d’un comportement spécifique aux approbations.
- `ChannelPlugin.approvals` est supprimé. Placez les faits de livraison / natifs / rendu / auth des approbations sur `approvalCapability`.
- `plugin.auth` ne sert qu’à login/logout ; le cœur ne lit plus les hooks d’auth d’approbation depuis cet objet.
- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la jonction canonique d’auth d’approbation.
- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’auth d’approbation dans le même chat.
- Si votre canal expose des approbations exec natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état surface initiatrice / client natif lorsqu’il diffère de l’auth d’approbation dans le même chat. Le cœur utilise ce hook spécifique à exec pour distinguer `enabled` et `disabled`, décider si le canal initiateur prend en charge les approbations exec natives, et inclure le canal dans les indications de repli pour client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit cela pour le cas courant.
- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour un comportement spécifique au canal dans le cycle de vie des charges utiles, comme masquer des prompts locaux d’approbation en double ou envoyer des indicateurs de frappe avant la livraison.
- Le cœur gère `/approve` dans le même chat, les charges utiles de bouton d’approbation partagées, et la distribution de secours générique.
- Préférez un seul objet `approvalCapability` sur le plugin de canal quand le canal a besoin d’un comportement spécifique aux approbations.
- `ChannelPlugin.approvals` est supprimé. Placez les informations de distribution / natif / rendu / authentification des approbations sur `approvalCapability`.
- `plugin.auth` sert uniquement à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation depuis cet objet.
- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la jonction canonique pour l’authentification des approbations.
- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans le même chat.
- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface d’initiation / du client natif lorsqu’il diffère de l’authentification d’approbation dans le même chat. Le cœur utilise ce hook spécifique à l’exécution pour distinguer `enabled` de `disabled`, décider si le canal initiateur prend en charge les approbations d’exécution natives, et inclure le canal dans les indications de repli pour client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit cela pour le cas courant.
- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour les comportements spécifiques au canal dans le cycle de vie des charges utiles, par exemple masquer les prompts locaux d’approbation en double ou envoyer des indicateurs de saisie avant la livraison.
- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression du repli.
- Utilisez `approvalCapability.nativeRuntime` pour les faits d’approbation native détenus par le canal. Gardez-le lazy sur les points d’entrée de canal chauds avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module runtime à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations.
- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation natives gérées par le canal. Gardez-le paresseux sur les points d’entrée de canal sensibles avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module runtime à la demande tout en laissant le cœur assembler le cycle de vie des approbations.
- Utilisez `approvalCapability.render` uniquement lorsqu’un canal a réellement besoin de charges utiles d’approbation personnalisées au lieu du moteur de rendu partagé.
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse de chemin désactivé explique les boutons de config exacts nécessaires pour activer les approbations exec natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent rendre des chemins à portée de compte tels que `channels.<channel>.accounts.<id>.execApprovals.*` au lieu de valeurs par défaut de premier niveau.
- Si un canal peut déduire des identités DM stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans le même chat sans ajouter de logique centrale spécifique aux approbations.
- Si un canal a besoin d’une livraison d’approbation native, gardez le code du canal concentré sur la normalisation de la cible ainsi que sur les faits de transport / présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les faits spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et posséder le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage externe. `nativeRuntime` est découpé en quelques jonctions plus petites :
- `availability` — si le compte est configuré et si une requête doit être gérée
- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente / résolues / expirées ou des actions finales
- `transport` — préparer les cibles ainsi qu’envoyer / mettre à jour / supprimer les messages d’approbation natifs
- `interactions` — hooks facultatifs bind/unbind/clear-action pour les boutons ou réactions natifs
- `observe` — hooks facultatifs de diagnostic de livraison
- Si le canal a besoin d’objets détenus à l’exécution tels qu’un client, un jeton, une app Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte runtime permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de glue de wrapper spécifique aux approbations.
- N’utilisez `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de plus bas niveau que lorsque la jonction pilotée par les capacités n’est pas encore assez expressive.
- Les canaux d’approbation native doivent acheminer à la fois `accountId` et `approvalKind` via ces helpers. `accountId` maintient la portée correcte de la politique d’approbation multi-comptes au bon compte bot, et `approvalKind` maintient le comportement d’approbation exec vs Plugin disponible pour le canal sans branches codées en dur dans le cœur.
- Le cœur possède maintenant aussi les avis de reroutage d’approbation. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi « approval went to DMs / another channel » depuis `createChannelNativeApprovalRuntime` ; exposez plutôt un routage précis origine + DM d’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier un éventuel avis dans le chat initiateur.
- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas
deviner ou réécrire le routage d’approbation exec vs Plugin à partir de l’état local au canal.
- Différents types d’approbation peuvent intentionnellement exposer différentes surfaces natives.
Exemples fournis actuels :
- Slack conserve le routage d’approbation native disponible pour les identifiants exec et Plugin.
- Matrix conserve le même routage natif DM/canal et la même UX de réaction pour les approbations exec
et Plugin, tout en laissant l’auth différer selon le type d’approbation.
- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le constructeur de capacité et exposer `approvalCapability` sur le Plugin.
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal souhaite que la réponse sur le chemin désactivé explique les paramètres exacts nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent rendre des chemins à portée de compte comme `channels.<channel>.accounts.<id>.execApprovals.*` au lieu de valeurs par défaut de niveau supérieur.
- Si un canal peut déduire des identités de MP stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans le même chat sans ajouter de logique spécifique aux approbations dans le cœur.
- Si un canal a besoin d’une distribution d’approbation native, faites en sorte que le code du canal reste centré sur la normalisation des cibles ainsi que sur les informations de transport / présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et gérer le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage ailleurs. `nativeRuntime` est divisé en quelques jonctions plus petites :
- `availability` — si le compte est configuré et si une requête doit être traitée
- `presentation` — mappe le modèle de vue d’approbation partagé vers des charges utiles natives en attente / résolues / expirées ou des actions finales
- `transport` — prépare les cibles puis envoie / met à jour / supprime les messages d’approbation natifs
- `interactions` — hooks facultatifs bind / unbind / clear-action pour les boutons ou réactions natifs
- `observe` — hooks facultatifs de diagnostic de distribution
- Si le canal a besoin d’objets gérés à l’exécution tels qu’un client, un jeton, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte runtime permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de glue d’encapsulation spécifique aux approbations.
- Recourez à plus bas niveau à `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` uniquement lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive.
- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` par ces helpers. `accountId` maintient la portée correcte de la politique d’approbation multi-comptes pour le bon compte bot, et `approvalKind` maintient disponible au canal le comportement d’approbation d’exécution ou de plugin sans branches codées en dur dans le cœur.
- Le cœur gère désormais aussi les avis de reroutage d’approbation. Les plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation est allée en MP / vers un autre canal » depuis `createChannelNativeApprovalRuntime` ; à la place, exposez un routage précis de l’origine + des MP de l’approbateur via les helpers partagés des capacités d’approbation et laissez le cœur agréger les distributions réelles avant de publier un éventuel avis dans le chat initiateur.
- Préservez de bout en bout le type d’identifiant d’approbation distribué. Les clients natifs ne doivent pas
deviner ni réécrire le routage d’approbation d’exécution ou de plugin à partir de l’état local du canal.
- Différents types d’approbation peuvent volontairement exposer des surfaces natives différentes.
Exemples intégrés actuels :
- Slack maintient disponible le routage d’approbation natif à la fois pour les identifiants d’exécution et de plugin.
- Matrix conserve le même routage natif en MP / canal et la même UX par réaction pour les approbations d’exécution
et de plugin, tout en permettant quand même à l’authentification de différer selon le type d’approbation.
- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le builder de capacité et exposer `approvalCapability` sur le plugin.
Pour les points d’entrée de canal chauds, préférez les sous-chemins runtime plus étroits lorsque vous n’avez besoin
Pour les points d’entrée de canal sensibles, préférez les sous-chemins runtime plus étroits lorsque vous n’avez besoin
que d’une partie de cette famille :
- `openclaw/plugin-sdk/approval-auth-runtime`
@ -119,87 +121,96 @@ De même, préférez `openclaw/plugin-sdk/setup-runtime`,
`openclaw/plugin-sdk/setup-adapter-runtime`,
`openclaw/plugin-sdk/reply-runtime`,
`openclaw/plugin-sdk/reply-dispatch-runtime`,
`openclaw/plugin-sdk/reply-reference` et
`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la
surface parapluie plus large.
`openclaw/plugin-sdk/reply-reference`, et
`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la surface
ombrelle plus large.
Pour la configuration en particulier :
Pour la configuration initiale en particulier :
- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution :
adaptateurs de patch de configuration sûrs à l’import (`createPatchedAccountSetupAdapter`,
- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration initiale sûrs à l’exécution :
adaptateurs de patch de configuration initiale sûrs à l’import (`createPatchedAccountSetupAdapter`,
`createEnvPatchedAccountSetupAdapter`,
`createSetupInputPresenceValidator`), sortie de note de lookup,
`promptResolvedAllowFrom`, `splitSetupEntries` et les constructeurs
délégués de proxy de configuration
- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite sensible à l’env
`createSetupInputPresenceValidator`), sortie de note de recherche,
`promptResolvedAllowFrom`, `splitSetupEntries`, et les builders
de proxy de configuration déléguée
- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite sensible aux variables d’environnement
pour `createEnvPatchedAccountSetupAdapter`
- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration à installation facultative ainsi que quelques primitives sûres pour la configuration :
- `openclaw/plugin-sdk/channel-setup` couvre les builders de configuration initiale avec installation optionnelle
ainsi que quelques primitives sûres pour la configuration initiale :
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
Si votre canal prend en charge une configuration ou une auth pilotée par l’env et que les flux génériques de démarrage / config
doivent connaître ces noms d’env avant le chargement runtime, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`. Gardez les `envVars` runtime du canal ou les constantes locales uniquement pour le texte orienté opérateur.
Si votre canal prend en charge une configuration initiale ou une authentification pilotée par variables d’environnement et que les flux génériques de démarrage / configuration
doivent connaître ces noms de variables d’environnement avant le chargement du runtime, déclarez-les dans le
manifeste du plugin avec `channelEnvVars`. Conservez les `envVars` du runtime de canal ou les constantes locales uniquement pour le texte destiné aux opérateurs.
Si votre canal peut apparaître dans `status`, `channels list`, `channels status`, ou dans les analyses SecretRef avant que le runtime du plugin ne démarre, ajoutez `openclaw.setupEntry` dans
`package.json`. Ce point d’entrée doit pouvoir être importé sans risque dans des chemins de commande en lecture seule et doit renvoyer les métadonnées du canal, l’adaptateur de configuration sûr pour la configuration initiale, l’adaptateur de statut, et les métadonnées de cible secrète du canal nécessaires à ces résumés. Ne démarrez pas de clients, d’écouteurs ou de runtimes de transport depuis le point d’entrée de configuration initiale.
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` et
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, et
`splitSetupEntries`
- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez aussi besoin des
helpers partagés plus lourds de configuration / config comme
helpers partagés plus lourds de configuration initiale / configuration tels que
`moveSingleAccountChannelSectionToDefaultAccount(...)`
Si votre canal veut seulement annoncer « install this plugin first » dans les surfaces de configuration, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur / assistant générés échouent de façon sûre sur les écritures de configuration et la finalisation, et réutilisent le même message exigeant l’installation dans la validation, la finalisation et le texte de lien vers la documentation.
Si votre canal veut seulement annoncer « installez d’abord ce plugin » dans les surfaces de configuration initiale, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur / assistant généré échoue de manière fermée sur les écritures de configuration et la finalisation, et réutilise le même message exigeant l’installation dans la validation, la finalisation et le texte du lien vers la documentation.
Pour les autres chemins de canal chauds, préférez les helpers étroits aux surfaces héritées plus larges :
Pour les autres chemins de canal sensibles, préférez les helpers étroits aux surfaces héritées plus larges :
- `openclaw/plugin-sdk/account-core`,
`openclaw/plugin-sdk/account-id`,
`openclaw/plugin-sdk/account-resolution` et
`openclaw/plugin-sdk/account-resolution`, et
`openclaw/plugin-sdk/account-helpers` pour la configuration multi-comptes et
le repli de compte par défaut
le repli vers le compte par défaut
- `openclaw/plugin-sdk/inbound-envelope` et
`openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de route / enveloppe entrante et
l’enregistrement-et-répartition
- `openclaw/plugin-sdk/messaging-targets` pour l’analyse / correspondance des cibles
`openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage des routes / enveloppes entrantes et
l’enregistrement-et-distribution
- `openclaw/plugin-sdk/messaging-targets` pour l’analyse et la correspondance des cibles
- `openclaw/plugin-sdk/outbound-media` et
`openclaw/plugin-sdk/outbound-runtime` pour le chargement média ainsi que les délégués d’identité / envoi sortants et la planification de charge utile
`openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que les
délégations d’identité / d’envoi sortants et la planification des charges utiles
- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des liaisons de fil
et l’enregistrement d’adaptateur
- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champs héritée agent/média
est encore nécessaire
- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des commandes personnalisées Telegram, la validation des doublons / conflits et un contrat de configuration de commande stable en repli
et l’enregistrement des adaptateurs
- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champ héritée
pour les charges utiles agent / média est encore requise
- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des commandes personnalisées Telegram,
la validation des doublons / conflits, et un contrat de configuration de commandes
stable en repli
Les canaux avec auth uniquement peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes / auth. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de chat personnalisés doivent utiliser les helpers natifs partagés au lieu de développer leur propre cycle de vie d’approbation.
Les canaux uniquement basés sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le plugin expose simplement les capacités sortantes / d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de chat personnalisés doivent utiliser les helpers natifs partagés plutôt que d’implémenter leur propre cycle de vie d’approbation.
## Politique de mention entrante
Gardez la gestion des mentions entrantes séparée en deux couches :
- collecte de preuves détenue par le Plugin
- collecte d’éléments probants gérée par le plugin
- évaluation de politique partagée
Utilisez `openclaw/plugin-sdk/channel-mention-gating` pour les décisions de politique de mention.
Utilisez `openclaw/plugin-sdk/channel-inbound` uniquement lorsque vous avez besoin du barrel
plus large de helpers entrants.
Utilisez `openclaw/plugin-sdk/channel-inbound` uniquement lorsque vous avez besoin de la barrique
plus large des helpers entrants.
Bon cas d’usage pour la logique locale au Plugin :
Bon cas d’usage pour la logique locale au plugin :
- détection de réponse au bot
- détection de citation du bot
- vérifications de participation au fil
- exclusions de messages de service / système
- caches natifs à la plateforme nécessaires pour prouver la participation du bot
- caches natifs de plateforme nécessaires pour prouver la participation du bot
Bon cas d’usage pour le helper partagé :
- `requireMention`
- résultat de mention explicite
- liste d’autorisation de mention implicite
- contournement de commande
- décision finale d’ignorer
- contournement des commandes
- décision finale de saut
Flux recommandé :
1. Calculez les faits locaux de mention.
2. Passez ces faits à `resolveInboundMentionDecision({ facts, policy })`.
1. Calculez les faits de mention locaux.
2. Transmettez ces faits à `resolveInboundMentionDecision({ facts, policy })`.
3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde entrante.
```typescript
@ -239,8 +250,8 @@ const decision = resolveInboundMentionDecision({
if (decision.shouldSkip) return;
```
`api.runtime.channel.mentions` expose les mêmes helpers partagés de mention pour
les Plugins de canal fournis qui dépendent déjà de l’injection runtime :
`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour
les plugins de canal intégrés qui dépendent déjà de l’injection runtime :
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -249,22 +260,22 @@ les Plugins de canal fournis qui dépendent déjà de l’injection runtime :
- `resolveInboundMentionDecision`
Si vous n’avez besoin que de `implicitMentionKindWhen` et
`resolveInboundMentionDecision`, importez depuis
`resolveInboundMentionDecision`, importez-les depuis
`openclaw/plugin-sdk/channel-mention-gating` pour éviter de charger des helpers runtime
entrants sans rapport.
entrants non liés.
Les anciens helpers `resolveMentionGating*` restent sur
Les anciens helpers `resolveMentionGating*` restent présents sur
`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité. Le nouveau code
doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
## Guide pas à pas
## Procédure pas à pas
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="Paquet et manifeste">
Créez les fichiers de Plugin standard. Le champ `channel` dans `package.json` est
ce qui fait de ceci un Plugin de canal. Pour la surface complète des métadonnées de paquet,
voir [Configuration et config de Plugin](/fr/plugins/sdk-setup#openclaw-channel) :
<Step title="Package et manifeste">
Créez les fichiers de plugin standard. Le champ `channel` dans `package.json`
est ce qui fait de ceci un plugin de canal. Pour la surface complète des métadonnées de package,
voir [Configuration initiale et configuration des plugins](/fr/plugins/sdk-setup#openclaw-channel) :
<CodeGroup>
```json package.json
@ -290,7 +301,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
"kind": "channel",
"channels": ["acme-chat"],
"name": "Acme Chat",
"description": "Plugin de canal Acme Chat",
"description": "Acme Chat channel plugin",
"configSchema": {
"type": "object",
"additionalProperties": false,
@ -313,8 +324,8 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
</Step>
<Step title="Construire l’objet Plugin de canal">
L’interface `ChannelPlugin` comporte de nombreuses surfaces d’adaptation facultatives. Commencez avec
<Step title="Créer l’objet plugin de canal">
L’interface `ChannelPlugin` comporte de nombreuses surfaces d’adaptateur facultatives. Commencez par
le minimum — `id` et `setup` — puis ajoutez des adaptateurs selon vos besoins.
Créez `src/channel.ts` :
@ -366,7 +377,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
},
}),
// Sécurité DM : qui peut envoyer des messages au bot
// Sécurité des MP : qui peut envoyer des messages au bot
security: {
dm: {
channelKey: "acme-chat",
@ -376,18 +387,18 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
},
},
// Appairage : flux d’approbation pour les nouveaux contacts DM
// Appairage : flux d’approbation pour les nouveaux contacts en MP
pairing: {
text: {
idLabel: "nom d’utilisateur Acme Chat",
message: "Envoyez ce code pour vérifier votre identité :",
idLabel: "Acme Chat username",
message: "Send this code to verify your identity:",
notify: async ({ target, code }) => {
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
},
},
},
// Fil de discussion : comment les réponses sont livrées
// Fil de discussion : comment les réponses sont distribuées
threading: { topLevelReplyToMode: "reply" },
// Sortant : envoyer des messages vers la plateforme
@ -411,17 +422,17 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
```
<Accordion title="Ce que createChatChannelPlugin fait pour vous">
Au lieu d’implémenter manuellement des interfaces d’adaptation de bas niveau, vous passez
des options déclaratives et le constructeur les compose :
Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas niveau, vous transmettez
des options déclaratives et le builder les compose :
| Option | Ce qu’elle câble |
| --- | --- |
| `security.dm` | Résolveur de sécurité DM à portée depuis les champs de config |
| `pairing.text` | Flux d’appairage DM fondé sur du texte avec échange de code |
| `security.dm` | Résolveur de sécurité MP à portée limitée à partir des champs de configuration |
| `pairing.text` | Flux d’appairage MP basé sur du texte avec échange de code |
| `threading` | Résolveur de mode reply-to (fixe, à portée de compte ou personnalisé) |
| `outbound.attachedResults` | Fonctions d’envoi qui renvoient des métadonnées de résultat (identifiants de message) |
Vous pouvez aussi passer des objets d’adaptateur bruts au lieu des options déclaratives
Vous pouvez aussi transmettre des objets d’adaptateur bruts au lieu des options déclaratives
si vous avez besoin d’un contrôle total.
</Accordion>
@ -437,20 +448,20 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
export default defineChannelPluginEntry({
id: "acme-chat",
name: "Acme Chat",
description: "Plugin de canal Acme Chat",
description: "Acme Chat channel plugin",
plugin: acmeChatPlugin,
registerCliMetadata(api) {
api.registerCli(
({ program }) => {
program
.command("acme-chat")
.description("Gestion Acme Chat");
.description("Acme Chat management");
},
{
descriptors: [
{
name: "acme-chat",
description: "Gestion Acme Chat",
description: "Acme Chat management",
hasSubcommands: false,
},
],
@ -463,21 +474,22 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
});
```
Placez les descripteurs CLI détenus par le canal dans `registerCliMetadata(...)` afin qu’OpenClaw
Placez les descripteurs CLI gérés par le canal dans `registerCliMetadata(...)` afin qu’OpenClaw
puisse les afficher dans l’aide racine sans activer le runtime complet du canal,
tandis que les chargements complets normaux récupèrent toujours les mêmes descripteurs pour l’enregistrement réel des commandes. Gardez `registerFull(...)` pour le travail runtime uniquement.
tandis que les chargements complets normaux récupèrent quand même les mêmes descripteurs pour le véritable enregistrement
des commandes. Conservez `registerFull(...)` pour le travail uniquement runtime.
Si `registerFull(...)` enregistre des méthodes RPC Gateway, utilisez un
préfixe spécifique au Plugin. Les espaces de noms admin du cœur (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et se
résolvent toujours vers `operator.admin`.
`defineChannelPluginEntry` gère automatiquement la séparation de mode d’enregistrement. Voir
préfixe spécifique au plugin. Les espaces de noms d’administration du cœur (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et
se résolvent toujours vers `operator.admin`.
`defineChannelPluginEntry` gère automatiquement la séparation des modes d’enregistrement. Voir
[Points d’entrée](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour toutes les
options.
</Step>
<Step title="Ajouter un point d’entrée de configuration">
Créez `setup-entry.ts` pour un chargement léger pendant l’onboarding :
<Step title="Ajouter un point d’entrée de configuration initiale">
Créez `setup-entry.ts` pour un chargement léger pendant l’intégration :
```typescript setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -486,33 +498,33 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
export default defineSetupPluginEntry(acmeChatPlugin);
```
OpenClaw charge ceci au lieu du point d’entrée complet lorsque le canal est désactivé
ou non configuré. Cela évite de charger du code runtime lourd pendant les flux de configuration.
Voir [Configuration et config](/fr/plugins/sdk-setup#setup-entry) pour les détails.
OpenClaw charge ceci à la place du point d’entrée complet lorsque le canal est désactivé
ou non configuré. Cela évite de charger du code runtime lourd pendant les flux de configuration initiale.
Voir [Configuration initiale et configuration](/fr/plugins/sdk-setup#setup-entry) pour plus de détails.
Les canaux fournis de l’espace de travail qui divisent les exports sûrs pour la configuration dans des modules auxiliaires
peuvent utiliser `defineBundledChannelSetupEntry(...)` depuis
Les canaux intégrés de l’espace de travail qui séparent les exports sûrs pour la configuration initiale dans des modules
compagnons peuvent utiliser `defineBundledChannelSetupEntry(...)` depuis
`openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont aussi besoin d’un
setter runtime explicite au moment de la configuration.
setter runtime explicite au moment de la configuration initiale.
</Step>
<Step title="Gérer les messages entrants">
Votre Plugin doit recevoir des messages depuis la plateforme et les transmettre à
OpenClaw. Le modèle habituel est un Webhook qui vérifie la requête et la
répartit via le gestionnaire entrant de votre canal :
Votre plugin doit recevoir les messages depuis la plateforme et les transmettre à
OpenClaw. Le schéma habituel est un Webhook qui vérifie la requête et
la distribue via le gestionnaire entrant de votre canal :
```typescript
registerFull(api) {
api.registerHttpRoute({
path: "/acme-chat/webhook",
auth: "plugin", // auth gérée par le Plugin (vérifiez vous-même les signatures)
auth: "plugin", // authentification gérée par le plugin (vérifiez vous-même les signatures)
handler: async (req, res) => {
const event = parseWebhookPayload(req);
// Votre gestionnaire entrant répartit le message vers OpenClaw.
// Votre gestionnaire entrant distribue le message vers OpenClaw.
// Le câblage exact dépend de votre SDK de plateforme —
// voir un exemple réel dans le paquet de Plugin Microsoft Teams ou Google Chat fourni.
// voir un exemple réel dans le package de plugin Microsoft Teams ou Google Chat intégré.
await handleAcmeChatInbound(api, event);
res.statusCode = 200;
@ -524,9 +536,9 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
```
<Note>
La gestion des messages entrants est spécifique au canal. Chaque Plugin de canal possède
son propre pipeline entrant. Regardez les Plugins de canal fournis
(par exemple le paquet de Plugin Microsoft Teams ou Google Chat) pour voir des modèles réels.
La gestion des messages entrants est spécifique au canal. Chaque plugin de canal gère
son propre pipeline entrant. Regardez les plugins de canal intégrés
(par exemple le package de plugin Microsoft Teams ou Google Chat) pour voir des schémas réels.
</Note>
</Step>
@ -539,8 +551,8 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";
describe("plugin acme-chat", () => {
it("résout le compte depuis la configuration", () => {
describe("acme-chat plugin", () => {
it("resolves account from config", () => {
const cfg = {
channels: {
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
@ -550,7 +562,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
expect(account.token).toBe("test-token");
});
it("inspecte le compte sans matérialiser les secrets", () => {
it("inspects account without materializing secrets", () => {
const cfg = {
channels: { "acme-chat": { token: "test-token" } },
} as any;
@ -559,7 +571,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
expect(result.tokenStatus).toBe("available");
});
it("signale une configuration manquante", () => {
it("reports missing config", () => {
const cfg = { channels: {} } as any;
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
expect(result.configured).toBe(false);
@ -584,12 +596,12 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
├── openclaw.plugin.json # Manifeste avec schéma de configuration
├── index.ts # defineChannelPluginEntry
├── setup-entry.ts # defineSetupPluginEntry
├── api.ts # Exports publics (optionnel)
├── runtime-api.ts # Exports runtime internes (optionnel)
├── api.ts # Exports publics (facultatif)
├── runtime-api.ts # Exports runtime internes (facultatif)
└── src/
├── channel.ts # ChannelPlugin via createChatChannelPlugin
├── channel.test.ts # Tests
├── client.ts # Client API de la plateforme
├── client.ts # Client API de plateforme
└── runtime.ts # Store runtime (si nécessaire)
```
@ -599,7 +611,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
<Card title="Options de fil de discussion" icon="git-branch" href="/fr/plugins/sdk-entrypoints#registration-mode">
Modes de réponse fixes, à portée de compte ou personnalisés
</Card>
<Card title="Intégration de l’outil message" icon="puzzle" href="/fr/plugins/architecture#channel-plugins-and-the-shared-message-tool">
<Card title="Intégration de l’outil de message" icon="puzzle" href="/fr/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool et découverte des actions
</Card>
<Card title="Résolution de cible" icon="crosshair" href="/fr/plugins/architecture#channel-target-resolution">
@ -611,15 +623,15 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
</CardGroup>
<Note>
Certaines jonctions de helpers fournies existent encore pour la maintenance et la
compatibilité des Plugins fournis. Elles ne constituent pas le modèle recommandé pour les nouveaux Plugins de canal ;
préférez les sous-chemins génériques channel/setup/reply/runtime de la surface commune du SDK
sauf si vous maintenez directement cette famille de Plugins fournis.
Certaines jonctions helper intégrées existent encore pour la maintenance et la
compatibilité des plugins intégrés. Ce n’est pas le schéma recommandé pour les nouveaux plugins de canal ;
préférez les sous-chemins génériques channel/setup/reply/runtime de la surface
SDK commune, sauf si vous maintenez directement cette famille de plugins intégrés.
</Note>
## Étapes suivantes
- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles
- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — si votre plugin fournit aussi des modèles
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin
- [Tests du SDK](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat
- [Manifeste de Plugin](/fr/plugins/manifest) — schéma complet du manifeste
- [Tests SDK](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat
- [Manifeste du plugin](/fr/plugins/manifest) — schéma complet du manifeste

95
docs/fr/providers/github-copilot.md
View File

@ -1,31 +1,27 @@
---
read_when:
- Vous souhaitez utiliser GitHub Copilot comme fournisseur de modèles
- Vous souhaitez utiliser GitHub Copilot comme fournisseur de modèle
- Vous avez besoin du flux `openclaw models auth login-github-copilot`
summary: Se connecter à GitHub Copilot depuis OpenClaw en utilisant le flux appareil
summary: Connectez-vous à GitHub Copilot depuis OpenClaw en utilisant le flux d’appareil
title: GitHub Copilot
x-i18n:
generated_at: "2026-04-21T07:04:43Z"
generated_at: "2026-04-21T19:20:38Z"
model: gpt-5.4
provider: openai
source_hash: f7faafbd3bdcd8886e75fb0d40c3eec66355df3fca6160ebbbb9a0018b7839fe
source_hash: b5169839322f64b24b194302b61c5bad67c6cb6595989f9a1ef65867d8b68659
source_path: providers/github-copilot.md
workflow: 15
---
# GitHub Copilot
GitHub Copilot est l’assistant de codage IA de GitHub. Il donne accès aux
modèles Copilot pour votre compte GitHub et votre offre. OpenClaw peut utiliser Copilot comme
fournisseur de modèles de deux façons différentes.
GitHub Copilot est l’assistant de codage IA de GitHub. Il donne accès aux modèles Copilot pour votre compte et votre forfait GitHub. OpenClaw peut utiliser Copilot comme fournisseur de modèle de deux façons différentes.
## Deux façons d’utiliser Copilot dans OpenClaw
<Tabs>
<Tab title="Fournisseur intégré (github-copilot)">
Utilisez le flux natif de connexion par appareil pour obtenir un jeton GitHub, puis l’échanger contre
des jetons d’API Copilot lorsque OpenClaw s’exécute. Il s’agit du chemin **par défaut** et du plus simple
car il ne nécessite pas VS Code.
Utilisez le flux natif de connexion par appareil pour obtenir un jeton GitHub, puis l’échanger contre des jetons d’API Copilot lorsque OpenClaw s’exécute. Il s’agit du chemin **par défaut** et du plus simple, car il ne nécessite pas VS Code.
<Steps>
<Step title="Exécuter la commande de connexion">
@ -33,20 +29,19 @@ fournisseur de modèles de deux façons différentes.
openclaw models auth login-github-copilot
```
Il vous sera demandé de visiter une URL et de saisir un code à usage unique. Gardez le
terminal ouvert jusqu’à la fin.
Il vous sera demandé de consulter une URL et de saisir un code à usage unique. Gardez le terminal ouvert jusqu’à la fin de l’opération.
</Step>
<Step title="Définir un modèle par défaut">
```bash
openclaw models set github-copilot/claude-opus-4.6
openclaw models set github-copilot/claude-opus-4.7
```
Ou dans la configuration :
Ou dans la configuration :
```json5
{
agents: {
defaults: { model: { primary: "github-copilot/claude-opus-4.6" } },
defaults: { model: { primary: "github-copilot/claude-opus-4.7" } },
},
}
```
@ -56,23 +51,21 @@ fournisseur de modèles de deux façons différentes.
</Tab>
<Tab title="Plugin Copilot Proxy (copilot-proxy)">
Utilisez l’extension VS Code **Copilot Proxy** comme pont local. OpenClaw communique avec
le point de terminaison `/v1` du proxy et utilise la liste de modèles que vous y configurez.
Utilisez l’extension VS Code **Copilot Proxy** comme pont local. OpenClaw communique avec le point de terminaison `/v1` du proxy et utilise la liste de modèles que vous y configurez.
<Note>
Choisissez cette option si vous utilisez déjà Copilot Proxy dans VS Code ou si vous devez passer
par lui. Vous devez activer le plugin et garder l’extension VS Code en cours d’exécution.
Choisissez cette option si vous utilisez déjà Copilot Proxy dans VS Code ou si vous devez passer par lui. Vous devez activer le plugin et laisser l’extension VS Code en cours d’exécution.
</Note>
</Tab>
</Tabs>
## Options facultatives
## Indicateurs facultatifs
| Flag | Description |
| --------------- | --------------------------------------------------- |
| `--yes` | Ignorer l’invite de confirmation |
| `--set-default` | Appliquer également le modèle par défaut recommandé du fournisseur |
| Indicateur | Description |
| -------------- | -------------------------------------------------------- |
| `--yes` | Ignore l’invite de confirmation |
| `--set-default` | Applique également le modèle par défaut recommandé du fournisseur |
```bash
# Ignorer la confirmation
@ -84,34 +77,29 @@ openclaw models auth login --provider github-copilot --method device --set-defau
<AccordionGroup>
<Accordion title="TTY interactif requis">
Le flux de connexion par appareil nécessite un TTY interactif. Exécutez-le directement dans un
terminal, pas dans un script non interactif ni dans un pipeline CI.
Le flux de connexion par appareil nécessite un TTY interactif. Exécutez-le directement dans un terminal, pas dans un script non interactif ni dans un pipeline CI.
</Accordion>
<Accordion title="La disponibilité des modèles dépend de votre offre">
La disponibilité des modèles Copilot dépend de votre offre GitHub. Si un modèle est
rejeté, essayez un autre identifiant (par exemple `github-copilot/gpt-4.1`).
<Accordion title="La disponibilité des modèles dépend de votre forfait">
La disponibilité des modèles Copilot dépend de votre forfait GitHub. Si un modèle est refusé, essayez un autre identifiant (par exemple `github-copilot/gpt-4.1`).
</Accordion>
<Accordion title="Sélection du transport">
Les identifiants de modèles Claude utilisent automatiquement le transport Anthropic Messages. Les modèles GPT,
de série o et Gemini conservent le transport OpenAI Responses. OpenClaw
sélectionne le bon transport en fonction de la référence du modèle.
Les identifiants de modèle Claude utilisent automatiquement le transport Anthropic Messages. Les modèles GPT, o-series et Gemini conservent le transport OpenAI Responses. OpenClaw sélectionne le bon transport en fonction de la référence du modèle.
</Accordion>
<Accordion title="Ordre de résolution des variables d’environnement">
OpenClaw résout l’authentification Copilot à partir des variables d’environnement dans l’ordre
de priorité suivant :
OpenClaw résout l’authentification Copilot à partir des variables d’environnement dans l’ordre de priorité suivant :
| Priority | Variable | Notes |
| -------- | --------------------- | -------------------------------- |
| Priorité | Variable | Remarques |
| -------- | --------------------- | ------------------------------------- |
| 1 | `COPILOT_GITHUB_TOKEN` | Priorité la plus élevée, spécifique à Copilot |
| 2 | `GH_TOKEN` | Jeton GitHub CLI (repli) |
| 2 | `GH_TOKEN` | Jeton GitHub CLI (secours) |
| 3 | `GITHUB_TOKEN` | Jeton GitHub standard (priorité la plus basse) |
Lorsque plusieurs variables sont définies, OpenClaw utilise celle de priorité la plus élevée.
Lorsque plusieurs variables sont définies, OpenClaw utilise celle ayant la priorité la plus élevée.
Le flux de connexion par appareil (`openclaw models auth login-github-copilot`) stocke
son jeton dans le magasin de profils d’authentification et prend priorité sur toutes les variables
son jeton dans le magasin de profils d’authentification et a priorité sur toutes les variables
d’environnement.
</Accordion>
@ -124,22 +112,21 @@ openclaw models auth login --provider github-copilot --method device --set-defau
</AccordionGroup>
<Warning>
Nécessite un TTY interactif. Exécutez la commande de connexion directement dans un terminal, pas
dans un script headless ni dans un job CI.
Nécessite un TTY interactif. Exécutez la commande de connexion directement dans un terminal, et non dans un script sans interface ni dans une tâche CI.
</Warning>
## Embeddings de recherche Memory
## Embeddings de recherche mémoire
GitHub Copilot peut aussi servir de fournisseur d’embedding pour
[la recherche Memory](/fr/concepts/memory-search). Si vous avez un abonnement Copilot et
êtes connecté, OpenClaw peut l’utiliser pour les embeddings sans clé API distincte.
GitHub Copilot peut également servir de fournisseur d’embeddings pour la
[recherche mémoire](/fr/concepts/memory-search). Si vous avez un abonnement Copilot et
que vous vous êtes connecté, OpenClaw peut l’utiliser pour les embeddings sans clé d’API distincte.
### Détection automatique
Lorsque `memorySearch.provider` vaut `"auto"` (par défaut), GitHub Copilot est essayé
avec une priorité de 15 -- après les embeddings locaux mais avant OpenAI et les autres
fournisseurs payants. Si un jeton GitHub est disponible, OpenClaw découvre les
modèles d’embedding disponibles depuis l’API Copilot et choisit automatiquement le meilleur.
Lorsque `memorySearch.provider` vaut `"auto"` (la valeur par défaut), GitHub Copilot est essayé
avec la priorité 15 -- après les embeddings locaux mais avant OpenAI et les autres fournisseurs
payants. Si un jeton GitHub est disponible, OpenClaw découvre les modèles d’embedding disponibles
depuis l’API Copilot et choisit automatiquement le meilleur.
### Configuration explicite
@ -149,7 +136,7 @@ modèles d’embedding disponibles depuis l’API Copilot et choisit automatique
defaults: {
memorySearch: {
provider: "github-copilot",
// Facultatif : remplacer le modèle détecté automatiquement
// Facultatif : remplacer le modèle détecté automatiquement
model: "text-embedding-3-small",
},
},
@ -165,14 +152,14 @@ modèles d’embedding disponibles depuis l’API Copilot et choisit automatique
4. Choisit le meilleur modèle (préfère `text-embedding-3-small`).
5. Envoie les requêtes d’embedding au point de terminaison Copilot `/embeddings`.
La disponibilité des modèles dépend de votre offre GitHub. Si aucun modèle d’embedding n’est
La disponibilité des modèles dépend de votre forfait GitHub. Si aucun modèle d’embedding n’est
disponible, OpenClaw ignore Copilot et essaie le fournisseur suivant.
## Liens associés
## Voir aussi
<CardGroup cols={2}>
<Card title="Sélection de modèle" href="/fr/concepts/model-providers" icon="layers">
Choisir les fournisseurs, les références de modèle et le comportement de repli.
<Card title="Sélection du modèle" href="/fr/concepts/model-providers" icon="layers">
Choisir les fournisseurs, les références de modèle et le comportement de basculement.
</Card>
<Card title="OAuth et authentification" href="/fr/gateway/authentication" icon="key">
Détails d’authentification et règles de réutilisation des identifiants.

354
docs/fr/tools/subagents.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Vous voulez un travail en arrière-plan/parallèle via l'agent
- Vous modifiez `sessions_spawn` ou la politique d'outils des sub-agents
- Vous implémentez ou dépannez des sessions de sub-agent liées à un fil
summary: 'Sub-agents : lancer des exécutions d''agent isolées qui annoncent leurs résultats dans le chat demandeur'
title: Sub-agents
- Vous souhaitez un travail en arrière-plan/en parallèle via l’agent
- Vous modifiez la politique de l’outil `sessions_spawn` ou des sous-agents
- Vous implémentez ou résolvez des problèmes liés aux sessions de sous-agents liées à un fil de discussion
summary: 'Sous-agents : lancer des exécutions d’agents isolées qui annoncent les résultats dans le chat du demandeur'
title: Sous-agents
x-i18n:
generated_at: "2026-04-05T12:58:12Z"
generated_at: "2026-04-21T19:20:42Z"
model: gpt-5.4
provider: openai
source_hash: 9df7cc35a3069ce4eb9c92a95df3ce5365a00a3fae92ff73def75461b58fec3f
source_hash: 218913f0db88d40e1b5fdb0201b8d23e7af23df572c86ff4be2637cb62498281
source_path: tools/subagents.md
workflow: 15
---
# Sub-agents
# Sous-agents
Les sub-agents sont des exécutions d'agent en arrière-plan lancées à partir d'une exécution d'agent existante. Ils s'exécutent dans leur propre session (`agent:<agentId>:subagent:<uuid>`) et, une fois terminés, **annoncent** leur résultat dans le canal de chat demandeur. Chaque exécution de sub-agent est suivie comme une [tâche d'arrière-plan](/fr/automation/tasks).
Les sous-agents sont des exécutions d’agents en arrière-plan lancées à partir d’une exécution d’agent existante. Ils s’exécutent dans leur propre session (`agent:<agentId>:subagent:<uuid>`) et, une fois terminés, **annoncent** leur résultat dans le canal de chat du demandeur. Chaque exécution de sous-agent est suivie comme une [tâche en arrière-plan](/fr/automation/tasks).
## Commande slash
Utilisez `/subagents` pour inspecter ou contrôler les exécutions de sub-agent de la **session en cours** :
Utilisez `/subagents` pour inspecter ou contrôler les exécutions de sous-agents pour la **session en cours** :
- `/subagents list`
- `/subagents kill <id|#|all>`
@ -30,9 +30,9 @@ Utilisez `/subagents` pour inspecter ou contrôler les exécutions de sub-agent
- `/subagents steer <id|#> <message>`
- `/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]`
Contrôles de liaison au fil :
Contrôles de liaison au fil de discussion :
Ces commandes fonctionnent sur les canaux qui prennent en charge les liaisons persistantes à un fil. Voir **Canaux prenant en charge les fils** ci-dessous.
Ces commandes fonctionnent sur les canaux qui prennent en charge des liaisons persistantes aux fils de discussion. Voir **Canaux prenant en charge les fils de discussion** ci-dessous.
- `/focus <subagent-label|session-key|session-id|session-label>`
- `/unfocus`
@ -40,137 +40,141 @@ Ces commandes fonctionnent sur les canaux qui prennent en charge les liaisons pe
- `/session idle <duration|off>`
- `/session max-age <duration|off>`
`/subagents info` affiche les métadonnées d'exécution (statut, horodatages, id de session, chemin de transcription, nettoyage).
Utilisez `sessions_history` pour une vue de rappel bornée et filtrée pour la sécurité ; inspectez le chemin de transcription sur disque lorsque vous avez besoin de la transcription brute complète.
`/subagents info` affiche les métadonnées d’exécution (statut, horodatages, identifiant de session, chemin de transcription, nettoyage).
Utilisez `sessions_history` pour une vue de rappel bornée et filtrée pour la sécurité ; inspectez le
chemin de transcription sur le disque lorsque vous avez besoin de la transcription brute complète.
### Comportement du lancement
`/subagents spawn` démarre un sub-agent d'arrière-plan en tant que commande utilisateur, et non comme relais interne, et envoie une mise à jour finale d'achèvement dans le chat demandeur lorsque l'exécution se termine.
`/subagents spawn` démarre un sous-agent en arrière-plan comme commande utilisateur, et non comme relais interne, et il envoie une mise à jour finale d’achèvement dans le chat du demandeur lorsque l’exécution se termine.
- La commande de lancement est non bloquante ; elle renvoie immédiatement un id d'exécution.
- À l'achèvement, le sub-agent annonce un message de résumé/résultat dans le canal de chat demandeur.
- La distribution de l'achèvement est basée sur le push. Une fois lancé, ne sondez pas `/subagents list`, `sessions_list` ou `sessions_history` en boucle juste pour attendre la fin ; inspectez le statut uniquement à la demande pour le débogage ou l'intervention.
- À l'achèvement, OpenClaw ferme au mieux les onglets/processus de navigateur suivis ouverts par cette session de sub-agent avant que le flux de nettoyage de l'annonce continue.
- Pour les lancements manuels, la distribution est résiliente :
- OpenClaw essaie d'abord une distribution `agent` directe avec une clé d'idempotence stable.
- Si la distribution directe échoue, il bascule vers le routage par file d'attente.
- Si le routage par file d'attente n'est toujours pas disponible, l'annonce est réessayée avec un court backoff exponentiel avant l'abandon final.
- La distribution de l'achèvement conserve la route du demandeur résolue :
- les routes d'achèvement liées à un fil ou à une conversation sont prioritaires lorsqu'elles sont disponibles
- si l'origine de l'achèvement ne fournit qu'un canal, OpenClaw complète la cible/le compte manquants à partir de la route résolue de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) afin que la distribution directe fonctionne quand même
- Le transfert d'achèvement vers la session demandeuse est un contexte interne généré à l'exécution (et non un texte rédigé par l'utilisateur) et inclut :
- `Result` (dernier texte visible de réponse `assistant`, sinon dernier texte assaini `tool`/`toolResult`)
- La commande de lancement n’est pas bloquante ; elle renvoie immédiatement un identifiant d’exécution.
- À la fin, le sous-agent annonce un message de résumé/résultat dans le canal de chat du demandeur.
- La livraison de fin est basée sur une poussée. Une fois lancé, ne sondez pas `/subagents list`,
`sessions_list` ou `sessions_history` en boucle juste pour attendre la fin ;
inspectez l’état uniquement à la demande pour le débogage ou l’intervention.
- À la fin, OpenClaw ferme au mieux les onglets/processus de navigateur suivis ouverts par cette session de sous-agent avant que le flux de nettoyage de l’annonce se poursuive.
- Pour les lancements manuels, la livraison est résiliente :
- OpenClaw essaie d’abord une livraison directe `agent` avec une clé d’idempotence stable.
- Si la livraison directe échoue, il bascule vers l’acheminement par file d’attente.
- Si l’acheminement par file d’attente n’est toujours pas disponible, l’annonce est retentée avec un court backoff exponentiel avant l’abandon final.
- La livraison de fin conserve la route du demandeur résolue :
- les routes de fin liées à un fil ou à une conversation sont prioritaires lorsqu’elles sont disponibles
- si l’origine de fin ne fournit qu’un canal, OpenClaw complète la cible/le compte manquant à partir de la route résolue de la session du demandeur (`lastChannel` / `lastTo` / `lastAccountId`) afin que la livraison directe fonctionne quand même
- Le transfert de fin à la session du demandeur est un contexte interne généré à l’exécution (pas un texte rédigé par l’utilisateur) et inclut :
- `Result` (dernier texte visible de réponse `assistant`, sinon dernier texte `tool`/`toolResult` nettoyé ; les exécutions terminales en échec ne réutilisent pas le texte de réponse capturé)
- `Status` (`completed successfully` / `failed` / `timed out` / `unknown`)
- des statistiques compactes d'exécution/tokens
- une instruction de distribution demandant à l'agent demandeur de reformuler avec une voix d'assistant normale (sans transmettre les métadonnées internes brutes)
- des statistiques compactes d’exécution/tokens
- une instruction de livraison indiquant à l’agent demandeur de reformuler avec une voix normale d’assistant (sans transférer les métadonnées internes brutes)
- `--model` et `--thinking` remplacent les valeurs par défaut pour cette exécution spécifique.
- Utilisez `info`/`log` pour inspecter les détails et la sortie après l'achèvement.
- `/subagents spawn` est un mode ponctuel (`mode: "run"`). Pour des sessions persistantes liées à un fil, utilisez `sessions_spawn` avec `thread: true` et `mode: "session"`.
- Pour les sessions de harnais ACP (Codex, Claude Code, Gemini CLI), utilisez `sessions_spawn` avec `runtime: "acp"` et voir [ACP Agents](/tools/acp-agents).
- Utilisez `info`/`log` pour inspecter les détails et la sortie après la fin.
- `/subagents spawn` est un mode à usage unique (`mode: "run"`). Pour des sessions persistantes liées à un fil, utilisez `sessions_spawn` avec `thread: true` et `mode: "session"`.
- Pour les sessions de harnais ACP (Codex, Claude Code, Gemini CLI), utilisez `sessions_spawn` avec `runtime: "acp"` et consultez [Agents ACP](/fr/tools/acp-agents).
Objectifs principaux :
Objectifs principaux :
- Paralléliser le travail de type « recherche / tâche longue / outil lent » sans bloquer l'exécution principale.
- Garder les sub-agents isolés par défaut (séparation de session + sandboxing optionnel).
- Rendre la surface d'outils difficile à mal utiliser : les sub-agents n'obtiennent **pas** les outils de session par défaut.
- Prendre en charge une profondeur d'imbrication configurable pour les modèles d'orchestrateur.
- Paralléliser le travail de type « recherche / tâche longue / outil lent » sans bloquer l’exécution principale.
- Garder les sous-agents isolés par défaut (séparation de session + isolation facultative).
- Rendre la surface d’outils difficile à mal utiliser : les sous-agents n’obtiennent **pas** les outils de session par défaut.
- Prendre en charge une profondeur d’imbrication configurable pour les modèles d’orchestration.
Remarque sur les coûts : chaque sub-agent a son **propre** contexte et sa propre consommation de tokens. Pour les tâches lourdes ou répétitives, définissez un modèle moins cher pour les sub-agents et gardez votre agent principal sur un modèle de meilleure qualité.
Vous pouvez configurer cela via `agents.defaults.subagents.model` ou via des remplacements par agent.
Remarque sur le coût : chaque sous-agent possède son **propre** contexte et sa propre consommation de tokens. Pour les
tâches lourdes ou répétitives, définissez un modèle moins coûteux pour les sous-agents et conservez votre agent principal sur un modèle de meilleure qualité.
Vous pouvez configurer cela via `agents.defaults.subagents.model` ou par remplacements propres à l’agent.
## Outil
Utilisez `sessions_spawn` :
Utilisez `sessions_spawn` :
- Démarre une exécution de sub-agent (`deliver: false`, lane globale : `subagent`)
- Exécute ensuite une étape d'annonce et publie la réponse d'annonce dans le canal de chat demandeur
- Modèle par défaut : hérite de l'appelant sauf si vous définissez `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` par agent) ; une valeur explicite `sessions_spawn.model` reste prioritaire.
- Niveau de réflexion par défaut : hérite de l'appelant sauf si vous définissez `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` par agent) ; une valeur explicite `sessions_spawn.thinking` reste prioritaire.
- Délai d'exécution par défaut : si `sessions_spawn.runTimeoutSeconds` est omis, OpenClaw utilise `agents.defaults.subagents.runTimeoutSeconds` lorsqu'il est défini ; sinon, il retombe à `0` (pas de délai d'expiration).
- Démarre une exécution de sous-agent (`deliver: false`, file globale : `subagent`)
- Exécute ensuite une étape d’annonce et publie la réponse d’annonce dans le canal de chat du demandeur
- Modèle par défaut : hérite de l’appelant sauf si vous définissez `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` par agent) ; un `sessions_spawn.model` explicite reste prioritaire.
- Niveau de réflexion par défaut : hérite de l’appelant sauf si vous définissez `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` par agent) ; un `sessions_spawn.thinking` explicite reste prioritaire.
- Délai d’expiration d’exécution par défaut : si `sessions_spawn.runTimeoutSeconds` est omis, OpenClaw utilise `agents.defaults.subagents.runTimeoutSeconds` s’il est défini ; sinon, il revient à `0` (pas de délai d’expiration).
Paramètres de l'outil :
Paramètres de l’outil :
- `task` (obligatoire)
- `label?` (facultatif)
- `agentId?` (facultatif ; lance sous un autre id d'agent si autorisé)
- `model?` (facultatif ; remplace le modèle du sub-agent ; les valeurs invalides sont ignorées et le sub-agent s'exécute sur le modèle par défaut avec un avertissement dans le résultat de l'outil)
- `thinking?` (facultatif ; remplace le niveau de réflexion pour l'exécution du sub-agent)
- `runTimeoutSeconds?` (par défaut : `agents.defaults.subagents.runTimeoutSeconds` lorsqu'il est défini, sinon `0` ; lorsqu'il est défini, l'exécution du sub-agent est interrompue après N secondes)
- `thread?` (par défaut `false` ; lorsqu'il vaut `true`, demande une liaison au fil du canal pour cette session de sub-agent)
- `agentId?` (facultatif ; lancer sous un autre identifiant d’agent si autorisé)
- `model?` (facultatif ; remplace le modèle du sous-agent ; les valeurs non valides sont ignorées et le sous-agent s’exécute sur le modèle par défaut avec un avertissement dans le résultat de l’outil)
- `thinking?` (facultatif ; remplace le niveau de réflexion pour l’exécution du sous-agent)
- `runTimeoutSeconds?` (par défaut, `agents.defaults.subagents.runTimeoutSeconds` lorsqu’il est défini, sinon `0` ; lorsqu’il est défini, l’exécution du sous-agent est interrompue après N secondes)
- `thread?` (par défaut `false` ; lorsque `true`, demande une liaison au fil de discussion du canal pour cette session de sous-agent)
- `mode?` (`run|session`)
- la valeur par défaut est `run`
- si `thread: true` et `mode` est omis, la valeur par défaut devient `session`
- si `thread: true` et que `mode` est omis, la valeur par défaut devient `session`
- `mode: "session"` nécessite `thread: true`
- `cleanup?` (`delete|keep`, par défaut `keep`)
- `sandbox?` (`inherit|require`, par défaut `inherit` ; `require` rejette le lancement à moins que le runtime enfant cible soit sandboxé)
- `sessions_spawn` n'accepte **pas** les paramètres de distribution de canal (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Pour la distribution, utilisez `message`/`sessions_send` depuis l'exécution lancée.
- `cleanup?` (`delete|keep`, valeur par défaut `keep`)
- `sandbox?` (`inherit|require`, valeur par défaut `inherit` ; `require` rejette le lancement sauf si l’environnement d’exécution enfant cible est isolé)
- `sessions_spawn` n’accepte **pas** les paramètres de livraison de canal (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Pour la livraison, utilisez `message`/`sessions_send` depuis l’exécution lancée.
## Sessions liées à un fil
## Sessions liées à un fil de discussion
Lorsque les liaisons de fil sont activées pour un canal, un sub-agent peut rester lié à un fil afin que les messages utilisateur de suivi dans ce fil continuent d'être routés vers la même session de sub-agent.
Lorsque les liaisons aux fils de discussion sont activées pour un canal, un sous-agent peut rester lié à un fil afin que les messages ultérieurs de l’utilisateur dans ce fil continuent d’être routés vers la même session de sous-agent.
### Canaux prenant en charge les fils
### Canaux prenant en charge les fils de discussion
- Discord (actuellement le seul canal pris en charge) : prend en charge les sessions persistantes de sub-agent liées à un fil (`sessions_spawn` avec `thread: true`), les contrôles manuels de fil (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) et les clés d'adaptateur `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` et `channels.discord.threadBindings.spawnSubagentSessions`.
- Discord (actuellement le seul canal pris en charge) : prend en charge des sessions persistantes de sous-agents liées à un fil (`sessions_spawn` avec `thread: true`), des contrôles manuels des fils (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`), et les clés d’adaptateur `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` et `channels.discord.threadBindings.spawnSubagentSessions`.
Flux rapide :
Flux rapide :
1. Lancez avec `sessions_spawn` en utilisant `thread: true` (et éventuellement `mode: "session"`).
2. OpenClaw crée ou lie un fil à cette cible de session dans le canal actif.
3. Les réponses et messages de suivi dans ce fil sont routés vers la session liée.
4. Utilisez `/session idle` pour inspecter/mettre à jour le retrait automatique du focus lié à l'inactivité et `/session max-age` pour contrôler la limite stricte.
4. Utilisez `/session idle` pour inspecter/mettre à jour le retrait automatique du focus en cas d’inactivité et `/session max-age` pour contrôler la limite stricte.
5. Utilisez `/unfocus` pour détacher manuellement.
Contrôles manuels :
Contrôles manuels :
- `/focus <target>` lie le fil en cours (ou en crée un) à une cible de sub-agent/session.
- `/focus <target>` lie le fil en cours (ou en crée un) à une cible de sous-agent/session.
- `/unfocus` supprime la liaison pour le fil actuellement lié.
- `/agents` liste les exécutions actives et l'état de liaison (`thread:<id>` ou `unbound`).
- `/session idle` et `/session max-age` ne fonctionnent que pour les fils liés focalisés.
- `/agents` liste les exécutions actives et l’état de liaison (`thread:<id>` ou `unbound`).
- `/session idle` et `/session max-age` fonctionnent uniquement pour les fils liés ayant le focus.
Commutateurs de configuration :
Commutateurs de configuration :
- Valeur par défaut globale : `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
- Le remplacement de canal et les clés de liaison automatique au lancement sont spécifiques à l'adaptateur. Voir **Canaux prenant en charge les fils** ci-dessus.
- Valeur par défaut globale : `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
- Les remplacements par canal et les clés de liaison automatique au lancement sont spécifiques à l’adaptateur. Voir **Canaux prenant en charge les fils de discussion** ci-dessus.
Voir [Référence de configuration](/fr/gateway/configuration-reference) et [Commandes slash](/tools/slash-commands) pour les détails actuels des adaptateurs.
Consultez [Référence de configuration](/fr/gateway/configuration-reference) et [Commandes slash](/fr/tools/slash-commands) pour les détails actuels de l’adaptateur.
Allow-list :
Liste d’autorisation :
- `agents.list[].subagents.allowAgents` : liste des ids d'agents qui peuvent être ciblés via `agentId` (`["*"]` pour autoriser n'importe lequel). Par défaut : seulement l'agent demandeur.
- `agents.defaults.subagents.allowAgents` : allow-list d'agents cibles par défaut utilisée lorsque l'agent demandeur ne définit pas sa propre valeur `subagents.allowAgents`.
- Garde d'héritage du sandbox : si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles qui s'exécuteraient sans sandbox.
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId` : lorsque vrai, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite du profil). Par défaut : false.
- `agents.list[].subagents.allowAgents` : liste des identifiants d’agents pouvant être ciblés via `agentId` (`["*"]` pour autoriser n’importe lequel). Par défaut : uniquement l’agent demandeur.
- `agents.defaults.subagents.allowAgents` : liste d’autorisation par défaut des agents cibles utilisée lorsque l’agent demandeur ne définit pas sa propre valeur `subagents.allowAgents`.
- Garde de l’héritage de l’isolation : si la session du demandeur est isolée, `sessions_spawn` rejette les cibles qui s’exécuteraient sans isolation.
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId` : lorsque cette valeur est true, bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite du profil). Par défaut : false.
Découverte :
Découverte :
- Utilisez `agents_list` pour voir quels ids d'agents sont actuellement autorisés pour `sessions_spawn`.
- Utilisez `agents_list` pour voir quels identifiants d’agents sont actuellement autorisés pour `sessions_spawn`.
Archivage automatique :
Archivage automatique :
- Les sessions de sub-agent sont automatiquement archivées après `agents.defaults.subagents.archiveAfterMinutes` (par défaut : 60).
- L'archivage utilise `sessions.delete` et renomme la transcription en `*.deleted.<timestamp>` (même dossier).
- `cleanup: "delete"` archive immédiatement après l'annonce (tout en conservant la transcription via renommage).
- L'archivage automatique est au mieux ; les temporisateurs en attente sont perdus si la gateway redémarre.
- `runTimeoutSeconds` ne déclenche **pas** d'archivage automatique ; il arrête seulement l'exécution. La session reste jusqu'à l'archivage automatique.
- L'archivage automatique s'applique de la même manière aux sessions de profondeur 1 et 2.
- Le nettoyage du navigateur est distinct du nettoyage d'archivage : les onglets/processus de navigateur suivis sont fermés au mieux lorsque l'exécution se termine, même si l'enregistrement de transcription/session est conservé.
- Les sessions de sous-agents sont automatiquement archivées après `agents.defaults.subagents.archiveAfterMinutes` (par défaut : 60).
- L’archivage utilise `sessions.delete` et renomme la transcription en `*.deleted.<timestamp>` (dans le même dossier).
- `cleanup: "delete"` archive immédiatement après l’annonce (tout en conservant la transcription via renommage).
- L’archivage automatique est fait au mieux ; les temporisateurs en attente sont perdus si la Gateway redémarre.
- `runTimeoutSeconds` ne déclenche **pas** l’archivage automatique ; il arrête uniquement l’exécution. La session reste jusqu’à l’archivage automatique.
- L’archivage automatique s’applique de la même manière aux sessions de profondeur 1 et de profondeur 2.
- Le nettoyage du navigateur est distinct de l’archivage : les onglets/processus de navigateur suivis sont fermés au mieux à la fin de l’exécution, même si l’enregistrement de session/transcription est conservé.
## Sub-agents imbriqués
## Sous-agents imbriqués
Par défaut, les sub-agents ne peuvent pas lancer leurs propres sub-agents (`maxSpawnDepth: 1`). Vous pouvez activer un niveau d'imbrication en définissant `maxSpawnDepth: 2`, ce qui autorise le **modèle d'orchestrateur** : principal → sub-agent orchestrateur → sub-sub-agents workers.
Par défaut, les sous-agents ne peuvent pas lancer leurs propres sous-agents (`maxSpawnDepth: 1`). Vous pouvez activer un niveau d’imbrication en définissant `maxSpawnDepth: 2`, ce qui autorise le **modèle d’orchestration** : principal → sous-agent orchestrateur → sous-sous-agents workers.
### Comment l'activer
### Comment l’activer
```json5
{
agents: {
defaults: {
subagents: {
maxSpawnDepth: 2, // autorise les sub-agents à lancer des enfants (par défaut : 1)
maxChildrenPerAgent: 5, // nb max d'enfants actifs par session d'agent (par défaut : 5)
maxConcurrent: 8, // plafond global de concurrence de la lane (par défaut : 8)
runTimeoutSeconds: 900, // délai d'expiration par défaut pour sessions_spawn lorsqu'il est omis (0 = pas de délai)
maxSpawnDepth: 2, // autoriser les sous-agents à lancer des enfants (par défaut : 1)
maxChildrenPerAgent: 5, // nombre maximal d’enfants actifs par session d’agent (par défaut : 5)
maxConcurrent: 8, // limite globale de concurrence de la file (par défaut : 8)
runTimeoutSeconds: 900, // délai d’expiration par défaut pour sessions_spawn lorsqu’il est omis (0 = aucun délai)
},
},
},
@ -179,116 +183,126 @@ Par défaut, les sub-agents ne peuvent pas lancer leurs propres sub-agents (`max
### Niveaux de profondeur
| Depth | Forme de clé de session | Rôle | Peut lancer ? |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agent principal | Toujours |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agent (orchestrateur si profondeur 2 autorisée) | Seulement si `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agent (worker feuille) | Jamais |
| Profondeur | Forme de clé de session | Rôle | Peut lancer ? |
| ---------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agent principal | Toujours |
| 1 | `agent:<id>:subagent:<uuid>` | Sous-agent (orchestrateur si profondeur 2 autorisée) | Uniquement si `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sous-sous-agent (worker terminal) | Jamais |
### Chaîne d'annonce
### Chaîne d’annonce
Les résultats remontent la chaîne :
Les résultats remontent dans la chaîne :
1. Le worker de profondeur 2 se termine → annonce à son parent (orchestrateur de profondeur 1)
2. L'orchestrateur de profondeur 1 reçoit l'annonce, synthétise les résultats, se termine → annonce au principal
3. L'agent principal reçoit l'annonce et la distribue à l'utilisateur
1. Le worker de profondeur 2 termine → annonce à son parent (orchestrateur de profondeur 1)
2. L’orchestrateur de profondeur 1 reçoit l’annonce, synthétise les résultats, termine → annonce au principal
3. L’agent principal reçoit l’annonce et la remet à l’utilisateur
Chaque niveau ne voit que les annonces de ses enfants directs.
Consignes opérationnelles :
Conseils opérationnels :
- Démarrez le travail enfant une seule fois et attendez les événements d'achèvement au lieu de construire des boucles de sondage autour de `sessions_list`, `sessions_history`, `/subagents list` ou des commandes `exec` avec sommeil.
- Si un événement d'achèvement enfant arrive après que vous avez déjà envoyé la réponse finale, le bon suivi est le jeton silencieux exact `NO_REPLY` / `no_reply`.
- Démarrez le travail enfant une fois et attendez les événements de fin au lieu de construire des boucles de sondage
autour de `sessions_list`, `sessions_history`, `/subagents list` ou
des commandes `exec` avec temporisation.
- Si un événement de fin d’enfant arrive après que vous avez déjà envoyé la réponse finale,
le suivi correct est le jeton silencieux exact `NO_REPLY` / `no_reply`.
### Politique d'outils par profondeur
### Politique des outils par profondeur
- Le rôle et la portée de contrôle sont écrits dans les métadonnées de session au moment du lancement. Cela évite que des clés de session plates ou restaurées ne récupèrent accidentellement des privilèges d'orchestrateur.
- **Profondeur 1 (orchestrateur, lorsque `maxSpawnDepth >= 2`)** : obtient `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` afin de pouvoir gérer ses enfants. Les autres outils de session/système restent refusés.
- **Profondeur 1 (feuille, lorsque `maxSpawnDepth == 1`)** : aucun outil de session (comportement par défaut actuel).
- **Profondeur 2 (worker feuille)** : aucun outil de session — `sessions_spawn` est toujours refusé en profondeur 2. Ne peut pas lancer d'autres enfants.
- Le rôle et la portée de contrôle sont écrits dans les métadonnées de la session au moment du lancement. Cela empêche les clés de session aplaties ou restaurées de retrouver accidentellement des privilèges d’orchestrateur.
- **Profondeur 1 (orchestrateur, lorsque `maxSpawnDepth >= 2`)** : obtient `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` afin de pouvoir gérer ses enfants. Les autres outils de session/système restent refusés.
- **Profondeur 1 (terminal, lorsque `maxSpawnDepth == 1`)** : aucun outil de session (comportement par défaut actuel).
- **Profondeur 2 (worker terminal)** : aucun outil de session — `sessions_spawn` est toujours refusé à la profondeur 2. Impossible de lancer d’autres enfants.
### Limite de lancement par agent
Chaque session d'agent (à n'importe quelle profondeur) peut avoir au plus `maxChildrenPerAgent` (par défaut : 5) enfants actifs à la fois. Cela empêche une prolifération incontrôlée depuis un seul orchestrateur.
Chaque session d’agent (à n’importe quelle profondeur) peut avoir au plus `maxChildrenPerAgent` (par défaut : 5) enfants actifs en même temps. Cela évite une multiplication incontrôlée à partir d’un seul orchestrateur.
### Arrêt en cascade
L'arrêt d'un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants de profondeur 2 :
L’arrêt d’un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants de profondeur 2 :
- `/stop` dans le chat principal arrête tous les agents de profondeur 1 et cascade vers leurs enfants de profondeur 2.
- `/subagents kill <id>` arrête un sub-agent spécifique et cascade vers ses enfants.
- `/subagents kill all` arrête tous les sub-agents du demandeur et cascade.
- `/stop` dans le chat principal arrête tous les agents de profondeur 1 et se propage à leurs enfants de profondeur 2.
- `/subagents kill <id>` arrête un sous-agent spécifique et se propage à ses enfants.
- `/subagents kill all` arrête tous les sous-agents du demandeur et se propage.
## Authentification
L'authentification du sub-agent est résolue par **id d'agent**, et non par type de session :
L’authentification des sous-agents est résolue par **identifiant d’agent**, et non par type de session :
- La clé de session du sub-agent est `agent:<agentId>:subagent:<uuid>`.
- Le stockage d'authentification est chargé depuis le `agentDir` de cet agent.
- Les profils d'authentification de l'agent principal sont fusionnés comme **secours** ; les profils de l'agent remplacent les profils principaux en cas de conflit.
- La clé de session du sous-agent est `agent:<agentId>:subagent:<uuid>`.
- Le magasin d’authentification est chargé depuis le `agentDir` de cet agent.
- Les profils d’authentification de l’agent principal sont fusionnés comme **solution de secours** ; les profils de l’agent remplacent ceux du principal en cas de conflit.
Remarque : la fusion est additive, donc les profils principaux sont toujours disponibles comme secours. Une authentification entièrement isolée par agent n'est pas encore prise en charge.
Remarque : la fusion est additive, donc les profils du principal sont toujours disponibles comme solutions de secours. Une authentification entièrement isolée par agent n’est pas encore prise en charge.
## Annonce
Les sub-agents remontent leurs résultats via une étape d'annonce :
Les sous-agents font remonter l’information via une étape d’annonce :
- L'étape d'annonce s'exécute dans la session du sub-agent (pas dans la session demandeuse).
- Si le sub-agent répond exactement `ANNOUNCE_SKIP`, rien n'est publié.
- Si le dernier texte assistant est exactement le jeton silencieux `NO_REPLY` / `no_reply`, la sortie d'annonce est supprimée même si une progression visible antérieure existait.
- Sinon, la distribution dépend de la profondeur du demandeur :
- les sessions demandeuses de niveau supérieur utilisent un appel `agent` de suivi avec distribution externe (`deliver=true`)
- les sessions demandeuses de sub-agent imbriquées reçoivent une injection de suivi interne (`deliver=false`) afin que l'orchestrateur puisse synthétiser les résultats enfants en session
- si une session demandeuse de sub-agent imbriquée a disparu, OpenClaw bascule vers le demandeur de cette session lorsque disponible
- Pour les sessions demandeuses de niveau supérieur, la distribution directe en mode achèvement résout d'abord toute route liée à une conversation/un fil et tout remplacement de hook, puis complète les champs cibles de canal manquants à partir de la route stockée de la session demandeuse. Cela maintient les achèvements dans le bon chat/sujet même lorsque l'origine de l'achèvement n'identifie que le canal.
- L'agrégation des achèvements enfants est limitée à l'exécution demandeuse actuelle lors de la construction des constats d'achèvement imbriqués, empêchant que d'anciennes sorties d'enfants d'exécutions précédentes ne fuient dans l'annonce actuelle.
- Les réponses d'annonce préservent le routage de fil/sujet lorsque disponible sur les adaptateurs de canal.
- Le contexte d'annonce est normalisé en un bloc d'événement interne stable :
- L’étape d’annonce s’exécute dans la session du sous-agent (et non dans la session du demandeur).
- Si le sous-agent répond exactement `ANNOUNCE_SKIP`, rien n’est publié.
- Si le dernier texte de l’assistant est le jeton silencieux exact `NO_REPLY` / `no_reply`,
la sortie d’annonce est supprimée même si une progression visible antérieure existait.
- Sinon, la livraison dépend de la profondeur du demandeur :
- les sessions demandeuses de niveau supérieur utilisent un appel de suivi `agent` avec livraison externe (`deliver=true`)
- les sessions sous-agent demandeuses imbriquées reçoivent une injection de suivi interne (`deliver=false`) afin que l’orchestrateur puisse synthétiser les résultats enfants dans la session
- si une session sous-agent demandeuse imbriquée a disparu, OpenClaw revient vers le demandeur de cette session lorsque c’est possible
- Pour les sessions demandeuses de niveau supérieur, la livraison directe en mode achèvement résout d’abord toute route liée de conversation/fil et toute substitution de hook, puis complète les champs de cible de canal manquants à partir de la route stockée de la session du demandeur. Cela maintient les achèvements dans le bon chat/sujet même lorsque l’origine de l’achèvement n’identifie que le canal.
- L’agrégation des achèvements enfants est limitée à l’exécution demandeuse en cours lors de la construction des résultats d’achèvement imbriqués, empêchant que des sorties d’enfants obsolètes d’exécutions précédentes ne fuitent dans l’annonce en cours.
- Les réponses d’annonce conservent le routage de fil/sujet lorsqu’il est disponible sur les adaptateurs de canal.
- Le contexte d’annonce est normalisé en un bloc d’événement interne stable :
- source (`subagent` ou `cron`)
- clé/id de session enfant
- type d'annonce + étiquette de tâche
- ligne d'état dérivée du résultat d'exécution (`success`, `error`, `timeout` ou `unknown`)
- contenu du résultat sélectionné à partir du dernier texte assistant visible, sinon dernier texte assaini `tool`/`toolResult`
- type d’annonce + étiquette de tâche
- ligne d’état dérivée du résultat d’exécution (`success`, `error`, `timeout` ou `unknown`)
- contenu du résultat sélectionné à partir du dernier texte visible de l’assistant, sinon à partir du dernier texte `tool`/`toolResult` nettoyé ; les exécutions terminales en échec signalent un statut d’échec sans rejouer le texte de réponse capturé
- une instruction de suivi décrivant quand répondre ou rester silencieux
- `Status` n'est pas déduit de la sortie du modèle ; il provient des signaux de résultat d'exécution.
- En cas de délai d'expiration, si l'enfant n'est allé que jusqu'aux appels d'outil, l'annonce peut condenser cet historique en un court résumé de progression partielle au lieu de rejouer la sortie d'outil brute.
- `Status` n’est pas déduit à partir de la sortie du modèle ; il provient des signaux de résultat d’exécution.
- En cas de délai d’expiration, si l’enfant n’a effectué que des appels d’outils, l’annonce peut réduire cet historique à un court résumé de progression partielle au lieu de rejouer la sortie brute des outils.
Les charges utiles d'annonce incluent une ligne de statistiques à la fin (même lorsqu'elles sont enveloppées) :
Les charges utiles d’annonce incluent une ligne de statistiques à la fin (même lorsqu’elles sont encapsulées) :
- Runtime (par ex. `runtime 5m12s`)
- Utilisation de tokens (entrée/sortie/total)
- Temps d’exécution (par exemple, `runtime 5m12s`)
- Utilisation des tokens (entrée/sortie/total)
- Coût estimé lorsque la tarification du modèle est configurée (`models.providers.*.models[].cost`)
- `sessionKey`, `sessionId` et chemin de transcription (afin que l'agent principal puisse récupérer l'historique via `sessions_history` ou inspecter le fichier sur disque)
- Les métadonnées internes sont destinées uniquement à l'orchestration ; les réponses visibles par l'utilisateur doivent être réécrites avec une voix d'assistant normale.
- `sessionKey`, `sessionId` et chemin de transcription (afin que l’agent principal puisse récupérer l’historique via `sessions_history` ou inspecter le fichier sur le disque)
- Les métadonnées internes sont destinées uniquement à l’orchestration ; les réponses destinées à l’utilisateur doivent être réécrites avec une voix normale d’assistant.
`sessions_history` est la voie d'orchestration la plus sûre :
`sessions_history` est le chemin d’orchestration le plus sûr :
- le rappel assistant est d'abord normalisé :
- le rappel assistant est d’abord normalisé :
- les balises de réflexion sont supprimées
- les blocs d'échafaudage `<relevant-memories>` / `<relevant_memories>` sont supprimés
- les blocs de charge utile XML d'appel d'outil en texte brut tels que `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` et `<function_calls>...</function_calls>` sont supprimés, y compris les charges utiles tronquées qui ne se ferment jamais proprement
- l'échafaudage dégradé d'appel d'outil/résultat et les marqueurs de contexte historique sont supprimés
- les jetons de contrôle de modèle divulgués comme `<|assistant|>`, d'autres jetons ASCII `<|...|>` et les variantes pleine largeur `<｜...｜>` sont supprimés
- le XML d'appel d'outil MiniMax mal formé est supprimé
- le texte de type identifiant/token est caviardé
- les blocs d’échafaudage `<relevant-memories>` / `<relevant_memories>` sont supprimés
- les blocs de charge utile XML d’appel d’outil en texte brut tels que `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` et
`<function_calls>...</function_calls>` sont supprimés, y compris les charges
tronquées qui ne se ferment jamais correctement
- l’échafaudage d’appel/résultat d’outil rétrogradé et les marqueurs de contexte historique sont supprimés
- les jetons de contrôle du modèle divulgués tels que `<|assistant|>`, les autres
jetons ASCII `<|...|>` et les variantes pleine largeur `<｜...｜>` sont supprimés
- le XML mal formé d’appel d’outil MiniMax est supprimé
- le texte de type identifiant/token d’accès est masqué
- les blocs longs peuvent être tronqués
- les historiques très volumineux peuvent supprimer des lignes plus anciennes ou remplacer une ligne trop volumineuse par `[sessions_history omitted: message too large]`
- l'inspection brute de la transcription sur disque reste le recours lorsque vous avez besoin de la transcription complète octet par octet
- les historiques très volumineux peuvent supprimer les lignes les plus anciennes ou remplacer une ligne surdimensionnée par
`[sessions_history omitted: message too large]`
- l’inspection de la transcription brute sur disque reste la solution de secours lorsque vous avez besoin de la transcription complète octet par octet
## Politique d'outils (outils des sub-agents)
## Politique des outils (outils de sous-agents)
Par défaut, les sub-agents obtiennent **tous les outils sauf les outils de session** et les outils système :
Par défaut, les sous-agents obtiennent **tous les outils sauf les outils de session** et les outils système :
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
`sessions_history` reste ici aussi une vue de rappel bornée et assainie ; ce n'est pas un dump brut de transcription.
`sessions_history` reste ici aussi une vue de rappel bornée et nettoyée ; ce n’est pas
un dump brut de transcription.
Lorsque `maxSpawnDepth >= 2`, les sub-agents orchestrateurs de profondeur 1 reçoivent en plus `sessions_spawn`, `subagents`, `sessions_list` et `sessions_history` afin de pouvoir gérer leurs enfants.
Lorsque `maxSpawnDepth >= 2`, les sous-agents orchestrateurs de profondeur 1 reçoivent en plus `sessions_spawn`, `subagents`, `sessions_list` et `sessions_history` afin de pouvoir gérer leurs enfants.
Remplacez via la configuration :
Remplacement via la configuration :
```json5
{
@ -304,7 +318,7 @@ Remplacez via la configuration :
tools: {
// deny est prioritaire
deny: ["gateway", "cron"],
// si allow est défini, cela devient une allow-list stricte (deny reste prioritaire)
// si allow est défini, cela devient une liste d’autorisation uniquement (deny reste prioritaire)
// allow: ["read", "exec", "process"]
},
},
@ -314,21 +328,21 @@ Remplacez via la configuration :
## Concurrence
Les sub-agents utilisent une lane de file dédiée dans le processus :
Les sous-agents utilisent une file dédiée en cours de processus :
- Nom de la lane : `subagent`
- Concurrence : `agents.defaults.subagents.maxConcurrent` (par défaut `8`)
- Nom de la file : `subagent`
- Concurrence : `agents.defaults.subagents.maxConcurrent` (par défaut `8`)
## Arrêt
- L'envoi de `/stop` dans le chat demandeur interrompt la session demandeuse et arrête toutes les exécutions actives de sub-agent lancées depuis celle-ci, avec cascade vers les enfants imbriqués.
- `/subagents kill <id>` arrête un sub-agent spécifique et cascade vers ses enfants.
- L’envoi de `/stop` dans le chat du demandeur interrompt la session du demandeur et arrête toutes les exécutions actives de sous-agents lancées depuis celle-ci, avec propagation aux enfants imbriqués.
- `/subagents kill <id>` arrête un sous-agent spécifique et se propage à ses enfants.
## Limites
## Limitations
- L'annonce des sub-agents est **au mieux**. Si la gateway redémarre, le travail en attente de « retour d'annonce » est perdu.
- Les sub-agents partagent toujours les mêmes ressources de processus gateway ; traitez `maxConcurrent` comme une soupape de sécurité.
- `sessions_spawn` est toujours non bloquant : il renvoie immédiatement `{ status: "accepted", runId, childSessionKey }`.
- Le contexte des sub-agents injecte uniquement `AGENTS.md` + `TOOLS.md` (pas de `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`).
- La profondeur maximale d'imbrication est 5 (plage `maxSpawnDepth` : 1–5). La profondeur 2 est recommandée pour la plupart des cas d'usage.
- `maxChildrenPerAgent` limite le nombre d'enfants actifs par session (par défaut : 5, plage : 1–20).
- L’annonce des sous-agents est **faite au mieux**. Si la Gateway redémarre, le travail en attente de « retour d’annonce » est perdu.
- Les sous-agents partagent toujours les mêmes ressources de processus Gateway ; considérez `maxConcurrent` comme une soupape de sécurité.
- `sessions_spawn` est toujours non bloquant : il renvoie immédiatement `{ status: "accepted", runId, childSessionKey }`.
- Le contexte du sous-agent n’injecte que `AGENTS.md` + `TOOLS.md` (pas de `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`).
- La profondeur d’imbrication maximale est de 5 (plage de `maxSpawnDepth` : 1–5). La profondeur 2 est recommandée pour la plupart des cas d’usage.
- `maxChildrenPerAgent` limite le nombre d’enfants actifs par session (par défaut : 5, plage : 1–20).

146
docs/fr/tools/thinking.md
View File

@ -1,131 +1,131 @@
---
read_when:
- Ajustement de l’analyse ou des valeurs par défaut des directives de réflexion, du mode rapide ou du mode verbeux
- Ajuster l’analyse ou les valeurs par défaut des directives de réflexion, de mode rapide ou de verbosité
summary: Syntaxe des directives pour /think, /fast, /verbose, /trace et la visibilité du raisonnement
title: Niveaux de réflexion
x-i18n:
generated_at: "2026-04-21T13:37:06Z"
generated_at: "2026-04-21T19:21:02Z"
model: gpt-5.4
provider: openai
source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886
source_hash: c77f6f1318c428bbd21725ea5f32f8088506a10cbbf5b5cbca5973c72a5a81f9
source_path: tools/thinking.md
workflow: 15
---
# Niveaux de réflexion (directives `/think`)
# Niveaux de réflexion (directives /think)
## Ce que cela fait
- Directive en ligne dans tout corps entrant : `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Niveaux (alias) : `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → « think »
- low → « think hard »
- medium → « think harder »
- high → « ultrathink » (budget max)
- xhigh → « ultrathink+ » (effort GPT-5.2 + modèles Codex et Anthropic Claude Opus 4.7)
- Directive en ligne dans tout corps entrant : `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Niveaux (alias) : `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → « think »
- low → « think hard »
- medium → « think harder »
- high → « ultrathink » (budget maximal)
- xhigh → « ultrathink+ » (effort GPT-5.2 + modèles Codex et Anthropic Claude Opus 4.7)
- adaptive → réflexion adaptative gérée par le fournisseur (prise en charge pour Claude 4.6 sur Anthropic/Bedrock et Anthropic Claude Opus 4.7)
- max → raisonnement maximal du fournisseur (actuellement Anthropic Claude Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high` et `extra_high` correspondent à `xhigh`.
- `highest` correspond à `high`.
- Remarques sur les fournisseurs :
- Les menus et sélecteurs de réflexion sont pilotés par les profils fournisseur. Les Plugins fournisseur déclarent l’ensemble exact des niveaux pour le modèle sélectionné, y compris des libellés tels que le binaire `on`.
- `adaptive`, `xhigh` et `max` ne sont annoncés que pour les profils fournisseur/modèle qui les prennent en charge. Les directives typées pour des niveaux non pris en charge sont rejetées avec les options valides de ce modèle.
- Les niveaux non pris en charge déjà stockés, y compris les anciennes valeurs `max` après un changement de modèle, sont remappés vers le plus grand niveau pris en charge pour le modèle sélectionné.
- Notes sur les fournisseurs :
- Les menus et sélecteurs de réflexion sont pilotés par le profil du fournisseur. Les plugins de fournisseur déclarent l’ensemble exact de niveaux pour le modèle sélectionné, y compris des libellés tels que le binaire `on`.
- `adaptive`, `xhigh` et `max` ne sont annoncés que pour les profils fournisseur/modèle qui les prennent en charge. Les directives saisies pour des niveaux non pris en charge sont rejetées avec les options valides pour ce modèle.
- Les niveaux non pris en charge déjà stockés sont remappés selon le rang du profil fournisseur. `adaptive` se replie sur `medium` pour les modèles non adaptatifs, tandis que `xhigh` et `max` se replient sur le plus grand niveau pris en charge autre que `off` pour le modèle sélectionné.
- Les modèles Anthropic Claude 4.6 utilisent `adaptive` par défaut lorsqu’aucun niveau de réflexion explicite n’est défini.
- Anthropic Claude Opus 4.7 n’utilise pas la réflexion adaptative par défaut. Son effort API par défaut reste géré par le fournisseur sauf si vous définissez explicitement un niveau de réflexion.
- Anthropic Claude Opus 4.7 mappe `/think xhigh` vers une réflexion adaptative plus `output_config.effort: "xhigh"`, car `/think` est une directive de réflexion et `xhigh` est le réglage d’effort d’Opus 4.7.
- Anthropic Claude Opus 4.7 expose aussi `/think max` ; il mappe vers le même chemin d’effort maximal géré par le fournisseur.
- Les modèles OpenAI GPT mappent `/think` via la prise en charge d’effort de l’API Responses propre au modèle. `/think off` envoie `reasoning.effort: "none"` uniquement lorsque le modèle cible le prend en charge ; sinon OpenClaw omet la charge utile de raisonnement désactivé au lieu d’envoyer une valeur non prise en charge.
- MiniMax (`minimax/*`) sur le chemin de streaming compatible Anthropic utilise par défaut `thinking: { type: "disabled" }` sauf si vous définissez explicitement la réflexion dans les paramètres du modèle ou de la requête. Cela évite les deltas `reasoning_content` fuités depuis le format de flux Anthropic non natif de MiniMax.
- Z.AI (`zai/*`) ne prend en charge que la réflexion binaire (`on`/`off`). Tout niveau différent de `off` est traité comme `on` (mappé vers `low`).
- Moonshot (`moonshot/*`) mappe `/think off` vers `thinking: { type: "disabled" }` et tout niveau différent de `off` vers `thinking: { type: "enabled" }`. Lorsque la réflexion est activée, Moonshot n’accepte que `tool_choice` `auto|none` ; OpenClaw normalise les valeurs incompatibles vers `auto`.
- Anthropic Claude Opus 4.7 n’utilise pas la réflexion adaptative par défaut. Sa valeur d’effort API par défaut reste gérée par le fournisseur tant que vous ne définissez pas explicitement un niveau de réflexion.
- Anthropic Claude Opus 4.7 mappe `/think xhigh` vers une réflexion adaptative plus `output_config.effort: "xhigh"`, car `/think` est une directive de réflexion et `xhigh` est le paramètre d’effort d’Opus 4.7.
- Anthropic Claude Opus 4.7 expose également `/think max` ; cela correspond au même chemin d’effort maximal géré par le fournisseur.
- Les modèles OpenAI GPT mappent `/think` via la prise en charge de l’effort spécifique au modèle dans l’API Responses. `/think off` envoie `reasoning.effort: "none"` uniquement lorsque le modèle cible le prend en charge ; sinon OpenClaw omet la charge utile de raisonnement désactivé au lieu d’envoyer une valeur non prise en charge.
- MiniMax (`minimax/*`) sur le chemin de streaming compatible Anthropic utilise par défaut `thinking: { type: "disabled" }` sauf si vous définissez explicitement la réflexion dans les paramètres de modèle ou de requête. Cela évite les deltas `reasoning_content` divulgués par le format de flux Anthropic non natif de MiniMax.
- Z.AI (`zai/*`) ne prend en charge qu’une réflexion binaire (`on`/`off`). Tout niveau autre que `off` est traité comme `on` (mappé à `low`).
- Moonshot (`moonshot/*`) mappe `/think off` vers `thinking: { type: "disabled" }` et tout niveau autre que `off` vers `thinking: { type: "enabled" }`. Lorsque la réflexion est activée, Moonshot n’accepte que `tool_choice` `auto|none` ; OpenClaw normalise les valeurs incompatibles en `auto`.
## Ordre de résolution
1. Directive en ligne dans le message (s’applique uniquement à ce message).
2. Surcharge de session (définie en envoyant un message contenant uniquement une directive).
2. Remplacement de session (défini en envoyant un message ne contenant qu’une directive).
3. Valeur par défaut par agent (`agents.list[].thinkingDefault` dans la configuration).
4. Valeur par défaut globale (`agents.defaults.thinkingDefault` dans la configuration).
5. Repli : valeur par défaut déclarée par le fournisseur lorsqu’elle existe, `low` pour les autres modèles du catalogue marqués comme capables de raisonner, sinon `off`.
5. Repli : valeur par défaut déclarée par le fournisseur lorsqu’elle est disponible, `low` pour les autres modèles du catalogue marqués comme capables de raisonner, `off` sinon.
## Définir une valeur par défaut de session
- Envoyez un message qui est **uniquement** la directive (espaces autorisés), par exemple `/think:medium` ou `/t high`.
- Cela persiste pour la session en cours (par expéditeur par défaut) ; effacé par `/think:off` ou par la réinitialisation après inactivité de la session.
- Envoyez un message contenant **uniquement** la directive (espaces autorisés), par exemple `/think:medium` ou `/t high`.
- Cela reste actif pour la session en cours (par expéditeur par défaut) ; effacé par `/think:off` ou par la réinitialisation d’inactivité de la session.
- Une réponse de confirmation est envoyée (`Thinking level set to high.` / `Thinking disabled.`). Si le niveau est invalide (par exemple `/thinking big`), la commande est rejetée avec une indication et l’état de la session reste inchangé.
- Envoyez `/think` (ou `/think:`) sans argument pour voir le niveau de réflexion actuel.
## Application par agent
- **Pi embarqué** : le niveau résolu est transmis au runtime de l’agent Pi en processus.
- **Pi intégré** : le niveau résolu est transmis au runtime d’agent Pi en cours de processus.
## Mode rapide (/fast)
- Niveaux : `on|off`.
- Un message contenant uniquement une directive active une surcharge de mode rapide de session et répond `Fast mode enabled.` / `Fast mode disabled.`.
- Niveaux : `on|off`.
- Un message ne contenant qu’une directive active/désactive un remplacement de mode rapide de session et répond `Fast mode enabled.` / `Fast mode disabled.`.
- Envoyez `/fast` (ou `/fast status`) sans mode pour voir l’état effectif actuel du mode rapide.
- OpenClaw résout le mode rapide dans cet ordre :
1. `/fast on|off` en ligne / contenant uniquement une directive
2. Surcharge de session
- OpenClaw résout le mode rapide dans cet ordre :
1. `/fast on|off` en ligne / en directive seule
2. Remplacement de session
3. Valeur par défaut par agent (`agents.list[].fastModeDefault`)
4. Configuration par modèle : `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Repli : `off`
- Pour `openai/*`, le mode rapide se mappe au traitement prioritaire OpenAI en envoyant `service_tier=priority` sur les requêtes Responses prises en charge.
- Pour `openai-codex/*`, le mode rapide envoie le même indicateur `service_tier=priority` sur les réponses Codex. OpenClaw conserve une seule bascule `/fast` partagée entre les deux chemins d’authentification.
- Pour les requêtes publiques directes `anthropic/*`, y compris le trafic authentifié par OAuth envoyé à `api.anthropic.com`, le mode rapide se mappe aux niveaux de service Anthropic : `/fast on` définit `service_tier=auto`, `/fast off` définit `service_tier=standard_only`.
4. Configuration par modèle : `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Repli : `off`
- Pour `openai/*`, le mode rapide correspond au traitement prioritaire OpenAI en envoyant `service_tier=priority` sur les requêtes Responses prises en charge.
- Pour `openai-codex/*`, le mode rapide envoie le même indicateur `service_tier=priority` sur Codex Responses. OpenClaw conserve un seul basculement `/fast` partagé entre les deux chemins d’authentification.
- Pour les requêtes directes publiques `anthropic/*`, y compris le trafic authentifié par OAuth envoyé à `api.anthropic.com`, le mode rapide correspond aux niveaux de service Anthropic : `/fast on` définit `service_tier=auto`, `/fast off` définit `service_tier=standard_only`.
- Pour `minimax/*` sur le chemin compatible Anthropic, `/fast on` (ou `params.fastMode: true`) réécrit `MiniMax-M2.7` en `MiniMax-M2.7-highspeed`.
- Les paramètres de modèle Anthropic explicites `serviceTier` / `service_tier` remplacent la valeur par défaut du mode rapide lorsque les deux sont définis. OpenClaw continue toutefois d’ignorer l’injection de niveau de service Anthropic pour les URL de base proxy non Anthropic.
- Les paramètres de modèle explicites Anthropic `serviceTier` / `service_tier` remplacent la valeur par défaut du mode rapide lorsque les deux sont définis. OpenClaw continue d’ignorer l’injection de niveau de service Anthropic pour les URL de base proxy non Anthropic.
## Directives verbeuses (/verbose ou /v)
## Directives de verbosité (/verbose ou /v)
- Niveaux : `on` (minimal) | `full` | `off` (par défaut).
- Un message contenant uniquement une directive active le mode verbeux de session et répond `Verbose logging enabled.` / `Verbose logging disabled.` ; les niveaux invalides renvoient une indication sans modifier l’état.
- `/verbose off` stocke une surcharge explicite de session ; effacez-la via l’interface Sessions en choisissant `inherit`.
- Une directive en ligne n’affecte que ce message ; les valeurs par défaut de session/globales s’appliquent sinon.
- Envoyez `/verbose` (ou `/verbose:`) sans argument pour voir le niveau verbeux actuel.
- Quand le mode verbeux est activé, les agents qui émettent des résultats d’outils structurés (Pi, autres agents JSON) renvoient chaque appel d’outil comme son propre message de métadonnées uniquement, préfixé par `<emoji> <tool-name>: <arg>` lorsque disponible (chemin/commande). Ces résumés d’outils sont envoyés dès que chaque outil démarre (bulles séparées), pas sous forme de deltas de streaming.
- Les résumés d’échec d’outil restent visibles en mode normal, mais les suffixes de détail d’erreur bruts sont masqués sauf si le mode verbeux est `on` ou `full`.
- Quand le mode verbeux est `full`, les sorties d’outil sont également transmises après achèvement (bulle séparée, tronquée à une longueur sûre). Si vous basculez `/verbose on|full|off` pendant qu’une exécution est en cours, les bulles d’outil suivantes respectent le nouveau réglage.
- Niveaux : `on` (minimal) | `full` | `off` (par défaut).
- Un message ne contenant qu’une directive active/désactive la verbosité de session et répond `Verbose logging enabled.` / `Verbose logging disabled.` ; les niveaux invalides renvoient une indication sans modifier l’état.
- `/verbose off` stocke un remplacement de session explicite ; effacez-le via l’interface Sessions en choisissant `inherit`.
- Une directive en ligne n’affecte que ce message ; les valeurs par défaut de session/globales s’appliquent sinon.
- Envoyez `/verbose` (ou `/verbose:`) sans argument pour voir le niveau de verbosité actuel.
- Lorsque la verbosité est activée, les agents qui émettent des résultats d’outils structurés (Pi, autres agents JSON) renvoient chaque appel d’outil comme son propre message de métadonnées uniquement, préfixé par `<emoji> <tool-name>: <arg>` lorsque disponible (chemin/commande). Ces résumés d’outil sont envoyés dès le démarrage de chaque outil (bulles séparées), et non comme deltas de streaming.
- Les résumés d’échec d’outil restent visibles en mode normal, mais les suffixes détaillant les erreurs brutes sont masqués sauf si la verbosité est `on` ou `full`.
- Lorsque la verbosité est `full`, les sorties d’outils sont également transférées après achèvement (bulle séparée, tronquée à une longueur sûre). Si vous basculez `/verbose on|full|off` pendant qu’une exécution est en cours, les bulles d’outil suivantes respectent le nouveau réglage.
## Directives de trace Plugin (/trace)
## Directives de trace de Plugin (/trace)
- Niveaux : `on` | `off` (par défaut).
- Un message contenant uniquement une directive active la sortie de trace Plugin de session et répond `Plugin trace enabled.` / `Plugin trace disabled.`.
- Une directive en ligne n’affecte que ce message ; les valeurs par défaut de session/globales s’appliquent sinon.
- Niveaux : `on` | `off` (par défaut).
- Un message ne contenant qu’une directive active/désactive la sortie de trace des plugins de session et répond `Plugin trace enabled.` / `Plugin trace disabled.`.
- Une directive en ligne n’affecte que ce message ; les valeurs par défaut de session/globales s’appliquent sinon.
- Envoyez `/trace` (ou `/trace:`) sans argument pour voir le niveau de trace actuel.
- `/trace` est plus restreint que `/verbose` : il n’expose que les lignes de trace/débogage appartenant au Plugin, telles que les résumés de débogage Active Memory.
- `/trace` est plus restreint que `/verbose` : il n’expose que les lignes de trace/débogage propres aux plugins, comme les résumés de débogage Active Memory.
- Les lignes de trace peuvent apparaître dans `/status` et comme message de diagnostic de suivi après la réponse normale de l’assistant.
## Visibilité du raisonnement (/reasoning)
- Niveaux : `on|off|stream`.
- Un message contenant uniquement une directive active si les blocs de réflexion sont affichés dans les réponses.
- Quand elle est activée, la réflexion est envoyée comme **message séparé** préfixé par `Reasoning:`.
- `stream` (Telegram uniquement) : diffuse la réflexion dans la bulle de brouillon Telegram pendant la génération de la réponse, puis envoie la réponse finale sans réflexion.
- Alias : `/reason`.
- Envoyez `/reasoning` (ou `/reasoning:`) sans argument pour voir le niveau de raisonnement actuel.
- Ordre de résolution : directive en ligne, puis surcharge de session, puis valeur par défaut par agent (`agents.list[].reasoningDefault`), puis repli (`off`).
- Niveaux : `on|off|stream`.
- Un message ne contenant qu’une directive active/désactive l’affichage des blocs de réflexion dans les réponses.
- Lorsqu’il est activé, le raisonnement est envoyé comme **message séparé** préfixé par `Reasoning:`.
- `stream` (Telegram uniquement) : diffuse le raisonnement dans la bulle de brouillon Telegram pendant la génération de la réponse, puis envoie la réponse finale sans raisonnement.
- Alias : `/reason`.
- Envoyez `/reasoning` (ou `/reasoning:`) sans argument pour voir le niveau actuel de raisonnement.
- Ordre de résolution : directive en ligne, puis remplacement de session, puis valeur par défaut par agent (`agents.list[].reasoningDefault`), puis repli (`off`).
## Voir aussi
- La documentation du mode élevé se trouve dans [Mode élevé](/fr/tools/elevated).
- La documentation sur le mode élevé se trouve dans [Elevated mode](/fr/tools/elevated).
## Heartbeats
- Le corps de la sonde Heartbeat est le prompt Heartbeat configuré (par défaut : `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Les directives en ligne dans un message Heartbeat s’appliquent comme d’habitude (mais évitez de modifier les valeurs par défaut de session depuis les Heartbeats).
- La remise Heartbeat utilise par défaut uniquement la charge utile finale. Pour envoyer aussi le message séparé `Reasoning:` (lorsqu’il est disponible), définissez `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` par agent.
- Le corps de la sonde Heartbeat correspond à l’invite Heartbeat configurée (par défaut : `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Les directives en ligne dans un message Heartbeat s’appliquent comme d’habitude (mais évitez de modifier les valeurs par défaut de session depuis des Heartbeats).
- La livraison Heartbeat utilise par défaut uniquement la charge utile finale. Pour envoyer également le message séparé `Reasoning:` (lorsqu’il est disponible), définissez `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` par agent.
## Interface Web chat
## Interface de chat web
- Le sélecteur de réflexion du Web chat reflète le niveau stocké de la session depuis le stockage/configuration de session entrante lors du chargement de la page.
- Choisir un autre niveau écrit immédiatement la surcharge de session via `sessions.patch` ; il n’attend pas l’envoi suivant et ce n’est pas une surcharge ponctuelle `thinkingOnce`.
- La première option est toujours `Default (<resolved level>)`, où la valeur par défaut résolue provient du profil de réflexion du fournisseur du modèle de session actif.
- Le sélecteur utilise `thinkingOptions` renvoyé par la ligne de session Gateway. L’interface navigateur ne conserve pas sa propre liste regex fournisseur ; les Plugins possèdent les ensembles de niveaux propres au modèle.
- `/think:<level>` continue de fonctionner et met à jour le même niveau de session stocké, afin que les directives de chat et le sélecteur restent synchronisés.
- Le sélecteur de réflexion du chat web reflète le niveau stocké de la session depuis le magasin/configuration de session entrante au chargement de la page.
- Le choix d’un autre niveau écrit immédiatement le remplacement de session via `sessions.patch` ; il n’attend pas l’envoi suivant et il ne s’agit pas d’un remplacement ponctuel `thinkingOnce`.
- La première option est toujours `Default (<resolved level>)`, où la valeur par défaut résolue provient du profil de réflexion du fournisseur du modèle actif de la session.
- Le sélecteur utilise `thinkingOptions` renvoyé par la ligne de session Gateway. L’interface navigateur ne conserve pas sa propre liste regex de fournisseurs ; les plugins sont propriétaires des ensembles de niveaux spécifiques aux modèles.
- `/think:<level>` fonctionne toujours et met à jour le même niveau de session stocké, afin que les directives de chat et le sélecteur restent synchronisés.
## Profils fournisseur
## Profils de fournisseur
- Les Plugins fournisseur peuvent exposer `resolveThinkingProfile(ctx)` pour définir les niveaux pris en charge et la valeur par défaut du modèle.
- Chaque niveau de profil a un `id` canonique stocké (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) et peut inclure un `label` d’affichage. Les fournisseurs binaires utilisent `{ id: "low", label: "on" }`.
- Les hooks hérités publiés (`supportsXHighThinking`, `isBinaryThinking` et `resolveDefaultThinkingLevel`) restent des adaptateurs de compatibilité, mais les nouveaux ensembles de niveaux personnalisés doivent utiliser `resolveThinkingProfile`.
- Les lignes Gateway exposent `thinkingOptions` et `thinkingDefault` afin que les clients ACP/chat affichent le même profil que celui utilisé par la validation du runtime.
- Les plugins de fournisseur peuvent exposer `resolveThinkingProfile(ctx)` pour définir les niveaux pris en charge et la valeur par défaut du modèle.
- Chaque niveau du profil possède un `id` canonique stocké (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) et peut inclure un `label` d’affichage. Les fournisseurs binaires utilisent `{ id: "low", label: "on" }`.
- Les hooks historiques publiés (`supportsXHighThinking`, `isBinaryThinking` et `resolveDefaultThinkingLevel`) restent disponibles comme adaptateurs de compatibilité, mais les nouveaux ensembles de niveaux personnalisés doivent utiliser `resolveThinkingProfile`.
- Les lignes Gateway exposent `thinkingOptions` et `thinkingDefault` afin que les clients ACP/chat affichent le même profil que celui utilisé par la validation à l’exécution.