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

chore(i18n): refresh fr translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 09:00:02 +00:00
parent 33c6672312
commit ddf26b79d5
14 changed files with 2216 additions and 2168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/fr/automation/hooks.md
View File

@ -5,19 +5,19 @@ read_when:
summary: 'Hooks : automatisation pilotée par événements pour les commandes et les événements du cycle de vie'
title: Hooks
x-i18n:
generated_at: "2026-04-24T06:59:06Z"
generated_at: "2026-04-24T08:57:06Z"
model: gpt-5.4
provider: openai
source_hash: 9e24d5a95748151059e34f8c9ff9910dbcd7a32e7cadb44d1fa25352ef3a09a6
source_hash: 4e6246f25272208d9a9ff2f186bcd3a463c78ea24b833f0259174d0f7f0cbea6
source_path: automation/hooks.md
workflow: 15
---
Les hooks sont de petits scripts qui s’exécutent lorsqu’un événement se produit dans le Gateway. Ils peuvent être découverts à partir de répertoires et inspectés avec `openclaw hooks`. Le Gateway ne charge les hooks internes qu’après l’activation des hooks ou la configuration d’au moins une entrée de hook, d’un pack de hooks, d’un gestionnaire hérité ou d’un répertoire de hooks supplémentaire.
Les hooks sont de petits scripts qui s’exécutent lorsqu’un événement se produit dans le Gateway. Ils peuvent être découverts à partir de répertoires et inspectés avec `openclaw hooks`. Le Gateway charge les hooks internes uniquement après l’activation des hooks ou la configuration d’au moins une entrée de hook, d’un pack de hooks, d’un gestionnaire hérité ou d’un répertoire de hooks supplémentaire.
Il existe deux types de hooks dans OpenClaw :
- **Hooks internes** (cette page) : s’exécutent dans le Gateway lorsque des événements d’agent se déclenchent, comme `/new`, `/reset`, `/stop` ou des événements du cycle de vie.
- **Hooks internes** (cette page) : s’exécutent dans le Gateway lorsque des événements de l’agent se déclenchent, comme `/new`, `/reset`, `/stop` ou des événements du cycle de vie.
- **Webhooks** : points de terminaison HTTP externes qui permettent à d’autres systèmes de déclencher du travail dans OpenClaw. Voir [Webhooks](/fr/automation/cron-jobs#webhooks).
Les hooks peuvent aussi être inclus dans des plugins. `openclaw hooks list` affiche à la fois les hooks autonomes et les hooks gérés par des plugins.
@ -40,21 +40,21 @@ openclaw hooks info session-memory
## Types d’événements
| Event | Quand il se déclenche |
| ------------------------ | ----------------------------------------------- |
| `command:new` | Commande `/new` émise |
| `command:reset` | Commande `/reset` émise |
| `command:stop` | Commande `/stop` émise |
| `command` | Tout événement de commande (écouteur général) |
| `session:compact:before` | Avant que Compaction résume l’historique |
| `session:compact:after` | Après la fin de la compaction |
| Event | Quand il se déclenche |
| ------------------------ | ---------------------------------------------- |
| `command:new` | Commande `/new` émise |
| `command:reset` | Commande `/reset` émise |
| `command:stop` | Commande `/stop` émise |
| `command` | Tout événement de commande (écoute générale) |
| `session:compact:before` | Avant que la Compaction résume l’historique |
| `session:compact:after` | Après la fin de la Compaction |
| `session:patch` | Lorsque les propriétés de session sont modifiées |
| `agent:bootstrap` | Avant l’injection des fichiers bootstrap de l’espace de travail |
| `agent:bootstrap` | Avant l’injection des fichiers bootstrap du workspace |
| `gateway:startup` | Après le démarrage des canaux et le chargement des hooks |
| `message:received` | Message entrant depuis n’importe quel canal |
| `message:transcribed` | Après la fin de la transcription audio |
| `message:preprocessed` | Après la fin de tout le traitement des médias et de la compréhension des liens |
| `message:sent` | Message sortant remis |
| `message:received` | Message entrant depuis n’importe quel canal |
| `message:transcribed` | Après la fin de la transcription audio |
| `message:preprocessed` | Après la fin du traitement de tous les médias et liens |
| `message:sent` | Message sortant remis |
## Écriture de hooks
@ -62,7 +62,7 @@ openclaw hooks info session-memory
Chaque hook est un répertoire contenant deux fichiers :
```text
```
my-hook/
├── HOOK.md # Métadonnées + documentation
└── handler.ts # Implémentation du gestionnaire
@ -78,21 +78,21 @@ metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# Mon hook
# My Hook
La documentation détaillée va ici.
```
**Champs de métadonnées** (`metadata.openclaw`) :
| Field | Description |
| Champ | Description |
| ---------- | ---------------------------------------------------- |
| `emoji` | Emoji affiché dans la CLI |
| `emoji` | Emoji d’affichage pour la CLI |
| `events` | Tableau des événements à écouter |
| `export` | Export nommé à utiliser (par défaut `"default"`) |
| `os` | Plateformes requises (par ex. `["darwin", "linux"]`) |
| `requires` | `bins`, `anyBins`, `env` ou chemins `config` requis |
| `always` | Contourner les vérifications d’éligibilité (booléen) |
| `always` | Ignore les vérifications d’éligibilité (booléen) |
| `install` | Méthodes d’installation |
### Implémentation du gestionnaire
@ -104,22 +104,22 @@ const handler = async (event) => {
}
console.log(`[my-hook] New command triggered`);
// Votre logique ici
// Your logic here
// Facultatif : envoyer un message à l’utilisateur
// Optionally send message to user
event.messages.push("Hook executed!");
};
export default handler;
```
Chaque événement inclut : `type`, `action`, `sessionKey`, `timestamp`, `messages` (ajouter pour envoyer à l’utilisateur) et `context` (données spécifiques à l’événement).
Chaque événement inclut : `type`, `action`, `sessionKey`, `timestamp`, `messages` (ajouter avec `push` pour envoyer à l’utilisateur) et `context` (données spécifiques à l’événement). Les contextes de hooks des plugins d’agent et d’outil peuvent aussi inclure `trace`, un contexte de trace diagnostique compatible W3C en lecture seule que les plugins peuvent transmettre dans des journaux structurés pour la corrélation OTEL.
### Points importants sur le contexte des événements
### Points clés du contexte d’événement
**Événements de commande** (`command:new`, `command:reset`) : `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
**Événements de message** (`message:received`) : `context.from`, `context.content`, `context.channelId`, `context.metadata` (données spécifiques au fournisseur, y compris `senderId`, `senderName`, `guildId`).
**Événements de message** (`message:received`) : `context.from`, `context.content`, `context.channelId`, `context.metadata` (données spécifiques au fournisseur, notamment `senderId`, `senderName`, `guildId`).
**Événements de message** (`message:sent`) : `context.to`, `context.content`, `context.success`, `context.channelId`.
@ -127,24 +127,24 @@ Chaque événement inclut : `type`, `action`, `sessionKey`, `timestamp`, `messa
**Événements de message** (`message:preprocessed`) : `context.bodyForAgent` (corps final enrichi), `context.from`, `context.channelId`.
**Événements bootstrap** (`agent:bootstrap`) : `context.bootstrapFiles` (tableau modifiable), `context.agentId`.
**Événements de bootstrap** (`agent:bootstrap`) : `context.bootstrapFiles` (tableau mutable), `context.agentId`.
**Événements de modification de session** (`session:patch`) : `context.sessionEntry`, `context.patch` (uniquement les champs modifiés), `context.cfg`. Seuls les clients privilégiés peuvent déclencher des événements de modification.
**Événements de patch de session** (`session:patch`) : `context.sessionEntry`, `context.patch` (champs modifiés uniquement), `context.cfg`. Seuls les clients privilégiés peuvent déclencher des événements de patch.
**Événements de compaction** : `session:compact:before` inclut `messageCount`, `tokenCount`. `session:compact:after` ajoute `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
**Événements de Compaction** : `session:compact:before` inclut `messageCount`, `tokenCount`. `session:compact:after` ajoute `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
## Découverte des hooks
Les hooks sont découverts à partir de ces répertoires, dans l’ordre de priorité d’écrasement croissante :
Les hooks sont découverts à partir de ces répertoires, dans l’ordre de priorité croissante pour les remplacements :
1. **Hooks intégrés** : livrés avec OpenClaw
2. **Hooks de plugin** : hooks inclus dans les plugins installés
3. **Hooks gérés** : `~/.openclaw/hooks/` (installés par l’utilisateur, partagés entre les espaces de travail). Les répertoires supplémentaires de `hooks.internal.load.extraDirs` partagent cette même priorité.
4. **Hooks d’espace de travail** : `<workspace>/hooks/` (par agent, désactivés par défaut jusqu’à activation explicite)
1. **Hooks inclus** : livrés avec OpenClaw
2. **Hooks de plugins** : hooks inclus dans les plugins installés
3. **Hooks gérés** : `~/.openclaw/hooks/` (installés par l’utilisateur, partagés entre workspaces). Les répertoires supplémentaires de `hooks.internal.load.extraDirs` partagent cette priorité.
4. **Hooks du workspace** : `<workspace>/hooks/` (par agent, désactivés par défaut jusqu’à activation explicite)
Les hooks d’espace de travail peuvent ajouter de nouveaux noms de hooks, mais ne peuvent pas remplacer des hooks intégrés, gérés ou fournis par un plugin portant le même nom.
Les hooks du workspace peuvent ajouter de nouveaux noms de hooks, mais ne peuvent pas remplacer des hooks inclus, gérés ou fournis par un plugin portant le même nom.
Le Gateway ignore la découverte des hooks internes au démarrage tant que les hooks internes ne sont pas configurés. Activez un hook intégré ou géré avec `openclaw hooks enable <name>`, installez un pack de hooks ou définissez `hooks.internal.enabled=true` pour participer explicitement. Lorsque vous activez un hook nommé, le Gateway ne charge que le gestionnaire de ce hook ; `hooks.internal.enabled=true`, les répertoires de hooks supplémentaires et les gestionnaires hérités activent une découverte étendue.
Le Gateway ignore la découverte des hooks internes au démarrage tant que les hooks internes ne sont pas configurés. Activez un hook inclus ou géré avec `openclaw hooks enable <name>`, installez un pack de hooks ou définissez `hooks.internal.enabled=true` pour l’activer explicitement. Lorsque vous activez un hook nommé, le Gateway charge uniquement le gestionnaire de ce hook ; `hooks.internal.enabled=true`, les répertoires de hooks supplémentaires et les gestionnaires hérités activent une découverte large.
### Packs de hooks
@ -154,9 +154,9 @@ Les packs de hooks sont des packages npm qui exportent des hooks via `openclaw.h
openclaw plugins install <path-or-spec>
```
Les spécifications npm sont limitées au registre (nom du package + version exacte facultative ou dist-tag). Les spécifications Git/URL/fichier et les plages semver sont rejetées.
Les spécifications npm sont limitées au registre (nom du package + éventuellement version exacte ou dist-tag). Les spécifications Git/URL/fichier et les plages semver sont rejetées.
## Hooks intégrés
## Hooks inclus
| Hook | Events | Ce qu’il fait |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
@ -165,7 +165,7 @@ Les spécifications npm sont limitées au registre (nom du package + version exa
| command-logger | `command` | Journalise toutes les commandes dans `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | Exécute `BOOT.md` au démarrage du gateway |
Activez n’importe quel hook intégré :
Activez n’importe quel hook inclus :
```bash
openclaw hooks enable <hook-name>
@ -175,7 +175,7 @@ openclaw hooks enable <hook-name>
### Détails de session-memory
Extrait les 15 derniers messages utilisateur/assistant, génère un slug de nom de fichier descriptif via LLM et l’enregistre dans `<workspace>/memory/YYYY-MM-DD-slug.md`. Nécessite que `workspace.dir` soit configuré.
Extrait les 15 derniers messages utilisateur/assistant, génère un slug de nom de fichier descriptif via LLM, puis l’enregistre dans `<workspace>/memory/YYYY-MM-DD-slug.md`. Nécessite que `workspace.dir` soit configuré.
<a id="bootstrap-extra-files"></a>
@ -196,7 +196,7 @@ Extrait les 15 derniers messages utilisateur/assistant, génère un slug de nom
}
```
Les chemins sont résolus relativement à l’espace de travail. Seuls les noms de base bootstrap reconnus sont chargés (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
Les chemins sont résolus par rapport au workspace. Seuls les noms de base bootstrap reconnus sont chargés (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
<a id="command-logger"></a>
@ -208,13 +208,13 @@ Journalise chaque commande slash dans `~/.openclaw/logs/commands.log`.
### Détails de boot-md
Exécute `BOOT.md` depuis l’espace de travail actif au démarrage du gateway.
Exécute `BOOT.md` depuis le workspace actif au démarrage du gateway.
## Hooks de plugin
## Hooks de plugins
Les plugins peuvent enregistrer des hooks via le SDK de Plugin pour une intégration plus poussée : interception des appels d’outils, modification des prompts, contrôle du flux de messages, et plus encore. Le SDK de Plugin expose 28 hooks couvrant la résolution de modèle, le cycle de vie de l’agent, le flux de messages, l’exécution d’outils, la coordination des sous-agents et le cycle de vie du gateway.
Les plugins peuvent enregistrer des hooks via le Plugin SDK pour une intégration plus profonde : interception des appels d’outils, modification des prompts, contrôle du flux de messages, et plus encore. Le Plugin SDK expose 28 hooks couvrant la résolution de modèle, le cycle de vie de l’agent, le flux de messages, l’exécution d’outils, la coordination de sous-agents et le cycle de vie du gateway.
Pour la référence complète des hooks de plugin, y compris `before_tool_call`, `before_agent_reply`, `before_install` et tous les autres hooks de plugin, voir [Plugin Architecture](/fr/plugins/architecture-internals#provider-runtime-hooks).
Pour la référence complète des hooks de plugins, y compris `before_tool_call`, `before_agent_reply`, `before_install` et tous les autres hooks de plugins, voir [Plugin Architecture](/fr/plugins/architecture-internals#provider-runtime-hooks).
## Configuration
@ -264,19 +264,19 @@ Répertoires de hooks supplémentaires :
```
<Note>
L’ancien format de configuration en tableau `hooks.internal.handlers` est toujours pris en charge pour la rétrocompatibilité, mais les nouveaux hooks doivent utiliser le système basé sur la découverte.
Le format de configuration hérité `hooks.internal.handlers` sous forme de tableau est toujours pris en charge pour la rétrocompatibilité, mais les nouveaux hooks doivent utiliser le système basé sur la découverte.
</Note>
## Référence CLI
```bash
# Lister tous les hooks (ajoutez --eligible, --verbose ou --json)
# Lister tous les hooks (ajouter --eligible, --verbose ou --json)
openclaw hooks list
# Afficher les informations détaillées sur un hook
# Afficher les informations détaillées d’un hook
openclaw hooks info <hook-name>
# Afficher le résumé d’éligibilité
# Afficher un résumé d’éligibilité
openclaw hooks check
# Activer/désactiver
@ -286,7 +286,7 @@ openclaw hooks disable <hook-name>
## Bonnes pratiques
- **Gardez des gestionnaires rapides.** Les hooks s’exécutent pendant le traitement des commandes. Lancez les tâches lourdes en arrière-plan avec `void processInBackground(event)`.
- **Gardez les gestionnaires rapides.** Les hooks s’exécutent pendant le traitement des commandes. Déclenchez les travaux lourds en arrière-plan avec `void processInBackground(event)`.
- **Gérez les erreurs proprement.** Encadrez les opérations risquées avec try/catch ; ne lancez pas d’exception afin que les autres gestionnaires puissent s’exécuter.
- **Filtrez les événements tôt.** Retournez immédiatement si le type/l’action d’événement n’est pas pertinent.
- **Utilisez des clés d’événement spécifiques.** Préférez `"events": ["command:new"]` à `"events": ["command"]` pour réduire la surcharge.
@ -310,7 +310,7 @@ openclaw hooks list
openclaw hooks info my-hook
```
Vérifiez la présence des binaires requis (PATH), des variables d’environnement, des valeurs de configuration ou de la compatibilité du système d’exploitation.
Vérifiez l’absence de binaires requis (PATH), de variables d’environnement, de valeurs de configuration ou la compatibilité du système d’exploitation.
### Hook non exécuté
@ -322,5 +322,5 @@ Vérifiez la présence des binaires requis (PATH), des variables d’environneme
- [Référence CLI : hooks](/fr/cli/hooks)
- [Webhooks](/fr/automation/cron-jobs#webhooks)
- [Plugin Architecture](/fr/plugins/architecture-internals#provider-runtime-hooks) — référence complète des hooks de plugin
- [Plugin Architecture](/fr/plugins/architecture-internals#provider-runtime-hooks) — référence complète des hooks de plugins
- [Configuration](/fr/gateway/configuration-reference#hooks)

149
docs/fr/ci.md
View File

@ -1,27 +1,57 @@
---
read_when:
- Vous devez comprendre pourquoi un job CI s’est ou ne s’est pas exécuté
- Vous déboguez des vérifications GitHub Actions en échec
summary: Graphe des jobs CI, barrières de portée et équivalents des commandes locales
- Vous devez comprendre pourquoi un job CI s’est exécuté ou non.
- Vous déboguez des vérifications GitHub Actions en échec.
summary: Graphe des jobs CI, portes de portée et équivalents des commandes locales
title: Pipeline CI
x-i18n:
generated_at: "2026-04-24T07:02:49Z"
generated_at: "2026-04-24T08:57:06Z"
model: gpt-5.4
provider: openai
source_hash: 8e24efec145ff144b007e248ef0f9c56287619eb9af204d45d49984909a6136b
source_hash: 489ac05725a316b25f56f7f754d6a8652abbd60481fbe6e692572b81581fe405
source_path: ci.md
workflow: 15
---
La CI s’exécute à chaque push vers `main` et sur chaque pull request. Elle utilise un ciblage intelligent pour ignorer les jobs coûteux lorsque seules des zones sans rapport ont changé.
Le CI s’exécute sur chaque push vers `main` et sur chaque pull request. Il utilise une portée intelligente pour ignorer les jobs coûteux lorsque seules des zones sans rapport ont changé.
QA Lab dispose de voies CI dédiées en dehors du workflow principal à portée intelligente. Le workflow `Parity gate` s’exécute sur les changements de PR correspondants et par déclenchement manuel ; il construit le runtime QA privé et compare les packs agentiques mock GPT-5.4 et Opus 4.6. Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et par déclenchement manuel ; il distribue en parallèle le parity gate mock, la voie Matrix en direct et la voie Telegram en direct. Les jobs en direct utilisent l’environnement `qa-live-shared`, et la voie Telegram utilise des baux Convex. `OpenClaw Release Checks` exécute également les mêmes voies QA Lab avant l’approbation d’une release.
QA Lab dispose de lanes CI dédiées en dehors du workflow principal à portée intelligente. Le
workflow `Parity gate` s’exécute sur les modifications de PR correspondantes et sur déclenchement manuel ; il
construit le runtime QA privé et compare les packs agentiques simulés GPT-5.4 et Opus 4.6.
Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et sur
déclenchement manuel ; il répartit en jobs parallèles la parity gate simulée, la lane Matrix live et la lane Telegram live.
Les jobs live utilisent l’environnement `qa-live-shared`,
et la lane Telegram utilise des baux Convex. `OpenClaw Release
Checks` exécute également les mêmes lanes QA Lab avant l’approbation de la release.
Le workflow `Duplicate PRs After Merge` est un workflow manuel de maintenance pour le nettoyage des doublons après intégration. Il utilise par défaut le mode dry-run et ne ferme que les PR explicitement listées lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est fusionnée et que chaque doublon a soit une issue référencée partagée, soit des hunks modifiés qui se chevauchent.
Le workflow `Duplicate PRs After Merge` est un workflow manuel de maintenance pour
le nettoyage des doublons après intégration. Il utilise le mode dry-run par défaut et ne ferme
que les PR explicitement listées lorsque `apply=true`. Avant de modifier GitHub,
il vérifie que la PR intégrée est bien fusionnée et que chaque doublon a soit une issue référencée commune,
soit des hunks modifiés qui se chevauchent.
Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par événements pour maintenir la documentation existante alignée sur les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie sur `main` après un push non effectué par un bot peut le déclencher, et un déclenchement manuel peut l’exécuter directement. Les invocations par workflow-run sont ignorées si `main` a déjà avancé ou si une autre exécution `Docs Agent` non ignorée a été créée dans la dernière heure. Lorsqu’il s’exécute, il examine la plage de commits depuis le SHA source du précédent `Docs Agent` non ignoré jusqu’au `main` actuel, de sorte qu’une exécution horaire puisse couvrir tous les changements accumulés sur main depuis le dernier passage documentation.
Le workflow `Docs Agent` est une lane de maintenance Codex pilotée par événements pour maintenir
la documentation existante alignée avec les changements récemment intégrés. Il n’a pas de planification pure :
une exécution CI réussie sur `main` issue d’un push non-bot peut le déclencher,
et un déclenchement manuel peut l’exécuter directement. Les invocations via workflow-run sont ignorées si
`main` a déjà avancé ou si une autre exécution Docs Agent non ignorée a été créée dans la dernière heure.
Lorsqu’il s’exécute, il examine la plage de commits depuis le SHA source du précédent Docs Agent non ignoré jusqu’au
`main` actuel ; ainsi, une exécution horaire peut couvrir tous les changements de `main`
accumulés depuis le dernier passage docs.
Le workflow `Test Performance Agent` est une voie de maintenance Codex pilotée par événements pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie sur `main` après un push non effectué par un bot peut le déclencher, mais il est ignoré si une autre invocation par workflow-run a déjà été exécutée ou est en cours ce jour UTC. Le déclenchement manuel contourne cette barrière d’activité quotidienne. Cette voie construit un rapport complet des performances Vitest groupées, laisse Codex effectuer uniquement de petites corrections de performance de test préservant la couverture plutôt que de larges refactorings, puis relance le rapport complet et rejette les changements qui réduisent le nombre de tests de référence réussis. Si la référence comporte des tests en échec, Codex ne peut corriger que les échecs évidents et le rapport complet après intervention de l’agent doit réussir avant qu’un quelconque commit soit effectué. Lorsque `main` avance avant que le push du bot validé n’atterrisse, la voie rebase le correctif validé, relance `pnpm check:changed` et réessaie le push ; les correctifs obsolètes en conflit sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex puisse conserver la même posture de sécurité sans sudo que l’agent docs.
Le workflow `Test Performance Agent` est une lane de maintenance Codex pilotée par événements
pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie sur `main`
issue d’un push non-bot peut le déclencher, mais il est ignoré si une autre invocation workflow-run
s’est déjà exécutée ou est en cours ce jour UTC. Un déclenchement manuel contourne cette
porte d’activité quotidienne. La lane construit un rapport de performance Vitest groupé de la suite complète,
laisse Codex apporter uniquement de petites corrections de performance des tests préservant la couverture plutôt que de larges
refactorings, puis relance le rapport de suite complète et rejette les changements qui réduisent
le nombre de tests de référence réussis. Si la référence comporte des tests en échec, Codex
ne peut corriger que les échecs évidents et le rapport complet après intervention de l’agent doit réussir avant
qu’un quelconque commit soit effectué. Lorsque `main` avance avant que le push du bot n’atterrisse,
la lane rebase le patch validé, relance `pnpm check:changed`, puis réessaie le push ;
les patchs obsolètes en conflit sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex
puisse conserver la même posture de sécurité sans sudo que l’agent docs.
```bash
gh workflow run duplicate-after-merge.yml \
@ -32,90 +62,89 @@ gh workflow run duplicate-after-merge.yml \
## Vue d’ensemble des jobs
| Job | But | Quand il s’exécute |
| Job | Objectif | Quand il s’exécute |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------- |
| `preflight` | Détecter les changements docs-only, les portées modifiées, les extensions modifiées, et construire le manifeste CI | Toujours sur les pushes et PR non brouillon |
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushes et PR non brouillon |
| `security-dependency-audit` | Audit sans dépendances du lockfile de production par rapport aux avis npm | Toujours sur les pushes et PR non brouillon |
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushes et PR non brouillon |
| `build-artifacts` | Construire `dist/`, la Control UI, les vérifications d’artefacts construits, et les artefacts réutilisables en aval | Changements pertinents pour Node |
| `checks-fast-core` | Voies rapides de correction Linux, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications shardées des contrats de canaux avec un résultat de vérification agrégé stable | Changements pertinents pour Node |
| `checks-node-extensions` | Shards complets de tests de plugins inclus sur toute la suite d’extensions | Changements pertinents pour Node |
| `checks-node-core-test` | Shards de tests Node du cœur, hors canaux, plugins inclus, contrats et voies d’extensions | Changements pertinents pour Node |
| `extension-fast` | Tests ciblés uniquement pour les plugins inclus modifiés | Pull requests avec changements d’extensions |
| `check` | Équivalent local principal shardé : types prod, lint, gardes, types de test et smoke strict | Changements pertinents pour Node |
| `check-additional` | Architecture, limites, gardes de surface d’extension, limites de package, et shards gateway-watch | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de la CLI construite et smoke de mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Vérificateur pour les tests de canaux d’artefacts construits plus compatibilité Node 22 uniquement sur push | Changements pertinents pour Node |
| `check-docs` | Formatage docs, lint et vérifications de liens cassés | Documentation modifiée |
| `skills-python` | Ruff + pytest pour les Skills adossées à Python | Changements pertinents pour les Skills Python |
| `checks-windows` | Voies de test spécifiques à Windows | Changements pertinents pour Windows |
| `macos-node` | Voie de test TypeScript macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `preflight` | Détecter les changements docs-only, les portées modifiées, les extensions modifiées et construire le manifeste CI | Toujours sur les pushs et PR non brouillons |
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushs et PR non brouillons |
| `security-dependency-audit` | Audit du lockfile de production sans dépendances contre les avis npm | Toujours sur les pushs et PR non brouillons |
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs et PR non brouillons |
| `build-artifacts` | Construire `dist/`, l’interface Control UI, les vérifications d’artefacts construits et les artefacts réutilisables en aval | Changements pertinents pour Node |
| `checks-fast-core` | Lanes de correction Linux rapides, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node |
| `checks-fast-contracts-channels` | Vérifications shardées des contrats de canaux avec un résultat agrégé stable | Changements pertinents pour Node |
| `checks-node-extensions` | Shards de tests complets des plugins groupés sur toute la suite d’extensions | Changements pertinents pour Node |
| `checks-node-core-test` | Shards de tests Node du cœur, hors lanes canal, groupées, contrat et extension | Changements pertinents pour Node |
| `extension-fast` | Tests ciblés pour les seuls plugins groupés modifiés | Pull requests avec changements d’extension |
| `check` | Équivalent de la porte locale principale shardée : types prod, lint, gardes, types de test et smoke strict | Changements pertinents pour Node |
| `check-additional` | Shards architecture, limites, gardes de surface d’extension, limites de package et gateway-watch | Changements pertinents pour Node |
| `build-smoke` | Tests smoke de la CLI construite et smoke mémoire au démarrage | Changements pertinents pour Node |
| `checks` | Vérificateur pour les tests de canaux sur artefacts construits plus compatibilité Node 22 uniquement sur push | Changements pertinents pour Node |
| `check-docs` | Vérifications de formatage docs, lint et liens cassés | Docs modifiées |
| `skills-python` | Ruff + pytest pour les Skills basées sur Python | Changements pertinents pour les Skills Python |
| `checks-windows` | Lanes de tests spécifiques à Windows | Changements pertinents pour Windows |
| `macos-node` | Lane de tests TypeScript macOS utilisant les artefacts construits partagés | Changements pertinents pour macOS |
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements pertinents pour macOS |
| `android` | Tests unitaires Android pour les deux variantes plus un build APK debug | Changements pertinents pour Android |
| `test-performance-agent` | Optimisation quotidienne des tests lents par Codex après activité de confiance | Succès CI sur main ou déclenchement manuel |
| `test-performance-agent` | Optimisation quotidienne des tests lents par Codex après activité de confiance | Succès du CI principal ou déclenchement manuel |
## Ordre fail-fast
Les jobs sont ordonnés de sorte que les vérifications peu coûteuses échouent avant que les plus coûteuses ne s’exécutent :
Les jobs sont ordonnés de façon à ce que les vérifications peu coûteuses échouent avant le lancement des jobs plus coûteux :
1. `preflight` décide quelles voies existent réellement. La logique `docs-scope` et `changed-scope` correspond à des étapes dans ce job, et non à des jobs autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds de matrice d’artefacts et de plateformes.
3. `build-artifacts` se chevauche avec les voies Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt.
4. Les voies de plateforme et de runtime plus lourdes se distribuent ensuite : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` réservé aux PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
1. `preflight` décide quelles lanes existent réellement. La logique `docs-scope` et `changed-scope` correspond à des étapes à l’intérieur de ce job, pas à des jobs autonomes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds de matrice artefacts et plateformes.
3. `build-artifacts` se chevauche avec les lanes Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt.
4. Ensuite, les lanes plus lourdes de plateforme et de runtime se répartissent : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` réservé aux PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
La logique de portée se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`.
Les modifications du workflow CI valident le graphe CI Node ainsi que le lint des workflows, mais n’imposent pas à elles seules les builds natifs Windows, Android ou macOS ; ces voies de plateforme restent limitées aux changements du code source de la plateforme.
Les vérifications Node Windows sont limitées aux wrappers Windows spécifiques aux processus/chemins, aux helpers d’exécution npm/pnpm/UI, à la configuration du gestionnaire de packages, et aux surfaces de workflow CI qui exécutent cette voie ; les changements sans rapport dans le code source, les plugins, l’install-smoke et les tests seuls restent sur les voies Linux Node afin de ne pas réserver un worker Windows 16 vCPU pour une couverture déjà exercée par les shards de test normaux.
Le workflow séparé `install-smoke` réutilise le même script de portée via son propre job `preflight`. Il répartit la couverture smoke entre `run_fast_install_smoke` et `run_full_install_smoke`. Les pull requests exécutent le chemin rapide pour les surfaces Docker/package, les changements de package/manifeste de plugins inclus, et les surfaces cœur plugin/canal/gateway/Plugin SDK que les jobs Docker smoke exercent. Les changements uniquement de code source dans les plugins inclus, les modifications de tests seules et les modifications docs-only ne réservent pas de workers Docker. Le chemin rapide construit une fois l’image du Dockerfile racine, vérifie la CLI, exécute l’e2e gateway-network en conteneur, vérifie un argument de build d’extension incluse, et exécute le profil Docker de plugin inclus borné avec un délai de commande de 120 secondes. Le chemin complet conserve la couverture d’installation par QR package ainsi que la couverture installateur Docker/update pour les exécutions nocturnes planifiées, les déclenchements manuels, les vérifications de release par workflow-call et les pull requests qui touchent réellement les surfaces installateur/package/Docker. Les pushes sur `main`, y compris les commits de fusion, n’imposent pas le chemin complet ; lorsque la logique changed-scope demanderait une couverture complète sur un push, le workflow conserve le smoke Docker rapide et laisse le smoke d’installation complet à la validation nocturne ou de release. Le smoke lent d’installation globale Bun image-provider est contrôlé séparément par `run_bun_global_install_smoke` ; il s’exécute sur la planification nocturne et depuis le workflow de vérifications de release, et les déclenchements manuels de `install-smoke` peuvent l’inclure, mais les pull requests et les pushes sur `main` ne l’exécutent pas. Les tests Docker QR et installateur conservent leurs propres Dockerfiles centrés installation. En local, `test:docker:all` préconstruit une image partagée de test live et une image partagée d’application construite `scripts/e2e/Dockerfile`, puis exécute en parallèle les voies smoke live/E2E avec `OPENCLAW_SKIP_DOCKER_BUILD=1` ; ajustez le parallélisme par défaut du pool principal de 8 avec `OPENCLAW_DOCKER_ALL_PARALLELISM` et le parallélisme du pool de fin sensible au fournisseur de 8 avec `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. L’agrégat local arrête par défaut de planifier de nouvelles voies mutualisées après le premier échec, et chaque voie dispose d’un délai de 120 minutes, modifiable via `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le workflow live/E2E réutilisable reproduit le modèle à image partagée en construisant et publiant une image Docker E2E GHCR taguée par SHA avant la matrice Docker, puis en exécutant la matrice avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Le workflow live/E2E planifié exécute chaque jour la suite Docker complète du chemin de release. La matrice complète d’update/canal inclus reste manuelle/full-suite car elle effectue des passes répétées réelles de mise à jour npm et de réparation doctor.
Les modifications du workflow CI valident le graphe CI Node ainsi que le lint des workflows, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces lanes de plateforme restent limitées aux changements de sources propres à la plateforme.
Les vérifications Node Windows sont limitées aux wrappers spécifiques à Windows pour les processus et chemins, aux helpers npm/pnpm/UI runner, à la configuration du gestionnaire de paquets et aux surfaces de workflow CI qui exécutent cette lane ; les changements sans rapport dans le code source, les plugins, le smoke d’installation et les tests uniquement restent sur les lanes Node Linux afin de ne pas réserver un worker Windows 16 vCPU pour une couverture déjà exercée par les shards de tests normaux.
Le workflow séparé `install-smoke` réutilise le même script de portée via son propre job `preflight`. Il scinde la couverture smoke entre `run_fast_install_smoke` et `run_full_install_smoke`. Les pull requests exécutent le chemin rapide pour les surfaces Docker/package, les changements de package/manifeste de plugins groupés et les surfaces cœur plugin/channel/gateway/Plugin SDK que les jobs Docker smoke exercent. Les changements limités au code source de plugins groupés, les modifications de tests uniquement et les modifications de documentation uniquement ne réservent pas de workers Docker. Le chemin rapide construit une seule fois l’image du Dockerfile racine, vérifie la CLI, exécute l’e2e container gateway-network, vérifie un build arg d’extension groupée et exécute le profil Docker de plugin groupé borné avec un timeout de commande de 120 secondes. Le chemin complet conserve l’installation du package QR ainsi que la couverture installer Docker/update pour les exécutions planifiées nocturnes, les déclenchements manuels, les vérifications de release par workflow-call et les pull requests qui touchent réellement les surfaces installer/package/Docker. Les pushs sur `main`, y compris les merge commits, ne forcent pas le chemin complet ; lorsque la logique changed-scope demanderait une couverture complète sur un push, le workflow conserve le Docker smoke rapide et laisse le smoke d’installation complet à la validation nocturne ou de release. Le smoke lent du fournisseur d’images d’installation globale Bun est contrôlé séparément par `run_bun_global_install_smoke` ; il s’exécute selon la planification nocturne et depuis le workflow de vérifications de release, et les déclenchements manuels de `install-smoke` peuvent l’activer, mais les pull requests et les pushs sur `main` ne l’exécutent pas. Les tests Docker QR et installer conservent leurs propres Dockerfiles orientés installation. En local, `test:docker:all` préconstruit une image partagée pour les tests live et une image applicative partagée construite depuis `scripts/e2e/Dockerfile`, puis exécute en parallèle les lanes smoke live/E2E avec `OPENCLAW_SKIP_DOCKER_BUILD=1` ; réglez la concurrence par défaut du pool principal de 8 avec `OPENCLAW_DOCKER_ALL_PARALLELISM` et la concurrence du pool final sensible au fournisseur de 8 avec `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Le démarrage des lanes est échelonné de 2 secondes par défaut pour éviter les tempêtes locales de création du daemon Docker ; remplacez cela avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` ou une autre valeur en millisecondes. L’agrégat local cesse de planifier de nouvelles lanes groupées après le premier échec par défaut, et chaque lane a un timeout de 120 minutes remplaçable via `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le workflow réutilisable live/E2E reproduit le modèle d’image partagée en construisant et en poussant une image Docker E2E GHCR taguée par SHA avant la matrice Docker, puis en exécutant la matrice avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Le workflow planifié live/E2E exécute chaque jour la suite Docker complète du chemin de release. La matrice complète de mise à jour groupée/canal reste manuelle/suite complète, car elle effectue des passages répétés réels de mise à jour npm et de réparation doctor.
La logique locale des voies modifiées se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette barrière locale est plus stricte sur les limites d’architecture que la large portée de plateforme en CI : les changements de production du cœur exécutent le typecheck prod du cœur plus les tests du cœur, les changements uniquement de tests du cœur n’exécutent que le typecheck/tests du cœur, les changements de production d’extension exécutent le typecheck prod des extensions plus les tests d’extensions, et les changements uniquement de tests d’extensions n’exécutent que le typecheck/tests d’extensions. Les changements du Plugin SDK public ou du plugin-contract étendent la validation aux extensions car celles-ci dépendent de ces contrats du cœur. Les hausses de version limitées aux métadonnées de release exécutent des vérifications ciblées de version/configuration/dépendances racine. Les changements inconnus de racine/configuration échouent prudemment vers toutes les voies.
La logique locale des lanes modifiées se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte locale est plus stricte sur les limites d’architecture que la large portée CI par plateforme : les changements de production du cœur exécutent le typecheck prod du cœur plus les tests du cœur, les changements limités aux tests du cœur n’exécutent que le typecheck/tests du cœur, les changements de production des extensions exécutent le typecheck prod des extensions plus les tests des extensions, et les changements limités aux tests des extensions n’exécutent que le typecheck/tests des extensions. Les changements du Plugin SDK public ou du plugin-contract étendent la validation aux extensions, car les extensions dépendent de ces contrats du cœur. Les incréments de version limités aux métadonnées de release exécutent des vérifications ciblées de version/configuration/dépendances racine. Les changements inconnus à la racine ou dans la configuration échouent de manière sécurisée vers toutes les lanes.
Sur les pushes, la matrice `checks` ajoute la voie `compat-node22`, réservée aux pushes. Sur les pull requests, cette voie est ignorée et la matrice reste focalisée sur les voies normales de test/canal.
Sur les pushs, la matrice `checks` ajoute la lane `compat-node22`, uniquement sur push. Sur les pull requests, cette lane est ignorée et la matrice reste concentrée sur les lanes normales de test/canal.
Les familles de tests Node les plus lentes sont fractionnées ou équilibrées afin que chaque job reste compact sans sur-réserver les runners : les contrats de canal s’exécutent en trois shards pondérés, les tests de plugins inclus sont équilibrés sur six workers d’extension, les petites voies unitaires du cœur sont appariées, auto-reply s’exécute sur trois workers équilibrés au lieu de six minuscules workers, et les configurations agentiques gateway/plugin sont réparties sur les jobs Node agentiques existants réservés au code source au lieu d’attendre les artefacts construits. Les tests généraux de navigateur, QA, médias et plugins divers utilisent leurs configurations Vitest dédiées plutôt que le fourre-tout partagé des plugins. Les jobs de shards d’extensions exécutent les groupes de configuration de plugins en série avec un seul worker Vitest et un heap Node plus grand afin que les lots de plugins lourds en imports ne surchargent pas les petits runners CI. La large voie agents utilise l’ordonnanceur parallèle par fichiers Vitest partagé, car elle est dominée par les imports/la planification plutôt que par un seul fichier de test lent. `runtime-config` s’exécute avec le shard infra core-runtime pour éviter que le shard runtime partagé ne porte la fin de queue. `check-additional` conserve ensemble le travail de compilation/canary des limites de package et sépare l’architecture de topologie runtime de la couverture gateway watch ; le shard des gardes de limites exécute ses petits gardes indépendants en concurrence dans un seul job. Gateway watch, les tests de canaux et le shard core support-boundary s’exécutent en concurrence dans `build-artifacts` après que `dist/` et `dist-runtime/` sont déjà construits, ce qui conserve leurs anciens noms de vérification comme jobs légers de vérification tout en évitant deux workers Blacksmith supplémentaires et une seconde file d’attente de consommateurs d’artefacts.
Les familles de tests Node les plus lentes sont divisées ou équilibrées afin que chaque job reste petit sans sur-réserver les runners : les contrats de canaux s’exécutent en trois shards pondérés, les tests de plugins groupés sont équilibrés sur six workers d’extension, les petites lanes unitaires du cœur sont appariées, auto-reply s’exécute sur trois workers équilibrés au lieu de six petits workers, et les configurations agentiques gateway/plugin sont réparties sur les jobs Node agentiques existants limités au code source au lieu d’attendre les artefacts construits. Les tests larges de navigateur, QA, médias et plugins divers utilisent leurs configurations Vitest dédiées au lieu du fourre-tout partagé pour plugins. Les jobs de shards d’extension exécutent les groupes de configuration de plugins en série avec un seul worker Vitest et un tas Node plus grand afin que les lots de plugins lourds à l’import ne surchargent pas les petits runners CI. La large lane agents utilise le planificateur parallèle par fichier Vitest partagé, car elle est dominée par les imports et l’ordonnancement plutôt que par un seul fichier de test lent. `runtime-config` s’exécute avec le shard infra core-runtime afin d’éviter que le shard runtime partagé ne porte la traîne. `check-additional` conserve ensemble le travail de compilation/canary sur les limites de package et sépare l’architecture de topologie du runtime de la couverture gateway watch ; le shard boundary guard exécute ses petits gardes indépendants en concurrence à l’intérieur d’un même job. Gateway watch, les tests de canaux et le shard core support-boundary s’exécutent en concurrence dans `build-artifacts` une fois que `dist/` et `dist-runtime/` sont déjà construits, en conservant leurs anciens noms de vérification comme jobs vérificateurs légers tout en évitant deux workers Blacksmith supplémentaires et une seconde file d’attente de consommateurs d’artefacts.
Le CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. La variante third-party n’a ni source set ni manifeste séparés ; sa lane de tests unitaires compile tout de même cette variante avec les flags BuildConfig SMS/call-log, tout en évitant un job de packaging APK debug dupliqué sur chaque push pertinent pour Android.
`extension-fast` est réservé aux PR car les exécutions sur push exécutent déjà les shards complets de plugins groupés. Cela permet de conserver un retour rapide sur les plugins modifiés pendant les revues sans réserver un worker Blacksmith supplémentaire sur `main` pour une couverture déjà présente dans `checks-node-extensions`.
La CI Android exécute `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. La variante third-party n’a ni source set ni manifeste séparés ; sa voie de tests unitaires compile tout de même cette variante avec les drapeaux BuildConfig SMS/journal d’appels, tout en évitant un job de packaging APK debug dupliqué à chaque push pertinent pour Android.
`extension-fast` est réservé aux PR, car les exécutions sur push exécutent déjà les shards complets des plugins inclus. Cela permet un retour rapide sur les plugins modifiés pendant les revues sans réserver un worker Blacksmith supplémentaire sur `main` pour une couverture déjà présente dans `checks-node-extensions`.
GitHub peut marquer les jobs remplacés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou la même ref `main`. Considérez cela comme du bruit CI, sauf si l’exécution la plus récente pour cette même ref échoue également. Les vérifications agrégées de shards utilisent `!cancelled() && always()` afin qu’elles signalent toujours les échecs normaux de shards, sans toutefois se mettre en file d’attente après que l’ensemble du workflow a déjà été remplacé.
La clé de concurrence CI est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file d’attente ne puisse pas bloquer indéfiniment les nouvelles exécutions sur main.
GitHub peut marquer les jobs remplacés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou la même référence `main`. Considérez cela comme du bruit CI, sauf si l’exécution la plus récente pour cette même référence échoue également. Les vérifications agrégées de shards utilisent `!cancelled() && always()` afin de continuer à signaler les échecs normaux des shards, sans toutefois se mettre en file d’attente lorsque l’ensemble du workflow a déjà été remplacé.
La clé de concurrence CI est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file d’attente ne puisse pas bloquer indéfiniment les nouvelles exécutions sur `main`.
## Runners
| Runner | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, jobs de sécurité rapides et agrégats (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/plugins inclus, vérifications shardées des contrats de canaux, shards `check` sauf lint, shards et agrégats `check-additional`, vérificateurs agrégés des tests Node, vérifications docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight install-smoke utilise aussi Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse entrer en file plus tôt |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de tests Node Linux, shards de tests de plugins inclus, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, qui reste suffisamment sensible au CPU pour que 8 vCPU coûtent plus qu’ils ne rapportent ; builds Docker install-smoke, où le coût en temps de file d’attente de 32 vCPU dépassait le gain |
| `ubuntu-24.04` | `preflight`, jobs et agrégats de sécurité rapides (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides protocol/contract/groupées, vérifications shardées des contrats de canaux, shards `check` sauf lint, shards et agrégats `check-additional`, vérificateurs agrégés des tests Node, vérifications docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight d’install-smoke utilise également Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse se mettre en file d’attente plus tôt |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de tests Node Linux, shards de tests de plugins groupés, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, qui reste suffisamment sensible au CPU pour que 8 vCPU coûtent plus qu’ils ne font gagner ; builds Docker d’install-smoke, où le coût en temps de file d’attente de 32 vCPU dépassait le gain obtenu |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks reviennent à `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks reviennent à `macos-latest` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks reviennent sur `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks reviennent sur `macos-latest` |
## Équivalents locaux
```bash
pnpm changed:lanes # inspecter le classificateur local des voies modifiées pour origin/main...HEAD
pnpm check:changed # barrière locale intelligente : typecheck/lint/tests modifiés par voie de limite
pnpm check # barrière locale rapide : tsgo production + lint shardé + gardes rapides en parallèle
pnpm changed:lanes # inspecter le classificateur local des lanes modifiées pour origin/main...HEAD
pnpm check:changed # porte locale intelligente : typecheck/lint/tests modifiés par lane de limite
pnpm check # porte locale rapide : tsgo de production + lint shardé + gardes rapides en parallèle
pnpm check:test-types
pnpm check:timed # même barrière avec temps par étape
pnpm check:timed # même porte avec minutage par étape
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # tests vitest
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # format + lint docs + liens cassés
pnpm build # construire dist lorsque les voies CI artifact/build-smoke comptent
node scripts/ci-run-timings.mjs <run-id> # résumer le temps mur, le temps de file d’attente et les jobs les plus lents
node scripts/ci-run-timings.mjs --recent 10 # comparer les exécutions CI réussies récentes sur main
pnpm check:docs # format docs + lint + liens cassés
pnpm build # construire dist lorsque les lanes CI artifact/build-smoke sont pertinentes
node scripts/ci-run-timings.mjs <run-id> # résumer le temps total, le temps de file d’attente et les jobs les plus lents
node scripts/ci-run-timings.mjs --recent 10 # comparer les exécutions CI récentes réussies sur main
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
```
## Articles connexes
## Liens connexes
- [Vue d’ensemble de l’installation](/fr/install)
- [Canaux de release](/fr/install/development-channels)

414
docs/fr/gateway/troubleshooting.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Le hub de dépannage vous a orienté ici pour un diagnostic plus approfondi
- Le hub de dépannage vous a dirigé ici pour un diagnostic plus approfondi
- Vous avez besoin de sections de runbook stables basées sur les symptômes avec des commandes exactes
summary: Runbook de dépannage approfondi pour le gateway, les canaux, l’automatisation, les Node et le navigateur
summary: Guide de dépannage approfondi pour Gateway, les canaux, l’automatisation, les nœuds et le navigateur
title: Dépannage
x-i18n:
generated_at: "2026-04-24T07:13:18Z"
generated_at: "2026-04-24T08:57:12Z"
model: gpt-5.4
provider: openai
source_hash: 32c4cbbbe8b1cd5eaca34503f4a363d3fa2650e491f83455958eb5725f9d50c5
source_hash: 20066bdab03f05304b3a620fbadc38e4dc74b740da151c58673dcf5196e5f1e1
source_path: gateway/troubleshooting.md
workflow: 15
---
# Dépannage Gateway
# Dépannage de Gateway
Cette page est le runbook approfondi.
Commencez par [/help/troubleshooting](/fr/help/troubleshooting) si vous souhaitez d’abord le flux de tri rapide.
Commencez par [/help/troubleshooting](/fr/help/troubleshooting) si vous voulez d’abord le flux de triage rapide.
## Échelle de commandes
Exécutez d’abord celles-ci, dans cet ordre :
Exécutez d’abord celles-ci, dans cet ordre :
```bash
openclaw status
@ -30,16 +30,16 @@ openclaw doctor
openclaw channels status --probe
```
Signaux attendus en bonne santé :
Signaux attendus en bonne santé :
- `openclaw gateway status` affiche `Runtime: running`, `Connectivity probe: ok`, et une ligne `Capability: ...`.
- `openclaw doctor` ne signale aucun problème bloquant de configuration/service.
- `openclaw gateway status` affiche `Runtime: running`, `Connectivity probe: ok` et une ligne `Capability: ...`.
- `openclaw doctor` ne signale aucun problème bloquant de configuration ou de service.
- `openclaw channels status --probe` affiche l’état de transport en direct par compte et,
lorsque pris en charge, des résultats de sonde/audit tels que `works` ou `audit ok`.
là où c’est pris en charge, des résultats de sonde/audit tels que `works` ou `audit ok`.
## Anthropic 429 usage supplémentaire requis pour un contexte long
## Utilisation supplémentaire Anthropic 429 requise pour le contexte long
Utilisez cette section lorsque les journaux/erreurs incluent :
Utilisez ceci lorsque les journaux/erreurs incluent :
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
```bash
@ -48,19 +48,19 @@ openclaw models status
openclaw config get agents.defaults.models
```
Recherchez :
Recherchez :
- Le modèle Anthropic Opus/Sonnet sélectionné a `params.context1m: true`.
- L’identifiant Anthropic actuel n’est pas éligible à l’utilisation en contexte long.
- L’identifiant Anthropic actuel n’est pas éligible à l’utilisation du contexte long.
- Les requêtes échouent uniquement sur les longues sessions/exécutions de modèle qui nécessitent le chemin bêta 1M.
Options de correction :
Options de correction :
1. Désactivez `context1m` pour ce modèle afin de revenir à la fenêtre de contexte normale.
2. Utilisez un identifiant Anthropic éligible aux requêtes en contexte long, ou passez à une clé API Anthropic.
3. Configurez des modèles de repli afin que les exécutions se poursuivent lorsque les requêtes Anthropic en contexte long sont rejetées.
2. Utilisez un identifiant Anthropic éligible aux requêtes de contexte long, ou passez à une clé API Anthropic.
3. Configurez des modèles de secours afin que les exécutions continuent lorsque les requêtes Anthropic de contexte long sont rejetées.
Lié :
Liens associés :
- [/providers/anthropic](/fr/providers/anthropic)
- [/reference/token-use](/fr/reference/token-use)
@ -68,11 +68,11 @@ Lié :
## Le backend local compatible OpenAI réussit les sondes directes mais les exécutions d’agent échouent
Utilisez cette section lorsque :
Utilisez ceci lorsque :
- `curl ... /v1/models` fonctionne
- les petits appels directs `/v1/chat/completions` fonctionnent
- les exécutions de modèle OpenClaw échouent uniquement sur des tours d’agent normaux
- les petits appels directs à `/v1/chat/completions` fonctionnent
- les exécutions de modèle OpenClaw échouent uniquement lors des tours normaux de l’agent
```bash
curl http://127.0.0.1:1234/v1/models
@ -83,36 +83,38 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```
Recherchez :
Recherchez :
- les petits appels directs réussissent, mais les exécutions OpenClaw échouent uniquement sur les prompts plus volumineux
- des erreurs backend concernant `messages[].content` qui attend une chaîne
- des plantages backend qui apparaissent uniquement avec des nombres plus élevés de jetons de prompt ou des prompts complets du runtime d’agent
- les petits appels directs réussissent, mais les exécutions OpenClaw échouent uniquement sur des prompts plus volumineux
- des erreurs du backend indiquant que `messages[].content` attend une chaîne
- des plantages du backend qui apparaissent uniquement avec un plus grand nombre de tokens de prompt ou avec les prompts complets du runtime de l’agent
Signatures courantes :
Signatures courantes :
- `messages[...].content: invalid type: sequence, expected a string` → le backend
rejette les parties de contenu structurées de Chat Completions. Correction : définissez
rejette les parties de contenu structurées de Chat Completions. Correctif : définissez
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
- les petites requêtes directes réussissent, mais les exécutions d’agent OpenClaw échouent avec des plantages backend/modèle
(par exemple Gemma sur certaines builds `inferrs`) → le transport OpenClaw est
probablement déjà correct ; c’est le backend qui échoue sur la forme plus volumineuse du prompt
du runtime d’agent.
- les échecs diminuent après désactivation des outils mais ne disparaissent pas → les schémas d’outils
participaient à la pression, mais le problème restant est toujours une limitation de capacité du modèle/serveur en amont ou un bogue du backend.
- les petites requêtes directes réussissent, mais les exécutions de l’agent OpenClaw échouent avec des plantages du backend/modèle
(par exemple Gemma sur certaines versions de `inferrs`) → le transport OpenClaw est
probablement déjà correct ; c’est le backend qui échoue sur la forme du prompt
plus volumineux du runtime de l’agent.
- les échecs diminuent après désactivation des outils mais ne disparaissent pas → les schémas d’outils faisaient
partie de la pression, mais le problème restant est toujours en amont : capacité du modèle/serveur
ou bug du backend.
Options de correction :
Options de correction :
1. Définissez `compat.requiresStringContent: true` pour les backends Chat Completions qui n’acceptent que des chaînes.
2. Définissez `compat.supportsTools: false` pour les modèles/backends qui ne peuvent pas gérer
de manière fiable la surface de schéma d’outils d’OpenClaw.
3. Réduisez autant que possible la pression du prompt : bootstrap d’espace de travail plus petit, historique
de session plus court, modèle local plus léger ou backend avec meilleure prise en charge du contexte long.
4. Si les petites requêtes directes continuent de réussir alors que les tours d’agent OpenClaw plantent toujours
dans le backend, traitez cela comme une limitation du serveur/modèle en amont et déposez
une reproduction là-bas avec la forme de charge utile acceptée.
3. Réduisez la pression du prompt quand c’est possible : initialisation d’espace de travail plus petite, historique
de session plus court, modèle local plus léger, ou backend avec un meilleur support
du contexte long.
4. Si les petites requêtes directes continuent de réussir tandis que les tours de l’agent OpenClaw plantent encore
dans le backend, traitez cela comme une limitation du serveur/modèle en amont et ouvrez
un rapport reproductible là-bas avec la forme de payload acceptée.
Lié :
Liens associés :
- [/gateway/local-models](/fr/gateway/local-models)
- [/gateway/configuration](/fr/gateway/configuration)
@ -120,7 +122,7 @@ Lié :
## Aucune réponse
Si les canaux sont actifs mais que rien ne répond, vérifiez le routage et la politique avant de reconnecter quoi que ce soit.
Si les canaux sont actifs mais que rien ne répond, vérifiez le routage et la stratégie avant de reconnecter quoi que ce soit.
```bash
openclaw status
@ -130,27 +132,27 @@ openclaw config get channels
openclaw logs --follow
```
Recherchez :
Recherchez :
- Appairage en attente pour les expéditeurs de messages privés.
- Contrôle des mentions de groupe (`requireMention`, `mentionPatterns`).
- Incohérences de liste d’autorisation canal/groupe.
- Pairing en attente pour les expéditeurs de message direct.
- Filtrage des mentions de groupe (`requireMention`, `mentionPatterns`).
- Incohérences d’allowlist de canal/groupe.
Signatures courantes :
Signatures courantes :
- `drop guild message (mention required` → message de groupe ignoré jusqu’à mention.
- `pairing request` → l’expéditeur doit être approuvé.
- `blocked` / `allowlist` → l’expéditeur/le canal a été filtré par la politique.
- `pairing request` → l’expéditeur a besoin d’une approbation.
- `blocked` / `allowlist` → l’expéditeur/canal a été filtré par la stratégie.
Lié :
Liens associés :
- [/channels/troubleshooting](/fr/channels/troubleshooting)
- [/channels/pairing](/fr/channels/pairing)
- [/channels/groups](/fr/channels/groups)
## Connectivité de l’interface de contrôle du tableau de bord
## Connectivité de l’interface dashboard/control UI
Lorsque le tableau de bord/l’interface de contrôle ne se connecte pas, validez l’URL, le mode d’authentification et les hypothèses de contexte sécurisé.
Lorsque l’interface dashboard/control UI ne se connecte pas, validez l’URL, le mode d’authentification et les hypothèses de contexte sécurisé.
```bash
openclaw gateway status
@ -160,48 +162,51 @@ openclaw doctor
openclaw gateway status --json
```
Recherchez :
Recherchez :
- URL de sonde et URL du tableau de bord correctes.
- Incompatibilité de mode d’authentification/jeton entre le client et le gateway.
- Utilisation HTTP là où une identité d’appareil est requise.
- URL de sonde et URL du dashboard correctes.
- Incohérence de mode d’authentification/de jeton entre le client et Gateway.
- Utilisation de HTTP là où l’identité de l’appareil est requise.
Signatures courantes :
Signatures courantes :
- `device identity required` → contexte non sécurisé ou authentification d’appareil manquante.
- `origin not allowed` → `Origin` du navigateur n’est pas dans `gateway.controlUi.allowedOrigins`
(ou vous vous connectez depuis une origine navigateur non-loopback sans liste d’autorisation
explicite).
- `device nonce required` / `device nonce mismatch` → le client n’achève pas le
flux d’authentification d’appareil basé sur challenge (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → le client a signé la mauvaise
charge utile (ou un horodatage périmé) pour la poignée de main actuelle.
- `AUTH_TOKEN_MISMATCH` avec `canRetryWithDeviceToken=true` → le client peut effectuer une nouvelle tentative de confiance avec un jeton d’appareil mis en cache.
- Cette nouvelle tentative avec jeton mis en cache réutilise l’ensemble de scopes mis en cache stocké avec le jeton d’appareil appairé. Les appelants avec `deviceToken` explicite / `scopes` explicites conservent à la place l’ensemble de scopes demandé.
(ou vous vous connectez depuis une origine de navigateur non loopback sans
allowlist explicite).
- `device nonce required` / `device nonce mismatch` → le client ne termine pas
le flux d’authentification d’appareil basé sur challenge (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → le client a signé le mauvais
payload (ou un horodatage obsolète) pour la négociation en cours.
- `AUTH_TOKEN_MISMATCH` avec `canRetryWithDeviceToken=true` → le client peut faire une nouvelle tentative approuvée avec le jeton d’appareil en cache.
- Cette nouvelle tentative avec jeton en cache réutilise l’ensemble des portées en cache stocké avec le
jeton d’appareil appairé. Les appelants avec `deviceToken` explicite / `scopes` explicites conservent
à la place l’ensemble de portées qu’ils ont demandé.
- En dehors de ce chemin de nouvelle tentative, la priorité d’authentification de connexion est d’abord
jeton/mot de passe partagé explicite, puis `deviceToken` explicite, puis jeton d’appareil stocké,
puis jeton bootstrap.
le jeton partagé/mot de passe explicite, puis `deviceToken` explicite, puis le jeton d’appareil stocké,
puis le jeton d’amorçage.
- Sur le chemin asynchrone Tailscale Serve Control UI, les tentatives échouées pour le même
`{scope, ip}` sont sérialisées avant que le limiteur n’enregistre l’échec. Deux mauvaises nouvelles tentatives concurrentes du même client peuvent donc produire `retry later`
sur la seconde tentative au lieu de deux incompatibilités simples.
`{scope, ip}` sont sérialisées avant que le limiteur n’enregistre l’échec. Deux mauvaises
tentatives concurrentes du même client peuvent donc produire `retry later`
sur la seconde tentative au lieu de deux simples incohérences.
- `too many failed authentication attempts (retry later)` depuis un client loopback d’origine navigateur
→ les échecs répétés depuis cette même `Origin` normalisée sont temporairement
bloqués ; une autre origine localhost utilise un compartiment distinct.
- `unauthorized` répété après cette nouvelle tentative → dérive du jeton partagé/jeton d’appareil ; actualisez la configuration du jeton et réapprouvez/faites tourner le jeton d’appareil si nécessaire.
- `gateway connect failed:` → mauvaise cible hôte/port/url.
→ les échecs répétés depuis cette même `Origin` normalisée sont temporairement bloqués ;
une autre origine localhost utilise un compartiment distinct.
- `unauthorized` répété après cette nouvelle tentative → dérive du jeton partagé/du jeton d’appareil ; actualisez la configuration du jeton et réapprouvez/faites pivoter le jeton d’appareil si nécessaire.
- `gateway connect failed:` → cible d’hôte/port/URL incorrecte.
### Correspondance rapide des codes de détail d’authentification
### Carte rapide des codes de détail d’authentification
Utilisez `error.details.code` de la réponse `connect` en échec pour choisir l’action suivante :
Utilisez `error.details.code` de la réponse `connect` en échec pour choisir l’action suivante :
| Detail code | Signification | Action recommandée |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Le client n’a pas envoyé un jeton partagé requis. | Collez/définissez le jeton dans le client et réessayez. Pour les chemins du tableau de bord : `openclaw config get gateway.auth.token` puis collez-le dans les réglages de l’interface de contrôle. |
| `AUTH_TOKEN_MISMATCH` | Le jeton partagé ne correspond pas au jeton d’authentification du gateway. | Si `canRetryWithDeviceToken=true`, autorisez une nouvelle tentative de confiance. Les nouvelles tentatives avec jeton mis en cache réutilisent les scopes approuvés stockés ; les appelants avec `deviceToken` / `scopes` explicites conservent les scopes demandés. Si cela échoue encore, exécutez la [liste de contrôle de récupération de dérive de jeton](/fr/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Le jeton par appareil mis en cache est obsolète ou révoqué. | Faites tourner/réapprouvez le jeton d’appareil à l’aide de la [CLI devices](/fr/cli/devices), puis reconnectez-vous. |
| `PAIRING_REQUIRED` | L’identité d’appareil nécessite une approbation. Vérifiez `error.details.reason` pour `not-paired`, `scope-upgrade`, `role-upgrade`, ou `metadata-upgrade`, et utilisez `requestId` / `remediationHint` lorsqu’ils sont présents. | Approuvez la demande en attente : `openclaw devices list` puis `openclaw devices approve <requestId>`. Les montées de niveau de scope/rôle utilisent le même flux après examen de l’accès demandé. |
| Code de détail | Signification | Action recommandée |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Le client n’a pas envoyé de jeton partagé requis. | Collez/définissez le jeton dans le client et réessayez. Pour les chemins dashboard : `openclaw config get gateway.auth.token` puis collez-le dans les paramètres de Control UI. |
| `AUTH_TOKEN_MISMATCH` | Le jeton partagé ne correspond pas au jeton d’authentification de Gateway. | Si `canRetryWithDeviceToken=true`, autorisez une nouvelle tentative approuvée. Les nouvelles tentatives avec jeton en cache réutilisent les portées approuvées stockées ; les appelants avec `deviceToken` / `scopes` explicites conservent les portées demandées. Si l’échec persiste, exécutez la [checklist de récupération de dérive de jeton](/fr/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Le jeton par appareil en cache est obsolète ou révoqué. | Faites pivoter/réapprouvez le jeton d’appareil avec la [CLI des appareils](/fr/cli/devices), puis reconnectez-vous. |
| `PAIRING_REQUIRED` | L’identité de l’appareil nécessite une approbation. Vérifiez `error.details.reason` pour `not-paired`, `scope-upgrade`, `role-upgrade` ou `metadata-upgrade`, et utilisez `requestId` / `remediationHint` lorsqu’ils sont présents. | Approuvez la demande en attente : `openclaw devices list` puis `openclaw devices approve <requestId>`. Les mises à niveau de portée/rôle utilisent le même flux après examen de l’accès demandé. |
Vérification de migration de l’authentification d’appareil v2 :
Vérification de migration auth appareil v2 :
```bash
openclaw --version
@ -209,29 +214,30 @@ openclaw doctor
openclaw gateway status
```
Si les journaux montrent des erreurs de nonce/signature, mettez à jour le client qui se connecte et vérifiez qu’il :
Si les journaux affichent des erreurs de nonce/signature, mettez à jour le client qui se connecte et vérifiez qu’il :
1. attend `connect.challenge`
2. signe la charge utile liée au challenge
2. signe le payload lié au challenge
3. envoie `connect.params.device.nonce` avec le même nonce de challenge
Si `openclaw devices rotate` / `revoke` / `remove` est refusé de manière inattendue :
Si `openclaw devices rotate` / `revoke` / `remove` est refusé de façon inattendue :
- les sessions avec jeton d’appareil appairé ne peuvent gérer que **leur propre** appareil, sauf si l’appelant possède aussi `operator.admin`
- `openclaw devices rotate --scope ...` ne peut demander que des scopes operator
que la session appelante détient déjà
- les sessions de jeton d’appareil appairé peuvent gérer uniquement **leur propre** appareil sauf si
l’appelant possède aussi `operator.admin`
- `openclaw devices rotate --scope ...` peut uniquement demander des portées opérateur que
la session appelante détient déjà
Lié :
Liens associés :
- [/web/control-ui](/fr/web/control-ui)
- [/gateway/configuration](/fr/gateway/configuration) (modes d’authentification du gateway)
- [/gateway/configuration](/fr/gateway/configuration) (modes d’authentification de Gateway)
- [/gateway/trusted-proxy-auth](/fr/gateway/trusted-proxy-auth)
- [/gateway/remote](/fr/gateway/remote)
- [/cli/devices](/fr/cli/devices)
## Service Gateway non exécuté
## Le service Gateway n’est pas en cours d’exécution
Utilisez cette section lorsque le service est installé mais que le processus ne reste pas actif.
Utilisez ceci lorsque le service est installé mais que le processus ne reste pas actif.
```bash
openclaw gateway status
@ -241,30 +247,30 @@ openclaw doctor
openclaw gateway status --deep # analyse aussi les services au niveau système
```
Recherchez :
Recherchez :
- `Runtime: stopped` avec des indications de sortie.
- Incompatibilité de configuration du service (`Config (cli)` vs `Config (service)`).
- Conflits de port/écouteur.
- `Runtime: stopped` avec des indices de sortie.
- Incohérence de configuration du service (`Config (cli)` vs `Config (service)`).
- Conflits de port/d’écoute.
- Installations launchd/systemd/schtasks supplémentaires lorsque `--deep` est utilisé.
- Indications de nettoyage `Other gateway-like services detected (best effort)`.
- Indices de nettoyage `Other gateway-like services detected (best effort)`.
Signatures courantes :
Signatures courantes :
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → le mode gateway local n’est pas activé, ou le fichier de configuration a été écrasé et a perdu `gateway.mode`. Correction : définissez `gateway.mode="local"` dans votre configuration, ou relancez `openclaw onboard --mode local` / `openclaw setup` pour réappliquer la configuration attendue du mode local. Si vous exécutez OpenClaw via Podman, le chemin de configuration par défaut est `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → liaison non-loopback sans chemin d’authentification gateway valide (jeton/mot de passe, ou trusted-proxy là où il est configuré).
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → le mode Gateway local n’est pas activé, ou le fichier de configuration a été écrasé et a perdu `gateway.mode`. Correctif : définissez `gateway.mode="local"` dans votre configuration, ou relancez `openclaw onboard --mode local` / `openclaw setup` pour réappliquer la configuration attendue en mode local. Si vous exécutez OpenClaw via Podman, le chemin de configuration par défaut est `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → liaison non loopback sans chemin d’authentification Gateway valide (jeton/mot de passe, ou trusted-proxy lorsqu’il est configuré).
- `another gateway instance is already listening` / `EADDRINUSE` → conflit de port.
- `Other gateway-like services detected (best effort)` → des unités launchd/systemd/schtasks obsolètes ou parallèles existent. La plupart des configurations devraient conserver un seul gateway par machine ; si vous avez réellement besoin de plus d’un, isolez ports + configuration/état/espace de travail. Voir [/gateway#multiple-gateways-same-host](/fr/gateway#multiple-gateways-same-host).
- `Other gateway-like services detected (best effort)` → des unités launchd/systemd/schtasks obsolètes ou parallèles existent. La plupart des configurations doivent conserver une seule Gateway par machine ; si vous en avez vraiment besoin de plusieurs, isolez les ports + la configuration/l’état/l’espace de travail. Voir [/gateway#multiple-gateways-same-host](/fr/gateway#multiple-gateways-same-host).
Lié :
Liens associés :
- [/gateway/background-process](/fr/gateway/background-process)
- [/gateway/configuration](/fr/gateway/configuration)
- [/gateway/doctor](/fr/gateway/doctor)
## Le Gateway a restauré la dernière configuration valide connue
## Gateway a restauré la configuration du dernier état valide connu
Utilisez cette section lorsque le Gateway démarre, mais que les journaux indiquent qu’il a restauré `openclaw.json`.
Utilisez ceci lorsque Gateway démarre, mais que les journaux indiquent qu’elle a restauré `openclaw.json`.
```bash
openclaw logs --follow
@ -273,22 +279,22 @@ openclaw config validate
openclaw doctor
```
Recherchez :
Recherchez :
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- Un fichier horodaté `openclaw.json.clobbered.*` à côté de la configuration active
- Un événement système de l’agent principal qui commence par `Config recovery warning`
- Un événement système du main-agent qui commence par `Config recovery warning`
Ce qui s’est passé :
Ce qui s’est passé :
- La configuration rejetée n’a pas passé la validation au démarrage ou lors d’un rechargement à chaud.
- La configuration rejetée n’a pas passé la validation au démarrage ou lors du rechargement à chaud.
- OpenClaw a conservé la charge utile rejetée sous `.clobbered.*`.
- La configuration active a été restaurée à partir de la dernière copie valide connue.
- Le prochain tour de l’agent principal reçoit un avertissement lui indiquant de ne pas réécrire aveuglément la configuration rejetée.
- Le prochain tour du main-agent reçoit un avertissement pour ne pas réécrire aveuglément la configuration rejetée.
Inspecter et réparer :
Inspecter et corriger :
```bash
CONFIG="$(openclaw config file)"
@ -298,31 +304,31 @@ openclaw config validate
openclaw doctor
```
Signatures courantes :
Signatures courantes :
- `.clobbered.*` existe → une modification directe externe ou une lecture au démarrage a été restaurée.
- `.rejected.*` existe → une écriture de configuration gérée par OpenClaw a échoué aux vérifications de schéma ou d’écrasement avant validation.
- `Config write rejected:` → l’écriture a tenté de supprimer une forme requise, de réduire brutalement la taille du fichier, ou de persister une configuration invalide.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, ou `size-drop-vs-last-good:*` → le démarrage a traité le fichier actuel comme écrasé parce qu’il avait perdu des champs ou de la taille par rapport à la dernière sauvegarde valide connue.
- `Config last-known-good promotion skipped` → le candidat contenait des espaces réservés de secrets expurgés tels que `***`.
- `.rejected.*` existe → une écriture de configuration gérée par OpenClaw a échoué aux contrôles de schéma ou d’écrasement avant validation.
- `Config write rejected:` → l’écriture a tenté de supprimer une structure requise, de réduire fortement la taille du fichier, ou de persister une configuration invalide.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` ou `size-drop-vs-last-good:*` → au démarrage, le fichier actuel a été traité comme écrasé car il avait perdu des champs ou de la taille par rapport à la sauvegarde du dernier état valide connu.
- `Config last-known-good promotion skipped` → le candidat contenait des espaces réservés de secrets masqués tels que `***`.
Options de correction :
Options de correction :
1. Conservez la configuration active restaurée si elle est correcte.
2. Copiez uniquement les clés souhaitées depuis `.clobbered.*` ou `.rejected.*`, puis appliquez-les avec `openclaw config set` ou `config.patch`.
2. Copiez uniquement les clés prévues depuis `.clobbered.*` ou `.rejected.*`, puis appliquez-les avec `openclaw config set` ou `config.patch`.
3. Exécutez `openclaw config validate` avant de redémarrer.
4. Si vous modifiez à la main, conservez la configuration JSON5 complète, et non seulement l’objet partiel que vous vouliez changer.
4. Si vous modifiez à la main, conservez la configuration JSON5 complète, pas seulement l’objet partiel que vous vouliez modifier.
Lié :
Liens associés :
- [/gateway/configuration#strict-validation](/fr/gateway/configuration#strict-validation)
- [/gateway/configuration#config-hot-reload](/fr/gateway/configuration#config-hot-reload)
- [/cli/config](/fr/cli/config)
- [/gateway/doctor](/fr/gateway/doctor)
## Avertissements de gateway probe
## Avertissements de sonde Gateway
Utilisez cette section lorsque `openclaw gateway probe` atteint bien quelque chose, mais affiche tout de même un bloc d’avertissement.
Utilisez ceci lorsque `openclaw gateway probe` atteint bien quelque chose, mais affiche quand même un bloc d’avertissement.
```bash
openclaw gateway probe
@ -330,28 +336,28 @@ openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```
Recherchez :
Recherchez :
- `warnings[].code` et `primaryTargetId` dans la sortie JSON.
- Si l’avertissement concerne le repli SSH, plusieurs gateways, des scopes manquants, ou des références d’authentification non résolues.
- Si l’avertissement concerne un repli SSH, plusieurs Gateways, des portées manquantes, ou des références d’authentification non résolues.
Signatures courantes :
Signatures courantes :
- `SSH tunnel failed to start; falling back to direct probes.` → la mise en place du tunnel SSH a échoué, mais la commande a quand même essayé les cibles directes configurées/loopback.
- `multiple reachable gateways detected` → plus d’une cible a répondu. En général, cela signifie une configuration multi-gateway intentionnelle ou des écouteurs obsolètes/dupliqués.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → la connexion a fonctionné, mais le RPC détaillé est limité par les scopes ; appairez l’identité de l’appareil ou utilisez des identifiants disposant de `operator.read`.
- `Capability: pairing-pending` ou `gateway closed (1008): pairing required` → le gateway a répondu, mais ce client nécessite encore un appairage/une approbation avant un accès opérateur normal.
- texte d’avertissement de SecretRef non résolu pour `gateway.auth.*` / `gateway.remote.*` → le matériel d’authentification n’était pas disponible dans ce chemin de commande pour la cible en échec.
- `SSH tunnel failed to start; falling back to direct probes.` → la configuration SSH a échoué, mais la commande a quand même tenté les cibles directes configurées/en loopback.
- `multiple reachable gateways detected` → plus d’une cible a répondu. En général, cela signifie une configuration multi-Gateway intentionnelle ou des écouteurs obsolètes/dupliqués.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → la connexion a fonctionné, mais le RPC de détail est limité par la portée ; appairez l’identité de l’appareil ou utilisez des identifiants avec `operator.read`.
- `Capability: pairing-pending` ou `gateway closed (1008): pairing required` → la Gateway a répondu, mais ce client a encore besoin d’un appairage/d’une approbation avant l’accès opérateur normal.
- texte d’avertissement SecretRef non résolu `gateway.auth.*` / `gateway.remote.*` → le matériel d’authentification n’était pas disponible dans ce chemin de commande pour la cible en échec.
Lié :
Liens associés :
- [/cli/gateway](/fr/cli/gateway)
- [/gateway#multiple-gateways-same-host](/fr/gateway#multiple-gateways-same-host)
- [/gateway/remote](/fr/gateway/remote)
## Canal connecté mais messages non transmis
## Canal connecté mais messages non distribués
Si l’état du canal est connecté mais que le flux de messages est mort, concentrez-vous sur la politique, les permissions et les règles de livraison spécifiques au canal.
Si l’état du canal est connecté mais que le flux de messages est interrompu, concentrez-vous sur la stratégie, les autorisations et les règles de livraison spécifiques au canal.
```bash
openclaw channels status --probe
@ -361,19 +367,19 @@ openclaw logs --follow
openclaw config get channels
```
Recherchez :
Recherchez :
- Politique de message privé (`pairing`, `allowlist`, `open`, `disabled`).
- Liste d’autorisation de groupe et exigences de mention.
- Permissions/scopes API du canal manquants.
- Stratégie DM (`pairing`, `allowlist`, `open`, `disabled`).
- Allowlist de groupe et exigences de mention.
- Permissions/portées API du canal manquantes.
Signatures courantes :
Signatures courantes :
- `mention required` → message ignoré par la politique de mention de groupe.
- `mention required` → message ignoré par la stratégie de mention de groupe.
- traces `pairing` / approbation en attente → l’expéditeur n’est pas approuvé.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problème d’authentification/permissions du canal.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problème d’authentification/autorisations du canal.
Lié :
Liens associés :
- [/channels/troubleshooting](/fr/channels/troubleshooting)
- [/channels/whatsapp](/fr/channels/whatsapp)
@ -392,31 +398,31 @@ openclaw system heartbeat last
openclaw logs --follow
```
Recherchez :
Recherchez :
- Cron activé et prochain réveil présent.
- État de l’historique d’exécution des tâches (`ok`, `skipped`, `error`).
- Raisons d’ignorance du Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
- Cron activé et prochaine activation présente.
- État de l’historique des exécutions de tâche (`ok`, `skipped`, `error`).
- Raisons d’ignorance de Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
Signatures courantes :
Signatures courantes :
- `cron: scheduler disabled; jobs will not run automatically` → Cron désactivé.
- `cron: timer tick failed` → échec du tick du planificateur ; vérifiez les erreurs de fichier/journal/runtime.
- `cron: timer tick failed` → échec du tick du planificateur ; vérifiez les erreurs de fichier/journal/runtime.
- `heartbeat skipped` avec `reason=quiet-hours` → en dehors de la fenêtre d’heures actives.
- `heartbeat skipped` avec `reason=empty-heartbeat-file` → `HEARTBEAT.md` existe mais ne contient que des lignes vides / en-têtes markdown, donc OpenClaw ignore l’appel au modèle.
- `heartbeat skipped` avec `reason=no-tasks-due` → `HEARTBEAT.md` contient un bloc `tasks:`, mais aucune des tâches n’est due à ce tick.
- `heartbeat: unknown accountId` → identifiant de compte invalide pour la cible de livraison Heartbeat.
- `heartbeat skipped` avec `reason=dm-blocked` → la cible Heartbeat s’est résolue en destination de type message privé alors que `agents.defaults.heartbeat.directPolicy` (ou le remplacement par agent) est défini sur `block`.
- `heartbeat skipped` avec `reason=empty-heartbeat-file` → `HEARTBEAT.md` existe mais ne contient que des lignes vides / en-têtes markdown ; OpenClaw ignore donc l’appel au modèle.
- `heartbeat skipped` avec `reason=no-tasks-due` → `HEARTBEAT.md` contient un bloc `tasks:`, mais aucune tâche n’est due sur ce tick.
- `heartbeat: unknown accountId` → identifiant de compte invalide pour la cible de livraison de Heartbeat.
- `heartbeat skipped` avec `reason=dm-blocked` → la cible de Heartbeat a été résolue vers une destination de type DM alors que `agents.defaults.heartbeat.directPolicy` (ou la surcharge par agent) est défini sur `block`.
Lié :
Liens associés :
- [/automation/cron-jobs#troubleshooting](/fr/automation/cron-jobs#troubleshooting)
- [/automation/cron-jobs](/fr/automation/cron-jobs)
- [/gateway/heartbeat](/fr/gateway/heartbeat)
## Échec d’un outil sur un Node appairé
## Échec d’outil Node appairé
Si un Node est appairé mais que les outils échouent, isolez l’état de premier plan, de permission et d’approbation.
Si un Node est appairé mais que les outils échouent, isolez l’état de premier plan, les autorisations et l’état d’approbation.
```bash
openclaw nodes status
@ -426,20 +432,20 @@ openclaw logs --follow
openclaw status
```
Recherchez :
Recherchez :
- Node en ligne avec les capacités attendues.
- Permissions système accordées pour caméra/micro/localisation/écran.
- Approbations d’exécution et état de la liste d’autorisation.
- Autorisations OS accordées pour caméra/micro/localisation/écran.
- État des approbations exec et de l’allowlist.
Signatures courantes :
Signatures courantes :
- `NODE_BACKGROUND_UNAVAILABLE` → l’app Node doit être au premier plan.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permission système manquante.
- `SYSTEM_RUN_DENIED: approval required` → approbation d’exécution en attente.
- `SYSTEM_RUN_DENIED: allowlist miss` → commande bloquée par la liste d’autorisation.
- `NODE_BACKGROUND_UNAVAILABLE` → l’application Node doit être au premier plan.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → autorisation OS manquante.
- `SYSTEM_RUN_DENIED: approval required` → approbation exec en attente.
- `SYSTEM_RUN_DENIED: allowlist miss` → commande bloquée par l’allowlist.
Lié :
Liens associés :
- [/nodes/troubleshooting](/fr/nodes/troubleshooting)
- [/nodes/index](/fr/nodes/index)
@ -447,7 +453,7 @@ Lié :
## Échec de l’outil navigateur
Utilisez cette section lorsque les actions de l’outil navigateur échouent alors que le gateway lui-même est sain.
Utilisez ceci lorsque les actions de l’outil navigateur échouent même si la Gateway elle-même est saine.
```bash
openclaw browser status
@ -457,44 +463,46 @@ openclaw logs --follow
openclaw doctor
```
Recherchez :
Recherchez :
- Si `plugins.allow` est défini et inclut `browser`.
- Un chemin d’exécutable navigateur valide.
- Un chemin d’exécutable du navigateur valide.
- L’accessibilité du profil CDP.
- La disponibilité de Chrome local pour les profils `existing-session` / `user`.
Signatures courantes :
Signatures courantes :
- `unknown command "browser"` ou `unknown command 'browser'` → le plugin navigateur inclus est exclu par `plugins.allow`.
- outil navigateur manquant / indisponible alors que `browser.enabled=true` → `plugins.allow` exclut `browser`, donc le plugin n’a jamais été chargé.
- `Failed to start Chrome CDP on port` → le processus navigateur n’a pas réussi à se lancer.
- `unknown command "browser"` ou `unknown command 'browser'` → le Plugin navigateur intégré est exclu par `plugins.allow`.
- outil navigateur manquant / indisponible alors que `browser.enabled=true` → `plugins.allow` exclut `browser`, donc le Plugin ne s’est jamais chargé.
- `Failed to start Chrome CDP on port` → le processus du navigateur n’a pas réussi à se lancer.
- `browser.executablePath not found` → le chemin configuré est invalide.
- `browser.cdpUrl must be http(s) or ws(s)` → l’URL CDP configurée utilise un schéma non pris en charge comme `file:` ou `ftp:`.
- `browser.cdpUrl has invalid port` → l’URL CDP configurée a un port mauvais ou hors plage.
- `Could not find DevToolsActivePort for chrome` → la session existante Chrome MCP n’a pas encore pu s’attacher au répertoire de données navigateur sélectionné. Ouvrez la page d’inspection du navigateur, activez le débogage à distance, gardez le navigateur ouvert, approuvez la première demande d’attachement, puis réessayez. Si l’état connecté n’est pas requis, préférez le profil géré `openclaw`.
- `No Chrome tabs found for profile="user"` → le profil d’attachement Chrome MCP n’a aucun onglet Chrome local ouvert.
- `Remote CDP for profile "<name>" is not reachable` → le point de terminaison CDP distant configuré n’est pas accessible depuis l’hôte gateway.
- `Browser attachOnly is enabled ... not reachable` ou `Browser attachOnly is enabled and CDP websocket ... is not reachable` → le profil attach-only n’a aucune cible accessible, ou le point de terminaison HTTP a répondu mais le WebSocket CDP n’a toujours pas pu être ouvert.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → l’installation actuelle du gateway ne dispose pas de la dépendance d’exécution `playwright-core` du plugin navigateur inclus ; exécutez `openclaw doctor --fix`, puis redémarrez le gateway. Les instantanés ARIA et les captures d’écran de page de base peuvent encore fonctionner, mais la navigation, les instantanés IA, les captures d’écran d’éléments par sélecteur CSS et l’export PDF restent indisponibles.
- `fullPage is not supported for element screenshots` → la demande de capture d’écran mélange `--full-page` avec `--ref` ou `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → les appels de capture d’écran Chrome MCP / `existing-session` doivent utiliser une capture de page ou un `--ref` issu d’un instantané, pas un `--element` CSS.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → les hooks d’envoi de fichiers Chrome MCP nécessitent des refs d’instantané, pas des sélecteurs CSS.
- `browser.cdpUrl must be http(s) or ws(s)` → l’URL CDP configurée utilise un schéma non pris en charge tel que `file:` ou `ftp:`.
- `browser.cdpUrl has invalid port` → l’URL CDP configurée a un port incorrect ou hors plage.
- `Could not find DevToolsActivePort for chrome` → la session existante Chrome MCP n’a pas encore pu se rattacher au répertoire de données navigateur sélectionné. Ouvrez la page d’inspection du navigateur, activez le débogage à distance, gardez le navigateur ouvert, approuvez la première invite de rattachement, puis réessayez. Si l’état connecté n’est pas requis, préférez le profil géré `openclaw`.
- `No Chrome tabs found for profile="user"` → le profil de rattachement Chrome MCP n’a aucun onglet Chrome local ouvert.
- `Remote CDP for profile "<name>" is not reachable` → le point de terminaison CDP distant configuré n’est pas joignable depuis l’hôte Gateway.
- `Browser attachOnly is enabled ... not reachable` ou `Browser attachOnly is enabled and CDP websocket ... is not reachable` → le profil attach-only n’a aucune cible joignable, ou le point de terminaison HTTP a répondu mais le WebSocket CDP n’a quand même pas pu être ouvert.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → l’installation actuelle de Gateway n’a pas la dépendance runtime `playwright-core` du Plugin navigateur intégré ; exécutez `openclaw doctor --fix`, puis redémarrez Gateway. Les instantanés ARIA et les captures d’écran de page de base peuvent toujours fonctionner, mais la navigation, les instantanés IA, les captures d’écran d’élément par sélecteur CSS et l’export PDF restent indisponibles.
- `fullPage is not supported for element screenshots` → la requête de capture d’écran mélangeait `--full-page` avec `--ref` ou `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → les appels de capture d’écran Chrome MCP / `existing-session` doivent utiliser une capture de page ou un `--ref` d’instantané, pas un `--element` CSS.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → les hooks de téléversement Chrome MCP nécessitent des refs d’instantané, pas des sélecteurs CSS.
- `existing-session file uploads currently support one file at a time.` → envoyez un seul téléversement par appel sur les profils Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → les hooks de dialogue sur les profils Chrome MCP ne prennent pas en charge les remplacements de délai.
- `existing-session dialog handling does not support timeoutMs.` → les hooks de boîte de dialogue sur les profils Chrome MCP ne prennent pas en charge les remplacements de délai d’expiration.
- `existing-session type does not support timeoutMs overrides.` → omettez `timeoutMs` pour `act:type` sur `profile="user"` / profils Chrome MCP `existing-session`, ou utilisez un profil navigateur géré/CDP lorsqu’un délai d’expiration personnalisé est requis.
- `existing-session evaluate does not support timeoutMs overrides.` → omettez `timeoutMs` pour `act:evaluate` sur `profile="user"` / profils Chrome MCP `existing-session`, ou utilisez un profil navigateur géré/CDP lorsqu’un délai d’expiration personnalisé est requis.
- `response body is not supported for existing-session profiles yet.` → `responsebody` nécessite encore un navigateur géré ou un profil CDP brut.
- remplacements obsolètes de viewport / mode sombre / locale / hors ligne sur des profils attach-only ou CDP distants → exécutez `openclaw browser stop --browser-profile <name>` pour fermer la session de contrôle active et libérer l’état d’émulation Playwright/CDP sans redémarrer tout le gateway.
- remplacements persistants de viewport / mode sombre / paramètres régionaux / hors ligne sur les profils attach-only ou CDP distants → exécutez `openclaw browser stop --browser-profile <name>` pour fermer la session de contrôle active et libérer l’état d’émulation Playwright/CDP sans redémarrer toute la Gateway.
Lié :
Liens associés :
- [/tools/browser-linux-troubleshooting](/fr/tools/browser-linux-troubleshooting)
- [/tools/browser](/fr/tools/browser)
## Si vous avez mis à niveau et que quelque chose s’est soudainement cassé
La plupart des régressions après mise à niveau sont dues à une dérive de configuration ou à des valeurs par défaut plus strictes désormais appliquées.
La plupart des problèmes après mise à niveau viennent d’une dérive de configuration ou de valeurs par défaut plus strictes désormais appliquées.
### 1) Le comportement d’authentification et de remplacement d’URL a changé
### 1) Le comportement d’authentification et de surcharge d’URL a changé
```bash
openclaw gateway status
@ -503,15 +511,15 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
Points à vérifier :
Ce qu’il faut vérifier :
- Si `gateway.mode=remote`, les appels CLI peuvent viser un service distant alors que votre service local fonctionne très bien.
- Les appels explicites avec `--url` ne retombent pas sur les identifiants stockés.
- Si `gateway.mode=remote`, les appels CLI peuvent cibler le distant alors que votre service local fonctionne bien.
- Les appels explicites `--url` ne reviennent pas aux identifiants stockés.
Signatures courantes :
Signatures courantes :
- `gateway connect failed:` → mauvaise URL cible.
- `unauthorized` → point de terminaison accessible mais mauvaise authentification.
- `gateway connect failed:` → cible URL incorrecte.
- `unauthorized` → point de terminaison joignable mais authentification incorrecte.
### 2) Les garde-fous de liaison et d’authentification sont plus stricts
@ -523,15 +531,15 @@ openclaw gateway status
openclaw logs --follow
```
Points à vérifier :
Ce qu’il faut vérifier :
- Les liaisons non loopback (`lan`, `tailnet`, `custom`) nécessitent un chemin d’authentification gateway valide : authentification par jeton/mot de passe partagé, ou déploiement `trusted-proxy` non-loopback correctement configuré.
- Les liaisons non loopback (`lan`, `tailnet`, `custom`) nécessitent un chemin d’authentification Gateway valide : authentification par jeton partagé/mot de passe, ou déploiement `trusted-proxy` non loopback correctement configuré.
- Les anciennes clés comme `gateway.token` ne remplacent pas `gateway.auth.token`.
Signatures courantes :
Signatures courantes :
- `refusing to bind gateway ... without auth` → liaison non-loopback sans chemin d’authentification gateway valide.
- `Connectivity probe: failed` alors que le runtime est actif → le gateway est vivant mais inaccessible avec l’authentification/l’URL actuelles.
- `refusing to bind gateway ... without auth` → liaison non loopback sans chemin d’authentification Gateway valide.
- `Connectivity probe: failed` alors que le runtime est en cours d’exécution → Gateway est active mais inaccessible avec l’authentification/l’URL actuelle.
### 3) L’état d’appairage et d’identité d’appareil a changé
@ -542,30 +550,30 @@ openclaw logs --follow
openclaw doctor
```
Points à vérifier :
Ce qu’il faut vérifier :
- Approbations d’appareil en attente pour le tableau de bord/les Node.
- Approbations d’appairage de message privé en attente après des changements de politique ou d’identité.
- Approbations d’appareil en attente pour dashboard/nodes.
- Approbations d’appairage DM en attente après des changements de stratégie ou d’identité.
Signatures courantes :
Signatures courantes :
- `device identity required` → l’authentification de l’appareil n’est pas satisfaite.
- `device identity required` → authentification d’appareil non satisfaite.
- `pairing required` → l’expéditeur/l’appareil doit être approuvé.
Si la configuration du service et le runtime sont toujours en désaccord après ces vérifications, réinstallez les métadonnées du service à partir du même répertoire profil/état :
Si la configuration du service et le runtime sont toujours en désaccord après les vérifications, réinstallez les métadonnées du service à partir du même répertoire de profil/d’état :
```bash
openclaw gateway install --force
openclaw gateway restart
```
Lié :
Liens associés :
- [/gateway/pairing](/fr/gateway/pairing)
- [/gateway/authentication](/fr/gateway/authentication)
- [/gateway/background-process](/fr/gateway/background-process)
## Lié
## Liens associés
- [Runbook Gateway](/fr/gateway)
- [Doctor](/fr/gateway/doctor)

747
docs/fr/plugins/architecture-internals.md
View File

File diff suppressed because it is too large Load Diff

356
docs/fr/plugins/codex-harness.md
View File

@ -1,103 +1,111 @@
---
read_when:
- Vous voulez utiliser le harnais app-server Codex intégré
- Vous avez besoin de références de modèles Codex et d’exemples de configuration
- Vous voulez désactiver le repli PI pour les déploiements Codex uniquement
summary: Exécuter des tours d’agent embarqué OpenClaw via le harnais app-server Codex intégré
title: Harnais Codex
- Vous souhaitez utiliser le harnais app-server Codex groupé
- Vous avez besoin de références de modèle Codex et d’exemples de configuration
- Vous souhaitez désactiver le repli Pi pour les déploiements Codex uniquement
summary: Exécutez les tours de l’agent intégré OpenClaw via le harnais app-server Codex groupé
title: harnais Codex
x-i18n:
generated_at: "2026-04-24T07:22:05Z"
generated_at: "2026-04-24T08:57:10Z"
model: gpt-5.4
provider: openai
source_hash: 095933d2c32df302c312c67fdc266d2f01b552dddb1607d6e4ecc4f3c3326acf
source_hash: c02b1e6cbaaefee858db7ebd7e306261683278ed9375bca6fe74855ca84eabd8
source_path: plugins/codex-harness.md
workflow: 15
---
Le Plugin `codex` intégré permet à OpenClaw d’exécuter des tours d’agent embarqué via le
serveur d’application Codex au lieu du harnais PI intégré.
Le Plugin `codex` groupé permet à OpenClaw d’exécuter des tours d’agent intégrés via l’app-server Codex au lieu du harnais PI intégré.
Utilisez cela lorsque vous voulez que Codex possède la session d’agent de bas niveau : découverte de modèles, reprise native de fil, Compaction native et exécution du serveur d’application.
OpenClaw reste responsable des canaux de chat, des fichiers de session, de la sélection de modèle, des outils,
des approbations, de la livraison des médias et du miroir de transcription visible.
Utilisez ceci lorsque vous souhaitez que Codex prenne en charge la session d’agent de bas niveau : découverte des modèles, reprise native de thread, Compaction native et exécution par app-server.
OpenClaw continue de gérer les canaux de chat, les fichiers de session, la sélection de modèle, les outils,
les approbations, la livraison des médias et le miroir visible de la transcription.
Les tours Codex natifs conservent les hooks de Plugin OpenClaw comme couche publique de compatibilité.
Il s’agit de hooks OpenClaw en processus, pas des hooks de commande `hooks.json` de Codex :
Les tours Codex natifs conservent les hooks de Plugin OpenClaw comme couche de compatibilité publique.
Il s’agit de hooks OpenClaw en cours de processus, et non de hooks de commande `hooks.json` de Codex :
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `after_tool_call`
- `before_message_write` pour les enregistrements miroir de transcription
- `before_message_write` pour les enregistrements de transcription en miroir
- `agent_end`
Les plugins intégrés peuvent aussi enregistrer une fabrique d’extension de serveur d’application Codex pour ajouter un middleware asynchrone `tool_result`. Ce middleware s’exécute pour les outils dynamiques OpenClaw après qu’OpenClaw a exécuté l’outil et avant que le résultat ne soit renvoyé à Codex. Il est distinct du hook public de Plugin `tool_result_persist`, qui transforme les écritures de résultats d’outils détenues par OpenClaw dans la transcription.
Les plugins groupés peuvent également enregistrer une fabrique d’extension d’app-server Codex pour ajouter
un middleware asynchrone `tool_result`. Ce middleware s’exécute pour les outils dynamiques OpenClaw
après qu’OpenClaw a exécuté l’outil et avant que le résultat ne soit renvoyé à Codex. Il
est distinct du hook de Plugin public `tool_result_persist`, qui transforme les écritures de résultat d’outil dans la transcription gérée par OpenClaw.
Le harnais est désactivé par défaut. Les nouvelles configurations doivent conserver les références de modèles OpenAI sous la forme canonique `openai/gpt-*` et forcer explicitement
Le harnais est désactivé par défaut. Les nouvelles configurations doivent conserver les références de modèle OpenAI
canoniques sous la forme `openai/gpt-*` et forcer explicitement
`embeddedHarness.runtime: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex` lorsqu’elles
veulent une exécution native du serveur d’application. Les anciennes références de modèles `codex/*` sélectionnent encore automatiquement le harnais pour compatibilité.
souhaitent une exécution native par app-server. Les anciennes références de modèle `codex/*` sélectionnent toujours automatiquement
le harnais pour des raisons de compatibilité.
## Choisir le bon préfixe de modèle
Les routes de la famille OpenAI dépendent du préfixe. Utilisez `openai-codex/*` lorsque vous voulez
l’OAuth Codex via PI ; utilisez `openai/*` lorsque vous voulez un accès direct à l’API OpenAI ou
lorsque vous forcez le harnais natif du serveur d’application Codex :
l’authentification OAuth Codex via PI ; utilisez `openai/*` lorsque vous voulez un accès direct à l’API OpenAI ou
lorsque vous forcez le harnais app-server Codex natif :
| Réf. de modèle | Chemin d’exécution | Utiliser lorsque |
| ------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------- |
| `openai/gpt-5.4` | Fournisseur OpenAI via la plomberie OpenClaw/PI | Vous voulez l’accès direct actuel à l’API OpenAI Platform avec `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5` | OAuth OpenAI Codex via OpenClaw/PI | Vous voulez l’authentification par abonnement ChatGPT/Codex avec l’exécuteur PI par défaut. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harnais serveur d’application Codex | Vous voulez une exécution native du serveur d’application Codex pour le tour d’agent embarqué. |
| Référence de modèle | Chemin d’exécution | À utiliser lorsque |
| ---------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | Fournisseur OpenAI via le pipeline OpenClaw/PI | Vous voulez l’accès direct actuel à l’API OpenAI Platform avec `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5` | OAuth OpenAI Codex via OpenClaw/PI | Vous voulez l’authentification par abonnement ChatGPT/Codex avec l’exécuteur PI par défaut. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harnais app-server Codex | Vous voulez une exécution native par app-server Codex pour le tour d’agent intégré. |
GPT-5.5 est actuellement uniquement disponible via abonnement/OAuth dans OpenClaw. Utilisez
`openai-codex/gpt-5.5` pour l’OAuth PI, ou `openai/gpt-5.5` avec le harnais du
serveur d’application Codex. L’accès direct par clé API à `openai/gpt-5.5` est pris en charge
GPT-5.5 est actuellement disponible dans OpenClaw uniquement via abonnement/OAuth. Utilisez
`openai-codex/gpt-5.5` pour l’OAuth PI, ou `openai/gpt-5.5` avec le harnais
app-server Codex. L’accès direct par clé API pour `openai/gpt-5.5` est pris en charge
une fois qu’OpenAI active GPT-5.5 sur l’API publique.
Les anciennes références `codex/gpt-*` restent acceptées comme alias de compatibilité. Les nouvelles configurations PI
Codex OAuth doivent utiliser `openai-codex/gpt-*` ; les nouvelles configurations du harnais natif du serveur d’application
doivent utiliser `openai/gpt-*` plus `embeddedHarness.runtime:
Les anciennes références `codex/gpt-*` restent acceptées comme alias de compatibilité. Les nouvelles configurations
d’OAuth PI Codex doivent utiliser `openai-codex/gpt-*` ; les nouvelles configurations de harnais app-server
natif doivent utiliser `openai/gpt-*` avec `embeddedHarness.runtime:
"codex"`.
`agents.defaults.imageModel` suit la même séparation par préfixe. Utilisez
`openai-codex/gpt-*` lorsque la compréhension d’image doit passer par le chemin du fournisseur OpenAI
Codex OAuth. Utilisez `codex/gpt-*` lorsque la compréhension d’image doit passer
par un tour borné du serveur d’application Codex. Le modèle Codex du serveur d’application doit
annoncer la prise en charge des entrées image ; les modèles Codex texte uniquement échouent avant le début du tour média.
`openai-codex/gpt-*` lorsque l’analyse d’image doit passer par le chemin du fournisseur OAuth OpenAI
Codex. Utilisez `codex/gpt-*` lorsque l’analyse d’image doit s’exécuter
dans un tour d’app-server Codex borné. Le modèle app-server Codex doit
annoncer la prise en charge des entrées image ; les modèles Codex texte seul échouent avant le début
du tour média.
Utilisez `/status` pour confirmer le harnais effectif de la session actuelle. Si la
sélection est surprenante, activez la journalisation de débogage pour le sous-système `agents/harness`
et inspectez l’enregistrement structuré `agent harness selected` du gateway. Il
inclut l’ID du harnais sélectionné, la raison de sélection, la politique d’exécution/de repli, et,
sélection vous surprend, activez la journalisation de débogage pour le sous-système `agents/harness`
et inspectez l’enregistrement structuré `agent harness selected` de la Gateway. Il
inclut l’identifiant du harnais sélectionné, la raison de la sélection, la politique d’exécution/repli et,
en mode `auto`, le résultat de prise en charge de chaque candidat Plugin.
La sélection de harnais n’est pas un contrôle dynamique de session active. Lorsqu’un tour embarqué s’exécute,
OpenClaw enregistre l’ID du harnais sélectionné sur cette session et continue à l’utiliser pour les
tours ultérieurs du même ID de session. Modifiez la configuration `embeddedHarness` ou
La sélection du harnais n’est pas un contrôle de session en direct. Lorsqu’un tour intégré s’exécute,
OpenClaw enregistre l’identifiant du harnais sélectionné sur cette session et continue à l’utiliser pour
les tours ultérieurs du même identifiant de session. Modifiez la configuration `embeddedHarness` ou
`OPENCLAW_AGENT_RUNTIME` lorsque vous voulez que les futures sessions utilisent un autre harnais ;
utilisez `/new` ou `/reset` pour démarrer une nouvelle session avant de basculer une conversation existante entre PI et Codex. Cela évite de relire une même transcription à travers deux systèmes natifs de session incompatibles.
utilisez `/new` ou `/reset` pour démarrer une nouvelle session avant de faire basculer une conversation existante entre PI et Codex. Cela évite de rejouer une même transcription dans
deux systèmes de session natifs incompatibles.
Les anciennes sessions créées avant l’épinglage du harnais sont traitées comme épinglées PI une fois qu’elles ont un historique de transcription. Utilisez `/new` ou `/reset` pour faire adhérer cette conversation à Codex après changement de configuration.
Les anciennes sessions créées avant l’épinglage du harnais sont traitées comme épinglées à PI dès qu’elles
ont un historique de transcription. Utilisez `/new` ou `/reset` pour faire passer cette conversation à
Codex après avoir modifié la configuration.
`/status` affiche le harnais effectif non-PI à côté de `Fast`, par exemple
`Fast · codex`. Le harnais PI par défaut reste `Runner: pi (embedded)` et n’ajoute
pas de badge de harnais séparé.
`Fast · codex`. Le harnais PI par défaut reste `Runner: pi (embedded)` et
n’ajoute pas de badge de harnais séparé.
## Exigences
## Prérequis
- OpenClaw avec le Plugin `codex` intégré disponible.
- Serveur d’application Codex `0.118.0` ou plus récent.
- Authentification Codex disponible pour le processus du serveur d’application.
- OpenClaw avec le Plugin `codex` groupé disponible.
- App-server Codex `0.118.0` ou version ultérieure.
- Authentification Codex disponible pour le processus app-server.
Le Plugin bloque les handshakes de serveur d’application plus anciens ou sans version. Cela permet à
OpenClaw de rester sur la surface de protocole avec laquelle il a été testé.
Le Plugin bloque les handshakes d’app-server plus anciens ou non versionnés. Cela permet de maintenir
OpenClaw sur la surface de protocole avec laquelle il a été testé.
Pour les tests smoke live et Docker, l’authentification provient généralement de `OPENAI_API_KEY`, plus des fichiers CLI Codex facultatifs comme `~/.codex/auth.json` et
`~/.codex/config.toml`. Utilisez les mêmes éléments d’authentification que ceux de votre serveur d’application Codex local.
Pour les tests smoke en direct et dans Docker, l’authentification provient généralement de `OPENAI_API_KEY`, plus des fichiers optionnels de CLI Codex tels que `~/.codex/auth.json` et
`~/.codex/config.toml`. Utilisez les mêmes éléments d’authentification que votre app-server Codex locale.
## Configuration minimale
Utilisez `openai/gpt-5.5`, activez le Plugin intégré et forcez le harnais `codex` :
Utilisez `openai/gpt-5.5`, activez le Plugin groupé et forcez le harnais `codex` :
```json5
{
@ -120,7 +128,7 @@ Utilisez `openai/gpt-5.5`, activez le Plugin intégré et forcez le harnais `cod
}
```
Si votre configuration utilise `plugins.allow`, incluez-y aussi `codex` :
Si votre configuration utilise `plugins.allow`, incluez également `codex` :
```json5
{
@ -136,8 +144,8 @@ Si votre configuration utilise `plugins.allow`, incluez-y aussi `codex` :
```
Les anciennes configurations qui définissent `agents.defaults.model` ou un modèle d’agent sur
`codex/<model>` activent encore automatiquement le Plugin `codex` intégré. Les nouvelles configurations doivent
préférer `openai/<model>` plus l’entrée explicite `embeddedHarness` ci-dessus.
`codex/<model>` activent toujours automatiquement le Plugin `codex` groupé. Les nouvelles configurations doivent
préférer `openai/<model>` avec l’entrée `embeddedHarness` explicite ci-dessus.
## Ajouter Codex sans remplacer les autres modèles
@ -173,15 +181,15 @@ les agents qui doivent utiliser le harnais.
}
```
Avec cette forme :
Avec cette structure :
- `/model gpt` ou `/model openai/gpt-5.5` utilise le harnais du serveur d’application Codex pour cette configuration.
- `/model gpt` ou `/model openai/gpt-5.5` utilise le harnais app-server Codex pour cette configuration.
- `/model opus` utilise le chemin du fournisseur Anthropic.
- Si un modèle non-Codex est sélectionné, PI reste le harnais de compatibilité.
## Déploiements Codex uniquement
Désactivez le repli PI lorsque vous devez prouver que chaque tour d’agent embarqué utilise
Désactivez le repli PI lorsque vous devez prouver que chaque tour d’agent intégré utilise
le harnais Codex :
```json5
@ -198,7 +206,7 @@ le harnais Codex :
}
```
Remplacement par environnement :
Surcharge d’environnement :
```bash
OPENCLAW_AGENT_RUNTIME=codex \
@ -206,13 +214,13 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
Avec le repli désactivé, OpenClaw échoue immédiatement si le Plugin Codex est désactivé,
si le serveur d’application est trop ancien, ou s’il ne peut pas démarrer.
Avec le repli désactivé, OpenClaw échoue rapidement si le Plugin Codex est désactivé,
si l’app-server est trop ancien ou si l’app-server ne peut pas démarrer.
## Codex par agent
Vous pouvez rendre un agent Codex-only tandis que l’agent par défaut conserve la
sélection automatique normale :
Vous pouvez rendre un agent Codex uniquement tandis que l’agent par défaut conserve
la sélection automatique normale :
```json5
{
@ -243,21 +251,21 @@ sélection automatique normale :
}
```
Utilisez les commandes de session et de modèle normales pour changer d’agent et de modèle. `/new` crée une nouvelle
session OpenClaw et le harnais Codex crée ou reprend son fil sidecar de serveur d’application
si nécessaire. `/reset` efface la liaison de session OpenClaw pour ce fil
et laisse le tour suivant résoudre de nouveau le harnais depuis la configuration actuelle.
Utilisez les commandes de session normales pour changer d’agent et de modèle. `/new` crée une nouvelle
session OpenClaw et le harnais Codex crée ou reprend son thread app-server sidecar
selon les besoins. `/reset` efface l’association de session OpenClaw pour ce thread
et permet au tour suivant de résoudre à nouveau le harnais à partir de la configuration actuelle.
## Discovery de modèle
## Découverte des modèles
Par défaut, le Plugin Codex interroge le serveur d’application pour connaître les modèles disponibles. Si la
discovery échoue ou expire, il utilise un catalogue de repli intégré pour :
Par défaut, le Plugin Codex interroge l’app-server pour obtenir les modèles disponibles. Si
la découverte échoue ou expire, il utilise un catalogue de repli groupé pour :
- GPT-5.5
- GPT-5.4 mini
- GPT-5.2
Vous pouvez ajuster la discovery sous `plugins.entries.codex.config.discovery` :
Vous pouvez ajuster la découverte sous `plugins.entries.codex.config.discovery` :
```json5
{
@ -277,8 +285,8 @@ Vous pouvez ajuster la discovery sous `plugins.entries.codex.config.discovery` :
}
```
Désactivez la discovery lorsque vous voulez que le démarrage évite de sonder Codex et s’en tienne au
catalogue de repli :
Désactivez la découverte lorsque vous voulez que le démarrage évite de sonder Codex et s’en tienne
au catalogue de repli :
```json5
{
@ -297,7 +305,7 @@ catalogue de repli :
}
```
## Connexion au serveur d’application et politique
## Connexion et politique de l’app-server
Par défaut, le Plugin démarre Codex localement avec :
@ -305,13 +313,13 @@ Par défaut, le Plugin démarre Codex localement avec :
codex app-server --listen stdio://
```
Par défaut, OpenClaw démarre les sessions locales du harnais Codex en mode YOLO :
`approvalPolicy: "never"`, `approvalsReviewer: "user"`, et
`sandbox: "danger-full-access"`. Il s’agit de la posture locale d’opérateur de confiance utilisée
pour les Heartbeats autonomes : Codex peut utiliser les outils shell et réseau sans
s’arrêter sur des invites d’approbation natives auxquelles personne n’est présent pour répondre.
Par défaut, OpenClaw démarre les sessions de harnais Codex locales en mode YOLO :
`approvalPolicy: "never"`, `approvalsReviewer: "user"` et
`sandbox: "danger-full-access"`. Il s’agit de la posture d’opérateur local de confiance utilisée
pour les Heartbeat autonomes : Codex peut utiliser les outils shell et réseau sans
s’arrêter sur des invites d’approbation natives auxquelles personne n’est là pour répondre.
Pour adhérer explicitement aux approbations relues par guardian de Codex, définissez `appServer.mode:
Pour activer les approbations Codex relues par Guardian, définissez `appServer.mode:
"guardian"` :
```json5
@ -332,11 +340,11 @@ Pour adhérer explicitement aux approbations relues par guardian de Codex, défi
}
```
Guardian est un relecteur natif d’approbations Codex. Lorsque Codex demande à sortir du sandbox, écrire hors de l’espace de travail, ou ajouter des permissions comme l’accès réseau, Codex route cette demande d’approbation vers un sous-agent relecteur au lieu d’un prompt humain. Le relecteur applique le cadre de risque de Codex et approuve ou refuse la demande spécifique. Utilisez Guardian lorsque vous voulez plus de garde-fous que le mode YOLO mais avez encore besoin que des agents non supervisés puissent progresser.
Guardian est un réviseur d’approbation natif Codex. Lorsque Codex demande à sortir de la sandbox, à écrire hors de l’espace de travail ou à ajouter des autorisations comme l’accès réseau, Codex achemine cette demande d’approbation vers un sous-agent réviseur au lieu d’une invite humaine. Le réviseur applique le cadre de risque de Codex et approuve ou refuse la demande spécifique. Utilisez Guardian lorsque vous voulez davantage de garde-fous que le mode YOLO tout en ayant besoin que des agents sans supervision puissent continuer à progresser.
Le préréglage `guardian` se développe en `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"`, et `sandbox: "workspace-write"`. Les champs de politique individuels remplacent toujours `mode`, de sorte que les déploiements avancés peuvent combiner le préréglage avec des choix explicites.
Le préréglage `guardian` s’étend à `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` et `sandbox: "workspace-write"`. Les champs de politique individuels remplacent toujours `mode`, afin que les déploiements avancés puissent combiner le préréglage avec des choix explicites.
Pour un serveur d’application déjà en cours d’exécution, utilisez le transport WebSocket :
Pour un app-server déjà en cours d’exécution, utilisez le transport WebSocket :
```json5
{
@ -360,22 +368,22 @@ Pour un serveur d’application déjà en cours d’exécution, utilisez le tran
Champs `appServer` pris en charge :
| Champ | Valeur par défaut | Signification |
| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` lance Codex ; `"websocket"` se connecte à `url`. |
| `command` | `"codex"` | Exécutable pour le transport stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | Arguments pour le transport stdio. |
| `url` | non défini | URL WebSocket du serveur d’application. |
| `authToken` | non défini | Jeton Bearer pour le transport WebSocket. |
| `headers` | `{}` | En-têtes WebSocket supplémentaires. |
| `requestTimeoutMs` | `60000` | Délai d’expiration pour les appels de plan de contrôle au serveur d’application. |
| `mode` | `"yolo"` | Préréglage pour exécution YOLO ou relue par guardian. |
| `approvalPolicy` | `"never"` | Politique native d’approbation Codex envoyée au démarrage/reprise/tour de fil. |
| `sandbox` | `"danger-full-access"` | Mode de sandbox Codex natif envoyé au démarrage/reprise de fil. |
| `approvalsReviewer` | `"user"` | Utilisez `"guardian_subagent"` pour laisser Codex Guardian relire les prompts. |
| `serviceTier` | non défini | Niveau de service facultatif du serveur d’application Codex : `"fast"`, `"flex"`, ou `null`. Les anciennes valeurs invalides sont ignorées. |
| Champ | Valeur par défaut | Signification |
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` lance Codex ; `"websocket"` se connecte à `url`. |
| `command` | `"codex"` | Exécutable pour le transport stdio. |
| `args` | `["app-server", "--listen", "stdio://"]` | Arguments pour le transport stdio. |
| `url` | non défini | URL WebSocket de l’app-server. |
| `authToken` | non défini | Jeton Bearer pour le transport WebSocket. |
| `headers` | `{}` | En-têtes WebSocket supplémentaires. |
| `requestTimeoutMs` | `60000` | Délai d’expiration pour les appels au plan de contrôle de l’app-server. |
| `mode` | `"yolo"` | Préréglage pour l’exécution YOLO ou relue par Guardian. |
| `approvalPolicy` | `"never"` | Politique d’approbation Codex native envoyée au démarrage, à la reprise et au tour du thread. |
| `sandbox` | `"danger-full-access"` | Mode sandbox Codex natif envoyé au démarrage et à la reprise du thread. |
| `approvalsReviewer` | `"user"` | Utilisez `"guardian_subagent"` pour laisser Codex Guardian relire les invites. |
| `serviceTier` | non défini | Niveau de service optionnel de l’app-server Codex : `"fast"`, `"flex"` ou `null`. Les anciennes valeurs invalides sont ignorées. |
Les anciennes variables d’environnement fonctionnent toujours comme replis pour les tests locaux lorsque
Les anciennes variables d’environnement fonctionnent toujours comme solutions de repli pour les tests locaux lorsque
le champ de configuration correspondant n’est pas défini :
- `OPENCLAW_CODEX_APP_SERVER_BIN`
@ -384,15 +392,15 @@ le champ de configuration correspondant n’est pas défini :
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` a été supprimé. Utilisez
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` a été supprimée. Utilisez
`plugins.entries.codex.config.appServer.mode: "guardian"` à la place, ou
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` pour un test local ponctuel. La configuration est
préférée pour les déploiements reproductibles car elle conserve le comportement du Plugin dans le
même fichier revu que le reste de la configuration du harnais Codex.
préférable pour les déploiements reproductibles, car elle conserve le comportement du Plugin dans le
même fichier relu que le reste de la configuration du harnais Codex.
## Recettes courantes
Codex local avec transport stdio par défaut :
Codex local avec le transport stdio par défaut :
```json5
{
@ -406,7 +414,7 @@ Codex local avec transport stdio par défaut :
}
```
Validation de harnais Codex-only, avec repli PI désactivé :
Validation du harnais Codex uniquement, avec repli PI désactivé :
```json5
{
@ -423,7 +431,7 @@ Validation de harnais Codex-only, avec repli PI désactivé :
}
```
Approbations Codex relues par guardian :
Approvals Codex relues par Guardian :
```json5
{
@ -445,7 +453,7 @@ Approbations Codex relues par guardian :
}
```
Serveur d’application distant avec en-têtes explicites :
App-server distant avec en-têtes explicites :
```json5
{
@ -469,116 +477,126 @@ Serveur d’application distant avec en-têtes explicites :
```
Le changement de modèle reste contrôlé par OpenClaw. Lorsqu’une session OpenClaw est attachée
à un fil Codex existant, le tour suivant envoie de nouveau au
serveur d’application le modèle OpenAI actuellement sélectionné, le fournisseur, la politique d’approbation, le sandbox et le niveau de service.
Passer de `openai/gpt-5.5` à `openai/gpt-5.2` conserve la
liaison de fil mais demande à Codex de continuer avec le modèle nouvellement sélectionné.
à un thread Codex existant, le tour suivant renvoie le modèle
OpenAI actuellement sélectionné, le fournisseur, la politique d’approbation, la sandbox et le niveau de service à
l’app-server. Passer de `openai/gpt-5.5` à `openai/gpt-5.2` conserve
l’association au thread mais demande à Codex de continuer avec le modèle nouvellement sélectionné.
## Commande Codex
Le Plugin intégré enregistre `/codex` comme commande slash autorisée. Elle est
générique et fonctionne sur tout canal prenant en charge les commandes texte OpenClaw.
Le Plugin groupé enregistre `/codex` comme commande slash autorisée. Elle est
générique et fonctionne sur n’importe quel canal prenant en charge les commandes texte OpenClaw.
Formes courantes :
- `/codex status` affiche la connectivité live du serveur d’application, les modèles, le compte, les limites de débit, les serveurs MCP et les Skills.
- `/codex models` liste les modèles live du serveur d’application Codex.
- `/codex threads [filter]` liste les fils Codex récents.
- `/codex resume <thread-id>` attache la session OpenClaw actuelle à un fil Codex existant.
- `/codex compact` demande au serveur d’application Codex de compacter le fil attaché.
- `/codex review` démarre une revue native Codex pour le fil attaché.
- `/codex account` affiche le compte et l’état des limites de débit.
- `/codex mcp` liste l’état des serveurs MCP du serveur d’application Codex.
- `/codex skills` liste les Skills du serveur d’application Codex.
- `/codex status` affiche la connectivité en direct à l’app-server, les modèles, le compte, les limites de débit, les serveurs MCP et les Skills.
- `/codex models` liste les modèles de l’app-server Codex en direct.
- `/codex threads [filter]` liste les threads Codex récents.
- `/codex resume <thread-id>` attache la session OpenClaw actuelle à un thread Codex existant.
- `/codex compact` demande à l’app-server Codex de compacter le thread attaché.
- `/codex review` démarre la revue native Codex pour le thread attaché.
- `/codex account` affiche l’état du compte et des limites de débit.
- `/codex mcp` liste l’état des serveurs MCP de l’app-server Codex.
- `/codex skills` liste les Skills de l’app-server Codex.
`/codex resume` écrit le même fichier de liaison sidecar que celui utilisé par le harnais pour les
tours normaux. Au message suivant, OpenClaw reprend ce fil Codex, transmet le
modèle OpenClaw actuellement sélectionné au serveur d’application, et garde l’historique étendu
`/codex resume` écrit le même fichier d’association sidecar que celui utilisé par le harnais pour
les tours normaux. Au message suivant, OpenClaw reprend ce thread Codex, transmet le
modèle OpenClaw actuellement sélectionné à l’app-server et conserve l’historique étendu
activé.
La surface de commande exige un serveur d’application Codex `0.118.0` ou plus récent. Les méthodes de
La surface de commande nécessite l’app-server Codex `0.118.0` ou version ultérieure. Les méthodes de
contrôle individuelles sont signalées comme `unsupported by this Codex app-server` si un
serveur d’application futur ou personnalisé n’expose pas cette méthode JSON-RPC.
app-server futur ou personnalisé n’expose pas cette méthode JSON-RPC.
## Frontières des hooks
## Limites des hooks
Le harnais Codex comporte trois couches de hooks :
| Couche | Propriétaire | But |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------- |
| Hooks de Plugin OpenClaw | OpenClaw | Compatibilité produit/Plugin entre les harnais PI et Codex. |
| Middleware d’extension du serveur d’application Codex | Plugins intégrés OpenClaw | Comportement d’adaptation par tour autour des outils dynamiques OpenClaw. |
| Hooks natifs Codex | Codex | Cycle de vie bas niveau de Codex et politique d’outils natifs depuis la configuration Codex. |
| Couche | Propriétaire | But |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| Hooks de Plugin OpenClaw | OpenClaw | Compatibilité produit/plugin entre les harnais PI et Codex. |
| Middleware d’extension d’app-server Codex | Plugins groupés OpenClaw | Comportement d’adaptateur par tour autour des outils dynamiques OpenClaw. |
| Hooks natifs Codex | Codex | Cycle de vie Codex de bas niveau et politique d’outil native depuis la configuration Codex. |
OpenClaw n’utilise pas les fichiers de projet ou globaux `hooks.json` de Codex pour router le
comportement des plugins OpenClaw. Les hooks natifs Codex sont utiles pour les opérations
détenues par Codex telles que la politique shell, la revue native des résultats d’outils, la gestion de l’arrêt, et le cycle de vie natif de Compaction/modèle, mais ils ne constituent pas l’API de Plugin OpenClaw.
OpenClaw n’utilise pas les fichiers `hooks.json` de projet ou globaux de Codex pour acheminer
le comportement des plugins OpenClaw. Les hooks natifs Codex sont utiles pour les opérations
gérées par Codex, telles que la politique shell, la revue native des résultats d’outil, la gestion des arrêts et
le cycle de vie natif de Compaction/modèle, mais ils ne constituent pas l’API de Plugin OpenClaw.
Pour les outils dynamiques OpenClaw, OpenClaw exécute l’outil après que Codex a demandé
l’appel, donc OpenClaw déclenche le comportement de Plugin et de middleware qu’il possède dans l’adaptateur
de harnais. Pour les outils natifs Codex, Codex possède l’enregistrement canonique de l’outil.
OpenClaw peut refléter certains événements, mais il ne peut pas réécrire le fil natif Codex
à moins que Codex n’expose cette opération via le serveur d’application ou des callbacks de hook natifs.
l’appel ; OpenClaw déclenche donc le comportement de Plugin et de middleware qu’il possède dans
l’adaptateur de harnais. Pour les outils natifs Codex, Codex possède l’enregistrement canonique de l’outil.
OpenClaw peut mettre en miroir certains événements, mais il ne peut pas réécrire le thread Codex natif
à moins que Codex n’expose cette opération via l’app-server ou des callbacks de hook natifs.
Lorsque de nouvelles versions du serveur d’application Codex exposeront des événements natifs de hook pour la Compaction et le cycle de vie du modèle, OpenClaw devra version-garder cette prise en charge du protocole et mapper les
événements vers le contrat de hook OpenClaw existant lorsque la sémantique est honnête.
Jusqu’à alors, les événements `before_compaction`, `after_compaction`, `llm_input`, et
`llm_output` d’OpenClaw sont des observations au niveau adaptateur, pas des captures octet pour octet
Lorsque de nouvelles versions de l’app-server Codex exposeront des événements de hook natifs pour le cycle de vie de Compaction et du modèle,
OpenClaw devra restreindre la prise en charge de ce protocole par version et mapper les
événements vers le contrat de hook OpenClaw existant lorsque la sémantique est fidèle.
Jusque-là, les événements `before_compaction`, `after_compaction`, `llm_input` et
`llm_output` d’OpenClaw sont des observations au niveau de l’adaptateur, et non des captures octet pour octet
de la requête interne de Codex ou de la charge utile de Compaction.
Les notifications d’app-server natives Codex `hook/started` et `hook/completed` sont
projetées en tant qu’événements d’agent `codex_app_server.hook` pour la trajectoire et le débogage.
Elles n’invoquent pas les hooks de Plugin OpenClaw.
## Outils, médias et Compaction
Le harnais Codex ne change que l’exécuteur d’agent embarqué de bas niveau.
Le harnais Codex modifie uniquement l’exécuteur d’agent intégré de bas niveau.
OpenClaw construit toujours la liste d’outils et reçoit les résultats d’outils dynamiques depuis le
harnais. Le texte, les images, la vidéo, la musique, le TTS, les approbations et la sortie des outils de messagerie
continuent de passer par le chemin normal de livraison OpenClaw.
OpenClaw continue de construire la liste d’outils et de recevoir les résultats des outils dynamiques depuis le
harnais. Le texte, les images, la vidéo, la musique, la synthèse vocale, les approbations et la sortie des outils de messagerie
continuent de passer par le chemin de livraison OpenClaw normal.
Les sollicitations d’approbation d’outil MCP Codex sont routées via le flux d’approbation de Plugin OpenClaw lorsque Codex marque `_meta.codex_approval_kind` comme
`"mcp_tool_call"`. Les prompts Codex `request_user_input` sont renvoyés dans le
chat d’origine, et le message de suivi suivant en file répond à cette demande native
du serveur au lieu d’être orienté comme contexte supplémentaire. Les autres demandes de sollicitation MCP échouent toujours en mode fermé par défaut.
Les sollicitations d’approbation d’outil MCP Codex sont acheminées via le flux d’approbation de Plugin d’OpenClaw lorsque Codex marque `_meta.codex_approval_kind` comme
`"mcp_tool_call"`. Les invites Codex `request_user_input` sont renvoyées vers le
chat d’origine, et le message de suivi suivant dans la file répond à cette requête native du
serveur au lieu d’être orienté comme contexte supplémentaire. Les autres requêtes de sollicitation MCP échouent toujours en mode fermé.
Lorsque le modèle sélectionné utilise le harnais Codex, la Compaction native de fil est déléguée au serveur d’application Codex. OpenClaw conserve un miroir de transcription pour l’historique de canal, la recherche, `/new`, `/reset`, et les futurs changements de modèle ou de harnais. Le
miroir inclut le prompt utilisateur, le texte final de l’assistant, et des enregistrements légers de raisonnement ou de plan Codex lorsque le serveur d’application les émet. Aujourd’hui, OpenClaw enregistre uniquement les signaux natifs de début et de fin de Compaction. Il n’expose pas encore un résumé de Compaction lisible par l’humain ni une liste auditable des entrées que Codex a conservées après la Compaction.
Lorsque le modèle sélectionné utilise le harnais Codex, la Compaction native du thread est déléguée à l’app-server Codex. OpenClaw conserve un miroir de transcription pour l’historique du canal,
la recherche, `/new`, `/reset` et les futurs changements de modèle ou de harnais. Le
miroir inclut l’invite utilisateur, le texte final de l’assistant et des enregistrements légers de raisonnement ou de plan Codex lorsque l’app-server les émet. Aujourd’hui, OpenClaw n’enregistre que les signaux de début et de fin de Compaction native. Il n’expose pas encore de
résumé de Compaction lisible par un humain ni de liste vérifiable des entrées que Codex
a conservées après la Compaction.
Parce que Codex possède le fil natif canonique, `tool_result_persist` ne
réécrit pas actuellement les enregistrements de résultats d’outils natifs Codex. Il ne s’applique que lorsque
OpenClaw écrit un résultat d’outil dans une transcription de session détenue par OpenClaw.
Comme Codex possède le thread natif canonique, `tool_result_persist` ne
réécrit pas actuellement les enregistrements de résultat d’outil natifs Codex. Il ne s’applique que lorsque
OpenClaw écrit un résultat d’outil dans une transcription de session gérée par OpenClaw.
La génération de médias n’exige pas PI. L’image, la vidéo, la musique, le PDF, le TTS et la
La génération de médias ne nécessite pas PI. La génération d’images, de vidéo, de musique, de PDF, la synthèse vocale et la
compréhension des médias continuent d’utiliser les paramètres de fournisseur/modèle correspondants tels que
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, et
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` et
`messages.tts`.
## Dépannage
**Codex n’apparaît pas dans `/model` :** activez `plugins.entries.codex.enabled`,
sélectionnez un modèle `openai/gpt-*` avec `embeddedHarness.runtime: "codex"` (ou une
ancienne référence `codex/*`), et vérifiez si `plugins.allow` exclut `codex`.
ancienne référence `codex/*`) et vérifiez si `plugins.allow` exclut `codex`.
**OpenClaw utilise PI au lieu de Codex :** si aucun harnais Codex ne revendique l’exécution,
OpenClaw peut utiliser PI comme backend de compatibilité. Définissez
`embeddedHarness.runtime: "codex"` pour forcer la sélection de Codex pendant les tests, ou
`embeddedHarness.fallback: "none"` pour échouer lorsqu’aucun harnais de Plugin ne correspond. Une fois
le serveur d’application Codex sélectionné, ses échecs remontent directement sans configuration de repli supplémentaire.
l’app-server Codex sélectionné, ses échecs remontent directement sans configuration de
repli supplémentaire.
**Le serveur d’application est rejeté :** mettez à jour Codex afin que le handshake du serveur d’application
signale la version `0.118.0` ou plus récente.
**L’app-server est rejeté :** mettez à niveau Codex afin que le handshake de l’app-server
signale la version `0.118.0` ou ultérieure.
**La discovery de modèles est lente :** réduisez `plugins.entries.codex.config.discovery.timeoutMs`
ou désactivez la discovery.
**La découverte des modèles est lente :** réduisez `plugins.entries.codex.config.discovery.timeoutMs`
ou désactivez la découverte.
**Le transport WebSocket échoue immédiatement :** vérifiez `appServer.url`, `authToken`,
et que le serveur d’application distant parle la même version de protocole de serveur d’application Codex.
et que l’app-server distant parle la même version du protocole app-server Codex.
**Un modèle non-Codex utilise PI :** c’est attendu sauf si vous avez forcé
`embeddedHarness.runtime: "codex"` (ou sélectionné une ancienne référence `codex/*`). Les références simples
`openai/gpt-*` et les autres références fournisseurs restent sur leur chemin normal de fournisseur.
`openai/gpt-*` et celles des autres fournisseurs restent sur leur chemin fournisseur normal.
## Lié
## Liens connexes
- [Plugins de harnais d’agent](/fr/plugins/sdk-agent-harness)
- [Fournisseurs de modèles](/fr/concepts/model-providers)
- [Référence de configuration](/fr/gateway/configuration-reference)
- [Testing](/fr/help/testing-live#live-codex-app-server-harness-smoke)
- [Tests](/fr/help/testing-live#live-codex-app-server-harness-smoke)

262
docs/fr/plugins/google-meet.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Vous souhaitez qu’un agent OpenClaw rejoigne un appel Google Meet
- Vous configurez Chrome, le node Chrome, ou Twilio comme transport Google Meet
summary: 'Plugin Google Meet : rejoindre des URL Meet explicites via Chrome ou Twilio avec des paramètres vocaux temps réel par défaut'
- Vous voulez qu’un agent OpenClaw rejoigne un appel Google Meet
- Vous configurez Chrome, le Node Chrome ou Twilio comme transport Google Meet
summary: 'Plugin Google Meet : rejoindre des URL Meet explicites via Chrome ou Twilio avec les valeurs par défaut de voix en temps réel'
title: Plugin Google Meet
x-i18n:
generated_at: "2026-04-24T07:22:23Z"
generated_at: "2026-04-24T08:57:23Z"
model: gpt-5.4
provider: openai
source_hash: f0bf06b7ab585bf2dc9dbf6d890e1954e89e4deea148380e350d2d7f4d954f5e
source_hash: 8d430a1f2d6ee7fc1d997ef388a2e0d2915a6475480343e7060edac799dfc027
source_path: plugins/google-meet.md
workflow: 15
---
@ -17,45 +17,41 @@ x-i18n:
Prise en charge des participants Google Meet pour OpenClaw.
Le plugin est explicite par conception :
Le Plugin est explicitement conçu ainsi :
- Il ne rejoint qu’une URL explicite `https://meet.google.com/...`.
- Il rejoint uniquement une URL explicite `https://meet.google.com/...`.
- La voix `realtime` est le mode par défaut.
- La voix temps réel peut rappeler l’agent OpenClaw complet lorsque du
raisonnement plus approfondi ou des outils sont nécessaires.
- La voix en temps réel peut rappeler l’agent OpenClaw complet lorsque des outils ou un raisonnement plus approfondi sont nécessaires.
- L’authentification commence comme un OAuth Google personnel ou un profil Chrome déjà connecté.
- Il n’y a pas d’annonce automatique de consentement.
- Il n’y a aucune annonce automatique de consentement.
- Le backend audio Chrome par défaut est `BlackHole 2ch`.
- Chrome peut s’exécuter localement ou sur un hôte node appairé.
- Twilio accepte un numéro d’appel ainsi qu’un PIN ou une séquence DTMF facultatifs.
- La commande CLI est `googlemeet` ; `meet` est réservée à des workflows plus larges
de téléconférence d’agent.
- Chrome peut s’exécuter localement ou sur un hôte Node appairé.
- Twilio accepte un numéro d’appel entrant avec un code PIN ou une séquence DTMF facultatifs.
- La commande CLI est `googlemeet` ; `meet` est réservé aux flux de téléconférence d’agent plus larges.
## Démarrage rapide
Installez les dépendances audio locales et assurez-vous que le fournisseur temps réel peut utiliser
OpenAI :
Installez les dépendances audio locales et assurez-vous que le fournisseur en temps réel peut utiliser OpenAI :
```bash
brew install blackhole-2ch sox
export OPENAI_API_KEY=sk-...
```
`blackhole-2ch` installe le périphérique audio virtuel `BlackHole 2ch`. L’installateur Homebrew
requiert un redémarrage avant que macOS n’expose le périphérique :
`blackhole-2ch` installe le périphérique audio virtuel `BlackHole 2ch`. Le programme d’installation de Homebrew nécessite un redémarrage avant que macOS n’expose le périphérique :
```bash
sudo reboot
```
Après le redémarrage, vérifiez les deux éléments :
Après le redémarrage, vérifiez les deux éléments :
```bash
system_profiler SPAudioDataType | grep -i BlackHole
command -v rec play
```
Activez le plugin :
Activez le Plugin :
```json5
{
@ -70,19 +66,19 @@ Activez le plugin :
}
```
Vérifiez la configuration :
Vérifiez la configuration :
```bash
openclaw googlemeet setup
```
Rejoignez une réunion :
Rejoignez une réunion :
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij
```
Ou laissez un agent rejoindre via l’outil `google_meet` :
Ou laissez un agent rejoindre la réunion via l’outil `google_meet` :
```json
{
@ -91,67 +87,57 @@ Ou laissez un agent rejoindre via l’outil `google_meet` :
}
```
Chrome rejoint avec le profil Chrome connecté. Dans Meet, choisissez `BlackHole 2ch` pour
le chemin micro/haut-parleur utilisé par OpenClaw. Pour un duplex audio propre, utilisez
des périphériques virtuels distincts ou un graphe de type Loopback ; un seul périphérique BlackHole suffit
pour un premier smoke test mais peut provoquer de l’écho.
Chrome rejoint la réunion en tant que profil Chrome connecté. Dans Meet, choisissez `BlackHole 2ch` pour le chemin microphone/haut-parleur utilisé par OpenClaw. Pour un audio duplex propre, utilisez des périphériques virtuels séparés ou un graphe de type Loopback ; un seul périphérique BlackHole suffit pour un premier test rapide, mais peut produire de l’écho.
### Gateway local + Chrome sous Parallels
### Gateway local + Chrome Parallels
Vous n’avez **pas** besoin d’un Gateway OpenClaw complet ni d’une clé API de modèle à l’intérieur d’une VM macOS
simplement pour que la VM héberge Chrome. Exécutez le Gateway et l’agent localement, puis exécutez un
hôte node dans la VM. Activez une fois le plugin inclus dans la VM pour que le node
annonce la commande Chrome :
Vous n’avez **pas** besoin d’un Gateway OpenClaw complet ni d’une clé API de modèle à l’intérieur d’une VM macOS uniquement pour faire de la VM l’hôte de Chrome. Exécutez le Gateway et l’agent localement, puis exécutez un hôte Node dans la VM. Activez une fois le Plugin intégré sur la VM afin que le Node annonce la commande Chrome :
Ce qui s’exécute où :
Ce qui s’exécute où :
- Hôte Gateway : Gateway OpenClaw, espace de travail agent, clés de modèle/API, fournisseur temps réel
et configuration du plugin Google Meet.
- VM macOS Parallels : CLI/node host OpenClaw, Google Chrome, SoX, BlackHole 2ch,
et un profil Chrome connecté à Google.
- Non nécessaire dans la VM : service Gateway, configuration d’agent, clé OpenAI/GPT, ou configuration
de fournisseur de modèle.
- Hôte Gateway : Gateway OpenClaw, espace de travail de l’agent, clés de modèle/API, fournisseur en temps réel et configuration du Plugin Google Meet.
- VM macOS Parallels : CLI/hôte Node OpenClaw, Google Chrome, SoX, BlackHole 2ch et un profil Chrome connecté à Google.
- Non requis dans la VM : service Gateway, configuration de l’agent, clé OpenAI/GPT ou configuration du fournisseur de modèle.
Installez les dépendances de la VM :
Installez les dépendances de la VM :
```bash
brew install blackhole-2ch sox
```
Redémarrez la VM après l’installation de BlackHole afin que macOS expose `BlackHole 2ch` :
Redémarrez la VM après l’installation de BlackHole afin que macOS expose `BlackHole 2ch` :
```bash
sudo reboot
```
Après le redémarrage, vérifiez que la VM voit le périphérique audio et les commandes SoX :
Après le redémarrage, vérifiez que la VM peut voir le périphérique audio et les commandes SoX :
```bash
system_profiler SPAudioDataType | grep -i BlackHole
command -v rec play
```
Installez ou mettez à jour OpenClaw dans la VM, puis activez-y le plugin inclus :
Installez ou mettez à jour OpenClaw dans la VM, puis activez-y le Plugin intégré :
```bash
openclaw plugins enable google-meet
```
Démarrez l’hôte node dans la VM :
Démarrez l’hôte Node dans la VM :
```bash
openclaw node run --host <gateway-host> --port 18789 --display-name parallels-macos
```
Si `<gateway-host>` est une IP LAN et que vous n’utilisez pas TLS, le node refuse le
WebSocket en clair sauf si vous activez explicitement ce réseau privé de confiance :
Si `<gateway-host>` est une IP LAN et que vous n’utilisez pas TLS, le Node refuse le WebSocket en texte clair sauf si vous l’autorisez explicitement pour ce réseau privé de confiance :
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
```
Utilisez la même variable d’environnement lorsque vous installez le node comme LaunchAgent :
Utilisez la même variable d’environnement lors de l’installation du Node comme LaunchAgent :
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -159,24 +145,22 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node restart
```
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` est une variable d’environnement de processus, pas un
paramètre `openclaw.json`. `openclaw node install` l’enregistre dans l’environnement du LaunchAgent
lorsqu’elle est présente sur la commande d’installation.
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` est un environnement de processus, pas un paramètre `openclaw.json`. `openclaw node install` l’enregistre dans l’environnement du LaunchAgent lorsqu’elle est présente sur la commande d’installation.
Approuvez le node depuis l’hôte Gateway :
Approuvez le Node depuis l’hôte Gateway :
```bash
openclaw devices list
openclaw devices approve <requestId>
```
Confirmez que le Gateway voit le node et qu’il annonce `googlemeet.chrome` :
Confirmez que le Gateway voit le Node et qu’il annonce `googlemeet.chrome` :
```bash
openclaw nodes status
```
Faites passer Meet par ce node sur l’hôte Gateway :
Acheminez Meet via ce Node sur l’hôte Gateway :
```json5
{
@ -201,7 +185,7 @@ Faites passer Meet par ce node sur l’hôte Gateway :
}
```
Vous pouvez maintenant rejoindre normalement depuis l’hôte Gateway :
Vous pouvez maintenant rejoindre la réunion normalement depuis l’hôte Gateway :
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij
@ -209,62 +193,40 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij
ou demander à l’agent d’utiliser l’outil `google_meet` avec `transport: "chrome-node"`.
Si `chromeNode.node` est omis, OpenClaw ne fait une sélection automatique que lorsqu’un seul
node connecté annonce `googlemeet.chrome`. Si plusieurs nodes capables sont
connectés, définissez `chromeNode.node` sur l’identifiant du node, le nom d’affichage ou l’IP distante.
Si `chromeNode.node` est omis, OpenClaw effectue une sélection automatique uniquement lorsqu’un seul Node connecté annonce `googlemeet.chrome`. Si plusieurs Nodes compatibles sont connectés, définissez `chromeNode.node` sur l’identifiant du Node, son nom d’affichage ou son IP distante.
Vérifications courantes en cas d’échec :
Vérifications courantes en cas d’échec :
- `No connected Google Meet-capable node` : démarrez `openclaw node run` dans la VM,
approuvez le pairing, et assurez-vous que `openclaw plugins enable google-meet` a bien été exécuté
dans la VM. Confirmez aussi que l’hôte Gateway autorise la commande node avec
`gateway.nodes.allowCommands: ["googlemeet.chrome"]`.
- `BlackHole 2ch audio device not found on the node` : installez `blackhole-2ch`
dans la VM puis redémarrez la VM.
- Chrome s’ouvre mais ne peut pas rejoindre : connectez-vous à Chrome dans la VM et confirmez que
ce profil peut rejoindre manuellement l’URL Meet.
- Pas de son : dans Meet, faites passer le micro/haut-parleur par le chemin du périphérique audio virtuel
utilisé par OpenClaw ; utilisez des périphériques virtuels séparés ou un routage de type Loopback
pour un duplex propre.
- `No connected Google Meet-capable node` : démarrez `openclaw node run` dans la VM, approuvez l’appairage et assurez-vous que `openclaw plugins enable google-meet` a bien été exécuté dans la VM. Confirmez aussi que l’hôte Gateway autorise la commande Node avec `gateway.nodes.allowCommands: ["googlemeet.chrome"]`.
- `BlackHole 2ch audio device not found on the node` : installez `blackhole-2ch` dans la VM et redémarrez la VM.
- Chrome s’ouvre mais ne peut pas rejoindre la réunion : connectez-vous à Chrome dans la VM et confirmez que ce profil peut rejoindre manuellement l’URL Meet.
- Pas d’audio : dans Meet, acheminez le microphone et le haut-parleur via le chemin de périphérique audio virtuel utilisé par OpenClaw ; utilisez des périphériques virtuels séparés ou un routage de type Loopback pour un audio duplex propre.
## Notes d’installation
Le mode par défaut Chrome realtime utilise deux outils externes :
Le mode Chrome en temps réel par défaut utilise deux outils externes :
- `sox` : utilitaire audio en ligne de commande. Le plugin utilise ses commandes `rec` et `play`
pour le pont audio G.711 mu-law 8 kHz par défaut.
- `blackhole-2ch` : pilote audio virtuel macOS. Il crée le périphérique audio `BlackHole 2ch`
par lequel Chrome/Meet peuvent être routés.
- `sox` : utilitaire audio en ligne de commande. Le Plugin utilise ses commandes `rec` et `play` pour le pont audio G.711 mu-law 8 kHz par défaut.
- `blackhole-2ch` : pilote audio virtuel macOS. Il crée le périphérique audio `BlackHole 2ch` par lequel Chrome/Meet peut être acheminé.
OpenClaw n’intègre ni ne redistribue aucun de ces deux packages. La documentation demande aux utilisateurs de
les installer comme dépendances hôtes via Homebrew. SoX est sous licence
`LGPL-2.0-only AND GPL-2.0-only` ; BlackHole est GPL-3.0. Si vous construisez un
installateur ou une appliance qui intègre BlackHole avec OpenClaw, examinez les
conditions de licence amont de BlackHole ou obtenez une licence séparée auprès d’Existential Audio.
OpenClaw ne fournit ni ne redistribue aucun de ces deux paquets. La documentation demande aux utilisateurs de les installer comme dépendances de l’hôte via Homebrew. SoX est sous licence `LGPL-2.0-only AND GPL-2.0-only` ; BlackHole est sous licence GPL-3.0. Si vous créez un programme d’installation ou une appliance qui intègre BlackHole avec OpenClaw, vérifiez les conditions de licence amont de BlackHole ou obtenez une licence distincte auprès de Existential Audio.
## Transports
### Chrome
Le transport Chrome ouvre l’URL Meet dans Google Chrome et rejoint avec le profil
Chrome connecté. Sur macOS, le plugin vérifie la présence de `BlackHole 2ch` avant le lancement.
S’il est configuré, il exécute aussi une commande de contrôle de santé du pont audio et une commande de démarrage
avant d’ouvrir Chrome. Utilisez `chrome` lorsque Chrome/l’audio résident sur l’hôte Gateway ;
utilisez `chrome-node` lorsque Chrome/l’audio résident sur un node appairé comme une VM macOS Parallels.
Le transport Chrome ouvre l’URL Meet dans Google Chrome et rejoint la réunion en tant que profil Chrome connecté. Sur macOS, le Plugin vérifie la présence de `BlackHole 2ch` avant le lancement. Si configuré, il exécute également une commande de vérification de santé du pont audio et une commande de démarrage avant d’ouvrir Chrome. Utilisez `chrome` lorsque Chrome/l’audio s’exécutent sur l’hôte Gateway ; utilisez `chrome-node` lorsque Chrome/l’audio s’exécutent sur un Node appairé, comme une VM macOS Parallels.
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node
```
Faites passer l’audio micro et haut-parleur de Chrome par le pont audio local OpenClaw.
Si `BlackHole 2ch` n’est pas installé, la jonction échoue avec une erreur de configuration
au lieu de rejoindre silencieusement sans chemin audio.
Acheminez l’audio microphone et haut-parleur de Chrome via le pont audio OpenClaw local. Si `BlackHole 2ch` n’est pas installé, la connexion échoue avec une erreur de configuration au lieu de rejoindre silencieusement sans chemin audio.
### Twilio
Le transport Twilio est un plan d’appel strict délégué au plugin Voice Call. Il
n’analyse pas les pages Meet pour extraire des numéros de téléphone.
Le transport Twilio est un plan de numérotation strict délégué au Plugin Voice Call. Il n’analyse pas les pages Meet pour y trouver des numéros de téléphone.
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -273,7 +235,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
--pin 123456
```
Utilisez `--dtmf-sequence` lorsque la réunion nécessite une séquence personnalisée :
Utilisez `--dtmf-sequence` lorsque la réunion nécessite une séquence personnalisée :
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -282,20 +244,17 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
--dtmf-sequence ww123456#
```
## OAuth et préflight
## OAuth et prévérification
L’accès à l’API Google Meet Media utilise d’abord un client OAuth personnel. Configurez
`oauth.clientId` et éventuellement `oauth.clientSecret`, puis exécutez :
L’accès à l’API média Google Meet utilise d’abord un client OAuth personnel. Configurez `oauth.clientId` et, facultativement, `oauth.clientSecret`, puis exécutez :
```bash
openclaw googlemeet auth login --json
```
La commande affiche un bloc de configuration `oauth` avec un jeton d’actualisation. Elle utilise PKCE,
un callback localhost sur `http://localhost:8085/oauth2callback`, et un flux manuel
copier/coller avec `--manual`.
La commande affiche un bloc de configuration `oauth` avec un jeton d’actualisation. Elle utilise PKCE, un rappel localhost sur `http://localhost:8085/oauth2callback` et un flux manuel de copier-coller avec `--manual`.
Ces variables d’environnement sont acceptées en repli :
Ces variables d’environnement sont acceptées comme solutions de secours :
- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` ou `GOOGLE_MEET_CLIENT_ID`
- `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` ou `GOOGLE_MEET_CLIENT_SECRET`
@ -306,33 +265,30 @@ Ces variables d’environnement sont acceptées en repli :
- `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` ou `GOOGLE_MEET_DEFAULT_MEETING`
- `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` ou `GOOGLE_MEET_PREVIEW_ACK`
Résolvez une URL Meet, un code, ou `spaces/{id}` via `spaces.get` :
Résolvez une URL Meet, un code ou `spaces/{id}` via `spaces.get` :
```bash
openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
```
Exécutez le préflight avant tout travail média :
Exécutez la prévérification avant le travail média :
```bash
openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij
```
Définissez `preview.enrollmentAcknowledged: true` uniquement après avoir confirmé que votre
projet Cloud, le principal OAuth et les participants à la réunion sont inscrits au Google
Workspace Developer Preview Program pour les API média Meet.
Définissez `preview.enrollmentAcknowledged: true` uniquement après avoir confirmé que votre projet Cloud, le principal OAuth et les participants à la réunion sont inscrits au Google Workspace Developer Preview Program pour les API média Meet.
## Configuration
Le chemin Chrome realtime courant n’a besoin que du plugin activé, de BlackHole, de SoX,
et d’une clé OpenAI :
Le chemin Chrome en temps réel courant nécessite seulement le Plugin activé, BlackHole, SoX et une clé OpenAI :
```bash
brew install blackhole-2ch sox
export OPENAI_API_KEY=sk-...
```
Définissez la configuration du plugin sous `plugins.entries.google-meet.config` :
Définissez la configuration du Plugin sous `plugins.entries.google-meet.config` :
```json5
{
@ -347,22 +303,21 @@ Définissez la configuration du plugin sous `plugins.entries.google-meet.config`
}
```
Valeurs par défaut :
Valeurs par défaut :
- `defaultTransport: "chrome"`
- `defaultMode: "realtime"`
- `chromeNode.node` : identifiant/nom/IP de node facultatif pour `chrome-node`
- `chromeNode.node` : identifiant/nom/IP du Node facultatif pour `chrome-node`
- `chrome.audioBackend: "blackhole-2ch"`
- `chrome.audioInputCommand` : commande SoX `rec` écrivant de l’audio
G.711 mu-law 8 kHz sur stdout
- `chrome.audioOutputCommand` : commande SoX `play` lisant de l’audio
G.711 mu-law 8 kHz depuis stdin
- `chrome.audioInputCommand` : commande SoX `rec` écrivant un audio G.711 mu-law 8 kHz vers stdout
- `chrome.audioOutputCommand` : commande SoX `play` lisant un audio G.711 mu-law 8 kHz depuis stdin
- `realtime.provider: "openai"`
- `realtime.toolPolicy: "safe-read-only"`
- `realtime.instructions` : réponses parlées brèves, avec
`openclaw_agent_consult` pour des réponses plus approfondies
- `realtime.instructions` : réponses parlées brèves, avec
`openclaw_agent_consult` pour les réponses plus approfondies
- `realtime.introMessage` : bref contrôle vocal de disponibilité lorsque le pont en temps réel se connecte ; définissez-le sur `""` pour rejoindre silencieusement
Surcharges facultatives :
Surcharges facultatives :
```json5
{
@ -377,11 +332,12 @@ Surcharges facultatives :
},
realtime: {
toolPolicy: "owner",
introMessage: "Say exactly: I'm here.",
},
}
```
Configuration Twilio uniquement :
Configuration Twilio uniquement :
```json5
{
@ -398,7 +354,7 @@ Configuration Twilio uniquement :
## Outil
Les agents peuvent utiliser l’outil `google_meet` :
Les agents peuvent utiliser l’outil `google_meet` :
```json
{
@ -409,61 +365,55 @@ Les agents peuvent utiliser l’outil `google_meet` :
}
```
Utilisez `transport: "chrome"` lorsque Chrome s’exécute sur l’hôte Gateway. Utilisez
`transport: "chrome-node"` lorsque Chrome s’exécute sur un node appairé comme une VM
Parallels. Dans les deux cas, le modèle temps réel et `openclaw_agent_consult` s’exécutent sur l’hôte
Gateway, donc les identifiants du modèle y restent.
Utilisez `transport: "chrome"` lorsque Chrome s’exécute sur l’hôte Gateway. Utilisez `transport: "chrome-node"` lorsque Chrome s’exécute sur un Node appairé, comme une VM Parallels. Dans les deux cas, le modèle en temps réel et `openclaw_agent_consult` s’exécutent sur l’hôte Gateway, de sorte que les identifiants du modèle y restent.
Utilisez `action: "status"` pour lister les sessions actives ou inspecter un ID de session. Utilisez
`action: "leave"` pour marquer une session comme terminée.
Utilisez `action: "status"` pour lister les sessions actives ou inspecter un identifiant de session. Utilisez `action: "speak"` avec `sessionId` et `message` pour faire parler immédiatement l’agent en temps réel. Utilisez `action: "leave"` pour marquer une session comme terminée.
```json
{
"action": "speak",
"sessionId": "meet_...",
"message": "Say exactly: I'm here and listening."
}
```
## Consultation d’agent en temps réel
Le mode Chrome realtime est optimisé pour une boucle vocale en direct. Le fournisseur
vocal temps réel entend l’audio de la réunion et parle via le pont audio configuré.
Lorsque le modèle temps réel a besoin d’un raisonnement plus approfondi, d’informations à jour,
ou des outils OpenClaw normaux, il peut appeler `openclaw_agent_consult`.
Le mode Chrome en temps réel est optimisé pour une boucle vocale en direct. Le fournisseur vocal en temps réel entend l’audio de la réunion et parle via le pont audio configuré. Lorsque le modèle en temps réel a besoin d’un raisonnement plus approfondi, d’informations actuelles ou des outils OpenClaw normaux, il peut appeler `openclaw_agent_consult`.
L’outil de consultation exécute en coulisses l’agent OpenClaw ordinaire avec le contexte
récent de transcription de réunion et renvoie une réponse concise parlée à la session
vocale temps réel. Le modèle vocal peut ensuite prononcer cette réponse dans la réunion.
L’outil de consultation exécute en arrière-plan l’agent OpenClaw standard avec le contexte récent de la transcription de la réunion, puis renvoie une réponse orale concise à la session vocale en temps réel. Le modèle vocal peut ensuite restituer cette réponse dans la réunion.
`realtime.toolPolicy` contrôle l’exécution de consultation :
`realtime.toolPolicy` contrôle l’exécution de la consultation :
- `safe-read-only` : expose l’outil de consultation et limite l’agent ordinaire à
`read`, `web_search`, `web_fetch`, `x_search`, `memory_search`, et
- `safe-read-only` : expose l’outil de consultation et limite l’agent standard à
`read`, `web_search`, `web_fetch`, `x_search`, `memory_search` et
`memory_get`.
- `owner` : expose l’outil de consultation et laisse l’agent ordinaire utiliser la politique normale d’outils de l’agent.
- `none` : n’expose pas l’outil de consultation au modèle vocal temps réel.
- `owner` : expose l’outil de consultation et permet à l’agent standard d’utiliser la politique d’outils normale de l’agent.
- `none` : n’expose pas l’outil de consultation au modèle vocal en temps réel.
La clé de session de consultation est limitée par session Meet, de sorte que les appels de consultation de suivi
puissent réutiliser le contexte des consultations précédentes pendant la même réunion.
La clé de session de consultation est limitée à chaque session Meet, afin que les appels de consultation de suivi puissent réutiliser le contexte de consultation précédent pendant la même réunion.
## Remarques
Pour forcer une vérification vocale de disponibilité après que Chrome a complètement rejoint l’appel :
L’API média officielle de Google Meet est orientée réception, donc parler dans un appel Meet
nécessite toujours un chemin de participant. Ce plugin garde cette frontière visible :
Chrome gère la participation via le navigateur et le routage audio local ; Twilio gère
la participation par appel téléphonique.
```bash
openclaw googlemeet speak meet_... "Say exactly: I'm here and listening."
```
Le mode Chrome realtime nécessite soit :
## Notes
- `chrome.audioInputCommand` plus `chrome.audioOutputCommand` : OpenClaw possède le
pont du modèle temps réel et fait passer l’audio G.711 mu-law 8 kHz entre ces
commandes et le fournisseur vocal temps réel sélectionné.
- `chrome.audioBridgeCommand` : une commande de pont externe possède tout le chemin
audio local et doit se terminer après avoir démarré ou validé son démon.
L’API média officielle de Google Meet est orientée réception, donc parler dans un appel Meet nécessite toujours un chemin de participation. Ce Plugin conserve cette limite visible : Chrome gère la participation via le navigateur et le routage audio local ; Twilio gère la participation par appel téléphonique.
Pour un duplex propre, faites passer la sortie Meet et le microphone Meet par des
périphériques virtuels séparés ou par un graphe de périphériques virtuels de type Loopback. Un seul périphérique
BlackHole partagé peut réinjecter les autres participants dans l’appel.
Le mode Chrome en temps réel nécessite soit :
`googlemeet leave` arrête le pont audio temps réel par paire de commandes pour les sessions
Chrome. Pour les sessions Twilio déléguées via le plugin Voice Call, cela
raccroche aussi l’appel vocal sous-jacent.
- `chrome.audioInputCommand` plus `chrome.audioOutputCommand` : OpenClaw gère le pont du modèle en temps réel et fait transiter l’audio G.711 mu-law 8 kHz entre ces commandes et le fournisseur vocal en temps réel sélectionné.
- `chrome.audioBridgeCommand` : une commande de pont externe gère l’ensemble du chemin audio local et doit se terminer après avoir démarré ou validé son démon.
## Articles connexes
Pour un audio duplex propre, acheminez la sortie Meet et le microphone Meet via des périphériques virtuels séparés ou un graphe de périphériques virtuels de type Loopback. Un seul périphérique BlackHole partagé peut réinjecter l’audio des autres participants dans l’appel.
`googlemeet speak` déclenche le pont audio en temps réel actif pour une session Chrome. `googlemeet leave` arrête ce pont. Pour les sessions Twilio déléguées via le Plugin Voice Call, `leave` raccroche également l’appel vocal sous-jacent.
## Liés
- [Plugin Voice Call](/fr/plugins/voice-call)
- [Mode Talk](/fr/nodes/talk)
- [Créer des plugins](/fr/plugins/building-plugins)
- [Mode conversation](/fr/nodes/talk)
- [Créer des Plugins](/fr/plugins/building-plugins)

465
docs/fr/plugins/sdk-migration.md
View File

@ -1,147 +1,112 @@
---
read_when:
- Vous voyez l’avertissement OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
- Vous voyez l’avertissement OPENCLAW_EXTENSION_API_DEPRECATED
- Vous mettez à jour un Plugin vers l’architecture moderne de plugins
- Vous maintenez un Plugin OpenClaw externe
- Vous voyez l’avertissement `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED`
- Vous voyez l’avertissement `OPENCLAW_EXTENSION_API_DEPRECATED`
- Vous mettez à jour un plugin vers l’architecture de Plugin moderne
- Vous maintenez un plugin OpenClaw externe
sidebarTitle: Migrate to SDK
summary: Migrer de la couche de compatibilité descendante héritée vers le SDK Plugin moderne
title: Migration du SDK Plugin
summary: Migrez de la couche de rétrocompatibilité héritée vers le SDK de Plugin moderne
title: Migration du SDK de Plugin
x-i18n:
generated_at: "2026-04-24T07:23:50Z"
generated_at: "2026-04-24T08:57:09Z"
model: gpt-5.4
provider: openai
source_hash: d1612fbdc0e472a0ba1ae310ceeca9c672afa5a7eba77637b94726ef1fedee87
source_hash: d1461ae8a7de0a802c9deb59f843e7d93d9d73bea22c27d837ca2db8ae9d14b7
source_path: plugins/sdk-migration.md
workflow: 15
---
OpenClaw est passé d’une couche large de compatibilité descendante à une architecture moderne de plugins
avec des imports ciblés et documentés. Si votre Plugin a été construit avant
la nouvelle architecture, ce guide vous aide à migrer.
OpenClaw est passé d’une large couche de rétrocompatibilité à une architecture de Plugin moderne avec des imports ciblés et documentés. Si votre plugin a été conçu avant la nouvelle architecture, ce guide vous aide à effectuer la migration.
## Ce qui change
L’ancien système de plugins fournissait deux surfaces très ouvertes qui permettaient aux plugins d’importer
tout ce dont ils avaient besoin depuis un seul point d’entrée :
L’ancien système de plugin fournissait deux surfaces très ouvertes qui permettaient aux plugins d’importer tout ce dont ils avaient besoin depuis un point d’entrée unique :
- **`openclaw/plugin-sdk/compat`** — un import unique qui réexportait des dizaines de
helpers. Il a été introduit pour garder les anciens plugins basés sur hooks fonctionnels pendant la construction de la
nouvelle architecture de plugins.
- **`openclaw/extension-api`** — un pont qui donnait aux plugins un accès direct à
des helpers côté hôte comme l’exécuteur d’agent embarqué.
- **`openclaw/plugin-sdk/compat`** — un import unique qui réexportait des dizaines de helpers. Il a été introduit pour permettre aux anciens plugins basés sur des hooks de continuer à fonctionner pendant la mise en place de la nouvelle architecture de plugin.
- **`openclaw/extension-api`** — un pont qui donnait aux plugins un accès direct à des helpers côté hôte comme l’exécuteur d’agent embarqué.
Ces deux surfaces sont maintenant **obsolètes**. Elles fonctionnent encore à l’exécution, mais les nouveaux
plugins ne doivent pas les utiliser, et les plugins existants doivent migrer avant que la prochaine
version majeure ne les supprime.
Ces deux surfaces sont désormais **obsolètes**. Elles fonctionnent encore à l’exécution, mais les nouveaux plugins ne doivent pas les utiliser, et les plugins existants doivent migrer avant que la prochaine version majeure ne les supprime.
OpenClaw ne supprime ni ne réinterprète un comportement de Plugin documenté dans le même
changement qui introduit un remplacement. Les changements de contrat cassants doivent d’abord passer
par un adaptateur de compatibilité, des diagnostics, de la documentation et une fenêtre de dépréciation.
Cela s’applique aux imports SDK, champs de manifest, API de configuration, hooks et au comportement d’enregistrement à l’exécution.
OpenClaw ne supprime ni ne réinterprète un comportement de plugin documenté dans le même changement qui introduit un remplacement. Les changements cassants de contrat doivent d’abord passer par un adaptateur de compatibilité, des diagnostics, de la documentation et une période de dépréciation. Cela s’applique aux imports du SDK, aux champs de manifeste, aux API de configuration, aux hooks et au comportement d’enregistrement à l’exécution.
<Warning>
La couche de compatibilité descendante sera supprimée dans une future version majeure.
Les plugins qui importent encore depuis ces surfaces casseront lorsque cela arrivera.
La couche de rétrocompatibilité sera supprimée dans une future version majeure.
Les plugins qui importent encore depuis ces surfaces cesseront de fonctionner à ce moment-là.
</Warning>
## Pourquoi cela a changé
L’ancienne approche posait problème :
L’ancienne approche posait des problèmes :
- **Démarrage lent** — importer un helper chargeait des dizaines de modules sans rapport
- **Dépendances circulaires** — les réexportations larges facilitaient la création de cycles d’import
- **Surface API floue** — aucun moyen de savoir quelles exportations étaient stables ou internes
- **Surface d’API peu claire** — aucun moyen de distinguer les exports stables des exports internes
Le SDK Plugin moderne corrige cela : chaque chemin d’import (`openclaw/plugin-sdk/\<subpath\>`)
est un petit module autonome avec un objectif clair et un contrat documenté.
Le SDK de Plugin moderne corrige cela : chaque chemin d’import (`openclaw/plugin-sdk/\<subpath\>`) est un module petit et autonome, avec un objectif clair et un contrat documenté.
Les couches de commodité héritées des fournisseurs pour les canaux intégrés ont également disparu. Les imports
tels que `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
les couches d’assistance marquées au nom du canal, et
`openclaw/plugin-sdk/telegram-core` étaient des raccourcis privés du mono-repo, pas
des contrats stables de Plugin. Utilisez à la place des sous-chemins génériques étroits du SDK. À l’intérieur de
l’espace de travail du Plugin intégré, gardez les helpers détenus par le fournisseur dans le propre
`api.ts` ou `runtime-api.ts` de ce Plugin.
Les points d’entrée de commodité hérités pour les fournisseurs des canaux intégrés ont également disparu. Les imports tels que `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, les points d’entrée de helpers associés à une marque de canal, et `openclaw/plugin-sdk/telegram-core` étaient des raccourcis privés du mono-repo, et non des contrats de plugin stables. Utilisez à la place des sous-chemins génériques et ciblés du SDK. À l’intérieur de l’espace de travail d’un plugin intégré, conservez les helpers appartenant au fournisseur dans le propre `api.ts` ou `runtime-api.ts` de ce plugin.
Exemples actuels de fournisseurs intégrés :
- Anthropic garde les helpers de flux spécifiques à Claude dans sa propre couche `api.ts` /
`contract-api.ts`
- OpenAI garde les constructeurs de fournisseur, les helpers de modèle par défaut, et les constructeurs
de fournisseur temps réel dans son propre `api.ts`
- OpenRouter garde le constructeur de fournisseur et les helpers d’onboarding/configuration dans son propre
`api.ts`
- Anthropic conserve les helpers de flux spécifiques à Claude dans son propre point d’entrée `api.ts` / `contract-api.ts`
- OpenAI conserve les constructeurs de fournisseur, les helpers de modèle par défaut et les constructeurs de fournisseur temps réel dans son propre `api.ts`
- OpenRouter conserve le constructeur de fournisseur et les helpers d’intégration/configuration dans son propre `api.ts`
## Politique de compatibilité
Pour les plugins externes, le travail de compatibilité suit cet ordre :
1. ajouter le nouveau contrat
2. garder l’ancien comportement câblé via un adaptateur de compatibilité
2. conserver l’ancien comportement via un adaptateur de compatibilité
3. émettre un diagnostic ou un avertissement qui nomme l’ancien chemin et son remplacement
4. couvrir les deux chemins dans les tests
5. documenter la dépréciation et le chemin de migration
6. supprimer seulement après la fenêtre de migration annoncée, généralement dans une version majeure
Si un champ de manifest est encore accepté, les auteurs de plugins peuvent continuer à l’utiliser jusqu’à ce
que la documentation et les diagnostics indiquent le contraire. Le nouveau code doit préférer le remplacement documenté, mais les plugins existants ne doivent pas casser pendant les versions mineures ordinaires.
Si un champ de manifeste est encore accepté, les auteurs de plugins peuvent continuer à l’utiliser jusqu’à ce que la documentation et les diagnostics indiquent le contraire. Le nouveau code doit privilégier le remplacement documenté, mais les plugins existants ne doivent pas cesser de fonctionner au cours de versions mineures ordinaires.
## Comment migrer
<Steps>
<Step title="Migrer les gestionnaires approval-native vers des faits de capacité">
Les plugins de canal capables d’approbation exposent maintenant le comportement d’approbation natif via
`approvalCapability.nativeRuntime` plus le registre partagé de contexte d’exécution.
<Step title="Migrer les handlers approval-native vers des faits de capacité">
Les plugins de canal capables de gérer les approbations exposent désormais le comportement d’approbation natif via `approvalCapability.nativeRuntime` ainsi que le registre partagé de contexte d’exécution.
Changements clés :
Principaux changements :
- Remplacer `approvalCapability.handler.loadRuntime(...)` par
`approvalCapability.nativeRuntime`
- Déplacer l’authentification/la livraison propres aux approbations hors du câblage hérité `plugin.auth` /
`plugin.approvals` vers `approvalCapability`
- `ChannelPlugin.approvals` a été supprimé du contrat public de plugin de canal ;
déplacez les champs delivery/native/render vers `approvalCapability`
- `plugin.auth` reste pour les flux de connexion/déconnexion du canal uniquement ; les
hooks d’authentification d’approbation à cet endroit ne sont plus lus par le cœur
- Enregistrer les objets d’exécution détenus par le canal tels que clients, jetons ou apps
Bolt via `openclaw/plugin-sdk/channel-runtime-context`
- N’envoyez pas d’avis de reroutage détenus par le Plugin depuis des gestionnaires d’approbation natifs ;
le cœur possède maintenant les avis routés ailleurs issus des résultats réels de livraison
- Lors du passage de `channelRuntime` à `createChannelManager(...)`, fournissez une
véritable surface `createPluginRuntime().channel`. Les stubs partiels sont rejetés.
- Remplacez `approvalCapability.handler.loadRuntime(...)` par `approvalCapability.nativeRuntime`
- Déplacez l’authentification/la livraison spécifiques aux approbations hors du câblage hérité `plugin.auth` / `plugin.approvals` vers `approvalCapability`
- `ChannelPlugin.approvals` a été supprimé du contrat public de plugin de canal ; déplacez les champs delivery/native/render vers `approvalCapability`
- `plugin.auth` reste utilisé uniquement pour les flux de connexion/déconnexion du canal ; les hooks d’authentification d’approbation à cet emplacement ne sont plus lus par le cœur
- Enregistrez les objets d’exécution appartenant au canal, tels que les clients, les jetons ou les apps Bolt, via `openclaw/plugin-sdk/channel-runtime-context`
- N’envoyez pas d’avis de redirection appartenant au plugin depuis les handlers d’approbation natifs ; le cœur gère désormais les avis routés ailleurs à partir des résultats réels de livraison
- Lors du passage de `channelRuntime` à `createChannelManager(...)`, fournissez une véritable surface `createPluginRuntime().channel`. Les stubs partiels sont rejetés.
Voir `/plugins/sdk-channel-plugins` pour la disposition actuelle de la
capacité d’approbation.
Consultez `/plugins/sdk-channel-plugins` pour la structure actuelle de la capacité d’approbation.
</Step>
<Step title="Auditer le comportement de repli du wrapper Windows">
Si votre Plugin utilise `openclaw/plugin-sdk/windows-spawn`, les wrappers Windows
`.cmd`/`.bat` non résolus échouent désormais en mode sécurisé par défaut, sauf si vous passez explicitement
`allowShellFallback: true`.
Si votre plugin utilise `openclaw/plugin-sdk/windows-spawn`, les wrappers Windows `.cmd`/`.bat` non résolus échouent désormais par défaut, sauf si vous passez explicitement `allowShellFallback: true`.
```typescript
// Avant
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });
// Après
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Ne définissez ceci que pour les appelants de compatibilité de confiance qui
// acceptent intentionnellement le repli médié par shell.
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
allowShellFallback: true,
});
```
Si votre appelant ne dépend pas intentionnellement du repli shell, ne définissez pas
`allowShellFallback` et gérez l’erreur levée à la place.
Si votre appelant ne dépend pas intentionnellement du repli vers le shell, ne définissez pas `allowShellFallback` et gérez plutôt l’erreur levée.
</Step>
<Step title="Trouver les imports obsolètes">
Recherchez dans votre Plugin les imports depuis l’une ou l’autre des surfaces obsolètes :
<Step title="Rechercher les imports obsolètes">
Recherchez dans votre plugin les imports provenant de l’une ou l’autre surface obsolète :
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -154,32 +119,31 @@ que la documentation et les diagnostics indiquent le contraire. Le nouveau code
Chaque export de l’ancienne surface correspond à un chemin d’import moderne spécifique :
```typescript
// Avant (couche de compatibilité descendante obsolète)
// Before (deprecated backwards-compatibility layer)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// Après (imports modernes ciblés)
// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
Pour les helpers côté hôte, utilisez le runtime de Plugin injecté au lieu d’importer
directement :
Pour les helpers côté hôte, utilisez le runtime de plugin injecté au lieu d’importer directement :
```typescript
// Avant (pont extension-api obsolète)
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// Après (runtime injecté)
// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
Le même motif s’applique aux autres helpers de pont hérités :
Le même modèle s’applique aux autres helpers de pont hérités :
| Ancien import | Équivalent moderne |
| --- | --- |
@ -189,11 +153,11 @@ que la documentation et les diagnostics indiquent le contraire. Le nouveau code
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| helpers de stockage de session | `api.runtime.agent.session.*` |
| helpers de magasin de session | `api.runtime.agent.session.*` |
</Step>
<Step title="Construire et tester">
<Step title="Compiler et tester">
```bash
pnpm build
pnpm test -- my-plugin/
@ -203,227 +167,216 @@ que la documentation et les diagnostics indiquent le contraire. Le nouveau code
## Référence des chemins d’import
<Accordion title="Table commune des chemins d’import">
| Chemin d’import | But | Exportations clés |
<Accordion title="Tableau des chemins d’import courants">
| Import path | Objectif | Exports clés |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper d’entrée de Plugin canonique | `definePluginEntry` |
| `plugin-sdk/core` | Réexportation globale héritée pour les définitions/constructeurs d’entrée de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Exportation du schéma de configuration racine | `OpenClawSchema` |
| `plugin-sdk/plugin-entry` | Helper d’entrée de plugin canonique | `definePluginEntry` |
| `plugin-sdk/core` | Réexportation parapluie héritée pour les définitions/builders d’entrée de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Export du schéma de configuration racine | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper d’entrée à fournisseur unique | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Définitions et constructeurs ciblés d’entrée de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helpers partagés d’assistant de configuration | Prompts de liste blanche, constructeurs d’état de configuration |
| `plugin-sdk/setup-runtime` | Helpers d’exécution au moment de la configuration | Adaptateurs de patch de configuration sûrs à l’import, helpers de lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, proxys de configuration délégués |
| `plugin-sdk/channel-core` | Définitions et builders ciblés pour les entrées de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helpers partagés d’assistant de configuration | Prompts de liste d’autorisation, builders d’état de configuration |
| `plugin-sdk/setup-runtime` | Helpers d’exécution au moment de la configuration | Adaptateurs de patch de configuration sûrs à importer, helpers de notes de recherche, `promptResolvedAllowFrom`, `splitSetupEntries`, proxys de configuration déléguée |
| `plugin-sdk/setup-adapter-runtime` | Helpers d’adaptateur de configuration | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helpers d’outillage de configuration | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helpers multi-compte | Helpers de liste/configuration/action-gate de compte |
| `plugin-sdk/account-id` | Helpers d’ID de compte | `DEFAULT_ACCOUNT_ID`, normalisation d’ID de compte |
| `plugin-sdk/account-core` | Helpers multi-comptes | Helpers de liste/configuration/action-gate de compte |
| `plugin-sdk/account-id` | Helpers d’identifiant de compte | `DEFAULT_ACCOUNT_ID`, normalisation d’identifiant de compte |
| `plugin-sdk/account-resolution` | Helpers de recherche de compte | Helpers de recherche de compte + repli par défaut |
| `plugin-sdk/account-helpers` | Helpers de compte étroits | Helpers de liste de compte/action de compte |
| `plugin-sdk/channel-setup` | Adaptateurs d’assistant de configuration | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/account-helpers` | Helpers de compte ciblés | Helpers de liste de comptes/action de compte |
| `plugin-sdk/channel-setup` | Adaptateurs d’assistant de configuration | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ainsi que `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitives d’appairage DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Câblage du préfixe de réponse + typing | `createChannelReplyPipeline` |
| `plugin-sdk/channel-reply-pipeline` | Câblage du préfixe de réponse + saisie | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Fabriques d’adaptateurs de configuration | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Constructeurs de schéma de configuration | Types de schéma de configuration de canal |
| `plugin-sdk/telegram-command-config` | Helpers de configuration de commande Telegram | Normalisation de nom de commande, troncature de description, validation de doublons/conflits |
| `plugin-sdk/channel-policy` | Résolution de politique groupe/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Helpers de cycle de vie d’état de compte et de flux draft | `createAccountStatusSink`, helpers de finalisation d’aperçu de brouillon |
| `plugin-sdk/inbound-envelope` | Helpers d’enveloppe entrante | Helpers partagés de construction de route + enveloppe |
| `plugin-sdk/inbound-reply-dispatch` | Helpers de réponse entrante | Helpers partagés d’enregistrement et de dispatch |
| `plugin-sdk/messaging-targets` | Analyse de cible de messagerie | Helpers d’analyse/correspondance de cible |
| `plugin-sdk/outbound-media` | Helpers de média sortant | Chargement partagé de médias sortants |
| `plugin-sdk/outbound-runtime` | Helpers d’exécution sortante | Helpers d’identité/de délégation d’envoi sortants et de planification de charge utile |
| `plugin-sdk/thread-bindings-runtime` | Helpers de liaison de fil | Helpers de cycle de vie et d’adaptateur de liaison de fil |
| `plugin-sdk/agent-media-payload` | Helpers hérités de charge utile média | Constructeur de charge utile média d’agent pour dispositions de champs héritées |
| `plugin-sdk/channel-config-schema` | Builders de schéma de configuration | Types de schéma de configuration de canal |
| `plugin-sdk/telegram-command-config` | Helpers de configuration des commandes Telegram | Normalisation des noms de commande, raccourcissement des descriptions, validation des doublons/conflits |
| `plugin-sdk/channel-policy` | Résolution de stratégie groupe/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Helpers de cycle de vie du statut de compte et de flux de brouillon | `createAccountStatusSink`, helpers de finalisation d’aperçu de brouillon |
| `plugin-sdk/inbound-envelope` | Helpers d’enveloppe entrante | Helpers partagés de route + construction d’enveloppe |
| `plugin-sdk/inbound-reply-dispatch` | Helpers de réponse entrante | Helpers partagés d’enregistrement et d’envoi |
| `plugin-sdk/messaging-targets` | Analyse des cibles de messagerie | Helpers d’analyse/correspondance des cibles |
| `plugin-sdk/outbound-media` | Helpers de média sortant | Chargement partagé des médias sortants |
| `plugin-sdk/outbound-runtime` | Helpers d’exécution sortante | Helpers d’identité sortante/délégué d’envoi et de planification de charge utile |
| `plugin-sdk/thread-bindings-runtime` | Helpers de liaison de thread | Helpers de cycle de vie et d’adaptateur des liaisons de thread |
| `plugin-sdk/agent-media-payload` | Helpers hérités de charge utile média | Builder de charge utile média d’agent pour des dispositions de champs héritées |
| `plugin-sdk/channel-runtime` | Shim de compatibilité obsolète | Utilitaires hérités d’exécution de canal uniquement |
| `plugin-sdk/channel-send-result` | Types de résultat d’envoi | Types de résultat de réponse |
| `plugin-sdk/runtime-store` | Stockage persistant de Plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helpers larges d’exécution | Helpers d’exécution/journalisation/sauvegarde/installation de Plugin |
| `plugin-sdk/runtime-env` | Helpers étroits d’environnement d’exécution | Helpers de logger/environnement d’exécution, délai d’expiration, nouvelle tentative et backoff |
| `plugin-sdk/plugin-runtime` | Helpers partagés d’exécution de Plugin | Helpers de commandes/hooks/http/interactif de Plugin |
| `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers partagés de pipeline de webhook/hook interne |
| `plugin-sdk/runtime-store` | Stockage persistant du plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helpers d’exécution étendus | Helpers d’exécution/journalisation/sauvegarde/installation de plugin |
| `plugin-sdk/runtime-env` | Helpers ciblés d’environnement d’exécution | Helpers de logger/environnement d’exécution, délai d’expiration, retry et backoff |
| `plugin-sdk/plugin-runtime` | Helpers partagés d’exécution de plugin | Helpers de commandes/hooks/http/interactif de plugin |
| `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers partagés de pipeline de Webhook/hook interne |
| `plugin-sdk/lazy-runtime` | Helpers d’exécution paresseuse | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helpers de processus | Helpers partagés d’exécution |
| `plugin-sdk/cli-runtime` | Helpers d’exécution CLI | Formatage de commandes, attentes, helpers de version |
| `plugin-sdk/gateway-runtime` | Helpers de Gateway | Helpers de client gateway et de patch d’état de canal |
| `plugin-sdk/cli-runtime` | Helpers d’exécution CLI | Formatage de commande, attentes, helpers de version |
| `plugin-sdk/gateway-runtime` | Helpers de Gateway | Helpers de client Gateway et de patch de statut de canal |
| `plugin-sdk/config-runtime` | Helpers de configuration | Helpers de chargement/écriture de configuration |
| `plugin-sdk/telegram-command-config` | Helpers de commande Telegram | Helpers de validation de commande Telegram à repli stable lorsque la surface de contrat Telegram intégrée n’est pas disponible |
| `plugin-sdk/approval-runtime` | Helpers de prompt d’approbation | Charge utile d’approbation exec/plugin, helpers de capacité/profil d’approbation, helpers natifs de routage/exécution d’approbation |
| `plugin-sdk/approval-auth-runtime` | Helpers d’authentification d’approbation | Résolution des approbateurs, auth d’action dans le même chat |
| `plugin-sdk/approval-client-runtime` | Helpers de client d’approbation | Helpers natifs de profil/filtre d’approbation exec |
| `plugin-sdk/telegram-command-config` | Helpers de commandes Telegram | Helpers de validation de commandes Telegram à repli stable lorsque la surface de contrat Telegram intégrée n’est pas disponible |
| `plugin-sdk/approval-runtime` | Helpers de prompt d’approbation | Charge utile d’approbation exec/plugin, helpers de capacité/profil d’approbation, helpers de routage/d’exécution d’approbation native |
| `plugin-sdk/approval-auth-runtime` | Helpers d’authentification d’approbation | Résolution de l’approbateur, authentification d’action dans le même chat |
| `plugin-sdk/approval-client-runtime` | Helpers de client d’approbation | Helpers de profil/filtre d’approbation exec native |
| `plugin-sdk/approval-delivery-runtime` | Helpers de livraison d’approbation | Adaptateurs de capacité/livraison d’approbation native |
| `plugin-sdk/approval-gateway-runtime` | Helpers de gateway d’approbation | Helper partagé de résolution gateway d’approbation |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers d’adaptateur d’approbation | Helpers légers de chargement d’adaptateur d’approbation native pour points d’entrée de canal chauds |
| `plugin-sdk/approval-handler-runtime` | Helpers de gestionnaire d’approbation | Helpers plus larges d’exécution de gestionnaire d’approbation ; préférez les couches plus étroites adapter/gateway lorsqu’elles suffisent |
| `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation | Helpers natifs de cible d’approbation/liaison de compte |
| `plugin-sdk/approval-gateway-runtime` | Helpers Gateway d’approbation | Helper partagé de résolution Gateway d’approbation |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers d’adaptateur d’approbation | Helpers légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal sensibles au temps de chargement |
| `plugin-sdk/approval-handler-runtime` | Helpers de handler d’approbation | Helpers plus larges d’exécution de handler d’approbation ; préférez les points d’entrée plus ciblés adapter/gateway lorsqu’ils suffisent |
| `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation | Helpers de liaison cible/compte d’approbation native |
| `plugin-sdk/approval-reply-runtime` | Helpers de réponse d’approbation | Helpers de charge utile de réponse d’approbation exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helpers de contexte d’exécution de canal | Helpers génériques d’enregistrement/récupération/surveillance du contexte d’exécution de canal |
| `plugin-sdk/channel-runtime-context` | Helpers de contexte d’exécution de canal | Helpers génériques register/get/watch du contexte d’exécution de canal |
| `plugin-sdk/security-runtime` | Helpers de sécurité | Helpers partagés de confiance, filtrage DM, contenu externe et collecte de secrets |
| `plugin-sdk/ssrf-policy` | Helpers de politique SSRF | Helpers de liste blanche d’hôte et de politique de réseau privé |
| `plugin-sdk/ssrf-runtime` | Helpers d’exécution SSRF | Helpers de pinned-dispatcher, récupération protégée, politique SSRF |
| `plugin-sdk/ssrf-policy` | Helpers de stratégie SSRF | Helpers de liste d’autorisation d’hôtes et de stratégie de réseau privé |
| `plugin-sdk/ssrf-runtime` | Helpers d’exécution SSRF | Helpers de répartiteur épinglé, fetch protégé, stratégie SSRF |
| `plugin-sdk/collection-runtime` | Helpers de cache borné | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helpers de filtrage diagnostique | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helpers de formatage d’erreur | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de graphe d’erreur |
| `plugin-sdk/diagnostic-runtime` | Helpers de filtrage des diagnostics | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helpers de formatage des erreurs | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de graphe d’erreurs |
| `plugin-sdk/fetch-runtime` | Helpers de fetch/proxy encapsulés | `resolveFetch`, helpers de proxy |
| `plugin-sdk/host-runtime` | Helpers de normalisation d’hôte | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helpers de nouvelle tentative | `RetryConfig`, `retryAsync`, exécuteurs de politique |
| `plugin-sdk/allow-from` | Formatage de liste blanche | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mapping d’entrée de liste blanche | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Filtrage de commande et helpers de surface de commande | `resolveControlCommandGate`, helpers d’autorisation d’expéditeur, helpers de registre de commandes |
| `plugin-sdk/command-status` | Moteurs de rendu d’état/aide de commande | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Analyse d’entrée secrète | Helpers d’entrée secrète |
| `plugin-sdk/webhook-ingress` | Helpers de requête webhook | Utilitaires de cible webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de garde du corps de requête webhook | Helpers de lecture/limite du corps de requête |
| `plugin-sdk/reply-runtime` | Exécution partagée de réponse | Dispatch entrant, Heartbeat, planificateur de réponse, segmentation |
| `plugin-sdk/reply-dispatch-runtime` | Helpers étroits de dispatch de réponse | Helpers de finalisation + dispatch fournisseur |
| `plugin-sdk/reply-history` | Helpers d’historique de réponse | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Planification de référence de réponse | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers de segmentation de réponse | Helpers de segmentation texte/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de stockage de session | Helpers de chemin de stockage + updated-at |
| `plugin-sdk/state-paths` | Helpers de chemins d’état | Helpers de répertoire d’état et d’OAuth |
| `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, exécuteurs de stratégie |
| `plugin-sdk/allow-from` | Formatage de liste d’autorisation | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mappage des entrées de liste d’autorisation | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Helpers de filtrage de commande et de surface de commande | `resolveControlCommandGate`, helpers d’autorisation d’expéditeur, helpers de registre de commandes |
| `plugin-sdk/command-status` | Rendus de statut/aide des commandes | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Analyse des entrées de secret | Helpers d’entrée de secret |
| `plugin-sdk/webhook-ingress` | Helpers de requête Webhook | Utilitaires de cible Webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de garde du corps de requête Webhook | Helpers de lecture/limitation du corps de requête |
| `plugin-sdk/reply-runtime` | Exécution partagée des réponses | Envoi entrant, Heartbeat, planificateur de réponse, fragmentation |
| `plugin-sdk/reply-dispatch-runtime` | Helpers ciblés d’envoi de réponse | Finalisation, envoi au fournisseur et helpers de libellé de conversation |
| `plugin-sdk/reply-history` | Helpers d’historique des réponses | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Planification des références de réponse | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers de fragmentation des réponses | Helpers de fragmentation texte/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de magasin de session | Helpers de chemin de magasin + date de mise à jour |
| `plugin-sdk/state-paths` | Helpers de chemins d’état | Helpers de répertoire d’état et OAuth |
| `plugin-sdk/routing` | Helpers de routage/clé de session | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalisation de clé de session |
| `plugin-sdk/status-helpers` | Helpers d’état de canal | Constructeurs de résumé d’état de canal/compte, valeurs par défaut d’état d’exécution, helpers de métadonnées de problème |
| `plugin-sdk/target-resolver-runtime` | Helpers de résolveur de cible | Helpers partagés de résolveur de cible |
| `plugin-sdk/status-helpers` | Helpers de statut de canal | Builders de résumé de statut de canal/compte, valeurs par défaut d’état d’exécution, helpers de métadonnées de problème |
| `plugin-sdk/target-resolver-runtime` | Helpers de résolution de cible | Helpers partagés de résolution de cible |
| `plugin-sdk/string-normalization-runtime` | Helpers de normalisation de chaîne | Helpers de normalisation de slug/chaîne |
| `plugin-sdk/request-url` | Helpers d’URL de requête | Extraire des URL chaîne à partir d’entrées de type requête |
| `plugin-sdk/run-command` | Helpers de commande temporisée | Exécuteur de commande temporisée avec stdout/stderr normalisés |
| `plugin-sdk/param-readers` | Lecteurs de paramètres | Lecteurs de paramètres communs d’outil/CLI |
| `plugin-sdk/tool-payload` | Extraction de charge utile d’outil | Extraire des charges utiles normalisées d’objets résultat d’outil |
| `plugin-sdk/tool-send` | Extraction d’envoi d’outil | Extraire les champs canoniques de cible d’envoi à partir des arguments d’outil |
| `plugin-sdk/request-url` | Helpers d’URL de requête | Extraire des URL de chaîne depuis des entrées de type requête |
| `plugin-sdk/run-command` | Helpers de commande temporisée | Exécuteur de commande temporisée avec `stdout`/`stderr` normalisés |
| `plugin-sdk/param-readers` | Lecteurs de paramètres | Lecteurs de paramètres d’outil/CLI communs |
| `plugin-sdk/tool-payload` | Extraction de charge utile d’outil | Extraire des charges utiles normalisées depuis des objets de résultat d’outil |
| `plugin-sdk/tool-send` | Extraction d’envoi d’outil | Extraire des champs de cible d’envoi canoniques depuis les arguments d’outil |
| `plugin-sdk/temp-path` | Helpers de chemin temporaire | Helpers partagés de chemin temporaire de téléchargement |
| `plugin-sdk/logging-core` | Helpers de journalisation | Logger de sous-système et helpers de caviardage |
| `plugin-sdk/markdown-table-runtime` | Helpers de tableau Markdown | Helpers de mode tableau Markdown |
| `plugin-sdk/logging-core` | Helpers de journalisation | Helpers de logger de sous-système et de masquage |
| `plugin-sdk/markdown-table-runtime` | Helpers de tableau Markdown | Helpers de mode de tableau Markdown |
| `plugin-sdk/reply-payload` | Types de réponse de message | Types de charge utile de réponse |
| `plugin-sdk/provider-setup` | Helpers ciblés de configuration de fournisseur local/auto-hébergé | Helpers de découverte/configuration de fournisseur auto-hébergé |
| `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur auto-hébergé compatible OpenAI | Les mêmes helpers de découverte/configuration de fournisseur auto-hébergé |
| `plugin-sdk/provider-auth-runtime` | Helpers d’authentification fournisseur à l’exécution | Helpers de résolution de clé API à l’exécution |
| `plugin-sdk/provider-auth-api-key` | Helpers de configuration de clé API fournisseur | Helpers d’onboarding/écriture de profil de clé API |
| `plugin-sdk/provider-auth-result` | Helpers de résultat d’authentification fournisseur | Constructeur standard de résultat d’authentification OAuth |
| `plugin-sdk/provider-auth-login` | Helpers de connexion interactive fournisseur | Helpers partagés de connexion interactive |
| `plugin-sdk/provider-selection-runtime` | Helpers de sélection de fournisseur | Sélection de fournisseur configuré ou automatique et fusion de configuration brute de fournisseur |
| `plugin-sdk/provider-env-vars` | Helpers de variables d’environnement fournisseur | Helpers de recherche de variables d’environnement d’authentification fournisseur |
| `plugin-sdk/provider-model-shared` | Helpers partagés de modèle/relecture fournisseur | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de relecture, helpers de point de terminaison fournisseur, et helpers de normalisation d’ID de modèle |
| `plugin-sdk/provider-catalog-shared` | Helpers partagés de catalogue fournisseur | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches d’onboarding fournisseur | Helpers de configuration d’onboarding |
| `plugin-sdk/provider-http` | Helpers HTTP fournisseur | Helpers génériques HTTP/capacités de point de terminaison fournisseur, y compris les helpers de formulaire multipart pour transcription audio |
| `plugin-sdk/provider-web-fetch` | Helpers web-fetch fournisseur | Helpers d’enregistrement/cache de fournisseur web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers de configuration web-search fournisseur | Helpers étroits de configuration/web-search/identifiants pour les fournisseurs qui n’ont pas besoin du câblage d’activation de Plugin |
| `plugin-sdk/provider-web-search-contract` | Helpers de contrat web-search fournisseur | Helpers étroits de contrat de configuration/web-search/identifiants tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d’identifiants limités par périmètre |
| `plugin-sdk/provider-web-search` | Helpers web-search fournisseur | Helpers d’enregistrement/cache/exécution de fournisseur web-search |
| `plugin-sdk/provider-tools` | Helpers de compatibilité outil/schéma fournisseur | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helpers d’utilisation fournisseur | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, et autres helpers d’utilisation fournisseur |
| `plugin-sdk/provider-stream` | Helpers d’enrobage de flux fournisseur | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types d’enrobage de flux, et helpers partagés d’enrobage Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helpers de transport fournisseur | Helpers natifs de transport fournisseur tels que récupération protégée, transformations de messages de transport, et flux d’événements de transport inscriptibles |
| `plugin-sdk/keyed-async-queue` | File asynchrone ordonnée | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helpers média partagés | Helpers de récupération/transformation/stockage média plus constructeurs de charge utile média |
| `plugin-sdk/media-generation-runtime` | Helpers partagés de génération média | Helpers partagés de basculement, sélection de candidats, et messagerie de modèle manquant pour la génération d’image/vidéo/musique |
| `plugin-sdk/media-understanding` | Helpers de compréhension média | Types de fournisseur de compréhension média plus exportations d’helpers image/audio orientées fournisseur |
| `plugin-sdk/text-runtime` | Helpers texte partagés | Retrait du texte visible par l’assistant, helpers de rendu/segmentation/tableau Markdown, helpers de caviardage, helpers de balises de directive, utilitaires de texte sûr, et helpers associés de texte/journalisation |
| `plugin-sdk/text-chunking` | Helpers de segmentation de texte | Helper de segmentation de texte sortant |
| `plugin-sdk/speech` | Helpers de parole | Types de fournisseur de parole plus helpers orientés fournisseur pour directives, registre et validation |
| `plugin-sdk/speech-core` | Cœur partagé de parole | Types de fournisseur de parole, registre, directives, normalisation |
| `plugin-sdk/realtime-transcription` | Helpers de transcription temps réel | Types de fournisseur, helpers de registre, et helper partagé de session WebSocket |
| `plugin-sdk/realtime-voice` | Helpers de voix temps réel | Types de fournisseur, helpers de registre/résolution, et helpers de session bridge |
| `plugin-sdk/image-generation-core` | Cœur partagé de génération d’image | Types de génération d’image, helpers de basculement, d’authentification et de registre |
| `plugin-sdk/music-generation` | Helpers de génération musicale | Types de fournisseur/requête/résultat de génération musicale |
| `plugin-sdk/music-generation-core` | Cœur partagé de génération musicale | Types de génération musicale, helpers de basculement, recherche de fournisseur et analyse de référence de modèle |
| `plugin-sdk/video-generation` | Helpers de génération vidéo | Types de fournisseur/requête/résultat de génération vidéo |
| `plugin-sdk/video-generation-core` | Cœur partagé de génération vidéo | Types de génération vidéo, helpers de basculement, recherche de fournisseur et analyse de référence de modèle |
| `plugin-sdk/interactive-runtime` | Helpers de réponse interactive | Normalisation/réduction de charge utile de réponse interactive |
| `plugin-sdk/channel-config-primitives` | Primitives de configuration de canal | Primitives étroites de schéma de configuration de canal |
| `plugin-sdk/channel-config-writes` | Helpers d’écriture de configuration de canal | Helpers d’autorisation d’écriture de configuration de canal |
| `plugin-sdk/channel-plugin-common` | Prélude partagé de canal | Exportations de prélude partagé de plugin de canal |
| `plugin-sdk/channel-status` | Helpers d’état de canal | Helpers partagés d’instantané/résumé d’état de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de configuration de liste blanche | Helpers d’édition/lecture de configuration de liste blanche |
| `plugin-sdk/group-access` | Helpers d’accès groupe | Helpers partagés de décision d’accès groupe |
| `plugin-sdk/direct-dm` | Helpers de DM direct | Helpers partagés d’authentification/garde DM direct |
| `plugin-sdk/extension-shared` | Helpers partagés d’extension | Primitives passives d’aide de canal/état et de proxy ambiant |
| `plugin-sdk/webhook-targets` | Helpers de cible webhook | Registre de cible webhook et helpers d’installation de route |
| `plugin-sdk/webhook-path` | Helpers de chemin webhook | Helpers de normalisation de chemin webhook |
| `plugin-sdk/web-media` | Helpers média web partagés | Helpers de chargement média distant/local |
| `plugin-sdk/zod` | Réexportation Zod | `zod` réexporté pour les consommateurs du SDK Plugin |
| `plugin-sdk/memory-core` | Helpers intégrés memory-core | Surface d’assistance memory manager/config/fichier/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Façade d’exécution du moteur mémoire | Façade d’exécution index/search de mémoire |
| `plugin-sdk/memory-core-host-engine-foundation` | Moteur fondation hôte mémoire | Exportations du moteur fondation hôte mémoire |
| `plugin-sdk/memory-core-host-engine-embeddings` | Moteur embeddings hôte mémoire | Contrats d’embedding mémoire, accès registre, fournisseur local, et helpers génériques batch/distants ; les fournisseurs distants concrets vivent dans leurs plugins propriétaires |
| `plugin-sdk/memory-core-host-engine-qmd` | Moteur QMD hôte mémoire | Exportations du moteur QMD hôte mémoire |
| `plugin-sdk/memory-core-host-engine-storage` | Moteur stockage hôte mémoire | Exportations du moteur stockage hôte mémoire |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux hôte mémoire | Helpers multimodaux hôte mémoire |
| `plugin-sdk/memory-core-host-query` | Helpers de requête hôte mémoire | Helpers de requête hôte mémoire |
| `plugin-sdk/memory-core-host-secret` | Helpers de secret hôte mémoire | Helpers de secret hôte mémoire |
| `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements hôte mémoire | Helpers de journal d’événements hôte mémoire |
| `plugin-sdk/memory-core-host-status` | Helpers d’état hôte mémoire | Helpers d’état hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-cli` | Exécution CLI hôte mémoire | Helpers d’exécution CLI hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-core` | Exécution core hôte mémoire | Helpers d’exécution core hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/exécution hôte mémoire | Helpers de fichier/exécution hôte mémoire |
| `plugin-sdk/memory-host-core` | Alias d’exécution core hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d’exécution core hôte mémoire |
| `plugin-sdk/memory-host-events` | Alias de journal d’événements hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements hôte mémoire |
| `plugin-sdk/memory-host-files` | Alias de fichier/exécution hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/exécution hôte mémoire |
| `plugin-sdk/memory-host-markdown` | Helpers Markdown gérés | Helpers partagés de markdown géré pour les plugins adjacents à la mémoire |
| `plugin-sdk/memory-host-search` | Façade de recherche Active Memory | Façade d’exécution paresseuse du gestionnaire de recherche active-memory |
| `plugin-sdk/memory-host-status` | Alias d’état hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d’état hôte mémoire |
| `plugin-sdk/memory-lancedb` | Helpers intégrés memory-lancedb | Surface d’assistance memory-lancedb |
| `plugin-sdk/testing` | Utilitaires de test | Helpers de test et mocks |
| `plugin-sdk/provider-setup` | Helpers organisés de configuration de fournisseur local/autohébergé | Helpers de découverte/configuration de fournisseur autohébergé |
| `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur autohébergé compatible OpenAI | Les mêmes helpers de découverte/configuration de fournisseur autohébergé |
| `plugin-sdk/provider-auth-runtime` | Helpers d’authentification d’exécution du fournisseur | Helpers de résolution de clé API à l’exécution |
| `plugin-sdk/provider-auth-api-key` | Helpers de configuration de clé API du fournisseur | Helpers d’intégration/écriture de profil de clé API |
| `plugin-sdk/provider-auth-result` | Helpers de résultat d’authentification du fournisseur | Builder standard de résultat d’authentification OAuth |
| `plugin-sdk/provider-auth-login` | Helpers de connexion interactive du fournisseur | Helpers partagés de connexion interactive |
| `plugin-sdk/provider-selection-runtime` | Helpers de sélection de fournisseur | Sélection du fournisseur configuré ou automatique et fusion de configuration brute de fournisseur |
| `plugin-sdk/provider-env-vars` | Helpers de variables d’environnement du fournisseur | Helpers de recherche de variable d’environnement d’authentification du fournisseur |
| `plugin-sdk/provider-model-shared` | Helpers partagés de modèle/relecture du fournisseur | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders partagés de stratégie de relecture, helpers de point de terminaison du fournisseur et helpers de normalisation d’identifiant de modèle |
| `plugin-sdk/provider-catalog-shared` | Helpers partagés de catalogue de fournisseur | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches d’intégration du fournisseur | Helpers de configuration d’intégration |
| `plugin-sdk/provider-http` | Helpers HTTP du fournisseur | Helpers génériques de capacité HTTP/point de terminaison du fournisseur, y compris les helpers de formulaire multipart pour la transcription audio |
| `plugin-sdk/provider-web-fetch` | Helpers web-fetch du fournisseur | Helpers d’enregistrement/cache de fournisseur web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers de configuration de recherche web du fournisseur | Helpers ciblés de configuration/identifiants de recherche web pour les fournisseurs qui n’ont pas besoin du câblage d’activation du plugin |
| `plugin-sdk/provider-web-search-contract` | Helpers de contrat de recherche web du fournisseur | Helpers ciblés de contrat de configuration/identifiants de recherche web tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` et des setters/getters d’identifiants à portée limitée |
| `plugin-sdk/provider-web-search` | Helpers de recherche web du fournisseur | Helpers d’enregistrement/cache/exécution de fournisseur de recherche web |
| `plugin-sdk/provider-tools` | Helpers de compatibilité outil/schéma du fournisseur | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et helpers de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helpers d’utilisation du fournisseur | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` et autres helpers d’utilisation du fournisseur |
| `plugin-sdk/provider-stream` | Helpers d’enveloppe de flux du fournisseur | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types d’enveloppe de flux, et helpers partagés d’enveloppe Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helpers de transport du fournisseur | Helpers de transport natif du fournisseur tels que fetch protégé, transformations de messages de transport et flux d’événements de transport inscriptibles |
| `plugin-sdk/keyed-async-queue` | File asynchrone ordonnée | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helpers média partagés | Helpers de récupération/transformation/stockage de média ainsi que builders de charge utile média |
| `plugin-sdk/media-generation-runtime` | Helpers partagés de génération de média | Helpers partagés de basculement, sélection de candidats et messages de modèle manquant pour la génération d’image/vidéo/musique |
| `plugin-sdk/media-understanding` | Helpers de compréhension des médias | Types de fournisseur de compréhension des médias ainsi qu’exports de helpers image/audio destinés aux fournisseurs |
| `plugin-sdk/text-runtime` | Helpers texte partagés | Suppression du texte visible par l’assistant, helpers de rendu/fragmentation/tableau markdown, helpers de masquage, helpers de balise de directive, utilitaires de texte sûr et helpers associés de texte/journalisation |
| `plugin-sdk/text-chunking` | Helpers de fragmentation du texte | Helper de fragmentation de texte sortant |
| `plugin-sdk/speech` | Helpers de parole | Types de fournisseur de parole ainsi que helpers de directive, registre et validation destinés aux fournisseurs |
| `plugin-sdk/speech-core` | Cœur partagé de la parole | Types de fournisseur de parole, registre, directives, normalisation |
| `plugin-sdk/realtime-transcription` | Helpers de transcription temps réel | Types de fournisseur, helpers de registre et helper partagé de session WebSocket |
| `plugin-sdk/realtime-voice` | Helpers de voix temps réel | Types de fournisseur, helpers de registre/résolution et helpers de session de pont |
| `plugin-sdk/image-generation-core` | Cœur partagé de génération d’image | Types de génération d’image, helpers de basculement, d’authentification et de registre |
| `plugin-sdk/music-generation` | Helpers de génération musicale | Types de fournisseur/requête/résultat de génération musicale |
| `plugin-sdk/music-generation-core` | Cœur partagé de génération musicale | Types de génération musicale, helpers de basculement, recherche de fournisseur et analyse de model-ref |
| `plugin-sdk/video-generation` | Helpers de génération vidéo | Types de fournisseur/requête/résultat de génération vidéo |
| `plugin-sdk/video-generation-core` | Cœur partagé de génération vidéo | Types de génération vidéo, helpers de basculement, recherche de fournisseur et analyse de model-ref |
| `plugin-sdk/interactive-runtime` | Helpers de réponse interactive | Normalisation/réduction de charge utile de réponse interactive |
| `plugin-sdk/channel-config-primitives` | Primitives de configuration de canal | Primitives ciblées de config-schema de canal |
| `plugin-sdk/channel-config-writes` | Helpers d’écriture de configuration de canal | Helpers d’autorisation d’écriture de configuration de canal |
| `plugin-sdk/channel-plugin-common` | Prélude de canal partagé | Exports de prélude de plugin de canal partagé |
| `plugin-sdk/channel-status` | Helpers de statut de canal | Helpers partagés d’instantané/résumé de statut de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de configuration de liste d’autorisation | Helpers de lecture/édition de configuration de liste d’autorisation |
| `plugin-sdk/group-access` | Helpers d’accès de groupe | Helpers partagés de décision d’accès de groupe |
| `plugin-sdk/direct-dm` | Helpers de DM direct | Helpers partagés d’authentification/garde de DM direct |
| `plugin-sdk/extension-shared` | Helpers partagés d’extension | Primitives de helpers de canal passif/statut et de proxy ambiant |
| `plugin-sdk/webhook-targets` | Helpers de cible Webhook | Registre de cibles Webhook et helpers d’installation de route |
| `plugin-sdk/webhook-path` | Helpers de chemin Webhook | Helpers de normalisation de chemin Webhook |
| `plugin-sdk/web-media` | Helpers web media partagés | Helpers de chargement de média distant/local |
| `plugin-sdk/zod` | Réexportation de Zod | `zod` réexporté pour les consommateurs du SDK de Plugin |
| `plugin-sdk/memory-core` | Helpers intégrés memory-core | Surface de helpers du gestionnaire/configuration/fichier/CLI de mémoire |
| `plugin-sdk/memory-core-engine-runtime` | Façade d’exécution du moteur mémoire | Façade d’exécution d’indexation/recherche mémoire |
| `plugin-sdk/memory-core-host-engine-foundation` | Moteur de fondation de l’hôte mémoire | Exports du moteur de fondation de l’hôte mémoire |
| `plugin-sdk/memory-core-host-engine-embeddings` | Moteur d’embeddings de l’hôte mémoire | Contrats d’embeddings mémoire, accès au registre, fournisseur local et helpers génériques de lot/distant ; les fournisseurs distants concrets vivent dans leurs plugins propriétaires |
| `plugin-sdk/memory-core-host-engine-qmd` | Moteur QMD de l’hôte mémoire | Exports du moteur QMD de l’hôte mémoire |
| `plugin-sdk/memory-core-host-engine-storage` | Moteur de stockage de l’hôte mémoire | Exports du moteur de stockage de l’hôte mémoire |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux de l’hôte mémoire | Helpers multimodaux de l’hôte mémoire |
| `plugin-sdk/memory-core-host-query` | Helpers de requête de l’hôte mémoire | Helpers de requête de l’hôte mémoire |
| `plugin-sdk/memory-core-host-secret` | Helpers de secret de l’hôte mémoire | Helpers de secret de l’hôte mémoire |
| `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements de l’hôte mémoire | Helpers de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-core-host-status` | Helpers de statut de l’hôte mémoire | Helpers de statut de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-cli` | Exécution CLI de l’hôte mémoire | Helpers d’exécution CLI de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-core` | Exécution cœur de l’hôte mémoire | Helpers d’exécution cœur de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/exécution de l’hôte mémoire | Helpers de fichier/exécution de l’hôte mémoire |
| `plugin-sdk/memory-host-core` | Alias d’exécution cœur de l’hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers d’exécution cœur de l’hôte mémoire |
| `plugin-sdk/memory-host-events` | Alias de journal d’événements de l’hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-host-files` | Alias de fichier/exécution de l’hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/exécution de l’hôte mémoire |
| `plugin-sdk/memory-host-markdown` | Helpers de markdown géré | Helpers partagés de markdown géré pour les plugins adjacents à la mémoire |
| `plugin-sdk/memory-host-search` | Façade de recherche Active Memory | Façade d’exécution paresseuse du gestionnaire de recherche Active Memory |
| `plugin-sdk/memory-host-status` | Alias de statut de l’hôte mémoire | Alias neutre vis-à-vis du fournisseur pour les helpers de statut de l’hôte mémoire |
| `plugin-sdk/memory-lancedb` | Helpers intégrés memory-lancedb | Surface de helpers memory-lancedb |
| `plugin-sdk/testing` | Utilitaires de test | Helpers de test et mocks |
</Accordion>
Ce tableau est volontairement le sous-ensemble commun de migration, et non la surface complète du SDK.
La liste complète des plus de 200 points d’entrée se trouve dans
`scripts/lib/plugin-sdk-entrypoints.json`.
Ce tableau représente volontairement le sous-ensemble courant pour la migration, et non la surface complète du SDK. La liste complète des plus de 200 points d’entrée se trouve dans `scripts/lib/plugin-sdk-entrypoints.json`.
Cette liste inclut encore certaines couches d’assistance pour plugins intégrés telles que
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup`, et `plugin-sdk/matrix*`. Elles restent exportées pour la
maintenance et la compatibilité des plugins intégrés, mais sont volontairement
omises du tableau commun de migration et ne constituent pas la cible recommandée pour
du nouveau code de Plugin.
Cette liste inclut encore certains points d’entrée de helpers pour plugins intégrés tels que `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` et `plugin-sdk/matrix*`. Ils restent exportés pour la maintenance et la compatibilité des plugins intégrés, mais ils sont volontairement omis du tableau de migration courant et ne constituent pas la cible recommandée pour le nouveau code de plugin.
La même règle s’applique aux autres familles de helpers intégrés telles que :
La même règle s’applique à d’autres familles de helpers intégrés telles que :
- helpers de prise en charge navigateur : `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 navigateur : `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`
- Matrix : `plugin-sdk/matrix*`
- LINE : `plugin-sdk/line*`
- IRC : `plugin-sdk/irc*`
- surfaces d’assistance/plugin intégrées telles que `plugin-sdk/googlechat`,
- surfaces de helper/plugin intégrées comme `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
`plugin-sdk/twitch`,
`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`, et `plugin-sdk/voice-call`
`plugin-sdk/thread-ownership` et `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` expose actuellement la surface étroite d’assistance de jeton
`DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken`, et `resolveCopilotApiToken`.
`plugin-sdk/github-copilot-token` expose actuellement la surface ciblée de helper de jeton `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken`.
Utilisez l’import le plus étroit qui corresponde à la tâche. Si vous ne trouvez pas un export,
vérifiez la source dans `src/plugin-sdk/` ou demandez sur Discord.
Utilisez l’import le plus ciblé correspondant à la tâche. Si vous ne trouvez pas un export, consultez la source dans `src/plugin-sdk/` ou demandez dans Discord.
## Calendrier de suppression
| Quand | Ce qui se passe |
| ---------------------- | ---------------------------------------------------------------------- |
| **Maintenant** | Les surfaces obsolètes émettent des avertissements à l’exécution |
| Quand | Ce qui se passe |
| ---------------------- | ----------------------------------------------------------------------- |
| **Maintenant** | Les surfaces obsolètes émettent des avertissements à l’exécution |
| **Prochaine version majeure** | Les surfaces obsolètes seront supprimées ; les plugins qui les utilisent encore échoueront |
Tous les plugins core ont déjà été migrés. Les plugins externes doivent migrer
avant la prochaine version majeure.
Tous les plugins du cœur ont déjà été migrés. Les plugins externes doivent migrer avant la prochaine version majeure.
## Supprimer temporairement les avertissements
## Masquer temporairement les avertissements
Définissez ces variables d’environnement pendant que vous travaillez à la migration :
Définissez ces variables d’environnement pendant que vous travaillez sur la migration :
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Il s’agit d’une échappatoire temporaire, pas d’une solution permanente.
Il s’agit d’une échappatoire temporaire, et non d’une solution permanente.
## Lié
- [Prise en main](/fr/plugins/building-plugins) — créer votre premier Plugin
- [Pour commencer](/fr/plugins/building-plugins) — créez votre premier plugin
- [Vue d’ensemble du SDK](/fr/plugins/sdk-overview) — référence complète des imports par sous-chemin
- [Plugins de canal](/fr/plugins/sdk-channel-plugins) — créer des plugins de canal
- [Plugins fournisseur](/fr/plugins/sdk-provider-plugins) — créer des plugins fournisseur
- [Internals des plugins](/fr/plugins/architecture) — analyse approfondie de l’architecture
- [Manifest de Plugin](/fr/plugins/manifest) — référence du schéma de manifest
- [Plugins de fournisseur](/fr/plugins/sdk-provider-plugins) — créer des plugins de fournisseur
- [Internes des plugins](/fr/plugins/architecture) — analyse approfondie de l’architecture
- [Manifeste de plugin](/fr/plugins/manifest) — référence du schéma de manifeste

436
docs/fr/plugins/sdk-subpaths.md
View File

@ -1,30 +1,30 @@
---
read_when:
- choix du bon sous-chemin plugin-sdk pour un import de plugin
- audit des sous-chemins de plugins intégrés et des surfaces de helpers
summary: 'catalogue des sous-chemins du SDK de plugin : où vivent les imports, groupés par domaine'
title: sous-chemins du SDK de plugin
- Choisir le bon sous-chemin de plugin-sdk pour une importation de Plugin
- Audit des sous-chemins de bundled-plugin et des surfaces d’assistance
summary: 'Catalogue des sous-chemins du Plugin SDK : où se trouvent quelles importations, regroupées par domaine'
title: Sous-chemins du Plugin SDK
x-i18n:
generated_at: "2026-04-24T07:24:50Z"
generated_at: "2026-04-24T08:57:07Z"
model: gpt-5.4
provider: openai
source_hash: ff4b934501a3163e36b402db72dd75a260fe9f849b3823a7a05e4867a1a5e655
source_hash: 20b923e392b3ec65cfc958ccc7452b52d82bc372ae57cc9becad74a5085ed71b
source_path: plugins/sdk-subpaths.md
workflow: 15
---
Le SDK de plugin est exposé comme un ensemble de sous-chemins étroits sous `openclaw/plugin-sdk/`.
Cette page catalogue les sous-chemins les plus courants, groupé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 réservés de helpers pour plugins intégrés y apparaissent mais restent des
détails d’implémentation sauf si une page de documentation les promeut explicitement.
Le Plugin SDK est exposé comme un ensemble de sous-chemins étroits sous `openclaw/plugin-sdk/`.
Cette page répertorie les sous-chemins 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 d’assistance réservés à bundled-plugin y apparaissent, mais sont des détails
d’implémentation, sauf si une page de documentation les met explicitement en avant.
Pour le guide de création de plugins, voir [Vue d’ensemble du SDK de plugin](/fr/plugins/sdk-overview).
Pour le guide de création de Plugin, voir [vue d’ensemble du Plugin SDK](/fr/plugins/sdk-overview).
## Entrée de plugin
## Entrée de Plugin
| Sous-chemin | Exports clés |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Sous-chemin | Exportations clés |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
@ -32,256 +32,256 @@ x-i18n:
<AccordionGroup>
<Accordion title="Sous-chemins de canal">
| Sous-chemin | Exports clés |
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Export du schéma Zod 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 de liste d’autorisation, constructeurs d’état de configuration |
| `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/setup` | Assistants partagés pour l’assistant de configuration, invites de liste d’autorisation, 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 multi-comptes de configuration/barrière d’action, helpers de repli du compte par défaut |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalisation d’id de compte |
| `plugin-sdk/account-resolution` | Helpers de recherche de compte + repli par défaut |
| `plugin-sdk/account-helpers` | Helpers étroits de liste d’actions/de comptes |
| `plugin-sdk/account-core` | Assistants de configuration multi-compte/contrôle d’actions, assistants de repli vers le compte par défaut |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, assistants de normalisation d’identifiant de compte |
| `plugin-sdk/account-resolution` | Assistants de recherche de compte + repli par défaut |
| `plugin-sdk/account-helpers` | Assistants ciblés pour les listes de comptes et les actions sur les comptes |
| `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 configuration de canal |
| `plugin-sdk/telegram-command-config` | Helpers de normalisation/validation des commandes personnalisées Telegram avec repli vers contrat intégré |
| `plugin-sdk/command-gating` | Helpers étroits de barrière d’autorisation de commande |
| `plugin-sdk/telegram-command-config` | Assistants de normalisation/validation des commandes personnalisées Telegram avec repli vers le contrat bundled |
| `plugin-sdk/command-gating` | Assistants ciblés de contrôle d’autorisation des commandes |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helpers de cycle de vie/finalisation de flux de brouillon |
| `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/messaging-targets` | Helpers d’analyse/mise en correspondance des cibles |
| `plugin-sdk/outbound-media` | Helpers partagés de chargement de médias sortants |
| `plugin-sdk/outbound-runtime` | Helpers d’identité sortante, de délégation d’envoi et de planification de charge utile |
| `plugin-sdk/poll-runtime` | Helpers étroits de normalisation de sondage |
| `plugin-sdk/thread-bindings-runtime` | Helpers de cycle de vie d’association de fil et d’adaptateur |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, assistants de cycle de vie/finalisation des flux de brouillons |
| `plugin-sdk/inbound-envelope` | Assistants partagés pour les routes entrantes + la construction d’enveloppes |
| `plugin-sdk/inbound-reply-dispatch` | Assistants partagés pour l’enregistrement et la distribution des réponses entrantes |
| `plugin-sdk/messaging-targets` | Assistants d’analyse/correspondance des cibles |
| `plugin-sdk/outbound-media` | Assistants partagés de chargement des médias sortants |
| `plugin-sdk/outbound-runtime` | Assistants pour l’identité sortante, le délégué d’envoi et la planification de charge utile |
| `plugin-sdk/poll-runtime` | Assistants ciblés de normalisation des sondages |
| `plugin-sdk/thread-bindings-runtime` | Assistants pour le cycle de vie des liaisons de fils et les adaptateurs |
| `plugin-sdk/agent-media-payload` | Constructeur hérité de charge utile média d’agent |
| `plugin-sdk/conversation-runtime` | Helpers de liaison conversation/fil, d’association et de liaison configurée |
| `plugin-sdk/runtime-config-snapshot` | Helper d’instantané de configuration runtime |
| `plugin-sdk/runtime-group-policy` | Helpers runtime 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` | Primitifs étroits de schéma de configuration de canal |
| `plugin-sdk/channel-config-writes` | Helpers d’autorisation des écritures de configuration de canal |
| `plugin-sdk/channel-plugin-common` | Exports de prélude partagés pour plugins de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de lecture/édition de configuration de liste d’autorisation |
| `plugin-sdk/group-access` | Helpers partagés de décision d’accès de groupe |
| `plugin-sdk/direct-dm` | Helpers partagés d’authentification/protection des DM directs |
| `plugin-sdk/interactive-runtime` | Présentation sémantique de message, livraison et helpers hérités de réponse interactive. Voir [Présentation de message](/fr/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Barrel de compatibilité pour l’anti-rebond entrant, la correspondance de mentions, les helpers de politique de mention et les helpers d’enveloppe |
| `plugin-sdk/channel-inbound-debounce` | Helpers étroits d’anti-rebond entrant |
| `plugin-sdk/channel-mention-gating` | Helpers étroits de politique de mention et de texte de mention sans la surface runtime entrante plus large |
| `plugin-sdk/channel-envelope` | Helpers étroits de formatage d’enveloppe entrante |
| `plugin-sdk/channel-location` | Helpers de contexte et de formatage de localisation de canal |
| `plugin-sdk/channel-logging` | Helpers de journalisation de canal pour suppressions entrantes et échecs de saisie/accusé de réception |
| `plugin-sdk/channel-send-result` | Types de résultats de réponse |
| `plugin-sdk/channel-actions` | Helpers d’actions de message de canal, plus helpers de schéma natif obsolètes conservés pour la compatibilité des plugins |
| `plugin-sdk/channel-targets` | Helpers d’analyse/mise en correspondance des cibles |
| `plugin-sdk/conversation-runtime` | Assistants pour les liaisons de conversation/fil, l’appairage et les liaisons configurées |
| `plugin-sdk/runtime-config-snapshot` | Assistant d’instantané de configuration d’exécution |
| `plugin-sdk/runtime-group-policy` | Assistants de résolution de politique de groupe à l’exécution |
| `plugin-sdk/channel-status` | Assistants partagés d’instantané/résumé de l’état du canal |
| `plugin-sdk/channel-config-primitives` | Primitives ciblées de schéma de configuration de canal |
| `plugin-sdk/channel-config-writes` | Assistants d’autorisation d’écriture de configuration de canal |
| `plugin-sdk/channel-plugin-common` | Exportations de prélude partagées pour Plugin de canal |
| `plugin-sdk/allowlist-config-edit` | Assistants de lecture/modification de configuration de liste d’autorisation |
| `plugin-sdk/group-access` | Assistants partagés de décision d’accès de groupe |
| `plugin-sdk/direct-dm` | Assistants partagés d’authentification/garde-fou pour messages directs |
| `plugin-sdk/interactive-runtime` | Assistants pour la présentation sémantique des messages, la livraison et les réponses interactives héritées. Voir [Présentation des messages](/fr/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Barrel de compatibilité pour l’anti-rebond entrant, la correspondance de mention, les assistants de politique de mention et les assistants d’enveloppe |
| `plugin-sdk/channel-inbound-debounce` | Assistants ciblés d’anti-rebond entrant |
| `plugin-sdk/channel-mention-gating` | Assistants ciblés pour la politique de mention et le texte de mention, sans la surface d’exécution entrante plus large |
| `plugin-sdk/channel-envelope` | Assistants ciblés de formatage des enveloppes entrantes |
| `plugin-sdk/channel-location` | Assistants de contexte et de formatage d’emplacement du canal |
| `plugin-sdk/channel-logging` | Assistants de journalisation de canal pour les abandons entrants et les échecs de saisie/accusé de réception |
| `plugin-sdk/channel-send-result` | Types de résultat de réponse |
| `plugin-sdk/channel-actions` | Assistants d’actions sur les messages de canal, ainsi que des assistants de schéma natif obsolètes conservés pour la compatibilité des Plugin |
| `plugin-sdk/channel-targets` | Assistants d’analyse/correspondance des cibles |
| `plugin-sdk/channel-contract` | Types de contrat de canal |
| `plugin-sdk/channel-feedback` | Câblage des retours/réactions |
| `plugin-sdk/channel-secret-runtime` | Helpers étroits de contrat de secret tels que `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, et types de cibles de secret |
| `plugin-sdk/channel-secret-runtime` | Assistants ciblés de contrat de secret tels que `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` et les types de cible de secret |
</Accordion>
<Accordion title="Sous-chemins de fournisseur">
| Sous-chemin | Exports clés |
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helpers soignés de configuration de fournisseur local/auto-hébergé |
| `plugin-sdk/self-hosted-provider-setup` | Helpers ciblés de configuration de fournisseur auto-hébergé compatible OpenAI |
| `plugin-sdk/cli-backend` | Valeurs par défaut de backend CLI + constantes watchdog |
| `plugin-sdk/provider-auth-runtime` | Helpers runtime de résolution de clé API pour les plugins de fournisseur |
| `plugin-sdk/provider-auth-api-key` | Helpers d’intégration par clé API/écriture de profil tels que `upsertApiKeyProfile` |
| `plugin-sdk/provider-setup` | Assistants de configuration sélectionnés pour les fournisseurs locaux/autohébergés |
| `plugin-sdk/self-hosted-provider-setup` | Assistants ciblés de configuration de fournisseur autohébergé compatible OpenAI |
| `plugin-sdk/cli-backend` | Valeurs par défaut du backend CLI + constantes de surveillance |
| `plugin-sdk/provider-auth-runtime` | Assistants d’exécution pour la résolution des clés API pour les Plugin de fournisseur |
| `plugin-sdk/provider-auth-api-key` | Assistants 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 interactifs partagés de connexion pour les plugins de fournisseur |
| `plugin-sdk/provider-env-vars` | Helpers de recherche des variables d’environnement d’authentification du fournisseur |
| `plugin-sdk/provider-auth-login` | Assistants partagés de connexion interactive pour les Plugin de fournisseur |
| `plugin-sdk/provider-env-vars` | Assistants de recherche des variables d’environnement d’authentification du 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 fournisseur et helpers de normalisation d’id de modèle tels que `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructeurs partagés de politique de relecture, assistants d’endpoint fournisseur, et assistants de normalisation d’identifiant de modèle tels que `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helpers génériques HTTP/capacité de point de terminaison fournisseur, y compris les helpers de formulaires multipart pour la transcription audio |
| `plugin-sdk/provider-web-fetch-contract` | Helpers étroits de contrat config/sélection web-fetch tels que `enablePluginInConfig` et `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helpers d’enregistrement/cache des fournisseurs web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers étroits config/identifiants de recherche web 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 config/identifiants de recherche web tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, et setters/getters d’identifiants limités par portée |
| `plugin-sdk/provider-web-search` | Helpers d’enregistrement/cache/runtime des fournisseurs de recherche web |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage + diagnostics de schéma Gemini, et helpers de compat xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-http` | Assistants génériques de capacité HTTP/endpoint fournisseur, y compris les assistants de formulaire multipart pour la transcription audio |
| `plugin-sdk/provider-web-fetch-contract` | Assistants ciblés de contrat de configuration/sélection web-fetch tels que `enablePluginInConfig` et `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Assistants d’enregistrement/cache pour les fournisseurs web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Assistants ciblés de configuration/identifiants web-search pour les fournisseurs qui n’ont pas besoin du câblage d’activation de Plugin |
| `plugin-sdk/provider-web-search-contract` | Assistants ciblés de contrat de configuration/identifiants web-search tels que `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` et des accesseurs/mutateurs d’identifiants à portée limitée |
| `plugin-sdk/provider-web-search` | Assistants d’enregistrement/cache/exécution pour les fournisseurs web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, nettoyage de schéma Gemini + diagnostics, et assistants de compatibilité xAI tels que `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` et similaires |
| `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-transport-runtime` | Helpers de transport fournisseur natif tels que fetch protégé, transformations de message de transport et flux d’événements de transport inscriptibles |
| `plugin-sdk/provider-onboard` | Helpers de patch de configuration d’onboarding |
| `plugin-sdk/global-singleton` | Helpers de singleton/map/cache locaux au processus |
| `plugin-sdk/group-activation` | Helpers étroits de mode d’activation de groupe et d’analyse de commande |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, types d’enveloppes de flux, et assistants d’enveloppes partagés pour Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Assistants de transport natif fournisseur tels que fetch protégé, transformations de messages de transport et flux d’événements de transport inscriptibles |
| `plugin-sdk/provider-onboard` | Assistants de correctif de configuration d’intégration |
| `plugin-sdk/global-singleton` | Assistants de singleton/map/cache locaux au processus |
| `plugin-sdk/group-activation` | Assistants ciblés pour le mode d’activation de groupe et l’analyse des commandes |
</Accordion>
<Accordion title="Sous-chemins auth et sécurité">
| Sous-chemin | Exports clés |
<Accordion title="Sous-chemins d’authentification et de sécurité">
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registre de commandes, helpers d’autorisation d’expéditeur |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, assistants de registre de commandes, assistants 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` | Résolution d’approbateur et helpers d’authentification d’action dans le même chat |
| `plugin-sdk/approval-client-runtime` | Helpers de profil/filtre d’approbation exec native |
| `plugin-sdk/approval-delivery-runtime` | Adaptateurs de capacité/livraison d’approbation native |
| `plugin-sdk/approval-gateway-runtime` | Helper partagé de résolution gateway d’approbation |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers légers de chargement d’adaptateur d’approbation native pour points d’entrée de canal rapides |
| `plugin-sdk/approval-handler-runtime` | Helpers runtime plus larges de gestionnaire d’approbation ; préférez les coutures plus étroites adapter/gateway lorsqu’elles suffisent |
| `plugin-sdk/approval-native-runtime` | Helpers de cible d’approbation native + liaison de compte |
| `plugin-sdk/approval-reply-runtime` | Helpers de charge utile de réponse d’approbation exec/plugin |
| `plugin-sdk/reply-dedupe` | Helpers étroits de réinitialisation de déduplication de réponse entrante |
| `plugin-sdk/channel-contract-testing` | Helpers étroits de test de contrat de canal sans le barrel de test large |
| `plugin-sdk/command-auth-native` | Helpers d’authentification de commande native + cible de session native |
| `plugin-sdk/command-detection` | Helpers partagés de détection de commande |
| `plugin-sdk/command-primitives-runtime` | Prédicats légers sur le texte de commande pour chemins de canal rapides |
| `plugin-sdk/command-surface` | Helpers de normalisation de corps de commande et surface de commande |
| `plugin-sdk/approval-auth-runtime` | Résolution de l’approbateur et assistants d’authentification d’action dans le même chat |
| `plugin-sdk/approval-client-runtime` | Assistants de profil/filtre d’approbation d’exécution native |
| `plugin-sdk/approval-delivery-runtime` | Adaptateurs natifs de capacité/livraison d’approbation |
| `plugin-sdk/approval-gateway-runtime` | Assistant partagé de résolution de Gateway d’approbation |
| `plugin-sdk/approval-handler-adapter-runtime` | Assistants légers de chargement d’adaptateur d’approbation native pour les points d’entrée de canal à chaud |
| `plugin-sdk/approval-handler-runtime` | Assistants d’exécution plus larges pour le gestionnaire d’approbation ; préférez les interfaces plus étroites d’adaptateur/Gateway lorsqu’elles suffisent |
| `plugin-sdk/approval-native-runtime` | Assistants de cible d’approbation native + liaison de compte |
| `plugin-sdk/approval-reply-runtime` | Assistants de charge utile de réponse d’approbation exec/Plugin |
| `plugin-sdk/reply-dedupe` | Assistants étroits de réinitialisation de déduplication des réponses entrantes |
| `plugin-sdk/channel-contract-testing` | Assistants étroits de test de contrat de canal sans le barrel de test étendu |
| `plugin-sdk/command-auth-native` | Authentification de commande native + assistants natifs de cible de session |
| `plugin-sdk/command-detection` | Assistants partagés de détection de commande |
| `plugin-sdk/command-primitives-runtime` | Prédicats légers sur le texte de commande pour les chemins de canal à chaud |
| `plugin-sdk/command-surface` | Normalisation du corps de commande et assistants de surface de commande |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helpers étroits de collecte de contrat de secret pour surfaces de secret de canal/plugin |
| `plugin-sdk/secret-ref-runtime` | Helpers étroits `coerceSecretRef` et de typage SecretRef pour l’analyse contrat de secret/configuration |
| `plugin-sdk/security-runtime` | Helpers partagés de confiance, filtrage DM, contenu externe et collecte de secrets |
| `plugin-sdk/ssrf-policy` | Helpers de liste d’autorisation d’hôte et de politique SSRF réseau privé |
| `plugin-sdk/ssrf-dispatcher` | Helpers étroits de dispatcher épinglé sans la surface runtime d’infrastructure large |
| `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 de corps de requête/délai d’expiration |
| `plugin-sdk/channel-secret-runtime` | Assistants étroits de collecte de contrat de secret pour les surfaces de secret de canal/Plugin |
| `plugin-sdk/secret-ref-runtime` | Assistants étroits `coerceSecretRef` et de typage SecretRef pour l’analyse du contrat de secret/de la configuration |
| `plugin-sdk/security-runtime` | Assistants partagés de confiance, filtrage DM, contenu externe et collecte de secrets |
| `plugin-sdk/ssrf-policy` | Assistants de politique SSRF pour liste d’autorisation d’hôtes et réseau privé |
| `plugin-sdk/ssrf-dispatcher` | Assistants étroits de répartiteur épinglé sans la large surface d’exécution d’infrastructure |
| `plugin-sdk/ssrf-runtime` | Répartiteur épinglé, fetch protégé contre SSRF et assistants de politique SSRF |
| `plugin-sdk/secret-input` | Assistants d’analyse des entrées secrètes |
| `plugin-sdk/webhook-ingress` | Assistants de requête/cible Webhook |
| `plugin-sdk/webhook-request-guards` | Assistants de taille du corps de requête/délai d’expiration |
</Accordion>
<Accordion title="Sous-chemins runtime et stockage">
| Sous-chemin | Exports clés |
<Accordion title="Sous-chemins d’exécution et de stockage">
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/runtime` | Helpers larges de runtime/journalisation/sauvegarde/installation de plugin |
| `plugin-sdk/runtime-env` | Helpers étroits d’environnement runtime, logger, délai, retry et backoff |
| `plugin-sdk/channel-runtime-context` | Helpers génériques d’enregistrement et de recherche du contexte runtime de canal |
| `plugin-sdk/runtime` | Assistants étendus d’exécution/journalisation/sauvegarde/installation de Plugin |
| `plugin-sdk/runtime-env` | Assistants étroits d’environnement d’exécution, journaliseur, délai d’expiration, nouvelle tentative et backoff |
| `plugin-sdk/channel-runtime-context` | Assistants 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 hook Webhook/interne |
| `plugin-sdk/lazy-runtime` | Helpers de chargement/liaison runtime paresseux tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod`, et `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helpers d’exécution de processus |
| `plugin-sdk/cli-runtime` | Helpers de formatage CLI, attente et version |
| `plugin-sdk/gateway-runtime` | Helpers de client Gateway et de patch d’état de canal |
| `plugin-sdk/config-runtime` | Helpers de chargement/écriture de configuration et de recherche de configuration de plugin |
| `plugin-sdk/telegram-command-config` | Normalisation nom/description de commande Telegram et vérifications de doublon/conflit, même lorsque la surface de contrat Telegram intégrée est indisponible |
| `plugin-sdk/text-autolink-runtime` | Détection d’autoliens de références de fichiers sans le barrel text-runtime large |
| `plugin-sdk/approval-runtime` | Helpers d’approbation exec/plugin, constructeurs de capacité d’approbation, helpers auth/profil, helpers natifs de routage/runtime |
| `plugin-sdk/reply-runtime` | Helpers runtime partagés d’entrée/réponse, découpage, 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 courte fenêtre tels que `buildHistoryContext`, `recordPendingHistoryEntry`, et `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | Assistants partagés de commande/hook/http/interaction pour Plugin |
| `plugin-sdk/hook-runtime` | Assistants partagés de pipeline de Webhook/hook interne |
| `plugin-sdk/lazy-runtime` | Assistants d’importation/liaison différée à l’exécution tels que `createLazyRuntimeModule`, `createLazyRuntimeMethod` et `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Assistants d’exécution de processus |
| `plugin-sdk/cli-runtime` | Assistants de formatage, d’attente et de version CLI |
| `plugin-sdk/gateway-runtime` | Assistants de client Gateway et de correctif d’état de canal |
| `plugin-sdk/config-runtime` | Assistants de chargement/écriture de configuration et assistants de recherche de configuration de Plugin |
| `plugin-sdk/telegram-command-config` | Normalisation du nom/de la description des commandes Telegram et vérifications de doublons/conflits, même lorsque la surface de contrat Telegram bundled n’est pas disponible |
| `plugin-sdk/text-autolink-runtime` | Détection d’autoliens de références de fichiers sans le large barrel text-runtime |
| `plugin-sdk/approval-runtime` | Assistants d’approbation exec/Plugin, constructeurs de capacité d’approbation, assistants d’authentification/profil, assistants natifs de routage/exécution |
| `plugin-sdk/reply-runtime` | Assistants partagés d’exécution entrante/de réponse, segmentation, distribution, Heartbeat, planificateur de réponse |
| `plugin-sdk/reply-dispatch-runtime` | Assistants étroits de distribution/finalisation de réponse et d’étiquette de conversation |
| `plugin-sdk/reply-history` | Assistants partagés d’historique des réponses sur courte fenêtre tels que `buildHistoryContext`, `recordPendingHistoryEntry` et `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers étroits de découpage texte/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de chemin du magasin de sessions + updated-at |
| `plugin-sdk/state-paths` | Helpers de chemins de répertoire state/OAuth |
| `plugin-sdk/routing` | Helpers de liaison route/clé de session/compte tels que `resolveAgentRoute`, `buildAgentSessionKey`, et `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helpers partagés de résumé d’état canal/compte, valeurs par défaut d’état runtime 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` | Extrait des URL chaîne à partir d’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 de paramètres communs outil/CLI |
| `plugin-sdk/tool-payload` | Extrait des charges utiles normalisées à partir d’objets de résultat d’outil |
| `plugin-sdk/tool-send` | Extrait les champs de cible d’envoi canoniques à partir des 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/conversion de tableaux Markdown |
| `plugin-sdk/json-store` | Petits helpers de lecture/écriture d’état JSON |
| `plugin-sdk/file-lock` | Helpers de verrou de fichier réentrant |
| `plugin-sdk/persistent-dedupe` | Helpers de cache de déduplication adossé au disque |
| `plugin-sdk/acp-runtime` | Helpers de runtime/session ACP et de répartition de réponse |
| `plugin-sdk/acp-binding-resolve-runtime` | Résolution en lecture seule de liaison ACP sans imports de démarrage de cycle de vie |
| `plugin-sdk/agent-config-primitives` | Primitifs étroits de schéma de configuration 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 de bootstrap d’appareil et de jeton d’association |
| `plugin-sdk/extension-shared` | Primitifs partagés de canal passif, statut et proxy ambiant |
| `plugin-sdk/models-provider-runtime` | Helpers de réponse de commande/fournisseur `/models` |
| `plugin-sdk/skill-commands-runtime` | Helpers de listing de commandes de Skills |
| `plugin-sdk/native-command-registry` | Helpers de construction/sérialisation du registre de commandes natives |
| `plugin-sdk/agent-harness` | Surface expérimentale de plugin de confiance pour harnais d’agent bas niveau : types de harnais, helpers de steer/abort d’exécution active, helpers de pont d’outil OpenClaw, helpers de formatage/détail de progression d’outil, et utilitaires de résultat de tentative |
| `plugin-sdk/provider-zai-endpoint` | Helpers de détection de point de terminaison Z.AI |
| `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/événement de diagnostic |
| `plugin-sdk/error-runtime` | Graphe d’erreur, formatage, helpers partagés de classification d’erreur, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helpers de fetch enveloppé, proxy et recherche épinglée |
| `plugin-sdk/runtime-fetch` | Fetch runtime conscient du dispatcher sans imports proxy/fetch protégé |
| `plugin-sdk/response-limit-runtime` | Lecteur borné de corps de réponse sans la surface runtime média large |
| `plugin-sdk/session-binding-runtime` | État actuel de liaison de conversation sans routage de liaison configurée ni magasins d’association |
| `plugin-sdk/session-store-runtime` | Helpers de lecture du magasin de sessions sans imports larges d’écritures/maintenance de configuration |
| `plugin-sdk/context-visibility-runtime` | Résolution de visibilité de contexte et filtrage de contexte supplémentaire sans imports larges de config/sécurité |
| `plugin-sdk/string-coerce-runtime` | Helpers étroits de coercition et normalisation de chaîne/enregistrement primitif sans imports markdown/journalisation |
| `plugin-sdk/host-runtime` | Helpers de normalisation d’hôte hostname et SCP |
| `plugin-sdk/retry-runtime` | Helpers de configuration et d’exécuteur retry |
| `plugin-sdk/agent-runtime` | Helpers de répertoire/identité/espace de travail d’agent |
| `plugin-sdk/directory-runtime` | Requête/déduplication d’annuaire adossé à la configuration |
| `plugin-sdk/reply-chunking` | Assistants étroits de segmentation de texte/Markdown |
| `plugin-sdk/session-store-runtime` | Assistants de chemin de magasin de session + date de mise à jour |
| `plugin-sdk/state-paths` | Assistants de chemins de répertoires d’état/OAuth |
| `plugin-sdk/routing` | Assistants de liaison route/clé de session/compte tels que `resolveAgentRoute`, `buildAgentSessionKey` et `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Assistants partagés de résumé d’état canal/compte, valeurs par défaut d’état d’exécution et assistants de métadonnées de problème |
| `plugin-sdk/target-resolver-runtime` | Assistants partagés de résolution de cible |
| `plugin-sdk/string-normalization-runtime` | Assistants de normalisation de slug/chaîne |
| `plugin-sdk/request-url` | Extraire des URL sous forme de chaîne à partir d’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 communs de paramètres d’outil/CLI |
| `plugin-sdk/tool-payload` | Extraire des charges utiles normalisées à partir d’objets de résultat d’outil |
| `plugin-sdk/tool-send` | Extraire les champs cibles d’envoi canoniques à partir des arguments d’outil |
| `plugin-sdk/temp-path` | Assistants partagés de chemins temporaires de téléchargement |
| `plugin-sdk/logging-core` | Assistants de journaliseur de sous-système et de masquage |
| `plugin-sdk/markdown-table-runtime` | Assistants de mode de tableau Markdown et de conversion |
| `plugin-sdk/json-store` | Petits assistants de lecture/écriture d’état JSON |
| `plugin-sdk/file-lock` | Assistants de verrou de fichier réentrant |
| `plugin-sdk/persistent-dedupe` | Assistants de cache de déduplication adossé au disque |
| `plugin-sdk/acp-runtime` | Assistants d’exécution/session ACP et de distribution de réponse |
| `plugin-sdk/acp-binding-resolve-runtime` | Résolution en lecture seule des liaisons ACP sans importations de démarrage du cycle de vie |
| `plugin-sdk/agent-config-primitives` | Primitives étroites 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` | Assistants de résolution de correspondance de noms dangereux |
| `plugin-sdk/device-bootstrap` | Assistants d’initialisation d’appareil et de jeton d’appairage |
| `plugin-sdk/extension-shared` | Primitives d’assistance partagées pour canal passif, état et proxy ambiant |
| `plugin-sdk/models-provider-runtime` | Assistants de réponse de fournisseur/commande `/models` |
| `plugin-sdk/skill-commands-runtime` | Assistants de listage des commandes Skills |
| `plugin-sdk/native-command-registry` | Assistants 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, assistants de pilotage/abandon d’exécution active, assistants de pont d’outil OpenClaw, assistants de formatage/détail de progression d’outil et utilitaires de résultat de tentative |
| `plugin-sdk/provider-zai-endpoint` | Assistants de détection d’endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Assistants d’événement système/Heartbeat |
| `plugin-sdk/collection-runtime` | Petits assistants de cache borné |
| `plugin-sdk/diagnostic-runtime` | Assistants d’indicateur et d’événement de diagnostic |
| `plugin-sdk/error-runtime` | Graphe d’erreurs, formatage, assistants partagés de classification des erreurs, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Assistants de fetch encapsulé, proxy et recherche épinglée |
| `plugin-sdk/runtime-fetch` | Fetch d’exécution tenant compte du répartiteur, sans importations de 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 actuel de liaison de conversation sans routage de liaison configurée ni magasins d’appairage |
| `plugin-sdk/session-store-runtime` | Assistants de lecture du magasin de session sans importations étendues d’écriture/maintenance de configuration |
| `plugin-sdk/context-visibility-runtime` | Résolution de visibilité du contexte et filtrage du contexte supplémentaire sans importations étendues de configuration/sécurité |
| `plugin-sdk/string-coerce-runtime` | Assistants étroits de conversion/normalisation de chaîne et d’enregistrement primitif, sans importations Markdown/journalisation |
| `plugin-sdk/host-runtime` | Assistants de normalisation de nom d’hôte et d’hôte SCP |
| `plugin-sdk/retry-runtime` | Assistants de configuration et d’exécuteur de nouvelle tentative |
| `plugin-sdk/agent-runtime` | Assistants de répertoire/identité/espace de travail d’agent |
| `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 | Exports clés |
<Accordion title="Sous-chemins de capacités et de test">
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/media-runtime` | Helpers partagés de récupération/transformation/stockage de médias plus constructeurs de charge utile média |
| `plugin-sdk/media-store` | Helpers étroits de magasin média tels que `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | Helpers partagés de repli pour génération de médias, sélection de candidats et messagerie de modèle manquant |
| `plugin-sdk/media-understanding` | Types de fournisseurs de compréhension média plus exports d’helpers image/audio côté fournisseur |
| `plugin-sdk/text-runtime` | Helpers partagés texte/markdown/journalisation tels que suppression de texte visible par l’assistant, helpers de rendu/découpage/tableaux markdown, helpers de masquage, helpers de balises de directives, et utilitaires de texte sûr |
| `plugin-sdk/text-chunking` | Helper de découpage de texte sortant |
| `plugin-sdk/speech` | Types de fournisseurs de parole plus helpers côté fournisseur de directive, registre et validation |
| `plugin-sdk/speech-core` | Types, registre, directive et helpers de normalisation partagés pour fournisseurs de parole |
| `plugin-sdk/realtime-transcription` | Types de fournisseurs de transcription en temps réel, helpers de registre, et helper partagé de session WebSocket |
| `plugin-sdk/realtime-voice` | Types de fournisseurs de voix en temps réel et helpers de registre |
| `plugin-sdk/image-generation` | Types de fournisseurs de génération d’images |
| `plugin-sdk/image-generation-core` | Types partagés de génération d’images, repli, authentification et helpers de registre |
| `plugin-sdk/media-runtime` | Assistants partagés de récupération/transformation/stockage de médias, plus constructeurs de charge utile média |
| `plugin-sdk/media-store` | Assistants étroits de magasin média tels que `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | Assistants partagés de bascule de génération de média, sélection de candidats et messages de modèle manquant |
| `plugin-sdk/media-understanding` | Types de fournisseur de compréhension de média, plus exportations d’assistants image/audio destinés aux fournisseurs |
| `plugin-sdk/text-runtime` | Assistants partagés de texte/Markdown/journalisation tels que suppression du texte visible par l’assistant, assistants de rendu/segmentation/tableau Markdown, assistants de masquage, assistants de balises de directive et utilitaires de texte sûr |
| `plugin-sdk/text-chunking` | Assistant de segmentation de texte sortant |
| `plugin-sdk/speech` | Types de fournisseur de parole, plus assistants de directive, registre et validation destinés aux fournisseurs |
| `plugin-sdk/speech-core` | Assistants partagés de types de fournisseur de parole, registre, directive et normalisation |
| `plugin-sdk/realtime-transcription` | Types de fournisseur de transcription en temps réel, assistants de registre et assistant partagé de session WebSocket |
| `plugin-sdk/realtime-voice` | Types de fournisseur de voix en temps réel et assistants de registre |
| `plugin-sdk/image-generation` | Types de fournisseur de génération d’image |
| `plugin-sdk/image-generation-core` | Assistants partagés de types de génération d’image, bascule, authentification et registre |
| `plugin-sdk/music-generation` | Types de fournisseur/requête/résultat de génération musicale |
| `plugin-sdk/music-generation-core` | Types partagés de génération musicale, helpers de repli, recherche de fournisseur et analyse de model-ref |
| `plugin-sdk/music-generation-core` | Assistants partagés de types de génération musicale, assistants de bascule, recherche de fournisseur et analyse de référence de modèle |
| `plugin-sdk/video-generation` | Types de fournisseur/requête/résultat de génération vidéo |
| `plugin-sdk/video-generation-core` | Types partagés de génération vidéo, helpers de repli, recherche de fournisseur et analyse de model-ref |
| `plugin-sdk/webhook-targets` | Helpers de registre de cibles Webhook et 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 de plugin |
| `plugin-sdk/video-generation-core` | Assistants partagés de types de génération vidéo, assistants de bascule, recherche de fournisseur et analyse de référence de modèle |
| `plugin-sdk/webhook-targets` | Registre de cibles Webhook et assistants d’installation de route |
| `plugin-sdk/webhook-path` | Assistants de normalisation de chemin Webhook |
| `plugin-sdk/web-media` | Assistants partagés de chargement de médias distants/locaux |
| `plugin-sdk/zod` | `zod` réexporté pour les consommateurs du Plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Sous-chemins mémoire">
| Sous-chemin | Exports clés |
<Accordion title="Sous-chemins de mémoire">
| Sous-chemin | Exportations clés |
| --- | --- |
| `plugin-sdk/memory-core` | Surface de helpers memory-core intégrée pour les helpers de gestionnaire/configuration/fichier/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Façade runtime d’index/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 de l’hôte mémoire, accès au registre, fournisseur local, et helpers génériques batch/distants |
| `plugin-sdk/memory-core-host-engine-qmd` | Exports du moteur QMD de l’hôte mémoire |
| `plugin-sdk/memory-core-host-engine-storage` | Exports du moteur de stockage de l’hôte mémoire |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodaux de l’hôte mémoire |
| `plugin-sdk/memory-core-host-query` | Helpers de requête de l’hôte mémoire |
| `plugin-sdk/memory-core-host-secret` | Helpers de secret de l’hôte mémoire |
| `plugin-sdk/memory-core-host-events` | Helpers de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-core-host-status` | Helpers d’état de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers runtime CLI de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-core` | Helpers runtime du cœur de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de fichier/runtime de l’hôte mémoire |
| `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les helpers runtime du cœur de l’hôte mémoire |
| `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les helpers de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les helpers de fichier/runtime de l’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 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 d’état de l’hôte mémoire |
| `plugin-sdk/memory-lancedb` | Surface de helpers memory-lancedb intégrée |
| `plugin-sdk/memory-core` | Surface d’assistance `memory-core` bundled pour les assistants 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` | Exportations du moteur de base de l’hôte mémoire |
| `plugin-sdk/memory-core-host-engine-embeddings` | Contrats d’embeddings de l’hôte mémoire, accès au registre, fournisseur local et assistants génériques de lot/distant |
| `plugin-sdk/memory-core-host-engine-qmd` | Exportations du moteur QMD de l’hôte mémoire |
| `plugin-sdk/memory-core-host-engine-storage` | Exportations du moteur de stockage de l’hôte mémoire |
| `plugin-sdk/memory-core-host-multimodal` | Assistants multimodaux de l’hôte mémoire |
| `plugin-sdk/memory-core-host-query` | Assistants de requête de l’hôte mémoire |
| `plugin-sdk/memory-core-host-secret` | Assistants de secret de l’hôte mémoire |
| `plugin-sdk/memory-core-host-events` | Assistants de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-core-host-status` | Assistants d’état de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-cli` | Assistants d’exécution CLI de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-core` | Assistants d’exécution cœur de l’hôte mémoire |
| `plugin-sdk/memory-core-host-runtime-files` | Assistants de fichier/exécution de l’hôte mémoire |
| `plugin-sdk/memory-host-core` | Alias neutre vis-à-vis du fournisseur pour les assistants d’exécution cœur de l’hôte mémoire |
| `plugin-sdk/memory-host-events` | Alias neutre vis-à-vis du fournisseur pour les assistants de journal d’événements de l’hôte mémoire |
| `plugin-sdk/memory-host-files` | Alias neutre vis-à-vis du fournisseur pour les assistants de fichier/exécution de l’hôte mémoire |
| `plugin-sdk/memory-host-markdown` | Assistants partagés de Markdown géré pour les Plugins proches de la mémoire |
| `plugin-sdk/memory-host-search` | Façade d’exécution de Active Memory pour l’accès au gestionnaire de recherche |
| `plugin-sdk/memory-host-status` | Alias neutre vis-à-vis du fournisseur pour les assistants d’état de l’hôte mémoire |
| `plugin-sdk/memory-lancedb` | Surface d’assistance `memory-lancedb` bundled |
</Accordion>
<Accordion title="Sous-chemins réservés de helpers intégrés">
| Famille | Sous-chemins actuels | Usage prévu |
<Accordion title="Sous-chemins d’assistance bundled réservés">
| Famille | Sous-chemins actuels | Utilisation prévue |
| --- | --- | --- |
| 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 intégrée de helper/runtime Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface intégrée de helper/runtime LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface intégrée de helper IRC |
| Helpers spécifiques au 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` | Coutures de compatibilité/helper de canaux intégrés |
| Helpers spécifiques auth/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` | Coutures de helper de fonctionnalité/plugin intégrées ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, et `resolveCopilotApiToken` |
| Navigateur | `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` | Assistants de prise en charge du Plugin navigateur bundled (`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 d’assistance/d’exécution Matrix bundled |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface d’assistance/d’exécution LINE bundled |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface d’assistance IRC bundled |
| Assistants 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` | Interfaces de compatibilité/d’assistance bundled pour canaux |
| Assistants spécifiques à l’authentification/aux Plugins | `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` | Interfaces d’assistance bundled pour fonctionnalités/Plugins ; `plugin-sdk/github-copilot-token` exporte actuellement `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` et `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## Liens associés
- [Vue d’ensemble du SDK de plugin](/fr/plugins/sdk-overview)
- [Configuration du SDK de plugin](/fr/plugins/sdk-setup)
- [Créer des plugins](/fr/plugins/building-plugins)
- [vue d’ensemble du Plugin SDK](/fr/plugins/sdk-overview)
- [configuration du Plugin SDK](/fr/plugins/sdk-setup)
- [Créer des Plugins](/fr/plugins/building-plugins)

248
docs/fr/providers/google.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Vous voulez utiliser les modèles Google Gemini avec OpenClaw
- Vous avez besoin du flux d’authentification par clé API ou OAuth
summary: Configuration de Google Gemini (clé API + OAuth, génération d’image, compréhension des médias, TTS, recherche Web)
- Vous souhaitez utiliser les modèles Google Gemini avec OpenClaw
- Vous avez besoin de la clé API ou du flux d’authentification OAuth
summary: Configuration de Google Gemini (clé API + OAuth, génération d’images, compréhension des médias, TTS, recherche web)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-24T07:27:03Z"
generated_at: "2026-04-24T08:57:44Z"
model: gpt-5.4
provider: openai
source_hash: b43d7171f56ecdfb49a25256783433e64f99a02760b3bc6f0e1055195f556f5d
source_hash: 7e66c9dd637e26976659d04b9b7e2452e6881945dab6011970f9e1c5e4a9a685
source_path: providers/google.md
workflow: 15
---
Le Plugin Google fournit l’accès aux modèles Gemini via Google AI Studio, ainsi qu’à la
génération d’image, à la compréhension des médias (image/audio/vidéo), à la synthèse vocale, et à la recherche Web via
Le plugin Google fournit l’accès aux modèles Gemini via Google AI Studio, ainsi que la
génération d’images, la compréhension des médias (image/audio/vidéo), la synthèse vocale et la recherche web via
Gemini Grounding.
- Fournisseur : `google`
- Authentification : `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
- API : API Google Gemini
- Fournisseur alternatif : `google-gemini-cli` (OAuth)
- Fournisseur : `google`
- Authentification : `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
- API : API Google Gemini
- Fournisseur alternatif : `google-gemini-cli` (OAuth)
## Prise en main
## Premiers pas
Choisissez votre méthode d’authentification préférée et suivez les étapes de configuration.
<Tabs>
<Tab title="Clé API">
**Idéal pour :** accès standard à l’API Gemini via Google AI Studio.
**Idéal pour :** l’accès standard à l’API Gemini via Google AI Studio.
<Steps>
<Step title="Lancer l’onboarding">
@ -36,7 +36,7 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
openclaw onboard --auth-choice gemini-api-key
```
Ou passez directement la clé :
Ou transmettez directement la clé :
```bash
openclaw onboard --non-interactive \
@ -70,11 +70,11 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
</Tab>
<Tab title="Gemini CLI (OAuth)">
**Idéal pour :** réutiliser une connexion Gemini CLI existante via l’OAuth PKCE au lieu d’une clé API séparée.
**Idéal pour :** réutiliser une connexion Gemini CLI existante via OAuth PKCE au lieu d’une clé API distincte.
<Warning>
Le fournisseur `google-gemini-cli` est une intégration non officielle. Certains utilisateurs
signalent des restrictions de compte lorsqu’ils utilisent l’OAuth de cette manière. Utilisez-la à vos propres risques.
signalent des restrictions de compte lors de l’utilisation d’OAuth de cette façon. Utilisez-le à vos propres risques.
</Warning>
<Steps>
@ -89,8 +89,8 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
npm install -g @google/gemini-cli
```
OpenClaw prend en charge à la fois les installations Homebrew et les installations npm globales, y compris
les dispositions Windows/npm courantes.
OpenClaw prend en charge les installations Homebrew et les installations npm globales, y compris
les configurations courantes Windows/npm.
</Step>
<Step title="Se connecter via OAuth">
```bash
@ -104,10 +104,10 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
</Step>
</Steps>
- Modèle par défaut : `google-gemini-cli/gemini-3-flash-preview`
- Alias : `gemini-cli`
- Modèle par défaut : `google-gemini-cli/gemini-3-flash-preview`
- Alias : `gemini-cli`
**Variables d’environnement :**
**Variables d’environnement :**
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
@ -115,60 +115,61 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
(Ou les variantes `GEMINI_CLI_*`.)
<Note>
Si les requêtes Gemini CLI OAuth échouent après la connexion, définissez `GOOGLE_CLOUD_PROJECT` ou
`GOOGLE_CLOUD_PROJECT_ID` sur l’hôte gateway et réessayez.
Si les requêtes OAuth Gemini CLI échouent après la connexion, définissez `GOOGLE_CLOUD_PROJECT` ou
`GOOGLE_CLOUD_PROJECT_ID` sur l’hôte du gateway, puis réessayez.
</Note>
<Note>
Si la connexion échoue avant le démarrage du flux navigateur, assurez-vous que la commande locale `gemini`
est installée et présente dans le `PATH`.
est installée et disponible dans le `PATH`.
</Note>
Le fournisseur `google-gemini-cli` uniquement OAuth est une surface distincte
d’inférence texte. La génération d’image, la compréhension des médias et Gemini Grounding restent sur
l’ID fournisseur `google`.
Le fournisseur `google-gemini-cli`, limité à OAuth, constitue une surface distincte
d’inférence de texte. La génération d’images, la compréhension des médias et Gemini Grounding restent sur
l’identifiant de fournisseur `google`.
</Tab>
</Tabs>
## Capacités
| Capacité | Pris en charge |
| Capability | Pris en charge |
| ---------------------- | ------------------------------ |
| Complétions de chat | Oui |
| Génération d’image | Oui |
| Génération musicale | Oui |
| Synthèse vocale | Oui |
| Compréhension d’image | Oui |
| Transcription audio | Oui |
| Compréhension vidéo | Oui |
| Recherche Web (Grounding) | Oui |
| Réflexion/raisonnement | Oui (Gemini 2.5+ / Gemini 3+) |
| Modèles Gemma 4 | Oui |
| Chat completions | Oui |
| Image generation | Oui |
| Music generation | Oui |
| Text-to-speech | Oui |
| Realtime voice | Oui (Google Live API) |
| Image understanding | Oui |
| Audio transcription | Oui |
| Video understanding | Oui |
| Web search (Grounding) | Oui |
| Thinking/reasoning | Oui (Gemini 2.5+ / Gemini 3+) |
| Gemma 4 models | Oui |
<Tip>
Les modèles Gemini 3 utilisent `thinkingLevel` plutôt que `thinkingBudget`. OpenClaw mappe
les contrôles de raisonnement de Gemini 3, Gemini 3.1, et des alias `gemini-*-latest` vers
`thinkingLevel` afin que les exécutions par défaut/à faible latence n’envoient pas
de valeurs `thinkingBudget` désactivées.
les contrôles de raisonnement des alias Gemini 3, Gemini 3.1 et `gemini-*-latest` vers
`thinkingLevel` afin que les exécutions par défaut/à faible latence n’envoient pas de valeurs
`thinkingBudget` désactivées.
Les modèles Gemma 4 (par exemple `gemma-4-26b-a4b-it`) prennent en charge le mode réflexion. OpenClaw
Les modèles Gemma 4 (par exemple `gemma-4-26b-a4b-it`) prennent en charge le mode de réflexion. OpenClaw
réécrit `thinkingBudget` vers un `thinkingLevel` Google pris en charge pour Gemma 4.
Définir la réflexion sur `off` conserve la réflexion désactivée au lieu de la mapper vers
`MINIMAL`.
</Tip>
## Génération d’image
## Génération d’images
Le fournisseur intégré `google` de génération d’image utilise par défaut
Le fournisseur groupé de génération d’images `google` utilise par défaut
`google/gemini-3.1-flash-image-preview`.
- Prend aussi en charge `google/gemini-3-pro-image-preview`
- Génération : jusqu’à 4 images par requête
- Mode édition : activé, jusqu’à 5 images d’entrée
- Contrôles de géométrie : `size`, `aspectRatio`, et `resolution`
- Génération : jusqu’à 4 images par requête
- Mode édition : activé, jusqu’à 5 images d’entrée
- Contrôles de géométrie : `size`, `aspectRatio` et `resolution`
Pour utiliser Google comme fournisseur d’image par défaut :
Pour utiliser Google comme fournisseur d’images par défaut :
```json5
{
@ -183,20 +184,20 @@ Pour utiliser Google comme fournisseur d’image par défaut :
```
<Note>
Voir [Génération d’image](/fr/tools/image-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
Voir [Image Generation](/fr/tools/image-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
</Note>
## Génération vidéo
Le Plugin intégré `google` enregistre aussi la génération vidéo via l’outil partagé
Le plugin groupé `google` enregistre aussi la génération vidéo via l’outil partagé
`video_generate`.
- Modèle vidéo par défaut : `google/veo-3.1-fast-generate-preview`
- Modes : texte-vers-vidéo, image-vers-vidéo, et flux à référence vidéo unique
- Prend en charge `aspectRatio`, `resolution`, et `audio`
- Limite actuelle de durée : **4 à 8 secondes**
- Modèle vidéo par défaut : `google/veo-3.1-fast-generate-preview`
- Modes : texte vers vidéo, image vers vidéo et flux de référence à vidéo unique
- Prend en charge `aspectRatio`, `resolution` et `audio`
- Limitation actuelle de durée : **4 à 8 secondes**
Pour utiliser Google comme fournisseur vidéo par défaut :
Pour utiliser Google comme fournisseur vidéo par défaut :
```json5
{
@ -211,22 +212,22 @@ Pour utiliser Google comme fournisseur vidéo par défaut :
```
<Note>
Voir [Génération vidéo](/fr/tools/video-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
Voir [Video Generation](/fr/tools/video-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
</Note>
## Génération musicale
Le Plugin intégré `google` enregistre aussi la génération musicale via l’outil partagé
Le plugin groupé `google` enregistre aussi la génération musicale via l’outil partagé
`music_generate`.
- Modèle musical par défaut : `google/lyria-3-clip-preview`
- Modèle musical par défaut : `google/lyria-3-clip-preview`
- Prend aussi en charge `google/lyria-3-pro-preview`
- Contrôles de prompt : `lyrics` et `instrumental`
- Format de sortie : `mp3` par défaut, plus `wav` sur `google/lyria-3-pro-preview`
- Entrées de référence : jusqu’à 10 images
- Les exécutions adossées à une session se détachent via le flux partagé tâche/statut, y compris `action: "status"`
- Contrôles du prompt : `lyrics` et `instrumental`
- Format de sortie : `mp3` par défaut, plus `wav` sur `google/lyria-3-pro-preview`
- Entrées de référence : jusqu’à 10 images
- Les exécutions adossées à une session se détachent via le flux partagé de tâche/statut, y compris `action: "status"`
Pour utiliser Google comme fournisseur musical par défaut :
Pour utiliser Google comme fournisseur musical par défaut :
```json5
{
@ -241,20 +242,20 @@ Pour utiliser Google comme fournisseur musical par défaut :
```
<Note>
Voir [Génération musicale](/fr/tools/music-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
Voir [Music Generation](/fr/tools/music-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
</Note>
## Synthèse vocale
Le fournisseur de parole intégré `google` utilise le chemin TTS de l’API Gemini avec
Le fournisseur vocal groupé `google` utilise le chemin TTS de l’API Gemini avec
`gemini-3.1-flash-tts-preview`.
- Voix par défaut : `Kore`
- Authentification : `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY`, ou `GOOGLE_API_KEY`
- Sortie : WAV pour les pièces jointes TTS normales, PCM pour Talk/téléphonie
- Sortie native en note vocale : non prise en charge sur ce chemin de l’API Gemini car l’API renvoie du PCM plutôt que de l’Opus
- Voix par défaut : `Kore`
- Authentification : `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
- Sortie : WAV pour les pièces jointes TTS classiques, PCM pour Talk/téléphonie
- Sortie native de note vocale : non prise en charge sur ce chemin d’API Gemini, car l’API renvoie du PCM plutôt que de l’Opus
Pour utiliser Google comme fournisseur TTS par défaut :
Pour utiliser Google comme fournisseur TTS par défaut :
```json5
{
@ -274,20 +275,77 @@ Pour utiliser Google comme fournisseur TTS par défaut :
```
Le TTS de l’API Gemini accepte des balises audio expressives entre crochets dans le texte, telles que
`[whispers]` ou `[laughs]`. Pour garder les balises hors de la réponse de chat visible tout en
les envoyant au TTS, placez-les dans un bloc `[[tts:text]]...[[/tts:text]]` :
`[whispers]` ou `[laughs]`. Pour garder les balises hors de la réponse visible dans le chat tout en
les envoyant au TTS, placez-les dans un bloc `[[tts:text]]...[[/tts:text]]` :
```text
Here is the clean reply text.
Voici le texte propre de la réponse.
[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
[[tts:text]][whispers] Voici la version parlée.[[/tts:text]]
```
<Note>
Une clé API Google Cloud Console limitée à l’API Gemini est valide pour ce
Une clé API Google Cloud Console restreinte à l’API Gemini est valide pour ce
fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Speech.
</Note>
## Voix en temps réel
Le plugin groupé `google` enregistre un fournisseur vocal en temps réel adossé à la
Google Live API pour les ponts audio backend comme Voice Call et Google Meet.
| Réglage | Chemin de configuration | Par défaut |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Modèle | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| Voix | `...google.voice` | `Kore` |
| Température | `...google.temperature` | (non défini) |
| Sensibilité de début VAD | `...google.startSensitivity` | (non défini) |
| Sensibilité de fin VAD | `...google.endSensitivity` | (non défini) |
| Durée du silence | `...google.silenceDurationMs` | (non défini) |
| Clé API | `...google.apiKey` | Repli vers `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` |
Exemple de configuration temps réel pour Voice Call :
```json5
{
plugins: {
entries: {
"voice-call": {
enabled: true,
config: {
realtime: {
enabled: true,
provider: "google",
providers: {
google: {
model: "gemini-2.5-flash-native-audio-preview-12-2025",
voice: "Kore",
},
},
},
},
},
},
},
}
```
<Note>
Google Live API utilise l’audio bidirectionnel et l’appel de fonctions via un WebSocket.
OpenClaw adapte l’audio des ponts téléphonie/Meet au flux PCM de la Live API de Gemini et
conserve les appels d’outils sur le contrat partagé de voix en temps réel. Laissez `temperature`
non défini sauf si vous avez besoin de modifier l’échantillonnage ; OpenClaw omet les valeurs non positives
car Google Live peut renvoyer des transcriptions sans audio pour `temperature: 0`.
La transcription de l’API Gemini est activée sans `languageCodes` ; le SDK Google actuel
rejette les indications de code de langue sur ce chemin d’API.
</Note>
<Note>
Les sessions navigateur Talk de l’interface Control nécessitent toujours un fournisseur de voix en temps réel avec une
implémentation de session WebRTC dans le navigateur. Aujourd’hui, ce chemin est OpenAI Realtime ; le
fournisseur Google est destiné aux ponts backend en temps réel.
</Note>
## Configuration avancée
<AccordionGroup>
@ -295,12 +353,12 @@ fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Spee
Pour les exécutions directes de l’API Gemini (`api: "google-generative-ai"`), OpenClaw
transmet un handle `cachedContent` configuré aux requêtes Gemini.
- Configurez des paramètres par modèle ou globaux avec soit
`cachedContent` soit l’ancien `cached_content`
- Si les deux sont présents, `cachedContent` l’emporte
- Exemple de valeur : `cachedContents/prebuilt-context`
- L’utilisation de cache-hit Gemini est normalisée en `cacheRead` OpenClaw à partir de
`cachedContentTokenCount` amont
- Configurez des paramètres par modèle ou globaux avec
`cachedContent` ou l’ancien `cached_content`
- Si les deux sont présents, `cachedContent` est prioritaire
- Exemple de valeur : `cachedContents/prebuilt-context`
- L’utilisation des cache-hit Gemini est normalisée dans `cacheRead` d’OpenClaw à partir de
`cachedContentTokenCount` en amont
```json5
{
@ -320,21 +378,21 @@ fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Spee
</Accordion>
<Accordion title="Remarques sur l’utilisation JSON de Gemini CLI">
<Accordion title="Notes d’utilisation du JSON Gemini CLI">
Lors de l’utilisation du fournisseur OAuth `google-gemini-cli`, OpenClaw normalise
la sortie JSON de la CLI comme suit :
la sortie JSON de la CLI comme suit :
- Le texte de réponse provient du champ JSON `response` de la CLI.
- L’utilisation revient à `stats` lorsque la CLI laisse `usage` vide.
- `stats.cached` est normalisé en `cacheRead` OpenClaw.
- Si `stats.input` est manquant, OpenClaw dérive les tokens d’entrée à partir de
- L’usage se replie sur `stats` lorsque la CLI laisse `usage` vide.
- `stats.cached` est normalisé dans `cacheRead` d’OpenClaw.
- Si `stats.input` est absent, OpenClaw dérive les tokens d’entrée à partir de
`stats.input_tokens - stats.cached`.
</Accordion>
<Accordion title="Environnement et configuration du daemon">
Si le Gateway s’exécute comme daemon (launchd/systemd), assurez-vous que `GEMINI_API_KEY`
est disponible pour ce processus (par exemple dans `~/.openclaw/.env` ou via
<Accordion title="Configuration de l’environnement et du daemon">
Si le Gateway s’exécute comme un daemon (launchd/systemd), assurez-vous que `GEMINI_API_KEY`
est disponible pour ce processus (par exemple, dans `~/.openclaw/.env` ou via
`env.shellEnv`).
</Accordion>
</AccordionGroup>
@ -342,16 +400,16 @@ fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Spee
## Lié
<CardGroup cols={2}>
<Card title="Sélection de modèle" href="/fr/concepts/model-providers" icon="layers">
Choisir les fournisseurs, références de modèles et comportement de basculement.
<Card title="Sélection du modèle" href="/fr/concepts/model-providers" icon="layers">
Choix des fournisseurs, des références de modèle et du comportement de basculement.
</Card>
<Card title="Génération d’image" href="/fr/tools/image-generation" icon="image">
Paramètres partagés d’outil d’image et sélection du fournisseur.
<Card title="Génération d’images" href="/fr/tools/image-generation" icon="image">
Paramètres partagés de l’outil d’image et sélection du fournisseur.
</Card>
<Card title="Génération vidéo" href="/fr/tools/video-generation" icon="video">
Paramètres partagés d’outil vidéo et sélection du fournisseur.
Paramètres partagés de l’outil vidéo et sélection du fournisseur.
</Card>
<Card title="Génération musicale" href="/fr/tools/music-generation" icon="music">
Paramètres partagés d’outil musical et sélection du fournisseur.
Paramètres partagés de l’outil musical et sélection du fournisseur.
</Card>
</CardGroup>

96
docs/fr/reference/test.md
View File

@ -1,51 +1,51 @@
---
read_when:
- Exécuter ou corriger des tests
summary: Comment exécuter les tests localement (vitest) et quand utiliser les modes force/coverage
summary: Comment exécuter les tests en local (Vitest) et quand utiliser les modes force/couverture
title: Tests
x-i18n:
generated_at: "2026-04-24T07:32:24Z"
generated_at: "2026-04-24T08:58:06Z"
model: gpt-5.4
provider: openai
source_hash: df4ad5808ddbc06c704c9bcf9f780b06f9be94ac213ed22e79d880dedcaa6d3b
source_hash: 26cdb5fe005e738ddd00b183e91ccebe08c709bd64eed377d573a37b76e3a3bf
source_path: reference/test.md
workflow: 15
---
- Kit de test complet (suites, live, Docker) : [Testing](/fr/help/testing)
- `pnpm test:force` : tue tout processus gateway résiduel tenant le port de contrôle par défaut, puis exécute la suite Vitest complète avec un port gateway isolé afin que les tests serveur n’entrent pas en collision avec une instance en cours d’exécution. Utilisez-le lorsqu’une exécution précédente du gateway a laissé le port 18789 occupé.
- `pnpm test:coverage` : exécute la suite unit avec couverture V8 (via `vitest.unit.config.ts`). Il s’agit d’une barrière de couverture unitaire des fichiers chargés, pas d’une couverture globale de tous les fichiers du dépôt. Les seuils sont de 70 % pour les lignes/fonctions/instructions et 55 % pour les branches. Comme `coverage.all` vaut false, la barrière mesure les fichiers chargés par la suite de couverture unitaire au lieu de considérer tous les fichiers source des lanes séparées comme non couverts.
- `pnpm test:coverage:changed` : exécute la couverture unit uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:changed` : développe les chemins git modifiés en lanes Vitest ciblées lorsque le diff ne touche que des fichiers source/test routables. Les changements de configuration/setup reviennent toujours à l’exécution native des projets racine afin que les modifications de câblage relancent largement si nécessaire.
- `pnpm changed:lanes` : affiche les lanes architecturales déclenchées par le diff par rapport à `origin/main`.
- `pnpm check:changed` : exécute la barrière intelligente sur les changements du diff par rapport à `origin/main`. Il exécute le travail cœur avec les lanes de test cœur, le travail d’extension avec les lanes de test d’extension, le travail uniquement test avec seulement le typecheck/tests de test, étend les changements du Plugin SDK public ou du contrat de plugin à un passage de validation d’extension, et limite les bumps de version portant uniquement sur les métadonnées de publication aux vérifications ciblées de version/configuration/dépendances racine.
- `pnpm test` : route des cibles explicites de fichier/répertoire via des lanes Vitest ciblées. Les exécutions non ciblées utilisent des groupes de shards fixes et se développent en configurations feuille pour une exécution locale parallèle ; le groupe d’extensions se développe toujours vers les configurations de shard par extension au lieu d’un immense processus de projet racine.
- Les exécutions complètes et par shard d’extension mettent à jour les données de timing locales dans `.artifacts/vitest-shard-timings.json` ; les exécutions suivantes utilisent ces timings pour équilibrer les shards lents et rapides. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artefact local de timing.
- Certains fichiers de test `plugin-sdk` et `commands` sont désormais routés via des lanes légères dédiées qui ne conservent que `test/setup.ts`, laissant les cas lourds au runtime sur leurs lanes existantes.
- Certains fichiers source auxiliaires `plugin-sdk` et `commands` mappent également `pnpm test:changed` vers des tests frères explicites dans ces lanes légères, afin que de petites modifications d’helpers évitent de relancer les suites lourdes adossées au runtime.
- `auto-reply` se divise désormais lui aussi en trois configurations dédiées (`core`, `top-level`, `reply`) afin que le harnais de réponse ne domine pas les tests plus légers de statut/jeton/helper de niveau supérieur.
- La configuration Vitest de base utilise désormais par défaut `pool: "threads"` et `isolate: false`, avec le runner partagé non isolé activé dans les configurations du dépôt.
- `pnpm test:force` : tue tout processus Gateway persistant qui détient le port de contrôle par défaut, puis exécute la suite Vitest complète avec un port Gateway isolé afin que les tests serveur n’entrent pas en collision avec une instance en cours d’exécution. Utilisez cette commande lorsqu’une exécution précédente de Gateway a laissé le port 18789 occupé.
- `pnpm test:coverage` : exécute la suite unitaire avec la couverture V8 (via `vitest.unit.config.ts`). Il s’agit d’une porte de couverture unitaire sur les fichiers chargés, et non d’une couverture globale all-file de tout le dépôt. Les seuils sont de 70 % pour les lignes/fonctions/instructions et de 55 % pour les branches. Comme `coverage.all` vaut false, la porte mesure les fichiers chargés par la suite de couverture unitaire au lieu de considérer chaque fichier source de lane scindée comme non couvert.
- `pnpm test:coverage:changed` : exécute la couverture unitaire uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:changed` : développe les chemins git modifiés en lanes Vitest ciblées lorsque le diff ne touche que des fichiers source/de test routables. Les changements de configuration/setup reviennent tout de même à l’exécution native des projets racine afin que les modifications de câblage relancent largement lorsque c’est nécessaire.
- `pnpm changed:lanes` : affiche les lanes d’architecture déclenchées par le diff par rapport à `origin/main`.
- `pnpm check:changed` : exécute la porte intelligente des changements pour le diff par rapport à `origin/main`. Elle exécute le travail du cœur avec les lanes de test du cœur, le travail des extensions avec les lanes de test des extensions, le travail limité aux tests avec uniquement le typecheck/tests des tests, étend les changements du Plugin SDK public ou du plugin-contract à un passage de validation d’extension, et maintient les incréments de version limités aux métadonnées de release sur des vérifications ciblées de version/configuration/dépendances racine.
- `pnpm test` : achemine les cibles explicites de fichier/répertoire via des lanes Vitest ciblées. Les exécutions sans cible utilisent des groupes de shards fixes et se développent en configurations feuille pour une exécution parallèle locale ; le groupe d’extensions se développe toujours en configurations de shard par extension au lieu d’un unique processus géant de projet racine.
- Les exécutions complètes et par shard d’extension mettent à jour les données locales de minutage dans `.artifacts/vitest-shard-timings.json` ; les exécutions suivantes utilisent ensuite ces minutages pour équilibrer les shards lents et rapides. Définissez `OPENCLAW_TEST_PROJECTS_TIMINGS=0` pour ignorer l’artefact local de minutage.
- Certains fichiers de test `plugin-sdk` et `commands` sélectionnés sont désormais acheminés via des lanes légères dédiées qui ne conservent que `test/setup.ts`, en laissant les cas lourds en runtime sur leurs lanes existantes.
- Certains fichiers source utilitaires `plugin-sdk` et `commands` sélectionnés font également correspondre `pnpm test:changed` à des tests voisins explicites dans ces lanes légères, afin que de petites modifications d’utilitaires évitent de relancer les suites lourdes adossées au runtime.
- `auto-reply` est désormais lui aussi scindé en trois configurations dédiées (`core`, `top-level`, `reply`) afin que le harnais reply ne domine pas les tests plus légers de statut/token/utilitaires de niveau supérieur.
- La configuration de base Vitest utilise désormais par défaut `pool: "threads"` et `isolate: false`, avec le runner partagé non isolé activé dans toutes les configurations du dépôt.
- `pnpm test:channels` exécute `vitest.channels.config.ts`.
- `pnpm test:extensions` et `pnpm test extensions` exécutent tous les shards d’extension/plugin. Les plugins de canal lourds, le plugin navigateur et OpenAI s’exécutent comme shards dédiés ; les autres groupes de plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une lane d’un plugin intégré.
- `pnpm test:perf:imports` : active le reporting Vitest de durée d’import + détail des imports, tout en utilisant toujours le routage ciblé de lanes pour les cibles explicites fichier/répertoire.
- `pnpm test:perf:imports:changed` : même profilage d’import, mais uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` compare le chemin routé en mode changed avec l’exécution native du projet racine pour le même diff git validé.
- `pnpm test:perf:changed:bench -- --worktree` compare l’ensemble de changements du worktree actuel sans devoir valider d’abord.
- `pnpm test:extensions` et `pnpm test extensions` exécutent tous les shards d’extension/plugin. Les plugins de canaux lourds, le plugin navigateur et OpenAI s’exécutent comme shards dédiés ; les autres groupes de plugins restent regroupés. Utilisez `pnpm test extensions/<id>` pour une seule lane de plugin groupé.
- `pnpm test:perf:imports` : active les rapports Vitest de durée d’import + détail des imports, tout en utilisant toujours le routage ciblé des lanes pour les cibles explicites de fichier/répertoire.
- `pnpm test:perf:imports:changed` : même profilage des imports, mais uniquement pour les fichiers modifiés depuis `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` compare en benchmark le chemin changed-mode acheminé à l’exécution native du projet racine pour le même diff git validé.
- `pnpm test:perf:changed:bench -- --worktree` compare en benchmark l’ensemble de changements du worktree actuel sans devoir le valider d’abord.
- `pnpm test:perf:profile:main` : écrit un profil CPU pour le thread principal Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner` : écrit des profils CPU + heap pour le runner unit (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute en série chaque configuration feuille Vitest de la suite complète et écrit des données de durée groupées ainsi que des artefacts JSON/log par configuration. Le Test Performance Agent utilise cela comme base de référence avant de tenter des correctifs de tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après un changement orienté performances.
- Intégration Gateway : opt-in via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e` : exécute les smoke tests de bout en bout du gateway (multi-instance WS/HTTP/jumelage de nœuds). Utilise par défaut `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des journaux détaillés.
- `pnpm test:live` : exécute les tests live des fournisseurs (minimax/zai). Nécessite des clés API et `LIVE=1` (ou un `*_LIVE_TEST=1` spécifique au fournisseur) pour enlever le skip.
- `pnpm test:docker:all` : construit une fois l’image partagée de live-test et l’image Docker E2E, puis exécute les lanes smoke Docker avec `OPENCLAW_SKIP_DOCKER_BUILD=1` à une concurrence de 8 par défaut. Ajustez le pool principal avec `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` et le pool de fin sensible aux fournisseurs avec `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` ; les deux valent 8 par défaut. Le runner cesse de planifier de nouvelles lanes du pool après le premier échec sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque lane a un délai d’attente de 120 minutes remplaçable avec `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Les journaux par lane sont écrits sous `.artifacts/docker-tests/<run-id>/`.
- `pnpm test:docker:openwebui` : démarre OpenClaw dockerisé + Open WebUI, se connecte via Open WebUI, vérifie `/api/models`, puis exécute un vrai chat proxifié via `/api/chat/completions`. Nécessite une clé de modèle live exploitable (par exemple OpenAI dans `~/.profile`), récupère une image Open WebUI externe, et n’est pas censé être stable en CI comme les suites unit/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway pré-initialisé et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte de conversations routées, les lectures de transcript, les métadonnées de pièces jointes, le comportement de la file d’événements live, le routage des envois sortants, ainsi que les notifications de style canal Claude + permissions sur le vrai pont stdio. L’assertion des notifications Claude lit directement les trames MCP stdio brutes afin que le smoke reflète ce que le pont émet réellement.
- `pnpm test:perf:profile:runner` : écrit des profils CPU + heap pour le runner unitaire (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json` : exécute chaque configuration feuille Vitest de la suite complète en série et écrit des données de durée groupées ainsi que des artefacts JSON/log par configuration. Le Test Performance Agent utilise cela comme référence avant de tenter des corrections de tests lents.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json` : compare les rapports groupés après une modification centrée sur la performance.
- Intégration Gateway : activation explicite via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e` : exécute les tests smoke end-to-end de Gateway (appairage multi-instance WS/HTTP/node). Utilise par défaut `threads` + `isolate: false` avec des workers adaptatifs dans `vitest.e2e.config.ts` ; ajustez avec `OPENCLAW_E2E_WORKERS=<n>` et définissez `OPENCLAW_E2E_VERBOSE=1` pour des logs verbeux.
- `pnpm test:live` : exécute les tests live du fournisseur (minimax/zai). Nécessite des clés API et `LIVE=1` (ou `*_LIVE_TEST=1` spécifique au fournisseur) pour lever le skip.
- `pnpm test:docker:all` : construit une fois l’image partagée de test live et l’image Docker E2E, puis exécute les lanes Docker smoke avec `OPENCLAW_SKIP_DOCKER_BUILD=1` avec une concurrence de 8 par défaut. Ajustez le pool principal avec `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` et le pool final sensible au fournisseur avec `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` ; les deux valent 8 par défaut. Le démarrage des lanes est échelonné de 2 secondes par défaut pour éviter les tempêtes locales de création du daemon Docker ; remplacez cela avec `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Le runner cesse de planifier de nouvelles lanes groupées après le premier échec, sauf si `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` est défini, et chaque lane possède un délai maximal de 120 minutes remplaçable via `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Les logs par lane sont écrits dans `.artifacts/docker-tests/<run-id>/`.
- `pnpm test:docker:openwebui` : démarre OpenClaw et Open WebUI conteneurisés, ouvre une session via Open WebUI, vérifie `/api/models`, puis exécute un vrai chat proxifié via `/api/chat/completions`. Nécessite une clé de modèle live utilisable (par exemple OpenAI dans `~/.profile`), télécharge une image Open WebUI externe et n’est pas censé être stable en CI comme les suites unitaires/e2e normales.
- `pnpm test:docker:mcp-channels` : démarre un conteneur Gateway amorcé et un second conteneur client qui lance `openclaw mcp serve`, puis vérifie la découverte de conversation routée, la lecture des transcriptions, les métadonnées des pièces jointes, le comportement de la file d’événements live, le routage des envois sortants et les notifications de type Claude pour canal + permissions sur le vrai pont stdio. L’assertion de notification Claude lit directement les frames MCP stdio brutes afin que le smoke reflète ce que le pont émet réellement.
## Barrière locale de PR
## Porte PR locale
Pour les vérifications locales de PR/atterrissage, exécutez :
Pour les vérifications locales de landing/porte de PR, exécutez :
- `pnpm check:changed`
- `pnpm check`
@ -54,25 +54,25 @@ Pour les vérifications locales de PR/atterrissage, exécutez :
- `pnpm test`
- `pnpm check:docs`
Si `pnpm test` flake sur une machine chargée, relancez une fois avant de le traiter comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les machines à mémoire limitée, utilisez :
Si `pnpm test` est instable sur une machine chargée, relancez-le une fois avant de le considérer comme une régression, puis isolez avec `pnpm test <path/to/test>`. Pour les machines avec peu de mémoire, utilisez :
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Benchmark de latence des modèles (clés locales)
## Benchmark de latence de modèle (clés locales)
Script : [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
Utilisation :
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Variables env facultatives : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt par défaut : « Reply with a single word: ok. No punctuation or extra text. »
- Env facultatif : `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt par défaut : « Répondez avec un seul mot : ok. Sans ponctuation ni texte supplémentaire. »
Dernière exécution (2025-12-31, 20 runs) :
Dernière exécution (2025-12-31, 20 exécutions) :
- minimax médiane 1279ms (min 1114, max 2431)
- opus médiane 2454ms (min 1224, max 3170)
- minimax médiane 1279 ms (min 1114, max 2431)
- opus médiane 2454 ms (min 1224, max 3170)
## Benchmark de démarrage CLI
@ -101,23 +101,23 @@ Préréglages :
- `real` : `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all` : les deux préréglages
La sortie inclut `sampleCount`, moyenne, p50, p95, min/max, distribution exit-code/signal, et résumés RSS max pour chaque commande. Les options facultatives `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 par exécution afin que la mesure de temps et la capture de profil utilisent le même harnais.
La sortie inclut `sampleCount`, avg, p50, p95, min/max, la distribution exit-code/signal et les résumés de RSS max pour chaque commande. Les options facultatives `--cpu-prof-dir` / `--heap-prof-dir` écrivent des profils V8 par exécution afin que la mesure temporelle et la capture de profil utilisent le même harnais.
Conventions de sortie enregistrée :
- `pnpm test:startup:bench:smoke` écrit l’artefact smoke ciblé dans `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` écrit l’artefact de suite complète dans `.artifacts/cli-startup-bench-all.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:update` actualise le fixture de référence versionné dans `test/fixtures/cli-startup-bench.json` avec `runs=5` et `warmup=1`
- `pnpm test:startup:bench:save` écrit l’artefact de suite complète dans `.artifacts/cli-startup-bench-all.json` en utilisant `runs=5` et `warmup=1`
- `pnpm test:startup:bench:update` rafraîchit le fixture de référence versionné dans `test/fixtures/cli-startup-bench.json` en utilisant `runs=5` et `warmup=1`
Fixture versionné :
- `test/fixtures/cli-startup-bench.json`
- Actualisez-le avec `pnpm test:startup:bench:update`
- Comparez les résultats actuels au fixture avec `pnpm test:startup:bench:check`
- Rafraîchir avec `pnpm test:startup:bench:update`
- Comparer les résultats actuels au fixture avec `pnpm test:startup:bench:check`
## E2E onboarding (Docker)
## E2E d’onboarding (Docker)
Docker est facultatif ; il n’est nécessaire que pour les smoke tests d’onboarding conteneurisés.
Docker est facultatif ; cela n’est nécessaire que pour les tests smoke d’onboarding conteneurisés.
Flux complet de démarrage à froid dans un conteneur Linux propre :
@ -125,17 +125,17 @@ Flux complet de démarrage à froid dans un conteneur Linux propre :
scripts/e2e/onboard-docker.sh
```
Ce script pilote l’assistant interactif via un pseudo-tty, vérifie les fichiers de configuration/espace de travail/session, puis démarre le gateway et exécute `openclaw health`.
Ce script pilote l’assistant interactif via un pseudo-TTY, vérifie les fichiers de configuration/workspace/session, puis démarre Gateway et exécute `openclaw health`.
## Smoke d’import QR (Docker)
Garantit que l’assistant runtime QR maintenu se charge sous les runtimes Node Docker pris en charge (Node 24 par défaut, Node 22 compatible) :
Garantit que le helper runtime QR maintenu se charge sous les runtimes Node Docker pris en charge (Node 24 par défaut, Node 22 compatible) :
```bash
pnpm test:docker:qr
```
## Associé
## Liens connexes
- [Testing](/fr/help/testing)
- [Testing live](/fr/help/testing-live)

429
docs/fr/tools/browser.md
View File

@ -1,39 +1,38 @@
---
read_when:
- Ajout d’une automatisation de navigateur contrôlée par l’agent
- Débogage des raisons pour lesquelles openclaw interfère avec votre propre Chrome
- Implémentation des paramètres + du cycle de vie du navigateur dans l’application macOS
- Ajout de l’automatisation du navigateur contrôlée par l’agent
- Déboguer pourquoi openclaw interfère avec votre propre Chrome
- Implémentation des paramètres et du cycle de vie du navigateur dans l’app macOS
summary: Service intégré de contrôle du navigateur + commandes d’action
title: Browser (géré par OpenClaw)
title: Navigateur (géré par OpenClaw)
x-i18n:
generated_at: "2026-04-24T07:35:06Z"
generated_at: "2026-04-24T08:58:21Z"
model: gpt-5.4
provider: openai
source_hash: 2fb0fc0b6235fa8a0324b754e247e015d5ca19d114d324d565ed4a19f9313f7e
source_hash: 80805676213ef5195093163874a848955b3c25364b20045a8d759d03ac088e14
source_path: tools/browser.md
workflow: 15
---
OpenClaw peut exécuter un **profil Chrome/Brave/Edge/Chromium dédié** contrôlé par l’agent.
Il est isolé de votre navigateur personnel et géré via un petit service de
contrôle local à l’intérieur du Gateway (loopback uniquement).
contrôle local à l’intérieur du Gateway (loopback local uniquement).
Vue pour débutant :
Vue débutant :
- Voyez-le comme un **navigateur séparé, réservé à l’agent**.
- Considérez-le comme un **navigateur séparé, réservé à l’agent**.
- Le profil `openclaw` ne touche **pas** à votre profil de navigateur personnel.
- L’agent peut **ouvrir des onglets, lire des pages, cliquer et saisir** dans une voie sûre.
- Le profil intégré `user` s’attache à votre vraie session Chrome connectée via Chrome MCP.
- L’agent peut **ouvrir des onglets, lire des pages, cliquer et saisir du texte** dans un cadre sûr.
- Le profil intégré `user` se connecte à votre vraie session Chrome connectée via Chrome MCP.
## Ce que vous obtenez
- Un profil de navigateur séparé nommé **openclaw** (accent orange par défaut).
- Contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
- Actions d’agent (cliquer/saisir/glisser/sélectionner), instantanés, captures d’écran, PDF.
- Prise en charge facultative de plusieurs profils (`openclaw`, `work`, `remote`, ...).
- Un profil de navigateur distinct nommé **openclaw** (accent orange par défaut).
- Un contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
- Des actions d’agent (cliquer/saisir/faire glisser/sélectionner), des instantanés, des captures d’écran, des PDF.
- Une prise en charge facultative de plusieurs profils (`openclaw`, `work`, `remote`, ...).
Ce navigateur n’est **pas** votre navigateur quotidien. C’est une surface sûre et isolée pour
l’automatisation et la vérification par l’agent.
Ce navigateur n’est **pas** votre navigateur principal au quotidien. C’est une surface sûre et isolée pour l’automatisation et la vérification par l’agent.
## Démarrage rapide
@ -44,15 +43,13 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
Si vous obtenez « Browser disabled », activez-le dans la configuration (voir ci-dessous) et redémarrez le
Gateway.
Si vous obtenez « Browser disabled », activez-le dans la configuration (voir ci-dessous) puis redémarrez le Gateway.
Si `openclaw browser` est totalement absent, ou si l’agent dit que l’outil browser
est indisponible, allez à [Commande ou outil browser manquant](/fr/tools/browser#missing-browser-command-or-tool).
Si `openclaw browser` est totalement absent, ou si l’agent indique que l’outil navigateur n’est pas disponible, consultez [Commande ou outil navigateur manquant](/fr/tools/browser#missing-browser-command-or-tool).
## Contrôle du Plugin
L’outil `browser` par défaut est un Plugin intégré. Désactivez-le pour le remplacer par un autre Plugin qui enregistre le même nom d’outil `browser` :
L’outil `browser` par défaut est un Plugin intégré. Désactivez-le pour le remplacer par un autre Plugin qui enregistre le même nom d’outil `browser` :
```json5
{
@ -66,13 +63,13 @@ L’outil `browser` par défaut est un Plugin intégré. Désactivez-le pour le
}
```
Les valeurs par défaut nécessitent à la fois `plugins.entries.browser.enabled` **et** `browser.enabled=true`. Désactiver uniquement le Plugin supprime d’un seul bloc le CLI `openclaw browser`, la méthode gateway `browser.request`, l’outil d’agent et le service de contrôle ; votre configuration `browser.*` reste intacte pour un remplacement.
Les valeurs par défaut nécessitent à la fois `plugins.entries.browser.enabled` **et** `browser.enabled=true`. Désactiver uniquement le Plugin supprime en une seule unité la CLI `openclaw browser`, la méthode Gateway `browser.request`, l’outil d’agent et le service de contrôle ; votre configuration `browser.*` reste intacte pour un remplacement.
Les changements de configuration browser nécessitent un redémarrage du Gateway afin que le Plugin puisse réenregistrer son service.
Les modifications de configuration du navigateur nécessitent un redémarrage du Gateway afin que le Plugin puisse réenregistrer son service.
## Commande ou outil browser manquant
## Commande ou outil navigateur manquant
Si `openclaw browser` est inconnu après une mise à niveau, que `browser.request` est manquant, ou que l’agent signale que l’outil browser est indisponible, la cause habituelle est une liste `plugins.allow` qui omet `browser`. Ajoutez-le :
Si `openclaw browser` est inconnu après une mise à niveau, si `browser.request` est absent ou si l’agent indique que l’outil navigateur n’est pas disponible, la cause habituelle est une liste `plugins.allow` qui omet `browser`. Ajoutez-le :
```json5
{
@ -82,39 +79,38 @@ Si `openclaw browser` est inconnu après une mise à niveau, que `browser.reques
}
```
`browser.enabled=true`, `plugins.entries.browser.enabled=true`, et `tools.alsoAllow: ["browser"]` ne remplacent pas l’appartenance à la liste d’autorisation — la liste d’autorisation filtre le chargement du Plugin, et la politique d’outils ne s’exécute qu’après le chargement. Supprimer complètement `plugins.allow` restaure également le comportement par défaut.
`browser.enabled=true`, `plugins.entries.browser.enabled=true` et `tools.alsoAllow: ["browser"]` ne remplacent pas l’appartenance à la liste d’autorisation — cette liste contrôle le chargement des Plugins, et la politique d’outils ne s’exécute qu’après le chargement. Supprimer complètement `plugins.allow` rétablit également le comportement par défaut.
## Profils : `openclaw` vs `user`
## Profils : `openclaw` vs `user`
- `openclaw` : navigateur géré, isolé (aucune extension requise).
- `user` : profil intégré d’attachement Chrome MCP pour votre **vraie session Chrome connectée**.
- `openclaw` : navigateur géré et isolé (aucune extension requise).
- `user` : profil intégré de connexion Chrome MCP à votre **vraie session Chrome connectée**.
Pour les appels d’outils browser par l’agent :
Pour les appels d’outil navigateur de l’agent :
- Par défaut : utiliser le navigateur isolé `openclaw`.
- Préférez `profile="user"` lorsque les sessions connectées existantes comptent et que l’utilisateur
est à l’ordinateur pour cliquer/approuver toute invite d’attachement.
- `profile` est la surcharge explicite lorsque vous voulez un mode de navigateur spécifique.
- Par défaut : utilisez le navigateur isolé `openclaw`.
- Préférez `profile="user"` lorsque des sessions déjà connectées comptent et que l’utilisateur est à l’ordinateur pour cliquer/approuver toute invite de connexion.
- `profile` est la surcharge explicite lorsque vous voulez un mode navigateur spécifique.
Définissez `browser.defaultProfile: "openclaw"` si vous voulez le mode géré par défaut.
## Configuration
Les paramètres browser se trouvent dans `~/.openclaw/openclaw.json`.
Les paramètres du navigateur se trouvent dans `~/.openclaw/openclaw.json`.
```json5
{
browser: {
enabled: true, // default: true
enabled: true, // défaut : true
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
// allowPrivateNetwork: true, // legacy alias
// dangerouslyAllowPrivateNetwork: true, // activer uniquement pour un accès intentionnel à un réseau privé de confiance
// allowPrivateNetwork: true, // alias hérité
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
// cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
// cdpUrl: "http://127.0.0.1:18792", // surcharge héritée à profil unique
remoteCdpTimeoutMs: 1500, // délai d’attente HTTP CDP distant (ms)
remoteCdpHandshakeTimeoutMs: 3000, // délai d’attente de poignée de main WebSocket CDP distante (ms)
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@ -145,29 +141,29 @@ Les paramètres browser se trouvent dans `~/.openclaw/openclaw.json`.
<Accordion title="Ports et accessibilité">
- Le service de contrôle se lie à loopback sur un port dérivé de `gateway.port` (par défaut `18791` = gateway + 2). Remplacer `gateway.port` ou `OPENCLAW_GATEWAY_PORT` décale les ports dérivés dans la même famille.
- Les profils locaux `openclaw` attribuent automatiquement `cdpPort`/`cdpUrl` ; ne définissez ceux-ci que pour le CDP distant. `cdpUrl` prend par défaut le port CDP local géré lorsqu’il n’est pas défini.
- `remoteCdpTimeoutMs` s’applique aux vérifications d’accessibilité HTTP CDP distantes (non loopback) ; `remoteCdpHandshakeTimeoutMs` s’applique aux poignées de main WebSocket CDP distantes.
- Le service de contrôle se lie au loopback sur un port dérivé de `gateway.port` (par défaut `18791` = gateway + 2). Remplacer `gateway.port` ou `OPENCLAW_GATEWAY_PORT` décale les ports dérivés dans la même famille.
- Les profils `openclaw` locaux attribuent automatiquement `cdpPort`/`cdpUrl` ; définissez-les uniquement pour le CDP distant. `cdpUrl` utilise par défaut le port CDP local géré lorsqu’il n’est pas défini.
- `remoteCdpTimeoutMs` s’applique aux vérifications d’accessibilité HTTP CDP distantes (hors loopback) ; `remoteCdpHandshakeTimeoutMs` s’applique aux poignées de main WebSocket CDP distantes.
</Accordion>
<Accordion title="Politique SSRF">
- La navigation browser et l’ouverture d’onglet sont protégées contre SSRF avant la navigation et revérifiées au mieux sur l’URL finale `http(s)` ensuite.
- La navigation du navigateur et l’ouverture d’onglets sont protégées contre les SSRF avant la navigation et revérifiées au mieux sur l’URL `http(s)` finale ensuite.
- En mode SSRF strict, la découverte du point de terminaison CDP distant et les sondes `/json/version` (`cdpUrl`) sont également vérifiées.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé par défaut ; activez-le uniquement lorsque l’accès browser au réseau privé est intentionnellement approuvé.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé par défaut ; activez-le uniquement lorsque l’accès au navigateur sur un réseau privé est intentionnellement approuvé.
- `browser.ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias hérité.
</Accordion>
<Accordion title="Comportement des profils">
- `attachOnly: true` signifie ne jamais lancer de navigateur local ; seulement s’y attacher s’il s’exécute déjà.
- `color` (niveau supérieur et par profil) teinte l’interface du navigateur afin que vous puissiez voir quel profil est actif.
- Le profil par défaut est `openclaw` (standalone géré). Utilisez `defaultProfile: "user"` pour opter pour le navigateur utilisateur connecté.
- Ordre de détection automatique : navigateur système par défaut s’il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu du CDP brut. Ne définissez pas `cdpUrl` pour ce driver.
- Définissez `browser.profiles.<name>.userDataDir` lorsqu’un profil existing-session doit s’attacher à un profil utilisateur Chromium non par défaut (Brave, Edge, etc.).
- `attachOnly: true` signifie ne jamais lancer de navigateur local ; se connecter uniquement si un navigateur est déjà en cours d’exécution.
- `color` (au niveau supérieur et par profil) teinte l’interface du navigateur afin que vous puissiez voir quel profil est actif.
- Le profil par défaut est `openclaw` (autonome géré). Utilisez `defaultProfile: "user"` pour choisir le navigateur utilisateur connecté.
- Ordre de détection automatique : navigateur système par défaut s’il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu du CDP brut. Ne définissez pas `cdpUrl` pour ce pilote.
- Définissez `browser.profiles.<name>.userDataDir` lorsqu’un profil existing-session doit se connecter à un profil utilisateur Chromium non par défaut (Brave, Edge, etc.).
</Accordion>
@ -175,15 +171,15 @@ Les paramètres browser se trouvent dans `~/.openclaw/openclaw.json`.
## Utiliser Brave (ou un autre navigateur basé sur Chromium)
Si votre **navigateur système par défaut** est basé sur Chromium (Chrome/Brave/Edge/etc),
Si votre navigateur **par défaut du système** est basé sur Chromium (Chrome/Brave/Edge/etc.),
OpenClaw l’utilise automatiquement. Définissez `browser.executablePath` pour remplacer
la détection automatique :
la détection automatique :
```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
```
Ou définissez-le dans la configuration, selon la plateforme :
Ou définissez-le dans la configuration, selon la plateforme :
<Tabs>
<Tab title="macOS">
@ -217,53 +213,46 @@ Ou définissez-le dans la configuration, selon la plateforme :
## Contrôle local vs distant
- **Contrôle local (par défaut) :** le Gateway démarre le service de contrôle loopback et peut lancer un navigateur local.
- **Contrôle distant (hôte node) :** exécutez un hôte node sur la machine qui possède le navigateur ; le Gateway y relaie les actions browser.
- **CDP distant :** définissez `browser.profiles.<name>.cdpUrl` (ou `browser.cdpUrl`) pour
vous attacher à un navigateur distant basé sur Chromium. Dans ce cas, OpenClaw ne lancera pas de navigateur local.
- **Contrôle local (par défaut) :** le Gateway démarre le service de contrôle loopback et peut lancer un navigateur local.
- **Contrôle distant (hôte Node) :** exécutez un hôte Node sur la machine qui possède le navigateur ; le Gateway transmet les actions du navigateur à cet hôte.
- **CDP distant :** définissez `browser.profiles.<name>.cdpUrl` (ou `browser.cdpUrl`) pour vous connecter à un navigateur distant basé sur Chromium. Dans ce cas, OpenClaw ne lancera pas de navigateur local.
Le comportement à l’arrêt diffère selon le mode de profil :
Le comportement d’arrêt diffère selon le mode de profil :
- profils gérés locaux : `openclaw browser stop` arrête le processus navigateur que
OpenClaw a lancé
- profils attach-only et CDP distant : `openclaw browser stop` ferme la session de contrôle active
et libère les surcharges d’émulation Playwright/CDP (viewport,
schéma de couleurs, locale, fuseau horaire, mode hors ligne et état similaire), même
si aucun processus navigateur n’a été lancé par OpenClaw
- profils locaux gérés : `openclaw browser stop` arrête le processus navigateur lancé par OpenClaw
- profils en connexion uniquement et profils CDP distants : `openclaw browser stop` ferme la session de contrôle active et libère les surcharges d’émulation Playwright/CDP (viewport, schéma de couleurs, langue, fuseau horaire, mode hors ligne et états similaires), même si aucun processus navigateur n’a été lancé par OpenClaw
Les URL CDP distantes peuvent inclure une authentification :
Les URL CDP distantes peuvent inclure une authentification :
- Jetons de requête (par ex., `https://provider.example?token=<token>`)
- Auth Basic HTTP (par ex., `https://user:pass@provider.example`)
- Jetons de requête (par ex. `https://provider.example?token=<token>`)
- Authentification HTTP Basic (par ex. `https://user:pass@provider.example`)
OpenClaw préserve l’authentification lorsqu’il appelle les points de terminaison `/json/*` et lorsqu’il se connecte
au WebSocket CDP. Préférez les variables d’environnement ou les gestionnaires de secrets pour
les jetons plutôt que de les committer dans les fichiers de configuration.
OpenClaw conserve l’authentification lors des appels aux points de terminaison `/json/*` et lors de la connexion au WebSocket CDP. Préférez des variables d’environnement ou des gestionnaires de secrets pour les jetons plutôt que de les valider dans des fichiers de configuration.
## Proxy browser Node (par défaut sans configuration)
## Proxy de navigateur Node (par défaut sans configuration)
Si vous exécutez un **hôte node** sur la machine qui possède votre navigateur, OpenClaw peut
router automatiquement les appels d’outils browser vers ce node sans configuration browser supplémentaire.
C’est le chemin par défaut pour les gateways distants.
Si vous exécutez un **hôte Node** sur la machine qui possède votre navigateur, OpenClaw peut automatiquement
acheminer les appels d’outil navigateur vers ce Node sans configuration supplémentaire du navigateur.
C’est le chemin par défaut pour les Gateways distants.
Remarques :
Remarques :
- L’hôte node expose son serveur local de contrôle du navigateur via une **commande proxy**.
- Les profils proviennent de la propre configuration `browser.profiles` du node (comme en local).
- `nodeHost.browserProxy.allowProfiles` est facultatif. Laissez-le vide pour le comportement hérité/par défaut : tous les profils configurés restent accessibles via le proxy, y compris les routes de création/suppression de profil.
- Si vous définissez `nodeHost.browserProxy.allowProfiles`, OpenClaw le traite comme une frontière de moindre privilège : seuls les profils autorisés peuvent être ciblés, et les routes persistantes de création/suppression de profil sont bloquées sur la surface proxy.
- Désactivez-le si vous n’en voulez pas :
- Sur le node : `nodeHost.browserProxy.enabled=false`
- Sur le gateway : `gateway.nodes.browser.mode="off"`
- L’hôte Node expose son serveur local de contrôle du navigateur via une **commande proxy**.
- Les profils proviennent de la propre configuration `browser.profiles` du Node (identique au mode local).
- `nodeHost.browserProxy.allowProfiles` est facultatif. Laissez-le vide pour le comportement hérité/par défaut : tous les profils configurés restent accessibles via le proxy, y compris les routes de création/suppression de profils.
- Si vous définissez `nodeHost.browserProxy.allowProfiles`, OpenClaw le traite comme une limite de moindre privilège : seuls les profils autorisés peuvent être ciblés, et les routes de création/suppression de profils persistants sont bloquées sur la surface du proxy.
- Désactivez-le si vous n’en voulez pas :
- Sur le Node : `nodeHost.browserProxy.enabled=false`
- Sur le gateway : `gateway.nodes.browser.mode="off"`
## Browserless (CDP distant hébergé)
[Browserless](https://browserless.io) est un service Chromium hébergé qui expose
des URL de connexion CDP via HTTPS et WebSocket. OpenClaw peut utiliser l’une ou l’autre forme, mais
pour un profil de navigateur distant, l’option la plus simple est l’URL WebSocket directe
issue de la documentation de connexion Browserless.
de la documentation de connexion de Browserless.
Exemple :
Exemple :
```json5
{
@ -282,42 +271,40 @@ Exemple :
}
```
Remarques :
Remarques :
- Remplacez `<BROWSERLESS_API_KEY>` par votre vrai jeton Browserless.
- Choisissez le point de terminaison de région correspondant à votre compte Browserless (voir leur documentation).
- Choisissez le point de terminaison régional correspondant à votre compte Browserless (voir leur documentation).
- Si Browserless vous fournit une URL de base HTTPS, vous pouvez soit la convertir en
`wss://` pour une connexion CDP directe, soit conserver l’URL HTTPS et laisser OpenClaw
découvrir `/json/version`.
## Providers CDP WebSocket directs
## Fournisseurs CDP WebSocket directs
Certains services de navigateur hébergés exposent un point de terminaison **WebSocket direct** au lieu de
la découverte CDP standard basée sur HTTP (`/json/version`). OpenClaw accepte trois formes d’URL
CDP et choisit automatiquement la bonne stratégie de connexion :
Certains services de navigateur hébergés exposent un point de terminaison **WebSocket direct** plutôt que
la découverte CDP standard basée sur HTTP (`/json/version`). OpenClaw accepte trois
formes d’URL CDP et choisit automatiquement la bonne stratégie de connexion :
- **Découverte HTTP(S)** — `http://host[:port]` ou `https://host[:port]`.
OpenClaw appelle `/json/version` pour découvrir l’URL du débogueur WebSocket, puis
s’y connecte. Aucun repli WebSocket.
se connecte. Aucun repli WebSocket.
- **Points de terminaison WebSocket directs** — `ws://host[:port]/devtools/<kind>/<id>` ou
`wss://...` avec un chemin `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
OpenClaw se connecte directement via une poignée de main WebSocket et ignore complètement
`/json/version`.
OpenClaw se connecte directement via une poignée de main WebSocket et ignore
complètement `/json/version`.
- **Racines WebSocket nues** — `ws://host[:port]` ou `wss://host[:port]` sans
chemin `/devtools/...` (par ex. [Browserless](https://browserless.io),
[Browserbase](https://www.browserbase.com)). OpenClaw essaie d’abord la découverte HTTP
`/json/version` (en normalisant le schéma en `http`/`https`) ;
[Browserbase](https://www.browserbase.com)). OpenClaw tente d’abord la découverte HTTP
`/json/version` (en normalisant le schéma en `http`/`https`) ;
si la découverte renvoie un `webSocketDebuggerUrl`, il est utilisé, sinon OpenClaw
revient à une poignée de main WebSocket directe à la racine nue. Cela permet à une
URL `ws://` nue pointant vers un Chrome local de tout de même se connecter, puisque Chrome n’accepte
les upgrades WebSocket que sur le chemin spécifique par cible fourni par
URL nue `ws://` pointant vers un Chrome local de se connecter, puisque Chrome n’accepte
les mises à niveau WebSocket que sur le chemin spécifique par cible provenant de
`/json/version`.
### Browserbase
[Browserbase](https://www.browserbase.com) est une plateforme cloud pour exécuter des
navigateurs headless avec résolution intégrée des CAPTCHA, mode furtif, et proxies
résidentiels.
[Browserbase](https://www.browserbase.com) est une plateforme cloud pour exécuter des navigateurs headless avec résolution CAPTCHA intégrée, mode furtif et proxys résidentiels.
```json5
{
@ -336,80 +323,79 @@ résidentiels.
}
```
Remarques :
Remarques :
- [Inscrivez-vous](https://www.browserbase.com/sign-up) et copiez votre **API Key**
- [Inscrivez-vous](https://www.browserbase.com/sign-up) et copiez votre **clé API**
depuis le [tableau de bord Overview](https://www.browserbase.com/overview).
- Remplacez `<BROWSERBASE_API_KEY>` par votre vraie clé API Browserbase.
- Browserbase crée automatiquement une session de navigateur lors de la connexion WebSocket, donc
aucune étape de création manuelle de session n’est nécessaire.
- L’offre gratuite autorise une session concurrente et une heure de navigateur par mois.
Voir [pricing](https://www.browserbase.com/pricing) pour les limites des offres payantes.
- Consultez la [documentation Browserbase](https://docs.browserbase.com) pour la référence API
complète, les guides SDK et les exemples d’intégration.
- Browserbase crée automatiquement une session de navigateur lors de la connexion WebSocket, donc aucune étape manuelle de création de session n’est nécessaire.
- Le niveau gratuit autorise une session concurrente et une heure de navigateur par mois.
Consultez les [tarifs](https://www.browserbase.com/pricing) pour les limites des offres payantes.
- Consultez la [documentation Browserbase](https://docs.browserbase.com) pour la référence API complète,
les guides SDK et les exemples d’intégration.
## Sécurité
Idées clés :
Idées clés :
- Le contrôle du navigateur est limité à loopback ; l’accès passe par l’authentification du Gateway ou l’appairage de node.
- L’API HTTP browser autonome sur loopback utilise **uniquement l’authentification par secret partagé** :
authentification bearer par jeton gateway, `x-openclaw-password`, ou authentification Basic HTTP avec le mot de passe gateway configuré.
- Les en-têtes d’identité Tailscale Serve et `gateway.auth.mode: "trusted-proxy"` n’authentifient **pas** cette API browser autonome sur loopback.
- Si le contrôle browser est activé et qu’aucune authentification par secret partagé n’est configurée, OpenClaw
- Le contrôle du navigateur est limité au loopback ; l’accès passe par l’authentification du Gateway ou l’appairage de Node.
- L’API HTTP autonome du navigateur sur loopback utilise **uniquement une authentification par secret partagé** :
authentification bearer par jeton Gateway, `x-openclaw-password` ou authentification HTTP Basic avec le
mot de passe Gateway configuré.
- Les en-têtes d’identité Tailscale Serve et `gateway.auth.mode: "trusted-proxy"` n’authentifient
**pas** cette API autonome du navigateur sur loopback.
- Si le contrôle du navigateur est activé et qu’aucune authentification par secret partagé n’est configurée, OpenClaw
génère automatiquement `gateway.auth.token` au démarrage et le persiste dans la configuration.
- OpenClaw ne génère **pas** automatiquement ce jeton lorsque `gateway.auth.mode` vaut déjà
`password`, `none`, ou `trusted-proxy`.
- Gardez le Gateway et tous les hôtes node sur un réseau privé (Tailscale) ; évitez l’exposition publique.
- Traitez les URL/jetons CDP distants comme des secrets ; préférez les variables d’environnement ou un gestionnaire de secrets.
- OpenClaw ne génère **pas** automatiquement ce jeton lorsque `gateway.auth.mode` est
déjà `password`, `none` ou `trusted-proxy`.
- Conservez le Gateway et tous les hôtes Node sur un réseau privé (Tailscale) ; évitez toute exposition publique.
- Traitez les URL/jetons CDP distants comme des secrets ; préférez des variables d’environnement ou un gestionnaire de secrets.
Conseils CDP distant :
Conseils pour le CDP distant :
- Préférez des points de terminaison chiffrés (HTTPS ou WSS) et des jetons de courte durée lorsque c’est possible.
- Préférez les points de terminaison chiffrés (HTTPS ou WSS) et les jetons à courte durée de vie lorsque c’est possible.
- Évitez d’intégrer directement des jetons longue durée dans les fichiers de configuration.
## Profils (multi-navigateurs)
OpenClaw prend en charge plusieurs profils nommés (configurations de routage). Les profils peuvent être :
OpenClaw prend en charge plusieurs profils nommés (configurations de routage). Les profils peuvent être :
- **gérés par openclaw** : une instance dédiée de navigateur basé sur Chromium avec son propre répertoire de données utilisateur + port CDP
- **distants** : une URL CDP explicite (navigateur basé sur Chromium exécuté ailleurs)
- **session existante** : votre profil Chrome existant via connexion automatique Chrome DevTools MCP
- **gérés par openclaw** : une instance dédiée de navigateur basé sur Chromium avec son propre répertoire de données utilisateur + port CDP
- **distants** : une URL CDP explicite (navigateur basé sur Chromium exécuté ailleurs)
- **session existante** : votre profil Chrome existant via l’auto-connexion Chrome DevTools MCP
Valeurs par défaut :
Valeurs par défaut :
- Le profil `openclaw` est créé automatiquement s’il manque.
- Le profil `user` est intégré pour l’attachement existing-session via Chrome MCP.
- Les profils existing-session sont opt-in au-delà de `user` ; créez-les avec `--driver existing-session`.
- Les ports CDP locaux sont alloués dans la plage **18800–18899** par défaut.
- Supprimer un profil déplace son répertoire de données local vers la Corbeille.
- Le profil `openclaw` est créé automatiquement s’il est absent.
- Le profil `user` est intégré pour la connexion existing-session Chrome MCP.
- Les profils existing-session sont facultatifs au-delà de `user` ; créez-les avec `--driver existing-session`.
- Les ports CDP locaux sont attribués à partir de **18800–18899** par défaut.
- La suppression d’un profil déplace son répertoire de données local vers la corbeille.
Tous les points de terminaison de contrôle acceptent `?profile=<name>` ; le CLI utilise `--browser-profile`.
Tous les points de terminaison de contrôle acceptent `?profile=<name>` ; la CLI utilise `--browser-profile`.
## Existing-session via Chrome DevTools MCP
OpenClaw peut aussi s’attacher à un profil de navigateur basé sur Chromium en cours d’exécution via le
serveur officiel Chrome DevTools MCP. Cela réutilise les onglets et l’état de connexion
déjà ouverts dans ce profil de navigateur.
OpenClaw peut également se connecter à un profil de navigateur basé sur Chromium en cours d’exécution via le serveur officiel Chrome DevTools MCP. Cela réutilise les onglets et l’état de connexion déjà ouverts dans ce profil de navigateur.
Références officielles sur le contexte et la configuration :
Références officielles de contexte et de configuration :
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
- [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
Profil intégré :
Profil intégré :
- `user`
Facultatif : créez votre propre profil existing-session personnalisé si vous voulez un
nom, une couleur ou un répertoire de données de navigateur différent.
Facultatif : créez votre propre profil existing-session personnalisé si vous voulez un
nom, une couleur ou un répertoire de données de navigateur différents.
Comportement par défaut :
Comportement par défaut :
- Le profil intégré `user` utilise la connexion automatique Chrome MCP, qui cible le
- Le profil intégré `user` utilise l’auto-connexion Chrome MCP, qui cible le
profil Google Chrome local par défaut.
Utilisez `userDataDir` pour Brave, Edge, Chromium, ou un profil Chrome non par défaut :
Utilisez `userDataDir` pour Brave, Edge, Chromium ou un profil Chrome non par défaut :
```json5
{
@ -426,19 +412,19 @@ Utilisez `userDataDir` pour Brave, Edge, Chromium, ou un profil Chrome non par d
}
```
Puis, dans le navigateur correspondant :
Ensuite, dans le navigateur correspondant :
1. Ouvrez la page d’inspection de ce navigateur pour le débogage à distance.
2. Activez le débogage à distance.
3. Gardez le navigateur en cours d’exécution et approuvez l’invite de connexion lorsqu’OpenClaw s’y attache.
3. Gardez le navigateur en cours d’exécution et approuvez l’invite de connexion lorsque OpenClaw se connecte.
Pages d’inspection courantes :
Pages d’inspection courantes :
- Chrome : `chrome://inspect/#remote-debugging`
- Brave : `brave://inspect/#remote-debugging`
- Edge : `edge://inspect/#remote-debugging`
- Chrome : `chrome://inspect/#remote-debugging`
- Brave : `brave://inspect/#remote-debugging`
- Edge : `edge://inspect/#remote-debugging`
Test smoke d’attachement en direct :
Test rapide de connexion en direct :
```bash
openclaw browser --browser-profile user start
@ -447,62 +433,61 @@ openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
À quoi ressemble le succès :
À quoi ressemble une réussite :
- `status` affiche `driver: existing-session`
- `status` affiche `transport: chrome-mcp`
- `status` affiche `running: true`
- `tabs` liste les onglets de navigateur déjà ouverts
- `tabs` liste les onglets déjà ouverts dans votre navigateur
- `snapshot` renvoie des refs depuis l’onglet actif sélectionné
Ce qu’il faut vérifier si l’attachement ne fonctionne pas :
Ce qu’il faut vérifier si la connexion ne fonctionne pas :
- le navigateur basé sur Chromium ciblé est en version `144+`
- le navigateur cible basé sur Chromium est en version `144+`
- le débogage à distance est activé dans la page d’inspection de ce navigateur
- le navigateur a affiché l’invite de consentement d’attachement et vous l’avez acceptée
- `openclaw doctor` migre l’ancienne configuration browser basée sur extension et vérifie que
Chrome est installé localement pour les profils de connexion automatique par défaut, mais il ne peut pas
- le navigateur a affiché l’invite de consentement à la connexion et vous l’avez acceptée
- `openclaw doctor` migre l’ancienne configuration de navigateur basée sur une extension et vérifie que
Chrome est installé localement pour les profils par défaut à auto-connexion, mais il ne peut pas
activer le débogage à distance côté navigateur à votre place
Utilisation par l’agent :
Utilisation par l’agent :
- Utilisez `profile="user"` lorsque vous avez besoin de l’état du navigateur connecté de l’utilisateur.
- Si vous utilisez un profil existing-session personnalisé, passez ce nom de profil explicite.
- Ne choisissez ce mode que lorsque l’utilisateur est devant l’ordinateur pour approuver l’invite
d’attachement.
- le Gateway ou l’hôte node peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
- Choisissez ce mode uniquement lorsque l’utilisateur est à l’ordinateur pour approuver l’invite de connexion.
- le Gateway ou l’hôte Node peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
Remarques :
Remarques :
- Ce chemin est plus risqué que le profil isolé `openclaw` parce qu’il peut
agir à l’intérieur de votre session de navigateur connectée.
- OpenClaw ne lance pas le navigateur pour ce driver ; il ne fait que s’y attacher.
- Ce chemin présente plus de risques que le profil isolé `openclaw` car il peut
agir dans votre session de navigateur connectée.
- OpenClaw ne lance pas le navigateur pour ce pilote ; il se contente de s’y connecter.
- OpenClaw utilise ici le flux officiel `--autoConnect` de Chrome DevTools MCP. Si
`userDataDir` est défini, il est transmis afin de cibler ce répertoire de données utilisateur.
- Existing-session peut s’attacher sur l’hôte sélectionné ou via un
node browser connecté. Si Chrome vit ailleurs et qu’aucun node browser n’est connecté, utilisez
plutôt un CDP distant ou un hôte node.
`userDataDir` est défini, il est transmis pour cibler ce répertoire de données utilisateur.
- Existing-session peut se connecter sur l’hôte sélectionné ou via un
Node navigateur connecté. Si Chrome se trouve ailleurs et qu’aucun Node navigateur n’est connecté, utilisez
plutôt un CDP distant ou un hôte Node.
<Accordion title="Limites fonctionnelles d’existing-session">
<Accordion title="Limites de la fonctionnalité existing-session">
Comparés au profil géré `openclaw`, les drivers existing-session sont plus contraints :
Comparés au profil géré `openclaw`, les pilotes existing-session sont plus contraints :
- **Captures d’écran** — les captures de page et les captures d’élément `--ref` fonctionnent ; les sélecteurs CSS `--element` ne fonctionnent pas. `--full-page` ne peut pas être combiné avec `--ref` ou `--element`. Playwright n’est pas requis pour les captures de page ou d’élément basées sur des refs.
- **Actions** — `click`, `type`, `hover`, `scrollIntoView`, `drag`, et `select` nécessitent des refs d’instantané (pas de sélecteurs CSS). `click` est limité au bouton gauche. `type` ne prend pas en charge `slowly=true` ; utilisez `fill` ou `press`. `press` ne prend pas en charge `delayMs`. `hover`, `scrollIntoView`, `drag`, `select`, `fill`, et `evaluate` ne prennent pas en charge de délais d’attente par appel. `select` accepte une seule valeur.
- **Wait / upload / dialog** — `wait --url` prend en charge les motifs exacts, par sous-chaîne, et glob ; `wait --load networkidle` n’est pas pris en charge. Les hooks d’upload nécessitent `ref` ou `inputRef`, un fichier à la fois, sans CSS `element`. Les hooks de dialogue ne prennent pas en charge de surcharges de délai d’attente.
- **Fonctionnalités réservées au mode géré** — actions par lot, export PDF, interception des téléchargements, et `responsebody` nécessitent toujours le chemin de navigateur géré.
- **Captures d’écran** — les captures de page et les captures d’élément `--ref` fonctionnent ; les sélecteurs CSS `--element` ne fonctionnent pas. `--full-page` ne peut pas être combiné avec `--ref` ou `--element`. Playwright n’est pas nécessaire pour les captures d’écran de page ou d’élément basées sur une ref.
- **Actions** — `click`, `type`, `hover`, `scrollIntoView`, `drag` et `select` nécessitent des refs d’instantané (pas de sélecteurs CSS). `click` ne prend en charge que le bouton gauche. `type` ne prend pas en charge `slowly=true` ; utilisez `fill` ou `press`. `press` ne prend pas en charge `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` et `evaluate` ne prennent pas en charge les délais d’attente par appel. `select` accepte une seule valeur.
- **Attente / téléversement / boîte de dialogue** — `wait --url` prend en charge les motifs exacts, par sous-chaîne et glob ; `wait --load networkidle` n’est pas pris en charge. Les hooks de téléversement nécessitent `ref` ou `inputRef`, un fichier à la fois, sans `element` CSS. Les hooks de boîte de dialogue ne prennent pas en charge les surcharges de délai d’attente.
- **Fonctionnalités réservées au mode géré** — les actions par lot, l’export PDF, l’interception des téléchargements et `responsebody` nécessitent toujours le chemin de navigateur géré.
</Accordion>
## Garanties d’isolation
- **Répertoire de données utilisateur dédié** : ne touche jamais à votre profil de navigateur personnel.
- **Ports dédiés** : évite `9222` pour prévenir les collisions avec les workflows de développement.
- **Contrôle déterministe des onglets** : cible les onglets par `targetId`, pas par « dernier onglet ».
- **Répertoire de données utilisateur dédié** : ne touche jamais à votre profil de navigateur personnel.
- **Ports dédiés** : évite `9222` pour prévenir les collisions avec les flux de développement.
- **Contrôle déterministe des onglets** : cible les onglets par `targetId`, pas par « dernier onglet ».
## Sélection du navigateur
Lors d’un lancement local, OpenClaw choisit le premier disponible :
Lors d’un lancement local, OpenClaw choisit le premier disponible :
1. Chrome
2. Brave
@ -512,43 +497,43 @@ Lors d’un lancement local, OpenClaw choisit le premier disponible :
Vous pouvez remplacer cela avec `browser.executablePath`.
Plateformes :
Plateformes :
- macOS : vérifie `/Applications` et `~/Applications`.
- Linux : recherche `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
- Windows : vérifie les emplacements d’installation courants.
- macOS : vérifie `/Applications` et `~/Applications`.
- Linux : recherche `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
- Windows : vérifie les emplacements d’installation courants.
## API de contrôle (facultative)
## API de contrôle (facultatif)
Pour le scripting et le débogage, le Gateway expose une petite **API HTTP de contrôle loopback-only**
ainsi qu’un CLI `openclaw browser` correspondant (instantanés, refs, wait
power-ups, sortie JSON, workflows de débogage). Voir
Pour les scripts et le débogage, le Gateway expose une petite **API HTTP de contrôle
limitée au loopback** ainsi qu’une CLI `openclaw browser` correspondante (instantanés, refs, améliorations de `wait`,
sortie JSON, flux de débogage). Consultez
[API de contrôle du navigateur](/fr/tools/browser-control) pour la référence complète.
## Dépannage
Pour les problèmes spécifiques à Linux (notamment snap Chromium), voir
Pour les problèmes spécifiques à Linux (en particulier snap Chromium), consultez
[Dépannage du navigateur](/fr/tools/browser-linux-troubleshooting).
Pour les configurations partagées WSL2 Gateway + Windows Chrome sur hôtes séparés, voir
Pour les configurations à hôte scindé WSL2 Gateway + Chrome Windows, consultez
[Dépannage WSL2 + Windows + CDP Chrome distant](/fr/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
### Échec de démarrage CDP vs blocage SSRF de navigation
Ce sont deux classes d’échec différentes et elles pointent vers des chemins de code différents.
- **Échec de démarrage ou de disponibilité CDP** signifie qu’OpenClaw ne peut pas confirmer que le plan de contrôle du navigateur est sain.
- **Blocage SSRF de navigation** signifie que le plan de contrôle du navigateur est sain, mais qu’une cible de navigation de page est rejetée par la politique.
- **Un échec de démarrage ou de disponibilité CDP** signifie qu’OpenClaw ne peut pas confirmer que le plan de contrôle du navigateur est sain.
- **Un blocage SSRF de navigation** signifie que le plan de contrôle du navigateur est sain, mais qu’une cible de navigation de page est rejetée par la politique.
Exemples courants :
Exemples courants :
- Échec de démarrage ou de disponibilité CDP :
- Échec de démarrage ou de disponibilité CDP :
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
- Blocage SSRF de navigation :
- les flux `open`, `navigate`, snapshot, ou d’ouverture d’onglet échouent avec une erreur de politique browser/réseau alors que `start` et `tabs` fonctionnent encore
- Blocage SSRF de navigation :
- les flux `open`, `navigate`, d’instantané ou d’ouverture d’onglet échouent avec une erreur de politique navigateur/réseau alors que `start` et `tabs` fonctionnent toujours
Utilisez cette séquence minimale pour séparer les deux :
Utilisez cette séquence minimale pour distinguer les deux :
```bash
openclaw browser --browser-profile openclaw start
@ -556,47 +541,47 @@ openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
```
Comment lire les résultats :
Comment interpréter les résultats :
- Si `start` échoue avec `not reachable after start`, commencez par dépanner la disponibilité CDP.
- Si `start` réussit mais que `tabs` échoue, le plan de contrôle est toujours malsain. Traitez cela comme un problème d’accessibilité CDP, et non comme un problème de navigation de page.
- Si `start` et `tabs` réussissent mais que `open` ou `navigate` échoue, le plan de contrôle du navigateur est opérationnel et l’échec se situe dans la politique de navigation ou dans la page cible.
- Si `start`, `tabs`, et `open` réussissent tous, le chemin de contrôle de base du navigateur géré est sain.
- Si `start` réussit mais que `tabs` échoue, le plan de contrôle est toujours défaillant. Considérez cela comme un problème d’accessibilité CDP, pas comme un problème de navigation de page.
- Si `start` et `tabs` réussissent mais que `open` ou `navigate` échouent, le plan de contrôle du navigateur fonctionne et l’échec se situe dans la politique de navigation ou la page cible.
- Si `start`, `tabs` et `open` réussissent tous, le chemin de contrôle de base du navigateur géré est sain.
Détails importants de comportement :
Détails de comportement importants :
- La configuration browser utilise par défaut un objet de politique SSRF en fermeture stricte même lorsque vous ne configurez pas `browser.ssrfPolicy`.
- Pour le profil géré local `openclaw` sur loopback, les vérifications de santé CDP ignorent volontairement l’application de l’accessibilité SSRF du navigateur pour le plan de contrôle local propre à OpenClaw.
- La protection de navigation est distincte. Un résultat réussi de `start` ou `tabs` ne signifie pas qu’une cible ultérieure de `open` ou `navigate` est autorisée.
- La configuration du navigateur utilise par défaut un objet de politique SSRF en échec fermé même lorsque vous ne configurez pas `browser.ssrfPolicy`.
- Pour le profil géré local `openclaw` sur loopback, les vérifications d’état CDP ignorent intentionnellement l’application de l’accessibilité SSRF du navigateur pour le propre plan de contrôle local d’OpenClaw.
- La protection de navigation est distincte. Un résultat réussi pour `start` ou `tabs` ne signifie pas qu’une cible ultérieure `open` ou `navigate` est autorisée.
Consignes de sécurité :
Consignes de sécurité :
- Ne relâchez **pas** la politique SSRF du navigateur par défaut.
- N’assouplissez **pas** la politique SSRF du navigateur par défaut.
- Préférez des exceptions d’hôte étroites telles que `hostnameAllowlist` ou `allowedHostnames` plutôt qu’un accès large au réseau privé.
- Utilisez `dangerouslyAllowPrivateNetwork: true` uniquement dans des environnements intentionnellement approuvés où l’accès browser au réseau privé est requis et revu.
- Utilisez `dangerouslyAllowPrivateNetwork: true` uniquement dans des environnements explicitement approuvés où l’accès du navigateur au réseau privé est requis et a été examiné.
## Outils d’agent + fonctionnement du contrôle
L’agent reçoit **un outil** pour l’automatisation du navigateur :
L’agent reçoit **un seul outil** pour l’automatisation du navigateur :
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
Correspondance :
Correspondance :
- `browser snapshot` renvoie un arbre d’interface stable (AI ou ARIA).
- `browser act` utilise les identifiants `ref` de l’instantané pour cliquer/saisir/glisser/sélectionner.
- `browser screenshot` capture des pixels (page entière ou élément).
- `browser` accepte :
- `profile` pour choisir un profil de navigateur nommé (openclaw, chrome, ou CDP distant).
- `target` (`sandbox` | `host` | `node`) pour sélectionner où vit le navigateur.
- `browser act` utilise les identifiants `ref` de l’instantané pour cliquer/saisir/faire glisser/sélectionner.
- `browser screenshot` capture les pixels (page complète ou élément).
- `browser` accepte :
- `profile` pour choisir un profil de navigateur nommé (openclaw, chrome ou CDP distant).
- `target` (`sandbox` | `host` | `node`) pour sélectionner l’emplacement du navigateur.
- Dans les sessions sandboxées, `target: "host"` nécessite `agents.defaults.sandbox.browser.allowHostControl=true`.
- Si `target` est omis : les sessions sandboxées utilisent `sandbox` par défaut, les sessions non sandboxées utilisent `host` par défaut.
- Si un node compatible browser est connecté, l’outil peut automatiquement s’y router sauf si vous épinglez `target="host"` ou `target="node"`.
- Si `target` est omis : les sessions sandboxées utilisent par défaut `sandbox`, les sessions non sandboxées utilisent par défaut `host`.
- Si un Node compatible navigateur est connecté, l’outil peut automatiquement lui acheminer les appels sauf si vous fixez `target="host"` ou `target="node"`.
Cela permet à l’agent de rester déterministe et d’éviter les sélecteurs fragiles.
Cela permet de garder l’agent déterministe et d’éviter les sélecteurs fragiles.
## Liens associés
## Liés
- [Vue d’ensemble des outils](/fr/tools) — tous les outils d’agent disponibles
- [Sandboxing](/fr/gateway/sandboxing) — contrôle du navigateur dans les environnements sandboxés
- [Sécurité](/fr/gateway/security) — risques du contrôle du navigateur et durcissement
- [Sandboxing](/fr/gateway/sandboxing) — contrôle du navigateur dans des environnements sandboxés
- [Sécurité](/fr/gateway/security) — risques et renforcement du contrôle du navigateur

114
docs/fr/tools/capability-cookbook.md
View File

@ -1,80 +1,102 @@
---
read_when:
- Ajouter une nouvelle capacité cœur et une surface d’enregistrement de plugin
- Décider si le code appartient au cœur, à un plugin fournisseur, ou à un plugin de fonctionnalité
- Câbler un nouveau helper runtime pour les canaux ou les outils
- Ajout d’une nouvelle capacité centrale et d’une surface d’enregistrement de Plugin
- Décider si le code doit appartenir au cœur, à un Plugin fournisseur ou à un Plugin de fonctionnalité
- Câbler un nouvel assistant d’exécution pour les canaux ou les outils
sidebarTitle: Adding Capabilities
summary: Guide du contributeur pour ajouter une nouvelle capacité partagée au système de plugins OpenClaw
title: Ajouter des capacités (guide du contributeur)
title: Ajout de capacités (guide du contributeur)
x-i18n:
generated_at: "2026-04-24T07:35:13Z"
generated_at: "2026-04-24T08:58:27Z"
model: gpt-5.4
provider: openai
source_hash: f1e3251b9150c9744d967e91f531dfce01435b13aea3a17088ccd54f2145d14f
source_hash: 864506dd3f61aa64e7c997c9d9e05ce0ad70c80a26a734d4f83b2e80331be4ab
source_path: tools/capability-cookbook.md
workflow: 15
---
<Info>
Ceci est un **guide du contributeur** pour les développeurs du cœur OpenClaw. Si vous
construisez un plugin externe, voir plutôt [Créer des plugins](/fr/plugins/building-plugins).
Ceci est un **guide du contributeur** pour les développeurs du cœur d’OpenClaw. Si vous
créez un plugin externe, consultez plutôt [Créer des plugins](/fr/plugins/building-plugins).
</Info>
Utilisez ceci lorsqu’OpenClaw a besoin d’un nouveau domaine comme la génération d’image, la génération vidéo, ou toute future zone de fonctionnalité adossée à un fournisseur.
Utilisez ceci lorsqu’OpenClaw a besoin d’un nouveau domaine tel que la génération d’images, la génération
de vidéos ou une future zone de fonctionnalité prise en charge par un fournisseur.
La règle :
- plugin = frontière de responsabilité
- capacité = contrat cœur partagé
- plugin = limite de responsabilité
- capacité = contrat central partagé
Cela signifie que vous ne devez pas commencer par câbler un fournisseur directement dans un canal ou un
Cela signifie que vous ne devez pas commencer par connecter directement un fournisseur à un canal ou à un
outil. Commencez par définir la capacité.
## Quand créer une capacité
Créez une nouvelle capacité lorsque toutes les conditions suivantes sont vraies :
1. plus d’un fournisseur pourrait raisonnablement l’implémenter
2. les canaux, outils ou plugins de fonctionnalité devraient la consommer sans se soucier du fournisseur
3. le cœur doit posséder le comportement de repli, la politique, la configuration ou la livraison
1. plus d’un fournisseur pourrait vraisemblablement l’implémenter
2. les canaux, outils ou plugins de fonctionnalité devraient la consommer sans se soucier du
fournisseur
3. le cœur doit gérer le repli, la politique, la configuration ou le comportement de livraison
Si le travail est uniquement propre à un fournisseur et qu’aucun contrat partagé n’existe encore, arrêtez-vous et définissez d’abord le contrat.
Si le travail est propre au fournisseur et qu’aucun contrat partagé n’existe encore, arrêtez-vous et définissez
d’abord le contrat.
## Séquence standard
## La séquence standard
1. Définir le contrat cœur typé.
2. Ajouter l’enregistrement de plugin pour ce contrat.
3. Ajouter un helper runtime partagé.
4. Câbler un vrai plugin fournisseur comme preuve.
5. Faire passer les consommateurs de fonctionnalité/canal par le helper runtime.
6. Ajouter des tests de contrat.
7. Documenter la configuration orientée opérateur et le modèle de responsabilité.
1. Définissez le contrat central typé.
2. Ajoutez l’enregistrement du plugin pour ce contrat.
3. Ajoutez un assistant d’exécution partagé.
4. Connectez un vrai plugin fournisseur comme preuve.
5. Faites passer les consommateurs fonctionnalité/canal sur l’assistant d’exécution.
6. Ajoutez des tests de contrat.
7. Documentez la configuration orientée opérateur et le modèle de responsabilité.
## Ce qui va où
Cœur :
- types requête/réponse
- registre de fournisseurs + résolution
- types de requête/réponse
- registre des fournisseurs + résolution
- comportement de repli
- schéma de configuration plus métadonnées de documentation `title` / `description` propagées sur les nœuds d’objet imbriqué, joker, élément de tableau et composition
- surface de helper runtime
- schéma de configuration plus métadonnées de documentation `title` / `description` propagées sur les nœuds d’objet imbriqué, de joker, d’élément de tableau et de composition
- surface d’assistant d’exécution
Plugin fournisseur :
- appels API du fournisseur
- appels d’API fournisseur
- gestion de l’authentification du fournisseur
- normalisation de requête spécifique au fournisseur
- normalisation des requêtes spécifique au fournisseur
- enregistrement de l’implémentation de la capacité
Plugin de fonctionnalité/canal :
- appelle `api.runtime.*` ou le helper `plugin-sdk/*-runtime` correspondant
- appelle `api.runtime.*` ou l’assistant `plugin-sdk/*-runtime` correspondant
- n’appelle jamais directement une implémentation fournisseur
## Checklist de fichiers
## Points d’extension Provider et Harness
Pour une nouvelle capacité, attendez-vous à modifier ces zones :
Utilisez les hooks de provider lorsque le comportement appartient au contrat du fournisseur de modèle
plutôt qu’à la boucle d’agent générique. Les exemples incluent les paramètres de requête spécifiques au fournisseur
après la sélection du transport, la préférence de profil d’authentification, les surcouches de prompt et
le routage de repli de suivi après le basculement de modèle/profil.
Utilisez les hooks de harness d’agent lorsque le comportement appartient à l’environnement d’exécution
qui exécute un tour. Les harnesses peuvent classifier des résultats de tentative réussis mais inutilisables
comme des réponses vides, limitées au raisonnement ou limitées à la planification, afin que la politique
de repli de modèle externe puisse prendre la décision de nouvelle tentative.
Gardez les deux points d’extension étroits :
- le cœur gère la politique de nouvelle tentative/repli
- les plugins provider gèrent les indices spécifiques au fournisseur pour les requêtes/l’authentification/le routage
- les plugins harness gèrent la classification spécifique à l’exécution des tentatives
- les plugins tiers renvoient des indices, et non des mutations directes de l’état central
## Liste de fichiers
Pour une nouvelle capacité, attendez-vous à modifier les zones suivantes :
- `src/<capability>/types.ts`
- `src/<capability>/...registry/runtime.ts`
@ -86,41 +108,41 @@ Pour une nouvelle capacité, attendez-vous à modifier ces zones :
- `src/plugins/runtime/index.ts`
- `src/plugin-sdk/<capability>.ts`
- `src/plugin-sdk/<capability>-runtime.ts`
- un ou plusieurs packages de plugins inclus
- config/docs/tests
- un ou plusieurs packages de plugins groupés
- configuration/docs/tests
## Exemple : génération d’image
## Exemple : génération d’images
La génération d’image suit la forme standard :
La génération d’images suit la forme standard :
1. le cœur définit `ImageGenerationProvider`
2. le cœur expose `registerImageGenerationProvider(...)`
3. le cœur expose `runtime.imageGeneration.generate(...)`
4. les plugins `openai`, `google`, `fal`, et `minimax` enregistrent des implémentations adossées à des fournisseurs
4. les plugins `openai`, `google`, `fal` et `minimax` enregistrent des implémentations prises en charge par des fournisseurs
5. les futurs fournisseurs peuvent enregistrer le même contrat sans modifier les canaux/outils
La clé de configuration est distincte du routage d’analyse de vision :
La clé de configuration est distincte du routage d’analyse visuelle :
- `agents.defaults.imageModel` = analyser les images
- `agents.defaults.imageGenerationModel` = générer des images
Gardez-les séparés afin que le repli et la politique restent explicites.
Gardez-les séparées afin que le repli et la politique restent explicites.
## Checklist de revue
## Liste de vérification pour la revue
Avant de livrer une nouvelle capacité, vérifiez :
- aucun canal/outil n’importe directement du code fournisseur
- le helper runtime est le chemin partagé
- au moins un test de contrat affirme la responsabilité des éléments inclus
- l’assistant d’exécution est le chemin partagé
- au moins un test de contrat affirme la responsabilité des éléments groupés
- la documentation de configuration nomme la nouvelle clé de modèle/configuration
- la documentation des plugins explique la frontière de responsabilité
- la documentation des plugins explique la limite de responsabilité
Si une PR saute la couche de capacité et code en dur le comportement fournisseur dans un
canal/outil, renvoyez-la et définissez d’abord le contrat.
## Articles connexes
## Liens connexes
- [Plugin](/fr/tools/plugin)
- [Créer des Skills](/fr/tools/creating-skills)
- [Créer des skills](/fr/tools/creating-skills)
- [Outils et plugins](/fr/tools)

239
docs/fr/tools/plugin.md
View File

@ -2,23 +2,23 @@
read_when:
- Installation ou configuration de plugins
- Comprendre les règles de découverte et de chargement des plugins
- Travailler avec des bundles de plugins compatibles Codex/Claude
- Utiliser des bundles de plugins compatibles avec Codex/Claude
sidebarTitle: Install and Configure
summary: Installer, configurer et gérer les plugins OpenClaw
title: Plugins
x-i18n:
generated_at: "2026-04-24T07:38:30Z"
generated_at: "2026-04-24T08:58:31Z"
model: gpt-5.4
provider: openai
source_hash: a93114ddb312552f4c321b6e318f3e19810cf5059dd0c68fde93da41936566b8
source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28
source_path: tools/plugin.md
workflow: 15
---
Les plugins étendent OpenClaw avec de nouvelles capacités : canaux, fournisseurs de modèles,
outils, Skills, parole, transcription en temps réel, voix en temps réel,
compréhension des médias, génération d’images, génération vidéo, récupération web, recherche
web, et plus encore. Certains plugins sont **cœur** (livrés avec OpenClaw), d’autres
harnesses d’agent, outils, Skills, parole, transcription en temps réel, voix en temps réel,
compréhension des médias, génération d’images, génération vidéo, récupération web, recherche web,
et plus encore. Certains plugins sont **core** (livrés avec OpenClaw), d’autres
sont **externes** (publiés sur npm par la communauté).
## Démarrage rapide
@ -47,12 +47,12 @@ sont **externes** (publiés sur npm par la communauté).
openclaw gateway restart
```
Puis configurez sous `plugins.entries.\<id\>.config` dans votre fichier de configuration.
Configurez ensuite sous `plugins.entries.\<id\>.config` dans votre fichier de configuration.
</Step>
</Steps>
Si vous préférez un contrôle natif au chat, activez `commands.plugins: true` et utilisez :
Si vous préférez un contrôle natif dans le chat, activez `commands.plugins: true` et utilisez :
```text
/plugin install clawhub:@openclaw/voice-call
@ -60,34 +60,33 @@ Si vous préférez un contrôle natif au chat, activez `commands.plugins: true`
/plugin enable voice-call
```
Le chemin d’installation utilise le même résolveur que la CLI : chemin/archive local, préfixe explicite
`clawhub:<pkg>`, ou spécification de package simple (ClawHub d’abord, puis repli npm).
Le chemin d’installation utilise le même résolveur que la CLI : chemin/archive local(e), `clawhub:<pkg>` explicite, ou spécification de package simple (ClawHub d’abord, puis repli sur npm).
Si la configuration est invalide, l’installation échoue normalement en mode fail-closed et vous oriente vers
Si la configuration est invalide, l’installation échoue normalement de manière stricte et vous oriente vers
`openclaw doctor --fix`. La seule exception de récupération est un chemin étroit de
réinstallation de plugin inclus pour les plugins qui participent à
réinstallation de plugin inclus pour les plugins qui optent pour
`openclaw.install.allowInvalidConfigRecovery`.
Les installations packagées d’OpenClaw n’installent pas de façon anticipée tout l’arbre de dépendances runtime
de chaque plugin inclus. Lorsqu’un plugin OpenClaw inclus est actif depuis
la configuration de plugin, une configuration de canal héritée, ou un manifeste activé par défaut, le
démarrage ne répare que les dépendances runtime déclarées de ce plugin avant de l’importer.
Les plugins externes et chemins de chargement personnalisés doivent toujours être installés via
Les installations packagées d’OpenClaw n’installent pas d’emblée tout l’arbre de dépendances d’exécution
de chaque plugin inclus. Lorsqu’un plugin inclus appartenant à OpenClaw est actif à partir de la
configuration du plugin, d’une configuration de canal héritée ou d’un manifeste activé par défaut, le
démarrage ne répare que les dépendances d’exécution déclarées de ce plugin avant de l’importer.
Les plugins externes et les chemins de chargement personnalisés doivent toujours être installés via
`openclaw plugins install`.
## Types de plugins
OpenClaw reconnaît deux formats de plugin :
OpenClaw reconnaît deux formats de plugins :
| Format | Fonctionnement | Exemples |
| ---------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
| **Natif** | `openclaw.plugin.json` + module runtime ; s’exécute dans le processus | Plugins officiels, packages npm communautaires |
| **Bundle** | Disposition compatible Codex/Claude/Cursor ; mappée vers les fonctionnalités OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| Format | Fonctionnement | Exemples |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| **Natif** | `openclaw.plugin.json` + module d’exécution ; s’exécute en processus | Plugins officiels, packages npm communautaires |
| **Bundle** | Disposition compatible Codex/Claude/Cursor ; mappée aux fonctionnalités OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Les deux apparaissent dans `openclaw plugins list`. Voir [Plugin Bundles](/fr/plugins/bundles) pour les détails sur les bundles.
Les deux apparaissent dans `openclaw plugins list`. Voir [Plugin Bundles](/fr/plugins/bundles) pour les détails des bundles.
Si vous écrivez un plugin natif, commencez par [Créer des plugins](/fr/plugins/building-plugins)
et [Aperçu du SDK de Plugin](/fr/plugins/sdk-overview).
Si vous écrivez un plugin natif, commencez par [Building Plugins](/fr/plugins/building-plugins)
et [Plugin SDK Overview](/fr/plugins/sdk-overview).
## Plugins officiels
@ -102,7 +101,7 @@ et [Aperçu du SDK de Plugin](/fr/plugins/sdk-overview).
| Zalo | `@openclaw/zalo` | [Zalo](/fr/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/fr/plugins/zalouser) |
### Cœur (livrés avec OpenClaw)
### Core (livrés avec OpenClaw)
<AccordionGroup>
<Accordion title="Fournisseurs de modèles (activés par défaut)">
@ -113,22 +112,22 @@ et [Aperçu du SDK de Plugin](/fr/plugins/sdk-overview).
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="Plugins Memory">
- `memory-core` — recherche Memory incluse (par défaut via `plugins.slots.memory`)
- `memory-lancedb` — Memory long terme installée à la demande avec rappel/capture automatiques (définissez `plugins.slots.memory = "memory-lancedb"`)
<Accordion title="Plugins de mémoire">
- `memory-core` — recherche mémoire incluse (par défaut via `plugins.slots.memory`)
- `memory-lancedb` — mémoire à long terme installée à la demande avec rappel/capture automatiques (définissez `plugins.slots.memory = "memory-lancedb"`)
</Accordion>
<Accordion title="Fournisseurs de parole (activés par défaut)">
<Accordion title="Fournisseurs vocaux (activés par défaut)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="Autres">
- `browser` — plugin navigateur inclus pour l’outil navigateur, la CLI `openclaw browser`, la méthode gateway `browser.request`, le runtime navigateur, et le service de contrôle navigateur par défaut (activé par défaut ; désactivez-le avant de le remplacer)
- `copilot-proxy` — pont VS Code Copilot Proxy (désactivé par défaut)
- `browser` — plugin navigateur inclus pour l’outil navigateur, la CLI `openclaw browser`, la méthode gateway `browser.request`, le runtime navigateur et le service de contrôle navigateur par défaut (activé par défaut ; désactivez-le avant de le remplacer)
- `copilot-proxy` — pont proxy VS Code Copilot (désactivé par défaut)
</Accordion>
</AccordionGroup>
Vous cherchez des plugins tiers ? Voir [Plugins communautaires](/fr/plugins/community).
Vous cherchez des plugins tiers ? Voir [Community Plugins](/fr/plugins/community).
## Configuration
@ -146,17 +145,17 @@ Vous cherchez des plugins tiers ? Voir [Plugins communautaires](/fr/plugins/com
}
```
| Field | Description |
| Champ | Description |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Interrupteur principal (par défaut : `true`) |
| `allow` | Liste d’autorisation des plugins (facultatif) |
| `deny` | Liste d’interdiction des plugins (facultatif ; deny l’emporte) |
| `load.paths` | Fichiers/répertoires de plugins supplémentaires |
| `slots` | Sélecteurs de slots exclusifs (par ex. `memory`, `contextEngine`) |
| `entries.\<id\>` | Activations + configuration par plugin |
| `enabled` | Interrupteur maître (par défaut : `true`) |
| `allow` | Liste d’autorisation des plugins (facultatif) |
| `deny` | Liste de refus des plugins (facultatif ; le refus prime) |
| `load.paths` | Fichiers/répertoires de plugins supplémentaires |
| `slots` | Sélecteurs de slot exclusifs (par ex. `memory`, `contextEngine`) |
| `entries.\<id\>` | Activations + configuration par plugin |
Les changements de configuration **nécessitent un redémarrage du gateway**. Si le Gateway s’exécute avec surveillance de configuration
+ redémarrage dans le processus activés (le chemin par défaut `openclaw gateway`), ce
Les changements de configuration **nécessitent un redémarrage du gateway**. Si le Gateway s’exécute avec
surveillance de configuration + redémarrage en processus activé (le chemin `openclaw gateway` par défaut), ce
redémarrage est généralement effectué automatiquement peu après l’écriture de la configuration.
<Accordion title="États des plugins : désactivé vs manquant vs invalide">
@ -167,14 +166,14 @@ redémarrage est généralement effectué automatiquement peu après l’écritu
## Découverte et priorité
OpenClaw recherche les plugins dans cet ordre (première correspondance gagnante) :
OpenClaw recherche les plugins dans cet ordre (la première correspondance l’emporte) :
<Steps>
<Step title="Chemins de configuration">
`plugins.load.paths` — chemins explicites de fichiers ou répertoires.
`plugins.load.paths` — chemins explicites de fichier ou de répertoire.
</Step>
<Step title="Plugins d’espace de travail">
<Step title="Plugins du workspace">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` et `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
@ -191,16 +190,18 @@ OpenClaw recherche les plugins dans cet ordre (première correspondance gagnante
### Règles d’activation
- `plugins.enabled: false` désactive tous les plugins
- `plugins.deny` l’emporte toujours sur allow
- `plugins.deny` prime toujours sur allow
- `plugins.entries.\<id\>.enabled: false` désactive ce plugin
- Les plugins provenant de l’espace de travail sont **désactivés par défaut** (ils doivent être explicitement activés)
- Les plugins inclus suivent l’ensemble intégré activé par défaut sauf remplacement
- Les plugins d’origine workspace sont **désactivés par défaut** (ils doivent être explicitement activés)
- Les plugins inclus suivent l’ensemble intégré activé par défaut, sauf remplacement
- Les slots exclusifs peuvent forcer l’activation du plugin sélectionné pour ce slot
- Certains plugins inclus opt-in sont activés automatiquement lorsque la configuration nomme une
surface appartenant au plugin, comme une référence de modèle de fournisseur, une configuration de canal, ou un runtime de harnais
- Les routes Codex de la famille OpenAI conservent des frontières de plugin séparées :
`openai-codex/*` appartient au plugin OpenAI, tandis que le plugin inclus du
serveur d’application Codex est sélectionné par `embeddedHarness.runtime: "codex"` ou par les références de modèles héritées `codex/*`
- Certains plugins inclus sur opt-in sont activés automatiquement lorsque la configuration nomme une
surface appartenant au plugin, comme une référence de modèle de fournisseur, une configuration de canal ou un
runtime de harness
- Les routes Codex de la famille OpenAI conservent des limites de plugin distinctes :
`openai-codex/*` appartient au plugin OpenAI, tandis que le plugin intégré de
serveur d’application Codex est sélectionné par `embeddedHarness.runtime: "codex"` ou les anciennes
références de modèle `codex/*`
## Slots de plugins (catégories exclusives)
@ -217,16 +218,16 @@ Certaines catégories sont exclusives (une seule active à la fois) :
}
```
| Slot | Ce qu’il contrôle | Par défaut |
| --------------- | ------------------------- | -------------------- |
| `memory` | Plugin Memory actif | `memory-core` |
| `contextEngine` | Moteur de contexte actif | `legacy` (intégré) |
| Slot | Ce qu’il contrôle | Par défaut |
| --------------- | ---------------------------- | ------------------- |
| `memory` | Plugin Active Memory | `memory-core` |
| `contextEngine` | Moteur de contexte actif | `legacy` (intégré) |
## Référence CLI
```bash
openclaw plugins list # inventaire compact
openclaw plugins list --enabled # seulement les plugins chargés
openclaw plugins list --enabled # plugins chargés uniquement
openclaw plugins list --verbose # lignes de détail par plugin
openclaw plugins list --json # inventaire lisible par machine
openclaw plugins inspect <id> # détail approfondi
@ -237,7 +238,7 @@ openclaw plugins doctor # diagnostics
openclaw plugins install <package> # installer (ClawHub d’abord, puis npm)
openclaw plugins install clawhub:<pkg> # installer depuis ClawHub uniquement
openclaw plugins install <spec> --force # écraser l’installation existante
openclaw plugins install <spec> --force # écraser une installation existante
openclaw plugins install <path> # installer depuis un chemin local
openclaw plugins install -l <path> # lier (sans copie) pour le développement
openclaw plugins install <plugin> --marketplace <source>
@ -257,52 +258,57 @@ openclaw plugins disable <id>
```
Les plugins inclus sont livrés avec OpenClaw. Beaucoup sont activés par défaut (par exemple
les fournisseurs de modèles inclus, les fournisseurs de parole inclus, et le plugin navigateur inclus). D’autres plugins inclus nécessitent toujours `openclaw plugins enable <id>`.
les fournisseurs de modèles inclus, les fournisseurs vocaux inclus et le plugin navigateur
inclus). Les autres plugins inclus nécessitent toujours `openclaw plugins enable <id>`.
`--force` écrase en place un plugin installé existant ou un pack de hooks. Utilisez
`openclaw plugins update <id-or-npm-spec>` pour les mises à niveau de routine des plugins npm
suivis. Ce n’est pas pris en charge avec `--link`, qui réutilise le chemin source au lieu
`--force` écrase sur place un plugin installé existant ou un pack de hooks existant. Utilisez
`openclaw plugins update <id-or-npm-spec>` pour les mises à niveau courantes des
plugins npm suivis. Il n’est pas pris en charge avec `--link`, qui réutilise le chemin source au lieu
de copier vers une cible d’installation gérée.
Lorsque `plugins.allow` est déjà défini, `openclaw plugins install` ajoute
l’identifiant du plugin installé à cette liste d’autorisation avant de l’activer, de sorte que les installations soient
immédiatement chargeables après redémarrage.
Lorsque `plugins.allow` est déjà défini, `openclaw plugins install` ajoute l’identifiant du plugin
installé à cette liste d’autorisation avant de l’activer, afin que les installations puissent être
chargées immédiatement après redémarrage.
`openclaw plugins update <id-or-npm-spec>` s’applique aux installations suivies. Passer
une spécification de package npm avec un dist-tag ou une version exacte résout le nom du package vers l’enregistrement du plugin suivi et enregistre la nouvelle spécification pour les mises à jour futures.
Passer le nom du package sans version fait revenir une installation épinglée exacte vers
la branche de version par défaut du registre. Si le plugin npm installé correspond déjà à
`openclaw plugins update <id-or-npm-spec>` s’applique aux installations suivies. Le fait de transmettre
une spécification de package npm avec un dist-tag ou une version exacte résout le nom du package
vers l’enregistrement de plugin suivi et enregistre la nouvelle spécification pour les futures mises à jour.
Transmettre le nom du package sans version fait revenir une installation exacte épinglée vers la
ligne de publication par défaut du registre. Si le plugin npm installé correspond déjà à
la version résolue et à l’identité d’artefact enregistrée, OpenClaw ignore la mise à jour
sans téléchargement, réinstallation ni réécriture de configuration.
`--pin` est réservé à npm. Il n’est pas pris en charge avec `--marketplace`, car
les installations via marketplace persistent des métadonnées de source marketplace au lieu d’une spécification npm.
les installations marketplace conservent les métadonnées de source marketplace au lieu d’une spécification npm.
`--dangerously-force-unsafe-install` est un remplacement d’urgence pour les faux
positifs du scanner intégré de code dangereux. Il permet aux installations et mises à jour de plugins de se poursuivre malgré des résultats `critical` intégrés, mais il ne contourne toujours pas les blocages de politique `before_install` du plugin ni les blocages dus aux échecs de scan.
positifs du scanner intégré de code dangereux. Il permet aux installations et mises à jour de plugins
de continuer malgré les résultats intégrés `critical`, mais il
ne contourne toujours pas les blocages de politique `before_install` du plugin ni le blocage en cas d’échec d’analyse.
Cet indicateur CLI s’applique uniquement aux flux d’installation/mise à jour de plugins. Les installations de dépendances de Skills adossées au Gateway utilisent à la place le remplacement de requête correspondant `dangerouslyForceUnsafeInstall`, tandis que `openclaw skills install` reste le flux séparé de téléchargement/installation de skills ClawHub.
Ce drapeau CLI s’applique uniquement aux flux d’installation/mise à jour de plugins. Les installations de dépendances
de Skills adossées au Gateway utilisent à la place la surcharge de requête correspondante `dangerouslyForceUnsafeInstall`, tandis que
`openclaw skills install` reste le flux distinct de téléchargement/installation de Skills ClawHub.
Les bundles compatibles participent au même flux list/inspect/enable/disable
des plugins. La prise en charge runtime actuelle inclut les Skills de bundle, les
command-skills Claude, les valeurs par défaut de `settings.json` Claude, les
valeurs par défaut Claude `.lsp.json` et `lspServers` déclarées dans le manifeste, les
command-skills Cursor, et les répertoires de hooks Codex compatibles.
Les bundles compatibles participent au même flux de liste/inspection/activation/désactivation
des plugins. La prise en charge actuelle à l’exécution inclut les Skills de bundle, les command-skills Claude,
les valeurs par défaut Claude `settings.json`, les valeurs par défaut Claude `.lsp.json` et `lspServers`
déclarés dans le manifeste, les command-skills Cursor et les répertoires de hooks Codex compatibles.
`openclaw plugins inspect <id>` signale également les capacités de bundle détectées ainsi que
les entrées MCP et LSP prises en charge ou non prises en charge pour les plugins adossés à un bundle.
`openclaw plugins inspect <id>` signale aussi les capacités de bundle détectées ainsi que
les entrées de serveur MCP et LSP prises en charge ou non prises en charge pour les plugins adossés à un bundle.
Les sources marketplace peuvent être un nom de marketplace connu Claude provenant de
`~/.claude/plugins/known_marketplaces.json`, une racine marketplace locale ou un chemin
`marketplace.json`, un raccourci GitHub comme `owner/repo`, une URL de dépôt GitHub,
ou une URL git. Pour les marketplaces distants, les entrées de plugin doivent rester dans le dépôt marketplace cloné et utiliser uniquement des sources de chemin relatives.
`~/.claude/plugins/known_marketplaces.json`, une racine de marketplace locale ou un chemin
`marketplace.json`, une forme abrégée GitHub comme `owner/repo`, une URL de dépôt GitHub ou une URL git. Pour les marketplaces distantes, les entrées de plugin doivent rester dans le
dépôt de marketplace cloné et utiliser uniquement des sources de chemin relatif.
Voir la [référence CLI `openclaw plugins`](/fr/cli/plugins) pour tous les détails.
## Aperçu de l’API des plugins
## Vue d’ensemble de l’API Plugin
Les plugins natifs exportent un objet d’entrée qui expose `register(api)`. Les
anciens plugins peuvent encore utiliser `activate(api)` comme alias hérité, mais les nouveaux plugins doivent
Les plugins natifs exportent un objet d’entrée qui expose `register(api)`. Les anciens
plugins peuvent encore utiliser `activate(api)` comme alias hérité, mais les nouveaux plugins doivent
utiliser `register`.
```typescript
@ -324,48 +330,47 @@ export default definePluginEntry({
```
OpenClaw charge l’objet d’entrée et appelle `register(api)` pendant l’activation
du plugin. Le chargeur retombe encore sur `activate(api)` pour les anciens plugins,
mais les plugins inclus et les nouveaux plugins externes doivent considérer `register` comme le
contrat public.
du plugin. Le chargeur se replie encore sur `activate(api)` pour les anciens plugins,
mais les plugins inclus et les nouveaux plugins externes doivent considérer `register` comme le contrat public.
Méthodes d’enregistrement courantes :
| Method | Ce que cela enregistre |
| --------------------------------------- | -------------------------- |
| `registerProvider` | Fournisseur de modèle (LLM) |
| `registerChannel` | Canal de chat |
| `registerTool` | Outil d’agent |
| `registerHook` / `on(...)` | Hooks de cycle de vie |
| `registerSpeechProvider` | Text-to-speech / STT |
| `registerRealtimeTranscriptionProvider` | STT en streaming |
| `registerRealtimeVoiceProvider` | Voix temps réel duplex |
| `registerMediaUnderstandingProvider` | Analyse image/audio |
| `registerImageGenerationProvider` | Génération d’images |
| `registerMusicGenerationProvider` | Génération musicale |
| `registerVideoGenerationProvider` | Génération vidéo |
| Method | Ce qu’elle enregistre |
| --------------------------------------- | ---------------------------- |
| `registerProvider` | Fournisseur de modèle (LLM) |
| `registerChannel` | Canal de chat |
| `registerTool` | Outil d’agent |
| `registerHook` / `on(...)` | Hooks de cycle de vie |
| `registerSpeechProvider` | Synthèse vocale / STT |
| `registerRealtimeTranscriptionProvider` | STT en streaming |
| `registerRealtimeVoiceProvider` | Voix en temps réel duplex |
| `registerMediaUnderstandingProvider` | Analyse image/audio |
| `registerImageGenerationProvider` | Génération d’images |
| `registerMusicGenerationProvider` | Génération musicale |
| `registerVideoGenerationProvider` | Génération vidéo |
| `registerWebFetchProvider` | Fournisseur de récupération / scraping web |
| `registerWebSearchProvider` | Recherche web |
| `registerHttpRoute` | Point de terminaison HTTP |
| `registerCommand` / `registerCli` | Commandes CLI |
| `registerContextEngine` | Moteur de contexte |
| `registerService` | Service d’arrière-plan |
| `registerWebSearchProvider` | Recherche web |
| `registerHttpRoute` | Point de terminaison HTTP |
| `registerCommand` / `registerCli` | Commandes CLI |
| `registerContextEngine` | Moteur de contexte |
| `registerService` | Service en arrière-plan |
Comportement de garde des hooks pour les hooks de cycle de vie typés :
Comportement des gardes de hooks pour les hooks de cycle de vie typés :
- `before_tool_call` : `{ block: true }` est terminal ; les gestionnaires de priorité inférieure sont ignorés.
- `before_tool_call` : `{ block: false }` est un no-op et n’efface pas un blocage antérieur.
- `before_tool_call` : `{ block: false }` n’a aucun effet et n’annule pas un blocage antérieur.
- `before_install` : `{ block: true }` est terminal ; les gestionnaires de priorité inférieure sont ignorés.
- `before_install` : `{ block: false }` est un no-op et n’efface pas un blocage antérieur.
- `before_install` : `{ block: false }` n’a aucun effet et n’annule pas un blocage antérieur.
- `message_sending` : `{ cancel: true }` est terminal ; les gestionnaires de priorité inférieure sont ignorés.
- `message_sending` : `{ cancel: false }` est un no-op et n’efface pas une annulation antérieure.
- `message_sending` : `{ cancel: false }` n’a aucun effet et n’annule pas une annulation antérieure.
Pour le comportement complet des hooks typés, voir [Aperçu du SDK](/fr/plugins/sdk-overview#hook-decision-semantics).
Pour le comportement complet des hooks typés, voir [SDK Overview](/fr/plugins/sdk-overview#hook-decision-semantics).
## Lié
- [Créer des plugins](/fr/plugins/building-plugins) — créer votre propre plugin
- [Building Plugins](/fr/plugins/building-plugins) — créer votre propre plugin
- [Plugin Bundles](/fr/plugins/bundles) — compatibilité des bundles Codex/Claude/Cursor
- [Manifeste de plugin](/fr/plugins/manifest) — schéma du manifeste
- [Enregistrer des outils](/fr/plugins/building-plugins#registering-agent-tools) — ajouter des outils d’agent dans un plugin
- [Internals des plugins](/fr/plugins/architecture) — modèle de capacités et pipeline de chargement
- [Plugins communautaires](/fr/plugins/community) — listes tierces
- [Plugin Manifest](/fr/plugins/manifest) — schéma du manifeste
- [Registering Tools](/fr/plugins/building-plugins#registering-agent-tools) — ajouter des outils d’agent dans un plugin
- [Plugin Internals](/fr/plugins/architecture) — modèle de capacités et pipeline de chargement
- [Community Plugins](/fr/plugins/community) — listes tierces

323
docs/fr/web/control-ui.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Vous voulez utiliser le Gateway depuis un navigateur
- Vous voulez un accès Tailnet sans tunnels SSH
summary: Interface de contrôle basée sur le navigateur pour le Gateway (chat, nodes, configuration)
- Vous souhaitez utiliser le Gateway depuis un navigateur
- Vous souhaitez un accès Tailnet sans tunnels SSH
summary: Interface de contrôle basée sur le navigateur pour le Gateway (chat, nœuds, configuration)
title: Interface de contrôle
x-i18n:
generated_at: "2026-04-24T07:40:02Z"
generated_at: "2026-04-24T08:58:37Z"
model: gpt-5.4
provider: openai
source_hash: 2ad0d0cef7d842eddf665ba50f37403df258b17d4c072d22a30d1bc3830dc467
source_hash: c84a74e20d6c8829168025830ff4ec8f650f10f72fcaed7c8d2f5d92ab98d616
source_path: web/control-ui.md
workflow: 15
---
@ -16,182 +16,186 @@ x-i18n:
L’interface de contrôle est une petite application monopage **Vite + Lit** servie par le Gateway :
- par défaut : `http://<host>:18789/`
- préfixe facultatif : définissez `gateway.controlUi.basePath` (par ex. `/openclaw`)
- préfixe facultatif : définissez `gateway.controlUi.basePath` (par exemple `/openclaw`)
Elle communique **directement avec le WebSocket Gateway** sur le même port.
Elle communique **directement avec le WebSocket du Gateway** sur le même port.
## Ouverture rapide (local)
Si le Gateway s’exécute sur le même ordinateur, ouvrez :
Si le Gateway fonctionne sur le même ordinateur, ouvrez :
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (ou [http://localhost:18789/](http://localhost:18789/))
Si la page ne se charge pas, démarrez d’abord le Gateway : `openclaw gateway`.
L’authentification est fournie lors de la poignée de main WebSocket via :
L’authentification est fournie lors de la négociation WebSocket via :
- `connect.params.auth.token`
- `connect.params.auth.password`
- les en-têtes d’identité Tailscale Serve lorsque `gateway.auth.allowTailscale: true`
- les en-têtes d’identité trusted-proxy lorsque `gateway.auth.mode: "trusted-proxy"`
- les en-têtes d’identité de proxy approuvé lorsque `gateway.auth.mode: "trusted-proxy"`
Le panneau des paramètres du tableau de bord conserve un jeton pour la session
de l’onglet actuel du navigateur et l’URL Gateway sélectionnée ; les mots de passe ne sont pas persistés. L’onboarding
génère généralement un jeton Gateway pour l’authentification à secret partagé à la première connexion, mais l’authentification
par mot de passe fonctionne aussi lorsque `gateway.auth.mode` vaut `"password"`.
Le panneau de paramètres du tableau de bord conserve un jeton pour la session
de l’onglet actuel du navigateur et l’URL du Gateway sélectionnée ; les mots de passe ne sont pas persistés. L’intégration initiale génère généralement
un jeton Gateway pour l’authentification par secret partagé lors de la première connexion, mais l’authentification par mot de passe fonctionne aussi lorsque `gateway.auth.mode` vaut `"password"`.
## Appairage d’appareil (première connexion)
## Appairage de l’appareil (première connexion)
Lorsque vous vous connectez à l’interface de contrôle depuis un nouveau navigateur ou appareil, le Gateway
exige une **approbation d’appairage unique** — même si vous êtes sur le même Tailnet
avec `gateway.auth.allowTailscale: true`. Il s’agit d’une mesure de sécurité destinée à empêcher
exige **une approbation d’appairage à usage unique** — même si vous êtes sur le même Tailnet
avec `gateway.auth.allowTailscale: true`. Il s’agit d’une mesure de sécurité visant à empêcher
les accès non autorisés.
**Ce que vous verrez :** "disconnected (1008): pairing required"
**Ce que vous verrez :** `disconnected (1008): pairing required`
**Pour approuver l’appareil :**
```bash
# List pending requests
# Lister les demandes en attente
openclaw devices list
# Approve by request ID
# Approuver par ID de demande
openclaw devices approve <requestId>
```
Si le navigateur réessaie l’appairage avec des détails d’authentification modifiés (rôle/scopes/clé
Si le navigateur relance l’appairage avec des détails d’authentification modifiés (rôle/portées/clé
publique), la demande en attente précédente est remplacée et un nouveau `requestId` est
créé. Réexécutez `openclaw devices list` avant l’approbation.
créé. Exécutez de nouveau `openclaw devices list` avant l’approbation.
Si le navigateur est déjà appairé et que vous le faites passer d’un accès en lecture à un
accès en écriture/admin, cela est traité comme une montée d’approbation, et non comme une reconnexion silencieuse.
Si le navigateur est déjà appairé et que vous passez d’un accès en lecture à
un accès en écriture/admin, cela est traité comme une montée de privilèges d’approbation, et non comme une reconnexion silencieuse.
OpenClaw conserve l’ancienne approbation active, bloque la reconnexion élargie,
et vous demande d’approuver explicitement le nouvel ensemble de scopes.
et vous demande d’approuver explicitement le nouvel ensemble de portées.
Une fois approuvé, l’appareil est mémorisé et ne nécessitera pas de nouvelle approbation sauf
Une fois approuvé, l’appareil est mémorisé et ne nécessitera pas de nouvelle approbation, sauf
si vous le révoquez avec `openclaw devices revoke --device <id> --role <role>`. Voir
[CLI Devices](/fr/cli/devices) pour la rotation et la révocation des jetons.
[CLI Devices](/fr/cli/devices) pour la rotation des jetons et la révocation.
**Remarques :**
- Les connexions directes de navigateur local loopback (`127.0.0.1` / `localhost`) sont
- Les connexions directes du navigateur en local loopback (`127.0.0.1` / `localhost`) sont
approuvées automatiquement.
- Les connexions navigateur Tailnet et LAN exigent toujours une approbation explicite, même lorsqu’elles
- Les connexions navigateur via Tailnet et LAN exigent toujours une approbation explicite, même lorsqu’elles
proviennent de la même machine.
- Chaque profil de navigateur génère un identifiant d’appareil unique, donc changer de navigateur ou
effacer les données du navigateur nécessitera un nouvel appairage.
- Chaque profil de navigateur génère un identifiant d’appareil unique ; changer de navigateur ou
effacer les données du navigateur exigera donc un nouvel appairage.
## Identité personnelle (locale au navigateur)
L’interface de contrôle prend en charge une identité personnelle par navigateur (nom d’affichage et
avatar) attachée aux messages sortants pour l’attribution dans les sessions partagées. Elle
réside dans le stockage du navigateur, est limitée au profil de navigateur actuel, et n’est pas
est stockée dans le navigateur, limitée au profil de navigateur actuel, et n’est pas
synchronisée avec d’autres appareils ni persistée côté serveur au-delà des métadonnées normales
d’auteur de transcription sur les messages que vous envoyez réellement. Effacer les données du site ou
d’auteur dans la transcription des messages que vous envoyez réellement. Effacer les données du site ou
changer de navigateur la réinitialise à vide.
## Endpoint de configuration runtime
## Point de terminaison de configuration d’exécution
L’interface de contrôle récupère ses paramètres runtime depuis
`/__openclaw/control-ui-config.json`. Cet endpoint est protégé par la même
authentification gateway que le reste de la surface HTTP : les navigateurs non authentifiés ne peuvent pas
L’interface de contrôle récupère ses paramètres d’exécution depuis
`/__openclaw/control-ui-config.json`. Ce point de terminaison est protégé par la même
authentification Gateway que le reste de la surface HTTP : les navigateurs non authentifiés ne peuvent pas
le récupérer, et une récupération réussie exige soit un jeton/mot de passe Gateway déjà valide,
soit une identité Tailscale Serve, soit une identité trusted-proxy.
soit une identité Tailscale Serve, soit une identité de proxy approuvé.
## Prise en charge des langues
L’interface de contrôle peut se localiser elle-même au premier chargement en fonction de la locale de votre navigateur.
Pour la remplacer ultérieurement, ouvrez **Overview -> Gateway Access -> Language**. Le
sélecteur de locale se trouve dans la carte Gateway Access, pas dans Appearance.
L’interface de contrôle peut se localiser lors du premier chargement en fonction de la langue de votre navigateur.
Pour la remplacer ensuite, ouvrez **Overview -> Gateway Access -> Language**. Le
sélecteur de langue se trouve dans la carte Gateway Access, et non sous Appearance.
- Locales prises en charge : `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
- Les traductions non anglaises sont chargées à la demande dans le navigateur.
- La locale sélectionnée est enregistrée dans le stockage du navigateur et réutilisée lors des visites futures.
- Langues prises en charge : `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
- Les traductions autres qu’en anglais sont chargées à la demande dans le navigateur.
- La langue sélectionnée est enregistrée dans le stockage du navigateur et réutilisée lors des visites futures.
- Les clés de traduction manquantes reviennent à l’anglais.
## Ce qu’elle peut faire (aujourd’hui)
- Discuter avec le modèle via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
- Parler directement à OpenAI Realtime depuis le navigateur via WebRTC. Le Gateway
- Communiquer directement avec OpenAI Realtime depuis le navigateur via WebRTC. Le Gateway
génère un secret client Realtime de courte durée avec `talk.realtime.session` ; le
navigateur envoie l’audio du microphone directement à OpenAI et relaie les appels d’outil
`openclaw_agent_consult` via `chat.send` vers le plus grand
modèle OpenClaw configuré.
- Diffuser les appels d’outils + les cartes de sortie d’outil en direct dans Chat (événements agent)
- Canaux : état des canaux intégrés ainsi que des plugins groupés/externes, connexion QR, et configuration par canal (`channels.status`, `web.login.*`, `config.patch`)
navigateur envoie l’audio du microphone directement à OpenAI et relaie
les appels d’outil `openclaw_agent_consult` via `chat.send` pour le modèle OpenClaw
plus grand configuré.
- Diffuser les appels d’outil + cartes de sortie d’outil en direct dans le chat (événements d’agent)
- Canaux : statut des canaux intégrés ainsi que des canaux de Plugin bundled/externes, connexion QR, et configuration par canal (`channels.status`, `web.login.*`, `config.patch`)
- Instances : liste de présence + actualisation (`system-presence`)
- Sessions : liste + remplacements par session pour modèle/thinking/fast/verbose/trace/reasoning (`sessions.list`, `sessions.patch`)
- Dreams : statut du Dreaming, bascule activation/désactivation et lecteur Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Sessions : liste + remplacements par session pour modèle/réflexion/rapide/verbeux/trace/raisonnement (`sessions.list`, `sessions.patch`)
- Dreams : état de Dreaming, activation/désactivation, et lecteur de Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Tâches Cron : lister/ajouter/modifier/exécuter/activer/désactiver + historique d’exécution (`cron.*`)
- Skills : état, activation/désactivation, installation, mises à jour de clé API (`skills.*`)
- Nodes : liste + capacités (`node.list`)
- Approbations exec : modifier les listes d’autorisation gateway ou node + politique ask pour `exec host=gateway/node` (`exec.approvals.*`)
- Config : voir/modifier `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
- Config : appliquer + redémarrer avec validation (`config.apply`) et réveiller la dernière session active
- Les écritures de configuration incluent une garde par hash de base pour éviter d’écraser des modifications concurrentes
- Les écritures de configuration (`config.set`/`config.apply`/`config.patch`) effectuent aussi en prévol la résolution active de SecretRef pour les refs dans la charge utile de configuration soumise ; les refs actives soumises non résolues sont rejetées avant l’écriture
- Nœuds : liste + capacités (`node.list`)
- Approbations exec : modifier les listes d’autorisation du Gateway ou du nœud + demander la stratégie pour `exec host=gateway/node` (`exec.approvals.*`)
- Configuration : afficher/modifier `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
- Configuration : appliquer + redémarrer avec validation (`config.apply`) et réveiller la dernière session active
- Les écritures de configuration incluent une protection par hachage de base pour éviter d’écraser des modifications concurrentes
- Les écritures de configuration (`config.set`/`config.apply`/`config.patch`) effectuent également en amont la résolution active des SecretRef pour les références présentes dans la charge utile de configuration envoyée ; les références actives non résolues présentes dans la charge utile envoyée sont rejetées avant l’écriture
- Schéma de configuration + rendu de formulaire (`config.schema` / `config.schema.lookup`,
y compris `title` / `description` de champ, indices d’UI correspondants, résumés immédiats des enfants,
métadonnées de documentation sur les nœuds imbriqués objet/wildcard/tableau/composition,
ainsi que les schémas de plugin + canal lorsque disponibles) ; l’éditeur Raw JSON n’est
disponible que lorsque le snapshot a un aller-retour brut sûr
- Si un snapshot ne peut pas effectuer en toute sécurité un aller-retour de texte brut, l’interface de contrôle force le mode Form et désactive le mode Raw pour ce snapshot
- « Reset to saved » dans l’éditeur Raw JSON préserve la forme rédigée en brut (formatage, commentaires, disposition `$include`) au lieu de réafficher un snapshot aplati, afin que les modifications externes survivent à une réinitialisation lorsque le snapshot peut effectuer en toute sécurité un aller-retour
- Les valeurs d’objet SecretRef structurées sont rendues en lecture seule dans les entrées texte du formulaire pour éviter une corruption accidentelle objet-vers-chaîne
- Débogage : snapshots statut/health/models + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`)
- Logs : suivi en direct des fichiers journaux du gateway avec filtre/export (`logs.tail`)
- Mise à jour : exécuter une mise à jour package/git + redémarrage (`update.run`) avec rapport de redémarrage
y compris les champs `title` / `description`, les indications d’interface correspondantes, les résumés immédiats des enfants,
les métadonnées de documentation sur les nœuds d’objet imbriqué/joker/tableau/composition,
ainsi que les schémas de Plugin + de canal lorsqu’ils sont disponibles) ; l’éditeur JSON brut n’est
disponible que lorsque l’instantané peut effectuer un aller-retour sûr du brut
- Si un instantané ne peut pas effectuer en toute sécurité un aller-retour du texte brut, l’interface de contrôle force le mode Form et désactive le mode Raw pour cet instantané
- Dans l’éditeur JSON brut, « Reset to saved » préserve la forme rédigée en brut (mise en forme, commentaires, structure `$include`) au lieu de réafficher un instantané aplati, afin que les modifications externes survivent à une réinitialisation lorsque l’instantané peut effectuer un aller-retour sûr
- Les valeurs d’objet SecretRef structurées sont affichées en lecture seule dans les champs texte du formulaire afin d’éviter une corruption accidentelle d’objet en chaîne
- Débogage : instantanés d’état/santé/modèles + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`)
- Journaux : suivi en direct des journaux de fichiers du Gateway avec filtre/export (`logs.tail`)
- Mise à jour : exécuter une mise à jour de paquet/git + redémarrage (`update.run`) avec rapport de redémarrage
Remarques sur le panneau des tâches Cron :
- Pour les tâches isolées, la livraison par défaut est announce summary. Vous pouvez la passer à none si vous voulez des exécutions internes uniquement.
- Les champs canal/cible apparaissent lorsque announce est sélectionné.
- Pour les tâches isolées, le mode de livraison par défaut est l’annonce du résumé. Vous pouvez passer à aucun si vous souhaitez des exécutions internes uniquement.
- Les champs canal/cible apparaissent lorsque l’annonce est sélectionnée.
- Le mode Webhook utilise `delivery.mode = "webhook"` avec `delivery.to` défini sur une URL Webhook HTTP(S) valide.
- Pour les tâches main-session, les modes de livraison webhook et none sont disponibles.
- Les contrôles d’édition avancée incluent delete-after-run, clear agent override, les options cron exact/stagger,
les remplacements agent model/thinking, et les bascules de livraison best-effort.
- La validation du formulaire est intégrée avec des erreurs au niveau du champ ; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
- Pour les tâches de session principale, les modes de livraison webhook et none sont disponibles.
- Les contrôles de modification avancés incluent supprimer après exécution, effacer le remplacement d’agent, les options Cron exactes/échelonnées,
les remplacements de modèle/réflexion d’agent, et les bascules de livraison au mieux.
- La validation du formulaire est en ligne avec des erreurs au niveau des champs ; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
- Définissez `cron.webhookToken` pour envoyer un jeton bearer dédié ; s’il est omis, le webhook est envoyé sans en-tête d’authentification.
- Repli obsolète : les anciennes tâches stockées avec `notify: true` peuvent toujours utiliser `cron.webhook` jusqu’à migration.
- Solution de repli obsolète : les anciennes tâches enregistrées avec `notify: true` peuvent encore utiliser `cron.webhook` jusqu’à leur migration.
## Comportement du chat
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via des événements `chat`.
- Renvoyer avec la même `idempotencyKey` retourne `{ status: "in_flight" }` pendant l’exécution, et `{ status: "ok" }` après la fin.
- Les réponses `chat.history` sont bornées en taille pour la sécurité de l’UI. Lorsque les entrées de transcription sont trop volumineuses, Gateway peut tronquer les champs texte longs, omettre les blocs de métadonnées lourds, et remplacer les messages surdimensionnés par un placeholder (`[chat.history omitted: message too large]`).
- Les images assistant/générées sont persistées comme références de média gérées et resservies via des URLs média Gateway authentifiées, de sorte que les rechargements ne dépendent pas de la conservation des charges utiles image base64 brutes dans la réponse de l’historique du chat.
- `chat.history` supprime aussi les balises de directive inline réservées à l’affichage du texte assistant visible (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), 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/full-width divulgués, et omet les entrées assistant dont tout le texte visible est seulement le jeton silencieux exact `NO_REPLY` / `no_reply`.
- `chat.inject` ajoute une note assistant à la transcription de session et diffuse un événement `chat` pour les mises à jour UI uniquement (pas d’exécution d’agent, pas de livraison de canal).
- Les sélecteurs de modèle et de thinking dans l’en-tête du chat patchent immédiatement la session active via `sessions.patch` ; ce sont des remplacements persistants de session, et non des options d’envoi à usage unique.
- Le mode Talk utilise le fournisseur de voix temps réel enregistré. Configurez OpenAI avec
`talk.provider: "openai"` plus `talk.providers.openai.apiKey`, ou réutilisez la
configuration du fournisseur temps réel Voice Call. Le navigateur ne reçoit jamais la clé API OpenAI standard ; il reçoit seulement le secret client Realtime éphémère. L’invite de session Realtime est assemblée par le Gateway ; `talk.realtime.session` n’accepte pas de remplacements d’instructions fournis par l’appelant.
- Dans le compositeur Chat, le contrôle Talk est le bouton en forme d’ondes à côté du
bouton de dictée micro. Lorsque Talk démarre, la ligne d’état du compositeur affiche
`Connecting Talk...`, puis `Talk live` pendant que l’audio est connecté, ou
`Asking OpenClaw...` pendant qu’un appel d’outil temps réel consulte le plus grand
modèle configuré via `chat.send`.
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via les événements `chat`.
- Un nouvel envoi avec la même `idempotencyKey` renvoie `{ status: "in_flight" }` pendant l’exécution, et `{ status: "ok" }` après la fin.
- Les réponses `chat.history` sont limitées en taille pour la sécurité de l’interface. Lorsque les entrées de transcription sont trop volumineuses, le Gateway peut tronquer les longs champs texte, omettre les blocs de métadonnées lourds, et remplacer les messages surdimensionnés par un espace réservé (`[chat.history omitted: message too large]`).
- Les images d’assistant/générées sont conservées comme références média gérées et servies à nouveau via des URL média Gateway authentifiées, de sorte que les rechargements ne dépendent pas du maintien des charges utiles d’image base64 brutes dans la réponse de l’historique du chat.
- `chat.history` supprime également du texte visible de l’assistant les balises de directive en ligne uniquement destinées à l’affichage (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), 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, et omet les entrées d’assistant dont tout le texte visible est uniquement le jeton silencieux exact `NO_REPLY` / `no_reply`.
- `chat.inject` ajoute une note d’assistant à la transcription de la session et diffuse un événement `chat` pour des mises à jour d’interface uniquement (pas d’exécution d’agent, pas de livraison à un canal).
- Les sélecteurs de modèle et de réflexion dans l’en-tête du chat appliquent immédiatement des correctifs à la session active via `sessions.patch` ; il s’agit de remplacements persistants de session, et non d’options d’envoi pour un seul tour.
- Le mode Talk utilise un fournisseur vocal temps réel enregistré qui prend en charge les
sessions WebRTC dans le navigateur. Configurez OpenAI avec `talk.provider: "openai"` plus
`talk.providers.openai.apiKey`, ou réutilisez la configuration du fournisseur temps réel Voice Call.
Le navigateur ne reçoit jamais la clé API OpenAI standard ; il reçoit
uniquement le secret client Realtime éphémère. La voix temps réel Google Live est
prise en charge pour le backend Voice Call et les ponts Google Meet, mais pas encore pour ce chemin
WebRTC du navigateur. L’invite de session Realtime est assemblée par le Gateway ;
`talk.realtime.session` n’accepte pas de remplacements d’instructions fournis par l’appelant.
- Dans le compositeur de chat, la commande Talk est le bouton en forme d’ondes à côté du
bouton de dictée au microphone. Lorsque Talk démarre, la ligne d’état du compositeur affiche
`Connecting Talk...`, puis `Talk live` lorsque l’audio est connecté, ou
`Asking OpenClaw...` lorsqu’un appel d’outil temps réel consulte le
plus grand modèle configuré via `chat.send`.
- Arrêt :
- Cliquez sur **Stop** (appelle `chat.abort`)
- Pendant qu’une exécution est active, les suivis normaux sont mis en file d’attente. Cliquez sur **Steer** sur un message en attente pour injecter ce suivi dans le tour en cours.
- Tapez `/stop` (ou des phrases d’interruption autonomes comme `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) pour interrompre hors bande
- Lorsqu’une exécution est active, les suivis normaux sont mis en file d’attente. Cliquez sur **Steer** sur un message en attente pour injecter ce suivi dans le tour en cours.
- Saisissez `/stop` (ou des expressions d’arrêt autonomes comme `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) pour interrompre hors bande
- `chat.abort` prend en charge `{ sessionKey }` (sans `runId`) pour interrompre toutes les exécutions actives de cette session
- Conservation partielle après interruption :
- Lorsqu’une exécution est interrompue, du texte assistant partiel peut quand même être affiché dans l’UI
- Gateway persiste le texte assistant partiel interrompu dans l’historique de transcription lorsqu’une sortie tamponnée existe
- Les entrées persistées incluent des métadonnées d’interruption afin que les consommateurs de transcription puissent distinguer les partiels interrompus de la sortie normale de fin
- Conservation partielle lors de l’interruption :
- Lorsqu’une exécution est interrompue, un texte partiel de l’assistant peut toujours être affiché dans l’interface
- Le Gateway conserve le texte partiel interrompu de l’assistant dans l’historique de la transcription lorsqu’une sortie tamponnée existe
- Les entrées conservées incluent des métadonnées d’interruption afin que les consommateurs de transcription puissent distinguer les fragments dus à une interruption d’une sortie normale terminée
## Intégrations hébergées
Les messages assistant peuvent afficher du contenu web hébergé en ligne avec le shortcode `[embed ...]`.
La politique sandbox iframe est contrôlée par
Les messages d’assistant peuvent afficher du contenu web hébergé en ligne via le shortcode `[embed ...]`.
La politique de sandbox d’iframe est contrôlée par
`gateway.controlUi.embedSandbox` :
- `strict` : désactive l’exécution de scripts dans les intégrations hébergées
- `scripts` : autorise les intégrations interactives tout en conservant l’isolation d’origine ; c’est
la valeur par défaut et c’est généralement suffisant pour les jeux/widgets navigateur autonomes
la valeur par défaut et elle suffit généralement pour les jeux/widgets navigateur autonomes
- `trusted` : ajoute `allow-same-origin` en plus de `allow-scripts` pour les
documents de même site qui ont intentionnellement besoin de privilèges plus élevés
documents du même site qui ont intentionnellement besoin de privilèges plus élevés
Exemple :
@ -205,19 +209,18 @@ Exemple :
}
```
Utilisez `trusted` uniquement lorsque le document intégré a réellement besoin d’un
comportement same-origin. Pour la plupart des jeux générés par agent et des canvases interactifs, `scripts` est
le choix le plus sûr.
N’utilisez `trusted` que lorsque le document intégré a réellement besoin d’un
comportement de même origine. Pour la plupart des jeux générés par agent et des canevas interactifs, `scripts` est le choix le plus sûr.
Les URLs d’intégration externes absolues `http(s)` restent bloquées par défaut. Si vous
voulez intentionnellement que `[embed url="https://..."]` charge des pages tierces, définissez
Les URL d’intégration externes absolues `http(s)` restent bloquées par défaut. Si vous
souhaitez intentionnellement que `[embed url="https://..."]` charge des pages tierces, définissez
`gateway.controlUi.allowExternalEmbedUrls: true`.
## Accès Tailnet (recommandé)
### Tailscale Serve intégré (préféré)
Gardez le Gateway sur loopback et laissez Tailscale Serve le proxifier en HTTPS :
Conservez le Gateway sur local loopback et laissez Tailscale Serve le proxifier en HTTPS :
```bash
openclaw gateway --tailscale serve
@ -227,32 +230,32 @@ Ouvrez :
- `https://<magicdns>/` (ou votre `gateway.controlUi.basePath` configuré)
Par défaut, les requêtes Serve de Control UI/WebSocket peuvent s’authentifier via les en-têtes d’identité Tailscale
Par défaut, les requêtes Serve de l’interface de contrôle/WebSocket peuvent s’authentifier via les en-têtes d’identité Tailscale
(`tailscale-user-login`) lorsque `gateway.auth.allowTailscale` vaut `true`. OpenClaw
vérifie l’identité en résolvant l’adresse `x-forwarded-for` avec
`tailscale whois` et en la faisant correspondre à l’en-tête, et n’accepte ces en-têtes que lorsque la
requête atteint loopback avec les en-têtes `x-forwarded-*` de Tailscale. Définissez
`gateway.auth.allowTailscale: false` si vous voulez exiger des identifiants explicites à secret partagé
`tailscale whois` et en la comparant à l’en-tête, et n’accepte ces en-têtes que lorsque la
requête atteint local loopback avec les en-têtes `x-forwarded-*` de Tailscale. Définissez
`gateway.auth.allowTailscale: false` si vous souhaitez exiger des identifiants explicites à secret partagé
même pour le trafic Serve. Utilisez alors `gateway.auth.mode: "token"` ou
`"password"`.
Pour ce chemin d’identité Serve asynchrone, les tentatives d’authentification échouées pour la même IP cliente
et le même scope d’authentification sont sérialisées avant les écritures de limitation de débit. Des nouvelles tentatives invalides
concurrentes depuis le même navigateur peuvent donc afficher `retry later` sur la deuxième requête
au lieu de deux simples incompatibilités en course parallèle.
L’authentification Serve sans jeton suppose que l’hôte gateway est digne de confiance. Si du code local non digne de confiance
et le même périmètre d’authentification sont sérialisées avant les écritures de limitation de débit. Des
nouvelles tentatives incorrectes concurrentes depuis le même navigateur peuvent donc afficher
`retry later` sur la deuxième requête au lieu de deux simples non-correspondances en parallèle.
L’authentification Serve sans jeton suppose que l’hôte du gateway est de confiance. Si du code local non fiable
peut s’exécuter sur cet hôte, exigez une authentification par jeton/mot de passe.
### Lier à tailnet + jeton
### Liaison au tailnet + jeton
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
Puis ouvrez :
Ouvrez ensuite :
- `http://<tailscale-ip>:18789/` (ou votre `gateway.controlUi.basePath` configuré)
Collez le secret partagé correspondant dans les paramètres de l’UI (envoyé comme
Collez le secret partagé correspondant dans les paramètres de l’interface (envoyé comme
`connect.params.auth.token` ou `connect.params.auth.password`).
## HTTP non sécurisé
@ -264,15 +267,15 @@ OpenClaw **bloque** les connexions à l’interface de contrôle sans identité
Exceptions documentées :
- compatibilité HTTP non sécurisé localhost uniquement avec `gateway.controlUi.allowInsecureAuth=true`
- authentification opérateur réussie à l’interface de contrôle via `gateway.auth.mode: "trusted-proxy"`
- solution de secours `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
- authentification réussie d’opérateur à l’interface de contrôle via `gateway.auth.mode: "trusted-proxy"`
- option de secours `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Correctif recommandé :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’UI localement :
**Correctif recommandé :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’interface localement :
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (sur l’hôte gateway)
- `http://127.0.0.1:18789/` (sur l’hôte du gateway)
**Comportement de la bascule d’authentification non sécurisée :**
**Comportement de l’option d’authentification non sécurisée :**
```json5
{
@ -284,14 +287,14 @@ Exceptions documentées :
}
```
`allowInsecureAuth` est uniquement une bascule de compatibilité locale :
`allowInsecureAuth` est uniquement une option locale de compatibilité :
- Elle permet aux sessions localhost de l’interface de contrôle de continuer sans identité d’appareil dans
- Elle permet aux sessions de l’interface de contrôle sur localhost de se poursuivre sans identité d’appareil dans
des contextes HTTP non sécurisés.
- Elle ne contourne pas les vérifications d’appairage.
- Elle n’assouplit pas les exigences d’identité d’appareil à distance (hors localhost).
**Solution de secours uniquement :**
**Secours uniquement :**
```json5
{
@ -306,47 +309,47 @@ Exceptions documentées :
`dangerouslyDisableDeviceAuth` désactive les vérifications d’identité d’appareil de l’interface de contrôle et constitue une
forte dégradation de la sécurité. Revenez rapidement en arrière après usage d’urgence.
Remarque trusted-proxy :
Remarque sur le proxy approuvé :
- une authentification trusted-proxy réussie peut autoriser des sessions **opérateur** de l’interface de contrôle sans
- une authentification réussie via proxy approuvé peut autoriser des sessions d’interface de contrôle **opérateur** sans
identité d’appareil
- cela ne s’étend **pas** aux sessions de l’interface de contrôle de rôle node
- les proxys inverses loopback sur le même hôte ne satisfont toujours pas l’authentification trusted-proxy ; voir
[Authentification Trusted Proxy](/fr/gateway/trusted-proxy-auth)
- cela ne s’étend **pas** aux sessions d’interface de contrôle avec rôle de nœud
- les proxys inverses local loopback sur le même hôte ne satisfont toujours pas à l’authentification par proxy approuvé ; voir
[Authentification par proxy approuvé](/fr/gateway/trusted-proxy-auth)
Voir [Tailscale](/fr/gateway/tailscale) pour les conseils de configuration HTTPS.
## Politique de sécurité du contenu
L’interface de contrôle est fournie avec une politique `img-src` stricte : seuls les assets **same-origin** et les URLs `data:` sont autorisés. Les URLs d’image distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et n’émettent aucune récupération réseau.
L’interface de contrôle est fournie avec une politique `img-src` stricte : seules les ressources **de même origine** et les URL `data:` sont autorisées. Les URL d’image distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et n’émettent aucune requête réseau.
Ce que cela signifie en pratique :
Concrètement :
- Les avatars et images servis sous des chemins relatifs (par exemple `/avatars/<id>`) s’affichent toujours.
- Les URLs inline `data:image/...` s’affichent toujours (utile pour les charges utiles dans le protocole).
- Les URLs d’avatar distantes émises par les métadonnées de canal sont supprimées au niveau des helpers d’avatar de l’interface de contrôle et remplacées par le logo/le badge intégré, de sorte qu’un canal compromis ou malveillant ne puisse pas forcer des récupérations d’image distantes arbitraires depuis le navigateur d’un opérateur.
- Les URL `data:image/...` en ligne s’affichent toujours (utile pour les charges utiles dans le protocole).
- Les URL d’avatar distantes émises par les métadonnées de canal sont supprimées par les assistants d’avatar de l’interface de contrôle et remplacées par le logo/badge intégré, de sorte qu’un canal compromis ou malveillant ne peut pas forcer des récupérations d’images distantes arbitraires depuis le navigateur d’un opérateur.
Vous n’avez rien à changer pour obtenir ce comportement — il est toujours activé et non configurable.
Vous n’avez rien à modifier pour obtenir ce comportement — il est toujours activé et n’est pas configurable.
## Authentification de la route avatar
## Authentification de la route d’avatar
Lorsque l’authentification gateway est configurée, l’endpoint avatar de l’interface de contrôle exige le même jeton gateway que le reste de l’API :
Lorsque l’authentification gateway est configurée, le point de terminaison d’avatar de l’interface de contrôle exige le même jeton gateway que le reste de l’API :
- `GET /avatar/<agentId>` ne renvoie l’image avatar qu’aux appelants authentifiés. `GET /avatar/<agentId>?meta=1` renvoie les métadonnées d’avatar selon la même règle.
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme la route sœur assistant-media). Cela empêche la route avatar de divulguer l’identité de l’agent sur des hôtes autrement protégés.
- L’interface de contrôle elle-même transmet le jeton gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URLs blob authentifiées afin que l’image s’affiche toujours dans les tableaux de bord.
- `GET /avatar/<agentId>` ne renvoie l’image d’avatar qu’aux appelants authentifiés. `GET /avatar/<agentId>?meta=1` renvoie les métadonnées de l’avatar selon la même règle.
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme pour la route sœur de média d’assistant). Cela empêche la route d’avatar de divulguer l’identité de l’agent sur des hôtes par ailleurs protégés.
- L’interface de contrôle elle-même transmet le jeton gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URL blob authentifiées afin que l’image continue de s’afficher dans les tableaux de bord.
Si vous désactivez l’authentification gateway (non recommandé sur des hôtes partagés), la route avatar devient également non authentifiée, en cohérence avec le reste du gateway.
Si vous désactivez l’authentification gateway (non recommandé sur des hôtes partagés), la route d’avatar devient également non authentifiée, conformément au reste du gateway.
## Construction de l’UI
## Construire l’interface
Le Gateway sert des fichiers statiques depuis `dist/control-ui`. Construisez-les avec :
Le Gateway sert les fichiers statiques depuis `dist/control-ui`. Construisez-les avec :
```bash
pnpm ui:build
```
Base absolue facultative (lorsque vous voulez des URLs d’assets fixes) :
Base absolue facultative (lorsque vous souhaitez des URL de ressources fixes) :
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
@ -358,15 +361,15 @@ Pour le développement local (serveur de développement séparé) :
pnpm ui:dev
```
Puis pointez l’UI vers l’URL WS de votre Gateway (par ex. `ws://127.0.0.1:18789`).
Pointez ensuite l’interface vers l’URL WS de votre Gateway (par exemple `ws://127.0.0.1:18789`).
## Débogage/test : serveur de développement + Gateway distant
L’interface de contrôle est constituée de fichiers statiques ; la cible WebSocket est configurable et peut être
différente de l’origine HTTP. C’est pratique lorsque vous voulez le serveur de développement Vite
L’interface de contrôle est composée de fichiers statiques ; la cible WebSocket est configurable et peut être
différente de l’origine HTTP. C’est pratique lorsque vous souhaitez le serveur de développement Vite
en local mais que le Gateway s’exécute ailleurs.
1. Démarrez le serveur de développement UI : `pnpm ui:dev`
1. Démarrez le serveur de développement de l’interface : `pnpm ui:dev`
2. Ouvrez une URL comme :
```text
@ -381,19 +384,19 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
Remarques :
- `gatewayUrl` est stocké dans localStorage après le chargement et retiré de l’URL.
- `token` doit être passé via le fragment d’URL (`#token=...`) chaque fois que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites via journaux de requête et Referer. Les anciens paramètres de requête `?token=` sont encore importés une fois pour compatibilité, mais seulement comme repli, et sont supprimés immédiatement après le bootstrap.
- `gatewayUrl` est stocké dans localStorage après le chargement et supprimé de l’URL.
- `token` doit être transmis via le fragment d’URL (`#token=...`) autant que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites dans les journaux de requêtes et via Referer. Les anciens paramètres de requête `?token=` sont encore importés une fois pour compatibilité, mais seulement en repli, et sont supprimés immédiatement après l’initialisation.
- `password` est conservé uniquement en mémoire.
- Lorsque `gatewayUrl` est défini, l’UI ne retombe pas sur des identifiants issus de la configuration ou de l’environnement.
Fournissez explicitement `token` (ou `password`). L’absence d’identifiants explicites est une erreur.
- Lorsque `gatewayUrl` est défini, l’interface ne revient pas aux identifiants de configuration ou d’environnement.
Fournissez `token` (ou `password`) explicitement. L’absence d’identifiants explicites est une erreur.
- Utilisez `wss://` lorsque le Gateway est derrière TLS (Tailscale Serve, proxy HTTPS, etc.).
- `gatewayUrl` n’est accepté que dans une fenêtre de premier niveau (pas intégrée) afin d’empêcher le clickjacking.
- Les déploiements d’interface de contrôle hors loopback doivent définir `gateway.controlUi.allowedOrigins`
explicitement (origines complètes). Cela inclut les configurations de développement distantes.
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]` sauf pour des tests locaux très contrôlés.
Cela signifie autoriser n’importe quelle origine de navigateur, pas « correspondre à l’hôte que j’utilise ».
- `gatewayUrl` n’est accepté que dans une fenêtre de premier niveau (pas intégrée) afin d’empêcher le détournement de clic.
- Les déploiements d’interface de contrôle hors local loopback doivent définir explicitement `gateway.controlUi.allowedOrigins`
(origines complètes). Cela inclut les configurations de développement distantes.
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]` sauf pour des tests locaux étroitement contrôlés.
Cela signifie autoriser toute origine de navigateur, et non « correspondre à l’hôte que j’utilise ».
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` active
le mode de repli d’origine par en-tête Host, mais c’est un mode de sécurité dangereux.
le mode de repli sur l’origine de l’en-tête Host, mais c’est un mode de sécurité dangereux.
Exemple :
@ -409,9 +412,9 @@ Exemple :
Détails de configuration de l’accès distant : [Accès distant](/fr/gateway/remote).
## Associé
## Liens associés
- [Dashboard](/fr/web/dashboard) — tableau de bord du gateway
- [WebChat](/fr/web/webchat) — interface de chat basée sur le navigateur
- [TUI](/fr/web/tui) — interface utilisateur terminal
- [TUI](/fr/web/tui) — interface utilisateur en terminal
- [Health Checks](/fr/gateway/health) — surveillance de l’état du gateway