chore(i18n): refresh fr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
0fda378789
commit
41ae35e536
File diff suppressed because it is too large
Load Diff
@ -1,99 +1,99 @@
|
||||
---
|
||||
read_when:
|
||||
- Modification du texte du prompt système, de la liste des outils ou des sections heure/pulsation
|
||||
- Modification du comportement d’amorçage de l’espace de travail ou d’injection des Skills
|
||||
- Modification du texte du prompt système, de la liste des outils ou des sections d’heure/Heartbeat
|
||||
- Modification du bootstrap de l’espace de travail ou du comportement d’injection des Skills
|
||||
summary: Ce que contient le prompt système d’OpenClaw et comment il est assemblé
|
||||
title: Prompt système
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T06:49:38Z"
|
||||
generated_at: "2026-04-15T19:41:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Prompt système
|
||||
|
||||
OpenClaw construit un prompt système personnalisé pour chaque exécution d’agent. Le prompt est **géré par OpenClaw** et n’utilise pas le prompt par défaut de pi-coding-agent.
|
||||
OpenClaw construit un prompt système personnalisé pour chaque exécution d’agent. Le prompt appartient à **OpenClaw** et n’utilise pas le prompt par défaut de pi-coding-agent.
|
||||
|
||||
Le prompt est assemblé par OpenClaw et injecté dans chaque exécution d’agent.
|
||||
|
||||
Les plugins de fournisseur peuvent apporter des indications de prompt compatibles avec le cache sans remplacer l’intégralité du prompt géré par OpenClaw. Le runtime du fournisseur peut :
|
||||
Les plugins de fournisseur peuvent apporter des indications de prompt compatibles avec le cache sans remplacer l’intégralité du prompt détenu par OpenClaw. Le runtime du fournisseur peut :
|
||||
|
||||
- remplacer un petit ensemble de sections principales nommées (`interaction_style`,
|
||||
- remplacer un petit ensemble de sections cœur nommées (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- injecter un **préfixe stable** au-dessus de la limite de cache du prompt
|
||||
- injecter un **suffixe dynamique** au-dessous de la limite de cache du prompt
|
||||
- injecter un **préfixe stable** au-dessus de la limite du cache de prompt
|
||||
- injecter un **suffixe dynamique** en dessous de la limite du cache de prompt
|
||||
|
||||
Utilisez les contributions gérées par le fournisseur pour l’ajustement spécifique à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour de véritables modifications globales du prompt, pas pour le comportement normal d’un fournisseur.
|
||||
Utilisez des contributions détenues par le fournisseur pour les ajustements spécifiques à une famille de modèles. Conservez la mutation de prompt héritée `before_prompt_build` pour la compatibilité ou pour des changements de prompt réellement globaux, pas pour le comportement normal d’un fournisseur.
|
||||
|
||||
## Structure
|
||||
|
||||
Le prompt est volontairement compact et utilise des sections fixes :
|
||||
Le prompt est volontairement compact et utilise des sections fixes :
|
||||
|
||||
- **Outils** : rappel structuré de la source de vérité des outils, plus indications d’exécution pour l’utilisation des outils.
|
||||
- **Sécurité** : court rappel des garde-fous pour éviter les comportements de recherche de pouvoir ou le contournement de la supervision.
|
||||
- **Skills** (lorsqu’elles sont disponibles) : indique au modèle comment charger les instructions des Skills à la demande.
|
||||
- **Auto-mise à jour d’OpenClaw** : explique comment inspecter la configuration en toute sécurité avec
|
||||
`config.schema.lookup`, corriger la configuration avec `config.patch`, remplacer l’intégralité de la
|
||||
configuration avec `config.apply`, et exécuter `update.run` uniquement sur demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse également de réécrire
|
||||
- **Tooling** : rappel de la source de vérité des outils structurés, plus indications d’utilisation des outils au runtime.
|
||||
- **Safety** : court rappel de garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision.
|
||||
- **Skills** (lorsqu’ils sont disponibles) : indique au modèle comment charger à la demande les instructions des Skills.
|
||||
- **OpenClaw Self-Update** : comment inspecter la configuration en toute sécurité avec
|
||||
`config.schema.lookup`, corriger la configuration avec `config.patch`, remplacer la
|
||||
configuration complète avec `config.apply`, et exécuter `update.run` uniquement sur demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse également de réécrire
|
||||
`tools.exec.ask` / `tools.exec.security`, y compris les alias hérités `tools.bash.*`
|
||||
qui se normalisent vers ces chemins exec protégés.
|
||||
- **Espace de travail** : répertoire de travail (`agents.defaults.workspace`).
|
||||
- **Documentation** : chemin local vers la documentation OpenClaw (dépôt ou package npm) et moment où la lire.
|
||||
- **Fichiers de l’espace de travail (injectés)** : indique que les fichiers d’amorçage sont inclus ci-dessous.
|
||||
- **Sandbox** (lorsqu’elle est activée) : indique l’environnement d’exécution isolé, les chemins de sandbox et si l’exécution élevée est disponible.
|
||||
- **Date et heure actuelles** : heure locale de l’utilisateur, fuseau horaire et format d’heure.
|
||||
- **Balises de réponse** : syntaxe facultative des balises de réponse pour les fournisseurs pris en charge.
|
||||
- **Pulsations** : prompt de pulsation et comportement d’accusé de réception, lorsque les pulsations sont activées pour l’agent par défaut.
|
||||
- **Runtime** : hôte, OS, node, racine du dépôt (lorsqu’elle est détectée), niveau de réflexion (une ligne).
|
||||
- **Raisonnement** : niveau de visibilité actuel + indication de bascule `/reasoning`.
|
||||
- **Workspace** : répertoire de travail (`agents.defaults.workspace`).
|
||||
- **Documentation** : chemin local vers la documentation OpenClaw (dépôt ou package npm) et quand la lire.
|
||||
- **Workspace Files (injected)** : indique que les fichiers de bootstrap sont inclus ci-dessous.
|
||||
- **Sandbox** (lorsqu’elle est activée) : indique le runtime sandboxé, les chemins de la sandbox et si l’exécution élevée est disponible.
|
||||
- **Current Date & Time** : heure locale de l’utilisateur, fuseau horaire et format horaire.
|
||||
- **Reply Tags** : syntaxe facultative des balises de réponse pour les fournisseurs pris en charge.
|
||||
- **Heartbeats** : prompt de Heartbeat et comportement d’accusé de réception, lorsque les Heartbeats sont activés pour l’agent par défaut.
|
||||
- **Runtime** : hôte, OS, node, modèle, racine du dépôt (lorsqu’elle est détectée), niveau de réflexion (une ligne).
|
||||
- **Reasoning** : niveau de visibilité actuel + indication de bascule /reasoning.
|
||||
|
||||
La section Outils comprend également des indications d’exécution pour les tâches de longue durée :
|
||||
La section Tooling inclut également des indications d’exécution pour les tâches longues :
|
||||
|
||||
- utiliser cron pour un suivi ultérieur (`check back later`, rappels, travail récurrent)
|
||||
au lieu de boucles `exec` avec veille, d’astuces de délai `yieldMs` ou d’un sondage répété de `process`
|
||||
- utiliser `exec` / `process` uniquement pour les commandes qui démarrent maintenant et continuent à s’exécuter
|
||||
- utiliser Cron pour un suivi ultérieur (`check back later`, rappels, travail récurrent)
|
||||
au lieu de boucles de veille `exec`, d’astuces de délai `yieldMs` ou de sondages `process`
|
||||
répétés
|
||||
- utiliser `exec` / `process` uniquement pour des commandes qui démarrent maintenant et continuent à s’exécuter
|
||||
en arrière-plan
|
||||
- lorsque le réveil automatique à la fin est activé, démarrer la commande une seule fois et s’appuyer sur
|
||||
le chemin de réveil push lorsqu’elle émet une sortie ou échoue
|
||||
- utiliser `process` pour les journaux, le statut, l’entrée ou l’intervention lorsque vous devez
|
||||
le mécanisme de réveil push lorsqu’elle produit une sortie ou échoue
|
||||
- utiliser `process` pour les journaux, l’état, l’entrée ou l’intervention lorsque vous devez
|
||||
inspecter une commande en cours d’exécution
|
||||
- si la tâche est plus importante, préférer `sessions_spawn` ; la fin d’un sous-agent est
|
||||
pilotée par push et réannoncée automatiquement au demandeur
|
||||
- si la tâche est plus importante, préférer `sessions_spawn` ; la fin des sous-agents est
|
||||
signalée par push et réannoncée automatiquement au demandeur
|
||||
- ne pas sonder `subagents list` / `sessions_list` en boucle uniquement pour attendre
|
||||
la fin
|
||||
|
||||
Lorsque l’outil expérimental `update_plan` est activé, la section Outils indique également au
|
||||
modèle de l’utiliser uniquement pour les tâches non triviales en plusieurs étapes, de conserver exactement une étape
|
||||
`in_progress`, et d’éviter de répéter l’intégralité du plan après chaque mise à jour.
|
||||
Lorsque l’outil expérimental `update_plan` est activé, Tooling indique également au
|
||||
modèle de ne l’utiliser que pour un travail non trivial en plusieurs étapes, de conserver exactement une étape
|
||||
`in_progress`, et d’éviter de répéter le plan entier après chaque mise à jour.
|
||||
|
||||
Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations exec, le sandboxing et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception.
|
||||
Les garde-fous de Safety dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas la politique. Utilisez la politique des outils, les approbations exec, la sandbox et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception.
|
||||
|
||||
Sur les canaux avec cartes ou boutons d’approbation natifs, le prompt d’exécution indique désormais à
|
||||
l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle
|
||||
`/approve` que lorsque le résultat de l’outil indique que les approbations dans le chat ne sont pas disponibles ou
|
||||
que l’approbation manuelle est la seule possibilité.
|
||||
Sur les canaux disposant de cartes/boutons d’approbation natifs, le prompt runtime indique désormais à l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle
|
||||
`/approve` que lorsque le résultat de l’outil indique que les approbations dans le chat ne sont pas disponibles ou que l’approbation manuelle est la seule option.
|
||||
|
||||
## Modes de prompt
|
||||
|
||||
OpenClaw peut produire des prompts système plus petits pour les sous-agents. Le runtime définit un
|
||||
`promptMode` pour chaque exécution (ce n’est pas une configuration visible par l’utilisateur) :
|
||||
OpenClaw peut générer des prompts système plus petits pour les sous-agents. Le runtime définit un
|
||||
`promptMode` pour chaque exécution (pas une configuration destinée à l’utilisateur) :
|
||||
|
||||
- `full` (par défaut) : inclut toutes les sections ci-dessus.
|
||||
- `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Rappel mémoire**, **Auto-mise à jour d’OpenClaw**, **Alias de modèles**, **Identité de l’utilisateur**, **Balises de réponse**,
|
||||
**Messagerie**, **Réponses silencieuses** et **Pulsations**. Outils, **Sécurité**,
|
||||
Espace de travail, Sandbox, Date et heure actuelles (lorsqu’elles sont connues), Runtime et le contexte
|
||||
- `full` (par défaut) : inclut toutes les sections ci-dessus.
|
||||
- `minimal` : utilisé pour les sous-agents ; omet **Skills**, **Memory Recall**, **OpenClaw
|
||||
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
|
||||
**Messaging**, **Silent Replies** et **Heartbeats**. Tooling, **Safety**,
|
||||
Workspace, Sandbox, Current Date & Time (lorsqu’ils sont connus), Runtime et le contexte
|
||||
injecté restent disponibles.
|
||||
- `none` : renvoie uniquement la ligne d’identité de base.
|
||||
- `none` : renvoie uniquement la ligne d’identité de base.
|
||||
|
||||
Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont libellés **Contexte du sous-agent**
|
||||
au lieu de **Contexte du chat de groupe**.
|
||||
Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont étiquetés **Subagent
|
||||
Context** au lieu de **Group Chat Context**.
|
||||
|
||||
## Injection de l’amorçage de l’espace de travail
|
||||
## Injection du bootstrap de l’espace de travail
|
||||
|
||||
Les fichiers d’amorçage sont tronqués et ajoutés sous **Contexte du projet** afin que le modèle voie le contexte d’identité et de profil sans nécessiter de lectures explicites :
|
||||
Les fichiers de bootstrap sont tronqués et ajoutés sous **Project Context** afin que le modèle voie le contexte d’identité et de profil sans avoir besoin de lectures explicites :
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -101,68 +101,68 @@ Les fichiers d’amorçage sont tronqués et ajoutés sous **Contexte du projet*
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (uniquement dans les tout nouveaux espaces de travail)
|
||||
- `BOOTSTRAP.md` (uniquement dans les espaces de travail tout neufs)
|
||||
- `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de repli en minuscules
|
||||
|
||||
Tous ces fichiers sont **injectés dans la fenêtre de contexte** à chaque tour, sauf si
|
||||
un garde-fou spécifique au fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque
|
||||
les pulsations sont désactivées pour l’agent par défaut ou lorsque
|
||||
une condition spécifique au fichier s’applique. `HEARTBEAT.md` est omis lors des exécutions normales lorsque
|
||||
les Heartbeats sont désactivés pour l’agent par défaut ou que
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` vaut false. Gardez les fichiers injectés concis —
|
||||
en particulier `MEMORY.md`, qui peut grossir avec le temps et entraîner
|
||||
une utilisation du contexte étonnamment élevée ainsi que des compactages plus fréquents.
|
||||
une utilisation du contexte étonnamment élevée ainsi qu’une Compaction plus fréquente.
|
||||
|
||||
> **Remarque :** les fichiers quotidiens `memory/*.md` ne font **pas** partie du
|
||||
> **Contexte du projet** d’amorçage normal. Lors des tours ordinaires, on y accède à la demande via les outils
|
||||
> **Remarque :** les fichiers quotidiens `memory/*.md` ne font **pas** partie du
|
||||
> Project Context de bootstrap normal. Lors des tours ordinaires, ils sont consultés à la demande via les outils
|
||||
> `memory_search` et `memory_get`, de sorte qu’ils ne comptent pas dans la
|
||||
> fenêtre de contexte à moins que le modèle ne les lise explicitement. Les tours simples `/new` et
|
||||
> `/reset` constituent l’exception : le runtime peut préfixer la mémoire quotidienne récente
|
||||
> sous la forme d’un bloc ponctuel de contexte de démarrage pour ce premier tour.
|
||||
> fenêtre de contexte sauf si le modèle les lit explicitement. Les tours `/new` et
|
||||
> `/reset` seuls constituent l’exception : le runtime peut préfixer de la mémoire quotidienne récente
|
||||
> comme bloc de contexte de démarrage à usage unique pour ce premier tour.
|
||||
|
||||
Les fichiers volumineux sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par
|
||||
`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total d’amorçage injecté
|
||||
`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total du bootstrap injecté
|
||||
sur l’ensemble des fichiers est plafonné par `agents.defaults.bootstrapTotalMaxChars`
|
||||
(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. Lorsqu’une troncature
|
||||
se produit, OpenClaw peut injecter un bloc d’avertissement dans Contexte du projet ; contrôlez cela avec
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ;
|
||||
par défaut : `once`).
|
||||
(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. En cas de troncature,
|
||||
OpenClaw peut injecter un bloc d’avertissement dans Project Context ; contrôlez cela avec
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ;
|
||||
par défaut : `once`).
|
||||
|
||||
Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers d’amorçage
|
||||
Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers de bootstrap
|
||||
sont filtrés pour garder le contexte du sous-agent réduit).
|
||||
|
||||
Les hooks internes peuvent intercepter cette étape via `agent:bootstrap` pour modifier ou remplacer
|
||||
les fichiers d’amorçage injectés (par exemple en remplaçant `SOUL.md` par une persona alternative).
|
||||
les fichiers de bootstrap injectés (par exemple en remplaçant `SOUL.md` par un persona alternatif).
|
||||
|
||||
Si vous souhaitez rendre l’agent moins générique, commencez par le
|
||||
Si vous souhaitez que l’agent paraisse moins générique, commencez par
|
||||
[Guide de personnalité SOUL.md](/fr/concepts/soul).
|
||||
|
||||
Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge du schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context).
|
||||
Pour inspecter la contribution de chaque fichier injecté (brut vs injecté, troncature, plus surcharge de schéma d’outil), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context).
|
||||
|
||||
## Gestion du temps
|
||||
|
||||
Le prompt système inclut une section dédiée **Date et heure actuelles** lorsque le
|
||||
fuseau horaire de l’utilisateur est connu. Pour garder le cache du prompt stable, elle n’inclut désormais que le
|
||||
**fuseau horaire** (pas d’horloge dynamique ni de format d’heure).
|
||||
Le prompt système inclut une section dédiée **Current Date & Time** lorsque le
|
||||
fuseau horaire de l’utilisateur est connu. Pour garder le cache de prompt stable, il n’inclut désormais que le
|
||||
**fuseau horaire** (sans horloge dynamique ni format horaire).
|
||||
|
||||
Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte d’état
|
||||
inclut une ligne d’horodatage. Le même outil peut aussi définir une substitution de modèle par session
|
||||
(`model=default` la supprime).
|
||||
Utilisez `session_status` lorsque l’agent a besoin de l’heure actuelle ; la carte d’état
|
||||
inclut une ligne d’horodatage. Le même outil peut aussi définir un remplacement de modèle par session
|
||||
(`model=default` l’efface).
|
||||
|
||||
Configurez avec :
|
||||
Configurez avec :
|
||||
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Voir [Date et heure](/fr/date-time) pour tous les détails du comportement.
|
||||
Voir [Date & Time](/fr/date-time) pour tous les détails de comportement.
|
||||
|
||||
## Skills
|
||||
|
||||
Lorsque des Skills éligibles existent, OpenClaw injecte une **liste compacte des Skills disponibles**
|
||||
(`formatSkillsForPrompt`) qui inclut le **chemin du fichier** pour chaque Skill. Le
|
||||
Lorsque des Skills admissibles existent, OpenClaw injecte une **liste compacte des Skills disponibles**
|
||||
(`formatSkillsForPrompt`) qui inclut le **chemin de fichier** pour chaque Skill. Le
|
||||
prompt indique au modèle d’utiliser `read` pour charger le SKILL.md à l’emplacement indiqué
|
||||
(espace de travail, géré ou intégré). Si aucune Skill n’est éligible, la section
|
||||
Skills est omise.
|
||||
(espace de travail, géré ou intégré). Si aucun Skill n’est admissible, la
|
||||
section Skills est omise.
|
||||
|
||||
L’éligibilité comprend les garde-fous des métadonnées des Skills, les vérifications d’environnement/configuration d’exécution,
|
||||
L’admissibilité inclut les conditions des métadonnées des Skills, les vérifications de l’environnement/configuration du runtime,
|
||||
et la liste d’autorisation effective des Skills de l’agent lorsque `agents.defaults.skills` ou
|
||||
`agents.list[].skills` est configuré.
|
||||
|
||||
@ -176,13 +176,26 @@ et la liste d’autorisation effective des Skills de l’agent lorsque `agents.d
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Cela maintient un prompt de base réduit tout en permettant une utilisation ciblée des Skills.
|
||||
Cela permet de conserver un prompt de base réduit tout en rendant possible une utilisation ciblée des Skills.
|
||||
|
||||
Le budget de la liste des Skills appartient au sous-système des Skills :
|
||||
|
||||
- Valeur globale par défaut : `skills.limits.maxSkillsPromptChars`
|
||||
- Remplacement par agent : `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Les extraits runtime génériques bornés utilisent une autre surface :
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
Cette séparation permet de découpler le dimensionnement des Skills de celui de la lecture/injection au runtime
|
||||
comme `memory_get`, les résultats d’outil en direct et les actualisations de `AGENTS.md` après Compaction.
|
||||
|
||||
## Documentation
|
||||
|
||||
Lorsque disponible, le prompt système inclut une section **Documentation** qui pointe vers le
|
||||
répertoire local de documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du
|
||||
Lorsqu’elle est disponible, le prompt système inclut une section **Documentation** qui pointe vers le
|
||||
répertoire local de la documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du
|
||||
package npm intégré) et mentionne également le miroir public, le dépôt source, le Discord de la communauté et
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) pour la découverte des Skills. Le prompt indique au modèle de consulter d’abord la documentation locale
|
||||
pour le comportement, les commandes, la configuration ou l’architecture d’OpenClaw, et d’exécuter
|
||||
`openclaw status` lui-même lorsque c’est possible (en demandant à l’utilisateur seulement lorsqu’il n’y a pas accès).
|
||||
lui-même `openclaw status` lorsque c’est possible (en ne demandant à l’utilisateur que lorsqu’il n’y a pas accès).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous créez un nouveau Plugin de canal de messagerie.
|
||||
- Vous souhaitez connecter OpenClaw à une plateforme de messagerie.
|
||||
- Vous devez comprendre la surface d’adaptation de `ChannelPlugin`
|
||||
- Vous créez un nouveau Plugin de canal de messagerie
|
||||
- Vous souhaitez connecter OpenClaw à une plateforme de messagerie
|
||||
- Vous devez comprendre la surface d’adaptation de ChannelPlugin
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: Guide étape par étape pour créer un Plugin de canal de messagerie pour OpenClaw
|
||||
title: Créer des Plugins de canal
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T06:56:34Z"
|
||||
generated_at: "2026-04-15T19:41:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,93 +18,106 @@ x-i18n:
|
||||
# Créer des Plugins de canal
|
||||
|
||||
Ce guide explique comment créer un Plugin de canal qui connecte OpenClaw à une
|
||||
plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec la sécurité des DM,
|
||||
l’appairage, le fil des réponses et la messagerie sortante.
|
||||
plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec
|
||||
la sécurité des messages privés, l’appairage, le fil de réponse et la
|
||||
messagerie sortante.
|
||||
|
||||
<Info>
|
||||
Si vous n’avez encore créé aucun Plugin OpenClaw, lisez d’abord
|
||||
[Getting Started](/fr/plugins/building-plugins) pour la structure de package
|
||||
de base et la configuration du manifeste.
|
||||
Si vous n’avez encore jamais créé de Plugin OpenClaw, lisez d’abord
|
||||
[Getting Started](/fr/plugins/building-plugins) pour comprendre la structure de
|
||||
package de base et la configuration du manifeste.
|
||||
</Info>
|
||||
|
||||
## Fonctionnement des Plugins de canal
|
||||
|
||||
Les Plugins de canal n’ont pas besoin de leurs propres outils d’envoi/modification/réaction. OpenClaw conserve un
|
||||
outil `message` partagé dans le cœur. Votre Plugin gère :
|
||||
Les Plugins de canal n’ont pas besoin de leurs propres outils send/edit/react.
|
||||
OpenClaw conserve un seul outil `message` partagé dans le cœur. Votre Plugin
|
||||
gère :
|
||||
|
||||
- **Configuration** — résolution de compte et assistant de configuration
|
||||
- **Sécurité** — politique DM et listes d’autorisation
|
||||
- **Appairage** — flux d’approbation des DM
|
||||
- **Grammaire de session** — comment les identifiants de conversation propres au fournisseur sont mappés vers les discussions de base, les identifiants de fil et les solutions de repli parent
|
||||
- **Configuration** — résolution du compte et assistant de configuration
|
||||
- **Sécurité** — politique des messages privés et listes d’autorisation
|
||||
- **Appairage** — flux d’approbation des messages privés
|
||||
- **Grammaire de session** — comment les identifiants de conversation spécifiques au fournisseur sont mappés vers les discussions de base, les identifiants de fil et les solutions de repli parent
|
||||
- **Sortant** — envoi de texte, de médias et de sondages vers la plateforme
|
||||
- **Fil des réponses** — comment les réponses sont organisées en fil
|
||||
- **Fil de discussion** — comment les réponses sont organisées en fil
|
||||
|
||||
Le cœur gère l’outil de message partagé, le câblage des prompts, la forme externe de la clé de session,
|
||||
la gestion générique `:thread:` et la distribution.
|
||||
Le cœur gère l’outil de message partagé, le câblage des prompts, la forme
|
||||
externe de la clé de session, le suivi générique `:thread:` et la répartition.
|
||||
|
||||
Si votre canal ajoute des paramètres d’outil de message qui transportent des sources média, exposez ces
|
||||
noms de paramètres via `describeMessageTool(...).mediaSourceParams`. Le cœur utilise
|
||||
cette liste explicite pour la normalisation des chemins du sandbox et la politique
|
||||
d’accès aux médias sortants, afin que les Plugins n’aient pas besoin de cas particuliers dans le cœur partagé pour des
|
||||
paramètres spécifiques au fournisseur comme l’avatar, la pièce jointe ou l’image de couverture.
|
||||
Préférez renvoyer une map indexée par action comme
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }` afin que des actions sans lien n’héritent pas des arguments média d’une autre action. Un tableau plat fonctionne aussi pour des paramètres
|
||||
volontairement partagés par chaque action exposée.
|
||||
Si votre canal ajoute des paramètres d’outil de message qui transportent des
|
||||
sources de médias, exposez ces noms de paramètres via
|
||||
`describeMessageTool(...).mediaSourceParams`. Le cœur utilise
|
||||
cette liste explicite pour la normalisation des chemins du bac à sable et la
|
||||
politique d’accès aux médias sortants. Les Plugins n’ont donc pas besoin de cas
|
||||
particuliers dans le cœur partagé pour les paramètres spécifiques au
|
||||
fournisseur, comme l’avatar, les pièces jointes ou l’image de couverture.
|
||||
Préférez renvoyer une map indexée par action, comme
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }`, afin que des actions sans
|
||||
rapport n’héritent pas des arguments média d’une autre action. Un tableau plat
|
||||
fonctionne également pour des paramètres volontairement partagés par toutes les
|
||||
actions exposées.
|
||||
|
||||
Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, conservez cette analyse
|
||||
dans le Plugin avec `messaging.resolveSessionConversation(...)`. C’est le
|
||||
hook canonique pour mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil optionnel,
|
||||
`baseConversationId` explicite, et tout `parentConversationCandidates`.
|
||||
Lorsque vous renvoyez `parentConversationCandidates`, conservez leur ordre du
|
||||
parent le plus spécifique vers la conversation parente la plus large/de base.
|
||||
Si votre plateforme stocke une portée supplémentaire dans les identifiants de
|
||||
conversation, conservez cette logique d’analyse dans le Plugin avec
|
||||
`messaging.resolveSessionConversation(...)`. Il s’agit du hook canonique pour
|
||||
mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de fil
|
||||
facultatif, l’éventuel `baseConversationId` et tous les
|
||||
`parentConversationCandidates`.
|
||||
Lorsque vous renvoyez `parentConversationCandidates`, gardez-les ordonnés du
|
||||
parent le plus spécifique au parent le plus large ou à la conversation de base.
|
||||
|
||||
Les Plugins groupés qui ont besoin de la même analyse avant le démarrage du registre des canaux
|
||||
peuvent aussi exposer un fichier de premier niveau `session-key-api.ts` avec un
|
||||
export `resolveSessionConversation(...)` correspondant. Le cœur utilise cette surface sûre au démarrage
|
||||
uniquement lorsque le registre de Plugin d’exécution n’est pas encore disponible.
|
||||
Les Plugins intégrés qui ont besoin de la même analyse avant le démarrage du
|
||||
registre de canaux peuvent aussi exposer un fichier `session-key-api.ts` de
|
||||
niveau supérieur avec un export `resolveSessionConversation(...)`
|
||||
correspondant. Le cœur utilise cette surface sûre pour l’amorçage uniquement
|
||||
lorsque le registre de Plugin d’exécution n’est pas encore disponible.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` reste disponible comme solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin de solutions de repli parent qu’au-dessus de l’identifiant générique/brut. Si les deux hooks existent, le cœur utilise
|
||||
d’abord `resolveSessionConversation(...).parentConversationCandidates` et ne
|
||||
revient à `resolveParentConversationCandidates(...)` que lorsque le hook canonique
|
||||
les omet.
|
||||
`messaging.resolveParentConversationCandidates(...)` reste disponible comme
|
||||
solution de repli de compatibilité héritée lorsqu’un Plugin n’a besoin que de
|
||||
solutions de repli parent au-dessus de l’identifiant générique ou brut. Si les
|
||||
deux hooks existent, le cœur utilise d’abord
|
||||
`resolveSessionConversation(...).parentConversationCandidates` et ne se rabat
|
||||
sur `resolveParentConversationCandidates(...)` que lorsque le hook canonique ne
|
||||
les fournit pas.
|
||||
|
||||
## Approbations et capacités de canal
|
||||
## Approbations et capacités des canaux
|
||||
|
||||
La plupart des Plugins de canal n’ont pas besoin de code spécifique aux approbations.
|
||||
La plupart des Plugins de canal n’ont pas besoin de code spécifique aux
|
||||
approbations.
|
||||
|
||||
- Le cœur gère `/approve` dans la même discussion, les charges utiles de bouton d’approbation partagées et la livraison de repli générique.
|
||||
- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal a besoin d’un comportement spécifique aux approbations.
|
||||
- `ChannelPlugin.approvals` est supprimé. Placez les informations de livraison/rendu/authentification natives de l’approbation dans `approvalCapability`.
|
||||
- `plugin.auth` concerne uniquement login/logout ; le cœur ne lit plus les hooks d’authentification des approbations depuis cet objet.
|
||||
- Préférez un seul objet `approvalCapability` sur le Plugin de canal lorsque le canal nécessite un comportement spécifique aux approbations.
|
||||
- `ChannelPlugin.approvals` a été supprimé. Placez les informations de livraison, native, rendu et authentification des approbations dans `approvalCapability`.
|
||||
- `plugin.auth` est réservé à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation depuis cet objet.
|
||||
- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la jonction canonique pour l’authentification des approbations.
|
||||
- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification des approbations dans la même discussion.
|
||||
- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface initiatrice/du client natif lorsqu’il diffère de l’authentification des approbations dans la même discussion. Le cœur utilise ce hook spécifique à exec pour distinguer `enabled` de `disabled`, déterminer si le canal initiateur prend en charge les approbations d’exécution natives, et inclure le canal dans les indications de repli du client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit ce rôle pour le cas courant.
|
||||
- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, par exemple masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison.
|
||||
- Utilisez `approvalCapability.delivery` uniquement pour le routage des approbations natives ou la suppression du repli.
|
||||
- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation native gérées par le canal. Gardez-le paresseux sur les points d’entrée chauds du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module d’exécution à la demande tout en permettant au cœur d’assembler le cycle de vie de l’approbation.
|
||||
- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans la même discussion.
|
||||
- Si votre canal expose des approbations d’exécution natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface initiatrice ou du client natif lorsqu’il diffère de l’authentification d’approbation dans la même discussion. Le cœur utilise ce hook spécifique à l’exécution pour distinguer `enabled` et `disabled`, décider si le canal initiateur prend en charge les approbations d’exécution natives et inclure le canal dans les indications de repli du client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit ce rôle pour le cas courant.
|
||||
- Utilisez `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` pour le comportement spécifique au canal dans le cycle de vie des charges utiles, comme masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison.
|
||||
- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression du repli.
|
||||
- Utilisez `approvalCapability.nativeRuntime` pour les informations d’approbation native gérées par le canal. Gardez-le paresseux sur les points d’entrée critiques du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module d’exécution à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations.
|
||||
- Utilisez `approvalCapability.render` uniquement lorsqu’un canal a réellement besoin de charges utiles d’approbation personnalisées au lieu du moteur de rendu partagé.
|
||||
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal souhaite que la réponse du chemin désactivé explique les paramètres de configuration exacts nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent afficher des chemins à portée de compte tels que `channels.<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 la même discussion sans ajouter de logique du cœur spécifique aux approbations.
|
||||
- Si un canal a besoin d’une livraison d’approbation native, faites en sorte que le code du canal reste centré sur la normalisation de la cible ainsi que sur les informations de transport/de présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et gérer lui-même le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage externe. `nativeRuntime` est divisé en quelques jonctions plus petites :
|
||||
- `availability` — si le compte est configuré et si une requête doit être traitée
|
||||
- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente/résolues/expirées ou des actions finales
|
||||
- `transport` — préparer les cibles puis envoyer/mettre à jour/supprimer des messages d’approbation natifs
|
||||
- `interactions` — hooks facultatifs bind/unbind/clear-action pour les boutons ou réactions natifs
|
||||
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse du chemin désactivé explique exactement quels paramètres de configuration sont nécessaires pour activer les approbations d’exécution natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à comptes nommés doivent afficher des chemins à portée de compte comme `channels.<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 messages privés stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans la même discussion sans ajouter de logique spécifique aux approbations dans le cœur.
|
||||
- Si un canal a besoin de la livraison d’approbations natives, gardez le code du canal centré sur la normalisation de la cible ainsi que sur les informations de transport et de présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les informations spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les notifications de routage ailleurs. `nativeRuntime` est divisé en quelques jonctions plus petites :
|
||||
- `availability` — si le compte est configuré et si une requête doit être prise en charge
|
||||
- `presentation` — mapper le modèle de vue d’approbation partagé vers des charges utiles natives en attente, résolues, expirées ou vers des actions finales
|
||||
- `transport` — préparer les cibles puis envoyer, mettre à jour ou supprimer les messages d’approbation natifs
|
||||
- `interactions` — hooks facultatifs pour lier, délier ou effacer des actions pour les boutons ou réactions natifs
|
||||
- `observe` — hooks facultatifs de diagnostic de livraison
|
||||
- Si le canal a besoin d’objets gérés par l’exécution comme un client, un jeton, une app Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte d’exécution permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de colle d’encapsulation spécifique aux approbations.
|
||||
- Utilisez les niveaux inférieurs `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` uniquement lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive.
|
||||
- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` par ces helpers. `accountId` permet de garder la politique d’approbation multi-compte limitée au bon compte de bot, et `approvalKind` rend disponible au canal le comportement d’approbation exec vs Plugin sans branches codées en dur dans le cœur.
|
||||
- Le cœur gère désormais aussi les avis de reroutage d’approbation. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation a été envoyée vers les DM / un autre canal » depuis `createChannelNativeApprovalRuntime` ; exposez plutôt un routage précis de l’origine + des DM de l’approbateur via les helpers de capacité d’approbation partagés et laissez le cœur agréger les livraisons réelles avant de publier un éventuel avis dans la discussion initiatrice.
|
||||
- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas
|
||||
deviner ou réécrire le routage des approbations exec vs Plugin à partir d’un état local au canal.
|
||||
- Différents types d’approbation peuvent intentionnellement exposer différentes surfaces natives.
|
||||
Exemples groupés actuels :
|
||||
- Slack maintient le routage d’approbation native disponible à la fois pour les identifiants exec et Plugin.
|
||||
- Matrix conserve le même routage natif DM/canal et la même UX par réaction pour les approbations exec
|
||||
et Plugin, tout en permettant à l’authentification de différer selon le type d’approbation.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme encapsulation de compatibilité, mais le nouveau code doit préférer le constructeur de capacité et exposer `approvalCapability` sur le Plugin.
|
||||
- Si le canal a besoin d’objets gérés par l’exécution, comme un client, un jeton, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte d’exécution permet au cœur d’amorcer des gestionnaires pilotés par les capacités à partir de l’état de démarrage du canal sans ajouter de colle d’enveloppe spécifique aux approbations.
|
||||
- N’utilisez le niveau plus bas `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` que lorsque la jonction pilotée par les capacités n’est pas encore suffisamment expressive.
|
||||
- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` via ces helpers. `accountId` conserve la portée de la politique d’approbation multi-compte sur le bon compte de bot, et `approvalKind` conserve le comportement d’approbation d’exécution par rapport au Plugin disponible pour le canal sans branches codées en dur dans le cœur.
|
||||
- Le cœur gère désormais aussi les notifications de reroutage des approbations. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi du type « l’approbation est allée dans les messages privés / un autre canal » depuis `createChannelNativeApprovalRuntime` ; à la place, exposez un routage précis de l’origine et des messages privés de l’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier toute notification dans la discussion initiatrice.
|
||||
- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas deviner ni réécrire le routage des approbations d’exécution par rapport aux approbations de Plugin à partir d’un état local au canal.
|
||||
- Différents types d’approbation peuvent volontairement exposer différentes surfaces natives.
|
||||
Exemples intégrés actuels :
|
||||
- Slack conserve le routage d’approbation native disponible à la fois pour les identifiants d’exécution et de Plugin.
|
||||
- Matrix conserve le même routage natif en messages privés ou canal et la même UX basée sur les réactions pour les approbations d’exécution et de Plugin, tout en permettant à l’authentification de différer selon le type d’approbation.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme enveloppe de compatibilité, mais le nouveau code doit préférer le constructeur de capacités et exposer `approvalCapability` sur le Plugin.
|
||||
|
||||
Pour les points d’entrée chauds du canal, préférez les sous-chemins d’exécution plus étroits lorsque vous n’avez besoin que d’une seule partie de cette famille :
|
||||
Pour les points d’entrée critiques du canal, préférez les sous-chemins
|
||||
d’exécution plus étroits lorsque vous n’avez besoin que d’une seule partie de
|
||||
cette famille :
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -120,91 +133,91 @@ De même, préférez `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference`, et
|
||||
`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la surface
|
||||
parapluie plus large.
|
||||
`openclaw/plugin-sdk/reply-reference` et
|
||||
`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la
|
||||
surface englobante plus large.
|
||||
|
||||
Pour la configuration en particulier :
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution :
|
||||
adaptateurs de patch de configuration sûrs à l’import (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), sortie de note de recherche,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries`, et les constructeurs
|
||||
de proxy de configuration déléguée
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite sensible à l’environnement
|
||||
pour `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration avec installation facultative
|
||||
ainsi que quelques primitives sûres pour la configuration :
|
||||
- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs à l’exécution : adaptateurs de patch de configuration sûrs à l’importation (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), sortie des notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries` et les constructeurs de proxy de configuration déléguée
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` est la jonction d’adaptateur étroite, consciente de l’environnement, pour `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration d’installation facultative ainsi que quelques primitives sûres pour la configuration :
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Si votre canal prend en charge une configuration ou une authentification pilotée par l’environnement et que les flux génériques de démarrage/configuration doivent connaître ces noms de variables d’environnement avant le chargement de l’exécution, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`. Conservez les `envVars` d’exécution du canal ou les constantes locales uniquement pour le texte destiné aux opérateurs.
|
||||
Si votre canal prend en charge une configuration ou une authentification pilotée
|
||||
par des variables d’environnement et que les flux génériques de démarrage ou de
|
||||
configuration doivent connaître ces noms de variables avant le chargement de
|
||||
l’exécution, déclarez-les dans le manifeste du Plugin avec `channelEnvVars`.
|
||||
Conservez `envVars` de l’exécution du canal ou des constantes locales
|
||||
uniquement pour le texte destiné aux opérateurs.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, et
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` et
|
||||
`splitSetupEntries`
|
||||
|
||||
- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez également besoin des
|
||||
helpers partagés plus lourds de configuration/config tels que
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
- utilisez la jonction plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez aussi besoin des helpers partagés de configuration plus lourds, comme `moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Si votre canal veut seulement annoncer « installez d’abord ce Plugin » dans les
|
||||
surfaces de configuration, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur/assistant généré échoue de manière fermée sur les écritures de configuration et la finalisation, et il réutilise
|
||||
le même message « installation requise » pour la validation, la finalisation et le texte
|
||||
du lien vers la documentation.
|
||||
surfaces de configuration, préférez
|
||||
`createOptionalChannelSetupSurface(...)`. L’adaptateur et l’assistant générés
|
||||
échouent en mode fermé sur les écritures de configuration et la finalisation, et
|
||||
ils réutilisent le même message « installation requise » dans la validation, la
|
||||
finalisation et le texte du lien vers la documentation.
|
||||
|
||||
Pour les autres chemins chauds du canal, préférez les helpers étroits aux surfaces héritées plus larges :
|
||||
Pour les autres chemins critiques du canal, préférez les helpers étroits aux
|
||||
surfaces héritées plus larges :
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
`openclaw/plugin-sdk/account-id`,
|
||||
`openclaw/plugin-sdk/account-resolution`, et
|
||||
`openclaw/plugin-sdk/account-resolution` et
|
||||
`openclaw/plugin-sdk/account-helpers` pour la configuration multi-compte et
|
||||
le repli vers le compte par défaut
|
||||
la solution de repli du compte par défaut
|
||||
- `openclaw/plugin-sdk/inbound-envelope` et
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de route/enveloppe entrante et
|
||||
d’enregistrement-et-distribution
|
||||
- `openclaw/plugin-sdk/messaging-targets` pour l’analyse/la correspondance des cibles
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` pour le câblage de la route ou
|
||||
de l’enveloppe entrante ainsi que de l’enregistrement et de la répartition
|
||||
- `openclaw/plugin-sdk/messaging-targets` pour l’analyse et la correspondance
|
||||
des cibles
|
||||
- `openclaw/plugin-sdk/outbound-media` et
|
||||
`openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que les
|
||||
délégations d’identité/d’envoi sortants
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des liaisons de fil
|
||||
et l’enregistrement des adaptateurs
|
||||
- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champ de charge utile agent/média héritée
|
||||
est encore requise
|
||||
- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des commandes personnalisées Telegram,
|
||||
la validation des doublons/conflits et un contrat de configuration de commandes
|
||||
stable en repli
|
||||
`openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que
|
||||
les délégués d’identité et d’envoi sortants
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des
|
||||
liaisons de fil et l’enregistrement des adaptateurs
|
||||
- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition
|
||||
héritée des champs de charge utile agent/média est encore nécessaire
|
||||
- `openclaw/plugin-sdk/telegram-command-config` pour la normalisation des
|
||||
commandes personnalisées Telegram, la validation des doublons ou conflits, et
|
||||
un contrat de configuration de commande stable en solution de repli
|
||||
|
||||
Les canaux uniquement basés sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes/d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de chat personnalisés doivent utiliser les helpers natifs partagés au lieu d’implémenter leur propre cycle de vie d’approbation.
|
||||
Les canaux basés uniquement sur l’authentification peuvent généralement s’arrêter au chemin par défaut : le cœur gère les approbations et le Plugin expose simplement les capacités sortantes et d’authentification. Les canaux d’approbation native comme Matrix, Slack, Telegram et les transports de discussion personnalisés doivent utiliser les helpers natifs partagés au lieu de créer leur propre cycle de vie d’approbation.
|
||||
|
||||
## Politique des mentions entrantes
|
||||
|
||||
Conservez la gestion des mentions entrantes séparée en deux couches :
|
||||
Conservez la gestion des mentions entrantes répartie en deux couches :
|
||||
|
||||
- collecte d’éléments de preuve gérée par le Plugin
|
||||
- collecte de preuves gérée par le Plugin
|
||||
- évaluation de politique partagée
|
||||
|
||||
Utilisez `openclaw/plugin-sdk/channel-inbound` pour la couche partagée.
|
||||
|
||||
Convient bien à la logique locale au Plugin :
|
||||
Bon cas d’usage pour la logique locale au Plugin :
|
||||
|
||||
- détection des réponses au bot
|
||||
- détection des citations du bot
|
||||
- détection de réponse au bot
|
||||
- détection de citation du bot
|
||||
- vérifications de participation au fil
|
||||
- exclusions des messages de service/système
|
||||
- exclusions de messages de service ou système
|
||||
- caches natifs à la plateforme nécessaires pour prouver la participation du bot
|
||||
|
||||
Convient bien au helper partagé :
|
||||
Bon cas d’usage pour le helper partagé :
|
||||
|
||||
- `requireMention`
|
||||
- résultat de mention explicite
|
||||
- liste d’autorisation de mention implicite
|
||||
- contournement de commande
|
||||
- décision finale d’ignorance
|
||||
- décision finale d’ignorer
|
||||
|
||||
Flux recommandé :
|
||||
|
||||
1. Calculez les éléments factuels locaux sur les mentions.
|
||||
2. Passez ces éléments à `resolveInboundMentionDecision({ facts, policy })`.
|
||||
1. Calculez les faits de mention locaux.
|
||||
2. Transmettez ces faits à `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde d’entrée.
|
||||
|
||||
```typescript
|
||||
@ -245,7 +258,7 @@ if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour
|
||||
les Plugins de canal groupés qui dépendent déjà de l’injection d’exécution :
|
||||
les Plugins de canal intégrés qui dépendent déjà de l’injection d’exécution :
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -253,18 +266,20 @@ les Plugins de canal groupés qui dépendent déjà de l’injection d’exécut
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Les anciens helpers `resolveMentionGating*` restent présents dans
|
||||
`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité. Le nouveau code
|
||||
doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
Les anciens helpers `resolveMentionGating*` restent dans
|
||||
`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité.
|
||||
Le nouveau code doit utiliser
|
||||
`resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## Guide pas à pas
|
||||
## Procédure pas à pas
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Package et manifeste">
|
||||
Créez les fichiers standards du Plugin. Le champ `channel` dans `package.json`
|
||||
est ce qui en fait un Plugin de canal. Pour la surface complète des métadonnées du package,
|
||||
voir [Plugin Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) :
|
||||
Créez les fichiers de Plugin standard. Le champ `channel` dans `package.json`
|
||||
est ce qui en fait un Plugin de canal. Pour la surface complète des
|
||||
métadonnées de package, consultez
|
||||
[Plugin Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) :
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -290,7 +305,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"kind": "channel",
|
||||
"channels": ["acme-chat"],
|
||||
"name": "Acme Chat",
|
||||
"description": "Plugin de canal Acme Chat",
|
||||
"description": "Acme Chat channel plugin",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@ -314,8 +329,9 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
</Step>
|
||||
|
||||
<Step title="Créer l’objet Plugin de canal">
|
||||
L’interface `ChannelPlugin` comporte de nombreuses surfaces d’adaptateur optionnelles. Commencez par
|
||||
le minimum — `id` et `setup` — puis ajoutez des adaptateurs selon vos besoins.
|
||||
L’interface `ChannelPlugin` possède de nombreuses surfaces d’adaptation
|
||||
facultatives. Commencez par le minimum — `id` et `setup` — puis ajoutez des
|
||||
adaptateurs selon vos besoins.
|
||||
|
||||
Créez `src/channel.ts` :
|
||||
|
||||
@ -325,7 +341,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
createChannelPluginBase,
|
||||
} from "openclaw/plugin-sdk/channel-core";
|
||||
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
|
||||
import { acmeChatApi } from "./client.js"; // votre client API de plateforme
|
||||
import { acmeChatApi } from "./client.js"; // your platform API client
|
||||
|
||||
type ResolvedAccount = {
|
||||
accountId: string | null;
|
||||
@ -366,7 +382,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
},
|
||||
}),
|
||||
|
||||
// Sécurité DM : qui peut envoyer des messages au bot
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -376,21 +392,21 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
},
|
||||
},
|
||||
|
||||
// Appairage : flux d’approbation pour les nouveaux contacts DM
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "nom d’utilisateur Acme Chat",
|
||||
message: "Envoyez ce code pour vérifier votre identité :",
|
||||
idLabel: "Acme Chat username",
|
||||
message: "Send this code to verify your identity:",
|
||||
notify: async ({ target, code }) => {
|
||||
await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Fil des réponses : comment les réponses sont livrées
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// Sortant : envoyer des messages vers la plateforme
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -411,23 +427,24 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
<Accordion title="Ce que createChatChannelPlugin fait pour vous">
|
||||
Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas niveau, vous passez
|
||||
des options déclaratives et le constructeur les compose :
|
||||
Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas
|
||||
niveau, vous fournissez des options déclaratives et le constructeur les
|
||||
compose :
|
||||
|
||||
| Option | Ce qu’elle câble |
|
||||
| Option | Ce qu’elle connecte |
|
||||
| --- | --- |
|
||||
| `security.dm` | Résolveur de sécurité DM à portée limitée depuis les champs de configuration |
|
||||
| `pairing.text` | Flux d’appairage DM basé sur du texte avec échange de code |
|
||||
| `security.dm` | Résolveur de sécurité des messages privés à portée limitée depuis les champs de configuration |
|
||||
| `pairing.text` | Flux d’appairage de messages privés basé sur du texte avec échange de code |
|
||||
| `threading` | Résolveur de mode de réponse (fixe, à portée de compte ou personnalisé) |
|
||||
| `outbound.attachedResults` | Fonctions d’envoi qui renvoient des métadonnées de résultat (identifiants de message) |
|
||||
|
||||
Vous pouvez aussi passer des objets d’adaptateur bruts au lieu des options déclaratives
|
||||
si vous avez besoin d’un contrôle total.
|
||||
Vous pouvez aussi transmettre des objets d’adaptateur bruts au lieu des
|
||||
options déclaratives si vous avez besoin d’un contrôle total.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Câbler le point d’entrée">
|
||||
<Step title="Connecter le point d’entrée">
|
||||
Créez `index.ts` :
|
||||
|
||||
```typescript index.ts
|
||||
@ -437,20 +454,20 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
export default defineChannelPluginEntry({
|
||||
id: "acme-chat",
|
||||
name: "Acme Chat",
|
||||
description: "Plugin de canal Acme Chat",
|
||||
description: "Acme Chat channel plugin",
|
||||
plugin: acmeChatPlugin,
|
||||
registerCliMetadata(api) {
|
||||
api.registerCli(
|
||||
({ program }) => {
|
||||
program
|
||||
.command("acme-chat")
|
||||
.description("Gestion Acme Chat");
|
||||
.description("Acme Chat management");
|
||||
},
|
||||
{
|
||||
descriptors: [
|
||||
{
|
||||
name: "acme-chat",
|
||||
description: "Gestion Acme Chat",
|
||||
description: "Acme Chat management",
|
||||
hasSubcommands: false,
|
||||
},
|
||||
],
|
||||
@ -463,17 +480,20 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
});
|
||||
```
|
||||
|
||||
Placez les descripteurs CLI propres au canal dans `registerCliMetadata(...)` afin qu’OpenClaw
|
||||
puisse les afficher dans l’aide racine sans activer l’exécution complète du canal,
|
||||
tandis que les chargements complets normaux récupèrent toujours les mêmes descripteurs pour le véritable enregistrement
|
||||
des commandes. Réservez `registerFull(...)` au travail réservé à l’exécution.
|
||||
Placez les descripteurs CLI gérés par le canal dans
|
||||
`registerCliMetadata(...)` afin qu’OpenClaw puisse les afficher dans l’aide
|
||||
racine sans activer l’exécution complète du canal, tandis que les
|
||||
chargements complets normaux récupèrent toujours les mêmes descripteurs pour
|
||||
l’enregistrement réel des commandes. Conservez `registerFull(...)` pour le
|
||||
travail réservé à l’exécution.
|
||||
Si `registerFull(...)` enregistre des méthodes RPC Gateway, utilisez un
|
||||
préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) restent réservés et se
|
||||
résolvent toujours vers `operator.admin`.
|
||||
`defineChannelPluginEntry` gère automatiquement la séparation des modes d’enregistrement. Voir
|
||||
[Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour toutes les
|
||||
options.
|
||||
préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur
|
||||
(`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) restent réservés
|
||||
et se résolvent toujours vers `operator.admin`.
|
||||
`defineChannelPluginEntry` gère automatiquement cette séparation des modes
|
||||
d’enregistrement. Consultez
|
||||
[Entry Points](/fr/plugins/sdk-entrypoints#definechannelpluginentry) pour
|
||||
toutes les options.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -487,28 +507,36 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
OpenClaw charge ceci au lieu de l’entrée complète lorsque le canal est désactivé
|
||||
ou non configuré. Cela évite de charger du code d’exécution lourd pendant les flux de configuration.
|
||||
Voir [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de détails.
|
||||
OpenClaw charge ceci à la place du point d’entrée complet lorsque le canal
|
||||
est désactivé ou non configuré. Cela évite de charger du code d’exécution
|
||||
lourd pendant les flux de configuration.
|
||||
Consultez [Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour plus de
|
||||
détails.
|
||||
|
||||
Les canaux d’espace de travail intégrés qui répartissent les exports sûrs
|
||||
pour la configuration dans des modules annexes peuvent utiliser
|
||||
`defineBundledChannelSetupEntry(...)` depuis
|
||||
`openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont aussi besoin
|
||||
d’un setter d’exécution explicite au moment de la configuration.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Gérer les messages entrants">
|
||||
Votre Plugin doit recevoir les messages depuis la plateforme et les transmettre à
|
||||
OpenClaw. Le modèle habituel est un Webhook qui vérifie la requête et
|
||||
la distribue via le gestionnaire entrant de votre canal :
|
||||
Votre Plugin doit recevoir les messages depuis la plateforme et les
|
||||
transférer vers OpenClaw. Le modèle habituel est un Webhook qui vérifie la
|
||||
requête et la distribue via le gestionnaire entrant de votre canal :
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
api.registerHttpRoute({
|
||||
path: "/acme-chat/webhook",
|
||||
auth: "plugin", // authentification gérée par le Plugin (vérifiez vous-même les signatures)
|
||||
auth: "plugin", // plugin-managed auth (verify signatures yourself)
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// Votre gestionnaire entrant distribue le message à OpenClaw.
|
||||
// Le câblage exact dépend de votre SDK de plateforme —
|
||||
// voir un exemple réel dans le package Plugin groupé Microsoft Teams ou Google Chat.
|
||||
// Your inbound handler dispatches the message to OpenClaw.
|
||||
// The exact wiring depends on your platform SDK —
|
||||
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
res.statusCode = 200;
|
||||
@ -520,9 +548,10 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
La gestion des messages entrants est spécifique au canal. Chaque Plugin de canal gère
|
||||
son propre pipeline entrant. Consultez les Plugins de canal groupés
|
||||
(par exemple le package Plugin Microsoft Teams ou Google Chat) pour voir des modèles réels.
|
||||
La gestion des messages entrants est spécifique au canal. Chaque Plugin de
|
||||
canal gère son propre pipeline entrant. Examinez les Plugins de canal
|
||||
intégrés (par exemple le package Plugin Microsoft Teams ou Google Chat)
|
||||
pour voir des modèles réels.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -567,7 +596,7 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Pour les helpers de test partagés, voir [Testing](/fr/plugins/sdk-testing).
|
||||
Pour les helpers de test partagés, consultez [Testing](/fr/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -592,30 +621,31 @@ doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
## Sujets avancés
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Options de fil des réponses" icon="git-branch" href="/fr/plugins/sdk-entrypoints#registration-mode">
|
||||
<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 de message" icon="puzzle" href="/fr/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool et découverte des actions
|
||||
describeMessageTool et découverte d’action
|
||||
</Card>
|
||||
<Card title="Résolution de cible" icon="crosshair" href="/fr/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Helpers d’exécution" icon="settings" href="/fr/plugins/sdk-runtime">
|
||||
TTS, STT, média, sous-agent via api.runtime
|
||||
TTS, STT, médias, sous-agent via api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Certaines jonctions de helpers groupés existent encore pour la maintenance et la
|
||||
compatibilité des Plugins groupés. Elles ne constituent pas le modèle recommandé pour les nouveaux Plugins de canal ;
|
||||
préférez les sous-chemins génériques channel/setup/reply/runtime de la surface SDK
|
||||
commune, sauf si vous maintenez directement cette famille de Plugins groupés.
|
||||
Certaines jonctions de helpers intégrés existent encore pour la maintenance et
|
||||
la compatibilité des Plugins intégrés. Ce n’est pas le modèle recommandé pour
|
||||
les nouveaux Plugins de canal ; préférez les sous-chemins génériques
|
||||
channel/setup/reply/runtime de la surface SDK commune, sauf si vous maintenez
|
||||
directement cette famille de Plugins intégrés.
|
||||
</Note>
|
||||
|
||||
## Étapes suivantes
|
||||
|
||||
- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles
|
||||
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin
|
||||
- [Tests du SDK](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat
|
||||
- [Manifeste de Plugin](/fr/plugins/manifest) — schéma complet du manifeste
|
||||
- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit aussi des modèles
|
||||
- [SDK Overview](/fr/plugins/sdk-overview) — référence complète des imports de sous-chemins
|
||||
- [SDK Testing](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat
|
||||
- [Plugin Manifest](/fr/plugins/manifest) — schéma complet du manifeste
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous avez besoin de la signature de type exacte de `definePluginEntry` ou `defineChannelPluginEntry`
|
||||
- Vous voulez comprendre le mode d’enregistrement (full vs setup vs métadonnées CLI)
|
||||
- Vous recherchez les options des points d’entrée
|
||||
- Vous avez besoin de la signature de type exacte de definePluginEntry ou de defineChannelPluginEntry
|
||||
- Vous souhaitez comprendre le mode d’enregistrement (complet vs configuration vs métadonnées CLI)
|
||||
- Vous recherchez les options de point d’entrée
|
||||
sidebarTitle: Entry Points
|
||||
summary: Référence pour `definePluginEntry`, `defineChannelPluginEntry` et `defineSetupPluginEntry`
|
||||
title: Points d’entrée de plugin
|
||||
summary: Référence pour definePluginEntry, defineChannelPluginEntry et defineSetupPluginEntry
|
||||
title: Points d’entrée du Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:49:58Z"
|
||||
generated_at: "2026-04-15T19:41:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f
|
||||
source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4
|
||||
source_path: plugins/sdk-entrypoints.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Points d’entrée de plugin
|
||||
# Points d’entrée du Plugin
|
||||
|
||||
Chaque plugin exporte un objet d’entrée par défaut. Le SDK fournit trois helpers pour
|
||||
les créer.
|
||||
|
||||
<Tip>
|
||||
**Vous cherchez un guide pas à pas ?** Voir [Plugins de canal](/plugins/sdk-channel-plugins)
|
||||
ou [Plugins de fournisseur](/plugins/sdk-provider-plugins) pour des guides étape par étape.
|
||||
**Vous cherchez un guide pas à pas ?** Consultez [Channel Plugins](/fr/plugins/sdk-channel-plugins)
|
||||
ou [Provider Plugins](/fr/plugins/sdk-provider-plugins) pour des guides étape par étape.
|
||||
</Tip>
|
||||
|
||||
## `definePluginEntry`
|
||||
|
||||
**Import :** `openclaw/plugin-sdk/plugin-entry`
|
||||
**Importation :** `openclaw/plugin-sdk/plugin-entry`
|
||||
|
||||
Pour les plugins de fournisseur, les plugins d’outils, les plugins de hooks, et tout ce qui **n’est pas**
|
||||
un canal de messagerie.
|
||||
@ -60,17 +60,18 @@ export default definePluginEntry({
|
||||
| `register` | `(api: OpenClawPluginApi) => void` | Oui | — |
|
||||
|
||||
- `id` doit correspondre à votre manifeste `openclaw.plugin.json`.
|
||||
- `kind` sert pour les emplacements exclusifs : `"memory"` ou `"context-engine"`.
|
||||
- `kind` est utilisé pour les emplacements exclusifs : `"memory"` ou `"context-engine"`.
|
||||
- `configSchema` peut être une fonction pour une évaluation paresseuse.
|
||||
- OpenClaw résout et met ce schéma en cache lors du premier accès, de sorte que les constructeurs de schéma coûteux
|
||||
- OpenClaw résout et mémorise ce schéma lors du premier accès, donc les générateurs de schéma coûteux
|
||||
ne s’exécutent qu’une seule fois.
|
||||
|
||||
## `defineChannelPluginEntry`
|
||||
|
||||
**Import :** `openclaw/plugin-sdk/channel-core`
|
||||
**Importation :** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Encapsule `definePluginEntry` avec le câblage spécifique aux canaux. Appelle automatiquement
|
||||
`api.registerChannel({ plugin })`, expose une couture facultative de métadonnées CLI d’aide racine, et conditionne `registerFull` au mode d’enregistrement.
|
||||
Encapsule `definePluginEntry` avec un câblage spécifique aux canaux. Appelle automatiquement
|
||||
`api.registerChannel({ plugin })`, expose une jonction facultative de métadonnées CLI
|
||||
pour l’aide racine, et conditionne `registerFull` selon le mode d’enregistrement.
|
||||
|
||||
```typescript
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -101,33 +102,33 @@ export default defineChannelPluginEntry({
|
||||
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Non | — |
|
||||
| `registerFull` | `(api: OpenClawPluginApi) => void` | Non | — |
|
||||
|
||||
- `setRuntime` est appelé pendant l’enregistrement afin que vous puissiez stocker la référence de runtime
|
||||
- `setRuntime` est appelé pendant l’enregistrement afin que vous puissiez stocker la référence d’exécution
|
||||
(généralement via `createPluginRuntimeStore`). Il est ignoré pendant la capture
|
||||
de métadonnées CLI.
|
||||
des métadonnées CLI.
|
||||
- `registerCliMetadata` s’exécute à la fois lorsque `api.registrationMode === "cli-metadata"`
|
||||
et lorsque `api.registrationMode === "full"`.
|
||||
Utilisez-le comme emplacement canonique pour les descripteurs CLI détenus par le canal afin que l’aide racine
|
||||
reste non activante tout en gardant l’enregistrement normal des commandes CLI compatible
|
||||
Utilisez-le comme emplacement canonique pour les descripteurs CLI possédés par le canal afin que l’aide racine
|
||||
reste non activante tout en conservant la compatibilité de l’enregistrement normal des commandes CLI
|
||||
avec les chargements complets de plugins.
|
||||
- `registerFull` ne s’exécute que lorsque `api.registrationMode === "full"`. Il est ignoré
|
||||
lors du chargement setup-only.
|
||||
lors du chargement pour la configuration uniquement.
|
||||
- Comme pour `definePluginEntry`, `configSchema` peut être une fabrique paresseuse et OpenClaw
|
||||
met en cache le schéma résolu lors du premier accès.
|
||||
- Pour les commandes CLI racine détenues par le plugin, préférez `api.registerCli(..., { descriptors: [...] })`
|
||||
lorsque vous voulez que la commande reste chargée paresseusement sans disparaître de
|
||||
l’arbre d’analyse de la CLI racine. Pour les plugins de canal, préférez enregistrer ces descripteurs
|
||||
depuis `registerCliMetadata(...)` et gardez `registerFull(...)` concentré sur le travail réservé au runtime.
|
||||
- Si `registerFull(...)` enregistre aussi des méthodes Gateway RPC, gardez-les sur un
|
||||
préfixe spécifique au plugin. Les espaces de noms d’administration réservés au cœur (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) sont toujours forcés à
|
||||
mémorise le schéma résolu lors du premier accès.
|
||||
- Pour les commandes CLI racine appartenant au plugin, préférez `api.registerCli(..., { descriptors: [...] })`
|
||||
lorsque vous voulez que la commande reste chargée paresseusement sans disparaître de l’arbre
|
||||
d’analyse de la CLI racine. Pour les plugins de canal, préférez enregistrer ces descripteurs
|
||||
depuis `registerCliMetadata(...)` et gardez `registerFull(...)` centré sur le travail réservé à l’exécution.
|
||||
- Si `registerFull(...)` enregistre aussi des méthodes RPC Gateway, conservez-les avec un
|
||||
préfixe spécifique au plugin. Les espaces de noms d’administration du cœur réservés (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) sont toujours forcés en
|
||||
`operator.admin`.
|
||||
|
||||
## `defineSetupPluginEntry`
|
||||
|
||||
**Import :** `openclaw/plugin-sdk/channel-core`
|
||||
**Importation :** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Pour le fichier léger `setup-entry.ts`. Renvoie simplement `{ plugin }` sans
|
||||
câblage runtime ni CLI.
|
||||
Pour le fichier léger `setup-entry.ts`. Retourne simplement `{ plugin }` sans
|
||||
câblage d’exécution ni de CLI.
|
||||
|
||||
```typescript
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -135,33 +136,59 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
OpenClaw charge ceci à la place de l’entrée complète lorsqu’un canal est désactivé,
|
||||
non configuré, ou lorsque le chargement différé est activé. Voir
|
||||
[Setup et configuration](/plugins/sdk-setup#setup-entry) pour savoir quand cela compte.
|
||||
OpenClaw charge ceci au lieu du point d’entrée complet lorsqu’un canal est désactivé,
|
||||
non configuré, ou lorsque le chargement différé est activé. Consultez
|
||||
[Setup and Config](/fr/plugins/sdk-setup#setup-entry) pour savoir quand cela a de l’importance.
|
||||
|
||||
En pratique, associez `defineSetupPluginEntry(...)` aux familles étroites de helpers setup :
|
||||
En pratique, associez `defineSetupPluginEntry(...)` aux familles étroites de helpers de configuration :
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` pour des helpers setup sûrs côté runtime tels que
|
||||
les adaptateurs de patch setup import-safe, la sortie lookup-note,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries`, et les proxys setup délégués
|
||||
- `openclaw/plugin-sdk/channel-setup` pour les surfaces setup à installation facultative
|
||||
- `openclaw/plugin-sdk/setup-tools` pour les helpers setup/install CLI/archive/docs
|
||||
- `openclaw/plugin-sdk/setup-runtime` pour les helpers de configuration sûrs à l’exécution, tels que
|
||||
les adaptateurs de patch de configuration sûrs à l’importation, la sortie de notes de recherche,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries`, et les proxys de configuration délégués
|
||||
- `openclaw/plugin-sdk/channel-setup` pour les surfaces de configuration d’installation facultative
|
||||
- `openclaw/plugin-sdk/setup-tools` pour les helpers de CLI/archive/documentation de configuration et d’installation
|
||||
|
||||
Gardez les SDK lourds, l’enregistrement CLI et les services runtime longue durée dans l’entrée complète.
|
||||
Conservez les SDK lourds, l’enregistrement CLI et les services d’exécution de longue durée dans le point
|
||||
d’entrée complet.
|
||||
|
||||
Les canaux de l’espace de travail groupé qui séparent les surfaces de configuration et d’exécution peuvent utiliser
|
||||
`defineBundledChannelSetupEntry(...)` depuis
|
||||
`openclaw/plugin-sdk/channel-entry-contract` à la place. Ce contrat permet au point d’entrée
|
||||
de configuration de conserver des exportations de plugin/secrets sûres pour la configuration tout en exposant
|
||||
un setter d’exécution :
|
||||
|
||||
```typescript
|
||||
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
|
||||
|
||||
export default defineBundledChannelSetupEntry({
|
||||
importMetaUrl: import.meta.url,
|
||||
plugin: {
|
||||
specifier: "./channel-plugin-api.js",
|
||||
exportName: "myChannelPlugin",
|
||||
},
|
||||
runtime: {
|
||||
specifier: "./runtime-api.js",
|
||||
exportName: "setMyChannelRuntime",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Utilisez ce contrat groupé uniquement lorsque les flux de configuration ont réellement besoin d’un setter
|
||||
d’exécution léger avant le chargement du point d’entrée complet du canal.
|
||||
|
||||
## Mode d’enregistrement
|
||||
|
||||
`api.registrationMode` indique à votre plugin comment il a été chargé :
|
||||
|
||||
| Mode | Quand | Ce qu’il faut enregistrer |
|
||||
| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Démarrage normal de Gateway | Tout |
|
||||
| `"setup-only"` | Canal désactivé/non configuré | Enregistrement du canal uniquement |
|
||||
| `"setup-runtime"` | Flux setup avec runtime disponible | Enregistrement du canal plus uniquement le runtime léger nécessaire avant le chargement de l’entrée complète |
|
||||
| `"cli-metadata"` | Aide racine / capture de métadonnées CLI | Descripteurs CLI uniquement |
|
||||
| Mode | Quand | Ce qu’il faut enregistrer |
|
||||
| ----------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Démarrage normal de Gateway | Tout |
|
||||
| `"setup-only"` | Canal désactivé/non configuré | Enregistrement du canal uniquement |
|
||||
| `"setup-runtime"` | Flux de configuration avec exécution disponible | Enregistrement du canal plus uniquement l’exécution légère nécessaire avant le chargement du point d’entrée complet |
|
||||
| `"cli-metadata"` | Capture de l’aide racine / des métadonnées CLI | Descripteurs CLI uniquement |
|
||||
|
||||
`defineChannelPluginEntry` gère automatiquement cette séparation. Si vous utilisez
|
||||
`definePluginEntry` directement pour un canal, vérifiez vous-même le mode :
|
||||
`definePluginEntry` directement pour un canal, vérifiez le mode vous-même :
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -173,23 +200,23 @@ register(api) {
|
||||
api.registerChannel({ plugin: myPlugin });
|
||||
if (api.registrationMode !== "full") return;
|
||||
|
||||
// Enregistrements lourds réservés au runtime
|
||||
// Heavy runtime-only registrations
|
||||
api.registerService(/* ... */);
|
||||
}
|
||||
```
|
||||
|
||||
Traitez `"setup-runtime"` comme la fenêtre où les surfaces de démarrage setup-only doivent
|
||||
exister sans réentrer dans le runtime complet du canal intégré. Les bonnes utilisations sont
|
||||
l’enregistrement du canal, les routes HTTP setup-safe, les méthodes gateway setup-safe, et
|
||||
les helpers setup délégués. Les services d’arrière-plan lourds, les enregistreurs CLI et
|
||||
les bootstrap SDK fournisseur/client appartiennent toujours à `"full"`.
|
||||
Traitez `"setup-runtime"` comme la fenêtre dans laquelle les surfaces de démarrage réservées à la configuration doivent
|
||||
exister sans réintégrer l’exécution complète du canal groupé. Les bons cas d’usage sont
|
||||
l’enregistrement du canal, les routes HTTP sûres pour la configuration, les méthodes Gateway sûres pour la configuration, et
|
||||
les helpers de configuration délégués. Les services d’arrière-plan lourds, les enregistreurs CLI, et
|
||||
les initialisations de SDK fournisseur/client appartiennent toujours à `"full"`.
|
||||
|
||||
Pour les enregistreurs CLI en particulier :
|
||||
|
||||
- utilisez `descriptors` lorsque l’enregistreur possède une ou plusieurs commandes racine et que vous
|
||||
voulez qu’OpenClaw charge paresseusement le vrai module CLI à la première invocation
|
||||
voulez qu’OpenClaw charge paresseusement le vrai module CLI lors de la première invocation
|
||||
- assurez-vous que ces descripteurs couvrent chaque racine de commande de premier niveau exposée par l’enregistreur
|
||||
- utilisez `commands` seul uniquement pour des chemins de compatibilité eager
|
||||
- utilisez `commands` seul uniquement pour les chemins de compatibilité eager
|
||||
|
||||
## Formes de plugin
|
||||
|
||||
@ -197,17 +224,17 @@ OpenClaw classe les plugins chargés selon leur comportement d’enregistrement
|
||||
|
||||
| Forme | Description |
|
||||
| --------------------- | -------------------------------------------------- |
|
||||
| **plain-capability** | Un seul type de capacité (par ex. fournisseur seul) |
|
||||
| **hybrid-capability** | Plusieurs types de capacité (par ex. fournisseur + speech) |
|
||||
| **plain-capability** | Un seul type de capacité (par ex. fournisseur uniquement) |
|
||||
| **hybrid-capability** | Plusieurs types de capacité (par ex. fournisseur + parole) |
|
||||
| **hook-only** | Seulement des hooks, aucune capacité |
|
||||
| **non-capability** | Outils/commandes/services mais aucune capacité |
|
||||
|
||||
Utilisez `openclaw plugins inspect <id>` pour voir la forme d’un plugin.
|
||||
|
||||
## Liens associés
|
||||
## Voir aussi
|
||||
|
||||
- [Vue d’ensemble du SDK](/plugins/sdk-overview) — API d’enregistrement et référence des sous-chemins
|
||||
- [Helpers runtime](/plugins/sdk-runtime) — `api.runtime` et `createPluginRuntimeStore`
|
||||
- [Setup et configuration](/plugins/sdk-setup) — manifeste, entrée setup, chargement différé
|
||||
- [Plugins de canal](/plugins/sdk-channel-plugins) — construction de l’objet `ChannelPlugin`
|
||||
- [Plugins de fournisseur](/plugins/sdk-provider-plugins) — enregistrement du fournisseur et hooks
|
||||
- [SDK Overview](/fr/plugins/sdk-overview) — API d’enregistrement et référence des sous-chemins
|
||||
- [Runtime Helpers](/fr/plugins/sdk-runtime) — `api.runtime` et `createPluginRuntimeStore`
|
||||
- [Setup and Config](/fr/plugins/sdk-setup) — manifeste, point d’entrée de configuration, chargement différé
|
||||
- [Channel Plugins](/fr/plugins/sdk-channel-plugins) — construction de l’objet `ChannelPlugin`
|
||||
- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — enregistrement des fournisseurs et hooks
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous devez appeler des assistants core depuis un plugin (TTS, STT, génération d’images, recherche web, sous-agent)
|
||||
- Vous devez appeler des assistants du cœur depuis un plugin (TTS, STT, génération d’images, recherche web, sous-agent)
|
||||
- Vous voulez comprendre ce que `api.runtime` expose
|
||||
- Vous accédez à des assistants de configuration, d’agent ou de médias depuis le code du plugin
|
||||
- Vous accédez à des assistants de configuration, d’agent ou de média depuis le code du plugin
|
||||
sidebarTitle: Runtime Helpers
|
||||
summary: api.runtime -- les assistants runtime injectés disponibles pour les plugins
|
||||
title: Assistants runtime des plugins
|
||||
summary: api.runtime -- les assistants d’exécution injectés disponibles pour les plugins
|
||||
title: Assistants d’exécution du Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:53Z"
|
||||
generated_at: "2026-04-15T19:41:44Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be
|
||||
source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Assistants runtime des plugins
|
||||
# Assistants d’exécution du Plugin
|
||||
|
||||
Référence pour l’objet `api.runtime` injecté dans chaque plugin pendant
|
||||
l’enregistrement. Utilisez ces assistants au lieu d’importer directement les internes de l’hôte.
|
||||
l’enregistrement. Utilisez ces assistants au lieu d’importer directement les composants internes de l’hôte.
|
||||
|
||||
<Tip>
|
||||
**Vous cherchez une procédure détaillée ?** Consultez [Plugins de canaux](/fr/plugins/sdk-channel-plugins)
|
||||
ou [Plugins fournisseurs](/fr/plugins/sdk-provider-plugins) pour des guides pas à pas
|
||||
montrant ces assistants dans leur contexte.
|
||||
**Vous cherchez un guide pas à pas ?** Consultez [Plugins de canal](/fr/plugins/sdk-channel-plugins)
|
||||
ou [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) pour des guides étape par étape
|
||||
qui montrent ces assistants dans leur contexte.
|
||||
</Tip>
|
||||
|
||||
```typescript
|
||||
@ -32,7 +32,7 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
## Espaces de noms runtime
|
||||
## Espaces de noms d’exécution
|
||||
|
||||
### `api.runtime.agent`
|
||||
|
||||
@ -70,12 +70,12 @@ const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` est l’assistant neutre pour démarrer un tour d’agent OpenClaw
|
||||
normal depuis le code du plugin. Il utilise la même résolution fournisseur/modèle et
|
||||
la même sélection d’agent harness que les réponses déclenchées par canal.
|
||||
normal depuis le code du plugin. Il utilise la même résolution de fournisseur/modèle et
|
||||
la même sélection du harnais d’agent que les réponses déclenchées par un canal.
|
||||
|
||||
`runEmbeddedPiAgent(...)` reste un alias de compatibilité.
|
||||
|
||||
Les **assistants de stockage de session** se trouvent sous `api.runtime.agent.session` :
|
||||
Les **assistants du magasin de sessions** se trouvent sous `api.runtime.agent.session` :
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -86,11 +86,11 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId
|
||||
|
||||
### `api.runtime.agent.defaults`
|
||||
|
||||
Constantes de fournisseur et de modèle par défaut :
|
||||
Constantes de modèle et de fournisseur par défaut :
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // ex. "anthropic/claude-sonnet-4-6"
|
||||
const provider = api.runtime.agent.defaults.provider; // ex. "anthropic"
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
|
||||
```
|
||||
|
||||
### `api.runtime.subagent`
|
||||
@ -123,15 +123,15 @@ await api.runtime.subagent.deleteSession({
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Les remplacements de modèle (`provider`/`model`) nécessitent l’activation explicite de l’opérateur via
|
||||
Les remplacements de modèle (`provider`/`model`) nécessitent un opt-in de l’opérateur via
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` dans la configuration.
|
||||
Les plugins non fiables peuvent toujours exécuter des sous-agents, mais les demandes de remplacement sont rejetées.
|
||||
</Warning>
|
||||
|
||||
### `api.runtime.taskFlow`
|
||||
|
||||
Lier un runtime Task Flow à une clé de session OpenClaw existante ou à un contexte
|
||||
d’outil de confiance, puis créer et gérer des Task Flows sans passer un propriétaire à chaque appel.
|
||||
Lier un runtime TaskFlow à une clé de session OpenClaw existante ou à un contexte
|
||||
d’outil de confiance, puis créer et gérer des TaskFlow sans transmettre un propriétaire à chaque appel.
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
@ -158,8 +158,8 @@ const waiting = taskFlow.setWaiting({
|
||||
});
|
||||
```
|
||||
|
||||
Utilisez `bindSession({ sessionKey, requesterOrigin })` lorsque vous avez déjà une
|
||||
clé de session OpenClaw de confiance issue de votre propre couche de liaison. Ne liez pas à partir d’une entrée utilisateur brute.
|
||||
Utilisez `bindSession({ sessionKey, requesterOrigin })` lorsque vous disposez déjà d’une
|
||||
clé de session OpenClaw de confiance provenant de votre propre couche de liaison. N’effectuez pas de liaison à partir d’une entrée utilisateur brute.
|
||||
|
||||
### `api.runtime.tts`
|
||||
|
||||
@ -185,8 +185,8 @@ const voices = await api.runtime.tts.listVoices({
|
||||
});
|
||||
```
|
||||
|
||||
Utilise la configuration core `messages.tts` et la sélection du fournisseur. Renvoie un tampon audio PCM
|
||||
et un taux d’échantillonnage.
|
||||
Utilise la configuration centrale `messages.tts` et la sélection de fournisseur. Renvoie un
|
||||
tampon audio PCM + une fréquence d’échantillonnage.
|
||||
|
||||
### `api.runtime.mediaUnderstanding`
|
||||
|
||||
@ -340,10 +340,10 @@ api.runtime.tools.registerMemoryCli(/* ... */);
|
||||
|
||||
### `api.runtime.channel`
|
||||
|
||||
Assistants runtime spécifiques aux canaux (disponibles lorsqu’un plugin de canal est chargé).
|
||||
Assistants d’exécution spécifiques au canal (disponibles lorsqu’un plugin de canal est chargé).
|
||||
|
||||
`api.runtime.channel.mentions` est la surface partagée de politique de mention entrante pour
|
||||
les plugins de canaux intégrés qui utilisent l’injection runtime :
|
||||
`api.runtime.channel.mentions` est la surface partagée de stratégie de mention entrante pour les
|
||||
plugins de canal intégrés qui utilisent l’injection du runtime :
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -382,16 +382,19 @@ Assistants de mention disponibles :
|
||||
assistants de compatibilité `resolveMentionGating*`. Préférez le chemin normalisé
|
||||
`{ facts, policy }`.
|
||||
|
||||
## Stocker des références runtime
|
||||
## Stockage des références de runtime
|
||||
|
||||
Utilisez `createPluginRuntimeStore` pour stocker la référence runtime afin de l’utiliser en dehors
|
||||
Utilisez `createPluginRuntimeStore` pour stocker la référence du runtime en vue d’une utilisation en dehors
|
||||
du callback `register` :
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "my-plugin",
|
||||
errorMessage: "my-plugin runtime not initialized",
|
||||
});
|
||||
|
||||
// In your entry point
|
||||
export default defineChannelPluginEntry({
|
||||
@ -412,22 +415,25 @@ export function tryGetRuntime() {
|
||||
}
|
||||
```
|
||||
|
||||
Préférez `pluginId` pour l’identité du runtime-store. La forme de niveau inférieur `key` est
|
||||
destinée aux cas peu courants où un plugin a intentionnellement besoin de plus d’un emplacement de runtime.
|
||||
|
||||
## Autres champs `api` de niveau supérieur
|
||||
|
||||
Au-delà de `api.runtime`, l’objet API fournit également :
|
||||
Au-delà de `api.runtime`, l’objet API fournit aussi :
|
||||
|
||||
| Champ | Type | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Identifiant du plugin |
|
||||
| `api.name` | `string` | Nom d’affichage du plugin |
|
||||
| `api.config` | `OpenClawConfig` | Instantané actuel de la configuration (instantané runtime actif en mémoire lorsqu’il est disponible) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Configuration spécifique au plugin provenant de `plugins.entries.<id>.config` |
|
||||
| `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.id` | `string` | ID du Plugin |
|
||||
| `api.name` | `string` | Nom d’affichage du Plugin |
|
||||
| `api.config` | `OpenClawConfig` | Instantané actuel de la configuration (instantané actif du runtime en mémoire lorsqu’il est disponible) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Configuration spécifique au Plugin provenant de `plugins.entries.<id>.config` |
|
||||
| `api.logger` | `PluginLogger` | Logger à portée limitée (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Mode de chargement actuel ; `"setup-runtime"` est la fenêtre légère de démarrage/configuration avant l’entrée complète |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Résoudre un chemin relatif à la racine du plugin |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Résout un chemin relatif à la racine du Plugin |
|
||||
|
||||
## Voir aussi
|
||||
## Lié
|
||||
|
||||
- [Aperçu du SDK](/fr/plugins/sdk-overview) -- référence de sous-chemin
|
||||
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) -- référence des sous-chemins
|
||||
- [Points d’entrée du SDK](/fr/plugins/sdk-entrypoints) -- options de `definePluginEntry`
|
||||
- [Internes des plugins](/fr/plugins/architecture) -- modèle de capacités et registre
|
||||
- [Composants internes du Plugin](/fr/plugins/architecture) -- modèle de capacités et registre
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous ajoutez un assistant de configuration à un plugin
|
||||
- Vous devez comprendre setup-entry.ts par rapport à index.ts
|
||||
- Vous définissez des schémas de configuration de plugin ou des métadonnées `openclaw` dans package.json
|
||||
- Vous ajoutez un assistant de configuration à un Plugin
|
||||
- Vous devez comprendre `setup-entry.ts` par rapport à `index.ts`
|
||||
- Vous définissez des schémas de configuration du Plugin ou des métadonnées `openclaw` dans `package.json`
|
||||
sidebarTitle: Setup and Config
|
||||
summary: Assistants de configuration, setup-entry.ts, schémas de configuration et métadonnées package.json
|
||||
title: Configuration et setup des plugins
|
||||
summary: Assistants de configuration, `setup-entry.ts`, schémas de configuration et métadonnées de `package.json`
|
||||
title: Configuration et config du Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:10:26Z"
|
||||
generated_at: "2026-04-15T19:41:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9
|
||||
source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
|
||||
source_path: plugins/sdk-setup.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Configuration et setup des plugins
|
||||
# Configuration et config du Plugin
|
||||
|
||||
Référence pour le packaging des plugins (métadonnées `package.json`), les manifestes
|
||||
(`openclaw.plugin.json`), les entrées de setup et les schémas de configuration.
|
||||
Référence pour le packaging des Plugins (métadonnées `package.json`), les manifestes
|
||||
(`openclaw.plugin.json`), les entrées de configuration et les schémas de config.
|
||||
|
||||
<Tip>
|
||||
**Vous cherchez un guide pas à pas ?** Les guides pratiques couvrent le packaging dans son contexte :
|
||||
[Plugins de canal](/fr/plugins/sdk-channel-plugins#step-1-package-and-manifest) et
|
||||
[Plugins de fournisseur](/fr/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
[Plugins de canaux](/fr/plugins/sdk-channel-plugins#step-1-package-and-manifest) et
|
||||
[Plugins de fournisseurs](/fr/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
</Tip>
|
||||
|
||||
## Métadonnées du package
|
||||
|
||||
Votre `package.json` doit contenir un champ `openclaw` qui indique au système de plugins ce
|
||||
que fournit votre plugin :
|
||||
Votre `package.json` doit contenir un champ `openclaw` qui indique au système de Plugin ce
|
||||
que votre Plugin fournit :
|
||||
|
||||
**Plugin de canal :**
|
||||
|
||||
@ -50,7 +50,7 @@ que fournit votre plugin :
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin de fournisseur / base de publication ClawHub :**
|
||||
**Plugin de fournisseur / référence de publication ClawHub :**
|
||||
|
||||
```json openclaw-clawhub-package.json
|
||||
{
|
||||
@ -71,7 +71,7 @@ que fournit votre plugin :
|
||||
}
|
||||
```
|
||||
|
||||
Si vous publiez le plugin en externe sur ClawHub, ces champs `compat` et `build`
|
||||
Si vous publiez le Plugin en externe sur ClawHub, ces champs `compat` et `build`
|
||||
sont obligatoires. Les extraits canoniques de publication se trouvent dans
|
||||
`docs/snippets/plugin-publish/`.
|
||||
|
||||
@ -80,38 +80,38 @@ sont obligatoires. Les extraits canoniques de publication se trouvent dans
|
||||
| Champ | Type | Description |
|
||||
| ------------ | ---------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Fichiers de point d’entrée (relatifs à la racine du package) |
|
||||
| `setupEntry` | `string` | Entrée légère réservée au setup (facultative) |
|
||||
| `channel` | `object` | Métadonnées du catalogue de canaux pour les surfaces de setup, de sélection, de démarrage rapide et d’état |
|
||||
| `providers` | `string[]` | Identifiants de fournisseurs enregistrés par ce plugin |
|
||||
| `setupEntry` | `string` | Entrée légère réservée à la configuration (facultatif) |
|
||||
| `channel` | `object` | Métadonnées du catalogue de canaux pour les surfaces de configuration, de sélection, de démarrage rapide et d’état |
|
||||
| `providers` | `string[]` | Identifiants de fournisseurs enregistrés par ce Plugin |
|
||||
| `install` | `object` | Indications d’installation : `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` |
|
||||
| `startup` | `object` | Drapeaux de comportement au démarrage |
|
||||
| `startup` | `object` | Indicateurs de comportement au démarrage |
|
||||
|
||||
### `openclaw.channel`
|
||||
|
||||
`openclaw.channel` contient des métadonnées légères du package pour les surfaces de découverte et de setup
|
||||
des canaux avant le chargement de l’exécution.
|
||||
`openclaw.channel` correspond à des métadonnées de package peu coûteuses pour la découverte des canaux et les
|
||||
surfaces de configuration avant le chargement de l’exécution.
|
||||
|
||||
| Champ | Type | Signification |
|
||||
| -------------------------------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `id` | `string` | Identifiant canonique du canal. |
|
||||
| `label` | `string` | Libellé principal du canal. |
|
||||
| `selectionLabel` | `string` | Libellé de sélection/setup lorsqu’il doit différer de `label`. |
|
||||
| Champ | Type | Signification |
|
||||
| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `id` | `string` | Identifiant canonique du canal. |
|
||||
| `label` | `string` | Libellé principal du canal. |
|
||||
| `selectionLabel` | `string` | Libellé du sélecteur/de la configuration lorsqu’il doit différer de `label`. |
|
||||
| `detailLabel` | `string` | Libellé de détail secondaire pour des catalogues de canaux et surfaces d’état plus riches. |
|
||||
| `docsPath` | `string` | Chemin de documentation pour les liens de setup et de sélection. |
|
||||
| `docsLabel` | `string` | Libellé de remplacement utilisé pour les liens de documentation lorsqu’il doit différer de l’identifiant du canal. |
|
||||
| `blurb` | `string` | Courte description d’onboarding/catalogue. |
|
||||
| `order` | `number` | Ordre de tri dans les catalogues de canaux. |
|
||||
| `aliases` | `string[]` | Alias supplémentaires pour la sélection du canal. |
|
||||
| `preferOver` | `string[]` | Identifiants de plugin/canal de priorité plus basse que ce canal doit surpasser. |
|
||||
| `systemImage` | `string` | Nom facultatif d’icône/system-image pour les catalogues UI de canaux. |
|
||||
| `selectionDocsPrefix` | `string` | Texte préfixe avant les liens de documentation dans les surfaces de sélection. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Afficher directement le chemin de documentation au lieu d’un lien documenté avec libellé dans le texte de sélection. |
|
||||
| `selectionExtras` | `string[]` | Courtes chaînes supplémentaires ajoutées dans le texte de sélection. |
|
||||
| `markdownCapable` | `boolean` | Marque le canal comme compatible Markdown pour les décisions de formatage sortant. |
|
||||
| `exposure` | `object` | Contrôles de visibilité du canal pour les surfaces de setup, de listes configurées et de documentation. |
|
||||
| `quickstartAllowFrom` | `boolean` | Fait participer ce canal au flux standard de setup rapide `allowFrom`. |
|
||||
| `forceAccountBinding` | `boolean` | Exige un rattachement de compte explicite même lorsqu’un seul compte existe. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Privilégie la recherche de session lors de la résolution des cibles d’annonce pour ce canal. |
|
||||
| `docsPath` | `string` | Chemin de documentation pour les liens de configuration et de sélection. |
|
||||
| `docsLabel` | `string` | Libellé de remplacement utilisé pour les liens vers la documentation lorsqu’il doit différer de l’identifiant du canal. |
|
||||
| `blurb` | `string` | Brève description d’onboarding/de catalogue. |
|
||||
| `order` | `number` | Ordre de tri dans les catalogues de canaux. |
|
||||
| `aliases` | `string[]` | Alias de recherche supplémentaires pour la sélection du canal. |
|
||||
| `preferOver` | `string[]` | Identifiants de Plugin/canal de priorité inférieure que ce canal doit dépasser. |
|
||||
| `systemImage` | `string` | Nom facultatif d’icône/d’image système pour les catalogues d’interface des canaux. |
|
||||
| `selectionDocsPrefix` | `string` | Texte préfixe avant les liens vers la documentation dans les surfaces de sélection. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Affiche directement le chemin de documentation au lieu d’un lien libellé dans le texte de sélection. |
|
||||
| `selectionExtras` | `string[]` | Chaînes courtes supplémentaires ajoutées dans le texte de sélection. |
|
||||
| `markdownCapable` | `boolean` | Indique que le canal prend en charge le Markdown pour les décisions de mise en forme sortante. |
|
||||
| `exposure` | `object` | Contrôles de visibilité du canal pour la configuration, les listes configurées et les surfaces de documentation. |
|
||||
| `quickstartAllowFrom` | `boolean` | Active pour ce canal le flux standard de configuration rapide `allowFrom`. |
|
||||
| `forceAccountBinding` | `boolean` | Exige une liaison explicite de compte même lorsqu’un seul compte existe. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Préfère la recherche de session lors de la résolution des cibles d’annonce pour ce canal. |
|
||||
|
||||
Exemple :
|
||||
|
||||
@ -146,36 +146,35 @@ Exemple :
|
||||
`exposure` prend en charge :
|
||||
|
||||
- `configured` : inclure le canal dans les surfaces de liste de type configuré/état
|
||||
- `setup` : inclure le canal dans les sélecteurs interactifs de setup/configuration
|
||||
- `docs` : marquer le canal comme orienté public dans les surfaces de documentation/navigation
|
||||
- `setup` : inclure le canal dans les sélecteurs interactifs de configuration/configurer
|
||||
- `docs` : marquer le canal comme visible publiquement dans les surfaces de documentation/navigation
|
||||
|
||||
`showConfigured` et `showInSetup` restent pris en charge comme alias historiques. Préférez
|
||||
`showConfigured` et `showInSetup` restent pris en charge comme alias hérités. Préférez
|
||||
`exposure`.
|
||||
|
||||
### `openclaw.install`
|
||||
|
||||
`openclaw.install` est une métadonnée de package, pas une métadonnée de manifeste.
|
||||
|
||||
| Champ | Type | Signification |
|
||||
| ---------------------------- | -------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `npmSpec` | `string` | Spécification npm canonique pour les flux d’installation/mise à jour. |
|
||||
| `localPath` | `string` | Chemin d’installation local de développement ou groupé. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Source d’installation préférée lorsque les deux sont disponibles. |
|
||||
| `minHostVersion` | `string` | Version minimale d’OpenClaw prise en charge, sous la forme `>=x.y.z`. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Permet aux flux de réinstallation de plugin groupé de récupérer après certains échecs dus à une configuration obsolète. |
|
||||
| Champ | Type | Signification |
|
||||
| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- |
|
||||
| `npmSpec` | `string` | Spécification npm canonique pour les flux d’installation/de mise à jour. |
|
||||
| `localPath` | `string` | Chemin d’installation local de développement ou intégré. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Source d’installation préférée lorsque les deux sont disponibles. |
|
||||
| `minHostVersion` | `string` | Version minimale prise en charge d’OpenClaw sous la forme `>=x.y.z`. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Permet aux flux de réinstallation de Plugins intégrés de récupérer de certaines erreurs de configuration obsolète. |
|
||||
|
||||
Si `minHostVersion` est défini, l’installation et le chargement du registre de manifestes
|
||||
l’appliquent tous deux. Les hôtes plus anciens ignorent le plugin ; les chaînes de version invalides sont rejetées.
|
||||
Si `minHostVersion` est défini, l’installation et le chargement du registre de manifestes l’appliquent tous deux.
|
||||
Les hôtes plus anciens ignorent le Plugin ; les chaînes de version invalides sont rejetées.
|
||||
|
||||
`allowInvalidConfigRecovery` n’est pas un contournement général des configurations cassées. Il sert
|
||||
uniquement à la récupération étroite de plugins groupés, afin que la réinstallation/le setup puisse réparer des restes
|
||||
connus de mise à niveau comme un chemin de plugin groupé manquant ou une entrée `channels.<id>`
|
||||
obsolète pour ce même plugin. Si la configuration est cassée pour des raisons non liées, l’installation
|
||||
échoue quand même de façon fermée et indique à l’opérateur d’exécuter `openclaw doctor --fix`.
|
||||
`allowInvalidConfigRecovery` n’est pas un contournement général pour des configurations cassées. Il sert
|
||||
uniquement à une récupération ciblée pour les Plugins intégrés, afin que la réinstallation/la configuration puisse corriger des restes connus de mise à niveau comme un chemin de Plugin intégré manquant ou une entrée `channels.<id>`
|
||||
obsolète pour ce même Plugin. Si la configuration est cassée pour des raisons sans rapport, l’installation
|
||||
échoue quand même de manière sûre et indique à l’opérateur d’exécuter `openclaw doctor --fix`.
|
||||
|
||||
### Chargement complet différé
|
||||
|
||||
Les plugins de canal peuvent choisir le chargement différé avec :
|
||||
Les Plugins de canaux peuvent activer le chargement différé avec :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -189,26 +188,25 @@ Les plugins de canal peuvent choisir le chargement différé avec :
|
||||
}
|
||||
```
|
||||
|
||||
Lorsqu’il est activé, OpenClaw ne charge que `setupEntry` pendant la phase de démarrage
|
||||
précédant l’écoute, même pour les canaux déjà configurés. L’entrée complète est chargée après
|
||||
le début de l’écoute de la gateway.
|
||||
Lorsqu’elle est activée, OpenClaw charge uniquement `setupEntry` pendant la phase de démarrage avant l’écoute,
|
||||
même pour les canaux déjà configurés. Le point d’entrée complet est chargé une fois que la Gateway commence à écouter.
|
||||
|
||||
<Warning>
|
||||
N’activez le chargement différé que si votre `setupEntry` enregistre tout ce dont la
|
||||
gateway a besoin avant de commencer à écouter (enregistrement du canal, routes HTTP,
|
||||
méthodes de gateway). Si l’entrée complète possède des capacités requises au démarrage, conservez
|
||||
Gateway a besoin avant de commencer à écouter (enregistrement du canal, routes HTTP,
|
||||
méthodes Gateway). Si le point d’entrée complet possède des capacités de démarrage requises, conservez
|
||||
le comportement par défaut.
|
||||
</Warning>
|
||||
|
||||
Si votre setup/entrée complète enregistre des méthodes RPC de gateway, conservez-les sur un
|
||||
préfixe spécifique au plugin. Les espaces de noms d’administration du noyau réservés (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) restent possédés par le noyau et sont toujours résolus
|
||||
Si votre entrée de configuration/complète enregistre des méthodes RPC Gateway, conservez-les sur un
|
||||
préfixe spécifique au Plugin. Les espaces de noms d’administration du cœur réservés (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) restent la propriété du cœur et sont toujours résolus
|
||||
vers `operator.admin`.
|
||||
|
||||
## Manifeste du plugin
|
||||
## Manifeste du Plugin
|
||||
|
||||
Chaque plugin natif doit livrer un `openclaw.plugin.json` à la racine du package.
|
||||
OpenClaw l’utilise pour valider la configuration sans exécuter le code du plugin.
|
||||
Chaque Plugin natif doit fournir un `openclaw.plugin.json` à la racine du package.
|
||||
OpenClaw l’utilise pour valider la configuration sans exécuter le code du Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -228,7 +226,7 @@ OpenClaw l’utilise pour valider la configuration sans exécuter le code du plu
|
||||
}
|
||||
```
|
||||
|
||||
Pour les plugins de canal, ajoutez `kind` et `channels` :
|
||||
Pour les Plugins de canaux, ajoutez `kind` et `channels` :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -243,7 +241,7 @@ Pour les plugins de canal, ajoutez `kind` et `channels` :
|
||||
}
|
||||
```
|
||||
|
||||
Même les plugins sans configuration doivent livrer un schéma. Un schéma vide est valide :
|
||||
Même les Plugins sans configuration doivent fournir un schéma. Un schéma vide est valide :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -255,25 +253,25 @@ Même les plugins sans configuration doivent livrer un schéma. Un schéma vide
|
||||
}
|
||||
```
|
||||
|
||||
Voir [Manifeste de plugin](/fr/plugins/manifest) pour la référence complète du schéma.
|
||||
Voir [Manifeste du Plugin](/fr/plugins/manifest) pour la référence complète du schéma.
|
||||
|
||||
## Publication sur ClawHub
|
||||
## Publication ClawHub
|
||||
|
||||
Pour les packages de plugins, utilisez la commande ClawHub spécifique au package :
|
||||
Pour les packages de Plugin, utilisez la commande ClawHub spécifique au package :
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
L’ancien alias de publication réservé aux skills concerne les skills. Les packages de plugins doivent
|
||||
L’ancien alias de publication réservé aux Skills concerne les Skills. Les packages de Plugin doivent
|
||||
toujours utiliser `clawhub package publish`.
|
||||
|
||||
## Entrée de setup
|
||||
## Entrée de configuration
|
||||
|
||||
Le fichier `setup-entry.ts` est une alternative légère à `index.ts` que
|
||||
OpenClaw charge lorsqu’il n’a besoin que des surfaces de setup (onboarding, réparation de configuration,
|
||||
inspection de canal désactivé).
|
||||
OpenClaw charge lorsqu’il n’a besoin que des surfaces de configuration (onboarding, réparation de config,
|
||||
inspection des canaux désactivés).
|
||||
|
||||
```typescript
|
||||
// setup-entry.ts
|
||||
@ -284,75 +282,79 @@ export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
Cela évite de charger du code d’exécution lourd (bibliothèques de chiffrement, enregistrements CLI,
|
||||
services d’arrière-plan) pendant les flux de setup.
|
||||
services en arrière-plan) pendant les flux de configuration.
|
||||
|
||||
**Quand OpenClaw utilise `setupEntry` au lieu de l’entrée complète :**
|
||||
Les canaux d’espace de travail intégrés qui conservent des exports sûrs pour la configuration dans des modules annexes peuvent
|
||||
utiliser `defineBundledChannelSetupEntry(...)` depuis
|
||||
`openclaw/plugin-sdk/channel-entry-contract` au lieu de
|
||||
`defineSetupPluginEntry(...)`. Ce contrat intégré prend également en charge un export `runtime`
|
||||
facultatif afin que le câblage de l’exécution au moment de la configuration reste léger et explicite.
|
||||
|
||||
- Le canal est désactivé mais a besoin des surfaces de setup/onboarding
|
||||
**Quand OpenClaw utilise `setupEntry` au lieu du point d’entrée complet :**
|
||||
|
||||
- Le canal est désactivé mais a besoin de surfaces de configuration/d’onboarding
|
||||
- Le canal est activé mais non configuré
|
||||
- Le chargement différé est activé (`deferConfiguredChannelFullLoadUntilAfterListen`)
|
||||
|
||||
**Ce que `setupEntry` doit enregistrer :**
|
||||
|
||||
- L’objet plugin de canal (via `defineSetupPluginEntry`)
|
||||
- Toute route HTTP requise avant l’écoute de la gateway
|
||||
- Toute méthode de gateway nécessaire au démarrage
|
||||
- L’objet Plugin de canal (via `defineSetupPluginEntry`)
|
||||
- Toute route HTTP requise avant l’écoute de la Gateway
|
||||
- Toute méthode Gateway nécessaire au démarrage
|
||||
|
||||
Ces méthodes de gateway de démarrage doivent toujours éviter les espaces de noms
|
||||
d’administration du noyau réservés comme `config.*` ou `update.*`.
|
||||
Ces méthodes Gateway de démarrage doivent toujours éviter les espaces de noms d’administration du cœur
|
||||
réservés tels que `config.*` ou `update.*`.
|
||||
|
||||
**Ce que `setupEntry` ne doit PAS inclure :**
|
||||
|
||||
- Enregistrements CLI
|
||||
- Services d’arrière-plan
|
||||
- Imports d’exécution lourds (crypto, SDK)
|
||||
- Méthodes de gateway nécessaires uniquement après le démarrage
|
||||
- Services en arrière-plan
|
||||
- Imports d’exécution lourds (chiffrement, SDK)
|
||||
- Méthodes Gateway nécessaires uniquement après le démarrage
|
||||
|
||||
### Imports d’assistants de setup étroits
|
||||
### Imports d’assistants de configuration ciblés
|
||||
|
||||
Pour les chemins chauds réservés au setup, préférez les points d’accès étroits des assistants de setup plutôt que le point d’accès plus large
|
||||
`plugin-sdk/setup` lorsque vous n’avez besoin que d’une partie de la surface de setup :
|
||||
Pour les chemins critiques réservés à la configuration, préférez les points d’accès d’assistants de configuration ciblés plutôt que le point d’accès plus large
|
||||
`plugin-sdk/setup` lorsque vous n’avez besoin que d’une partie de la surface de configuration :
|
||||
|
||||
| Chemin d’import | À utiliser pour | Exports clés |
|
||||
| ----------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | assistants d’exécution au moment du setup qui restent disponibles dans `setupEntry` / démarrage différé de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | adaptateurs de setup de compte sensibles à l’environnement | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | assistants setup/install CLI/archive/documentation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| Chemin d’import | À utiliser pour | Exports clés |
|
||||
| ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | assistants d’exécution au moment de la configuration qui restent disponibles dans `setupEntry` / le démarrage différé du canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | adaptateurs de configuration de compte sensibles à l’environnement | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | assistants CLI/archive/documentation de configuration/installation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
|
||||
Utilisez le point d’accès plus large `plugin-sdk/setup` lorsque vous voulez la boîte à outils de setup partagée complète,
|
||||
y compris les assistants de patch de configuration tels que
|
||||
Utilisez le point d’accès plus large `plugin-sdk/setup` lorsque vous souhaitez l’ensemble complet de la boîte à outils de configuration partagée, y compris les assistants de correctif de configuration tels que
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
|
||||
|
||||
Les adaptateurs de patch de setup restent sûrs pour le chemin chaud à l’import. Leur recherche groupée
|
||||
de surface de contrat de promotion de compte unique est paresseuse, donc l’import de
|
||||
`plugin-sdk/setup-runtime` ne charge pas de manière anticipée la découverte de surface de contrat groupée avant que l’adaptateur soit réellement utilisé.
|
||||
Les adaptateurs de correctif de configuration restent sûrs à l’importation sur les chemins critiques. Leur
|
||||
recherche de surface de contrat de promotion de compte unique intégrée est paresseuse ; ainsi, l’import de
|
||||
`plugin-sdk/setup-runtime` ne charge pas de manière anticipée la découverte de surface de contrat intégrée avant l’utilisation effective de l’adaptateur.
|
||||
|
||||
### Promotion de compte unique possédée par le canal
|
||||
### Promotion de compte unique gérée par le canal
|
||||
|
||||
Lorsqu’un canal passe d’une configuration de niveau supérieur à compte unique vers
|
||||
Lorsqu’un canal passe d’une config de niveau supérieur à compte unique à
|
||||
`channels.<id>.accounts.*`, le comportement partagé par défaut consiste à déplacer les
|
||||
valeurs promues à portée de compte dans `accounts.default`.
|
||||
valeurs promues de portée compte dans `accounts.default`.
|
||||
|
||||
Les canaux groupés peuvent restreindre ou remplacer cette promotion via leur surface de contrat
|
||||
de setup :
|
||||
Les canaux intégrés peuvent restreindre ou remplacer cette promotion via leur surface de contrat de configuration :
|
||||
|
||||
- `singleAccountKeysToMove` : clés supplémentaires de niveau supérieur qui doivent être déplacées dans le
|
||||
- `singleAccountKeysToMove` : clés supplémentaires de niveau supérieur qui doivent être déplacées vers le
|
||||
compte promu
|
||||
- `namedAccountPromotionKeys` : lorsque des comptes nommés existent déjà, seules ces
|
||||
clés sont déplacées dans le compte promu ; les clés partagées de politique/livraison restent à la
|
||||
racine du canal
|
||||
clés sont déplacées vers le compte promu ; les clés partagées de stratégie/de distribution restent à la racine
|
||||
du canal
|
||||
- `resolveSingleAccountPromotionTarget(...)` : choisit quel compte existant
|
||||
reçoit les valeurs promues
|
||||
|
||||
Matrix est l’exemple groupé actuel. Si exactement un compte Matrix nommé
|
||||
existe déjà, ou si `defaultAccount` pointe vers une clé existante non canonique
|
||||
telle que `Ops`, la promotion conserve ce compte au lieu de créer une nouvelle
|
||||
Matrix est l’exemple intégré actuel. Si exactement un compte Matrix nommé existe déjà,
|
||||
ou si `defaultAccount` pointe vers une clé existante non canonique telle que
|
||||
`Ops`, la promotion préserve ce compte au lieu de créer une nouvelle
|
||||
entrée `accounts.default`.
|
||||
|
||||
## Schéma de configuration
|
||||
## Schéma de config
|
||||
|
||||
La configuration du plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs
|
||||
configurent les plugins via :
|
||||
La config du Plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs
|
||||
configurent les Plugins via :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -368,9 +370,9 @@ configurent les plugins via :
|
||||
}
|
||||
```
|
||||
|
||||
Votre plugin reçoit cette configuration sous la forme `api.pluginConfig` pendant l’enregistrement.
|
||||
Votre Plugin reçoit cette config sous la forme de `api.pluginConfig` lors de l’enregistrement.
|
||||
|
||||
Pour une configuration spécifique à un canal, utilisez plutôt la section de configuration du canal :
|
||||
Pour une config spécifique au canal, utilisez plutôt la section de config du canal :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -383,10 +385,10 @@ Pour une configuration spécifique à un canal, utilisez plutôt la section de c
|
||||
}
|
||||
```
|
||||
|
||||
### Construire des schémas de configuration de canal
|
||||
### Création de schémas de config de canal
|
||||
|
||||
Utilisez `buildChannelConfigSchema` depuis `openclaw/plugin-sdk/core` pour convertir un
|
||||
schéma Zod dans l’enveloppe `ChannelConfigSchema` qu’OpenClaw valide :
|
||||
schéma Zod en l’enveloppe `ChannelConfigSchema` que OpenClaw valide :
|
||||
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
@ -404,7 +406,7 @@ const configSchema = buildChannelConfigSchema(accountSchema);
|
||||
|
||||
## Assistants de configuration
|
||||
|
||||
Les plugins de canal peuvent fournir des assistants de configuration interactifs pour `openclaw onboard`.
|
||||
Les Plugins de canaux peuvent fournir des assistants de configuration interactifs pour `openclaw onboard`.
|
||||
L’assistant est un objet `ChannelSetupWizard` sur le `ChannelPlugin` :
|
||||
|
||||
```typescript
|
||||
@ -439,22 +441,21 @@ const setupWizard: ChannelSetupWizard = {
|
||||
```
|
||||
|
||||
Le type `ChannelSetupWizard` prend en charge `credentials`, `textInputs`,
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, etc.
|
||||
Consultez les packages de plugins groupés (par exemple le plugin Discord `src/channel.setup.ts`) pour
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize`, et plus encore.
|
||||
Consultez les packages de Plugins intégrés (par exemple le Plugin Discord `src/channel.setup.ts`) pour
|
||||
des exemples complets.
|
||||
|
||||
Pour les invites de liste d’autorisation DM qui n’ont besoin que du flux standard
|
||||
`note -> prompt -> parse -> merge -> patch`, préférez les assistants de setup partagés
|
||||
de `openclaw/plugin-sdk/setup` : `createPromptParsedAllowFromForAccount(...)`,
|
||||
`createTopLevelChannelParsedAllowFromPrompt(...)` et
|
||||
Pour les invites de liste d’autorisation de message direct qui n’ont besoin que du flux standard
|
||||
`note -> prompt -> parse -> merge -> patch`, préférez les assistants de configuration partagés depuis `openclaw/plugin-sdk/setup` : `createPromptParsedAllowFromForAccount(...)`,
|
||||
`createTopLevelChannelParsedAllowFromPrompt(...)`, et
|
||||
`createNestedChannelParsedAllowFromPrompt(...)`.
|
||||
|
||||
Pour les blocs d’état de setup de canal qui ne varient que par les libellés, les scores et d’éventuelles
|
||||
Pour les blocs d’état de configuration de canal qui ne varient que par les libellés, les scores et d’éventuelles
|
||||
lignes supplémentaires, préférez `createStandardChannelSetupStatus(...)` depuis
|
||||
`openclaw/plugin-sdk/setup` au lieu de recréer à la main le même objet `status` dans
|
||||
chaque plugin.
|
||||
chaque Plugin.
|
||||
|
||||
Pour les surfaces de setup facultatives qui ne doivent apparaître que dans certains contextes, utilisez
|
||||
Pour les surfaces de configuration facultatives qui ne doivent apparaître que dans certains contextes, utilisez
|
||||
`createOptionalChannelSetupSurface` depuis `openclaw/plugin-sdk/channel-setup` :
|
||||
|
||||
```typescript
|
||||
@ -474,19 +475,19 @@ const setupSurface = createOptionalChannelSetupSurface({
|
||||
`createOptionalChannelSetupWizard(...)` lorsque vous n’avez besoin que d’une moitié
|
||||
de cette surface d’installation facultative.
|
||||
|
||||
L’adaptateur/l’assistant facultatif généré échoue de manière fermée sur les vraies écritures de configuration. Ils
|
||||
réutilisent un message unique d’installation requise dans `validateInput`,
|
||||
`applyAccountConfig` et `finalize`, et ajoutent un lien de documentation lorsque `docsPath` est
|
||||
L’adaptateur/l’assistant facultatif généré échoue de manière sûre sur les vraies écritures de config. Ils
|
||||
réutilisent un message unique indiquant qu’une installation est requise dans `validateInput`,
|
||||
`applyAccountConfig`, et `finalize`, et ajoutent un lien vers la documentation lorsque `docsPath` est
|
||||
défini.
|
||||
|
||||
Pour les UI de setup pilotées par binaire, préférez les assistants partagés délégués au lieu de
|
||||
copier la même logique de binaire/état dans chaque canal :
|
||||
Pour les interfaces de configuration adossées à un binaire, préférez les assistants délégués partagés au lieu de
|
||||
copier la même logique de binaire/d’état dans chaque canal :
|
||||
|
||||
- `createDetectedBinaryStatus(...)` pour les blocs d’état qui ne varient que par les libellés,
|
||||
indications, scores et détection de binaire
|
||||
- `createCliPathTextInput(...)` pour les entrées texte adossées à un chemin
|
||||
les indications, les scores et la détection du binaire
|
||||
- `createCliPathTextInput(...)` pour les entrées de texte adossées à un chemin
|
||||
- `createDelegatedSetupWizardStatusResolvers(...)`,
|
||||
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` et
|
||||
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)`, et
|
||||
`createDelegatedResolveConfigured(...)` lorsque `setupEntry` doit transférer vers
|
||||
un assistant complet plus lourd de manière paresseuse
|
||||
- `createDelegatedTextInputShouldPrompt(...)` lorsque `setupEntry` n’a besoin que de
|
||||
@ -500,22 +501,22 @@ copier la même logique de binaire/état dans chaque canal :
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
OpenClaw essaie d’abord ClawHub puis bascule automatiquement vers npm. Vous pouvez aussi
|
||||
OpenClaw essaie d’abord ClawHub puis bascule automatiquement sur npm. Vous pouvez aussi
|
||||
forcer explicitement ClawHub :
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub uniquement
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # ClawHub only
|
||||
```
|
||||
|
||||
Il n’existe pas de remplacement `npm:` correspondant. Utilisez la spécification de package npm normale lorsque vous
|
||||
Il n’existe pas d’équivalent pour le remplacement `npm:`. Utilisez la spécification normale du package npm lorsque vous
|
||||
voulez le chemin npm après le repli ClawHub :
|
||||
|
||||
```bash
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
**Plugins dans le dépôt :** placez-les sous l’arborescence de workspace des plugins groupés et ils seront automatiquement
|
||||
détectés pendant le build.
|
||||
**Plugins dans le dépôt :** placez-les dans l’arborescence d’espace de travail des Plugins intégrés et ils seront automatiquement
|
||||
découverts pendant la compilation.
|
||||
|
||||
**Les utilisateurs peuvent installer :**
|
||||
|
||||
@ -524,13 +525,13 @@ openclaw plugins install <package-name>
|
||||
```
|
||||
|
||||
<Info>
|
||||
Pour les installations issues de npm, `openclaw plugins install` exécute
|
||||
`npm install --ignore-scripts` (sans scripts de cycle de vie). Conservez des arbres de dépendances de plugin
|
||||
purs JS/TS et évitez les packages qui nécessitent des builds `postinstall`.
|
||||
Pour les installations depuis npm, `openclaw plugins install` exécute
|
||||
`npm install --ignore-scripts` (aucun script de cycle de vie). Gardez les arborescences de dépendances des Plugins
|
||||
en pur JS/TS et évitez les packages qui nécessitent des compilations `postinstall`.
|
||||
</Info>
|
||||
|
||||
## Lié
|
||||
|
||||
- [Points d’entrée du SDK](/fr/plugins/sdk-entrypoints) -- `definePluginEntry` et `defineChannelPluginEntry`
|
||||
- [Manifeste de plugin](/fr/plugins/manifest) -- référence complète du schéma de manifeste
|
||||
- [Créer des plugins](/fr/plugins/building-plugins) -- guide pas à pas pour démarrer
|
||||
- [Points d’entrée SDK](/fr/plugins/sdk-entrypoints) -- `definePluginEntry` et `defineChannelPluginEntry`
|
||||
- [Manifeste du Plugin](/fr/plugins/manifest) -- référence complète du schéma du manifeste
|
||||
- [Création de Plugins](/fr/plugins/building-plugins) -- guide de démarrage pas à pas
|
||||
|
||||
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous écrivez des tests pour un plugin
|
||||
- Vous avez besoin d’utilitaires de test du SDK plugin
|
||||
- Vous voulez comprendre les tests de contrat pour les plugins intégrés
|
||||
- Vous avez besoin d’utilitaires de test du SDK du Plugin
|
||||
- Vous souhaitez comprendre les tests de contrat pour les plugins intégrés
|
||||
sidebarTitle: Testing
|
||||
summary: Utilitaires et modèles de test pour les plugins OpenClaw
|
||||
title: Tests de plugins
|
||||
title: Tests du Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:50:44Z"
|
||||
generated_at: "2026-04-15T19:41:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe
|
||||
source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09
|
||||
source_path: plugins/sdk-testing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Tests de plugins
|
||||
# Tests du Plugin
|
||||
|
||||
Référence pour les utilitaires de test, les modèles et l’application des règles lint pour les
|
||||
Référence pour les utilitaires de test, les modèles et l’application des règles de lint pour les
|
||||
plugins OpenClaw.
|
||||
|
||||
<Tip>
|
||||
**Vous cherchez des exemples de tests ?** Les guides pratiques incluent des exemples de tests détaillés :
|
||||
[Tests de plugin de canal](/plugins/sdk-channel-plugins#step-6-test) et
|
||||
[Tests de plugin de provider](/plugins/sdk-provider-plugins#step-6-test).
|
||||
**Vous cherchez des exemples de test ?** Les guides pratiques incluent des exemples de test complets :
|
||||
[Tests de plugins de canal](/fr/plugins/sdk-channel-plugins#step-6-test) et
|
||||
[Tests de plugins de fournisseur](/fr/plugins/sdk-provider-plugins#step-6-test).
|
||||
</Tip>
|
||||
|
||||
## Utilitaires de test
|
||||
|
||||
**Import :** `openclaw/plugin-sdk/testing`
|
||||
**Importation :** `openclaw/plugin-sdk/testing`
|
||||
|
||||
Le sous-chemin de test exporte un ensemble restreint d’assistants pour les auteurs de plugins :
|
||||
|
||||
@ -42,15 +42,15 @@ import {
|
||||
|
||||
### Exports disponibles
|
||||
|
||||
| Export | But |
|
||||
| -------------------------------------- | ----------------------------------------------------- |
|
||||
| Export | But |
|
||||
| -------------------------------------- | ------------------------------------------------------ |
|
||||
| `installCommonResolveTargetErrorCases` | Cas de test partagés pour la gestion des erreurs de résolution de cible |
|
||||
| `shouldAckReaction` | Vérifie si un canal doit ajouter une réaction d’ack |
|
||||
| `removeAckReactionAfterReply` | Supprime la réaction d’ack après la livraison de la réponse |
|
||||
| `shouldAckReaction` | Vérifier si un canal doit ajouter une réaction d’accusé de réception |
|
||||
| `removeAckReactionAfterReply` | Supprimer la réaction d’accusé de réception après l’envoi de la réponse |
|
||||
|
||||
### Types
|
||||
|
||||
Le sous-chemin de test réexporte également des types utiles dans les fichiers de test :
|
||||
Le sous-chemin de test réexporte aussi des types utiles dans les fichiers de test :
|
||||
|
||||
```typescript
|
||||
import type {
|
||||
@ -65,23 +65,23 @@ import type {
|
||||
|
||||
## Tester la résolution de cible
|
||||
|
||||
Utilisez `installCommonResolveTargetErrorCases` pour ajouter des cas d’erreur standard à la
|
||||
résolution de cible d’un canal :
|
||||
Utilisez `installCommonResolveTargetErrorCases` pour ajouter des cas d’erreur standard pour la
|
||||
résolution de cible de canal :
|
||||
|
||||
```typescript
|
||||
import { describe } from "vitest";
|
||||
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testing";
|
||||
|
||||
describe("résolution de cible my-channel", () => {
|
||||
describe("my-channel target resolution", () => {
|
||||
installCommonResolveTargetErrorCases({
|
||||
resolveTarget: ({ to, mode, allowFrom }) => {
|
||||
// Logique de résolution de cible de votre canal
|
||||
// Your channel's target resolution logic
|
||||
return myChannelResolveTarget({ to, mode, allowFrom });
|
||||
},
|
||||
implicitAllowFrom: ["user1", "user2"],
|
||||
});
|
||||
|
||||
// Ajouter des cas de test spécifiques au canal
|
||||
// Add channel-specific test cases
|
||||
it("should resolve @username targets", () => {
|
||||
// ...
|
||||
});
|
||||
@ -90,12 +90,12 @@ describe("résolution de cible my-channel", () => {
|
||||
|
||||
## Modèles de test
|
||||
|
||||
### Tester unitaire un plugin de canal
|
||||
### Test unitaire d’un Plugin de canal
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
|
||||
describe("plugin my-channel", () => {
|
||||
describe("my-channel plugin", () => {
|
||||
it("should resolve account from config", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
@ -120,22 +120,22 @@ describe("plugin my-channel", () => {
|
||||
const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
|
||||
expect(inspection.configured).toBe(true);
|
||||
expect(inspection.tokenStatus).toBe("available");
|
||||
// Aucune valeur de jeton exposée
|
||||
// No token value exposed
|
||||
expect(inspection).not.toHaveProperty("token");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Tester unitaire un plugin de provider
|
||||
### Test unitaire d’un Plugin de fournisseur
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
describe("plugin my-provider", () => {
|
||||
describe("my-provider plugin", () => {
|
||||
it("should resolve dynamic models", () => {
|
||||
const model = myProvider.resolveDynamicModel({
|
||||
modelId: "custom-model-v2",
|
||||
// ... contexte
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(model.id).toBe("custom-model-v2");
|
||||
@ -146,7 +146,7 @@ describe("plugin my-provider", () => {
|
||||
it("should return catalog when API key is available", async () => {
|
||||
const result = await myProvider.catalog.run({
|
||||
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
|
||||
// ... contexte
|
||||
// ... context
|
||||
});
|
||||
|
||||
expect(result?.provider?.models).toHaveLength(2);
|
||||
@ -154,7 +154,7 @@ describe("plugin my-provider", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### Simuler le runtime du plugin
|
||||
### Simuler le runtime du Plugin
|
||||
|
||||
Pour le code qui utilise `createPluginRuntimeStore`, simulez le runtime dans les tests :
|
||||
|
||||
@ -162,43 +162,46 @@ Pour le code qui utilise `createPluginRuntimeStore`, simulez le runtime dans les
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "test-plugin",
|
||||
errorMessage: "test runtime not set",
|
||||
});
|
||||
|
||||
// Dans la configuration du test
|
||||
// In test setup
|
||||
const mockRuntime = {
|
||||
agent: {
|
||||
resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
|
||||
// ... autres simulations
|
||||
// ... other mocks
|
||||
},
|
||||
config: {
|
||||
loadConfig: vi.fn(),
|
||||
writeConfigFile: vi.fn(),
|
||||
},
|
||||
// ... autres espaces de noms
|
||||
// ... other namespaces
|
||||
} as unknown as PluginRuntime;
|
||||
|
||||
store.setRuntime(mockRuntime);
|
||||
|
||||
// Après les tests
|
||||
// After tests
|
||||
store.clearRuntime();
|
||||
```
|
||||
|
||||
### Tester avec des stubs par instance
|
||||
|
||||
Préférez les stubs par instance à la mutation de prototype :
|
||||
Préférez les stubs par instance à la mutation du prototype :
|
||||
|
||||
```typescript
|
||||
// Préféré : stub par instance
|
||||
// Preferred: per-instance stub
|
||||
const client = new MyChannelClient();
|
||||
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
|
||||
|
||||
// À éviter : mutation du prototype
|
||||
// Avoid: prototype mutation
|
||||
// MyChannelClient.prototype.sendMessage = vi.fn();
|
||||
```
|
||||
|
||||
## Tests de contrat (plugins dans le dépôt)
|
||||
## Tests de contrat (plugins du dépôt)
|
||||
|
||||
Les plugins intégrés ont des tests de contrat qui vérifient la propriété de l’enregistrement :
|
||||
Les plugins intégrés disposent de tests de contrat qui vérifient la propriété de l’enregistrement :
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/
|
||||
@ -206,10 +209,10 @@ pnpm test -- src/plugins/contracts/
|
||||
|
||||
Ces tests vérifient :
|
||||
|
||||
- Quels plugins enregistrent quels providers
|
||||
- Quels plugins enregistrent quels providers de parole
|
||||
- La correction de la forme d’enregistrement
|
||||
- La conformité du contrat d’exécution
|
||||
- Quels plugins enregistrent quels fournisseurs
|
||||
- Quels plugins enregistrent quels fournisseurs vocaux
|
||||
- La justesse de la forme d’enregistrement
|
||||
- La conformité au contrat d’exécution
|
||||
|
||||
### Exécuter des tests ciblés
|
||||
|
||||
@ -227,32 +230,32 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts
|
||||
pnpm test -- src/plugins/contracts/runtime.contract.test.ts
|
||||
```
|
||||
|
||||
## Application des règles lint (plugins dans le dépôt)
|
||||
## Application des règles de lint (plugins du dépôt)
|
||||
|
||||
Trois règles sont appliquées par `pnpm check` pour les plugins dans le dépôt :
|
||||
Trois règles sont appliquées par `pnpm check` pour les plugins du dépôt :
|
||||
|
||||
1. **Pas d’imports racine monolithiques** -- la racine `openclaw/plugin-sdk` est rejetée
|
||||
2. **Pas d’imports directs `src/`** -- les plugins ne peuvent pas importer directement `../../src/`
|
||||
1. **Pas d’imports racine monolithiques** -- le barrel racine `openclaw/plugin-sdk` est rejeté
|
||||
2. **Pas d’imports directs depuis `src/`** -- les plugins ne peuvent pas importer `../../src/` directement
|
||||
3. **Pas d’auto-imports** -- les plugins ne peuvent pas importer leur propre sous-chemin `plugin-sdk/<name>`
|
||||
|
||||
Les plugins externes ne sont pas soumis à ces règles lint, mais il est recommandé de suivre les mêmes
|
||||
Les plugins externes ne sont pas soumis à ces règles de lint, mais il est recommandé de suivre les mêmes
|
||||
modèles.
|
||||
|
||||
## Configuration des tests
|
||||
|
||||
OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugin :
|
||||
OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugins :
|
||||
|
||||
```bash
|
||||
# Exécuter tous les tests
|
||||
# Run all tests
|
||||
pnpm test
|
||||
|
||||
# Exécuter les tests d’un plugin spécifique
|
||||
# Run specific plugin tests
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts
|
||||
|
||||
# Exécuter avec un filtre sur un nom de test spécifique
|
||||
# Run with a specific test name filter
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"
|
||||
|
||||
# Exécuter avec la couverture
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
```
|
||||
|
||||
@ -262,9 +265,9 @@ Si les exécutions locales provoquent une pression mémoire :
|
||||
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
|
||||
```
|
||||
|
||||
## Liens associés
|
||||
## Voir aussi
|
||||
|
||||
- [SDK Overview](/plugins/sdk-overview) -- conventions d’import
|
||||
- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- interface des plugins de canal
|
||||
- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- hooks des plugins de provider
|
||||
- [Building Plugins](/plugins/building-plugins) -- guide de démarrage
|
||||
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) -- conventions d’importation
|
||||
- [SDK Channel Plugins](/fr/plugins/sdk-channel-plugins) -- interface de Plugin de canal
|
||||
- [SDK Provider Plugins](/fr/plugins/sdk-provider-plugins) -- hooks de Plugin de fournisseur
|
||||
- [Création de plugins](/fr/plugins/building-plugins) -- guide de démarrage
|
||||
|
||||
@ -1,35 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- Expliquer l’utilisation des tokens, les coûts ou les fenêtres de contexte
|
||||
- Déboguer la croissance du contexte ou le comportement de compactage
|
||||
summary: Comment OpenClaw construit le contexte du prompt et rapporte l’utilisation des tokens ainsi que les coûts
|
||||
- Déboguer la croissance du contexte ou le comportement de Compaction
|
||||
summary: Comment OpenClaw construit le contexte du prompt et rapporte l’utilisation des tokens et les coûts
|
||||
title: Utilisation des tokens et coûts
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T06:50:09Z"
|
||||
generated_at: "2026-04-15T19:42:15Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
|
||||
source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5
|
||||
source_path: reference/token-use.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Utilisation des tokens et coûts
|
||||
|
||||
OpenClaw suit les **tokens**, pas les caractères. Les tokens sont spécifiques au modèle, mais la plupart des modèles de style OpenAI ont une moyenne d’environ 4 caractères par token pour le texte anglais.
|
||||
OpenClaw suit les **tokens**, pas les caractères. Les tokens dépendent du modèle, mais la plupart
|
||||
des modèles de style OpenAI font en moyenne ~4 caractères par token pour le texte en anglais.
|
||||
|
||||
## Comment le prompt système est construit
|
||||
|
||||
OpenClaw assemble son propre prompt système à chaque exécution. Il inclut :
|
||||
OpenClaw assemble son propre prompt système à chaque exécution. Il comprend :
|
||||
|
||||
- Liste des outils + courtes descriptions
|
||||
- Liste des Skills (métadonnées uniquement ; les instructions sont chargées à la demande avec `read`)
|
||||
- Instructions d’auto-mise à jour
|
||||
- Fichiers de l’espace de travail + d’initialisation (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` lorsqu’il est nouveau, ainsi que `MEMORY.md` lorsqu’il est présent ou `memory.md` comme solution de secours en minuscules). Les fichiers volumineux sont tronqués par `agents.defaults.bootstrapMaxChars` (par défaut : 20000), et l’injection totale d’initialisation est plafonnée par `agents.defaults.bootstrapTotalMaxChars` (par défaut : 150000). Les fichiers quotidiens `memory/*.md` ne font pas partie du prompt d’initialisation normal ; ils restent accessibles à la demande via les outils de mémoire lors des tours ordinaires, mais `/new` et `/reset` seuls peuvent préfixer un bloc de contexte de démarrage à usage unique avec la mémoire quotidienne récente pour ce premier tour. Ce préambule de démarrage est contrôlé par `agents.defaults.startupContext`.
|
||||
- Liste des Skills (métadonnées uniquement ; les instructions sont chargées à la demande avec `read`).
|
||||
Le bloc compact des Skills est limité par `skills.limits.maxSkillsPromptChars`,
|
||||
avec une surcharge facultative par agent dans
|
||||
`agents.list[].skillsLimits.maxSkillsPromptChars`.
|
||||
- Instructions de mise à jour automatique
|
||||
- Fichiers d’espace de travail + d’amorçage (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quand ils sont nouveaux, ainsi que `MEMORY.md` lorsqu’il est présent ou `memory.md` comme solution de repli en minuscules). Les fichiers volumineux sont tronqués par `agents.defaults.bootstrapMaxChars` (par défaut : 12000), et l’injection totale d’amorçage est plafonnée par `agents.defaults.bootstrapTotalMaxChars` (par défaut : 60000). Les fichiers quotidiens `memory/*.md` ne font pas partie du prompt d’amorçage normal ; ils restent accessibles à la demande via les outils de mémoire lors des tours ordinaires, mais les commandes `/new` et `/reset` sans argument peuvent préfixer un bloc de contexte de démarrage à usage unique avec la mémoire quotidienne récente pour ce premier tour. Ce préambule de démarrage est contrôlé par `agents.defaults.startupContext`.
|
||||
- Heure (UTC + fuseau horaire de l’utilisateur)
|
||||
- Balises de réponse + comportement heartbeat
|
||||
- Balises de réponse + comportement Heartbeat
|
||||
- Métadonnées d’exécution (hôte/OS/modèle/réflexion)
|
||||
|
||||
Voir le détail complet dans [Prompt système](/fr/concepts/system-prompt).
|
||||
Consultez la ventilation complète dans [Prompt système](/fr/concepts/system-prompt).
|
||||
|
||||
## Ce qui compte dans la fenêtre de contexte
|
||||
|
||||
@ -39,53 +43,66 @@ Tout ce que le modèle reçoit compte dans la limite de contexte :
|
||||
- Historique de conversation (messages utilisateur + assistant)
|
||||
- Appels d’outils et résultats d’outils
|
||||
- Pièces jointes/transcriptions (images, audio, fichiers)
|
||||
- Résumés de compactage et artefacts d’élagage
|
||||
- Wrappers fournisseur ou en-têtes de sécurité (non visibles, mais quand même comptés)
|
||||
- Résumés de Compaction et artefacts d’élagage
|
||||
- Wrappers de fournisseur ou en-têtes de sécurité (non visibles, mais quand même comptabilisés)
|
||||
|
||||
Pour les images, OpenClaw réduit la taille des charges utiles d’image des transcriptions/outils avant les appels au fournisseur.
|
||||
Certaines surfaces d’exécution volumineuses ont leurs propres limites explicites :
|
||||
|
||||
- `agents.defaults.contextLimits.memoryGetMaxChars`
|
||||
- `agents.defaults.contextLimits.memoryGetDefaultLines`
|
||||
- `agents.defaults.contextLimits.toolResultMaxChars`
|
||||
- `agents.defaults.contextLimits.postCompactionMaxChars`
|
||||
|
||||
Les surcharges par agent se trouvent sous `agents.list[].contextLimits`. Ces paramètres
|
||||
servent pour les extraits d’exécution limités et les blocs injectés appartenant à l’exécution.
|
||||
Ils sont distincts des limites d’amorçage, des limites de contexte de démarrage et des limites
|
||||
du prompt des Skills.
|
||||
|
||||
Pour les images, OpenClaw réduit les payloads d’image de transcription/d’outil avant les appels au fournisseur.
|
||||
Utilisez `agents.defaults.imageMaxDimensionPx` (par défaut : `1200`) pour ajuster cela :
|
||||
|
||||
- Des valeurs plus faibles réduisent généralement l’utilisation de vision tokens et la taille des charges utiles.
|
||||
- Des valeurs plus élevées préservent davantage de détails visuels pour l’OCR/les captures d’écran d’interface lourdes.
|
||||
- Des valeurs plus basses réduisent généralement l’utilisation des vision-tokens et la taille des payloads.
|
||||
- Des valeurs plus élevées préservent davantage de détails visuels pour l’OCR/les captures d’écran riches en UI.
|
||||
|
||||
Pour un découpage pratique (par fichier injecté, outils, Skills et taille du prompt système), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context).
|
||||
Pour une ventilation pratique (par fichier injecté, outils, Skills et taille du prompt système), utilisez `/context list` ou `/context detail`. Voir [Contexte](/fr/concepts/context).
|
||||
|
||||
## Comment voir l’utilisation actuelle des tokens
|
||||
|
||||
Utilisez ceci dans le chat :
|
||||
|
||||
- `/status` → **carte d’état riche en emoji** avec le modèle de session, l’utilisation du contexte, les tokens d’entrée/sortie de la dernière réponse et le **coût estimé** (clé API uniquement).
|
||||
- `/status` → **carte d’état riche en emoji** avec le modèle de session, l’utilisation du contexte,
|
||||
les tokens d’entrée/sortie de la dernière réponse et le **coût estimé** (clé API uniquement).
|
||||
- `/usage off|tokens|full` → ajoute un **pied de page d’utilisation par réponse** à chaque réponse.
|
||||
- Persiste par session (stocké comme `responseUsage`).
|
||||
- L’auth OAuth **masque le coût** (tokens uniquement).
|
||||
- Persistant par session (stocké comme `responseUsage`).
|
||||
- L’authentification OAuth **masque le coût** (tokens uniquement).
|
||||
- `/usage cost` → affiche un résumé local des coûts à partir des journaux de session OpenClaw.
|
||||
|
||||
Autres interfaces :
|
||||
Autres surfaces :
|
||||
|
||||
- **TUI/Web TUI :** `/status` + `/usage` sont pris en charge.
|
||||
- **CLI :** `openclaw status --usage` et `openclaw channels list` affichent
|
||||
des fenêtres de quota fournisseur normalisées (`X% restants`, pas les coûts par réponse).
|
||||
Fournisseurs actuels avec fenêtre d’utilisation : Anthropic, GitHub Copilot, Gemini CLI,
|
||||
des fenêtres de quota fournisseur normalisées (`X% left`, et non des coûts par réponse).
|
||||
Fournisseurs actuels de fenêtre d’utilisation : Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi et z.ai.
|
||||
|
||||
Les interfaces d’utilisation normalisent les alias de champs natifs des fournisseurs avant affichage.
|
||||
Pour le trafic OpenAI-family Responses, cela inclut à la fois `input_tokens` /
|
||||
`output_tokens` et `prompt_tokens` / `completion_tokens`, afin que les noms de champs
|
||||
spécifiques au transport ne modifient pas `/status`, `/usage` ni les résumés de session.
|
||||
L’utilisation JSON de Gemini CLI est également normalisée : le texte de réponse vient de `response`, et
|
||||
`stats.cached` est mappé à `cacheRead`, avec `stats.input_tokens - stats.cached`
|
||||
Les surfaces d’utilisation normalisent les alias courants des champs natifs des fournisseurs avant l’affichage.
|
||||
Pour le trafic Responses de la famille OpenAI, cela inclut à la fois `input_tokens` /
|
||||
`output_tokens` et `prompt_tokens` / `completion_tokens`, afin que les noms de champs propres
|
||||
au transport ne modifient pas `/status`, `/usage` ou les résumés de session.
|
||||
L’utilisation JSON de Gemini CLI est également normalisée : le texte de réponse provient de `response`, et
|
||||
`stats.cached` est mappé vers `cacheRead`, avec `stats.input_tokens - stats.cached`
|
||||
utilisé lorsque la CLI omet un champ explicite `stats.input`.
|
||||
Pour le trafic natif OpenAI-family Responses, les alias d’utilisation WebSocket/SSE sont
|
||||
normalisés de la même manière, et les totaux retombent sur les valeurs normalisées d’entrée + sortie lorsque
|
||||
Pour le trafic Responses natif de la famille OpenAI, les alias d’utilisation WebSocket/SSE sont
|
||||
normalisés de la même manière, et les totaux reviennent à l’entrée + sortie normalisées lorsque
|
||||
`total_tokens` est absent ou vaut `0`.
|
||||
Lorsque l’instantané de la session en cours est peu détaillé, `/status` et `session_status` peuvent
|
||||
Lorsque l’instantané de la session actuelle est incomplet, `/status` et `session_status` peuvent
|
||||
également récupérer les compteurs de tokens/cache et l’étiquette du modèle d’exécution actif à partir du
|
||||
journal d’utilisation de transcription le plus récent. Les valeurs actives non nulles existantes restent prioritaires
|
||||
sur les valeurs de secours issues de la transcription, et des totaux de transcription plus élevés
|
||||
orientés prompt peuvent l’emporter lorsque les totaux stockés sont absents ou plus faibles.
|
||||
L’authentification d’utilisation pour les fenêtres de quota fournisseur provient de hooks spécifiques au fournisseur lorsque
|
||||
disponible ; sinon OpenClaw retombe sur les identifiants OAuth/clé API correspondants provenant des profils d’authentification,
|
||||
de l’environnement ou de la configuration.
|
||||
journal d’utilisation de transcription le plus récent. Les valeurs actives non nulles existantes
|
||||
restent prioritaires sur les valeurs de repli issues de la transcription, et des totaux de transcription
|
||||
plus élevés orientés prompt peuvent l’emporter lorsque les totaux stockés sont absents ou plus faibles.
|
||||
L’authentification d’utilisation pour les fenêtres de quota fournisseur provient de hooks spécifiques
|
||||
au fournisseur lorsqu’ils sont disponibles ; sinon OpenClaw se replie sur des identifiants OAuth/clé API
|
||||
correspondants issus des profils d’authentification, de l’environnement ou de la configuration.
|
||||
|
||||
## Estimation des coûts (lorsqu’elle est affichée)
|
||||
|
||||
@ -95,35 +112,36 @@ Les coûts sont estimés à partir de votre configuration tarifaire de modèle :
|
||||
models.providers.<provider>.models[].cost
|
||||
```
|
||||
|
||||
Il s’agit de **USD par 1M tokens** pour `input`, `output`, `cacheRead` et
|
||||
Ce sont des **USD par 1M de tokens** pour `input`, `output`, `cacheRead` et
|
||||
`cacheWrite`. Si la tarification est absente, OpenClaw n’affiche que les tokens. Les tokens OAuth
|
||||
n’affichent jamais de coût en dollars.
|
||||
|
||||
## Impact du TTL du cache et de l’élagage
|
||||
|
||||
La mise en cache des prompts fournisseur ne s’applique que dans la fenêtre TTL du cache. OpenClaw peut
|
||||
Le cache de prompt du fournisseur ne s’applique que dans la fenêtre TTL du cache. OpenClaw peut
|
||||
facultativement exécuter un **élagage cache-ttl** : il élague la session une fois le TTL du cache
|
||||
expiré, puis réinitialise la fenêtre de cache afin que les requêtes suivantes puissent réutiliser le
|
||||
contexte fraîchement mis en cache au lieu de remettre en cache tout l’historique. Cela permet de limiter les
|
||||
coûts d’écriture dans le cache lorsqu’une session reste inactive au-delà du TTL.
|
||||
contexte fraîchement mis en cache au lieu de remettre en cache tout l’historique. Cela permet de
|
||||
maintenir des coûts d’écriture de cache plus faibles lorsqu’une session reste inactive au-delà du TTL.
|
||||
|
||||
Configurez cela dans [Configuration de la gateway](/fr/gateway/configuration) et consultez les
|
||||
Configurez cela dans [Configuration du Gateway](/fr/gateway/configuration) et consultez les
|
||||
détails du comportement dans [Élagage de session](/fr/concepts/session-pruning).
|
||||
|
||||
Heartbeat peut maintenir le cache **chaud** pendant les périodes d’inactivité. Si le TTL de cache de votre modèle
|
||||
est de `1h`, régler l’intervalle heartbeat juste en dessous (par exemple `55m`) peut éviter de
|
||||
remettre en cache l’intégralité du prompt, ce qui réduit les coûts d’écriture dans le cache.
|
||||
Heartbeat peut garder le cache **chaud** pendant les périodes d’inactivité. Si le TTL du cache de votre modèle
|
||||
est `1h`, définir l’intervalle Heartbeat juste en dessous (par ex. `55m`) peut éviter de remettre en cache
|
||||
le prompt complet, ce qui réduit les coûts d’écriture du cache.
|
||||
|
||||
Dans les configurations multi-agent, vous pouvez conserver une configuration de modèle partagée et ajuster le comportement du cache
|
||||
Dans les configurations multi-agents, vous pouvez conserver une configuration de modèle partagée et ajuster le comportement du cache
|
||||
par agent avec `agents.list[].params.cacheRetention`.
|
||||
|
||||
Pour un guide complet paramètre par paramètre, voir [Prompt Caching](/fr/reference/prompt-caching).
|
||||
Pour un guide complet paramètre par paramètre, voir [Cache de prompt](/fr/reference/prompt-caching).
|
||||
|
||||
Pour la tarification de l’API Anthropic, les lectures du cache sont significativement moins chères que les
|
||||
tokens d’entrée, tandis que les écritures du cache sont facturées avec un multiplicateur plus élevé. Consultez la tarification Anthropic du prompt caching pour connaître les tarifs et multiplicateurs TTL les plus récents :
|
||||
Pour la tarification de l’API Anthropic, les lectures de cache sont nettement moins coûteuses que les tokens
|
||||
d’entrée, tandis que les écritures de cache sont facturées avec un multiplicateur plus élevé. Consultez la tarification
|
||||
du cache de prompt d’Anthropic pour connaître les derniers tarifs et multiplicateurs TTL :
|
||||
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
|
||||
|
||||
### Exemple : garder un cache de 1h chaud avec heartbeat
|
||||
### Exemple : garder un cache de 1h chaud avec Heartbeat
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -153,19 +171,19 @@ agents:
|
||||
- id: "research"
|
||||
default: true
|
||||
heartbeat:
|
||||
every: "55m" # garde le cache long chaud pour les sessions approfondies
|
||||
every: "55m" # garder le cache long chaud pour les sessions profondes
|
||||
- id: "alerts"
|
||||
params:
|
||||
cacheRetention: "none" # évite les écritures de cache pour les notifications par rafales
|
||||
cacheRetention: "none" # éviter les écritures de cache pour les notifications en rafales
|
||||
```
|
||||
|
||||
`agents.list[].params` fusionne au-dessus des `params` du modèle sélectionné, ce qui vous permet
|
||||
de ne remplacer que `cacheRetention` et d’hériter inchangés des autres paramètres par défaut du modèle.
|
||||
`agents.list[].params` est fusionné par-dessus le `params` du modèle sélectionné, ce qui vous permet
|
||||
de surcharger uniquement `cacheRetention` et d’hériter inchangés des autres paramètres par défaut du modèle.
|
||||
|
||||
### Exemple : activer l’en-tête bêta Anthropic 1M context
|
||||
### Exemple : activer l’en-tête bêta Anthropic de contexte 1M
|
||||
|
||||
La fenêtre de contexte Anthropic de 1M est actuellement protégée par une bêta. OpenClaw peut injecter la
|
||||
valeur `anthropic-beta` requise lorsque vous activez `context1m` sur les modèles Opus
|
||||
La fenêtre de contexte 1M d’Anthropic est actuellement protégée par une bêta. OpenClaw peut injecter la
|
||||
valeur `anthropic-beta` requise lorsque vous activez `context1m` sur des modèles Opus
|
||||
ou Sonnet pris en charge.
|
||||
|
||||
```yaml
|
||||
@ -177,23 +195,23 @@ agents:
|
||||
context1m: true
|
||||
```
|
||||
|
||||
Cela correspond à l’en-tête bêta Anthropic `context-1m-2025-08-07`.
|
||||
Cela correspond à l’en-tête bêta `context-1m-2025-08-07` d’Anthropic.
|
||||
|
||||
Cela s’applique uniquement lorsque `context1m: true` est défini sur cette entrée de modèle.
|
||||
Cela ne s’applique que lorsque `context1m: true` est défini sur cette entrée de modèle.
|
||||
|
||||
Exigence : l’identifiant doit être éligible à l’utilisation long contexte. Dans le cas contraire,
|
||||
Exigence : l’identifiant doit être éligible à l’utilisation de contexte long. Sinon,
|
||||
Anthropic répond avec une erreur de limitation de débit côté fournisseur pour cette requête.
|
||||
|
||||
Si vous authentifiez Anthropic avec des tokens OAuth/d’abonnement (`sk-ant-oat-*`),
|
||||
OpenClaw ignore l’en-tête bêta `context-1m-*` car Anthropic rejette actuellement
|
||||
cette combinaison avec une erreur HTTP 401.
|
||||
cette combinaison avec HTTP 401.
|
||||
|
||||
## Conseils pour réduire la pression sur les tokens
|
||||
## Conseils pour réduire la pression des tokens
|
||||
|
||||
- Utilisez `/compact` pour résumer les longues sessions.
|
||||
- Réduisez les sorties d’outils volumineuses dans vos workflows.
|
||||
- Diminuez `agents.defaults.imageMaxDimensionPx` pour les sessions riches en captures d’écran.
|
||||
- Gardez les descriptions de Skills courtes (la liste des Skills est injectée dans le prompt).
|
||||
- Préférez des modèles plus petits pour le travail verbeux et exploratoire.
|
||||
- Préférez des modèles plus petits pour un travail verbeux et exploratoire.
|
||||
|
||||
Voir [Skills](/fr/tools/skills) pour la formule exacte de surcharge de la liste des Skills.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user