chore(i18n): refresh fr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
42061df4ba
commit
45fbe3855b
@ -1,39 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous devez expliquer l’espace de travail de l’agent ou son organisation de fichiers
|
||||
- Vous devez expliquer l’espace de travail de l’agent ou la disposition de ses fichiers
|
||||
- Vous souhaitez sauvegarder ou migrer un espace de travail d’agent
|
||||
summary: 'Espace de travail de l’agent : emplacement, organisation et stratégie de sauvegarde'
|
||||
summary: 'Espace de travail de l’agent : emplacement, disposition et stratégie de sauvegarde'
|
||||
title: Espace de travail de l’agent
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:39:36Z"
|
||||
generated_at: "2026-04-18T06:43:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
|
||||
source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Espace de travail de l’agent
|
||||
|
||||
L’espace de travail est le foyer de l’agent. C’est le seul répertoire de travail utilisé pour
|
||||
les outils de fichiers et pour le contexte de l’espace de travail. Gardez-le privé et traitez-le comme de la mémoire.
|
||||
L’espace de travail est la maison de l’agent. C’est le seul répertoire de travail utilisé pour
|
||||
les outils de fichiers et pour le contexte d’espace de travail. Gardez-le privé et traitez-le comme une mémoire.
|
||||
|
||||
Ceci est distinct de `~/.openclaw/`, qui stocke la configuration, les identifiants et
|
||||
Cela est distinct de `~/.openclaw/`, qui stocke la configuration, les identifiants et
|
||||
les sessions.
|
||||
|
||||
**Important :** l’espace de travail est le **cwd par défaut**, pas un sandbox strict. Les outils
|
||||
**Important :** l’espace de travail est le **cwd par défaut**, et non un sandbox strict. Les outils
|
||||
résolvent les chemins relatifs par rapport à l’espace de travail, mais les chemins absolus peuvent toujours atteindre
|
||||
d’autres emplacements sur l’hôte sauf si le sandboxing est activé. Si vous avez besoin d’isolation, utilisez
|
||||
[`agents.defaults.sandbox`](/gateway/sandboxing) (et/ou une configuration de sandbox par agent).
|
||||
[`agents.defaults.sandbox`](/fr/gateway/sandboxing) (et/ou une configuration de sandbox par agent).
|
||||
Lorsque le sandboxing est activé et que `workspaceAccess` n’est pas `"rw"`, les outils opèrent
|
||||
dans un espace de travail sandbox sous `~/.openclaw/sandboxes`, et non dans votre espace de travail hôte.
|
||||
|
||||
## Emplacement par défaut
|
||||
|
||||
- Par défaut : `~/.openclaw/workspace`
|
||||
- Si `OPENCLAW_PROFILE` est défini et n’est pas `"default"`, l’emplacement par défaut devient
|
||||
- Si `OPENCLAW_PROFILE` est défini et n’est pas `"default"`, la valeur par défaut devient
|
||||
`~/.openclaw/workspace-<profile>`.
|
||||
- Remplacez-le dans `~/.openclaw/openclaw.json` :
|
||||
- Remplacement dans `~/.openclaw/openclaw.json` :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -43,106 +43,104 @@ dans un espace de travail sandbox sous `~/.openclaw/sandboxes`, et non dans votr
|
||||
}
|
||||
```
|
||||
|
||||
`openclaw onboard`, `openclaw configure` ou `openclaw setup` créeront
|
||||
l’espace de travail et initialiseront les fichiers bootstrap s’ils sont absents.
|
||||
Les copies d’amorçage du sandbox n’acceptent que les fichiers ordinaires dans l’espace de travail ; les alias
|
||||
de lien symbolique/lien physique qui se résolvent en dehors de l’espace de travail source sont ignorés.
|
||||
`openclaw onboard`, `openclaw configure` ou `openclaw setup` créera l’espace de travail
|
||||
et initialisera les fichiers d’amorçage s’ils sont absents.
|
||||
Les copies de seed du sandbox n’acceptent que les fichiers réguliers situés dans l’espace de travail ; les
|
||||
alias symlink/hardlink qui se résolvent en dehors de l’espace de travail source sont ignorés.
|
||||
|
||||
Si vous gérez déjà vous-même les fichiers de l’espace de travail, vous pouvez désactiver la création
|
||||
des fichiers bootstrap :
|
||||
Si vous gérez déjà vous-même les fichiers de l’espace de travail, vous pouvez désactiver la création des fichiers d’amorçage :
|
||||
|
||||
```json5
|
||||
{ agent: { skipBootstrap: true } }
|
||||
```
|
||||
|
||||
## Dossiers supplémentaires d’espace de travail
|
||||
## Dossiers d’espace de travail supplémentaires
|
||||
|
||||
Les anciennes installations ont pu créer `~/openclaw`. Conserver plusieurs répertoires
|
||||
d’espace de travail peut provoquer des dérives d’authentification ou d’état difficiles à comprendre, car un seul
|
||||
Les anciennes installations peuvent avoir créé `~/openclaw`. Conserver plusieurs répertoires d’espace de travail
|
||||
peut provoquer une dérive confuse de l’authentification ou de l’état, car un seul
|
||||
espace de travail est actif à la fois.
|
||||
|
||||
**Recommandation :** gardez un seul espace de travail actif. Si vous n’utilisez plus les
|
||||
dossiers supplémentaires, archivez-les ou placez-les dans la Corbeille (par exemple `trash ~/openclaw`).
|
||||
Si vous conservez volontairement plusieurs espaces de travail, assurez-vous que
|
||||
`agents.defaults.workspace` pointe vers l’espace de travail actif.
|
||||
**Recommandation :** conservez un seul espace de travail actif. Si vous n’utilisez plus les
|
||||
dossiers supplémentaires, archivez-les ou déplacez-les vers la corbeille (par exemple `trash ~/openclaw`).
|
||||
Si vous conservez intentionnellement plusieurs espaces de travail, assurez-vous que
|
||||
`agents.defaults.workspace` pointe vers celui qui est actif.
|
||||
|
||||
`openclaw doctor` affiche un avertissement lorsqu’il détecte des répertoires d’espace de travail supplémentaires.
|
||||
`openclaw doctor` avertit lorsqu’il détecte des répertoires d’espace de travail supplémentaires.
|
||||
|
||||
## Carte des fichiers de l’espace de travail (signification de chaque fichier)
|
||||
|
||||
Voici les fichiers standard qu’OpenClaw attend dans l’espace de travail :
|
||||
|
||||
- `AGENTS.md`
|
||||
- Instructions de fonctionnement pour l’agent et façon dont il doit utiliser la mémoire.
|
||||
- Instructions de fonctionnement pour l’agent et la manière dont il doit utiliser la mémoire.
|
||||
- Chargé au début de chaque session.
|
||||
- Bon emplacement pour les règles, priorités et détails sur « comment se comporter ».
|
||||
- Bon emplacement pour les règles, les priorités et les détails sur « comment se comporter ».
|
||||
|
||||
- `SOUL.md`
|
||||
- Persona, ton et limites.
|
||||
- Chargé à chaque session.
|
||||
- Guide : [Guide de personnalité SOUL.md](/concepts/soul)
|
||||
- Guide : [Guide de personnalité SOUL.md](/fr/concepts/soul)
|
||||
|
||||
- `USER.md`
|
||||
- Qui est l’utilisateur et comment s’adresser à lui.
|
||||
- Chargé à chaque session.
|
||||
|
||||
- `IDENTITY.md`
|
||||
- Le nom, le style et l’emoji de l’agent.
|
||||
- Créé/mis à jour pendant le rituel bootstrap.
|
||||
- Le nom de l’agent, son style et son emoji.
|
||||
- Créé/mis à jour pendant le rituel d’amorçage.
|
||||
|
||||
- `TOOLS.md`
|
||||
- Notes sur vos outils locaux et conventions.
|
||||
- Ne contrôle pas la disponibilité des outils ; ne sert que de guide.
|
||||
- Notes sur vos outils locaux et vos conventions.
|
||||
- Ne contrôle pas la disponibilité des outils ; il sert uniquement de guide.
|
||||
|
||||
- `HEARTBEAT.md`
|
||||
- Petite checklist facultative pour les exécutions heartbeat.
|
||||
- Gardez-la courte pour éviter de gaspiller des jetons.
|
||||
- Petite checklist facultative pour les exécutions Heartbeat.
|
||||
- Gardez-la courte pour éviter de brûler des tokens.
|
||||
|
||||
- `BOOT.md`
|
||||
- Checklist de démarrage facultative exécutée au redémarrage de gateway lorsque les hooks internes sont activés.
|
||||
- Checklist de démarrage facultative exécutée au redémarrage de la Gateway lorsque les hooks internes sont activés.
|
||||
- Gardez-la courte ; utilisez l’outil de message pour les envois sortants.
|
||||
|
||||
- `BOOTSTRAP.md`
|
||||
- Rituel unique de première exécution.
|
||||
- Créé uniquement pour un espace de travail entièrement nouveau.
|
||||
- Rituel unique du premier lancement.
|
||||
- Créé uniquement pour un espace de travail entièrement neuf.
|
||||
- Supprimez-le une fois le rituel terminé.
|
||||
|
||||
- `memory/YYYY-MM-DD.md`
|
||||
- Journal mémoire quotidien (un fichier par jour).
|
||||
- Il est recommandé de lire aujourd’hui + hier au démarrage de la session.
|
||||
- Journal de mémoire quotidien (un fichier par jour).
|
||||
- Il est recommandé de lire celui d’aujourd’hui + celui d’hier au démarrage de la session.
|
||||
|
||||
- `MEMORY.md` (facultatif)
|
||||
- Mémoire long terme organisée.
|
||||
- À charger uniquement dans la session principale privée (pas dans les contextes partagés/de groupe).
|
||||
- À charger uniquement dans la session principale et privée (pas dans les contextes partagés/de groupe).
|
||||
|
||||
Voir [Mémoire](/concepts/memory) pour le flux de travail et la purge mémoire automatique.
|
||||
Consultez [Memory](/fr/concepts/memory) pour le workflow et le vidage automatique de la mémoire.
|
||||
|
||||
- `skills/` (facultatif)
|
||||
- Skills spécifiques à l’espace de travail.
|
||||
- Emplacement de Skills à la plus haute priorité pour cet espace de travail.
|
||||
- Remplace les Skills d’agent de projet, les Skills d’agent personnels, les Skills gérés, les Skills intégrés et `skills.load.extraDirs` en cas de collision de noms.
|
||||
- Emplacement de Skills à la priorité la plus élevée pour cet espace de travail.
|
||||
- Remplace les skills d’agent du projet, les skills d’agent personnels, les skills gérés, les skills intégrés et `skills.load.extraDirs` lorsque les noms entrent en conflit.
|
||||
|
||||
- `canvas/` (facultatif)
|
||||
- Fichiers UI canvas pour les affichages de nœud (par exemple `canvas/index.html`).
|
||||
- Fichiers d’interface Canvas pour les affichages de nœud (par exemple `canvas/index.html`).
|
||||
|
||||
Si un fichier bootstrap est absent, OpenClaw injecte un marqueur « fichier manquant » dans
|
||||
la session et continue. Les gros fichiers bootstrap sont tronqués lors de l’injection ;
|
||||
ajustez les limites avec `agents.defaults.bootstrapMaxChars` (par défaut : 20000) et
|
||||
`agents.defaults.bootstrapTotalMaxChars` (par défaut : 150000).
|
||||
`openclaw setup` peut recréer les valeurs par défaut manquantes sans écraser les
|
||||
fichiers existants.
|
||||
Si un fichier d’amorçage est manquant, OpenClaw injecte un marqueur « fichier manquant » dans
|
||||
la session et continue. Les grands fichiers d’amorçage sont tronqués lors de l’injection ;
|
||||
ajustez les limites avec `agents.defaults.bootstrapMaxChars` (par défaut : 12000) et
|
||||
`agents.defaults.bootstrapTotalMaxChars` (par défaut : 60000).
|
||||
`openclaw setup` peut recréer les valeurs par défaut manquantes sans écraser les fichiers existants.
|
||||
|
||||
## Ce qui n’est PAS dans l’espace de travail
|
||||
|
||||
Ces éléments se trouvent sous `~/.openclaw/` et ne doivent PAS être validés dans le dépôt de l’espace de travail :
|
||||
Ces éléments se trouvent sous `~/.openclaw/` et ne doivent PAS être commités dans le dépôt de l’espace de travail :
|
||||
|
||||
- `~/.openclaw/openclaw.json` (configuration)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (profils d’authentification de modèle : OAuth + clés API)
|
||||
- `~/.openclaw/credentials/` (état du canal/fournisseur plus données d’importation OAuth héritées)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (profils d’authentification des modèles : OAuth + clés API)
|
||||
- `~/.openclaw/credentials/` (état des canaux/providers ainsi que données d’import OAuth héritées)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (transcriptions de session + métadonnées)
|
||||
- `~/.openclaw/skills/` (Skills gérés)
|
||||
|
||||
Si vous devez migrer des sessions ou la configuration, copiez-les séparément et gardez-les
|
||||
Si vous devez migrer des sessions ou la configuration, copiez-les séparément et conservez-les
|
||||
hors du contrôle de version.
|
||||
|
||||
## Sauvegarde Git (recommandée, privée)
|
||||
@ -150,12 +148,12 @@ hors du contrôle de version.
|
||||
Traitez l’espace de travail comme une mémoire privée. Placez-le dans un dépôt git **privé** afin qu’il soit
|
||||
sauvegardé et récupérable.
|
||||
|
||||
Exécutez ces étapes sur la machine où gateway s’exécute (c’est là que
|
||||
l’espace de travail se trouve).
|
||||
Exécutez ces étapes sur la machine où la Gateway s’exécute (c’est là que se trouve
|
||||
l’espace de travail).
|
||||
|
||||
### 1) Initialiser le dépôt
|
||||
|
||||
Si git est installé, les nouveaux espaces de travail sont initialisés automatiquement. Si cet
|
||||
Si git est installé, les espaces de travail neufs sont initialisés automatiquement. Si cet
|
||||
espace de travail n’est pas déjà un dépôt, exécutez :
|
||||
|
||||
```bash
|
||||
@ -165,7 +163,7 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
|
||||
git commit -m "Add agent workspace"
|
||||
```
|
||||
|
||||
### 2) Ajouter un remote privé (options adaptées aux débutants)
|
||||
### 2) Ajouter un remote privé (options simples pour débutants)
|
||||
|
||||
Option A : interface web GitHub
|
||||
|
||||
@ -209,18 +207,18 @@ git commit -m "Update memory"
|
||||
git push
|
||||
```
|
||||
|
||||
## Ne validez pas de secrets
|
||||
## Ne commitez pas de secrets
|
||||
|
||||
Même dans un dépôt privé, évitez de stocker des secrets dans l’espace de travail :
|
||||
|
||||
- Clés API, jetons OAuth, mots de passe ou identifiants privés.
|
||||
- Clés API, tokens OAuth, mots de passe ou identifiants privés.
|
||||
- Tout ce qui se trouve sous `~/.openclaw/`.
|
||||
- Dumps bruts de chats ou pièces jointes sensibles.
|
||||
- Dumps bruts de discussions ou pièces jointes sensibles.
|
||||
|
||||
Si vous devez stocker des références sensibles, utilisez des espaces réservés et conservez le vrai
|
||||
Si vous devez stocker des références sensibles, utilisez des placeholders et conservez le vrai
|
||||
secret ailleurs (gestionnaire de mots de passe, variables d’environnement ou `~/.openclaw/`).
|
||||
|
||||
Exemple de départ pour `.gitignore` :
|
||||
Exemple de `.gitignore` recommandé :
|
||||
|
||||
```gitignore
|
||||
.DS_Store
|
||||
@ -235,19 +233,19 @@ Exemple de départ pour `.gitignore` :
|
||||
1. Clonez le dépôt vers le chemin souhaité (par défaut `~/.openclaw/workspace`).
|
||||
2. Définissez `agents.defaults.workspace` sur ce chemin dans `~/.openclaw/openclaw.json`.
|
||||
3. Exécutez `openclaw setup --workspace <path>` pour initialiser les fichiers manquants.
|
||||
4. Si vous avez besoin des sessions, copiez `~/.openclaw/agents/<agentId>/sessions/` depuis l’
|
||||
ancienne machine séparément.
|
||||
4. Si vous avez besoin des sessions, copiez `~/.openclaw/agents/<agentId>/sessions/` depuis l’ancienne
|
||||
machine séparément.
|
||||
|
||||
## Notes avancées
|
||||
|
||||
- Le routage multi-agent peut utiliser différents espaces de travail par agent. Voir
|
||||
[Routage des canaux](/channels/channel-routing) pour la configuration du routage.
|
||||
- Le routage multi-agent peut utiliser des espaces de travail différents par agent. Consultez
|
||||
[Routage des canaux](/fr/channels/channel-routing) pour la configuration du routage.
|
||||
- Si `agents.defaults.sandbox` est activé, les sessions non principales peuvent utiliser des espaces de travail
|
||||
sandbox par session sous `agents.defaults.sandbox.workspaceRoot`.
|
||||
|
||||
## Liens associés
|
||||
|
||||
- [Ordres permanents](/automation/standing-orders) — instructions persistantes dans les fichiers d’espace de travail
|
||||
- [Heartbeat](/gateway/heartbeat) — fichier d’espace de travail HEARTBEAT.md
|
||||
- [Session](/concepts/session) — chemins de stockage des sessions
|
||||
- [Sandboxing](/gateway/sandboxing) — accès à l’espace de travail dans les environnements sandboxés
|
||||
- [Standing Orders](/fr/automation/standing-orders) — instructions persistantes dans les fichiers de l’espace de travail
|
||||
- [Heartbeat](/fr/gateway/heartbeat) — fichier d’espace de travail HEARTBEAT.md
|
||||
- [Session](/fr/concepts/session) — chemins de stockage des sessions
|
||||
- [Sandboxing](/fr/gateway/sandboxing) — accès à l’espace de travail dans les environnements sandboxés
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous voulez comprendre ce que signifie « contexte » dans OpenClaw
|
||||
- Vous déboguez pourquoi le modèle « sait » quelque chose (ou l’a oublié)
|
||||
- Vous voulez comprendre ce que signifie « contexte » dans OpenClaw
|
||||
- Vous déboguez pourquoi le modèle « sait » quelque chose (ou l’a oublié)
|
||||
- Vous souhaitez réduire la surcharge de contexte (/context, /status, /compact)
|
||||
summary: 'Contexte : ce que le modèle voit, comment il est construit et comment l’inspecter'
|
||||
summary: 'Contexte : ce que voit le modèle, comment il est construit et comment l’inspecter'
|
||||
title: Contexte
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T23:28:13Z"
|
||||
generated_at: "2026-04-18T06:43:36Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d
|
||||
source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Contexte
|
||||
|
||||
Le « contexte » correspond à **tout ce qu’OpenClaw envoie au modèle pour une exécution**. Il est limité par la **fenêtre de contexte** du modèle (limite de jetons).
|
||||
Le « contexte » est **tout ce que OpenClaw envoie au modèle pour une exécution**. Il est limité par la **fenêtre de contexte** du modèle (limite de tokens).
|
||||
|
||||
Modèle mental pour débuter :
|
||||
Modèle mental pour débutants :
|
||||
|
||||
- **Prompt système** (construit par OpenClaw) : règles, outils, liste des Skills, heure/exécution, et fichiers d’espace de travail injectés.
|
||||
- **Historique de conversation** : vos messages + les messages de l’assistant pour cette session.
|
||||
- **Appels/résultats d’outils + pièces jointes** : sortie de commande, lectures de fichiers, images/audio, etc.
|
||||
- **Prompt système** (construit par OpenClaw) : règles, outils, liste des Skills, heure/exécution, et fichiers d’espace de travail injectés.
|
||||
- **Historique de conversation** : vos messages + les messages de l’assistant pour cette session.
|
||||
- **Appels/résultats d’outils + pièces jointes** : sortie de commandes, lectures de fichiers, images/audio, etc.
|
||||
|
||||
Le contexte _n’est pas la même chose_ que la « mémoire » : la mémoire peut être stockée sur disque et rechargée plus tard ; le contexte est ce qui se trouve dans la fenêtre actuelle du modèle.
|
||||
Le contexte n’est _pas la même chose_ que la « mémoire » : la mémoire peut être stockée sur disque et rechargée plus tard ; le contexte est ce qui se trouve dans la fenêtre actuelle du modèle.
|
||||
|
||||
## Démarrage rapide (inspecter le contexte)
|
||||
|
||||
- `/status` → vue rapide « à quel point ma fenêtre est-elle remplie ? » + paramètres de session.
|
||||
- `/status` → vue rapide « à quel point ma fenêtre est-elle remplie ? » + paramètres de session.
|
||||
- `/context list` → ce qui est injecté + tailles approximatives (par fichier + totaux).
|
||||
- `/context detail` → ventilation plus approfondie : par fichier, tailles des schémas d’outils, tailles des entrées de Skills et taille du prompt système.
|
||||
- `/context detail` → ventilation plus approfondie : par fichier, tailles des schémas d’outils, tailles des entrées de Skills, et taille du prompt système.
|
||||
- `/usage tokens` → ajoute un pied de page d’utilisation par réponse aux réponses normales.
|
||||
- `/compact` → résume l’historique plus ancien dans une entrée compacte pour libérer de l’espace dans la fenêtre.
|
||||
|
||||
Voir aussi : [Commandes slash](/fr/tools/slash-commands), [Utilisation des jetons et coûts](/fr/reference/token-use), [Compaction](/fr/concepts/compaction).
|
||||
Voir aussi : [Commandes slash](/fr/tools/slash-commands), [Utilisation des tokens et coûts](/fr/reference/token-use), [Compaction](/fr/concepts/compaction).
|
||||
|
||||
## Exemple de sortie
|
||||
|
||||
@ -44,27 +44,27 @@ Les valeurs varient selon le modèle, le fournisseur, la politique d’outils et
|
||||
|
||||
```
|
||||
🧠 Ventilation du contexte
|
||||
Workspace: <workspaceDir>
|
||||
Bootstrap max/file: 20,000 chars
|
||||
Sandbox: mode=non-main sandboxed=false
|
||||
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
Espace de travail : <workspaceDir>
|
||||
Bootstrap max/fichier : 12,000 caractères
|
||||
Sandbox : mode=non-main sandboxed=false
|
||||
Prompt système (exécution) : 38,412 caractères (~9,603 tok) (Contexte du projet 23,901 caractères (~5,976 tok))
|
||||
|
||||
Injected workspace files:
|
||||
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
|
||||
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
|
||||
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
|
||||
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
|
||||
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
|
||||
- HEARTBEAT.md: MISSING | raw 0 | injected 0
|
||||
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
|
||||
Fichiers de l’espace de travail injectés :
|
||||
- AGENTS.md: OK | brut 1,742 caractères (~436 tok) | injecté 1,742 caractères (~436 tok)
|
||||
- SOUL.md: OK | brut 912 caractères (~228 tok) | injecté 912 caractères (~228 tok)
|
||||
- TOOLS.md: TRONQUÉ | brut 54,210 caractères (~13,553 tok) | injecté 20,962 caractères (~5,241 tok)
|
||||
- IDENTITY.md: OK | brut 211 caractères (~53 tok) | injecté 211 caractères (~53 tok)
|
||||
- USER.md: OK | brut 388 caractères (~97 tok) | injecté 388 caractères (~97 tok)
|
||||
- HEARTBEAT.md: ABSENT | brut 0 | injecté 0
|
||||
- BOOTSTRAP.md: OK | brut 0 caractères (~0 tok) | injecté 0 caractères (~0 tok)
|
||||
|
||||
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
|
||||
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Tool list (system prompt text): 1,032 chars (~258 tok)
|
||||
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
|
||||
Tools: (same as above)
|
||||
Liste des Skills (texte du prompt système) : 2,184 caractères (~546 tok) (12 Skills)
|
||||
Outils : read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Liste des outils (texte du prompt système) : 1,032 caractères (~258 tok)
|
||||
Schémas d’outils (JSON) : 31,988 caractères (~7,997 tok) (comptent dans le contexte ; non affichés comme texte)
|
||||
Outils : (identiques ci-dessus)
|
||||
|
||||
Session tokens (cached): 14,250 total / ctx=32,000
|
||||
Tokens de session (en cache) : 14,250 au total / ctx=32,000
|
||||
```
|
||||
|
||||
### `/context detail`
|
||||
@ -72,44 +72,44 @@ Session tokens (cached): 14,250 total / ctx=32,000
|
||||
```
|
||||
🧠 Ventilation du contexte (détaillée)
|
||||
…
|
||||
Top skills (prompt entry size):
|
||||
- frontend-design: 412 chars (~103 tok)
|
||||
- oracle: 401 chars (~101 tok)
|
||||
… (+10 more skills)
|
||||
Principaux Skills (taille d’entrée du prompt) :
|
||||
- frontend-design: 412 caractères (~103 tok)
|
||||
- oracle: 401 caractères (~101 tok)
|
||||
… (+10 autres Skills)
|
||||
|
||||
Top tools (schema size):
|
||||
- browser: 9,812 chars (~2,453 tok)
|
||||
- exec: 6,240 chars (~1,560 tok)
|
||||
… (+N more tools)
|
||||
Principaux outils (taille du schéma) :
|
||||
- browser: 9,812 caractères (~2,453 tok)
|
||||
- exec: 6,240 caractères (~1,560 tok)
|
||||
… (+N autres outils)
|
||||
```
|
||||
|
||||
## Ce qui compte dans la fenêtre de contexte
|
||||
|
||||
Tout ce que le modèle reçoit compte, y compris :
|
||||
Tout ce que le modèle reçoit compte, y compris :
|
||||
|
||||
- Le prompt système (toutes les sections).
|
||||
- L’historique de conversation.
|
||||
- Les appels d’outils + les résultats d’outils.
|
||||
- Les pièces jointes/transcriptions (images/audio/fichiers).
|
||||
- Les résumés de compaction et les artefacts d’élagage.
|
||||
- Les « wrappers » du fournisseur ou en-têtes masqués (non visibles, mais quand même comptés).
|
||||
- Prompt système (toutes les sections).
|
||||
- Historique de conversation.
|
||||
- Appels d’outils + résultats d’outils.
|
||||
- Pièces jointes/transcriptions (images/audio/fichiers).
|
||||
- Résumés de Compaction et artefacts d’élagage.
|
||||
- « Wrappers » du fournisseur ou en-têtes cachés (non visibles, mais tout de même comptés).
|
||||
|
||||
## Comment OpenClaw construit le prompt système
|
||||
|
||||
Le prompt système est **géré par OpenClaw** et reconstruit à chaque exécution. Il inclut :
|
||||
Le prompt système appartient à **OpenClaw** et est reconstruit à chaque exécution. Il inclut :
|
||||
|
||||
- La liste des outils + de courtes descriptions.
|
||||
- La liste des Skills (métadonnées uniquement ; voir ci-dessous).
|
||||
- L’emplacement de l’espace de travail.
|
||||
- L’heure (UTC + heure utilisateur convertie si configurée).
|
||||
- Les métadonnées d’exécution (hôte/OS/modèle/réflexion).
|
||||
- Les fichiers bootstrap injectés de l’espace de travail sous **Contexte du projet**.
|
||||
- Liste des outils + courtes descriptions.
|
||||
- Liste des Skills (métadonnées uniquement ; voir ci-dessous).
|
||||
- Emplacement de l’espace de travail.
|
||||
- Heure (UTC + heure utilisateur convertie si configurée).
|
||||
- Métadonnées d’exécution (hôte/OS/modèle/réflexion).
|
||||
- Fichiers bootstrap de l’espace de travail injectés sous **Contexte du projet**.
|
||||
|
||||
Ventilation complète : [Prompt système](/fr/concepts/system-prompt).
|
||||
Ventilation complète : [Prompt système](/fr/concepts/system-prompt).
|
||||
|
||||
## Fichiers d’espace de travail injectés (Contexte du projet)
|
||||
## Fichiers de l’espace de travail injectés (Contexte du projet)
|
||||
|
||||
Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail (s’ils sont présents) :
|
||||
Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail (s’ils sont présents) :
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -119,59 +119,59 @@ Par défaut, OpenClaw injecte un ensemble fixe de fichiers d’espace de travail
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (première exécution uniquement)
|
||||
|
||||
Les fichiers volumineux sont tronqués par fichier selon `agents.defaults.bootstrapMaxChars` (valeur par défaut `20000` caractères). OpenClaw applique également une limite totale d’injection bootstrap sur l’ensemble des fichiers avec `agents.defaults.bootstrapTotalMaxChars` (valeur par défaut `150000` caractères). `/context` affiche les tailles **brutes vs injectées** et indique si une troncature a eu lieu.
|
||||
Les fichiers volumineux sont tronqués fichier par fichier à l’aide de `agents.defaults.bootstrapMaxChars` (par défaut `12000` caractères). OpenClaw applique aussi un plafond total d’injection bootstrap sur l’ensemble des fichiers avec `agents.defaults.bootstrapTotalMaxChars` (par défaut `60000` caractères). `/context` affiche les tailles **brutes vs injectées** et indique si une troncature a eu lieu.
|
||||
|
||||
Lorsqu’une troncature se produit, le runtime peut injecter un bloc d’avertissement dans le prompt sous Contexte du projet. Configurez cela avec `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; valeur par défaut `once`).
|
||||
Lorsqu’une troncature se produit, l’exécution peut injecter un bloc d’avertissement dans le prompt sous Contexte du projet. Configurez cela avec `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always` ; `once` par défaut).
|
||||
|
||||
## Skills : injectés ou chargés à la demande
|
||||
## Skills : injectés ou chargés à la demande
|
||||
|
||||
Le prompt système inclut une liste compacte de **Skills** (nom + description + emplacement). Cette liste a une surcharge réelle.
|
||||
Le prompt système inclut une liste compacte des **Skills** (nom + description + emplacement). Cette liste a un coût réel.
|
||||
|
||||
Les instructions des Skills ne sont _pas_ incluses par défaut. Le modèle est censé `read` le fichier `SKILL.md` du skill **uniquement quand nécessaire**.
|
||||
Les instructions des Skills ne sont _pas_ incluses par défaut. Le modèle est censé `read` le `SKILL.md` du skill **uniquement lorsque nécessaire**.
|
||||
|
||||
## Outils : il y a deux coûts
|
||||
## Outils : il y a deux coûts
|
||||
|
||||
Les outils affectent le contexte de deux façons :
|
||||
Les outils affectent le contexte de deux façons :
|
||||
|
||||
1. **Texte de la liste des outils** dans le prompt système (ce que vous voyez comme « Outillage »).
|
||||
1. **Texte de la liste des outils** dans le prompt système (ce que vous voyez comme « Tooling »).
|
||||
2. **Schémas d’outils** (JSON). Ils sont envoyés au modèle afin qu’il puisse appeler des outils. Ils comptent dans le contexte même si vous ne les voyez pas sous forme de texte brut.
|
||||
|
||||
`/context detail` détaille les plus gros schémas d’outils afin que vous puissiez voir ce qui domine.
|
||||
`/context detail` ventile les schémas d’outils les plus volumineux afin que vous puissiez voir ce qui domine.
|
||||
|
||||
## Commandes, directives et « raccourcis en ligne »
|
||||
## Commandes, directives et « raccourcis inline »
|
||||
|
||||
Les commandes slash sont gérées par la Gateway. Il existe quelques comportements différents :
|
||||
Les commandes slash sont gérées par la Gateway. Il existe quelques comportements différents :
|
||||
|
||||
- **Commandes autonomes** : un message qui n’est que `/...` s’exécute comme une commande.
|
||||
- **Directives** : `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` sont retirées avant que le modèle ne voie le message.
|
||||
- Les messages contenant uniquement une directive conservent les paramètres de session.
|
||||
- Les directives en ligne dans un message normal agissent comme des indications par message.
|
||||
- **Raccourcis en ligne** (expéditeurs autorisés uniquement) : certains jetons `/...` dans un message normal peuvent s’exécuter immédiatement (exemple : « hey /status »), et sont retirés avant que le modèle ne voie le texte restant.
|
||||
- **Commandes autonomes** : un message qui contient uniquement `/...` s’exécute comme une commande.
|
||||
- **Directives** : `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` sont retirées avant que le modèle ne voie le message.
|
||||
- Les messages contenant uniquement des directives conservent les paramètres de session.
|
||||
- Les directives inline dans un message normal agissent comme des indications propres au message.
|
||||
- **Raccourcis inline** (expéditeurs autorisés uniquement) : certains tokens `/...` dans un message normal peuvent s’exécuter immédiatement (exemple : « hey /status »), et sont retirés avant que le modèle ne voie le texte restant.
|
||||
|
||||
Détails : [Commandes slash](/fr/tools/slash-commands).
|
||||
Détails : [Commandes slash](/fr/tools/slash-commands).
|
||||
|
||||
## Sessions, compaction et élagage (ce qui persiste)
|
||||
## Sessions, Compaction et élagage (ce qui persiste)
|
||||
|
||||
Ce qui persiste d’un message à l’autre dépend du mécanisme :
|
||||
Ce qui persiste entre les messages dépend du mécanisme :
|
||||
|
||||
- **L’historique normal** persiste dans la transcription de session jusqu’à être compacté/élagué par la politique.
|
||||
- **La compaction** conserve un résumé dans la transcription et garde les messages récents intacts.
|
||||
- **L’élagage** supprime les anciens résultats d’outils du prompt _en mémoire_ pour une exécution, mais ne réécrit pas la transcription.
|
||||
- **L’historique normal** persiste dans la transcription de session jusqu’à ce qu’il soit compacté/élagué par la politique.
|
||||
- **Compaction** conserve un résumé dans la transcription et garde intacts les messages récents.
|
||||
- **L’élagage** retire les anciens résultats d’outils du prompt _en mémoire_ pour une exécution, mais ne réécrit pas la transcription.
|
||||
|
||||
Documentation : [Session](/fr/concepts/session), [Compaction](/fr/concepts/compaction), [Élagage de session](/fr/concepts/session-pruning).
|
||||
Documentation : [Session](/fr/concepts/session), [Compaction](/fr/concepts/compaction), [Élagage de session](/fr/concepts/session-pruning).
|
||||
|
||||
Par défaut, OpenClaw utilise le moteur de contexte intégré `legacy` pour l’assemblage et la compaction. Si vous installez un Plugin qui fournit `kind: "context-engine"` et le sélectionnez avec `plugins.slots.contextEngine`, OpenClaw délègue alors l’assemblage du contexte, `/compact` et les hooks associés du cycle de vie du contexte de sous-agent à ce moteur à la place. `ownsCompaction: false` ne provoque pas de retour automatique au moteur legacy ; le moteur actif doit toujours implémenter `compact()` correctement. Voir [Context Engine](/fr/concepts/context-engine) pour l’interface enfichable complète, les hooks de cycle de vie et la configuration.
|
||||
Par défaut, OpenClaw utilise le moteur de contexte intégré `legacy` pour l’assemblage et la Compaction. Si vous installez un Plugin qui fournit `kind: "context-engine"` et le sélectionnez avec `plugins.slots.contextEngine`, OpenClaw délègue à ce moteur l’assemblage du contexte, `/compact` et les hooks de cycle de vie de contexte des sous-agents associés. `ownsCompaction: false` ne revient pas automatiquement au moteur legacy ; le moteur actif doit tout de même implémenter correctement `compact()`. Voir [Context Engine](/fr/concepts/context-engine) pour l’interface enfichable complète, les hooks de cycle de vie et la configuration.
|
||||
|
||||
## Ce que `/context` signale réellement
|
||||
## Ce que `/context` rapporte réellement
|
||||
|
||||
`/context` privilégie le dernier rapport de prompt système **construit à l’exécution** lorsqu’il est disponible :
|
||||
`/context` privilégie le dernier rapport de prompt système **construit à l’exécution** lorsqu’il est disponible :
|
||||
|
||||
- `System prompt (run)` = capturé à partir de la dernière exécution embarquée (capable d’utiliser des outils) et conservé dans le stockage de session.
|
||||
- `System prompt (run)` = capturé lors de la dernière exécution embarquée (capable d’utiliser des outils) et conservé dans le stockage de session.
|
||||
- `System prompt (estimate)` = calculé à la volée lorsqu’aucun rapport d’exécution n’existe (ou lors d’une exécution via un backend CLI qui ne génère pas le rapport).
|
||||
|
||||
Dans les deux cas, il signale les tailles et les principaux contributeurs ; il ne vide **pas** le prompt système complet ni les schémas d’outils.
|
||||
Dans les deux cas, il rapporte des tailles et les principaux contributeurs ; il **n’affiche pas** le prompt système complet ni les schémas d’outils.
|
||||
|
||||
## Lié à ce sujet
|
||||
## Lié
|
||||
|
||||
- [Context Engine](/fr/concepts/context-engine) — injection de contexte personnalisée via des plugins
|
||||
- [Compaction](/fr/concepts/compaction) — résumé des longues conversations
|
||||
|
||||
@ -2,50 +2,50 @@
|
||||
read_when:
|
||||
- Extension de qa-lab ou de qa-channel
|
||||
- Ajout de scénarios QA adossés au dépôt
|
||||
- Création d’une automatisation QA plus réaliste autour du tableau de bord Gateway
|
||||
- Création d’une automatisation QA de plus grand réalisme autour du tableau de bord Gateway
|
||||
summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios initialisés et les rapports de protocole
|
||||
title: Automatisation QA E2E
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T06:57:31Z"
|
||||
generated_at: "2026-04-18T06:43:38Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
|
||||
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automatisation QA E2E
|
||||
|
||||
La pile QA privée a pour but d’exercer OpenClaw d’une manière plus réaliste,
|
||||
structurée comme un canal, qu’un simple test unitaire ne peut le faire.
|
||||
La pile QA privée a pour objectif d’exercer OpenClaw d’une manière plus réaliste,
|
||||
façonnée comme un canal, qu’un simple test unitaire ne peut le faire.
|
||||
|
||||
Éléments actuels :
|
||||
Éléments actuels :
|
||||
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec des surfaces pour les MP, les canaux, les fils,
|
||||
les réactions, les modifications et les suppressions.
|
||||
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec des surfaces de MP, canal, fil,
|
||||
réaction, modification et suppression.
|
||||
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
|
||||
injecter des messages entrants et exporter un rapport Markdown.
|
||||
- `qa/` : ressources initiales adossées au dépôt pour la tâche de démarrage et les
|
||||
- `qa/` : ressources initiales adossées au dépôt pour la tâche de lancement et les
|
||||
scénarios QA de référence.
|
||||
|
||||
Le flux opérateur QA actuel est un site QA à deux volets :
|
||||
Le flux opérateur QA actuel est un site QA à deux volets :
|
||||
|
||||
- Gauche : tableau de bord Gateway (UI de contrôle) avec l’agent.
|
||||
- Droite : QA Lab, affichant la transcription de type Slack et le plan du scénario.
|
||||
- Gauche : tableau de bord Gateway (Control UI) avec l’agent.
|
||||
- Droite : QA Lab, affichant une transcription de type Slack et le plan de scénario.
|
||||
|
||||
Exécutez-le avec :
|
||||
Exécutez-le avec :
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Cela construit le site QA, démarre la voie Gateway adossée à Docker et expose la
|
||||
page QA Lab où un opérateur ou une boucle d’automatisation peut confier à l’agent une mission QA,
|
||||
observer le comportement réel du canal et consigner ce qui a fonctionné, échoué ou
|
||||
est resté bloqué.
|
||||
page QA Lab où un opérateur ou une boucle d’automatisation peut donner à l’agent une
|
||||
mission QA, observer le comportement réel du canal et consigner ce qui a fonctionné, échoué
|
||||
ou est resté bloqué.
|
||||
|
||||
Pour itérer plus rapidement sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
démarrez la pile avec un bundle QA Lab monté par liaison :
|
||||
Pour une itération plus rapide sur l’interface de QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
démarrez la pile avec un bundle QA Lab monté par liaison :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -57,24 +57,24 @@ pnpm qa:lab:watch
|
||||
`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte par liaison
|
||||
`extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch`
|
||||
reconstruit ce bundle à chaque modification, et le navigateur se recharge automatiquement lorsque le hachage
|
||||
des ressources QA Lab change.
|
||||
des ressources de QA Lab change.
|
||||
|
||||
Pour une voie de smoke test Matrix sur transport réel, exécutez :
|
||||
Pour une voie smoke Matrix avec transport réel, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
Cette voie provisionne un homeserver Tuwunel jetable dans Docker, enregistre
|
||||
des utilisateurs temporaires pilote, SUT et observateur, crée une salle privée, puis exécute
|
||||
le vrai Plugin Matrix dans un enfant Gateway QA. La voie sur transport réel conserve
|
||||
des utilisateurs temporaires de pilote, SUT et observateur, crée un salon privé, puis exécute
|
||||
le vrai plugin Matrix dans un processus enfant QA Gateway. La voie de transport en direct conserve
|
||||
la configuration enfant limitée au transport testé, afin que Matrix s’exécute sans
|
||||
`qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés ainsi
|
||||
qu’un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour
|
||||
capturer également la sortie externe de build/lancement de `scripts/run-node.mjs`, définissez
|
||||
`qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés et
|
||||
un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour
|
||||
capturer également la sortie de construction/lancement externe de `scripts/run-node.mjs`, définissez
|
||||
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` vers un fichier journal local au dépôt.
|
||||
|
||||
Pour une voie de smoke test Telegram sur transport réel, exécutez :
|
||||
Pour une voie smoke Telegram avec transport réel, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
@ -85,122 +85,127 @@ serveur jetable. Elle nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et
|
||||
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, ainsi que deux bots distincts dans le même
|
||||
groupe privé. Le bot SUT doit avoir un nom d’utilisateur Telegram, et l’observation
|
||||
bot à bot fonctionne mieux lorsque les deux bots ont le mode de communication Bot-to-Bot
|
||||
activé dans `@BotFather`.
|
||||
bot à bot fonctionne au mieux lorsque les deux bots ont le mode de communication
|
||||
bot à bot activé dans `@BotFather`.
|
||||
|
||||
Les voies sur transport réel partagent désormais un contrat plus réduit au lieu que chacune
|
||||
invente sa propre structure de liste de scénarios.
|
||||
Les voies de transport en direct partagent désormais un contrat plus restreint au lieu que chacune invente
|
||||
sa propre forme de liste de scénarios.
|
||||
|
||||
`qa-channel` reste la suite large de comportements produit synthétiques et ne fait pas partie
|
||||
de la matrice de couverture des transports réels.
|
||||
`qa-channel` reste la suite large de comportement produit synthétique et ne fait pas partie
|
||||
de la matrice de couverture de transport en direct.
|
||||
|
||||
| Voie | Canary | Gating par mention | Blocage par allowlist | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande d’aide |
|
||||
| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | --------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| Voie | Canary | Filtrage des mentions | Blocage de la liste d’autorisation | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande help |
|
||||
| -------- | ------ | --------------------- | ---------------------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | ------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
Cela permet à `qa-channel` de rester la suite large de comportements produit, tandis que Matrix,
|
||||
Telegram et les futurs transports réels partagent une checklist explicite unique du contrat de transport.
|
||||
Cela permet de conserver `qa-channel` comme suite large de comportement produit tandis que Matrix,
|
||||
Telegram et les futurs transports en direct partagent une checklist explicite de contrat de transport.
|
||||
|
||||
Pour une voie de VM Linux jetable sans intégrer Docker dans le chemin QA, exécutez :
|
||||
Pour une voie VM Linux jetable sans faire entrer Docker dans le chemin QA, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw
|
||||
dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le
|
||||
résumé dans `.artifacts/qa-e2e/...` sur l’hôte.
|
||||
Cela démarre un invité Multipass neuf, installe les dépendances, construit OpenClaw
|
||||
dans l’invité, exécute `qa suite`, puis copie le rapport QA et le
|
||||
résumé habituels vers `.artifacts/qa-e2e/...` sur l’hôte.
|
||||
Cela réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte.
|
||||
Les exécutions de suite sur l’hôte et dans Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle
|
||||
avec des workers Gateway isolés, jusqu’à 64 workers ou au nombre de scénarios sélectionnés.
|
||||
Utilisez `--concurrency <count>` pour ajuster le nombre de workers, ou
|
||||
Les exécutions de suite sur hôte et Multipass exécutent plusieurs scénarios sélectionnés en parallèle
|
||||
avec des workers Gateway isolés par défaut, jusqu’à 64 workers ou au nombre
|
||||
de scénarios sélectionnés. Utilisez `--concurrency <count>` pour ajuster le nombre de workers, ou
|
||||
`--concurrency 1` pour une exécution en série.
|
||||
Les exécutions live transmettent les entrées d’auth QA prises en charge qui sont pratiques pour
|
||||
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA live, et
|
||||
`CODEX_HOME` lorsqu’il est présent. Conservez `--output-dir` sous la racine du dépôt afin que l’invité
|
||||
puisse écrire en retour via l’espace de travail monté.
|
||||
Les exécutions en direct transmettent les entrées d’auth QA prises en charge qui sont pratiques pour
|
||||
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA en direct, et
|
||||
`CODEX_HOME` lorsqu’il est présent. Gardez `--output-dir` sous la racine du dépôt afin que l’invité
|
||||
puisse réécrire via l’espace de travail monté.
|
||||
|
||||
## Ressources initiales adossées au dépôt
|
||||
|
||||
Les ressources initiales se trouvent dans `qa/` :
|
||||
Les ressources initiales se trouvent dans `qa/` :
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Elles sont volontairement dans git afin que le plan QA soit visible à la fois pour les humains et pour
|
||||
Elles sont volontairement dans git pour que le plan QA soit visible à la fois des humains et de
|
||||
l’agent.
|
||||
|
||||
`qa-lab` doit rester un exécuteur Markdown générique. Chaque fichier Markdown de scénario est
|
||||
la source de vérité pour une exécution de test et doit définir :
|
||||
la source de vérité pour une exécution de test et doit définir :
|
||||
|
||||
- les métadonnées du scénario
|
||||
- des métadonnées facultatives de catégorie, capacité, voie et risque
|
||||
- les références de documentation et de code
|
||||
- les exigences facultatives en matière de Plugin
|
||||
- le correctif facultatif de configuration Gateway
|
||||
- des exigences de plugin facultatives
|
||||
- un patch de configuration Gateway facultatif
|
||||
- le `qa-flow` exécutable
|
||||
|
||||
La surface d’exécution réutilisable qui sous-tend `qa-flow` peut rester générique
|
||||
et transverse. Par exemple, des scénarios Markdown peuvent combiner des helpers côté transport
|
||||
avec des helpers côté navigateur qui pilotent l’UI de contrôle intégrée via le
|
||||
point d’intégration Gateway `browser.request` sans ajouter d’exécuteur spécialisé.
|
||||
et transversale. Par exemple, les scénarios Markdown peuvent combiner des helpers côté
|
||||
transport avec des helpers côté navigateur qui pilotent la Control UI intégrée via la
|
||||
jointure Gateway `browser.request` sans ajouter d’exécuteur spécifique.
|
||||
|
||||
La liste de référence doit rester suffisamment large pour couvrir :
|
||||
Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier
|
||||
de l’arborescence source. Gardez les ID de scénario stables lorsque les fichiers sont déplacés ; utilisez
|
||||
`docsRefs` et `codeRefs` pour la traçabilité de l’implémentation.
|
||||
|
||||
- les MP et les conversations en canal
|
||||
La liste de référence doit rester suffisamment large pour couvrir :
|
||||
|
||||
- les MP et le chat en canal
|
||||
- le comportement des fils
|
||||
- le cycle de vie des actions sur les messages
|
||||
- les rappels Cron
|
||||
- le rappel de mémoire
|
||||
- le rappel mémoire
|
||||
- le changement de modèle
|
||||
- le transfert vers un sous-agent
|
||||
- le transfert à un sous-agent
|
||||
- la lecture du dépôt et de la documentation
|
||||
- une petite tâche de build comme Lobster Invaders
|
||||
- une petite tâche de build telle que Lobster Invaders
|
||||
|
||||
## Voies avec fournisseur simulé
|
||||
## Voies mock de fournisseur
|
||||
|
||||
`qa suite` dispose de deux voies locales avec fournisseur simulé :
|
||||
`qa suite` dispose de deux voies mock locales de fournisseur :
|
||||
|
||||
- `mock-openai` est le mock OpenClaw sensible aux scénarios. Il reste la
|
||||
voie simulée déterministe par défaut pour la QA adossée au dépôt et les gates de parité.
|
||||
- `aimock` démarre un serveur fournisseur adossé à AIMock pour une couverture expérimentale
|
||||
de protocole, de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne
|
||||
remplace pas le répartiteur de scénarios `mock-openai`.
|
||||
- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste la
|
||||
voie mock déterministe par défaut pour la QA adossée au dépôt et les contrôles de parité.
|
||||
- `aimock` démarre un serveur de fournisseur adossé à AIMock pour une couverture expérimentale de protocole,
|
||||
de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne remplace pas
|
||||
le répartiteur de scénarios `mock-openai`.
|
||||
|
||||
L’implémentation des voies fournisseur se trouve sous `extensions/qa-lab/src/providers/`.
|
||||
Chaque fournisseur possède ses valeurs par défaut, le démarrage de serveur local, la configuration
|
||||
du modèle Gateway, les besoins de préparation du profil d’auth, et les indicateurs de capacités live/simulées.
|
||||
Le code partagé de suite et Gateway doit passer par le registre des fournisseurs plutôt que de
|
||||
se brancher selon les noms de fournisseurs.
|
||||
L’implémentation des voies de fournisseur se trouve dans `extensions/qa-lab/src/providers/`.
|
||||
Chaque fournisseur possède ses valeurs par défaut, le démarrage du serveur local, la configuration
|
||||
du modèle Gateway, les besoins de préparation du profil d’authentification, et les drapeaux de capacité live/mock.
|
||||
Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu
|
||||
de brancher sur les noms des fournisseurs.
|
||||
|
||||
## Adaptateurs de transport
|
||||
|
||||
`qa-lab` possède un point d’intégration de transport générique pour les scénarios QA Markdown.
|
||||
`qa-channel` est le premier adaptateur sur ce point d’intégration, mais l’objectif de conception est plus large :
|
||||
les futurs canaux réels ou synthétiques doivent pouvoir se brancher sur le même exécuteur de suite
|
||||
`qa-lab` possède une jointure de transport générique pour les scénarios QA Markdown.
|
||||
`qa-channel` est le premier adaptateur sur cette jointure, mais l’objectif de conception est plus large :
|
||||
les futurs canaux réels ou synthétiques doivent se brancher sur le même exécuteur de suite
|
||||
au lieu d’ajouter un exécuteur QA spécifique au transport.
|
||||
|
||||
Au niveau de l’architecture, la séparation est la suivante :
|
||||
Au niveau de l’architecture, la séparation est la suivante :
|
||||
|
||||
- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et les rapports.
|
||||
- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting.
|
||||
- l’adaptateur de transport possède la configuration Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé.
|
||||
- les fichiers de scénarios Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute.
|
||||
- les fichiers de scénario Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute.
|
||||
|
||||
Les directives d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans
|
||||
Les consignes d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans
|
||||
[Testing](/fr/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## Rapports
|
||||
|
||||
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie observée du bus.
|
||||
Le rapport doit répondre aux questions suivantes :
|
||||
Le rapport doit répondre à :
|
||||
|
||||
- Ce qui a fonctionné
|
||||
- Ce qui a échoué
|
||||
- Ce qui est resté bloqué
|
||||
- Quels scénarios de suivi méritent d’être ajoutés
|
||||
- Quels scénarios de suivi valent la peine d’être ajoutés
|
||||
|
||||
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles live
|
||||
et écrivez un rapport Markdown évalué :
|
||||
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références
|
||||
de modèles live et écrivez un rapport Markdown évalué :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -219,36 +224,36 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
La commande exécute des processus enfants Gateway QA locaux, pas Docker. Les
|
||||
scénarios d’évaluation de caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur
|
||||
ordinaires tels que la conversation, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle
|
||||
candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande conserve chaque
|
||||
transcription complète, enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
|
||||
La commande exécute des processus enfants QA Gateway locaux, pas Docker. Les
|
||||
scénarios d’évaluation du caractère doivent définir le persona via `SOUL.md`, puis exécuter des tours
|
||||
utilisateur ordinaires tels que le chat, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle
|
||||
candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque transcription complète,
|
||||
enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode fast avec
|
||||
un raisonnement `xhigh` de classer les exécutions selon le naturel, l’ambiance et l’humour.
|
||||
Utilisez `--blind-judge-models` lors de la comparaison entre fournisseurs : l’invite du juge reçoit toujours
|
||||
chaque transcription et l’état d’exécution, mais les références candidates sont remplacées par des
|
||||
étiquettes neutres telles que `candidate-01` ; le rapport réassocie les classements aux vraies références après
|
||||
Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours
|
||||
chaque transcription et état d’exécution, mais les références candidates sont remplacées par des
|
||||
étiquettes neutres telles que `candidate-01` ; le rapport remappe les classements aux vraies références après
|
||||
l’analyse.
|
||||
Les exécutions candidates utilisent par défaut un niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui
|
||||
le prennent en charge. Remplacez un candidat spécifique en ligne avec
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours une
|
||||
valeur de repli globale, et l’ancienne forme `--model-thinking <provider/model=level>` est
|
||||
conservée pour compatibilité.
|
||||
Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé là
|
||||
où le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un
|
||||
candidat ou juge particulier a besoin d’un remplacement. Passez `--fast` uniquement lorsque vous souhaitez
|
||||
forcer le mode rapide pour tous les modèles candidats. Les durées des candidats et des juges sont
|
||||
enregistrées dans le rapport pour l’analyse de benchmark, mais les invites des juges indiquent explicitement
|
||||
Les références candidates OpenAI utilisent par défaut le mode fast afin que le traitement prioritaire soit utilisé là où
|
||||
le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un
|
||||
candidat ou juge donné a besoin d’une substitution. Passez `--fast` uniquement si vous souhaitez
|
||||
forcer le mode fast pour tous les modèles candidats. Les durées des candidats et des juges sont
|
||||
enregistrées dans le rapport pour l’analyse comparative, mais les invites des juges indiquent explicitement
|
||||
de ne pas classer selon la vitesse.
|
||||
Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez
|
||||
`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression sur le Gateway local
|
||||
rendent une exécution trop bruitée.
|
||||
Lorsqu’aucun `--model` candidat n’est fourni, l’évaluation de caractère utilise par défaut
|
||||
`--concurrency` ou `--judge-concurrency` lorsque les limites des fournisseurs ou la pression sur la Gateway locale
|
||||
rendent une exécution trop bruyante.
|
||||
Lorsqu’aucun `--model` candidat n’est transmis, l’évaluation du caractère utilise par défaut
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5`, et
|
||||
`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est fourni.
|
||||
Lorsqu’aucun `--judge-model` n’est fourni, les juges utilisent par défaut
|
||||
`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est transmis.
|
||||
Lorsqu’aucun `--judge-model` n’est transmis, les juges utilisent par défaut
|
||||
`openai/gpt-5.4,thinking=xhigh,fast` et
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 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
|
||||
- Modification du texte du prompt système, de la liste des outils ou des sections de l’heure/Heartbeat
|
||||
- Modification du comportement d’amorçage de l’espace de travail ou d’injection des Skills
|
||||
summary: Ce que contient le prompt système d’OpenClaw et comment il est assemblé
|
||||
title: Prompt système
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:43Z"
|
||||
generated_at: "2026-04-18T06:43:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,81 +19,80 @@ OpenClaw construit un prompt système personnalisé pour chaque exécution d’a
|
||||
|
||||
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 détenu par OpenClaw. Le runtime du fournisseur peut :
|
||||
Les plugins de fournisseur peuvent contribuer avec des indications de prompt conscientes du cache sans remplacer l’intégralité du prompt appartenant à OpenClaw. L’environnement d’exécution du fournisseur peut :
|
||||
|
||||
- remplacer un petit ensemble de sections cœur nommées (`interaction_style`,
|
||||
- remplacer un petit ensemble de sections principales nommées (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- injecter un **préfixe stable** au-dessus de la limite du cache de prompt
|
||||
- injecter un **suffixe dynamique** en dessous de la limite du cache de prompt
|
||||
- injecter un **préfixe stable** au-dessus de la limite de cache du prompt
|
||||
- injecter un **suffixe dynamique** en dessous de la limite de cache du prompt
|
||||
|
||||
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.
|
||||
Utilisez les contributions appartenant au 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 changements globaux du prompt, pas pour le comportement normal d’un fournisseur.
|
||||
|
||||
## Structure
|
||||
|
||||
Le prompt est volontairement compact et utilise des sections fixes :
|
||||
Le prompt est intentionnellement compact et utilise des sections fixes :
|
||||
|
||||
- **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.
|
||||
- **Tooling** : rappel structuré de la source de vérité des outils, plus indications d’exécution sur l’utilisation des outils.
|
||||
- **Safety** : bref rappel de garde-fous pour éviter les comportements de recherche de pouvoir ou de contournement de la supervision.
|
||||
- **Skills** (quand disponibles) : indique au modèle comment charger à la demande les instructions de 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
|
||||
`config.schema.lookup`, modifier la configuration avec `config.patch`, remplacer la configuration complète avec `config.apply`, et exécuter `update.run` uniquement à la demande explicite de l’utilisateur. L’outil `gateway`, réservé au propriétaire, refuse aussi 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.
|
||||
- **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.
|
||||
- **Workspace Files (injected)** : indique que des fichiers d’amorçage sont inclus ci-dessous.
|
||||
- **Sandbox** (quand activé) : indique l’environnement d’exécution sandboxé, les chemins sandbox, et si une exécution avec privilèges élevés est disponible.
|
||||
- **Current Date & Time** : heure locale de l’utilisateur, fuseau horaire et format d’heure.
|
||||
- **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.
|
||||
- **Heartbeats** : prompt 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 (quand détectée), niveau de réflexion (une ligne).
|
||||
- **Reasoning** : niveau de visibilité actuel + indication de bascule `/reasoning`.
|
||||
|
||||
La section Tooling inclut également des indications d’exécution pour les tâches longues :
|
||||
La section Tooling inclut également des indications d’exécution pour le travail de longue durée :
|
||||
|
||||
- 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
|
||||
au lieu de boucles de veille `exec`, 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 de s’exécuter
|
||||
en arrière-plan
|
||||
- lorsque le réveil automatique à la fin est activé, démarrer la commande une seule fois et s’appuyer sur
|
||||
le mécanisme de réveil push lorsqu’elle produit une sortie ou échoue
|
||||
- utiliser `process` pour les journaux, l’état, l’entrée ou l’intervention lorsque vous devez
|
||||
- lorsque le réveil automatique à l’achèvement est activé, démarrer la commande une seule fois et s’appuyer sur
|
||||
le chemin de réveil par push lorsqu’elle émet une sortie ou échoue
|
||||
- utiliser `process` pour les journaux, l’état, l’entrée ou une intervention lorsque vous devez
|
||||
inspecter une commande en cours d’exécution
|
||||
- si la tâche est plus importante, préférer `sessions_spawn` ; la fin des sous-agents est
|
||||
signalée par push et réannoncée automatiquement au demandeur
|
||||
- si la tâche est plus importante, préférer `sessions_spawn` ; l’achèvement du sous-agent se fait par push et est annoncé automatiquement au demandeur
|
||||
- ne pas sonder `subagents list` / `sessions_list` en boucle uniquement pour attendre
|
||||
la fin
|
||||
l’achèvement
|
||||
|
||||
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
|
||||
Lorsque l’outil expérimental `update_plan` est activé, Tooling indique aussi au
|
||||
modèle de ne l’utiliser que pour un travail non trivial à 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 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.
|
||||
Les garde-fous de sécurité dans le prompt système sont indicatifs. Ils guident le comportement du modèle mais n’appliquent pas de politique. Utilisez la politique des outils, les approbations d’exécution, le sandboxing et les listes d’autorisation des canaux pour une application stricte ; les opérateurs peuvent les désactiver par conception.
|
||||
|
||||
Sur les canaux 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.
|
||||
Sur les canaux disposant de cartes/boutons d’approbation natifs, le prompt d’exécution indique maintenant à
|
||||
l’agent de s’appuyer d’abord sur cette interface d’approbation native. Il ne doit inclure une commande manuelle
|
||||
`/approve` que si le résultat de l’outil indique que les approbations par chat ne sont pas disponibles ou
|
||||
si l’approbation manuelle est la seule voie possible.
|
||||
|
||||
## Modes de prompt
|
||||
|
||||
OpenClaw peut générer des prompts système plus petits pour les sous-agents. Le runtime définit un
|
||||
OpenClaw peut générer des prompts système plus petits pour les sous-agents. L’environnement d’exécution 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**, **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
|
||||
**Messaging**, **Silent Replies**, et **Heartbeats**. Tooling, **Safety**,
|
||||
Workspace, Sandbox, Current Date & Time (quand connue), Runtime, et le contexte
|
||||
injecté restent disponibles.
|
||||
- `none` : renvoie uniquement la ligne d’identité de base.
|
||||
|
||||
Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont étiquetés **Subagent
|
||||
Lorsque `promptMode=minimal`, les prompts injectés supplémentaires sont libellés **Subagent
|
||||
Context** au lieu de **Group Chat Context**.
|
||||
|
||||
## Injection du bootstrap de l’espace de travail
|
||||
## Injection de l’amorçage de l’espace de travail
|
||||
|
||||
Les fichiers de bootstrap sont tronqués 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 :
|
||||
Les fichiers d’amorçage sont tronqués puis ajoutés sous **Project Context** afin que le modèle voie le contexte d’identité et de profil sans nécessiter de lectures explicites :
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -105,46 +104,46 @@ Les fichiers de bootstrap sont tronqués et ajoutés sous **Project Context** af
|
||||
- `MEMORY.md` lorsqu’il est présent, sinon `memory.md` comme solution de repli en minuscules
|
||||
|
||||
Tous ces fichiers sont **injectés dans la fenêtre de contexte** à chaque tour, sauf si
|
||||
une condition spécifique 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
|
||||
un garde-fou spécifique à un 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 quand
|
||||
`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 qu’une Compaction plus fréquente.
|
||||
en particulier `MEMORY.md`, qui peut grossir avec le temps et entraîner une utilisation
|
||||
du contexte étonnamment élevée ainsi qu’une Compaction plus fréquente.
|
||||
|
||||
> **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 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.
|
||||
> Project Context d’amorçage normal. Lors des tours ordinaires, on y accède à la
|
||||
> demande via les outils `memory_search` et `memory_get`, donc ils ne comptent pas dans la
|
||||
> fenêtre de contexte tant que le modèle ne les lit pas explicitement. Les tours `/new` et
|
||||
> `/reset` simples constituent l’exception : l’environnement d’exécution peut préfixer la mémoire quotidienne récente
|
||||
> sous forme de bloc ponctuel de contexte de démarrage pour ce premier tour.
|
||||
|
||||
Les fichiers volumineux sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par
|
||||
`agents.defaults.bootstrapMaxChars` (par défaut : 20000). Le contenu total du bootstrap injecté
|
||||
Les gros fichiers sont tronqués avec un marqueur. La taille maximale par fichier est contrôlée par
|
||||
`agents.defaults.bootstrapMaxChars` (par défaut : 12000). Le contenu total injecté de l’amorçage
|
||||
sur l’ensemble des fichiers est plafonné par `agents.defaults.bootstrapTotalMaxChars`
|
||||
(par défaut : 150000). Les fichiers manquants injectent un court marqueur de fichier manquant. En cas de troncature,
|
||||
OpenClaw peut injecter un bloc d’avertissement dans Project Context ; contrôlez cela avec
|
||||
(par défaut : 60000). Les fichiers manquants injectent un court marqueur de fichier manquant. Lorsqu’une troncature
|
||||
se produit, 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 de bootstrap
|
||||
sont filtrés pour garder le contexte du sous-agent réduit).
|
||||
Les sessions de sous-agent n’injectent que `AGENTS.md` et `TOOLS.md` (les autres fichiers d’amorçage
|
||||
sont filtrés pour conserver un petit contexte de sous-agent).
|
||||
|
||||
Les hooks internes peuvent intercepter cette étape via `agent:bootstrap` pour modifier ou remplacer
|
||||
les fichiers de bootstrap injectés (par exemple en remplaçant `SOUL.md` par un persona alternatif).
|
||||
les fichiers d’amorçage injectés (par exemple en remplaçant `SOUL.md` par une persona alternative).
|
||||
|
||||
Si vous souhaitez que l’agent paraisse moins générique, commencez par
|
||||
[Guide de personnalité SOUL.md](/fr/concepts/soul).
|
||||
|
||||
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).
|
||||
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 [Context](/fr/concepts/context).
|
||||
|
||||
## Gestion du temps
|
||||
|
||||
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).
|
||||
fuseau horaire de l’utilisateur est connu. Pour conserver la stabilité du cache du prompt, il inclut désormais uniquement le
|
||||
**fuseau horaire** (sans horloge dynamique ni format d’heure).
|
||||
|
||||
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
|
||||
inclut une ligne d’horodatage. Le même outil peut aussi définir une substitution de modèle par session
|
||||
(`model=default` l’efface).
|
||||
|
||||
Configurez avec :
|
||||
@ -152,17 +151,17 @@ Configurez avec :
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Voir [Date & Time](/fr/date-time) pour tous les détails de comportement.
|
||||
Voir [Date & Time](/fr/date-time) pour les détails complets du comportement.
|
||||
|
||||
## Skills
|
||||
|
||||
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 aucun Skill n’est admissible, la
|
||||
(`formatSkillsForPrompt`) qui inclut le **chemin de fichier** de 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 aucun Skill n’est admissible, la
|
||||
section Skills est omise.
|
||||
|
||||
L’admissibilité inclut les conditions des métadonnées des Skills, les vérifications de l’environnement/configuration du runtime,
|
||||
L’admissibilité comprend les garde-fous de métadonnées du Skill, les vérifications de l’environnement/configuration d’exécution,
|
||||
et la liste d’autorisation effective des Skills de l’agent lorsque `agents.defaults.skills` ou
|
||||
`agents.list[].skills` est configuré.
|
||||
|
||||
@ -176,26 +175,26 @@ et la liste d’autorisation effective des Skills de l’agent lorsque `agents.d
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Cela permet de conserver un prompt de base réduit tout en rendant possible une utilisation ciblée des Skills.
|
||||
Cela permet de conserver un petit prompt de base tout en activant un usage ciblé 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`
|
||||
- Substitution par agent : `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Les extraits runtime génériques bornés utilisent une autre surface :
|
||||
Les extraits d’exécution génériques bornés utilisent une surface différente :
|
||||
|
||||
- `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.
|
||||
Cette séparation garde le dimensionnement des Skills distinct du dimensionnement de lecture/injection de l’exécution, par exemple pour
|
||||
`memory_get`, les résultats d’outils en direct, et les actualisations de AGENTS.md après Compaction.
|
||||
|
||||
## Documentation
|
||||
|
||||
Lorsqu’elle est disponible, le prompt système inclut une section **Documentation** qui pointe vers le
|
||||
répertoire local de la documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation 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
|
||||
répertoire local de documentation OpenClaw (soit `docs/` dans l’espace de travail du dépôt, soit la documentation du
|
||||
package npm intégré) et mentionne également le miroir public, le dépôt source, le Discord de la communauté, et
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) pour la découverte de 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
|
||||
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,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Implémentation ou mise à jour des clients WS Gateway
|
||||
- Implémenter ou mettre à jour des clients WS Gateway
|
||||
- Débogage des incompatibilités de protocole ou des échecs de connexion
|
||||
- Régénération du schéma/des modèles du protocole
|
||||
summary: 'Protocole WebSocket Gateway : poignée de main, trames, gestion des versions'
|
||||
summary: 'Protocole WebSocket Gateway : négociation, trames, gestion des versions'
|
||||
title: Protocole Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-16T06:57:00Z"
|
||||
generated_at: "2026-04-18T06:43:36Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3
|
||||
source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protocole Gateway (WebSocket)
|
||||
|
||||
Le protocole WS Gateway est le **plan de contrôle unique + transport de nœuds** pour
|
||||
OpenClaw. Tous les clients (CLI, interface web, application macOS, nœuds iOS/Android,
|
||||
nœuds headless) se connectent via WebSocket et déclarent leur **rôle** + leur **portée**
|
||||
au moment de la poignée de main.
|
||||
Le protocole WS Gateway est le **plan de contrôle unique + transport de nœud** pour
|
||||
OpenClaw. Tous les clients (CLI, interface web, app macOS, nœuds iOS/Android,
|
||||
nœuds sans interface) se connectent via WebSocket et déclarent leur **rôle** + **portée**
|
||||
au moment de la négociation.
|
||||
|
||||
## Transport
|
||||
|
||||
- WebSocket, trames texte avec charges utiles JSON.
|
||||
- La première trame **doit** être une requête `connect`.
|
||||
|
||||
## Poignée de main (`connect`)
|
||||
## Négociation (`connect`)
|
||||
|
||||
Gateway → Client (challenge avant connexion) :
|
||||
Gateway → Client (défi de pré-connexion) :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -96,9 +96,23 @@ Gateway → Client :
|
||||
```
|
||||
|
||||
`server`, `features`, `snapshot` et `policy` sont tous obligatoires d’après le schéma
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` et `canvasHostUrl` sont facultatifs.
|
||||
(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` est facultatif. `auth`
|
||||
rapporte le rôle/les portées négociés lorsqu’ils sont disponibles, et inclut `deviceToken`
|
||||
quand la gateway en émet un.
|
||||
|
||||
Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
|
||||
Lorsqu’aucun jeton d’appareil n’est émis, `hello-ok.auth` peut quand même rapporter les
|
||||
autorisations négociées :
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut aussi :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -110,8 +124,8 @@ Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
|
||||
}
|
||||
```
|
||||
|
||||
Pendant le transfert d’amorçage approuvé, `hello-ok.auth` peut également inclure des
|
||||
entrées de rôle supplémentaires bornées dans `deviceTokens` :
|
||||
Lors du transfert d’amorçage approuvé, `hello-ok.auth` peut aussi inclure des entrées de rôle
|
||||
supplémentaires et bornées dans `deviceTokens` :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -130,13 +144,12 @@ entrées de rôle supplémentaires bornées dans `deviceTokens` :
|
||||
}
|
||||
```
|
||||
|
||||
Pour le flux d’amorçage intégré nœud/opérateur, le jeton de nœud principal reste à
|
||||
`scopes: []` et tout jeton d’opérateur transféré reste borné à la liste d’autorisations
|
||||
Pour le flux d’amorçage intégré nœud/opérateur, le jeton principal du nœud reste
|
||||
`scopes: []` et tout jeton d’opérateur transmis reste borné à la liste d’autorisations
|
||||
de l’opérateur d’amorçage (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Les vérifications de portée d’amorçage
|
||||
restent préfixées par rôle : les entrées opérateur ne satisfont que les requêtes
|
||||
opérateur, et les rôles non opérateur ont toujours besoin de portées sous leur propre
|
||||
préfixe de rôle.
|
||||
`operator.talk.secrets`, `operator.write`). Les vérifications de portée d’amorçage restent
|
||||
préfixées par le rôle : les entrées opérateur ne satisfont que les requêtes opérateur, et
|
||||
les rôles non opérateur ont toujours besoin de portées sous leur propre préfixe de rôle.
|
||||
|
||||
### Exemple de nœud
|
||||
|
||||
@ -173,7 +186,7 @@ préfixe de rôle.
|
||||
}
|
||||
```
|
||||
|
||||
## Format des trames
|
||||
## Encapsulation
|
||||
|
||||
- **Requête** : `{type:"req", id, method, params}`
|
||||
- **Réponse** : `{type:"res", id, ok, payload|error}`
|
||||
@ -185,7 +198,7 @@ Les méthodes avec effets de bord nécessitent des **clés d’idempotence** (vo
|
||||
|
||||
### Rôles
|
||||
|
||||
- `operator` = client du plan de contrôle (CLI/UI/automatisation).
|
||||
- `operator` = client du plan de contrôle (CLI/interface/automatisation).
|
||||
- `node` = hôte de capacités (camera/screen/canvas/system.run).
|
||||
|
||||
### Portées (`operator`)
|
||||
@ -202,317 +215,312 @@ Portées courantes :
|
||||
`talk.config` avec `includeSecrets: true` nécessite `operator.talk.secrets`
|
||||
(ou `operator.admin`).
|
||||
|
||||
Les méthodes RPC Gateway enregistrées par Plugin peuvent demander leur propre portée opérateur, mais
|
||||
les préfixes d’administration réservés du noyau (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
Les méthodes RPC Gateway enregistrées par des plugins peuvent demander leur propre portée opérateur, mais
|
||||
les préfixes d’administration de base réservés (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) se résolvent toujours en `operator.admin`.
|
||||
|
||||
La portée de méthode n’est que le premier filtre. Certaines commandes slash
|
||||
atteintes via `chat.send` appliquent des vérifications plus strictes au niveau de la commande.
|
||||
Par exemple, les écritures persistantes `/config set` et `/config unset` nécessitent `operator.admin`.
|
||||
La portée de méthode n’est que la première barrière. Certaines commandes slash atteintes via
|
||||
`chat.send` appliquent en plus des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes
|
||||
`/config set` et `/config unset` nécessitent `operator.admin`.
|
||||
|
||||
`node.pair.approve` a aussi une vérification de portée supplémentaire au moment de
|
||||
l’approbation, en plus de la portée de méthode de base :
|
||||
`node.pair.approve` a aussi une vérification de portée supplémentaire au moment de l’approbation, en plus de la portée de méthode de base :
|
||||
|
||||
- requêtes sans commande : `operator.pairing`
|
||||
- requêtes avec commandes de nœud non exec : `operator.pairing` + `operator.write`
|
||||
- requêtes avec commandes de nœud autres que d’exécution : `operator.pairing` + `operator.write`
|
||||
- requêtes qui incluent `system.run`, `system.run.prepare` ou `system.which` :
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Caps/commands/permissions (`node`)
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
|
||||
Les nœuds déclarent leurs revendications de capacité au moment de la connexion :
|
||||
Les nœuds déclarent des revendications de capacités au moment de la connexion :
|
||||
|
||||
- `caps` : catégories de capacités de haut niveau.
|
||||
- `commands` : liste d’autorisations de commandes pour `invoke`.
|
||||
- `commands` : liste d’autorisations de commandes pour l’invocation.
|
||||
- `permissions` : bascules granulaires (par ex. `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway traite ces éléments comme des **revendications** et applique côté serveur des
|
||||
listes d’autorisations.
|
||||
La Gateway traite celles-ci comme des **revendications** et applique des listes d’autorisations côté serveur.
|
||||
|
||||
## Présence
|
||||
|
||||
- `system-presence` renvoie des entrées indexées par identité d’appareil.
|
||||
- Les entrées de présence incluent `deviceId`, `roles` et `scopes` afin que les UI puissent afficher une seule ligne par appareil
|
||||
- Les entrées de présence incluent `deviceId`, `roles` et `scopes` pour que les interfaces puissent afficher une seule ligne par appareil
|
||||
même lorsqu’il se connecte à la fois comme **operator** et **node**.
|
||||
|
||||
## Familles courantes de méthodes RPC
|
||||
|
||||
Cette page n’est pas un vidage complet généré, mais la surface WS publique est plus large
|
||||
que les exemples de poignée de main/authentification ci-dessus. Voici les principales familles
|
||||
de méthodes que Gateway expose aujourd’hui.
|
||||
Cette page n’est pas une génération complète, mais la surface WS publique est plus large
|
||||
que les exemples de négociation/authentification ci-dessus. Voici les principales familles de méthodes que la
|
||||
Gateway expose aujourd’hui.
|
||||
|
||||
`hello-ok.features.methods` est une liste de découverte prudente construite à partir de
|
||||
`src/gateway/server-methods-list.ts` ainsi que des exports de méthodes de Plugin/canal chargés.
|
||||
Traitez-la comme une découverte de fonctionnalités, pas comme un vidage généré de chaque helper appelable
|
||||
implémenté dans `src/gateway/server-methods/*.ts`.
|
||||
`hello-ok.features.methods` est une liste de découverte conservatrice construite à partir de
|
||||
`src/gateway/server-methods-list.ts` plus les exportations de méthodes de plugins/canaux chargés.
|
||||
Traitez-la comme une découverte de fonctionnalités, et non comme une génération exhaustive de tous les assistants appelables
|
||||
implémentés dans `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Système et identité
|
||||
|
||||
- `health` renvoie l’instantané de santé Gateway mis en cache ou sondé à nouveau.
|
||||
- `status` renvoie le résumé Gateway de type `/status` ; les champs sensibles ne sont
|
||||
inclus que pour les clients opérateur avec portée admin.
|
||||
- `gateway.identity.get` renvoie l’identité d’appareil Gateway utilisée par les flux de relais et
|
||||
- `health` renvoie l’instantané d’état de santé de la gateway, mis en cache ou sondé récemment.
|
||||
- `status` renvoie le résumé de gateway au format `/status` ; les champs sensibles ne sont
|
||||
inclus que pour les clients opérateur avec portée d’administration.
|
||||
- `gateway.identity.get` renvoie l’identité d’appareil de la gateway utilisée par les flux de relais et
|
||||
d’appairage.
|
||||
- `system-presence` renvoie l’instantané de présence actuel pour les appareils
|
||||
opérateur/nœud connectés.
|
||||
- `system-event` ajoute un événement système et peut mettre à jour/diffuser le
|
||||
contexte de présence.
|
||||
- `last-heartbeat` renvoie le dernier événement Heartbeat persisté.
|
||||
- `set-heartbeats` active ou désactive le traitement des Heartbeat sur Gateway.
|
||||
- `set-heartbeats` active ou désactive le traitement des Heartbeat sur la gateway.
|
||||
|
||||
### Modèles et utilisation
|
||||
|
||||
- `models.list` renvoie le catalogue de modèles autorisés à l’exécution.
|
||||
- `usage.status` renvoie les fenêtres d’utilisation fournisseur/les résumés de quota restant.
|
||||
- `usage.cost` renvoie des résumés agrégés des coûts pour une plage de dates.
|
||||
- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour le
|
||||
workspace actif de l’agent par défaut.
|
||||
- `usage.status` renvoie les fenêtres d’utilisation des fournisseurs/résumés de quota restant.
|
||||
- `usage.cost` renvoie des résumés agrégés de coût d’utilisation pour un intervalle de dates.
|
||||
- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour
|
||||
l’espace de travail actif de l’agent par défaut.
|
||||
- `sessions.usage` renvoie des résumés d’utilisation par session.
|
||||
- `sessions.usage.timeseries` renvoie une série temporelle d’utilisation pour une session.
|
||||
- `sessions.usage.logs` renvoie les entrées de journal d’utilisation pour une session.
|
||||
- `sessions.usage.logs` renvoie les entrées du journal d’utilisation pour une session.
|
||||
|
||||
### Canaux et helpers de connexion
|
||||
### Canaux et assistants de connexion
|
||||
|
||||
- `channels.status` renvoie les résumés d’état des canaux/plugins intégrés + groupés.
|
||||
- `channels.logout` déconnecte un canal/compte spécifique là où le canal
|
||||
prend en charge la déconnexion.
|
||||
- `web.login.start` démarre un flux de connexion QR/web pour le fournisseur de canal web
|
||||
actuel compatible QR.
|
||||
- `web.login.start` démarre un flux de connexion QR/web pour le fournisseur de canal web compatible QR actuellement actif.
|
||||
- `web.login.wait` attend la fin de ce flux de connexion QR/web et démarre le
|
||||
canal en cas de succès.
|
||||
- `push.test` envoie un push APNs de test à un nœud iOS enregistré.
|
||||
- `voicewake.get` renvoie les déclencheurs de mot de réveil stockés.
|
||||
- `voicewake.set` met à jour les déclencheurs de mot de réveil et diffuse la modification.
|
||||
- `push.test` envoie une notification APNs de test à un nœud iOS enregistré.
|
||||
- `voicewake.get` renvoie les déclencheurs de mot d’activation stockés.
|
||||
- `voicewake.set` met à jour les déclencheurs de mot d’activation et diffuse la modification.
|
||||
|
||||
### Messagerie et journaux
|
||||
|
||||
- `send` est la RPC de livraison sortante directe pour les envois ciblés par
|
||||
- `send` est la RPC de distribution sortante directe pour les envois ciblés par
|
||||
canal/compte/fil en dehors du moteur de chat.
|
||||
- `logs.tail` renvoie la fin du journal de fichiers Gateway configuré avec curseur/limite et
|
||||
contrôles de taille maximale en octets.
|
||||
- `logs.tail` renvoie la fin du journal de fichiers configuré de la gateway avec curseur/limite et
|
||||
contrôles du nombre maximal d’octets.
|
||||
|
||||
### Talk et TTS
|
||||
|
||||
- `talk.config` renvoie la charge utile effective de configuration Talk ; `includeSecrets`
|
||||
- `talk.config` renvoie la charge utile de config Talk effective ; `includeSecrets`
|
||||
nécessite `operator.talk.secrets` (ou `operator.admin`).
|
||||
- `talk.mode` définit/diffuse l’état actuel du mode Talk pour les clients
|
||||
WebChat/Control UI.
|
||||
- `talk.speak` synthétise la parole via le fournisseur vocal Talk actif.
|
||||
- `tts.status` renvoie l’état d’activation du TTS, le fournisseur actif, les fournisseurs de secours
|
||||
- `talk.speak` synthétise la parole via le fournisseur de parole Talk actif.
|
||||
- `tts.status` renvoie l’état d’activation de TTS, le fournisseur actif, les fournisseurs de repli
|
||||
et l’état de configuration du fournisseur.
|
||||
- `tts.providers` renvoie l’inventaire visible des fournisseurs TTS.
|
||||
- `tts.enable` et `tts.disable` activent ou désactivent l’état des préférences TTS.
|
||||
- `tts.setProvider` met à jour le fournisseur TTS préféré.
|
||||
- `tts.convert` exécute une conversion texte-parole ponctuelle.
|
||||
|
||||
### Secrets, configuration, mise à jour et assistant
|
||||
### Secrets, config, mise à jour et assistant
|
||||
|
||||
- `secrets.reload` re-résout les SecretRef actifs et ne remplace l’état secret d’exécution
|
||||
qu’en cas de réussite complète.
|
||||
- `secrets.resolve` résout les assignations de secrets ciblées par commande pour un
|
||||
ensemble commande/cible spécifique.
|
||||
- `config.get` renvoie l’instantané et le hash de la configuration actuelle.
|
||||
- `secrets.reload` résout à nouveau les SecretRef actifs et remplace l’état des secrets à l’exécution
|
||||
uniquement en cas de réussite complète.
|
||||
- `secrets.resolve` résout les affectations de secrets ciblées par commande pour un ensemble spécifique
|
||||
de commandes/cibles.
|
||||
- `config.get` renvoie l’instantané de configuration actuel et son hachage.
|
||||
- `config.set` écrit une charge utile de configuration validée.
|
||||
- `config.patch` fusionne une mise à jour partielle de configuration.
|
||||
- `config.apply` valide + remplace la charge utile complète de configuration.
|
||||
- `config.schema` renvoie la charge utile du schéma de configuration en direct utilisée par Control UI et
|
||||
les outils CLI : schéma, `uiHints`, version et métadonnées de génération, y compris
|
||||
les métadonnées de schéma des Plugins + canaux lorsque l’exécution peut les charger. Le schéma
|
||||
les métadonnées de schéma de plugin + canal lorsque l’exécution peut les charger. Le schéma
|
||||
inclut les métadonnées de champ `title` / `description` dérivées des mêmes libellés
|
||||
et textes d’aide utilisés par l’UI, y compris pour les objets imbriqués, caractères génériques,
|
||||
éléments de tableau et branches de composition `anyOf` / `oneOf` / `allOf` lorsque la
|
||||
et textes d’aide utilisés par l’interface, y compris pour les objets imbriqués, les jokers,
|
||||
les éléments de tableau et les branches de composition `anyOf` / `oneOf` / `allOf` lorsque la
|
||||
documentation de champ correspondante existe.
|
||||
- `config.schema.lookup` renvoie une charge utile de consultation limitée à un chemin pour un chemin de configuration :
|
||||
- `config.schema.lookup` renvoie une charge utile de recherche limitée à un chemin pour un chemin de configuration :
|
||||
chemin normalisé, nœud de schéma superficiel, indice correspondant + `hintPath`, et
|
||||
résumés immédiats des enfants pour l’exploration détaillée UI/CLI.
|
||||
- Les nœuds de schéma de consultation conservent la documentation orientée utilisateur et les champs de validation courants :
|
||||
résumés immédiats des enfants pour l’exploration d’interface/CLI.
|
||||
- Les nœuds de schéma de recherche conservent la documentation orientée utilisateur et les champs de validation courants :
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
bornes numériques/chaînes/tableaux/objets, et indicateurs booléens tels que
|
||||
bornes numériques/chaînes/tableaux/objets, et indicateurs booléens comme
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- Les résumés enfants exposent `key`, le `path` normalisé, `type`, `required`,
|
||||
`hasChildren`, ainsi que le `hint` / `hintPath` correspondant.
|
||||
- `update.run` exécute le flux de mise à jour Gateway et ne planifie un redémarrage que
|
||||
si la mise à jour elle-même a réussi.
|
||||
- Les résumés d’enfants exposent `key`, le `path` normalisé, `type`, `required`,
|
||||
`hasChildren`, plus les `hint` / `hintPath` correspondants.
|
||||
- `update.run` exécute le flux de mise à jour de la gateway et planifie un redémarrage uniquement lorsque
|
||||
la mise à jour elle-même a réussi.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` et `wizard.cancel` exposent l’assistant
|
||||
d’onboarding via WS RPC.
|
||||
d’intégration via WS RPC.
|
||||
|
||||
### Familles principales existantes
|
||||
### Familles majeures existantes
|
||||
|
||||
#### Helpers d’agent et de workspace
|
||||
#### Assistants pour agent et espace de travail
|
||||
|
||||
- `agents.list` renvoie les entrées d’agent configurées.
|
||||
- `agents.create`, `agents.update` et `agents.delete` gèrent les enregistrements d’agent et
|
||||
le raccordement du workspace.
|
||||
- `agents.list` renvoie les entrées d’agents configurées.
|
||||
- `agents.create`, `agents.update` et `agents.delete` gèrent les enregistrements d’agents et
|
||||
le câblage de l’espace de travail.
|
||||
- `agents.files.list`, `agents.files.get` et `agents.files.set` gèrent les
|
||||
fichiers de workspace d’amorçage exposés pour un agent.
|
||||
fichiers d’espace de travail d’amorçage exposés pour un agent.
|
||||
- `agent.identity.get` renvoie l’identité effective de l’assistant pour un agent ou
|
||||
une session.
|
||||
- `agent.wait` attend qu’une exécution se termine et renvoie l’instantané terminal lorsqu’il est
|
||||
- `agent.wait` attend la fin d’une exécution et renvoie l’instantané terminal lorsqu’il est
|
||||
disponible.
|
||||
|
||||
#### Contrôle de session
|
||||
|
||||
- `sessions.list` renvoie l’index actuel des sessions.
|
||||
- `sessions.subscribe` et `sessions.unsubscribe` activent ou désactivent les abonnements
|
||||
aux événements de changement de session pour le client WS actuel.
|
||||
- `sessions.subscribe` et `sessions.unsubscribe` activent ou désactivent les abonnements aux événements de changement de session
|
||||
pour le client WS actuel.
|
||||
- `sessions.messages.subscribe` et `sessions.messages.unsubscribe` activent ou désactivent
|
||||
les abonnements aux événements de transcription/message pour une session.
|
||||
- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés de
|
||||
session spécifiques.
|
||||
- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés
|
||||
de session spécifiques.
|
||||
- `sessions.resolve` résout ou canonise une cible de session.
|
||||
- `sessions.create` crée une nouvelle entrée de session.
|
||||
- `sessions.send` envoie un message dans une session existante.
|
||||
- `sessions.steer` est la variante interruption-et-réorientation pour une session active.
|
||||
- `sessions.abort` interrompt le travail actif pour une session.
|
||||
- `sessions.patch` met à jour les métadonnées/remplacements de session.
|
||||
- `sessions.reset`, `sessions.delete` et `sessions.compact` effectuent la maintenance
|
||||
des sessions.
|
||||
- `sessions.patch` met à jour les métadonnées/remplacements de la session.
|
||||
- `sessions.reset`, `sessions.delete` et `sessions.compact` effectuent la
|
||||
maintenance des sessions.
|
||||
- `sessions.get` renvoie la ligne complète de session stockée.
|
||||
- l’exécution de chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
|
||||
- l’exécution du chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
|
||||
`chat.inject`.
|
||||
- `chat.history` est normalisé pour l’affichage pour les clients UI : les balises de directive inline sont
|
||||
- `chat.history` est normalisé pour l’affichage côté clients d’interface : les balises de directive en ligne sont
|
||||
supprimées du texte visible, les charges utiles XML d’appel d’outil en texte brut (y compris
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, et
|
||||
les blocs d’appel d’outil tronqués) ainsi que les jetons de contrôle de modèle ASCII/pleine largeur divulgués
|
||||
sont supprimés, les lignes assistant composées uniquement de jetons silencieux telles que `NO_REPLY` /
|
||||
`no_reply` exacts sont omises, et les lignes surdimensionnées peuvent être remplacées
|
||||
par des espaces réservés.
|
||||
sont supprimés, les lignes d’assistant composées uniquement de jetons silencieux comme `NO_REPLY` /
|
||||
`no_reply` exacts sont omises, et les lignes surdimensionnées peuvent être remplacées par des espaces réservés.
|
||||
|
||||
#### Appairage d’appareils et jetons d’appareil
|
||||
|
||||
- `device.pair.list` renvoie les appareils appairés en attente et approuvés.
|
||||
- `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent
|
||||
les enregistrements d’appairage d’appareil.
|
||||
les enregistrements d’appairage d’appareils.
|
||||
- `device.token.rotate` fait tourner un jeton d’appareil appairé dans les limites approuvées
|
||||
de rôle et de portée.
|
||||
de son rôle et de ses portées.
|
||||
- `device.token.revoke` révoque un jeton d’appareil appairé.
|
||||
|
||||
#### Appairage de nœuds, invocation et travail en attente
|
||||
#### Appairage de nœud, invocation et travail en attente
|
||||
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
|
||||
`node.pair.reject` et `node.pair.verify` couvrent l’appairage des nœuds et la
|
||||
`node.pair.reject` et `node.pair.verify` couvrent l’appairage de nœud et la
|
||||
vérification d’amorçage.
|
||||
- `node.list` et `node.describe` renvoient l’état des nœuds connus/connectés.
|
||||
- `node.rename` met à jour un libellé de nœud appairé.
|
||||
- `node.invoke` transfère une commande à un nœud connecté.
|
||||
- `node.invoke` transmet une commande à un nœud connecté.
|
||||
- `node.invoke.result` renvoie le résultat d’une requête d’invocation.
|
||||
- `node.event` transporte les événements d’origine nœud de retour dans la Gateway.
|
||||
- `node.canvas.capability.refresh` rafraîchit les jetons de capacité canvas bornés par portée.
|
||||
- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente des nœuds connectés.
|
||||
- `node.pending.enqueue` et `node.pending.drain` gèrent le travail en attente durable
|
||||
- `node.event` transporte les événements émis par le nœud vers la gateway.
|
||||
- `node.canvas.capability.refresh` rafraîchit les jetons de capacité canvas à portée limitée.
|
||||
- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente pour nœud connecté.
|
||||
- `node.pending.enqueue` et `node.pending.drain` gèrent le travail durable en attente
|
||||
pour les nœuds hors ligne/déconnectés.
|
||||
|
||||
#### Familles d’approbation
|
||||
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` et
|
||||
`exec.approval.resolve` couvrent les requêtes d’approbation exec ponctuelles ainsi que la
|
||||
`exec.approval.resolve` couvrent les requêtes ponctuelles d’approbation exec ainsi que la
|
||||
recherche/relecture des approbations en attente.
|
||||
- `exec.approval.waitDecision` attend une approbation exec en attente et renvoie
|
||||
la décision finale (ou `null` en cas de délai d’attente).
|
||||
la décision finale (ou `null` en cas de délai dépassé).
|
||||
- `exec.approvals.get` et `exec.approvals.set` gèrent les instantanés de politique
|
||||
d’approbation exec de Gateway.
|
||||
- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale exec
|
||||
d’approbation de nœud via des commandes de relais de nœud.
|
||||
d’approbation exec de la gateway.
|
||||
- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale du nœud pour exec
|
||||
via des commandes relais de nœud.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` et `plugin.approval.resolve` couvrent
|
||||
les flux d’approbation définis par Plugin.
|
||||
les flux d’approbation définis par les plugins.
|
||||
|
||||
#### Autres familles principales
|
||||
#### Autres familles majeures
|
||||
|
||||
- automatisation :
|
||||
- `wake` planifie une injection de texte immédiate ou au prochain Heartbeat
|
||||
- automation :
|
||||
- `wake` planifie une injection de texte de réveil immédiate ou au prochain Heartbeat
|
||||
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
|
||||
`cron.run`, `cron.runs`
|
||||
- skills/outils : `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
|
||||
|
||||
### Familles d’événements courantes
|
||||
|
||||
- `chat` : mises à jour de chat UI telles que `chat.inject` et autres événements
|
||||
de chat limités à la transcription.
|
||||
- `session.message` et `session.tool` : mises à jour du flux de transcription/événements pour une
|
||||
- `chat` : mises à jour du chat de l’interface comme `chat.inject` et autres
|
||||
événements de chat limités à la transcription.
|
||||
- `session.message` et `session.tool` : mises à jour de transcription/flux d’événements pour une
|
||||
session abonnée.
|
||||
- `sessions.changed` : l’index de session ou les métadonnées ont changé.
|
||||
- `sessions.changed` : l’index ou les métadonnées des sessions ont changé.
|
||||
- `presence` : mises à jour de l’instantané de présence système.
|
||||
- `tick` : événement périodique de keepalive / vivacité.
|
||||
- `health` : mise à jour de l’instantané de santé Gateway.
|
||||
- `tick` : événement périodique de maintien en vie / vitalité.
|
||||
- `health` : mise à jour de l’instantané d’état de santé de la gateway.
|
||||
- `heartbeat` : mise à jour du flux d’événements Heartbeat.
|
||||
- `cron` : événement de changement d’exécution/de tâche Cron.
|
||||
- `shutdown` : notification d’arrêt de Gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved` : cycle de vie d’appairage de nœud.
|
||||
- `node.invoke.request` : diffusion d’une requête d’invocation de nœud.
|
||||
- `device.pair.requested` / `device.pair.resolved` : cycle de vie d’appareil appairé.
|
||||
- `voicewake.changed` : la configuration des déclencheurs de mot de réveil a changé.
|
||||
- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie
|
||||
d’approbation exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie
|
||||
d’approbation de Plugin.
|
||||
- `cron` : événement de modification d’exécution/de tâche Cron.
|
||||
- `shutdown` : notification d’arrêt de la gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved` : cycle de vie de l’appairage de nœud.
|
||||
- `node.invoke.request` : diffusion de requête d’invocation de nœud.
|
||||
- `device.pair.requested` / `device.pair.resolved` : cycle de vie d’un appareil appairé.
|
||||
- `voicewake.changed` : la configuration des déclencheurs du mot d’activation a changé.
|
||||
- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie de
|
||||
l’approbation exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie de l’approbation
|
||||
de plugin.
|
||||
|
||||
### Méthodes helper de nœud
|
||||
### Méthodes d’assistance pour nœud
|
||||
|
||||
- Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables de Skills
|
||||
pour les vérifications d’auto-autorisation.
|
||||
|
||||
### Méthodes helper d’opérateur
|
||||
### Méthodes d’assistance pour opérateur
|
||||
|
||||
- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire
|
||||
des commandes d’exécution pour un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire le workspace de l’agent par défaut.
|
||||
- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire des commandes à l’exécution d’un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
|
||||
- `scope` contrôle la surface ciblée par le `name` principal :
|
||||
- `text` renvoie le jeton de commande texte principal sans le `/` initial
|
||||
- `native` et le chemin par défaut `both` renvoient des noms natifs sensibles au fournisseur
|
||||
- `text` renvoie le jeton principal de commande texte sans le `/` initial
|
||||
- `native` et le chemin par défaut `both` renvoient des noms natifs adaptés au fournisseur
|
||||
lorsqu’ils sont disponibles
|
||||
- `textAliases` contient des alias slash exacts tels que `/model` et `/m`.
|
||||
- `nativeName` contient le nom de commande natif sensible au fournisseur lorsqu’il existe.
|
||||
- `provider` est facultatif et n’affecte que le nommage natif ainsi que la disponibilité des
|
||||
commandes Plugin natives.
|
||||
- `textAliases` contient les alias slash exacts comme `/model` et `/m`.
|
||||
- `nativeName` contient le nom de commande natif adapté au fournisseur lorsqu’il existe.
|
||||
- `provider` est facultatif et n’affecte que la dénomination native ainsi que la disponibilité des
|
||||
commandes natives de plugins.
|
||||
- `includeArgs=false` omet les métadonnées d’arguments sérialisées de la réponse.
|
||||
- Les opérateurs peuvent appeler `tools.catalog` (`operator.read`) pour récupérer le catalogue d’outils d’exécution pour un
|
||||
- Les opérateurs peuvent appeler `tools.catalog` (`operator.read`) pour récupérer le catalogue d’outils à l’exécution d’un
|
||||
agent. La réponse inclut des outils groupés et des métadonnées de provenance :
|
||||
- `source` : `core` ou `plugin`
|
||||
- `pluginId` : propriétaire Plugin lorsque `source="plugin"`
|
||||
- `optional` : indique si un outil de Plugin est facultatif
|
||||
- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire effectif
|
||||
des outils d’exécution pour une session.
|
||||
- `pluginId` : propriétaire du plugin lorsque `source="plugin"`
|
||||
- `optional` : si un outil de plugin est facultatif
|
||||
- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire des outils effectifs à l’exécution
|
||||
pour une session.
|
||||
- `sessionKey` est obligatoire.
|
||||
- La Gateway dérive un contexte d’exécution approuvé côté serveur à partir de la session au lieu d’accepter
|
||||
un contexte d’authentification ou de livraison fourni par l’appelant.
|
||||
- La réponse est limitée à la session et reflète ce que la conversation active peut utiliser
|
||||
maintenant, y compris les outils du noyau, de Plugin et de canal.
|
||||
- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire visible
|
||||
de Skills pour un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire le workspace de l’agent par défaut.
|
||||
- La gateway dérive côté serveur le contexte d’exécution approuvé à partir de la session au lieu d’accepter
|
||||
un contexte d’authentification ou de distribution fourni par l’appelant.
|
||||
- La réponse est limitée à la session et reflète ce que la conversation active peut utiliser actuellement,
|
||||
y compris les outils de base, de plugins et de canaux.
|
||||
- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire
|
||||
visible de Skills pour un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
|
||||
- La réponse inclut l’éligibilité, les exigences manquantes, les vérifications de configuration et
|
||||
les options d’installation nettoyées sans exposer les valeurs secrètes brutes.
|
||||
- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour les métadonnées
|
||||
de découverte ClawHub.
|
||||
- Les opérateurs peuvent appeler `skills.install` (`operator.admin`) dans deux modes :
|
||||
- mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
|
||||
dossier de skill dans le répertoire `skills/` du workspace de l’agent par défaut.
|
||||
- mode installateur Gateway : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
exécute une action déclarée `metadata.openclaw.install` sur l’hôte Gateway.
|
||||
- Les opérateurs peuvent appeler `skills.update` (`operator.admin`) dans deux modes :
|
||||
- le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
|
||||
le workspace de l’agent par défaut.
|
||||
- le mode config modifie par patch les valeurs de `skills.entries.<skillKey>` telles que `enabled`,
|
||||
les options d’installation assainies sans exposer de valeurs secrètes brutes.
|
||||
- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour les
|
||||
métadonnées de découverte ClawHub.
|
||||
- Les opérateurs peuvent appeler `skills.install` (`operator.admin`) en deux modes :
|
||||
- Mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
|
||||
dossier de skill dans le répertoire `skills/` de l’espace de travail de l’agent par défaut.
|
||||
- Mode installateur Gateway : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
exécute une action déclarée `metadata.openclaw.install` sur l’hôte gateway.
|
||||
- Les opérateurs peuvent appeler `skills.update` (`operator.admin`) en deux modes :
|
||||
- Le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
|
||||
l’espace de travail de l’agent par défaut.
|
||||
- Le mode config applique des correctifs aux valeurs `skills.entries.<skillKey>` telles que `enabled`,
|
||||
`apiKey` et `env`.
|
||||
|
||||
## Approbations exec
|
||||
|
||||
- Lorsqu’une requête exec a besoin d’une approbation, la Gateway diffuse `exec.approval.requested`.
|
||||
- Les clients opérateur résolvent cela en appelant `exec.approval.resolve` (nécessite la portée `operator.approvals`).
|
||||
- Lorsqu’une requête exec nécessite une approbation, la gateway diffuse `exec.approval.requested`.
|
||||
- Les clients opérateurs résolvent cela en appelant `exec.approval.resolve` (nécessite la portée `operator.approvals`).
|
||||
- Pour `host=node`, `exec.approval.request` doit inclure `systemRunPlan` (`argv`/`cwd`/`rawCommand`/métadonnées de session canoniques). Les requêtes sans `systemRunPlan` sont rejetées.
|
||||
- Après approbation, les appels transférés `node.invoke system.run` réutilisent ce
|
||||
`systemRunPlan` canonique comme contexte faisant autorité pour commande/cwd/session.
|
||||
- Après approbation, les appels transmis `node.invoke system.run` réutilisent ce
|
||||
`systemRunPlan` canonique comme contexte faisant autorité pour la commande/le répertoire de travail/la session.
|
||||
- Si un appelant modifie `command`, `rawCommand`, `cwd`, `agentId` ou
|
||||
`sessionKey` entre `prepare` et le transfert final approuvé de `system.run`, la
|
||||
Gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée.
|
||||
`sessionKey` entre la préparation et la transmission finale approuvée de `system.run`, la
|
||||
gateway rejette l’exécution au lieu de faire confiance à la charge utile modifiée.
|
||||
|
||||
## Repli de livraison d’agent
|
||||
## Repli de distribution d’agent
|
||||
|
||||
- Les requêtes `agent` peuvent inclure `deliver=true` pour demander une livraison sortante.
|
||||
- `bestEffortDeliver=false` conserve un comportement strict : les cibles de livraison non résolues ou internes uniquement renvoient `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` autorise un repli vers une exécution limitée à la session lorsqu’aucune route de livraison externe ne peut être résolue (par exemple sessions internes/webchat ou configurations multicanales ambiguës).
|
||||
- Les requêtes `agent` peuvent inclure `deliver=true` pour demander une distribution sortante.
|
||||
- `bestEffortDeliver=false` conserve le comportement strict : les cibles de distribution non résolues ou internes uniquement renvoient `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` autorise un repli vers une exécution limitée à la session lorsqu’aucune route externe distribuable ne peut être résolue (par exemple sessions internes/webchat ou configurations multicanales ambiguës).
|
||||
|
||||
## Gestion des versions
|
||||
|
||||
@ -525,122 +533,118 @@ implémenté dans `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Constantes client
|
||||
|
||||
Le client de référence dans `src/gateway/client.ts` utilise ces valeurs par défaut. Elles sont
|
||||
stables sur le protocole v3 et constituent la base attendue pour les clients tiers.
|
||||
Le client de référence dans `src/gateway/client.ts` utilise ces valeurs par défaut. Les valeurs sont
|
||||
stables pour le protocole v3 et constituent la base attendue pour les clients tiers.
|
||||
|
||||
| Constante | Par défaut | Source |
|
||||
| Constante | Valeur par défaut | Source |
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Délai d’attente de requête (par RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Délai d’attente préauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (limite `250`–`10_000`) |
|
||||
| Délai d’expiration des requêtes (par RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Délai préauth / défi de connexion | `10_000` ms | `src/gateway/handshake-timeouts.ts` (limite `250`–`10_000`) |
|
||||
| Backoff de reconnexion initial | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Backoff de reconnexion maximal | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Limite de nouvelle tentative rapide après fermeture par jeton d’appareil | `250` ms | `src/gateway/client.ts` |
|
||||
| Délai de grâce avant `terminate()` forcé | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Délai d’attente par défaut de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Intervalle `tick` par défaut (avant `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Fermeture pour expiration du `tick` | code `4000` lorsque le silence dépasse `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 Mo) | `src/gateway/server-constants.ts` |
|
||||
| Grâce d’arrêt forcé avant `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Délai par défaut de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Intervalle tick par défaut (avant `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Fermeture pour dépassement de délai tick | code `4000` quand le silence dépasse `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
|
||||
Le serveur annonce les valeurs effectives `policy.tickIntervalMs`, `policy.maxPayload`
|
||||
et `policy.maxBufferedBytes` dans `hello-ok` ; les clients doivent respecter ces valeurs
|
||||
plutôt que les valeurs par défaut avant la poignée de main.
|
||||
plutôt que les valeurs par défaut d’avant négociation.
|
||||
|
||||
## Authentification
|
||||
|
||||
- L’authentification Gateway par secret partagé utilise `connect.params.auth.token` ou
|
||||
`connect.params.auth.password`, selon le mode d’authentification configuré.
|
||||
- Les modes porteurs d’identité comme Tailscale Serve
|
||||
- Les modes porteurs d’identité tels que Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) ou le mode non-loopback
|
||||
`gateway.auth.mode: "trusted-proxy"` satisfont la vérification d’authentification de connexion à partir
|
||||
des en-têtes de requête plutôt que de `connect.params.auth.*`.
|
||||
- Le mode d’ingress privé `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion
|
||||
par secret partagé ; n’exposez pas ce mode sur un ingress public/non approuvé.
|
||||
- Après l’appairage, la Gateway émet un **jeton d’appareil** borné au rôle + aux portées de la
|
||||
connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
|
||||
`gateway.auth.mode: "trusted-proxy"` satisfont la vérification d’authentification de connexion à partir des
|
||||
en-têtes de requête au lieu de `connect.params.auth.*`.
|
||||
- Le mode d’ingress privé `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une ingress publique/non approuvée.
|
||||
- Après l’appairage, la Gateway émet un **jeton d’appareil** limité au rôle + aux portées
|
||||
de la connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
|
||||
persisté par le client pour les connexions futures.
|
||||
- Les clients doivent persister le `hello-ok.auth.deviceToken` principal après toute
|
||||
connexion réussie.
|
||||
- Une reconnexion avec ce jeton d’appareil **stocké** doit également réutiliser l’ensemble de portées approuvées
|
||||
stocké pour ce jeton. Cela préserve l’accès lecture/sondage/état qui a déjà été accordé
|
||||
et évite de réduire silencieusement les reconnexions à une
|
||||
- Une reconnexion avec ce jeton d’appareil **stocké** doit aussi réutiliser l’ensemble de portées approuvé stocké pour ce jeton. Cela préserve l’accès lecture/sondage/état
|
||||
déjà accordé et évite de réduire silencieusement les reconnexions à une
|
||||
portée implicite plus étroite, limitée à l’administration.
|
||||
- Assemblage côté client de l’authentification de connexion (`selectConnectAuth` dans
|
||||
`src/gateway/client.ts`) :
|
||||
- `auth.password` est orthogonal et est toujours transféré lorsqu’il est défini.
|
||||
- `auth.token` est renseigné par ordre de priorité : d’abord un jeton partagé explicite,
|
||||
puis un `deviceToken` explicite, puis un jeton par appareil stocké (indexé par
|
||||
- `auth.password` est orthogonal et est toujours transmis lorsqu’il est défini.
|
||||
- `auth.token` est renseigné dans l’ordre de priorité suivant : d’abord un jeton partagé explicite,
|
||||
puis un `deviceToken` explicite, puis un jeton stocké par appareil (indexé par
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` n’est envoyé que si aucun des éléments ci-dessus n’a résolu un
|
||||
`auth.token`. Un jeton partagé ou tout jeton d’appareil résolu le supprime.
|
||||
- La promotion automatique d’un jeton d’appareil stocké lors de l’unique
|
||||
nouvelle tentative `AUTH_TOKEN_MISMATCH` est limitée aux **points de terminaison approuvés uniquement** —
|
||||
loopback, ou `wss://` avec `tlsFingerprint` épinglé. Un `wss://` public
|
||||
sans épinglage n’est pas admissible.
|
||||
- `auth.bootstrapToken` n’est envoyé que lorsqu’aucun des éléments ci-dessus n’a résolu
|
||||
un `auth.token`. Un jeton partagé ou tout jeton d’appareil résolu le supprime.
|
||||
- L’auto-promotion d’un jeton d’appareil stocké lors de la nouvelle tentative unique
|
||||
`AUTH_TOKEN_MISMATCH` est réservée **aux points de terminaison approuvés uniquement** —
|
||||
loopback, ou `wss://` avec `tlsFingerprint` épinglé. Le `wss://` public
|
||||
sans épinglage ne remplit pas cette condition.
|
||||
- Les entrées supplémentaires `hello-ok.auth.deviceTokens` sont des jetons de transfert d’amorçage.
|
||||
Ne les persistez que lorsque la connexion a utilisé une authentification d’amorçage sur un transport approuvé
|
||||
Ne les persistez que lorsque la connexion a utilisé une auth d’amorçage sur un transport approuvé
|
||||
tel que `wss://` ou loopback/appairage local.
|
||||
- Si un client fournit un `deviceToken` **explicite** ou des `scopes` explicites, cet
|
||||
ensemble de portées demandé par l’appelant reste faisant autorité ; les portées mises en cache ne sont
|
||||
réutilisées que lorsque le client réutilise le jeton par appareil stocké.
|
||||
ensemble de portées demandé par l’appelant reste autoritaire ; les portées en cache ne sont
|
||||
réutilisées que lorsque le client réutilise le jeton stocké par appareil.
|
||||
- Les jetons d’appareil peuvent être tournés/révoqués via `device.token.rotate` et
|
||||
`device.token.revoke` (nécessite la portée `operator.pairing`).
|
||||
- L’émission/la rotation de jeton reste bornée à l’ensemble de rôles approuvés enregistré dans
|
||||
- L’émission/la rotation des jetons reste limitée à l’ensemble de rôles approuvé enregistré dans
|
||||
l’entrée d’appairage de cet appareil ; la rotation d’un jeton ne peut pas étendre l’appareil à un
|
||||
rôle que l’approbation d’appairage n’a jamais accordé.
|
||||
- Pour les sessions de jeton d’appareil appairé, la gestion des appareils est limitée à soi-même sauf si l’appelant
|
||||
dispose également de `operator.admin` : les appelants non administrateurs ne peuvent supprimer/révoquer/faire tourner
|
||||
que **leur propre** entrée d’appareil.
|
||||
- `device.token.rotate` vérifie également l’ensemble de portées opérateur demandé par rapport aux
|
||||
- Pour les sessions de jeton d’appareil appairé, la gestion des appareils est limitée à soi-même sauf si l’appelant dispose aussi de `operator.admin` : les appelants non administrateurs ne peuvent supprimer/révoquer/faire tourner que **leur propre** entrée d’appareil.
|
||||
- `device.token.rotate` vérifie aussi l’ensemble de portées opérateur demandé par rapport aux
|
||||
portées de session actuelles de l’appelant. Les appelants non administrateurs ne peuvent pas faire tourner un jeton vers
|
||||
un ensemble de portées opérateur plus large que celui qu’ils détiennent déjà.
|
||||
- Les échecs d’authentification incluent `error.details.code` plus des indications de récupération :
|
||||
- Les échecs d’authentification incluent `error.details.code` ainsi que des indications de récupération :
|
||||
- `error.details.canRetryWithDeviceToken` (booléen)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Comportement du client pour `AUTH_TOKEN_MISMATCH` :
|
||||
- Les clients approuvés peuvent tenter une nouvelle tentative bornée avec un jeton par appareil mis en cache.
|
||||
- Comportement client pour `AUTH_TOKEN_MISMATCH` :
|
||||
- Les clients approuvés peuvent tenter une nouvelle tentative bornée avec un jeton stocké par appareil en cache.
|
||||
- Si cette nouvelle tentative échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des indications d’action à l’opérateur.
|
||||
|
||||
## Identité d’appareil + appairage
|
||||
|
||||
- Les nœuds doivent inclure une identité d’appareil stable (`device.id`) dérivée de l’empreinte
|
||||
d’une paire de clés.
|
||||
- Les Gateways émettent des jetons par appareil + rôle.
|
||||
- Les approbations d’appairage sont requises pour les nouveaux ID d’appareil, sauf si l’approbation automatique locale
|
||||
- Les nœuds doivent inclure une identité d’appareil stable (`device.id`) dérivée de l’empreinte d’une
|
||||
paire de clés.
|
||||
- Les gateways émettent des jetons par appareil + rôle.
|
||||
- Les approbations d’appairage sont requises pour les nouveaux IDs d’appareil sauf si l’auto-approbation locale
|
||||
est activée.
|
||||
- L’approbation automatique d’appairage est centrée sur les connexions loopback locales directes.
|
||||
- OpenClaw dispose également d’un chemin étroit d’auto-connexion local backend/conteneur pour
|
||||
les flux helper approuvés à secret partagé.
|
||||
- Les connexions tailnet ou LAN du même hôte sont toujours traitées comme distantes pour l’appairage et
|
||||
- L’auto-approbation d’appairage est centrée sur les connexions directes locales loopback.
|
||||
- OpenClaw dispose aussi d’un chemin étroit d’auto-connexion locale backend/conteneur pour
|
||||
les flux d’assistance approuvés à secret partagé.
|
||||
- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’appairage et
|
||||
nécessitent une approbation.
|
||||
- Tous les clients WS doivent inclure l’identité `device` pendant `connect` (operator + node).
|
||||
Control UI peut l’omettre uniquement dans ces modes :
|
||||
- `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost uniquement.
|
||||
- authentification opérateur Control UI réussie avec `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (solution de dernier recours, forte dégradation de sécurité).
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (bris de glace, dégradation de sécurité sévère).
|
||||
- Toutes les connexions doivent signer le nonce `connect.challenge` fourni par le serveur.
|
||||
|
||||
### Diagnostics de migration d’authentification d’appareil
|
||||
### Diagnostics de migration de l’authentification d’appareil
|
||||
|
||||
Pour les clients hérités qui utilisent encore le comportement de signature antérieur au challenge, `connect` renvoie maintenant
|
||||
Pour les clients hérités qui utilisent encore le comportement de signature d’avant le défi, `connect` renvoie maintenant
|
||||
des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec un `error.details.reason` stable.
|
||||
|
||||
Échecs de migration courants :
|
||||
|
||||
| Message | details.code | details.reason | Signification |
|
||||
| Message | details.code | details.reason | Signification |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Le client a omis `device.nonce` (ou l’a envoyé vide). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Le client a signé avec un nonce périmé/incorrect. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La charge utile de signature ne correspond pas à la charge utile v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est hors de la dérive autorisée. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est hors de l’écart autorisé. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` ne correspond pas à l’empreinte de la clé publique. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Le format/la canonisation de la clé publique a échoué. |
|
||||
|
||||
Cible de migration :
|
||||
|
||||
- Toujours attendre `connect.challenge`.
|
||||
- Signer la charge utile v2 qui inclut le nonce serveur.
|
||||
- Envoyer le même nonce dans `connect.params.device.nonce`.
|
||||
- Attendez toujours `connect.challenge`.
|
||||
- Signez la charge utile v2 qui inclut le nonce du serveur.
|
||||
- Envoyez le même nonce dans `connect.params.device.nonce`.
|
||||
- La charge utile de signature préférée est `v3`, qui lie `platform` et `deviceFamily`
|
||||
en plus des champs appareil/client/rôle/portées/jeton/nonce.
|
||||
- Les signatures héritées `v2` restent acceptées pour compatibilité, mais l’épinglage des métadonnées
|
||||
@ -649,11 +653,11 @@ Cible de migration :
|
||||
## TLS + épinglage
|
||||
|
||||
- TLS est pris en charge pour les connexions WS.
|
||||
- Les clients peuvent facultativement épingler l’empreinte du certificat Gateway (voir la
|
||||
configuration `gateway.tls` ainsi que `gateway.remote.tlsFingerprint` ou la CLI `--tls-fingerprint`).
|
||||
- Les clients peuvent éventuellement épingler l’empreinte du certificat de la gateway (voir la config `gateway.tls`
|
||||
ainsi que `gateway.remote.tlsFingerprint` ou le CLI `--tls-fingerprint`).
|
||||
|
||||
## Portée
|
||||
|
||||
Ce protocole expose l’**API Gateway complète** (état, canaux, modèles, chat,
|
||||
Ce protocole expose **l’API gateway complète** (état, canaux, modèles, chat,
|
||||
agent, sessions, nœuds, approbations, etc.). La surface exacte est définie par les
|
||||
schémas TypeBox dans `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,76 +1,76 @@
|
||||
---
|
||||
read_when:
|
||||
- Implémenter des fonctionnalités de l'application macOS
|
||||
- Modifier le cycle de vie de la gateway ou le pontage de nœud sur macOS
|
||||
summary: Application compagnon OpenClaw pour macOS (barre de menus + courtier gateway)
|
||||
title: Application macOS
|
||||
- Implémentation des fonctionnalités de l’app macOS
|
||||
- Modification du cycle de vie de Gateway ou du pontage des nœuds sur macOS
|
||||
summary: Application compagnon macOS OpenClaw (barre des menus + broker Gateway)
|
||||
title: App macOS
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:49:16Z"
|
||||
generated_at: "2026-04-18T06:43:38Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135
|
||||
source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0
|
||||
source_path: platforms/macos.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Application compagnon OpenClaw pour macOS (barre de menus + courtier gateway)
|
||||
# Companion macOS OpenClaw (barre des menus + broker Gateway)
|
||||
|
||||
L'application macOS est le **compagnon de barre de menus** d'OpenClaw. Elle gère les autorisations,
|
||||
gère/se rattache à la gateway localement (launchd ou manuel), et expose les capacités
|
||||
macOS à l'agent comme un nœud.
|
||||
L’app macOS est le **compagnon de barre des menus** pour OpenClaw. Elle gère les autorisations,
|
||||
gère/se connecte au Gateway localement (launchd ou manuel), et expose les capacités macOS
|
||||
à l’agent en tant que nœud.
|
||||
|
||||
## Ce qu'elle fait
|
||||
## Ce qu’elle fait
|
||||
|
||||
- Affiche des notifications natives et l'état dans la barre de menus.
|
||||
- Gère les invites TCC (Notifications, Accessibilité, Enregistrement d'écran, Microphone,
|
||||
- Affiche des notifications natives et l’état dans la barre des menus.
|
||||
- Gère les invites TCC (Notifications, Accessibilité, Enregistrement de l’écran, Microphone,
|
||||
Reconnaissance vocale, Automation/AppleScript).
|
||||
- Exécute ou connecte la gateway (locale ou distante).
|
||||
- Expose des outils propres à macOS (Canvas, caméra, enregistrement d'écran, `system.run`).
|
||||
- Démarre le service hôte de nœud local en mode **remote** (launchd), et l'arrête en mode **local**.
|
||||
- Peut éventuellement héberger **PeekabooBridge** pour l'automatisation de l'interface.
|
||||
- Installe la CLI globale (`openclaw`) sur demande via npm, pnpm ou bun (l'application préfère npm, puis pnpm, puis bun ; Node reste le runtime recommandé pour la gateway).
|
||||
- Exécute ou se connecte au Gateway (local ou distant).
|
||||
- Expose des outils propres à macOS (Canvas, Caméra, Enregistrement de l’écran, `system.run`).
|
||||
- Démarre le service hôte de nœud local en mode **distant** (launchd), et l’arrête en mode **local**.
|
||||
- Peut héberger **PeekabooBridge** pour l’automatisation de l’interface utilisateur.
|
||||
- Installe la CLI globale (`openclaw`) à la demande via npm, pnpm ou bun (l’app préfère npm, puis pnpm, puis bun ; Node reste l’environnement d’exécution recommandé pour Gateway).
|
||||
|
||||
## Mode local vs distant
|
||||
|
||||
- **Local** (par défaut) : l'application se rattache à une gateway locale déjà en cours d'exécution si elle existe ;
|
||||
- **Local** (par défaut) : l’app se connecte à un Gateway local en cours d’exécution s’il est présent ;
|
||||
sinon elle active le service launchd via `openclaw gateway install`.
|
||||
- **Remote** : l'application se connecte à une gateway via SSH/Tailscale et ne démarre jamais
|
||||
- **Distant** : l’app se connecte à un Gateway via SSH/Tailscale et ne démarre jamais
|
||||
de processus local.
|
||||
L'application démarre le **service hôte de nœud** local afin que la gateway distante puisse atteindre ce Mac.
|
||||
L'application ne lance pas la gateway comme processus enfant.
|
||||
La découverte de la gateway préfère désormais les noms Tailscale MagicDNS aux IP tailnet brutes,
|
||||
de sorte que l'application Mac se rétablit plus fiablement lorsque les IP tailnet changent.
|
||||
L’app démarre le **service hôte de nœud** local afin que le Gateway distant puisse atteindre ce Mac.
|
||||
L’app ne lance pas le Gateway comme processus enfant.
|
||||
La découverte de Gateway privilégie désormais les noms Tailscale MagicDNS plutôt que les IP tailnet brutes,
|
||||
afin que l’app Mac se rétablisse plus fiablement lorsque les IP tailnet changent.
|
||||
|
||||
## Contrôle Launchd
|
||||
|
||||
L'application gère un LaunchAgent par utilisateur étiqueté `ai.openclaw.gateway`
|
||||
(ou `ai.openclaw.<profile>` lors de l'utilisation de `--profile`/`OPENCLAW_PROFILE` ; l'ancien `com.openclaw.*` continue d'être déchargé).
|
||||
L’app gère un LaunchAgent par utilisateur libellé `ai.openclaw.gateway`
|
||||
(ou `ai.openclaw.<profile>` lors de l’utilisation de `--profile`/`OPENCLAW_PROFILE` ; l’ancien `com.openclaw.*` se décharge toujours).
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
|
||||
launchctl bootout gui/$UID/ai.openclaw.gateway
|
||||
```
|
||||
|
||||
Remplacez le label par `ai.openclaw.<profile>` lors de l'exécution d'un profil nommé.
|
||||
Remplacez le libellé par `ai.openclaw.<profile>` lors de l’exécution avec un profil nommé.
|
||||
|
||||
Si le LaunchAgent n'est pas installé, activez-le depuis l'application ou exécutez
|
||||
Si le LaunchAgent n’est pas installé, activez-le depuis l’app ou exécutez
|
||||
`openclaw gateway install`.
|
||||
|
||||
## Capacités du nœud (Mac)
|
||||
## Capacités du nœud (mac)
|
||||
|
||||
L'application macOS se présente comme un nœud. Commandes courantes :
|
||||
L’app macOS se présente comme un nœud. Commandes courantes :
|
||||
|
||||
- Canvas : `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
|
||||
- Caméra : `camera.snap`, `camera.clip`
|
||||
- Écran : `screen.record`
|
||||
- Écran : `screen.snapshot`, `screen.record`
|
||||
- Système : `system.run`, `system.notify`
|
||||
|
||||
Le nœud signale une map `permissions` afin que les agents puissent décider de ce qui est autorisé.
|
||||
Le nœud rapporte une map `permissions` afin que les agents puissent déterminer ce qui est autorisé.
|
||||
|
||||
Service de nœud + IPC d'application :
|
||||
Service de nœud + IPC de l’app :
|
||||
|
||||
- Lorsque le service hôte de nœud headless est en cours d'exécution (mode remote), il se connecte à la gateway WS comme nœud.
|
||||
- `system.run` s'exécute dans l'application macOS (contexte UI/TCC) via un socket Unix local ; les invites et la sortie restent dans l'application.
|
||||
- Lorsque le service hôte de nœud sans interface est en cours d’exécution (mode distant), il se connecte au Gateway WS en tant que nœud.
|
||||
- `system.run` s’exécute dans l’app macOS (contexte UI/TCC) via un socket Unix local ; les invites et la sortie restent dans l’app.
|
||||
|
||||
Schéma (SCI) :
|
||||
|
||||
@ -81,10 +81,10 @@ Gateway -> Node Service (WS)
|
||||
Mac App (UI + TCC + system.run)
|
||||
```
|
||||
|
||||
## Approbations Exec (`system.run`)
|
||||
## Approbations d’exécution (system.run)
|
||||
|
||||
`system.run` est contrôlé par les **approbations Exec** dans l'application macOS (Settings → Exec approvals).
|
||||
La sécurité + la demande + la liste d'autorisation sont stockées localement sur le Mac dans :
|
||||
`system.run` est contrôlé par les **approbations d’exécution** dans l’app macOS (Réglages → Approbations d’exécution).
|
||||
La sécurité + la demande + la liste d’autorisation sont stockées localement sur le Mac dans :
|
||||
|
||||
```
|
||||
~/.openclaw/exec-approvals.json
|
||||
@ -111,20 +111,20 @@ Exemple :
|
||||
|
||||
Remarques :
|
||||
|
||||
- Les entrées `allowlist` sont des motifs glob pour les chemins binaires résolus.
|
||||
- Le texte brut de commande shell contenant une syntaxe de contrôle ou d'expansion shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance dans la liste d'autorisation et nécessite une approbation explicite (ou l'ajout du binaire shell à la liste d'autorisation).
|
||||
- Choisir « Always Allow » dans l'invite ajoute cette commande à la liste d'autorisation.
|
||||
- Les remplacements d'environnement de `system.run` sont filtrés (supprime `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) puis fusionnés avec l'environnement de l'application.
|
||||
- Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les remplacements d'environnement limités à la requête sont réduits à une petite liste d'autorisation explicite (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- Pour les décisions d'autorisation permanente en mode allowlist, les wrappers de répartition connus (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistent les chemins exécutables internes plutôt que les chemins des wrappers. Si le déballage n'est pas sûr, aucune entrée de liste d'autorisation n'est persistée automatiquement.
|
||||
- Les entrées `allowlist` sont des motifs glob pour les chemins de binaires résolus.
|
||||
- Le texte brut d’une commande shell qui contient une syntaxe de contrôle ou d’expansion shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance de liste d’autorisation et nécessite une approbation explicite (ou l’ajout du binaire shell à la liste d’autorisation).
|
||||
- Choisir « Toujours autoriser » dans l’invite ajoute cette commande à la liste d’autorisation.
|
||||
- Les remplacements d’environnement de `system.run` sont filtrés (supprime `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) puis fusionnés avec l’environnement de l’app.
|
||||
- Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les remplacements d’environnement propres à la requête sont réduits à une petite liste d’autorisation explicite (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- Pour les décisions toujours autoriser en mode liste d’autorisation, les wrappers de distribution connus (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) conservent les chemins des exécutables internes au lieu des chemins des wrappers. Si le déballage n’est pas sûr, aucune entrée de liste d’autorisation n’est automatiquement conservée.
|
||||
|
||||
## Liens profonds
|
||||
|
||||
L'application enregistre le schéma d'URL `openclaw://` pour les actions locales.
|
||||
L’app enregistre le schéma d’URL `openclaw://` pour les actions locales.
|
||||
|
||||
### `openclaw://agent`
|
||||
|
||||
Déclenche une requête `agent` vers la gateway.
|
||||
Déclenche une requête Gateway `agent`.
|
||||
__OC_I18N_900004__
|
||||
Paramètres de requête :
|
||||
|
||||
@ -133,28 +133,28 @@ Paramètres de requête :
|
||||
- `thinking` (facultatif)
|
||||
- `deliver` / `to` / `channel` (facultatif)
|
||||
- `timeoutSeconds` (facultatif)
|
||||
- `key` (facultatif, clé de mode sans supervision)
|
||||
- `key` (facultatif, clé pour le mode sans surveillance)
|
||||
|
||||
Sécurité :
|
||||
|
||||
- Sans `key`, l'application demande une confirmation.
|
||||
- Sans `key`, l'application impose une limite courte de longueur de message pour l'invite de confirmation et ignore `deliver` / `to` / `channel`.
|
||||
- Avec une `key` valide, l'exécution est sans supervision (prévue pour des automatisations personnelles).
|
||||
- Sans `key`, l’app demande une confirmation.
|
||||
- Sans `key`, l’app applique une limite courte de message pour l’invite de confirmation et ignore `deliver` / `to` / `channel`.
|
||||
- Avec une `key` valide, l’exécution se fait sans surveillance (prévu pour des automatisations personnelles).
|
||||
|
||||
## Flux d'onboarding (typique)
|
||||
## Flux d’intégration (typique)
|
||||
|
||||
1. Installez et lancez **OpenClaw.app**.
|
||||
2. Complétez la liste de vérification des autorisations (invites TCC).
|
||||
3. Assurez-vous que le mode **Local** est actif et que la gateway est en cours d'exécution.
|
||||
4. Installez la CLI si vous souhaitez un accès terminal.
|
||||
3. Assurez-vous que le mode **Local** est actif et que le Gateway est en cours d’exécution.
|
||||
4. Installez la CLI si vous souhaitez un accès au terminal.
|
||||
|
||||
## Emplacement du répertoire d'état (macOS)
|
||||
## Emplacement du répertoire d’état (macOS)
|
||||
|
||||
Évitez de placer votre répertoire d'état OpenClaw dans iCloud ou dans d'autres dossiers synchronisés dans le cloud.
|
||||
Les chemins adossés à une synchronisation peuvent ajouter de la latence et provoquer occasionnellement des courses de verrouillage/synchronisation de fichiers pour
|
||||
Évitez de placer votre répertoire d’état OpenClaw dans iCloud ou dans d’autres dossiers synchronisés dans le cloud.
|
||||
Les chemins pris en charge par la synchronisation peuvent ajouter de la latence et provoquer occasionnellement des courses de verrouillage/synchronisation de fichiers pour
|
||||
les sessions et les identifiants.
|
||||
|
||||
Préférez un chemin d'état local non synchronisé tel que :
|
||||
Préférez un chemin d’état local non synchronisé tel que :
|
||||
__OC_I18N_900005__
|
||||
Si `openclaw doctor` détecte un état sous :
|
||||
|
||||
@ -167,56 +167,56 @@ il affichera un avertissement et recommandera de revenir à un chemin local.
|
||||
|
||||
- `cd apps/macos && swift build`
|
||||
- `swift run OpenClaw` (ou Xcode)
|
||||
- Packager l'application : `scripts/package-mac-app.sh`
|
||||
- Packager l’app : `scripts/package-mac-app.sh`
|
||||
|
||||
## Déboguer la connectivité gateway (CLI macOS)
|
||||
## Déboguer la connectivité Gateway (CLI macOS)
|
||||
|
||||
Utilisez la CLI de débogage pour exercer la même poignée de main WebSocket gateway et la même logique de découverte
|
||||
que l'application macOS, sans lancer l'application.
|
||||
Utilisez la CLI de débogage pour exercer la même poignée de main WebSocket Gateway et la même logique de découverte
|
||||
que l’app macOS, sans lancer l’app.
|
||||
__OC_I18N_900006__
|
||||
Options de connexion :
|
||||
|
||||
- `--url <ws://host:port>` : remplace la configuration
|
||||
- `--mode <local|remote>` : résout à partir de la configuration (par défaut : config ou local)
|
||||
- `--probe` : force une nouvelle sonde d'état
|
||||
- `--timeout <ms>` : délai de requête (par défaut : `15000`)
|
||||
- `--json` : sortie structurée pour comparaison
|
||||
- `--url <ws://host:port>` : remplace la config
|
||||
- `--mode <local|remote>` : résout à partir de la config (par défaut : config ou local)
|
||||
- `--probe` : force une nouvelle sonde d’état
|
||||
- `--timeout <ms>` : délai d’expiration de la requête (par défaut : `15000`)
|
||||
- `--json` : sortie structurée pour les comparaisons
|
||||
|
||||
Options de découverte :
|
||||
|
||||
- `--include-local` : inclure les gateways qui seraient filtrées comme « local »
|
||||
- `--include-local` : inclut les gateways qui seraient filtrés comme « locaux »
|
||||
- `--timeout <ms>` : fenêtre globale de découverte (par défaut : `2000`)
|
||||
- `--json` : sortie structurée pour comparaison
|
||||
- `--json` : sortie structurée pour les comparaisons
|
||||
|
||||
Astuce : comparez avec `openclaw gateway discover --json` pour voir si le
|
||||
pipeline de découverte de l'application macOS (`local.` plus le domaine wide-area configuré, avec
|
||||
des replis wide-area et Tailscale Serve) diffère de
|
||||
Astuce : comparez avec `openclaw gateway discover --json` pour voir si le pipeline de découverte
|
||||
de l’app macOS (`local.` plus le domaine étendu configuré, avec
|
||||
des solutions de repli wide-area et Tailscale Serve) diffère de
|
||||
la découverte basée sur `dns-sd` de la CLI Node.
|
||||
|
||||
## Plomberie de connexion distante (tunnels SSH)
|
||||
## Plomberie des connexions distantes (tunnels SSH)
|
||||
|
||||
Lorsque l'application macOS fonctionne en mode **Remote**, elle ouvre un tunnel SSH afin que les composants UI locaux
|
||||
puissent communiquer avec une gateway distante comme si elle était sur localhost.
|
||||
Lorsque l’app macOS s’exécute en mode **distant**, elle ouvre un tunnel SSH afin que les composants de l’interface locale
|
||||
puissent communiquer avec un Gateway distant comme s’il était sur localhost.
|
||||
|
||||
### Tunnel de contrôle (port WebSocket gateway)
|
||||
### Tunnel de contrôle (port WebSocket Gateway)
|
||||
|
||||
- **Objectif :** vérifications d'état, status, Web Chat, configuration et autres appels du plan de contrôle.
|
||||
- **Port local :** le port gateway (par défaut `18789`), toujours stable.
|
||||
- **Port distant :** le même port gateway sur l'hôte distant.
|
||||
- **Comportement :** pas de port local aléatoire ; l'application réutilise un tunnel sain existant
|
||||
- **But :** contrôles d’état, statut, Chat Web, config et autres appels du plan de contrôle.
|
||||
- **Port local :** le port Gateway (par défaut `18789`), toujours stable.
|
||||
- **Port distant :** le même port Gateway sur l’hôte distant.
|
||||
- **Comportement :** pas de port local aléatoire ; l’app réutilise un tunnel sain existant
|
||||
ou le redémarre si nécessaire.
|
||||
- **Forme SSH :** `ssh -N -L <local>:127.0.0.1:<remote>` avec BatchMode +
|
||||
ExitOnForwardFailure + options de keepalive.
|
||||
- **Remontée d'IP :** le tunnel SSH utilise loopback, donc la gateway verra l'IP du nœud
|
||||
comme `127.0.0.1`. Utilisez le transport **Direct (ws/wss)** si vous souhaitez que la véritable
|
||||
IP cliente apparaisse (voir [accès distant macOS](/platforms/mac/remote)).
|
||||
- **Forme SSH :** `ssh -N -L <local>:127.0.0.1:<remote>` avec les options BatchMode +
|
||||
ExitOnForwardFailure + keepalive.
|
||||
- **Rapport d’IP :** le tunnel SSH utilise le loopback, donc le gateway verra l’IP du nœud
|
||||
comme `127.0.0.1`. Utilisez le transport **Direct (ws/wss)** si vous souhaitez que la véritable IP
|
||||
cliente apparaisse (voir [accès distant macOS](/fr/platforms/mac/remote)).
|
||||
|
||||
Pour les étapes de configuration, voir [accès distant macOS](/platforms/mac/remote). Pour les détails
|
||||
du protocole, voir [Protocole de la gateway](/gateway/protocol).
|
||||
Pour les étapes de configuration, voir [accès distant macOS](/fr/platforms/mac/remote). Pour les détails
|
||||
du protocole, voir [protocole Gateway](/fr/gateway/protocol).
|
||||
|
||||
## Documentation associée
|
||||
|
||||
- [Runbook gateway](/gateway)
|
||||
- [Gateway (macOS)](/platforms/mac/bundled-gateway)
|
||||
- [Autorisations macOS](/platforms/mac/permissions)
|
||||
- [Canvas](/platforms/mac/canvas)
|
||||
- [Runbook Gateway](/fr/gateway)
|
||||
- [Gateway (macOS)](/fr/platforms/mac/bundled-gateway)
|
||||
- [Autorisations macOS](/fr/platforms/mac/permissions)
|
||||
- [Canvas](/fr/platforms/mac/canvas)
|
||||
|
||||
@ -5,119 +5,110 @@ read_when:
|
||||
- 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
|
||||
title: Création de Plugins de canal
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:43Z"
|
||||
generated_at: "2026-04-18T06:44:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Créer des Plugins de canal
|
||||
# Création de 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 messages privés, l’appairage, le fil de réponse et la
|
||||
messagerie sortante.
|
||||
plateforme de messagerie. À la fin, vous disposerez d’un canal fonctionnel avec sécurité des DM,
|
||||
pairing, threading des réponses et messagerie sortante.
|
||||
|
||||
<Info>
|
||||
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.
|
||||
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.
|
||||
</Info>
|
||||
|
||||
## Fonctionnement des Plugins de canal
|
||||
|
||||
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 :
|
||||
Les Plugins de canal n’ont pas besoin de leurs propres outils d’envoi/édition/réaction. OpenClaw conserve un
|
||||
outil `message` partagé dans le cœur. Votre Plugin prend en charge :
|
||||
|
||||
- **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
|
||||
- **Configuration** — résolution de compte et assistant de configuration
|
||||
- **Sécurité** — politique DM et listes d’autorisation
|
||||
- **Pairing** — flux d’approbation DM
|
||||
- **Grammaire de session** — comment les identifiants de conversation spécifiques au provider se mappent aux chats de base, aux identifiants de thread et aux solutions de repli parent
|
||||
- **Sortant** — envoi de texte, de médias et de sondages vers la plateforme
|
||||
- **Fil de discussion** — comment les réponses sont organisées en fil
|
||||
- **Threading** — comment les réponses sont threadées
|
||||
|
||||
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.
|
||||
Le cœur prend en charge l’outil de message partagé, le câblage du prompt, la forme externe de la clé de session,
|
||||
la tenue générique des registres `:thread:` et la répartition.
|
||||
|
||||
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 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 les paramètres
|
||||
spécifiques au provider comme avatar, pièce jointe ou 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 toujours pour les paramètres
|
||||
qui sont volontairement partagés par chaque action exposée.
|
||||
|
||||
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.
|
||||
Si votre plateforme stocke une portée supplémentaire dans les identifiants de conversation, gardez cette logique d’analyse
|
||||
dans le Plugin avec `messaging.resolveSessionConversation(...)`. C’est le hook canonique
|
||||
pour mapper `rawId` vers l’identifiant de conversation de base, l’identifiant de thread optionnel,
|
||||
`baseConversationId` explicite et tout `parentConversationCandidates`.
|
||||
Lorsque vous renvoyez `parentConversationCandidates`, conservez-les ordonnés
|
||||
du parent le plus étroit au parent le plus large / à la conversation de base.
|
||||
|
||||
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.
|
||||
Les Plugins intégrés qui ont besoin de la même logique d’analyse avant
|
||||
le démarrage du registre de canal peuvent aussi exposer un fichier `session-key-api.ts`
|
||||
de niveau supérieur avec une exportation correspondante
|
||||
`resolveSessionConversation(...)`. 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 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.
|
||||
`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 en plus de l’identifiant générique/brut. Si les deux hooks existent, le cœur utilise
|
||||
d’abord `resolveSessionConversation(...).parentConversationCandidates` et ne
|
||||
revient à `resolveParentConversationCandidates(...)` que si le hook canonique
|
||||
les omet.
|
||||
|
||||
## Approbations et capacités des canaux
|
||||
## Approbations et capacités de canal
|
||||
|
||||
La plupart des Plugins de canal n’ont pas besoin de code spécifique aux
|
||||
approbations.
|
||||
La plupart des Plugins de canal n’ont pas besoin de code spécifique aux approbations.
|
||||
|
||||
- Le cœur 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 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 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.
|
||||
- Le cœur prend en charge `/approve` dans le même chat, les charges utiles de bouton d’approbation partagées et la livraison générique de secours.
|
||||
- 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 faits de livraison/native/render/auth des approbations dans `approvalCapability`.
|
||||
- `plugin.auth` est réservé à login/logout ; le cœur ne lit plus les hooks d’authentification d’approbation à partir de cet objet.
|
||||
- `approvalCapability.authorizeActorAction` et `approvalCapability.getActionAvailabilityState` constituent la surface canonique pour l’authentification d’approbation.
|
||||
- Utilisez `approvalCapability.getActionAvailabilityState` pour la disponibilité de l’authentification d’approbation dans le même chat.
|
||||
- Si votre canal expose des approbations exec natives, utilisez `approvalCapability.getExecInitiatingSurfaceState` pour l’état de la surface d’initiation / du client natif lorsqu’il diffère de l’authentification d’approbation dans le même chat. Le cœur utilise ce hook spécifique à exec pour distinguer `enabled` de `disabled`, décider si le canal initiateur prend en charge les approbations exec natives et inclure le canal dans les indications de secours pour client natif. `createApproverRestrictedNativeApprovalCapability(...)` remplit cela 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 prompts locaux d’approbation en double ou envoyer des indicateurs de saisie avant la livraison.
|
||||
- Utilisez `approvalCapability.delivery` uniquement pour le routage d’approbation natif ou la suppression des solutions de secours.
|
||||
- Utilisez `approvalCapability.nativeRuntime` pour les faits d’approbation native détenus par le canal. Gardez-le lazy sur les points d’entrée chauds du canal avec `createLazyChannelApprovalNativeRuntimeAdapter(...)`, qui peut importer votre module runtime à la demande tout en permettant au cœur d’assembler le cycle de vie des approbations.
|
||||
- Utilisez `approvalCapability.render` uniquement lorsqu’un canal a réellement besoin de charges utiles d’approbation personnalisées au lieu du moteur de rendu partagé.
|
||||
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse 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
|
||||
- Utilisez `approvalCapability.describeExecApprovalSetup` lorsque le canal veut que la réponse du chemin désactivé explique les paramètres de configuration exacts nécessaires pour activer les approbations exec natives. Le hook reçoit `{ channel, channelLabel, accountId }` ; les canaux à compte nommé doivent générer des chemins à portée de compte comme `channels.<channel>.accounts.<id>.execApprovals.*` au lieu des valeurs par défaut de niveau supérieur.
|
||||
- Si un canal peut déduire des identités DM stables de type propriétaire à partir de la configuration existante, utilisez `createResolvedApproverActionAuthAdapter` depuis `openclaw/plugin-sdk/approval-runtime` pour restreindre `/approve` dans le même chat sans ajouter de logique spécifique aux approbations dans le cœur.
|
||||
- Si un canal a besoin d’une livraison d’approbation native, gardez le code du canal focalisé sur la normalisation des cibles ainsi que sur les faits de transport / présentation. Utilisez `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` et `createApproverRestrictedNativeApprovalCapability` depuis `openclaw/plugin-sdk/approval-runtime`. Placez les faits spécifiques au canal derrière `approvalCapability.nativeRuntime`, idéalement via `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, afin que le cœur puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage vers un autre emplacement. `nativeRuntime` est découpé en quelques surfaces plus petites :
|
||||
- `availability` — si le compte est configuré et si une requête doit être traitée
|
||||
- `presentation` — mapper le view model d’approbation partagé vers des charges utiles natives pending/resolved/expired ou des actions finales
|
||||
- `transport` — préparer les cibles puis envoyer / mettre à jour / supprimer les messages d’approbation natifs
|
||||
- `interactions` — hooks facultatifs bind/unbind/clear-action pour les boutons ou réactions natifs
|
||||
- `observe` — hooks facultatifs de diagnostic de livraison
|
||||
- Si le canal a besoin d’objets 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.
|
||||
- Si le canal a besoin d’objets détenus par le runtime comme un client, un token, une application Bolt ou un récepteur Webhook, enregistrez-les via `openclaw/plugin-sdk/channel-runtime-context`. Le registre générique de contexte runtime permet au cœur d’amorcer des gestionnaires pilotés par capacités à partir de l’état de démarrage du canal sans ajouter de glue d’encapsulation spécifique aux approbations.
|
||||
- N’utilisez `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` au niveau inférieur que lorsque la surface pilotée par capacités n’est pas encore assez expressive.
|
||||
- Les canaux d’approbation native doivent faire transiter à la fois `accountId` et `approvalKind` par ces helpers. `accountId` maintient la portée correcte de la politique d’approbation multi-compte pour le bon compte bot, et `approvalKind` conserve le comportement d’approbation exec vs Plugin disponible pour le canal sans branches codées en dur dans le cœur.
|
||||
- Le cœur prend désormais aussi en charge les avis de reroutage des approbations. Les Plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation a été envoyée en DM / vers un autre canal » depuis `createChannelNativeApprovalRuntime` ; exposez plutôt un routage précis de l’origine + des DM d’approbateur via les helpers partagés de capacité d’approbation et laissez le cœur agréger les livraisons réelles avant de publier un avis dans le chat initiateur.
|
||||
- Préservez le type d’identifiant d’approbation livré de bout en bout. Les clients natifs ne doivent pas
|
||||
deviner ou réécrire le routage d’approbation exec vs Plugin à partir de l’état local du canal.
|
||||
- Des types d’approbation différents peuvent volontairement exposer des surfaces natives différentes.
|
||||
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.
|
||||
- Slack conserve le routage d’approbation native disponible à la fois pour les identifiants exec et Plugin.
|
||||
- Matrix conserve le même routage DM/canal natif et la même UX par réaction pour les approbations exec
|
||||
et Plugin, tout en laissant l’authentification varier selon le type d’approbation.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le générateur de capacités et exposer `approvalCapability` sur le Plugin.
|
||||
|
||||
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 :
|
||||
Pour les points d’entrée chauds du canal, préférez les sous-chemins runtime plus étroits lorsque vous n’avez besoin
|
||||
que d’une partie de cette famille :
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -134,91 +125,98 @@ De même, préférez `openclaw/plugin-sdk/setup-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 englobante plus large.
|
||||
`openclaw/plugin-sdk/reply-chunking` lorsque vous n’avez pas besoin de la surface
|
||||
globale plus large.
|
||||
|
||||
Pour la configuration en particulier :
|
||||
Pour la configuration plus précisément :
|
||||
|
||||
- `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 :
|
||||
- `openclaw/plugin-sdk/setup-runtime` couvre les helpers de configuration sûrs pour le runtime :
|
||||
adaptateurs de patch de configuration sûrs à l’importation (`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 surface étroite d’adaptateur sensible à l’environnement
|
||||
pour `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` couvre les constructeurs de configuration
|
||||
à 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 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.
|
||||
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 du runtime, déclarez-les dans le
|
||||
manifeste du Plugin avec `channelEnvVars`. Conservez `envVars` du runtime du canal ou des constantes locales
|
||||
uniquement pour le texte orienté opérateur.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` et
|
||||
`splitSetupEntries`
|
||||
|
||||
- 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(...)`
|
||||
- utilisez la surface plus large `openclaw/plugin-sdk/setup` uniquement lorsque vous avez également besoin des
|
||||
helpers partagés plus lourds de configuration/configuration comme
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Si votre canal veut seulement annoncer « installez d’abord ce Plugin » dans les
|
||||
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.
|
||||
surfaces de configuration, préférez `createOptionalChannelSetupSurface(...)`. L’adaptateur/l’assistant
|
||||
généré échoue en mode fermé sur les écritures de configuration et la finalisation, et réutilise
|
||||
le même message d’installation requise pour la validation, la finalisation et le texte
|
||||
de lien vers la documentation.
|
||||
|
||||
Pour les autres chemins critiques du canal, préférez les helpers étroits aux
|
||||
Pour les autres chemins chauds 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-helpers` pour la configuration multi-compte et
|
||||
la solution de repli du compte par défaut
|
||||
la solution de repli vers le compte par défaut
|
||||
- `openclaw/plugin-sdk/inbound-envelope` et
|
||||
`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/inbound-reply-dispatch` pour le câblage des routes/enveloppes entrantes et
|
||||
record-and-dispatch
|
||||
- `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é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
|
||||
`openclaw/plugin-sdk/outbound-runtime` pour le chargement des médias ainsi que les délégués
|
||||
d’identité/envoi sortants
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` pour le cycle de vie des liaisons de thread
|
||||
et l’enregistrement des adaptateurs
|
||||
- `openclaw/plugin-sdk/agent-media-payload` uniquement lorsqu’une disposition de champ héritée
|
||||
agent/media 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 commande
|
||||
stable en solution de repli
|
||||
|
||||
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.
|
||||
Les canaux uniquement d’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 de créer leur propre cycle de vie d’approbation.
|
||||
|
||||
## Politique des mentions entrantes
|
||||
## Politique de mention entrante
|
||||
|
||||
Conservez la gestion des mentions entrantes répartie en deux couches :
|
||||
Conservez la gestion des mentions entrantes divisée en deux couches :
|
||||
|
||||
- collecte de preuves gérée par le Plugin
|
||||
- collecte de preuves détenue par le Plugin
|
||||
- évaluation de politique partagée
|
||||
|
||||
Utilisez `openclaw/plugin-sdk/channel-inbound` pour la couche partagée.
|
||||
Utilisez `openclaw/plugin-sdk/channel-mention-gating` pour les décisions de politique de mention.
|
||||
Utilisez `openclaw/plugin-sdk/channel-inbound` uniquement lorsque vous avez besoin de la surface
|
||||
plus large de helpers entrants.
|
||||
|
||||
Bon cas d’usage pour la logique locale au Plugin :
|
||||
Bon choix pour la logique locale au Plugin :
|
||||
|
||||
- détection de réponse au bot
|
||||
- détection de citation du bot
|
||||
- vérifications de participation au fil
|
||||
- exclusions de messages de service ou système
|
||||
- caches natifs à la plateforme nécessaires pour prouver la participation du bot
|
||||
- vérifications de participation au thread
|
||||
- exclusions de messages de service/système
|
||||
- caches natifs de plateforme nécessaires pour prouver la participation du bot
|
||||
|
||||
Bon cas d’usage pour le helper partagé :
|
||||
Bon choix pour le helper partagé :
|
||||
|
||||
- `requireMention`
|
||||
- résultat de mention explicite
|
||||
- liste d’autorisation de mention implicite
|
||||
- contournement de commande
|
||||
- contournement des commandes
|
||||
- décision finale d’ignorer
|
||||
|
||||
Flux recommandé :
|
||||
|
||||
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.
|
||||
2. Passez ces faits à `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Utilisez `decision.effectiveWasMentioned`, `decision.shouldBypassMention` et `decision.shouldSkip` dans votre garde entrante.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -257,8 +255,8 @@ const decision = resolveInboundMentionDecision({
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour
|
||||
les Plugins de canal intégrés qui dépendent déjà de l’injection d’exécution :
|
||||
`api.runtime.channel.mentions` expose les mêmes helpers de mention partagés pour les
|
||||
Plugins de canal intégrés qui dépendent déjà de l’injection runtime :
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -266,20 +264,23 @@ les Plugins de canal intégrés qui dépendent déjà de l’injection d’exéc
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Les anciens helpers `resolveMentionGating*` restent dans
|
||||
`openclaw/plugin-sdk/channel-inbound` uniquement comme exports de compatibilité.
|
||||
Le nouveau code doit utiliser
|
||||
`resolveInboundMentionDecision({ facts, policy })`.
|
||||
Si vous n’avez besoin que de `implicitMentionKindWhen` et
|
||||
`resolveInboundMentionDecision`, importez-les depuis
|
||||
`openclaw/plugin-sdk/channel-mention-gating` afin d’éviter de charger des helpers runtime
|
||||
entrants sans rapport.
|
||||
|
||||
## Procédure pas à pas
|
||||
Les anciens helpers `resolveMentionGating*` restent disponibles sur
|
||||
`openclaw/plugin-sdk/channel-inbound` uniquement comme exportations de compatibilité. Le nouveau code
|
||||
doit utiliser `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## Procédure détaillée
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Package et manifeste">
|
||||
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) :
|
||||
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 de package,
|
||||
consultez [Setup and Config](/fr/plugins/sdk-setup#openclaw-channel) :
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -328,10 +329,9 @@ Le nouveau code doit utiliser
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Créer l’objet Plugin de canal">
|
||||
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.
|
||||
<Step title="Construire l’objet Plugin de canal">
|
||||
L’interface `ChannelPlugin` comporte 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` :
|
||||
|
||||
@ -427,24 +427,23 @@ Le nouveau code doit utiliser
|
||||
```
|
||||
|
||||
<Accordion title="Ce que createChatChannelPlugin fait pour vous">
|
||||
Au lieu d’implémenter manuellement des interfaces d’adaptateur de bas
|
||||
niveau, vous fournissez des options déclaratives et le constructeur les
|
||||
compose :
|
||||
Au lieu d’implémenter manuellement des interfaces d’adaptation de bas niveau, vous passez
|
||||
des options déclaratives et le constructeur les compose :
|
||||
|
||||
| Option | Ce qu’elle connecte |
|
||||
| Option | Ce qui est câblé |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
| `security.dm` | Résolveur de sécurité DM à portée limitée à partir des champs de configuration |
|
||||
| `pairing.text` | Flux de pairing DM 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 transmettre des objets d’adaptateur bruts au lieu des
|
||||
options déclaratives si vous avez besoin d’un contrôle total.
|
||||
Vous pouvez également passer des objets d’adaptateur bruts au lieu des options déclaratives
|
||||
si vous avez besoin d’un contrôle total.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Connecter le point d’entrée">
|
||||
<Step title="Câbler le point d’entrée">
|
||||
Créez `index.ts` :
|
||||
|
||||
```typescript index.ts
|
||||
@ -480,24 +479,21 @@ Le nouveau code doit utiliser
|
||||
});
|
||||
```
|
||||
|
||||
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.
|
||||
Placez les descripteurs CLI détenus par le canal dans `registerCliMetadata(...)` afin qu’OpenClaw
|
||||
puisse les afficher dans l’aide racine sans activer le runtime complet du canal,
|
||||
tandis que les chargements complets normaux récupèrent toujours les mêmes descripteurs pour le véritable enregistrement
|
||||
des commandes. Réservez `registerFull(...)` aux tâches limitées au runtime.
|
||||
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 cette séparation des modes
|
||||
d’enregistrement. Consultez
|
||||
[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>
|
||||
|
||||
<Step title="Ajouter une entrée de configuration">
|
||||
<Step title="Ajouter un point d’entrée de configuration">
|
||||
Créez `setup-entry.ts` pour un chargement léger pendant l’onboarding :
|
||||
|
||||
```typescript setup-entry.ts
|
||||
@ -507,24 +503,21 @@ Le nouveau code doit utiliser
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
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.
|
||||
OpenClaw charge ceci au lieu du point d’entrée complet lorsque le canal est désactivé
|
||||
ou non configuré. Cela évite de charger du code runtime lourd pendant les flux de configuration.
|
||||
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.
|
||||
Les canaux d’espace de travail intégrés qui répartissent les exportations sûres pour la configuration dans des modules
|
||||
compagnons peuvent utiliser `defineBundledChannelSetupEntry(...)` depuis
|
||||
`openclaw/plugin-sdk/channel-entry-contract` lorsqu’ils ont également besoin d’un
|
||||
setter runtime 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
|
||||
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 :
|
||||
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 répartit via le gestionnaire entrant de votre canal :
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
@ -548,10 +541,9 @@ Le nouveau code doit utiliser
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
La gestion des messages entrants est spécifique au canal. Chaque Plugin de canal possède
|
||||
son propre pipeline entrant. Regardez les Plugins de canal intégrés
|
||||
(par exemple le package Plugin Microsoft Teams ou Google Chat) pour voir de vrais modèles.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -564,8 +556,8 @@ Le nouveau code doit utiliser
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { acmeChatPlugin } from "./channel.js";
|
||||
|
||||
describe("plugin acme-chat", () => {
|
||||
it("résout le compte à partir de la configuration", () => {
|
||||
describe("acme-chat plugin", () => {
|
||||
it("resolves account from config", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
|
||||
@ -575,7 +567,7 @@ Le nouveau code doit utiliser
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("inspecte le compte sans matérialiser les secrets", () => {
|
||||
it("inspects account without materializing secrets", () => {
|
||||
const cfg = {
|
||||
channels: { "acme-chat": { token: "test-token" } },
|
||||
} as any;
|
||||
@ -584,7 +576,7 @@ Le nouveau code doit utiliser
|
||||
expect(result.tokenStatus).toBe("available");
|
||||
});
|
||||
|
||||
it("signale une configuration manquante", () => {
|
||||
it("reports missing config", () => {
|
||||
const cfg = { channels: {} } as any;
|
||||
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
|
||||
expect(result.configured).toBe(false);
|
||||
@ -609,19 +601,19 @@ Le nouveau code doit utiliser
|
||||
├── openclaw.plugin.json # Manifeste avec schéma de configuration
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Exports publics (facultatif)
|
||||
├── runtime-api.ts # Exports d’exécution internes (facultatif)
|
||||
├── api.ts # Exportations publiques (facultatif)
|
||||
├── runtime-api.ts # Exportations runtime internes (facultatif)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin via createChatChannelPlugin
|
||||
├── channel.test.ts # Tests
|
||||
├── client.ts # Client API de la plateforme
|
||||
└── runtime.ts # Stockage d’exécution (si nécessaire)
|
||||
└── runtime.ts # Store runtime (si nécessaire)
|
||||
```
|
||||
|
||||
## Sujets avancés
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Options de fil de discussion" icon="git-branch" href="/fr/plugins/sdk-entrypoints#registration-mode">
|
||||
<Card title="Options de threading" 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">
|
||||
@ -630,22 +622,21 @@ Le nouveau code doit utiliser
|
||||
<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édias, sous-agent via api.runtime
|
||||
<Card title="Helpers runtime" icon="settings" href="/fr/plugins/sdk-runtime">
|
||||
TTS, STT, média, sous-agent via api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
Certaines surfaces 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
|
||||
|
||||
- [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
|
||||
- [Provider Plugins](/fr/plugins/sdk-provider-plugins) — si votre Plugin fournit également des modèles
|
||||
- [SDK Overview](/fr/plugins/sdk-overview) — référence complète des importations par sous-chemin
|
||||
- [SDK Testing](/fr/plugins/sdk-testing) — utilitaires de test et tests de contrat
|
||||
- [Plugin Manifest](/fr/plugins/manifest) — schéma complet du manifeste
|
||||
|
||||
@ -1,367 +1,379 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous devez savoir depuis quel sous-chemin du SDK importer
|
||||
- Vous voulez une référence pour toutes les méthodes d’enregistrement sur `OpenClawPluginApi`
|
||||
- Vous recherchez une exportation SDK spécifique
|
||||
- Vous voulez une référence pour toutes les méthodes d’enregistrement sur OpenClawPluginApi
|
||||
- Vous recherchez une exportation spécifique du SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Map d’importation, référence de l’API d’enregistrement et architecture du SDK
|
||||
title: Vue d’ensemble du SDK Plugin
|
||||
summary: Map d’import, référence de l’API d’enregistrement et architecture du SDK
|
||||
title: Aperçu du SDK Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T06:57:33Z"
|
||||
generated_at: "2026-04-18T06:44:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
|
||||
source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Vue d’ensemble du SDK Plugin
|
||||
# Aperçu du SDK Plugin
|
||||
|
||||
Le SDK Plugin est le contrat typé entre les plugins et le cœur. Cette page est la
|
||||
référence pour **quoi importer** et **ce que vous pouvez enregistrer**.
|
||||
|
||||
<Tip>
|
||||
**Vous cherchez un guide pratique ?**
|
||||
- Premier plugin ? Commencez par [Premiers pas](/fr/plugins/building-plugins)
|
||||
- Plugin de canal ? Voir [Plugins de canal](/fr/plugins/sdk-channel-plugins)
|
||||
- Plugin de fournisseur ? Voir [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins)
|
||||
**Vous cherchez un guide pratique ?**
|
||||
- Premier plugin ? Commencez par [Prise en main](/fr/plugins/building-plugins)
|
||||
- Plugin de canal ? Voir [Plugins de canal](/fr/plugins/sdk-channel-plugins)
|
||||
- Plugin de fournisseur ? Voir [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## Convention d’importation
|
||||
## Convention d’import
|
||||
|
||||
Importez toujours depuis un sous-chemin spécifique :
|
||||
Importez toujours depuis un sous-chemin spécifique :
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Chaque sous-chemin est un module petit et autonome. Cela permet de garder un
|
||||
démarrage rapide et d’éviter les problèmes de dépendances circulaires. Pour les
|
||||
helpers d’entrée/de build spécifiques aux canaux, préférez
|
||||
`openclaw/plugin-sdk/channel-core` ; gardez `openclaw/plugin-sdk/core` pour
|
||||
la surface parapluie plus large et les helpers partagés tels que
|
||||
Chaque sous-chemin est un petit module autonome. Cela permet de garder un
|
||||
démarrage rapide et d’éviter les problèmes de dépendances circulaires. Pour les helpers
|
||||
d’entrée/de construction spécifiques aux canaux, privilégiez `openclaw/plugin-sdk/channel-core` ; réservez `openclaw/plugin-sdk/core` à
|
||||
la surface ombrelle plus large et aux helpers partagés comme
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
N’ajoutez pas et ne dépendez pas de surfaces de commodité nommées d’après des fournisseurs comme
|
||||
N’ajoutez pas et ne dépendez pas de points d’entrée de commodité nommés d’après des fournisseurs tels que
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de
|
||||
surfaces helper associées à une marque de canal. Les plugins intégrés doivent
|
||||
composer des sous-chemins SDK génériques dans leurs propres barrels `api.ts` ou `runtime-api.ts`, et le cœur
|
||||
points d’entrée helpers marqués canal. Les plugins intégrés doivent composer des
|
||||
sous-chemins génériques du SDK dans leurs propres barrels `api.ts` ou `runtime-api.ts`, et le cœur
|
||||
doit soit utiliser ces barrels locaux au plugin, soit ajouter un contrat SDK
|
||||
générique étroit lorsque le besoin est réellement transversal aux canaux.
|
||||
|
||||
La map d’exportation générée contient encore un petit ensemble de surfaces helper
|
||||
pour les plugins intégrés, comme `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
La map d’export générée contient encore un petit ensemble de points d’entrée helpers de plugins intégrés
|
||||
tels que `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` et `plugin-sdk/matrix*`. Ces
|
||||
sous-chemins n’existent que pour la maintenance et la compatibilité des plugins intégrés ;
|
||||
ils sont volontairement omis du tableau courant ci-dessous et ne constituent pas
|
||||
le chemin d’importation recommandé pour les nouveaux plugins tiers.
|
||||
sous-chemins existent uniquement pour la maintenance et la compatibilité des plugins intégrés ; ils sont
|
||||
volontairement omis du tableau courant ci-dessous et ne constituent pas le
|
||||
chemin d’import recommandé pour les nouveaux plugins tiers.
|
||||
|
||||
## Référence des sous-chemins
|
||||
|
||||
Les sous-chemins les plus couramment utilisés, regroupés par usage. La liste
|
||||
complète générée de plus de 200 sous-chemins se trouve dans
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
Les sous-chemins les plus couramment utilisés, regroupés par usage. La liste complète générée de
|
||||
plus de 200 sous-chemins se trouve dans `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Les sous-chemins helper réservés aux plugins intégrés figurent toujours dans cette
|
||||
liste générée. Traitez-les comme des surfaces de détail d’implémentation/de compatibilité, sauf si une page de documentation
|
||||
en promeut explicitement une comme publique.
|
||||
Les sous-chemins helpers réservés aux plugins intégrés figurent toujours dans cette liste générée.
|
||||
Traitez-les comme des surfaces de détail d’implémentation/de compatibilité, sauf si une page de documentation
|
||||
en promeut explicitement un comme public.
|
||||
|
||||
### Entrée de plugin
|
||||
|
||||
| Sous-chemin | Exportations clés |
|
||||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sous-chemins de canal">
|
||||
| Sous-chemin | Exportations clés |
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Exportation du schéma Zod racine `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ainsi que `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/config-schema` | Export Zod du schéma racine `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Helpers partagés d’assistant de configuration, invites d’allowlist, constructeurs d’état de configuration |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Helpers de config/mécanisme de contrôle d’action multi-compte, helpers de repli pour compte par défaut |
|
||||
| `plugin-sdk/account-core` | Helpers de configuration multi-comptes/gate d’action, helpers de repli de compte par défaut |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalisation d’identifiant de compte |
|
||||
| `plugin-sdk/account-resolution` | Helpers de recherche de compte + repli par défaut |
|
||||
| `plugin-sdk/account-helpers` | Helpers étroits de liste de comptes/action sur compte |
|
||||
| `plugin-sdk/account-resolution` | Recherche de compte + helpers de repli par défaut |
|
||||
| `plugin-sdk/account-helpers` | Helpers ciblés de liste de comptes/action de compte |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Types de schéma de config de canal |
|
||||
| `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation de commandes personnalisées Telegram avec repli sur contrat intégré |
|
||||
| `plugin-sdk/channel-config-schema` | Types de schéma de configuration de canal |
|
||||
| `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation des commandes personnalisées Telegram avec repli de contrat intégré |
|
||||
| `plugin-sdk/command-gating` | Helpers ciblés de gate d’autorisation de commande |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helpers partagés de route entrante + construction d’enveloppe |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d’enregistrement et de répartition entrante |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helpers partagés d’enregistrement entrant et de distribution |
|
||||
| `plugin-sdk/messaging-targets` | Helpers d’analyse/de correspondance de cibles |
|
||||
| `plugin-sdk/outbound-media` | Helpers partagés de chargement de médias sortants |
|
||||
| `plugin-sdk/outbound-runtime` | Helpers de délégation d’envoi/d’identité sortante |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d’adaptateur pour liaisons de fils |
|
||||
| `plugin-sdk/agent-media-payload` | Constructeur historique de charge utile média d’agent |
|
||||
| `plugin-sdk/conversation-runtime` | Helpers de liaison conversation/fil, appairage et liaison configurée |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de config d’exécution |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpers de résolution de politique de groupe à l’exécution |
|
||||
| `plugin-sdk/channel-status` | Helpers partagés d’instantané/résumé de statut de canal |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitives étroites de schéma de config de canal |
|
||||
| `plugin-sdk/channel-config-writes` | Helpers d’autorisation d’écriture de config de canal |
|
||||
| `plugin-sdk/channel-plugin-common` | Exportations de prélude partagées pour plugin de canal |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helpers de lecture/modification de config d’allowlist |
|
||||
| `plugin-sdk/poll-runtime` | Helpers ciblés de normalisation de sondage |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie et d’adaptateur des liaisons de thread |
|
||||
| `plugin-sdk/agent-media-payload` | Constructeur hérité de payload média d’agent |
|
||||
| `plugin-sdk/conversation-runtime` | Helpers de liaison de conversation/thread, d’appairage et de liaison configurée |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de configuration d’exécution |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpers d’exécution de résolution de politique de groupe |
|
||||
| `plugin-sdk/channel-status` | Helpers partagés d’instantané/résumé d’état de canal |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitives ciblées de schéma de configuration de canal |
|
||||
| `plugin-sdk/channel-config-writes` | Helpers d’autorisation d’écriture de configuration de canal |
|
||||
| `plugin-sdk/channel-plugin-common` | Exports de prélude partagés de plugin de canal |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helpers de lecture/édition de configuration d’allowlist |
|
||||
| `plugin-sdk/group-access` | Helpers partagés de décision d’accès de groupe |
|
||||
| `plugin-sdk/direct-dm` | Helpers partagés d’authentification/de garde pour messages directs |
|
||||
| `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de charge utile de réponse interactive |
|
||||
| `plugin-sdk/channel-inbound` | Helpers d’anti-rebond entrant, de correspondance de mention, de politique de mention et d’enveloppe |
|
||||
| `plugin-sdk/direct-dm` | Helpers partagés d’authentification/garde de message direct |
|
||||
| `plugin-sdk/interactive-runtime` | Helpers de normalisation/réduction de payload de réponse interactive |
|
||||
| `plugin-sdk/channel-inbound` | Barrel de compatibilité pour le debounce entrant, la correspondance de mention, les helpers de politique de mention et les helpers d’enveloppe |
|
||||
| `plugin-sdk/channel-mention-gating` | Helpers ciblés de politique de mention sans la surface d’exécution entrante plus large |
|
||||
| `plugin-sdk/channel-location` | Helpers de contexte et de formatage d’emplacement de canal |
|
||||
| `plugin-sdk/channel-logging` | Helpers de journalisation de canal pour les rejets entrants et les échecs de saisie/d’accusé de réception |
|
||||
| `plugin-sdk/channel-send-result` | Types de résultat de réponse |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Helpers d’analyse/de correspondance de cibles |
|
||||
| `plugin-sdk/channel-contract` | Types de contrat de canal |
|
||||
| `plugin-sdk/channel-feedback` | Câblage de feedback/réaction |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers étroits de contrat de secret comme `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, ainsi que les types de cible de secret |
|
||||
| `plugin-sdk/channel-feedback` | Câblage des retours/réactions |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers ciblés de contrat de secret comme `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, et types de cible de secret |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins de fournisseur">
|
||||
| Sous-chemin | Exportations clés |
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Helpers de configuration organisés pour fournisseurs locaux/autohébergés |
|
||||
| `plugin-sdk/provider-setup` | Helpers de configuration sélectionnés pour les fournisseurs locaux/autohébergés |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur autohébergé compatible OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpers d’exécution de résolution de clé API pour plugins de fournisseur |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpers d’intégration/écriture de profil de clé API comme `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes de watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpers d’exécution de résolution de clé API pour les plugins de fournisseur |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpers d’intégration/écriture de profil de clé API tels que `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Constructeur standard de résultat d’authentification OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helpers partagés de connexion interactive pour plugins de fournisseur |
|
||||
| `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d’environnement d’authentification de fournisseur |
|
||||
| `plugin-sdk/provider-auth-login` | Helpers partagés de connexion interactive pour les plugins de fournisseur |
|
||||
| `plugin-sdk/provider-env-vars` | Helpers de recherche de variables d’environnement d’authentification fournisseur |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de relecture, helpers de point de terminaison de fournisseur, et helpers de normalisation d’identifiant de modèle tels que `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de rejeu, helpers de point de terminaison fournisseur et helpers de normalisation d’identifiant de modèle comme `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Helpers génériques de capacité HTTP/point de terminaison de fournisseur |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Helpers étroits de contrat de config/sélection web-fetch comme `enablePluginInConfig` et `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-http` | Helpers génériques de capacité HTTP/point de terminaison fournisseur |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Helpers ciblés de contrat de configuration/sélection web-fetch comme `enablePluginInConfig` et `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpers d’enregistrement/cache de fournisseur web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Helpers étroits de config/identifiants web-search pour les fournisseurs qui n’ont pas besoin du câblage d’activation du plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Helpers étroits de contrat de config/identifiants web-search comme `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et les setters/getters d’identifiants à portée limitée |
|
||||
| `plugin-sdk/provider-web-search` | Helpers d’exécution/cache/enregistrement de fournisseur web-search |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Helpers ciblés de configuration/d’identifiants web-search pour les fournisseurs qui n’ont pas besoin de câblage d’activation de plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Helpers ciblés de contrat de configuration/d’identifiants web-search comme `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d’identifiants à portée limitée |
|
||||
| `plugin-sdk/provider-web-search` | Helpers d’enregistrement/cache/exécution de fournisseur web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI comme `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` et similaires |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types de wrapper de flux, et helpers partagés de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Helpers de correctif de config d’intégration |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types de wrappers de flux, et helpers partagés de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Helpers de correctif de configuration d’intégration |
|
||||
| `plugin-sdk/global-singleton` | Helpers de singleton/map/cache locaux au processus |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins d’authentification et de sécurité">
|
||||
| Sous-chemin | Exportations clés |
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registre de commandes, helpers d’autorisation d’expéditeur |
|
||||
| `plugin-sdk/command-status` | Constructeurs de messages de commande/d’aide tels que `buildCommandsMessagePaginated` et `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpers de résolution d’approbateur et d’authentification d’action dans la même discussion |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation d’exécution native |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/livraison d’approbation |
|
||||
| `plugin-sdk/command-status` | Constructeurs de messages de commande/d’aide comme `buildCommandsMessagePaginated` et `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpers de résolution d’approbateur et d’authentification d’action dans le même chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation exec natifs |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/de livraison d’approbation |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Helper partagé de résolution de Gateway d’approbation |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal critiques |
|
||||
| `plugin-sdk/approval-handler-runtime` | Helpers plus larges du runtime de gestionnaire d’approbation ; préférez les surfaces adaptateur/Gateway plus étroites lorsqu’elles suffisent |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpers natifs de cible d’approbation + liaison de compte |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpers de charge utile de réponse d’approbation exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Helpers natifs d’authentification de commande + helpers natifs de cible de session |
|
||||
| `plugin-sdk/command-detection` | Helpers partagés de détection de commande |
|
||||
| `plugin-sdk/command-surface` | Helpers de normalisation de corps de commande et de surface de commande |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation natif pour points d’entrée de canal à chaud |
|
||||
| `plugin-sdk/approval-handler-runtime` | Helpers d’exécution plus larges de gestionnaire d’approbation ; privilégiez les points d’entrée plus étroits adapter/gateway lorsqu’ils suffisent |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation native + de liaison de compte |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpers de payload de réponse d’approbation exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Authentification de commande native + helpers natifs de cible de session |
|
||||
| `plugin-sdk/command-detection` | Helpers partagés de détection de commandes |
|
||||
| `plugin-sdk/command-surface` | Helpers de normalisation du corps de commande et de surface de commande |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers étroits de collecte de contrat de secret pour les surfaces de secret de canal/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Helpers étroits `coerceSecretRef` et de typage SecretRef pour l’analyse de contrat de secret/config |
|
||||
| `plugin-sdk/security-runtime` | Helpers partagés de confiance, contrôle DM, contenu externe et collecte de secrets |
|
||||
| `plugin-sdk/ssrf-policy` | Helpers de politique SSRF d’allowlist d’hôtes et de réseau privé |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpers de répartiteur épinglé, fetch protégé par SSRF et politique SSRF |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers ciblés de collecte de contrat de secret pour surfaces de secrets de canal/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Helpers ciblés `coerceSecretRef` et de typage SecretRef pour l’analyse des contrats de secret/de la configuration |
|
||||
| `plugin-sdk/security-runtime` | Helpers partagés de confiance, gate DM, contenu externe et collecte de secrets |
|
||||
| `plugin-sdk/ssrf-policy` | Helpers de politique SSRF de liste d’autorisation d’hôtes et de réseau privé |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Helpers ciblés de dispatcher épinglé sans la large surface d’exécution infra |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpers de dispatcher épinglé, fetch protégé contre SSRF et politique SSRF |
|
||||
| `plugin-sdk/secret-input` | Helpers d’analyse d’entrée de secret |
|
||||
| `plugin-sdk/webhook-ingress` | Helpers de requête/cible Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpers de taille du corps de requête/délai d’attente |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpers de taille de corps de requête/délai d’expiration |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins de runtime et de stockage">
|
||||
| Sous-chemin | Exportations clés |
|
||||
<Accordion title="Sous-chemins d’exécution et de stockage">
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Helpers larges de runtime/journalisation/sauvegarde/installation de plugin |
|
||||
| `plugin-sdk/runtime-env` | Helpers étroits d’environnement de runtime, logger, délai d’attente, retry et backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche du contexte d’exécution de canal |
|
||||
| `plugin-sdk/runtime` | Helpers larges d’exécution/journalisation/sauvegarde/installation de plugin |
|
||||
| `plugin-sdk/runtime-env` | Helpers ciblés d’environnement d’exécution, logger, délai d’expiration, nouvelle tentative et backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche de contexte d’exécution de canal |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Helpers partagés de commande/hook/http/interaction de plugin |
|
||||
| `plugin-sdk/hook-runtime` | Helpers partagés de pipeline de Webhook/hook interne |
|
||||
| `plugin-sdk/lazy-runtime` | Helpers d’importation/de liaison de runtime paresseux tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/lazy-runtime` | Helpers d’import/liaison d’exécution paresseuse comme `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helpers d’exécution de processus |
|
||||
| `plugin-sdk/cli-runtime` | Helpers de formatage, d’attente et de version pour CLI |
|
||||
| `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de correctif de statut de canal |
|
||||
| `plugin-sdk/config-runtime` | Helpers de chargement/écriture de config |
|
||||
| `plugin-sdk/telegram-command-config` | Normalisation du nom/de la description de commande Telegram et vérifications de doublon/conflit, même lorsque la surface de contrat Telegram intégrée n’est pas disponible |
|
||||
| `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers d’authentification/profil, helpers natifs de routage/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Helpers partagés du runtime entrant/de réponse, segmentation, répartition, Heartbeat, planificateur de réponse |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helpers étroits de répartition/finalisation de réponse |
|
||||
| `plugin-sdk/reply-history` | Helpers partagés d’historique de réponse sur fenêtre courte tels que `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/cli-runtime` | Helpers de formatage, d’attente et de version pour la CLI |
|
||||
| `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de correctif d’état de canal |
|
||||
| `plugin-sdk/config-runtime` | Helpers de chargement/écriture de configuration |
|
||||
| `plugin-sdk/telegram-command-config` | Normalisation des noms/descriptions de commandes Telegram et vérifications des doublons/conflits, même lorsque la surface de contrat Telegram intégrée n’est pas disponible |
|
||||
| `plugin-sdk/text-autolink-runtime` | Détection d’autolien de référence de fichier sans le large barrel `text-runtime` |
|
||||
| `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers d’authentification/de profil, helpers de routage/d’exécution natifs |
|
||||
| `plugin-sdk/reply-runtime` | Helpers partagés d’exécution entrante/de réponse, découpage en blocs, distribution, Heartbeat, planificateur de réponse |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helpers ciblés de distribution/finalisation de réponse |
|
||||
| `plugin-sdk/reply-history` | Helpers partagés d’historique de réponse sur courte fenêtre comme `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Helpers étroits de segmentation de texte/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de chemin du magasin de session + date de mise à jour |
|
||||
| `plugin-sdk/state-paths` | Helpers de chemin de répertoire pour état/OAuth |
|
||||
| `plugin-sdk/routing` | Helpers de routage/clé de session/liaison de compte tels que `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helpers partagés de résumé de statut de canal/compte, valeurs par défaut de l’état d’exécution et helpers de métadonnées de problème |
|
||||
| `plugin-sdk/reply-chunking` | Helpers ciblés de découpage de texte/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de chemin de stockage de session + `updated-at` |
|
||||
| `plugin-sdk/state-paths` | Helpers de chemins de répertoire State/OAuth |
|
||||
| `plugin-sdk/routing` | Helpers de route/clé de session/liaison de compte comme `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helpers partagés de résumé d’état de canal/compte, valeurs par défaut d’état d’exécution et helpers de métadonnées de problème |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helpers partagés de résolution de cible |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de slug/chaîne |
|
||||
| `plugin-sdk/request-url` | Extraire des URL de chaîne à partir d’entrées de type fetch/request |
|
||||
| `plugin-sdk/request-url` | Extrait des URL chaîne depuis des entrées de type fetch/request |
|
||||
| `plugin-sdk/run-command` | Exécuteur de commande temporisé avec résultats stdout/stderr normalisés |
|
||||
| `plugin-sdk/param-readers` | Lecteurs courants de paramètres d’outil/CLI |
|
||||
| `plugin-sdk/tool-payload` | Extraire des charges utiles normalisées à partir d’objets résultat d’outil |
|
||||
| `plugin-sdk/tool-send` | Extraire les champs de cible d’envoi canoniques à partir des arguments d’outil |
|
||||
| `plugin-sdk/param-readers` | Lecteurs de paramètres communs d’outil/CLI |
|
||||
| `plugin-sdk/tool-payload` | Extrait des payloads normalisés depuis des objets de résultat d’outil |
|
||||
| `plugin-sdk/tool-send` | Extrait les champs de cible d’envoi canoniques depuis les arguments d’outil |
|
||||
| `plugin-sdk/temp-path` | Helpers partagés de chemin de téléchargement temporaire |
|
||||
| `plugin-sdk/logging-core` | Helpers de logger de sous-système et de masquage |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helpers de mode de tableau Markdown |
|
||||
| `plugin-sdk/json-store` | Petits helpers de lecture/écriture d’état JSON |
|
||||
| `plugin-sdk/file-lock` | Helpers de verrouillage de fichier réentrant |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication sauvegardé sur disque |
|
||||
| `plugin-sdk/acp-runtime` | Helpers ACP de runtime/session et de répartition de réponse |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitives étroites de schéma de config du runtime d’agent |
|
||||
| `plugin-sdk/boolean-param` | Lecteur souple de paramètre booléen |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpers de résolution de correspondance de nom dangereux |
|
||||
| `plugin-sdk/device-bootstrap` | Helpers d’initialisation d’appareil et de jeton d’appairage |
|
||||
| `plugin-sdk/extension-shared` | Primitives helper partagées pour canal passif, statut et proxy ambiant |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpers de réponse de fournisseur/commande `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helpers de liste de commandes Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helpers natifs de registre/construction/sérialisation de commande |
|
||||
| `plugin-sdk/agent-harness` | Surface expérimentale de plugin approuvé pour des harnais d’agent bas niveau : types de harnais, helpers de pilotage/abandon d’exécution active, helpers de pont d’outil OpenClaw et utilitaires de résultat de tentative |
|
||||
| `plugin-sdk/file-lock` | Helpers de verrouillage de fichier réentrants |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication adossé au disque |
|
||||
| `plugin-sdk/acp-runtime` | Helpers ACP d’exécution/session et de distribution de réponse |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Résolution en lecture seule des liaisons ACP sans imports de démarrage du cycle de vie |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitives ciblées de schéma de configuration d’exécution d’agent |
|
||||
| `plugin-sdk/boolean-param` | Lecteur permissif de paramètre booléen |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpers de résolution de correspondance de noms dangereux |
|
||||
| `plugin-sdk/device-bootstrap` | Helpers de bootstrap d’appareil et de jeton d’appairage |
|
||||
| `plugin-sdk/extension-shared` | Primitives helpers partagées de canal passif, statut et proxy ambiant |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpers de réponse de commande `/models`/fournisseur |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helpers de listage des commandes Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helpers natifs de registre/construction/sérialisation de commandes |
|
||||
| `plugin-sdk/agent-harness` | Surface expérimentale de plugin de confiance pour harnais d’agent de bas niveau : types de harnais, helpers de pilotage/abandon d’exécution active, helpers de pont d’outil OpenClaw et utilitaires de résultat de tentative |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Helpers de détection de point de terminaison Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | Helpers d’événement système/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Petits helpers de cache borné |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helpers de drapeau et d’événement de diagnostic |
|
||||
| `plugin-sdk/error-runtime` | Helpers de graphe d’erreur, formatage, classification d’erreur partagée, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Helpers de fetch enveloppé, proxy et recherche épinglée |
|
||||
| `plugin-sdk/error-runtime` | Graphe d’erreurs, formatage, helpers partagés de classification d’erreurs, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Helpers de fetch encapsulé, proxy et recherche épinglée |
|
||||
| `plugin-sdk/runtime-fetch` | Fetch d’exécution sensible au dispatcher sans imports proxy/fetch protégé |
|
||||
| `plugin-sdk/response-limit-runtime` | Lecteur borné de corps de réponse sans la large surface d’exécution média |
|
||||
| `plugin-sdk/session-binding-runtime` | État de liaison de conversation actuelle sans routage de liaison configurée ni magasins d’appairage |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de lecture du magasin de session sans imports larges d’écriture/de maintenance de configuration |
|
||||
| `plugin-sdk/context-visibility-runtime` | Résolution de visibilité du contexte et filtrage de contexte supplémentaire sans imports larges de configuration/sécurité |
|
||||
| `plugin-sdk/string-coerce-runtime` | Helpers ciblés de coercition et de normalisation de record/chaîne primitive sans imports Markdown/journalisation |
|
||||
| `plugin-sdk/host-runtime` | Helpers de normalisation de nom d’hôte et d’hôte SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helpers de config de retry et d’exécuteur de retry |
|
||||
| `plugin-sdk/retry-runtime` | Helpers de configuration de nouvelle tentative et d’exécuteur de nouvelle tentative |
|
||||
| `plugin-sdk/agent-runtime` | Helpers de répertoire/identité/espace de travail d’agent |
|
||||
| `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire basée sur la config |
|
||||
| `plugin-sdk/directory-runtime` | Requête/déduplication de répertoire adossée à la configuration |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins de capacité et de test">
|
||||
| Sous-chemin | Exportations clés |
|
||||
<Accordion title="Sous-chemins de capacités et de test">
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias ainsi que constructeurs de charge utile média |
|
||||
| `plugin-sdk/media-generation-runtime` | Helpers partagés de basculement en cas d’échec pour la génération de médias, sélection de candidats et messagerie de modèle manquant |
|
||||
| `plugin-sdk/media-understanding` | Types de fournisseur de compréhension des médias ainsi qu’exportations helper orientées fournisseur pour image/audio |
|
||||
| `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation tels que suppression du texte visible par l’assistant, helpers de rendu/segmentation/tableau Markdown, helpers de masquage, helpers de balise de directive et utilitaires de texte sûr |
|
||||
| `plugin-sdk/text-chunking` | Helper de segmentation de texte sortant |
|
||||
| `plugin-sdk/speech` | Types de fournisseur Speech ainsi qu’helpers orientés fournisseur pour directives, registre et validation |
|
||||
| `plugin-sdk/speech-core` | Helpers partagés de types, registre, directive et normalisation pour fournisseur Speech |
|
||||
| `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias, plus constructeurs de payload média |
|
||||
| `plugin-sdk/media-generation-runtime` | Helpers partagés de basculement en cas d’échec pour la génération de médias, sélection de candidats et messages de modèle manquant |
|
||||
| `plugin-sdk/media-understanding` | Types de fournisseur de compréhension de médias, plus exports helpers côté fournisseur pour image/audio |
|
||||
| `plugin-sdk/text-runtime` | Helpers partagés de texte/Markdown/journalisation comme la suppression de texte visible par l’assistant, les helpers de rendu/découpage/tableau Markdown, les helpers de masquage, les helpers de balises de directive et les utilitaires de texte sûr |
|
||||
| `plugin-sdk/text-chunking` | Helper de découpage de texte sortant |
|
||||
| `plugin-sdk/speech` | Types de fournisseur Speech, plus helpers côté fournisseur pour directives, registre et validation |
|
||||
| `plugin-sdk/speech-core` | Helpers partagés de types de fournisseur Speech, registre, directive et normalisation |
|
||||
| `plugin-sdk/realtime-transcription` | Types de fournisseur de transcription en temps réel et helpers de registre |
|
||||
| `plugin-sdk/realtime-voice` | Types de fournisseur de voix en temps réel et helpers de registre |
|
||||
| `plugin-sdk/image-generation` | Types de fournisseur de génération d’image |
|
||||
| `plugin-sdk/image-generation-core` | Helpers partagés de types, basculement en cas d’échec, authentification et registre pour la génération d’image |
|
||||
| `plugin-sdk/music-generation` | Types de fournisseur/de requête/de résultat pour la génération musicale |
|
||||
| `plugin-sdk/music-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération musicale |
|
||||
| `plugin-sdk/video-generation` | Types de fournisseur/de requête/de résultat pour la génération vidéo |
|
||||
| `plugin-sdk/video-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de référence de modèle pour la génération vidéo |
|
||||
| `plugin-sdk/webhook-targets` | Helpers de registre de cible Webhook et d’installation de route |
|
||||
| `plugin-sdk/music-generation` | Types de fournisseur/requête/résultat pour la génération musicale |
|
||||
| `plugin-sdk/music-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de `model-ref` pour la génération musicale |
|
||||
| `plugin-sdk/video-generation` | Types de fournisseur/requête/résultat pour la génération vidéo |
|
||||
| `plugin-sdk/video-generation-core` | Helpers partagés de types, basculement en cas d’échec, recherche de fournisseur et analyse de `model-ref` pour la génération vidéo |
|
||||
| `plugin-sdk/webhook-targets` | Registre de cibles Webhook et helpers d’installation de route |
|
||||
| `plugin-sdk/webhook-path` | Helpers de normalisation de chemin Webhook |
|
||||
| `plugin-sdk/web-media` | Helpers partagés de chargement de médias distants/locaux |
|
||||
| `plugin-sdk/zod` | `zod` réexporté pour les consommateurs du SDK Plugin |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins mémoire">
|
||||
| Sous-chemin | Exportations clés |
|
||||
<Accordion title="Sous-chemins de mémoire">
|
||||
| Sous-chemin | Exportations principales |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Surface helper `memory-core` intégrée pour les helpers de gestionnaire/config/fichier/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Façade de runtime pour l’indexation/la recherche mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Exportations du moteur de fondation hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embedding hôte mémoire, accès au registre, fournisseur local et helpers génériques de lot/distant |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Exportations du moteur QMD hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Exportations du moteur de stockage hôte mémoire |
|
||||
| `plugin-sdk/memory-core` | Surface helper `memory-core` intégrée pour les helpers de gestionnaire/configuration/fichier/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Façade d’exécution d’indexation/recherche mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Exports du moteur de fondation hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embeddings hôte mémoire, accès au registre, fournisseur local et helpers génériques de lot/distants |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Exports du moteur QMD hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Exports du moteur de stockage hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-query` | Helpers de requête hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-status` | Helpers de statut hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime CLI hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime central hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/runtime hôte mémoire |
|
||||
| `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers de runtime central hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-status` | Helpers d’état hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers d’exécution CLI hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpers d’exécution cœur hôte mémoire |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/d’exécution hôte mémoire |
|
||||
| `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers d’exécution cœur hôte mémoire |
|
||||
| `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements hôte mémoire |
|
||||
| `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/runtime hôte mémoire |
|
||||
| `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins adjacents à la mémoire |
|
||||
| `plugin-sdk/memory-host-search` | Façade de runtime Active Memory pour l’accès au gestionnaire de recherche |
|
||||
| `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers de statut hôte mémoire |
|
||||
| `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/d’exécution hôte mémoire |
|
||||
| `plugin-sdk/memory-host-markdown` | Helpers partagés de Markdown géré pour les plugins liés à la mémoire |
|
||||
| `plugin-sdk/memory-host-search` | Façade d’exécution Active Memory pour l’accès au gestionnaire de recherche |
|
||||
| `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les helpers d’état hôte mémoire |
|
||||
| `plugin-sdk/memory-lancedb` | Surface helper `memory-lancedb` intégrée |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sous-chemins helper intégrés réservés">
|
||||
| Famille | Sous-chemins actuels | Utilisation prévue |
|
||||
<Accordion title="Sous-chemins helpers intégrés réservés">
|
||||
| Famille | Sous-chemins actuels | Usage prévu |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de support pour le plugin Browser intégré (`browser-support` reste le barrel de compatibilité) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/runtime Matrix intégrée |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/runtime LINE intégrée |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de prise en charge du Plugin browser intégré (`browser-support` reste le barrel de compatibilité) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Surface helper/d’exécution Matrix intégrée |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/d’exécution LINE intégrée |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface helper IRC intégrée |
|
||||
| Helpers spécifiques à un canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Surfaces de compatibilité/helper de canaux intégrés |
|
||||
| Helpers spécifiques à l’authentification/au plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Surfaces helper de fonctionnalités/plugins intégrés ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` |
|
||||
| Helpers spécifiques aux canaux | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Points d’entrée de compatibilité/helper de canaux intégrés |
|
||||
| Helpers spécifiques à l’authentification/au plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Points d’entrée helper de fonctionnalité/plugin intégrés ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API d’enregistrement
|
||||
|
||||
Le callback `register(api)` reçoit un objet `OpenClawPluginApi` avec ces
|
||||
méthodes :
|
||||
méthodes :
|
||||
|
||||
### Enregistrement de capacités
|
||||
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ----------------------------------------------- | -------------------------------------- |
|
||||
| `api.registerProvider(...)` | Inférence de texte (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Exécuteur d’agent bas niveau expérimental |
|
||||
| `api.registerCliBackend(...)` | Backend local d’inférence CLI |
|
||||
| `api.registerChannel(...)` | Canal de messagerie |
|
||||
| `api.registerSpeechProvider(...)` | Synthèse texte-parole / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transcription en temps réel en streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales duplex en temps réel |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analyse d’image/audio/vidéo |
|
||||
| `api.registerImageGenerationProvider(...)` | Génération d’image |
|
||||
| `api.registerMusicGenerationProvider(...)` | Génération musicale |
|
||||
| `api.registerVideoGenerationProvider(...)` | Génération vidéo |
|
||||
| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web |
|
||||
| `api.registerWebSearchProvider(...)` | Recherche web |
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ------------------------------------------------ | -------------------------------------- |
|
||||
| `api.registerProvider(...)` | Inférence de texte (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Exécuteur d’agent expérimental de bas niveau |
|
||||
| `api.registerCliBackend(...)` | Backend local d’inférence CLI |
|
||||
| `api.registerChannel(...)` | Canal de messagerie |
|
||||
| `api.registerSpeechProvider(...)` | Synthèse texte-parole / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transcription temps réel en streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sessions vocales temps réel duplex |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analyse d’images/audio/vidéo |
|
||||
| `api.registerImageGenerationProvider(...)` | Génération d’image |
|
||||
| `api.registerMusicGenerationProvider(...)` | Génération musicale |
|
||||
| `api.registerVideoGenerationProvider(...)` | Génération vidéo |
|
||||
| `api.registerWebFetchProvider(...)` | Fournisseur de récupération / scraping web |
|
||||
| `api.registerWebSearchProvider(...)` | Recherche web |
|
||||
|
||||
### Outils et commandes
|
||||
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ----------------------------- | ------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Outil d’agent (obligatoire ou `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) |
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Outil d’agent (requis ou `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Commande personnalisée (contourne le LLM) |
|
||||
|
||||
### Infrastructure
|
||||
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| --------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook d’événement |
|
||||
| `api.registerHttpRoute(params)` | Point de terminaison HTTP Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Méthode RPC Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Sous-commande CLI |
|
||||
| `api.registerService(service)` | Service en arrière-plan |
|
||||
| `api.registerInteractiveHandler(registration)` | Gestionnaire interactif |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Section additive de prompt adjacente à la mémoire |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire |
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ---------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook d’événement |
|
||||
| `api.registerHttpRoute(params)` | Point de terminaison HTTP Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Méthode RPC Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Sous-commande CLI |
|
||||
| `api.registerService(service)` | Service d’arrière-plan |
|
||||
| `api.registerInteractiveHandler(registration)` | Gestionnaire interactif |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Section additive de prompt liée à la mémoire |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additif de recherche/lecture mémoire |
|
||||
|
||||
Les espaces de noms d’administration du cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) restent toujours `operator.admin`, même si un plugin essaie d’assigner une
|
||||
portée de méthode Gateway plus étroite. Préférez des préfixes spécifiques au plugin pour
|
||||
les méthodes appartenant au plugin.
|
||||
`update.*`) restent toujours `operator.admin`, même si un plugin tente
|
||||
d’attribuer une portée de méthode Gateway plus étroite. Préférez des préfixes spécifiques au plugin pour les
|
||||
méthodes possédées par le plugin.
|
||||
|
||||
### Métadonnées d’enregistrement CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de premier niveau :
|
||||
`api.registerCli(registrar, opts?)` accepte deux types de métadonnées de premier niveau :
|
||||
|
||||
- `commands` : racines de commande explicites appartenant au registrar
|
||||
- `descriptors` : descripteurs de commande au moment de l’analyse utilisés pour l’aide de la CLI racine,
|
||||
le routage et l’enregistrement paresseux de la CLI du plugin
|
||||
- `commands` : racines de commande explicites possédées par le registrar
|
||||
- `descriptors` : descripteurs de commande au moment de l’analyse utilisés pour l’aide de la CLI racine,
|
||||
le routage et l’enregistrement paresseux de CLI de plugin
|
||||
|
||||
Si vous voulez qu’une commande de plugin reste chargée paresseusement dans le chemin CLI racine normal,
|
||||
Si vous voulez qu’une commande de plugin reste chargée à la demande dans le chemin normal de la CLI racine,
|
||||
fournissez des `descriptors` qui couvrent chaque racine de commande de premier niveau exposée par ce
|
||||
registrar.
|
||||
|
||||
@ -383,135 +395,134 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Utilisez `commands` seul uniquement lorsque vous n’avez pas besoin d’un enregistrement CLI racine paresseux.
|
||||
Ce chemin de compatibilité eager reste pris en charge, mais il n’installe pas
|
||||
d’emplacements réservés adossés à des descripteurs pour le chargement paresseux au moment de l’analyse.
|
||||
Utilisez `commands` seul uniquement lorsque vous n’avez pas besoin d’un enregistrement paresseux dans la CLI racine.
|
||||
Ce chemin de compatibilité chargé de manière anticipée reste pris en charge, mais il n’installe pas
|
||||
de placeholders adossés à des descripteurs pour le chargement paresseux au moment de l’analyse.
|
||||
|
||||
### Enregistrement du backend CLI
|
||||
### Enregistrement de backend CLI
|
||||
|
||||
`api.registerCliBackend(...)` permet à un plugin de posséder la config par défaut d’un backend CLI
|
||||
d’IA local tel que `codex-cli`.
|
||||
`api.registerCliBackend(...)` permet à un plugin de posséder la configuration par défaut pour un
|
||||
backend CLI IA local tel que `codex-cli`.
|
||||
|
||||
- L’`id` du backend devient le préfixe de fournisseur dans des références de modèle comme `codex-cli/gpt-5`.
|
||||
- La `config` du backend utilise la même forme que `agents.defaults.cliBackends.<id>`.
|
||||
- La config utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.<id>` sur la
|
||||
- Le `id` du backend devient le préfixe du fournisseur dans des références de modèle comme `codex-cli/gpt-5`.
|
||||
- Le `config` du backend utilise la même forme que `agents.defaults.cliBackends.<id>`.
|
||||
- La configuration utilisateur garde la priorité. OpenClaw fusionne `agents.defaults.cliBackends.<id>` par-dessus la
|
||||
valeur par défaut du plugin avant d’exécuter la CLI.
|
||||
- Utilisez `normalizeConfig` lorsqu’un backend a besoin de réécritures de compatibilité après fusion
|
||||
(par exemple pour normaliser d’anciennes formes de drapeaux).
|
||||
|
||||
### Emplacements exclusifs
|
||||
### Slots exclusifs
|
||||
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts au prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée |
|
||||
| `api.registerMemoryPromptSection(builder)` | Constructeur de section de prompt mémoire |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Résolveur de plan de vidage mémoire |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adaptateur de runtime mémoire |
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Moteur de contexte (un seul actif à la fois). Le callback `assemble()` reçoit `availableTools` et `citationsMode` afin que le moteur puisse adapter les ajouts au prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Capacité mémoire unifiée |
|
||||
| `api.registerMemoryPromptSection(builder)` | Constructeur de section de prompt mémoire |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Résolveur de plan de vidage mémoire |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adaptateur d’exécution mémoire |
|
||||
|
||||
### Adaptateurs d’embedding mémoire
|
||||
### Adaptateurs d’embeddings mémoire
|
||||
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| --------------------------------------------- | -------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d’embedding mémoire pour le plugin actif |
|
||||
| Méthode | Ce qu’elle enregistre |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptateur d’embeddings mémoire pour le plugin actif |
|
||||
|
||||
- `registerMemoryCapability` est l’API de plugin mémoire exclusive préférée.
|
||||
- `registerMemoryCapability` est l’API exclusive préférée pour les plugins mémoire.
|
||||
- `registerMemoryCapability` peut aussi exposer `publicArtifacts.listArtifacts(...)`
|
||||
afin que des plugins compagnons puissent consommer les artefacts mémoire exportés via
|
||||
`openclaw/plugin-sdk/memory-host-core` au lieu d’atteindre la disposition privée d’un
|
||||
plugin mémoire spécifique.
|
||||
afin que des plugins compagnons puissent consommer des artefacts mémoire exportés via
|
||||
`openclaw/plugin-sdk/memory-host-core` au lieu d’atteindre la disposition privée
|
||||
d’un plugin mémoire spécifique.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` et
|
||||
`registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec les versions historiques.
|
||||
`registerMemoryRuntime` sont des API exclusives de plugin mémoire compatibles avec l’héritage.
|
||||
- `registerMemoryEmbeddingProvider` permet au plugin mémoire actif d’enregistrer un
|
||||
ou plusieurs identifiants d’adaptateur d’embedding (par exemple `openai`, `gemini` ou un identifiant
|
||||
personnalisé défini par le plugin).
|
||||
- La config utilisateur comme `agents.defaults.memorySearch.provider` et
|
||||
`agents.defaults.memorySearch.fallback` se résout par rapport à ces identifiants
|
||||
d’adaptateur enregistrés.
|
||||
ou plusieurs identifiants d’adaptateur d’embeddings (par exemple `openai`, `gemini` ou un identifiant personnalisé
|
||||
défini par le plugin).
|
||||
- La configuration utilisateur, comme `agents.defaults.memorySearch.provider` et
|
||||
`agents.defaults.memorySearch.fallback`, se résout par rapport à ces identifiants d’adaptateur enregistrés.
|
||||
|
||||
### Événements et cycle de vie
|
||||
|
||||
| Méthode | Ce qu’elle fait |
|
||||
| ------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé |
|
||||
| Méthode | Ce qu’elle fait |
|
||||
| -------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook de cycle de vie typé |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback de liaison de conversation |
|
||||
|
||||
### Sémantique de décision des hooks
|
||||
|
||||
- `before_tool_call` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `before_tool_call` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge.
|
||||
- `before_install` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `before_install` : retourner `{ block: false }` est traité comme aucune décision (comme si `block` était omis), et non comme une surcharge.
|
||||
- `reply_dispatch` : retourner `{ handled: true, ... }` est terminal. Dès qu’un gestionnaire revendique la répartition, les gestionnaires de priorité inférieure et le chemin par défaut de répartition du modèle sont ignorés.
|
||||
- `message_sending` : retourner `{ cancel: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `message_sending` : retourner `{ cancel: false }` est traité comme aucune décision (comme si `cancel` était omis), et non comme une surcharge.
|
||||
- `before_tool_call` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `before_tool_call` : retourner `{ block: false }` est traité comme aucune décision (identique à l’omission de `block`), et non comme une substitution.
|
||||
- `before_install` : retourner `{ block: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `before_install` : retourner `{ block: false }` est traité comme aucune décision (identique à l’omission de `block`), et non comme une substitution.
|
||||
- `reply_dispatch` : retourner `{ handled: true, ... }` est terminal. Dès qu’un gestionnaire revendique la distribution, les gestionnaires de priorité inférieure et le chemin par défaut de distribution du modèle sont ignorés.
|
||||
- `message_sending` : retourner `{ cancel: true }` est terminal. Dès qu’un gestionnaire le définit, les gestionnaires de priorité inférieure sont ignorés.
|
||||
- `message_sending` : retourner `{ cancel: false }` est traité comme aucune décision (identique à l’omission de `cancel`), et non comme une substitution.
|
||||
|
||||
### Champs de l’objet API
|
||||
|
||||
| Champ | Type | Description |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Identifiant du plugin |
|
||||
| `api.id` | `string` | ID du plugin |
|
||||
| `api.name` | `string` | Nom d’affichage |
|
||||
| `api.version` | `string?` | Version du plugin (facultatif) |
|
||||
| `api.description` | `string?` | Description du plugin (facultatif) |
|
||||
| `api.version` | `string?` | Version du plugin (facultative) |
|
||||
| `api.description` | `string?` | Description du plugin (facultative) |
|
||||
| `api.source` | `string` | Chemin source du plugin |
|
||||
| `api.rootDir` | `string?` | Répertoire racine du plugin (facultatif) |
|
||||
| `api.config` | `OpenClawConfig` | Instantané de config actuel (instantané actif en mémoire à l’exécution lorsqu’il est disponible) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Config spécifique au plugin depuis `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/fr/plugins/sdk-runtime) |
|
||||
| `api.config` | `OpenClawConfig` | Instantané de configuration actuel (instantané d’exécution en mémoire actif lorsqu’il est disponible) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Configuration spécifique au plugin provenant de `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helpers d’exécution](/fr/plugins/sdk-runtime) |
|
||||
| `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 le chargement complet |
|
||||
| `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 |
|
||||
|
||||
## Convention de module interne
|
||||
|
||||
Dans votre plugin, utilisez des fichiers barrel locaux pour les importations internes :
|
||||
Dans votre plugin, utilisez des fichiers barrel locaux pour les imports internes :
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Exportations publiques pour les consommateurs externes
|
||||
runtime-api.ts # Exportations de runtime réservées à l’interne
|
||||
api.ts # Exports publics pour les consommateurs externes
|
||||
runtime-api.ts # Exports d’exécution internes uniquement
|
||||
index.ts # Point d’entrée du plugin
|
||||
setup-entry.ts # Entrée légère réservée à la configuration (facultatif)
|
||||
setup-entry.ts # Entrée légère pour configuration uniquement (facultatif)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
N’importez jamais votre propre plugin via `openclaw/plugin-sdk/<your-plugin>`
|
||||
depuis le code de production. Faites passer les importations internes par `./api.ts` ou
|
||||
`./runtime-api.ts`. Le chemin du SDK est uniquement le contrat externe.
|
||||
depuis le code de production. Faites passer les imports internes via `./api.ts` ou
|
||||
`./runtime-api.ts`. Le chemin SDK est uniquement le contrat externe.
|
||||
</Warning>
|
||||
|
||||
Les surfaces publiques des plugins intégrés chargées via façade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` et fichiers d’entrée publics similaires) préfèrent désormais
|
||||
l’instantané actif de config d’exécution lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané
|
||||
d’exécution n’existe encore, elles reviennent au fichier de config résolu sur le disque.
|
||||
Les surfaces publiques de plugins intégrés chargées via façade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` et fichiers d’entrée publics similaires) privilégient désormais l’instantané
|
||||
de configuration d’exécution actif lorsque OpenClaw est déjà en cours d’exécution. Si aucun instantané
|
||||
d’exécution n’existe encore, elles reviennent au fichier de configuration résolu sur disque.
|
||||
|
||||
Les plugins de fournisseur peuvent aussi exposer un barrel de contrat local au plugin et étroit lorsqu’un
|
||||
helper est intentionnellement spécifique à un fournisseur et n’a pas encore sa place dans un sous-chemin SDK
|
||||
générique. Exemple intégré actuel : le fournisseur Anthropic conserve ses helpers de flux Claude
|
||||
dans sa propre surface publique `api.ts` / `contract-api.ts` au lieu de
|
||||
Les plugins de fournisseur peuvent également exposer un barrel de contrat local au plugin et étroit lorsqu’un
|
||||
helper est volontairement spécifique au fournisseur et n’a pas encore sa place dans un sous-chemin SDK
|
||||
générique. Exemple intégré actuel : le fournisseur Anthropic conserve ses helpers de flux Claude
|
||||
dans son propre point d’entrée public `api.ts` / `contract-api.ts` au lieu de
|
||||
promouvoir la logique d’en-tête bêta Anthropic et `service_tier` dans un contrat
|
||||
générique `plugin-sdk/*`.
|
||||
|
||||
Autres exemples intégrés actuels :
|
||||
Autres exemples intégrés actuels :
|
||||
|
||||
- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de fournisseur,
|
||||
- `@openclaw/openai-provider` : `api.ts` exporte des constructeurs de fournisseur,
|
||||
des helpers de modèle par défaut et des constructeurs de fournisseur temps réel
|
||||
- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de fournisseur ainsi que
|
||||
des helpers d’intégration/de config
|
||||
- `@openclaw/openrouter-provider` : `api.ts` exporte le constructeur de fournisseur ainsi que
|
||||
des helpers d’intégration/de configuration
|
||||
|
||||
<Warning>
|
||||
Le code de production des extensions doit également éviter les importations `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Le code de production d’extension doit également éviter les imports `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Si un helper est réellement partagé, promouvez-le vers un sous-chemin SDK neutre
|
||||
tel que `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou une autre
|
||||
surface orientée capacité au lieu de coupler deux plugins entre eux.
|
||||
</Warning>
|
||||
|
||||
## Liens connexes
|
||||
## Lié
|
||||
|
||||
- [Points d’entrée](/fr/plugins/sdk-entrypoints) — options de `definePluginEntry` et `defineChannelPluginEntry`
|
||||
- [Helpers de runtime](/fr/plugins/sdk-runtime) — référence complète de l’espace de noms `api.runtime`
|
||||
- [Configuration et config](/fr/plugins/sdk-setup) — empaquetage, manifestes, schémas de config
|
||||
- [Points d’entrée](/fr/plugins/sdk-entrypoints) — options `definePluginEntry` et `defineChannelPluginEntry`
|
||||
- [Helpers d’exécution](/fr/plugins/sdk-runtime) — référence complète de l’espace de noms `api.runtime`
|
||||
- [Configuration et config](/fr/plugins/sdk-setup) — empaquetage, manifestes, schémas de configuration
|
||||
- [Tests](/fr/plugins/sdk-testing) — utilitaires de test et règles de lint
|
||||
- [Migration du SDK](/fr/plugins/sdk-migration) — migration depuis des surfaces obsolètes
|
||||
- [Internes des plugins](/fr/plugins/architecture) — architecture détaillée et modèle de capacités
|
||||
- [Internes des plugins](/fr/plugins/architecture) — architecture approfondie et modèle de capacité
|
||||
|
||||
@ -1,33 +1,34 @@
|
||||
---
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T06:01:41Z"
|
||||
generated_at: "2026-04-18T06:44:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd
|
||||
source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca
|
||||
source_path: refactor/qa.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Refactorisation de la QA
|
||||
# Refactorisation QA
|
||||
|
||||
Statut : migration fondamentale terminée.
|
||||
Statut : la migration de base a été intégrée.
|
||||
|
||||
## Objectif
|
||||
|
||||
Faire évoluer la QA d’OpenClaw d’un modèle à définition répartie vers une source de vérité unique :
|
||||
Faire évoluer la QA d’OpenClaw d’un modèle à définitions séparées vers une source de vérité unique :
|
||||
|
||||
- métadonnées des scénarios
|
||||
- prompts envoyés au modèle
|
||||
- configuration et nettoyage
|
||||
- logique du harnais
|
||||
- assertions et critères de réussite
|
||||
- artefacts et indications pour les rapports
|
||||
- artefacts et indications de rapport
|
||||
|
||||
L’état final souhaité est un harnais QA générique qui charge de puissants fichiers de définition de scénario au lieu de coder en dur la majeure partie du comportement en TypeScript.
|
||||
L’état final souhaité est un harnais QA générique qui charge des fichiers de définition de scénarios puissants au lieu de coder en dur la majeure partie du comportement en TypeScript.
|
||||
|
||||
## État actuel
|
||||
|
||||
La source principale de vérité se trouve désormais dans `qa/scenarios/index.md` plus un fichier par scénario sous `qa/scenarios/*.md`.
|
||||
La source de vérité principale vit désormais dans `qa/scenarios/index.md` plus un fichier par
|
||||
scénario sous `qa/scenarios/<theme>/*.md`.
|
||||
|
||||
Implémenté :
|
||||
|
||||
@ -35,30 +36,30 @@ Implémenté :
|
||||
- métadonnées canoniques du pack QA
|
||||
- identité de l’opérateur
|
||||
- mission de lancement
|
||||
- `qa/scenarios/*.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
- un fichier Markdown par scénario
|
||||
- métadonnées du scénario
|
||||
- liaisons de handlers
|
||||
- configuration d’exécution spécifique au scénario
|
||||
- associations de handlers
|
||||
- configuration d’exécution propre au scénario
|
||||
- `extensions/qa-lab/src/scenario-catalog.ts`
|
||||
- parseur de pack Markdown + validation zod
|
||||
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
|
||||
- rendu du plan à partir du pack Markdown
|
||||
- `extensions/qa-lab/src/qa-agent-workspace.ts`
|
||||
- génère les fichiers de compatibilité initiaux plus `QA_SCENARIOS.md`
|
||||
- alimente les fichiers de compatibilité générés plus `QA_SCENARIOS.md`
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- sélectionne les scénarios exécutables via des liaisons de handlers définies en Markdown
|
||||
- Protocole QA bus + UI
|
||||
- sélectionne les scénarios exécutables via des associations de handlers définies en Markdown
|
||||
- Protocole de bus QA + interface utilisateur
|
||||
- pièces jointes inline génériques pour le rendu image/vidéo/audio/fichier
|
||||
|
||||
Surfaces encore réparties :
|
||||
Surfaces encore séparées :
|
||||
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- possède encore la majeure partie de la logique des handlers exécutables personnalisés
|
||||
- possède encore la majeure partie de la logique de handlers personnalisés exécutables
|
||||
- `extensions/qa-lab/src/report.ts`
|
||||
- dérive encore la structure du rapport à partir des sorties d’exécution
|
||||
|
||||
Ainsi, la répartition de la source de vérité est corrigée, mais l’exécution reste encore majoritairement appuyée sur des handlers plutôt que pleinement déclarative.
|
||||
La séparation de la source de vérité est donc corrigée, mais l’exécution reste encore majoritairement pilotée par des handlers plutôt que pleinement déclarative.
|
||||
|
||||
## À quoi ressemble réellement la surface des scénarios
|
||||
|
||||
@ -66,39 +67,39 @@ La lecture de la suite actuelle montre quelques classes de scénarios distinctes
|
||||
|
||||
### Interaction simple
|
||||
|
||||
- référence de base du canal
|
||||
- référence de base en message direct
|
||||
- suivi dans un fil
|
||||
- référence de canal
|
||||
- référence DM
|
||||
- suivi en fil
|
||||
- changement de modèle
|
||||
- suivi après approbation
|
||||
- réaction/modification/suppression
|
||||
- poursuite après approbation
|
||||
- réaction/édition/suppression
|
||||
|
||||
### Mutation de configuration et d’exécution
|
||||
|
||||
- désactivation de skill par patch de config
|
||||
- config apply restart wake-up
|
||||
- inversion de capacité après redémarrage de configuration
|
||||
- correctif de config avec désactivation de skill
|
||||
- réveil après redémarrage suite à application de config
|
||||
- bascule de capacité après redémarrage de config
|
||||
- vérification de dérive de l’inventaire d’exécution
|
||||
|
||||
### Assertions sur système de fichiers et dépôt
|
||||
### Assertions sur le système de fichiers et le dépôt
|
||||
|
||||
- rapport de découverte source/docs
|
||||
- build Lobster Invaders
|
||||
- recherche d’artefact d’image générée
|
||||
- build de Lobster Invaders
|
||||
- recherche d’artefact d’image généré
|
||||
|
||||
### Orchestration de la mémoire
|
||||
|
||||
- rappel de mémoire
|
||||
- outils de mémoire dans un contexte de canal
|
||||
- repli en cas d’échec de la mémoire
|
||||
- rappel mémoire
|
||||
- outils mémoire dans le contexte du canal
|
||||
- repli en cas d’échec mémoire
|
||||
- classement de la mémoire de session
|
||||
- isolation de la mémoire par fil
|
||||
- memory dreaming sweep
|
||||
- isolation mémoire par fil
|
||||
- balayage Dreaming de la mémoire
|
||||
|
||||
### Intégration d’outils et de plugins
|
||||
|
||||
- appel MCP plugin-tools
|
||||
- visibilité des Skills
|
||||
- visibilité des skill
|
||||
- installation à chaud de skill
|
||||
- génération d’image native
|
||||
- aller-retour d’image
|
||||
@ -107,31 +108,32 @@ La lecture de la suite actuelle montre quelques classes de scénarios distinctes
|
||||
### Multi-tour et multi-acteur
|
||||
|
||||
- transfert vers un sous-agent
|
||||
- synthèse par fanout de sous-agents
|
||||
- flux de style reprise après redémarrage
|
||||
- synthèse par répartition sur plusieurs sous-agents
|
||||
- flux de type récupération après redémarrage
|
||||
|
||||
Ces catégories sont importantes parce qu’elles pilotent les exigences du DSL. Une simple liste de prompt + texte attendu ne suffit pas.
|
||||
Ces catégories sont importantes car elles déterminent les exigences du DSL. Une liste plate de prompt + texte attendu ne suffit pas.
|
||||
|
||||
## Orientation
|
||||
|
||||
### Source de vérité unique
|
||||
|
||||
Utiliser `qa/scenarios/index.md` plus `qa/scenarios/*.md` comme source de vérité rédigée.
|
||||
Utiliser `qa/scenarios/index.md` plus `qa/scenarios/<theme>/*.md` comme
|
||||
source de vérité rédigée.
|
||||
|
||||
Le pack doit rester :
|
||||
|
||||
- lisible par un humain en revue
|
||||
- analysable par machine
|
||||
- suffisamment riche pour piloter :
|
||||
- analysable par la machine
|
||||
- assez riche pour piloter :
|
||||
- l’exécution de la suite
|
||||
- l’initialisation de l’espace de travail QA
|
||||
- les métadonnées de l’UI QA Lab
|
||||
- les prompts de documentation/découverte
|
||||
- le bootstrap de l’espace de travail QA
|
||||
- les métadonnées de l’interface QA Lab
|
||||
- les prompts de docs/découverte
|
||||
- la génération de rapports
|
||||
|
||||
### Format de rédaction préféré
|
||||
|
||||
Utiliser Markdown comme format de premier niveau, avec du YAML structuré à l’intérieur.
|
||||
Utiliser Markdown comme format de haut niveau, avec du YAML structuré à l’intérieur.
|
||||
|
||||
Forme recommandée :
|
||||
|
||||
@ -142,7 +144,7 @@ Forme recommandée :
|
||||
- tags
|
||||
- docs refs
|
||||
- code refs
|
||||
- surcharges de modèle/fournisseur
|
||||
- remplacements de modèle/provider
|
||||
- prérequis
|
||||
- sections en prose
|
||||
- objectif
|
||||
@ -157,12 +159,12 @@ Forme recommandée :
|
||||
Cela apporte :
|
||||
|
||||
- une meilleure lisibilité en PR qu’un énorme JSON
|
||||
- un contexte plus riche qu’un simple YAML
|
||||
- une analyse stricte et une validation zod
|
||||
- un contexte plus riche que du YAML pur
|
||||
- un parsing strict et une validation zod
|
||||
|
||||
Le JSON brut n’est acceptable qu’en tant que forme intermédiaire générée.
|
||||
|
||||
## Forme proposée pour un fichier de scénario
|
||||
## Forme proposée du fichier de scénario
|
||||
|
||||
Exemple :
|
||||
|
||||
@ -237,7 +239,7 @@ Verify generated media is reattached on the follow-up turn.
|
||||
|
||||
## Capacités du runner que le DSL doit couvrir
|
||||
|
||||
D’après la suite actuelle, le runner générique a besoin de plus que de l’exécution de prompts.
|
||||
D’après la suite actuelle, le runner générique a besoin de plus que l’exécution de prompts.
|
||||
|
||||
### Actions d’environnement et de configuration
|
||||
|
||||
@ -248,7 +250,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’
|
||||
- `thread.create`
|
||||
- `workspace.writeSkill`
|
||||
|
||||
### Actions de tour d’agent
|
||||
### Actions de tour agent
|
||||
|
||||
- `agent.send`
|
||||
- `agent.wait`
|
||||
@ -264,7 +266,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’
|
||||
- `tools.effective`
|
||||
- `skills.status`
|
||||
|
||||
### Actions sur fichiers et artefacts
|
||||
### Actions sur les fichiers et artefacts
|
||||
|
||||
- `file.write`
|
||||
- `file.read`
|
||||
@ -273,7 +275,7 @@ D’après la suite actuelle, le runner générique a besoin de plus que de l’
|
||||
- `artifact.captureGeneratedImage`
|
||||
- `artifact.capturePath`
|
||||
|
||||
### Actions de mémoire et de cron
|
||||
### Actions mémoire et Cron
|
||||
|
||||
- `memory.indexForce`
|
||||
- `memory.searchCli`
|
||||
@ -312,36 +314,36 @@ Exemples issus de la suite actuelle :
|
||||
- créer un fil, puis réutiliser `threadId`
|
||||
- créer une session, puis réutiliser `sessionKey`
|
||||
- générer une image, puis joindre le fichier au tour suivant
|
||||
- générer une chaîne marqueur de réveil, puis vérifier qu’elle apparaît plus tard
|
||||
- générer une chaîne de marqueur de réveil, puis vérifier qu’elle apparaît plus tard
|
||||
|
||||
Capacités nécessaires :
|
||||
|
||||
- `saveAs`
|
||||
- `${vars.name}`
|
||||
- `${artifacts.name}`
|
||||
- références typées pour les chemins, clés de session, identifiants de fil, marqueurs, sorties d’outils
|
||||
- références typées pour les chemins, clés de session, ids de fil, marqueurs, sorties d’outils
|
||||
|
||||
Sans prise en charge des variables, le harnais continuera à faire fuiter la logique des scénarios vers le TypeScript.
|
||||
Sans prise en charge des variables, le harnais continuera à faire fuir la logique des scénarios vers TypeScript.
|
||||
|
||||
## Ce qui doit rester comme échappatoires
|
||||
|
||||
Un runner purement déclaratif n’est pas réaliste en phase 1.
|
||||
Un runner entièrement déclaratif pur n’est pas réaliste en phase 1.
|
||||
|
||||
Certains scénarios sont intrinsèquement lourds en orchestration :
|
||||
|
||||
- memory dreaming sweep
|
||||
- config apply restart wake-up
|
||||
- config restart capability flip
|
||||
- résolution d’artefact d’image générée par horodatage/chemin
|
||||
- balayage Dreaming de la mémoire
|
||||
- réveil après redémarrage suite à application de config
|
||||
- bascule de capacité après redémarrage de config
|
||||
- résolution d’artefact d’image généré par horodatage/chemin
|
||||
- évaluation du rapport de découverte
|
||||
|
||||
Ils devraient pour l’instant utiliser des handlers personnalisés explicites.
|
||||
Ceux-ci devraient utiliser pour l’instant des handlers personnalisés explicites.
|
||||
|
||||
Règle recommandée :
|
||||
|
||||
- 85-90 % déclaratif
|
||||
- étapes `customHandler` explicites pour le reste difficile
|
||||
- uniquement des handlers personnalisés nommés et documentés
|
||||
- seulement des handlers personnalisés nommés et documentés
|
||||
- aucun code inline anonyme dans le fichier de scénario
|
||||
|
||||
Cela garde le moteur générique propre tout en permettant d’avancer.
|
||||
@ -350,19 +352,19 @@ Cela garde le moteur générique propre tout en permettant d’avancer.
|
||||
|
||||
### Actuel
|
||||
|
||||
Le Markdown des scénarios est déjà la source de vérité pour :
|
||||
Le Markdown de scénario est déjà la source de vérité pour :
|
||||
|
||||
- l’exécution de la suite
|
||||
- les fichiers d’initialisation de l’espace de travail
|
||||
- le catalogue de scénarios de l’UI QA Lab
|
||||
- les fichiers de bootstrap de l’espace de travail
|
||||
- le catalogue de scénarios de l’interface QA Lab
|
||||
- les métadonnées de rapport
|
||||
- les prompts de découverte
|
||||
|
||||
Compatibilité générée :
|
||||
|
||||
- l’espace de travail initial inclut toujours `QA_KICKOFF_TASK.md`
|
||||
- l’espace de travail initial inclut toujours `QA_SCENARIO_PLAN.md`
|
||||
- l’espace de travail initial inclut désormais aussi `QA_SCENARIOS.md`
|
||||
- l’espace de travail initialisé inclut encore `QA_KICKOFF_TASK.md`
|
||||
- l’espace de travail initialisé inclut encore `QA_SCENARIO_PLAN.md`
|
||||
- l’espace de travail initialisé inclut désormais aussi `QA_SCENARIOS.md`
|
||||
|
||||
## Plan de refactorisation
|
||||
|
||||
@ -371,16 +373,16 @@ Compatibilité générée :
|
||||
Terminé.
|
||||
|
||||
- ajout de `qa/scenarios/index.md`
|
||||
- séparation des scénarios dans `qa/scenarios/*.md`
|
||||
- ajout d’un parseur pour le contenu YAML Markdown nommé du pack
|
||||
- découpage des scénarios dans `qa/scenarios/<theme>/*.md`
|
||||
- ajout d’un parseur pour le contenu de pack YAML Markdown nommé
|
||||
- validation avec zod
|
||||
- basculement des consommateurs vers le pack analysé
|
||||
- bascule des consommateurs vers le pack parsé
|
||||
- suppression de `qa/seed-scenarios.json` et `qa/QA_KICKOFF_TASK.md` au niveau du dépôt
|
||||
|
||||
### Phase 2 : moteur générique
|
||||
|
||||
- diviser `extensions/qa-lab/src/suite.ts` en :
|
||||
- chargeur
|
||||
- découper `extensions/qa-lab/src/suite.ts` en :
|
||||
- loader
|
||||
- moteur
|
||||
- registre d’actions
|
||||
- registre d’assertions
|
||||
@ -391,12 +393,12 @@ Livrable :
|
||||
|
||||
- le moteur exécute des scénarios déclaratifs simples
|
||||
|
||||
Commencer par les scénarios qui sont principalement prompt + attente + assertion :
|
||||
Commencer par des scénarios qui sont principalement prompt + attente + assertion :
|
||||
|
||||
- suivi dans un fil
|
||||
- suivi en fil
|
||||
- compréhension d’image à partir d’une pièce jointe
|
||||
- visibilité et invocation de Skills
|
||||
- référence de base du canal
|
||||
- visibilité et invocation de skill
|
||||
- référence de canal
|
||||
|
||||
Livrable :
|
||||
|
||||
@ -405,10 +407,10 @@ Livrable :
|
||||
### Phase 4 : migrer les scénarios intermédiaires
|
||||
|
||||
- aller-retour de génération d’image
|
||||
- outils de mémoire dans un contexte de canal
|
||||
- outils mémoire dans le contexte du canal
|
||||
- classement de la mémoire de session
|
||||
- transfert vers un sous-agent
|
||||
- synthèse par fanout de sous-agents
|
||||
- synthèse par répartition sur plusieurs sous-agents
|
||||
|
||||
Livrable :
|
||||
|
||||
@ -416,24 +418,24 @@ Livrable :
|
||||
|
||||
### Phase 5 : conserver les scénarios difficiles sur des handlers personnalisés
|
||||
|
||||
- memory dreaming sweep
|
||||
- config apply restart wake-up
|
||||
- config restart capability flip
|
||||
- dérive d’inventaire d’exécution
|
||||
- balayage Dreaming de la mémoire
|
||||
- réveil après redémarrage suite à application de config
|
||||
- bascule de capacité après redémarrage de config
|
||||
- dérive de l’inventaire d’exécution
|
||||
|
||||
Livrable :
|
||||
|
||||
- même format de rédaction, mais avec des blocs d’étapes personnalisées explicites là où nécessaire
|
||||
- même format de rédaction, mais avec des blocs d’étapes personnalisées explicites quand nécessaire
|
||||
|
||||
### Phase 6 : supprimer la map de scénarios codée en dur
|
||||
|
||||
Quand la couverture du pack sera suffisamment bonne :
|
||||
Une fois que la couverture du pack est suffisamment bonne :
|
||||
|
||||
- supprimer la majeure partie du branchement TypeScript spécifique aux scénarios dans `extensions/qa-lab/src/suite.ts`
|
||||
- supprimer la majeure partie des branchements TypeScript spécifiques aux scénarios de `extensions/qa-lab/src/suite.ts`
|
||||
|
||||
## Faux Slack / prise en charge des médias riches
|
||||
## Prise en charge du faux Slack / des médias enrichis
|
||||
|
||||
Le QA bus actuel est centré sur le texte.
|
||||
Le bus QA actuel est centré sur le texte.
|
||||
|
||||
Fichiers concernés :
|
||||
|
||||
@ -443,7 +445,7 @@ Fichiers concernés :
|
||||
- `extensions/qa-lab/src/bus-server.ts`
|
||||
- `extensions/qa-lab/web/src/ui-render.ts`
|
||||
|
||||
Aujourd’hui, le QA bus prend en charge :
|
||||
Aujourd’hui, le bus QA prend en charge :
|
||||
|
||||
- texte
|
||||
- réactions
|
||||
@ -453,7 +455,7 @@ Il ne modélise pas encore les pièces jointes média inline.
|
||||
|
||||
### Contrat de transport nécessaire
|
||||
|
||||
Ajouter un modèle générique de pièce jointe QA bus :
|
||||
Ajouter un modèle générique de pièce jointe au bus QA :
|
||||
|
||||
```ts
|
||||
type QaBusAttachment = {
|
||||
@ -478,55 +480,55 @@ Puis ajouter `attachments?: QaBusAttachment[]` à :
|
||||
- `QaBusInboundMessageInput`
|
||||
- `QaBusOutboundMessageInput`
|
||||
|
||||
### Pourquoi commencer par du générique
|
||||
### Pourquoi d’abord générique
|
||||
|
||||
Ne construisez pas un modèle média réservé à Slack.
|
||||
Ne pas construire un modèle de média propre à Slack uniquement.
|
||||
|
||||
À la place :
|
||||
|
||||
- un modèle de transport QA générique
|
||||
- plusieurs moteurs de rendu par-dessus
|
||||
- le chat actuel de QA Lab
|
||||
- un futur faux Slack web
|
||||
- un modèle de transport QA générique unique
|
||||
- plusieurs moteurs de rendu au-dessus
|
||||
- le chat QA Lab actuel
|
||||
- un futur faux web Slack
|
||||
- toute autre vue de faux transport
|
||||
|
||||
Cela évite la logique dupliquée et permet aux scénarios média de rester indépendants du transport.
|
||||
Cela évite la duplication de logique et permet aux scénarios média de rester indépendants du transport.
|
||||
|
||||
### Travail UI nécessaire
|
||||
### Travail d’interface nécessaire
|
||||
|
||||
Mettre à jour l’UI QA pour afficher :
|
||||
Mettre à jour l’interface QA pour afficher :
|
||||
|
||||
- aperçu d’image inline
|
||||
- lecteur audio inline
|
||||
- lecteur vidéo inline
|
||||
- puce de pièce jointe de fichier
|
||||
- puce de pièce jointe fichier
|
||||
|
||||
L’UI actuelle peut déjà afficher les fils et les réactions, donc le rendu des pièces jointes devrait pouvoir se superposer au même modèle de carte de message.
|
||||
L’interface actuelle sait déjà afficher les fils et les réactions, donc le rendu des pièces jointes devrait se superposer au même modèle de carte de message.
|
||||
|
||||
### Travail sur les scénarios rendu possible par le transport média
|
||||
### Travail de scénario rendu possible par le transport média
|
||||
|
||||
Une fois que les pièces jointes circuleront dans le QA bus, nous pourrons ajouter des scénarios de faux chat plus riches :
|
||||
Une fois que les pièces jointes circulent via le bus QA, nous pouvons ajouter des scénarios de faux chat plus riches :
|
||||
|
||||
- réponse avec image inline dans un faux Slack
|
||||
- compréhension d’une pièce jointe audio
|
||||
- compréhension d’une pièce jointe vidéo
|
||||
- compréhension de pièce jointe audio
|
||||
- compréhension de pièce jointe vidéo
|
||||
- ordre mixte des pièces jointes
|
||||
- réponse dans un fil avec conservation du média
|
||||
|
||||
## Recommandation
|
||||
|
||||
Le prochain bloc d’implémentation devrait être :
|
||||
Le prochain lot d’implémentation devrait être :
|
||||
|
||||
1. ajouter un chargeur de scénarios Markdown + un schéma zod
|
||||
1. ajouter un chargeur de scénarios Markdown + schéma zod
|
||||
2. générer le catalogue actuel à partir du Markdown
|
||||
3. migrer d’abord quelques scénarios simples
|
||||
4. ajouter la prise en charge générique des pièces jointes QA bus
|
||||
5. afficher une image inline dans l’UI QA
|
||||
4. ajouter la prise en charge générique des pièces jointes du bus QA
|
||||
5. afficher l’image inline dans l’interface QA
|
||||
6. puis étendre à l’audio et à la vidéo
|
||||
|
||||
C’est le plus petit chemin qui prouve les deux objectifs :
|
||||
C’est le plus petit chemin qui valide les deux objectifs :
|
||||
|
||||
- QA générique définie en Markdown
|
||||
- QA générique définie par Markdown
|
||||
- surfaces de messagerie simulées plus riches
|
||||
|
||||
## Questions ouvertes
|
||||
@ -534,5 +536,5 @@ C’est le plus petit chemin qui prouve les deux objectifs :
|
||||
- si les fichiers de scénario doivent autoriser des modèles de prompt Markdown embarqués avec interpolation de variables
|
||||
- si setup/cleanup doivent être des sections nommées ou simplement des listes d’actions ordonnées
|
||||
- si les références d’artefacts doivent être fortement typées dans le schéma ou basées sur des chaînes
|
||||
- si les handlers personnalisés doivent vivre dans un seul registre ou dans des registres par surface
|
||||
- si les handlers personnalisés doivent vivre dans un registre unique ou dans des registres par surface
|
||||
- si le fichier de compatibilité JSON généré doit rester versionné pendant la migration
|
||||
|
||||
Loading…
Reference in New Issue
Block a user