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-20 07:14:08 +00:00
parent 5753fbccee
commit ab75b1d6c6
11 changed files with 3402 additions and 3365 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

454
docs/fr/channels/telegram.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Travailler sur des fonctionnalités Telegram ou des webhooks
summary: Statut de la prise en charge du bot Telegram, capacités et configuration
- Travail sur les fonctionnalités Telegram ou les Webhooks
summary: Statut de prise en charge du bot Telegram, capacités et configuration
title: Telegram
x-i18n:
generated_at: "2026-04-05T12:38:30Z"
generated_at: "2026-04-20T07:05:24Z"
model: gpt-5.4
provider: openai
source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e
source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477
source_path: channels/telegram.md
workflow: 15
---
# Telegram (Bot API)
# Telegram (API Bot)
Statut : prêt pour la production pour les DM de bot + les groupes via grammY. Le long polling est le mode par défaut ; le mode webhook est facultatif.
Statut : prêt pour la production pour les DM de bot + groupes via grammY. Le long polling est le mode par défaut ; le mode Webhook est facultatif.
<CardGroup cols={3}>
<Card title="Appairage" icon="link" href="/channels/pairing">
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
La politique DM par défaut pour Telegram est l’appairage.
</Card>
<Card title="Dépannage des canaux" icon="wrench" href="/channels/troubleshooting">
<Card title="Dépannage du canal" icon="wrench" href="/fr/channels/troubleshooting">
Diagnostics inter-canaux et guides de réparation.
</Card>
<Card title="Configuration de Gateway" icon="settings" href="/gateway/configuration">
Modèles de configuration complets des canaux et exemples.
<Card title="Configuration de Gateway" icon="settings" href="/fr/gateway/configuration">
Modèles complets de configuration des canaux et exemples.
</Card>
</CardGroup>
@ -32,7 +32,7 @@ Statut : prêt pour la production pour les DM de bot + les groupes via grammY. L
<Steps>
<Step title="Créer le jeton du bot dans BotFather">
Ouvrez Telegram et discutez avec **@BotFather** (vérifiez que le handle est exactement `@BotFather`).
Ouvrez Telegram et discutez avec **@BotFather** (vérifiez que le pseudonyme est exactement `@BotFather`).
Exécutez `/newbot`, suivez les invites et enregistrez le jeton.
@ -53,12 +53,12 @@ Statut : prêt pour la production pour les DM de bot + les groupes via grammY. L
}
```
Variable d’environnement de repli : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement).
Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans la config/l’environnement, puis démarrez gateway.
Repli via variable d’environnement : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement).
Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans la config/l’environnement, puis démarrez Gateway.
</Step>
<Step title="Démarrer gateway et approuver le premier DM">
<Step title="Démarrer Gateway et approuver le premier DM">
```bash
openclaw gateway
@ -71,30 +71,30 @@ openclaw pairing approve telegram <CODE>
</Step>
<Step title="Ajouter le bot à un groupe">
Ajoutez le bot à votre groupe, puis définissez `channels.telegram.groups` et `groupPolicy` selon votre modèle d’accès.
Ajoutez le bot à votre groupe, puis définissez `channels.telegram.groups` et `groupPolicy` pour qu’ils correspondent à votre modèle d’accès.
</Step>
</Steps>
<Note>
L’ordre de résolution du jeton tient compte du compte. En pratique, les valeurs de config priment sur la variable d’environnement de repli, et `TELEGRAM_BOT_TOKEN` ne s’applique qu’au compte par défaut.
L’ordre de résolution du jeton tient compte du compte. En pratique, les valeurs de config priment sur le repli via l’environnement, et `TELEGRAM_BOT_TOKEN` s’applique uniquement au compte par défaut.
</Note>
## Paramètres côté Telegram
<AccordionGroup>
<Accordion title="Mode confidentialité et visibilité des groupes">
Les bots Telegram utilisent par défaut le **mode confidentialité**, ce qui limite les messages de groupe qu’ils reçoivent.
<Accordion title="Mode confidentialité et visibilité dans les groupes">
Les bots Telegram sont en **mode confidentialité** par défaut, ce qui limite les messages de groupe qu’ils reçoivent.
Si le bot doit voir tous les messages du groupe, soit :
Si le bot doit voir tous les messages du groupe, vous pouvez soit :
- désactivez le mode confidentialité via `/setprivacy`, ou
- faites du bot un administrateur du groupe.
- désactiver le mode confidentialité via `/setprivacy`, ou
- faire du bot un administrateur du groupe.
Lorsque vous modifiez le mode confidentialité, supprimez puis réajoutez le bot dans chaque groupe afin que Telegram applique le changement.
Lors d’un changement du mode confidentialité, retirez puis rajoutez le bot dans chaque groupe afin que Telegram applique le changement.
</Accordion>
<Accordion title="Autorisations de groupe">
<Accordion title="Permissions du groupe">
Le statut d’administrateur est contrôlé dans les paramètres du groupe Telegram.
Les bots administrateurs reçoivent tous les messages du groupe, ce qui est utile pour un comportement de groupe toujours actif.
@ -113,7 +113,7 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu
<Tabs>
<Tab title="Politique DM">
`channels.telegram.dmPolicy` contrôle l’accès aux messages directs :
`channels.telegram.dmPolicy` contrôle l’accès par message direct :
- `pairing` (par défaut)
- `allowlist` (nécessite au moins un ID d’expéditeur dans `allowFrom`)
@ -122,14 +122,14 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu
`channels.telegram.allowFrom` accepte des ID utilisateur Telegram numériques. Les préfixes `telegram:` / `tg:` sont acceptés et normalisés.
`dmPolicy: "allowlist"` avec un `allowFrom` vide bloque tous les DM et est rejeté par la validation de configuration.
L’onboarding accepte une entrée `@username` et la résout en ID numériques.
La configuration demande uniquement des ID utilisateur numériques.
Si vous avez effectué une mise à niveau et que votre configuration contient des entrées de liste d’autorisation `@username`, exécutez `openclaw doctor --fix` pour les résoudre (au mieux ; nécessite un jeton de bot Telegram).
Si vous vous appuyiez auparavant sur les fichiers de liste d’autorisation du magasin d’appairage, `openclaw doctor --fix` peut récupérer des entrées dans `channels.telegram.allowFrom` dans les flux de liste d’autorisation (par exemple lorsque `dmPolicy: "allowlist"` n’a pas encore d’ID explicites).
Si vous vous appuyiez auparavant sur des fichiers de liste d’autorisation du magasin d’appairage, `openclaw doctor --fix` peut récupérer les entrées dans `channels.telegram.allowFrom` dans les flux allowlist (par exemple lorsque `dmPolicy: "allowlist"` n’a encore aucun ID explicite).
Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID numériques explicites dans `allowFrom` afin de conserver une politique d’accès durable dans la configuration (au lieu de dépendre d’approbations d’appairage précédentes).
Confusion courante : l’approbation d’un appairage DM ne signifie pas « cet expéditeur est autorisé partout ».
L’appairage n’accorde qu’un accès DM. L’autorisation des expéditeurs dans les groupes provient toujours de listes d’autorisation explicites dans la configuration.
Confusion fréquente : l’approbation de l’appairage DM ne signifie pas « cet expéditeur est autorisé partout ».
L’appairage accorde un accès DM uniquement. L’autorisation des expéditeurs dans les groupes provient toujours de listes d’autorisation explicites dans la configuration.
Si vous voulez « je suis autorisé une fois et les DM ainsi que les commandes de groupe fonctionnent », placez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom`.
### Trouver votre ID utilisateur Telegram
@ -140,7 +140,7 @@ L’ordre de résolution du jeton tient compte du compte. En pratique, les valeu
2. Exécutez `openclaw logs --follow`.
3. Lisez `from.id`.
Méthode officielle Bot API :
Méthode officielle de l’API Bot :
```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
@ -154,7 +154,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Deux contrôles s’appliquent ensemble :
1. **Quels groupes sont autorisés** (`channels.telegram.groups`)
- pas de configuration `groups` :
- aucune configuration `groups` :
- avec `groupPolicy: "open"` : n’importe quel groupe peut passer les vérifications d’ID de groupe
- avec `groupPolicy: "allowlist"` (par défaut) : les groupes sont bloqués jusqu’à ce que vous ajoutiez des entrées `groups` (ou `"*"`)
- `groups` configuré : agit comme une liste d’autorisation (ID explicites ou `"*"`)
@ -164,15 +164,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `allowlist` (par défaut)
- `disabled`
`groupAllowFrom` est utilisé pour filtrer les expéditeurs de groupe. S’il n’est pas défini, Telegram retombe sur `allowFrom`.
`groupAllowFrom` est utilisé pour filtrer les expéditeurs dans les groupes. S’il n’est pas défini, Telegram se rabat sur `allowFrom`.
Les entrées `groupAllowFrom` doivent être des ID utilisateur Telegram numériques (les préfixes `telegram:` / `tg:` sont normalisés).
Ne placez pas d’ID de chat de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de chat négatifs doivent être placés sous `channels.telegram.groups`.
Les entrées non numériques sont ignorées pour l’autorisation de l’expéditeur.
Frontière de sécurité (`2026.2.25+`) : l’authentification des expéditeurs de groupe **n’hérite pas** des approbations du magasin d’appairage DM.
Ne mettez pas d’ID de chat de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de chat négatifs doivent être placés sous `channels.telegram.groups`.
Les entrées non numériques sont ignorées pour l’autorisation des expéditeurs.
Limite de sécurité (`2026.2.25+`) : l’autorisation des expéditeurs dans les groupes n’hérite **pas** des approbations du magasin d’appairage DM.
L’appairage reste réservé aux DM. Pour les groupes, définissez `groupAllowFrom` ou `allowFrom` par groupe/par sujet.
Si `groupAllowFrom` n’est pas défini, Telegram retombe sur `allowFrom` de la configuration, et non sur le magasin d’appairage.
Si `groupAllowFrom` n’est pas défini, Telegram se rabat sur `allowFrom` de la configuration, et non sur le magasin d’appairage.
Modèle pratique pour les bots à propriétaire unique : définissez votre ID utilisateur dans `channels.telegram.allowFrom`, laissez `groupAllowFrom` non défini et autorisez les groupes cibles sous `channels.telegram.groups`.
Note du runtime : si `channels.telegram` est totalement absent, le runtime utilise par défaut `groupPolicy="allowlist"` en mode fail-closed, sauf si `channels.defaults.groupPolicy` est explicitement défini.
Note d’exécution : si `channels.telegram` est complètement absent, les valeurs d’exécution se replient par défaut sur `groupPolicy="allowlist"` en mode fermé, sauf si `channels.defaults.groupPolicy` est explicitement défini.
Exemple : autoriser n’importe quel membre dans un groupe spécifique :
@ -209,17 +209,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```
<Warning>
Erreur courante : `groupAllowFrom` n’est pas une liste d’autorisation de groupes Telegram.
Erreur fréquente : `groupAllowFrom` n’est pas une liste d’autorisation de groupes Telegram.
- Placez les ID négatifs de groupe ou de supergroupe Telegram comme `-1001234567890` sous `channels.telegram.groups`.
- Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes à l’intérieur d’un groupe autorisé pouvant déclencher le bot.
- Placez les ID négatifs de groupes ou de supergroupes Telegram comme `-1001234567890` sous `channels.telegram.groups`.
- Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter quelles personnes dans un groupe autorisé peuvent déclencher le bot.
- Utilisez `groupAllowFrom: ["*"]` uniquement lorsque vous voulez que n’importe quel membre d’un groupe autorisé puisse parler au bot.
</Warning>
</Tab>
<Tab title="Comportement des mentions">
Les réponses de groupe exigent une mention par défaut.
Les réponses dans les groupes nécessitent une mention par défaut.
La mention peut provenir de :
@ -228,7 +228,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
Commandes de bascule au niveau de la session :
Options de commande au niveau de la session :
- `/activation always`
- `/activation mention`
@ -251,27 +251,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Obtenir l’ID du chat de groupe :
- transférez un message de groupe à `@userinfobot` / `@getidsbot`
- ou lisez `chat.id` depuis `openclaw logs --follow`
- ou inspectez `getUpdates` de Bot API
- transférez un message du groupe à `@userinfobot` / `@getidsbot`
- ou lisez `chat.id` dans `openclaw logs --follow`
- ou inspectez `getUpdates` de l’API Bot
</Tab>
</Tabs>
## Comportement du runtime
## Comportement à l’exécution
- Telegram est géré par le processus gateway.
- Le routage est déterministe : les réponses entrantes Telegram reviennent vers Telegram (le modèle ne choisit pas les canaux).
- Les messages entrants sont normalisés dans l’enveloppe de canal partagée avec métadonnées de réponse et espaces réservés aux médias.
- Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent `:topic:<threadId>` pour maintenir l’isolation des sujets.
- Les messages DM peuvent transporter `message_thread_id` ; OpenClaw les route avec des clés de session conscientes des fils et préserve l’ID du fil pour les réponses.
- Le long polling utilise le runner grammY avec séquencement par chat/par fil. La concurrence globale du runner sink utilise `agents.defaults.maxConcurrent`.
- Telegram Bot API ne prend pas en charge les accusés de lecture (`sendReadReceipts` ne s’applique pas).
- Telegram est géré par le processus Gateway.
- Le routage est déterministe : les réponses entrantes depuis Telegram repartent vers Telegram (le modèle ne choisit pas les canaux).
- Les messages entrants sont normalisés dans l’enveloppe de canal partagée avec métadonnées de réponse et espaces réservés pour les médias.
- Les sessions de groupe sont isolées par ID de groupe. Les sujets de forum ajoutent `:topic:<threadId>` pour garder les sujets isolés.
- Les messages DM peuvent transporter `message_thread_id` ; OpenClaw les route avec des clés de session tenant compte des fils et préserve l’ID de fil pour les réponses.
- Le long polling utilise grammY runner avec séquencement par chat/par fil. La concurrence globale du sink du runner utilise `agents.defaults.maxConcurrent`.
- L’API Bot Telegram ne prend pas en charge les accusés de lecture (`sendReadReceipts` ne s’applique pas).
## Référence des fonctionnalités
<AccordionGroup>
<Accordion title="Aperçu de flux en direct (modifications de message)">
<Accordion title="Aperçu du flux en direct (modifications de message)">
OpenClaw peut diffuser des réponses partielles en temps réel :
- chats directs : message d’aperçu + `editMessageText`
@ -280,32 +280,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Exigence :
- `channels.telegram.streaming` vaut `off | partial | block | progress` (par défaut : `partial`)
- `progress` correspond à `partial` sur Telegram (compatibilité avec la dénomination inter-canaux)
- les anciennes valeurs booléennes de `channels.telegram.streamMode` et `streaming` sont mappées automatiquement
- `progress` est mappé vers `partial` sur Telegram (compatibilité avec la dénomination inter-canaux)
- les anciennes valeurs booléennes `channels.telegram.streamMode` et `streaming` sont automatiquement mappées
Pour les réponses texte uniquement :
- DM : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place (pas de second message)
- groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place (pas de second message)
Pour les réponses complexes (par exemple les charges utiles média), OpenClaw retombe sur la livraison finale normale puis nettoie le message d’aperçu.
Pour les réponses complexes (par exemple les charges utiles média), OpenClaw se rabat sur une livraison finale normale puis nettoie le message d’aperçu.
Le flux d’aperçu est distinct du flux par blocs. Lorsque le flux par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter un double flux.
Si le transport de brouillon natif n’est pas disponible/rejeté, OpenClaw retombe automatiquement sur `sendMessage` + `editMessageText`.
Si le transport de brouillon natif est indisponible/rejeté, OpenClaw se rabat automatiquement sur `sendMessage` + `editMessageText`.
Flux de raisonnement réservé à Telegram :
Flux de raisonnement propre à Telegram :
- `/reasoning stream` envoie le raisonnement vers l’aperçu en direct pendant la génération
- la réponse finale est envoyée sans le texte de raisonnement
</Accordion>
<Accordion title="Formatage et repli HTML">
Le texte sortant utilise le `parse_mode: "HTML"` de Telegram.
<Accordion title="Mise en forme et repli HTML">
Le texte sortant utilise Telegram `parse_mode: "HTML"`.
- Le texte de type Markdown est rendu en HTML sûr pour Telegram.
- Le HTML brut du modèle est échappé pour réduire les échecs d’analyse de Telegram.
- Le HTML brut du modèle est échappé pour réduire les échecs d’analyse Telegram.
- Si Telegram rejette le HTML analysé, OpenClaw réessaie en texte brut.
Les aperçus de liens sont activés par défaut et peuvent être désactivés avec `channels.telegram.linkPreview: false`.
@ -319,15 +319,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `commands.native: "auto"` active les commandes natives pour Telegram
Ajouter des entrées de menu de commandes personnalisées :
Ajouter des entrées personnalisées au menu de commandes :
```json5
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Git backup" },
{ command: "generate", description: "Create an image" },
{ command: "backup", description: "Sauvegarde Git" },
{ command: "generate", description: "Créer une image" },
],
},
},
@ -341,40 +341,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- les commandes personnalisées ne peuvent pas remplacer les commandes natives
- les conflits/doublons sont ignorés et journalisés
Notes :
Remarques :
- les commandes personnalisées sont uniquement des entrées de menu ; elles n’implémentent pas automatiquement un comportement
- les commandes de plugin/Skills peuvent toujours fonctionner lorsqu’elles sont saisies, même si elles ne sont pas affichées dans le menu Telegram
- les commandes personnalisées sont uniquement des entrées de menu ; elles n’implémentent pas automatiquement de comportement
- les commandes de Plugin/Skills peuvent toujours fonctionner lorsqu’elles sont saisies même si elles ne sont pas affichées dans le menu Telegram
Si les commandes natives sont désactivées, les commandes intégrées sont supprimées. Les commandes personnalisées/de plugin peuvent toujours être enregistrées si elles sont configurées.
Si les commandes natives sont désactivées, les commandes intégrées sont supprimées. Les commandes personnalisées/de Plugin peuvent tout de même s’enregistrer si elles sont configurées.
Échecs de configuration courants :
Échecs de configuration fréquents :
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram déborde toujours après réduction ; réduisez les commandes personnalisées/de plugin/de Skills ou désactivez `channels.telegram.commands.native`.
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram débordait encore après réduction ; réduisez les commandes de Plugin/Skills/personnalisées ou désactivez `channels.telegram.commands.native`.
- `setMyCommands failed` avec des erreurs réseau/fetch signifie généralement que le DNS/HTTPS sortant vers `api.telegram.org` est bloqué.
### Commandes d’appairage d’appareil (plugin `device-pair`)
### Commandes d’appairage d’appareil (Plugin `device-pair`)
Lorsque le plugin `device-pair` est installé :
Lorsque le Plugin `device-pair` est installé :
1. `/pair` génère un code de configuration
2. collez le code dans l’application iOS
3. `/pair pending` liste les demandes en attente (y compris rôle/portées)
2. collez le code dans l’app iOS
3. `/pair pending` liste les demandes en attente (y compris le rôle/les scopes)
4. approuvez la demande :
- `/pair approve <requestId>` pour une approbation explicite
- `/pair approve` lorsqu’il n’y a qu’une seule demande en attente
- `/pair approve latest` pour la plus récente
Le code de configuration transporte un jeton bootstrap de courte durée. Le transfert bootstrap intégré conserve le jeton de nœud principal à `scopes: []` ; tout jeton operator transmis reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de portée bootstrap sont préfixées par rôle, de sorte que cette liste d’autorisation operator ne satisfait que les demandes operator ; les rôles non-operator ont toujours besoin de portées sous leur propre préfixe de rôle.
Le code de configuration transporte un jeton d’amorçage de courte durée. Le transfert d’amorçage intégré conserve le jeton du Node principal avec `scopes: []` ; tout jeton opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de scope d’amorçage sont préfixées par le rôle ; cette liste d’autorisation opérateur ne satisfait donc que les demandes opérateur ; les rôles non opérateur ont toujours besoin de scopes sous leur propre préfixe de rôle.
Si un appareil réessaie avec des détails d’authentification modifiés (par exemple rôle/portées/clé publique), la demande en attente précédente est remplacée et la nouvelle demande utilise un autre `requestId`. Réexécutez `/pair pending` avant d’approuver.
Si un appareil réessaie avec des détails d’authentification modifiés (par exemple rôle/scopes/clé publique), la demande en attente précédente est remplacée et la nouvelle demande utilise un `requestId` différent. Relancez `/pair pending` avant d’approuver.
Plus de détails : [Appairage](/channels/pairing#pair-via-telegram-recommended-for-ios).
Plus de détails : [Appairage](/fr/channels/pairing#pair-via-telegram-recommended-for-ios).
</Accordion>
<Accordion title="Boutons intégrés">
Configurez la portée du clavier intégré :
<Accordion title="Boutons en ligne">
Configurez la portée du clavier en ligne :
```json5
{
@ -423,13 +423,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
action: "send",
channel: "telegram",
to: "123456789",
message: "Choose an option:",
message: "Choisissez une option :",
buttons: [
[
{ text: "Yes", callback_data: "yes" },
{ text: "No", callback_data: "no" },
{ text: "Oui", callback_data: "yes" },
{ text: "Non", callback_data: "no" },
],
[{ text: "Cancel", callback_data: "cancel" }],
[{ text: "Annuler", callback_data: "cancel" }],
],
}
```
@ -448,24 +448,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, `iconColor`, `iconCustomEmojiId` facultatifs)
Les actions de message de canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Les actions de message du canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Contrôles de restriction :
Contrôles de limitation :
- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (par défaut : désactivé)
- `channels.telegram.actions.sticker` (désactivé par défaut)
Remarque : `edit` et `topic-create` sont actuellement activés par défaut et n’ont pas de bascules `channels.telegram.actions.*` séparées.
Les envois runtime utilisent l’instantané actif de la configuration/des secrets (démarrage/rechargement), donc les chemins d’action n’effectuent pas de nouvelle résolution ad hoc de SecretRef à chaque envoi.
Les envois à l’exécution utilisent l’instantané actif de config/secrets (démarrage/rechargement), donc les chemins d’action n’effectuent pas de rerésolution ad hoc de `SecretRef` à chaque envoi.
Sémantique de suppression de réaction : [/tools/reactions](/tools/reactions)
Sémantique de suppression de réaction : [/tools/reactions](/fr/tools/reactions)
</Accordion>
<Accordion title="Balises de fil de réponse">
Telegram prend en charge des balises explicites de fil de réponse dans la sortie générée :
Telegram prend en charge les balises explicites de fil de réponse dans la sortie générée :
- `[[reply_to_current]]` répond au message déclencheur
- `[[reply_to:<id>]]` répond à un ID de message Telegram spécifique
@ -476,7 +476,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
Remarque : `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` sont toujours honorées.
Remarque : `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` sont toujours respectées.
</Accordion>
@ -484,7 +484,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Supergroupes de forum :
- les clés de session de sujet ajoutent `:topic:<threadId>`
- les réponses et les indicateurs de saisie ciblent le fil du sujet
- les réponses et indicateurs de saisie ciblent le fil du sujet
- chemin de configuration du sujet :
`channels.telegram.groups.<chatId>.topics.<threadId>`
@ -494,9 +494,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- les actions de saisie incluent toujours `message_thread_id`
Héritage des sujets : les entrées de sujet héritent des paramètres du groupe sauf remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` est réservé au sujet et n’hérite pas des valeurs par défaut du groupe.
`agentId` est propre au sujet et n’hérite pas des valeurs par défaut du groupe.
**Routage d’agent par sujet** : chaque sujet peut être routé vers un agent différent en définissant `agentId` dans la configuration du sujet. Cela donne à chaque sujet son propre espace de travail, sa propre mémoire et sa propre session. Exemple :
**Routage d’agent par sujet** : chaque sujet peut router vers un agent différent en définissant `agentId` dans la configuration du sujet. Cela donne à chaque sujet son propre espace de travail, sa propre mémoire et sa propre session. Exemple :
```json5
{
@ -518,7 +518,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Chaque sujet a alors sa propre clé de session : `agent:zu:telegram:group:-1001234567890:topic:3`
**Liaison ACP persistante par sujet** : les sujets de forum peuvent épingler des sessions de harnais ACP via des liaisons ACP typées de niveau supérieur :
**Liaison persistante de sujet ACP** : les sujets de forum peuvent épingler des sessions de harness ACP via des liaisons ACP typées de niveau supérieur :
- `bindings[]` avec `type: "acp"` et `match.channel: "telegram"`
@ -571,21 +571,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Cela est actuellement limité aux sujets de forum dans les groupes et supergroupes.
**Lancement ACP lié à un fil depuis le chat** :
**Lancement ACP lié au fil depuis le chat** :
- `/acp spawn <agent> --thread here|auto` peut lier le sujet Telegram actuel à une nouvelle session ACP.
- Les messages suivants dans le sujet sont routés directement vers la session ACP liée (pas de `/acp steer` requis).
- OpenClaw épingle le message de confirmation du lancement dans le sujet après une liaison réussie.
- Les messages suivants du sujet sont routés directement vers la session ACP liée (pas de `/acp steer` requis).
- OpenClaw épingle le message de confirmation de lancement dans le sujet après une liaison réussie.
- Nécessite `channels.telegram.threadBindings.spawnAcpSessions=true`.
Le contexte de modèle inclut :
Le contexte de template inclut :
- `MessageThreadId`
- `IsForum`
Comportement des fils DM :
Comportement des fils en DM :
- les chats privés avec `message_thread_id` conservent le routage DM mais utilisent des clés de session/cibles de réponse conscientes des fils.
- les chats privés avec `message_thread_id` conservent le routage DM mais utilisent des clés de session et des cibles de réponse tenant compte des fils.
</Accordion>
@ -595,7 +595,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Telegram distingue les notes vocales des fichiers audio.
- par défaut : comportement de fichier audio
- balise `[[audio_as_voice]]` dans la réponse de l’agent pour forcer l’envoi en note vocale
- balise `[[audio_as_voice]]` dans la réponse de l’agent pour forcer l’envoi comme note vocale
Exemple d’action de message :
@ -635,7 +635,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- TGS animé : ignoré
- WEBM vidéo : ignoré
Champs de contexte du sticker :
Champs de contexte de sticker :
- `Sticker.emoji`
- `Sticker.setName`
@ -643,13 +643,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `Sticker.fileUniqueId`
- `Sticker.cachedDescription`
Fichier de cache de stickers :
Fichier de cache des stickers :
- `~/.openclaw/telegram/sticker-cache.json`
Les stickers sont décrits une seule fois (lorsque possible) puis mis en cache afin de réduire les appels de vision répétés.
Les stickers sont décrits une fois (quand c’est possible) puis mis en cache pour réduire les appels de vision répétés.
Activer les actions de stickers :
Activer les actions de sticker :
```json5
{
@ -674,13 +674,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Rechercher dans les stickers mis en cache :
Rechercher dans les stickers en cache :
```json5
{
action: "sticker-search",
channel: "telegram",
query: "cat waving",
query: "chat qui fait signe",
limit: 5,
}
```
@ -688,30 +688,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Notifications de réaction">
Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (séparées des charges utiles des messages).
Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (séparées des payloads de message).
Lorsqu’elles sont activées, OpenClaw met en file d’attente des événements système tels que :
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
- `Réaction Telegram ajoutée : 👍 par Alice (@alice) sur le msg 42`
Configuration :
- `channels.telegram.reactionNotifications`: `off | own | all` (par défaut : `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (par défaut : `minimal`)
Notes :
Remarques :
- `own` signifie uniquement les réactions des utilisateurs aux messages envoyés par le bot (au mieux via le cache des messages envoyés).
- `own` signifie uniquement les réactions utilisateur sur les messages envoyés par le bot (au mieux via le cache des messages envoyés).
- Les événements de réaction respectent toujours les contrôles d’accès Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`) ; les expéditeurs non autorisés sont ignorés.
- Telegram ne fournit pas d’ID de fil dans les mises à jour de réaction.
- Telegram ne fournit pas les ID de fil dans les mises à jour de réaction.
- les groupes non forum sont routés vers la session de chat de groupe
- les groupes forum sont routés vers la session du sujet général du groupe (`:topic:1`), et non vers le sujet d’origine exact
`allowed_updates` pour le polling/webhook inclut automatiquement `message_reaction`.
`allowed_updates` pour polling/Webhook inclut automatiquement `message_reaction`.
</Accordion>
<Accordion title="Réactions d’accusé de réception">
<Accordion title="Réactions d’accusé">
`ackReaction` envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant.
Ordre de résolution :
@ -719,22 +719,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
- repli vers l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
Notes :
Remarques :
- Telegram attend un emoji unicode (par exemple "👀").
- Utilisez `""` pour désactiver la réaction pour un canal ou un compte.
</Accordion>
<Accordion title="Écritures de configuration depuis les événements et commandes Telegram">
<Accordion title="Écritures de config depuis les événements et commandes Telegram">
Les écritures de configuration du canal sont activées par défaut (`configWrites !== false`).
Les écritures déclenchées par Telegram incluent :
- les événements de migration de groupe (`migrate_to_chat_id`) pour mettre à jour `channels.telegram.groups`
- `/config set` et `/config unset` (nécessite l’activation de la commande)
- `/config set` et `/config unset` (nécessite l’activation des commandes)
Désactiver :
@ -750,36 +750,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Long polling vs webhook">
<Accordion title="Long polling vs Webhook">
Par défaut : long polling.
Mode webhook :
Mode Webhook :
- définissez `channels.telegram.webhookUrl`
- définissez `channels.telegram.webhookSecret` (obligatoire lorsque l’URL webhook est définie)
- définissez `channels.telegram.webhookSecret` (obligatoire lorsque l’URL Webhook est définie)
- `channels.telegram.webhookPath` facultatif (par défaut `/telegram-webhook`)
- `channels.telegram.webhookHost` facultatif (par défaut `127.0.0.1`)
- `channels.telegram.webhookPort` facultatif (par défaut `8787`)
L’écouteur local par défaut pour le mode webhook est lié à `127.0.0.1:8787`.
L’écouteur local par défaut pour le mode Webhook se lie à `127.0.0.1:8787`.
Si votre point de terminaison public diffère, placez un proxy inverse en amont et faites pointer `webhookUrl` vers l’URL publique.
Si votre point de terminaison public est différent, placez un proxy inverse devant et pointez `webhookUrl` vers l’URL publique.
Définissez `webhookHost` (par exemple `0.0.0.0`) lorsque vous avez intentionnellement besoin d’une entrée externe.
</Accordion>
<Accordion title="Limites, nouvelles tentatives et cibles CLI">
- `channels.telegram.textChunkLimit` vaut 4000 par défaut.
- `channels.telegram.chunkMode="newline"` privilégie les frontières de paragraphe (lignes vides) avant la segmentation par longueur.
- `channels.telegram.mediaMaxMb` (par défaut 100) limite la taille des médias Telegram entrants et sortants.
- `channels.telegram.timeoutSeconds` remplace le délai d’expiration du client Telegram API (si non défini, la valeur par défaut de grammY s’applique).
- l’historique du contexte de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (par défaut 50) ; `0` le désactive.
- la valeur par défaut de `channels.telegram.textChunkLimit` est 4000.
- `channels.telegram.chunkMode="newline"` privilégie les limites de paragraphe (lignes vides) avant le découpage par longueur.
- `channels.telegram.mediaMaxMb` (100 par défaut) limite la taille des médias Telegram entrants et sortants.
- `channels.telegram.timeoutSeconds` remplace le délai d’expiration du client API Telegram (si non défini, la valeur par défaut de grammY s’applique).
- l’historique du contexte de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (50 par défaut) ; `0` désactive.
- le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel que reçu.
- les listes d’autorisation Telegram servent principalement à contrôler qui peut déclencher l’agent, et non une frontière complète de caviardage du contexte supplémentaire.
- les listes d’autorisation Telegram contrôlent principalement qui peut déclencher l’agent, et non une limite complète de masquage du contexte supplémentaire.
- contrôles d’historique DM :
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- la configuration `channels.telegram.retry` s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs API sortantes récupérables.
- la configuration `channels.telegram.retry` s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs récupérables de l’API sortante.
La cible d’envoi CLI peut être un ID de chat numérique ou un nom d’utilisateur :
@ -798,19 +798,19 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-duration-seconds 300 --poll-public
```
Drapeaux de sondage réservés à Telegram :
Indicateurs de sondage propres à Telegram :
- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` pour les sujets de forum (ou utilisez une cible `:topic:`)
L’envoi Telegram prend également en charge :
L’envoi Telegram prend aussi en charge :
- `--buttons` pour les claviers intégrés lorsque `channels.telegram.capabilities.inlineButtons` l’autorise
- `--force-document` pour envoyer des images et GIF sortants comme documents au lieu de photos compressées ou de médias animés
- `--buttons` pour les claviers en ligne lorsque `channels.telegram.capabilities.inlineButtons` l’autorise
- `--force-document` pour envoyer les images et GIF sortants comme documents au lieu d’uploads photo compressés ou média animé
Restriction des actions :
Limitation des actions :
- `channels.telegram.actions.sendMessage=false` désactive les messages Telegram sortants, y compris les sondages
- `channels.telegram.actions.poll=false` désactive la création de sondages Telegram tout en laissant les envois classiques activés
@ -823,40 +823,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
Chemin de configuration :
- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers` (facultatif ; retombe sur les ID de propriétaire numériques déduits de `allowFrom` et de `defaultTo` direct lorsque possible)
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, par défaut : `dm`)
- `channels.telegram.execApprovals.approvers` (facultatif ; se rabat sur les ID propriétaires numériques déduits de `allowFrom` et du `defaultTo` direct lorsque c’est possible)
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, `dm` par défaut)
- `agentFilter`, `sessionFilter`
Les approbateurs doivent être des ID utilisateur Telegram numériques. Telegram active automatiquement les approbations exec natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un approbateur peut être résolu, soit depuis `execApprovals.approvers`, soit depuis la configuration numérique du propriétaire du compte (`allowFrom` et `defaultTo` de message direct). Définissez `enabled: false` pour désactiver explicitement Telegram comme client d’approbation natif. Les demandes d’approbation retombent sinon sur d’autres routes d’approbation configurées ou sur la politique de repli des approbations exec.
Les approbateurs doivent être des ID utilisateur Telegram numériques. Telegram active automatiquement les approbations exec natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un approbateur peut être résolu, soit depuis `execApprovals.approvers`, soit depuis la configuration propriétaire numérique du compte (`allowFrom` et `defaultTo` en message direct). Définissez `enabled: false` pour désactiver explicitement Telegram comme client d’approbation natif. Les demandes d’approbation se rabattent sinon sur les autres routes d’approbation configurées ou sur la politique de repli des approbations exec.
Telegram affiche également les boutons d’approbation partagés utilisés par les autres canaux de chat. L’adaptateur Telegram natif ajoute principalement le routage DM des approbateurs, la diffusion vers le canal/sujet et les indications de saisie avant livraison.
Lorsque ces boutons sont présents, ils constituent l’UX principale d’approbation ; OpenClaw
Telegram affiche aussi les boutons d’approbation partagés utilisés par les autres canaux de chat. L’adaptateur Telegram natif ajoute principalement le routage DM des approbateurs, la diffusion vers le canal/sujet et les indications de saisie avant livraison.
Lorsque ces boutons sont présents, ils constituent l’UX d’approbation principale ; OpenClaw
ne doit inclure une commande manuelle `/approve` que lorsque le résultat de l’outil indique
que les approbations de chat ne sont pas disponibles ou que l’approbation manuelle est la seule voie.
que les approbations par chat ne sont pas disponibles ou que l’approbation manuelle est la seule voie.
Règles de livraison :
- `target: "dm"` envoie les invites d’approbation uniquement aux DM des approbateurs résolus
- `target: "channel"` renvoie l’invite au chat/sujet Telegram d’origine
- `target: "channel"` renvoie l’invite vers le chat/sujet Telegram d’origine
- `target: "both"` envoie aux DM des approbateurs et au chat/sujet d’origine
Seuls les approbateurs résolus peuvent approuver ou refuser. Les non-approbateurs ne peuvent pas utiliser `/approve` ni les boutons d’approbation Telegram.
Comportement de résolution des approbations :
- les ID préfixés par `plugin:` sont toujours résolus via les approbations de plugin.
- les ID préfixés par `plugin:` sont toujours résolus via les approbations du Plugin.
- les autres ID essaient d’abord `exec.approval.resolve`.
- si Telegram est aussi autorisé pour les approbations de plugin et que gateway indique
- si Telegram est aussi autorisé pour les approbations du Plugin et que la Gateway indique
que l’approbation exec est inconnue/expirée, Telegram réessaie une fois via
`plugin.approval.resolve`.
- les refus/erreurs d’approbation exec réels ne retombent pas silencieusement sur la résolution
d’approbation de plugin.
- les refus/erreurs réels d’approbation exec ne basculent pas silencieusement vers la
résolution d’approbation du Plugin.
La livraison dans le canal affiche le texte de la commande dans le chat ; activez donc `channel` ou `both` uniquement dans des groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw préserve le sujet à la fois pour l’invite d’approbation et pour le suivi après approbation. Les approbations exec expirent après 30 minutes par défaut.
La livraison dans le canal affiche le texte de la commande dans le chat ; n’activez donc `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw préserve le sujet à la fois pour l’invite d’approbation et pour le suivi post-approbation. Les approbations exec expirent au bout de 30 minutes par défaut.
Les boutons d’approbation intégrés dépendent aussi du fait que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`).
Les boutons d’approbation en ligne dépendent aussi du fait que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`).
Documentation associée : [Approbations exec](/tools/exec-approvals)
Documentation associée : [Approbations exec](/fr/tools/exec-approvals)
</Accordion>
</AccordionGroup>
@ -865,10 +865,10 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut soit répondre avec le texte d’erreur, soit le supprimer. Deux clés de configuration contrôlent ce comportement :
| Clé | Valeurs | Par défaut | Description |
| ----------------------------------- | ----------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial dans le chat. `silent` supprime entièrement les réponses d’erreur. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Temps minimal entre deux réponses d’erreur au même chat. Empêche le spam d’erreurs pendant les pannes. |
| Key | Values | Default | Description |
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial dans le chat. `silent` supprime entièrement les réponses d’erreur. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Temps minimal entre les réponses d’erreur vers le même chat. Empêche le spam d’erreurs pendant les pannes. |
Les remplacements par compte, par groupe et par sujet sont pris en charge (même héritage que pour les autres clés de configuration Telegram).
@ -880,7 +880,7 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
errorCooldownMs: 120000,
groups: {
"-1001234567890": {
errorPolicy: "silent", // supprimer les erreurs dans ce groupe
errorPolicy: "silent", // supprime les erreurs dans ce groupe
},
},
},
@ -894,10 +894,10 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
<Accordion title="Le bot ne répond pas aux messages de groupe sans mention">
- Si `requireMention=false`, le mode confidentialité Telegram doit autoriser une visibilité complète.
- BotFather : `/setprivacy` -> Désactiver
- puis supprimer + réajouter le bot au groupe
- BotFather : `/setprivacy` -> Disable
- puis retirez + rajoutez le bot au groupe
- `openclaw channels status` avertit lorsque la configuration attend des messages de groupe sans mention.
- `openclaw channels status --probe` peut vérifier des ID de groupe numériques explicites ; le joker `"*"` ne peut pas être sondé pour l’appartenance.
- `openclaw channels status --probe` peut vérifier des ID de groupe numériques explicites ; le joker `"*"` ne peut pas être vérifié pour l’appartenance.
- test rapide de session : `/activation always`.
</Accordion>
@ -912,19 +912,19 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
<Accordion title="Les commandes fonctionnent partiellement ou pas du tout">
- autorisez votre identité d’expéditeur (appairage et/ou `allowFrom` numérique)
- autorisez l’identité de votre expéditeur (appairage et/ou `allowFrom` numérique)
- l’autorisation des commandes s’applique toujours même lorsque la politique de groupe est `open`
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif a trop d’entrées ; réduisez les commandes personnalisées/de plugin/de Skills ou désactivez les menus natifs
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif comporte trop d’entrées ; réduisez les commandes de Plugin/Skills/personnalisées ou désactivez les menus natifs
- `setMyCommands failed` avec des erreurs réseau/fetch indique généralement des problèmes d’accessibilité DNS/HTTPS vers `api.telegram.org`
</Accordion>
<Accordion title="Polling ou instabilité réseau">
<Accordion title="Instabilité du polling ou du réseau">
- Node 22+ + fetch/proxy personnalisé peuvent déclencher un comportement d’abandon immédiat si les types AbortSignal ne correspondent pas.
- Certains hôtes résolvent `api.telegram.org` vers IPv6 en premier ; une sortie IPv6 défectueuse peut provoquer des échecs intermittents de Telegram API.
- Node 22+ + fetch/proxy personnalisé peut déclencher un comportement d’abandon immédiat si les types `AbortSignal` ne correspondent pas.
- Certains hôtes résolvent `api.telegram.org` d’abord en IPv6 ; une sortie IPv6 défaillante peut provoquer des pannes intermittentes de l’API Telegram.
- Si les journaux incluent `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, OpenClaw réessaie désormais ces cas comme des erreurs réseau récupérables.
- Sur des hôtes VPS avec sortie directe/TLS instable, faites passer les appels Telegram API via `channels.telegram.proxy` :
- Sur des hôtes VPS avec sortie directe/TLS instable, routez les appels API Telegram via `channels.telegram.proxy` :
```yaml
channels:
@ -943,10 +943,10 @@ channels:
```
- Les réponses de plage de benchmark RFC 2544 (`198.18.0.0/15`) sont déjà autorisées
par défaut pour les téléchargements de médias Telegram. Si un faux IP ou un proxy
transparent de confiance réécrit `api.telegram.org` vers une autre
adresse privée/interne/spéciale lors des téléchargements de médias, vous pouvez activer
le contournement réservé à Telegram :
par défaut pour les téléchargements de médias Telegram. Si une fausse IP de confiance ou un
proxy transparent réécrit `api.telegram.org` vers une autre
adresse privée/interne/à usage spécial pendant les téléchargements de médias, vous pouvez
activer le contournement propre à Telegram :
```yaml
channels:
@ -955,25 +955,25 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- Le même opt-in est disponible par compte dans
- La même option d’activation existe aussi par compte dans
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
- Si votre proxy résout les hôtes média Telegram en `198.18.x.x`, laissez
d’abord le drapeau dangereux désactivé. Les médias Telegram autorisent déjà
la plage de benchmark RFC 2544 par défaut.
- Si votre proxy résout les hôtes média Telegram en `198.18.x.x`, laissez d’abord
cette option dangereuse désactivée. Les médias Telegram autorisent déjà par défaut
la plage de benchmark RFC 2544.
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections
SSRF des médias Telegram. Utilisez-le uniquement dans des environnements de proxy
de confiance contrôlés par l’opérateur, tels que le routage fake-IP de Clash, Mihomo ou Surge,
lorsqu’ils synthétisent des réponses privées ou spéciales en dehors de la
plage de benchmark RFC 2544. Laissez-le désactivé pour un accès Telegram Internet public normal.
`channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections SSRF
des médias Telegram. Utilisez-le uniquement dans des environnements proxy de confiance contrôlés par l’opérateur
tels que le routage fake-IP de Clash, Mihomo ou Surge lorsqu’ils synthétisent des réponses
privées ou à usage spécial en dehors de la plage de benchmark RFC 2544.
Laissez-le désactivé pour un accès Telegram normal sur l’internet public.
</Warning>
- Remplacements via variables d’environnement (temporaires) :
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Validez les réponses DNS :
- Valider les réponses DNS :
```bash
dig +short api.telegram.org A
@ -983,9 +983,9 @@ dig +short api.telegram.org AAAA
</Accordion>
</AccordionGroup>
Plus d’aide : [Dépannage des canaux](/channels/troubleshooting).
Plus d’aide : [Dépannage du canal](/fr/channels/troubleshooting).
## Pointeurs de référence de configuration Telegram
## Pointeurs vers la référence de configuration Telegram
Référence principale :
@ -993,69 +993,69 @@ Référence principale :
- `channels.telegram.botToken` : jeton du bot (BotFather).
- `channels.telegram.tokenFile` : lire le jeton depuis un chemin de fichier ordinaire. Les liens symboliques sont rejetés.
- `channels.telegram.dmPolicy` : `pairing | allowlist | open | disabled` (par défaut : pairing).
- `channels.telegram.allowFrom` : liste d’autorisation DM (ID utilisateur Telegram numériques). `allowlist` exige au moins un ID d’expéditeur. `open` exige `"*"`. `openclaw doctor --fix` peut résoudre les anciennes entrées `@username` en ID et peut récupérer des entrées de liste d’autorisation à partir des fichiers du magasin d’appairage dans les flux de migration de liste d’autorisation.
- `channels.telegram.allowFrom` : liste d’autorisation DM (ID utilisateur Telegram numériques). `allowlist` nécessite au moins un ID d’expéditeur. `open` nécessite `"*"`. `openclaw doctor --fix` peut résoudre les anciennes entrées `@username` en ID et peut récupérer des entrées d’allowlist depuis des fichiers du magasin d’appairage dans les flux de migration allowlist.
- `channels.telegram.actions.poll` : activer ou désactiver la création de sondages Telegram (activé par défaut ; nécessite toujours `sendMessage`).
- `channels.telegram.defaultTo` : cible Telegram par défaut utilisée par le CLI `--deliver` lorsqu’aucun `--reply-to` explicite n’est fourni.
- `channels.telegram.groupPolicy` : `open | allowlist | disabled` (par défaut : allowlist).
- `channels.telegram.groupAllowFrom` : liste d’autorisation des expéditeurs de groupe (ID utilisateur Telegram numériques). `openclaw doctor --fix` peut résoudre les anciennes entrées `@username` en ID. Les entrées non numériques sont ignorées au moment de l’authentification. L’authentification de groupe n’utilise pas de repli sur le magasin d’appairage DM (`2026.2.25+`).
- `channels.telegram.groupAllowFrom` : liste d’autorisation des expéditeurs de groupe (ID utilisateur Telegram numériques). `openclaw doctor --fix` peut résoudre les anciennes entrées `@username` en ID. Les entrées non numériques sont ignorées au moment de l’authentification. L’authentification de groupe n’utilise pas le repli du magasin d’appairage DM (`2026.2.25+`).
- Priorité multi-comptes :
- Lorsque deux ID de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) pour rendre le routage par défaut explicite.
- Si aucun n’est défini, OpenClaw retombe sur le premier ID de compte normalisé et `openclaw doctor` émet un avertissement.
- `channels.telegram.accounts.default.allowFrom` et `channels.telegram.accounts.default.groupAllowFrom` ne s’appliquent qu’au compte `default`.
- Lorsque deux ID de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) pour expliciter le routage par défaut.
- Si aucun des deux n’est défini, OpenClaw se rabat sur le premier ID de compte normalisé et `openclaw doctor` affiche un avertissement.
- `channels.telegram.accounts.default.allowFrom` et `channels.telegram.accounts.default.groupAllowFrom` s’appliquent uniquement au compte `default`.
- Les comptes nommés héritent de `channels.telegram.allowFrom` et `channels.telegram.groupAllowFrom` lorsque les valeurs au niveau du compte ne sont pas définies.
- Les comptes nommés n’héritent pas de `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
- `channels.telegram.groups` : valeurs par défaut par groupe + liste d’autorisation (utilisez `"*"` pour des valeurs par défaut globales).
- `channels.telegram.groups` : valeurs par défaut par groupe + allowlist (utilisez `"*"` pour les valeurs par défaut globales).
- `channels.telegram.groups.<id>.groupPolicy` : remplacement par groupe pour groupPolicy (`open | allowlist | disabled`).
- `channels.telegram.groups.<id>.requireMention` : valeur par défaut du contrôle par mention.
- `channels.telegram.groups.<id>.skills` : filtre Skills (omission = tous les Skills, vide = aucun).
- `channels.telegram.groups.<id>.allowFrom` : remplacement de la liste d’autorisation des expéditeurs par groupe.
- `channels.telegram.groups.<id>.requireMention` : valeur par défaut du filtrage par mention.
- `channels.telegram.groups.<id>.skills` : filtre de Skills (omis = toutes les Skills, vide = aucune).
- `channels.telegram.groups.<id>.allowFrom` : remplacement par groupe de la liste d’autorisation des expéditeurs.
- `channels.telegram.groups.<id>.systemPrompt` : prompt système supplémentaire pour le groupe.
- `channels.telegram.groups.<id>.enabled` : désactive le groupe lorsque `false`.
- `channels.telegram.groups.<id>.topics.<threadId>.*` : remplacements par sujet (champs de groupe + `agentId` réservé au sujet).
- `channels.telegram.groups.<id>.topics.<threadId>.agentId` : route ce sujet vers un agent spécifique (remplace le routage au niveau du groupe et des liaisons).
- `channels.telegram.groups.<id>.enabled` : désactive le groupe lorsqu’il vaut `false`.
- `channels.telegram.groups.<id>.topics.<threadId>.*` : remplacements par sujet (champs de groupe + `agentId` propre au sujet).
- `channels.telegram.groups.<id>.topics.<threadId>.agentId` : route ce sujet vers un agent spécifique (remplace le routage au niveau du groupe et des bindings).
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy` : remplacement par sujet pour groupPolicy (`open | allowlist | disabled`).
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention` : remplacement du contrôle par mention par sujet.
- `bindings[]` de niveau supérieur avec `type: "acp"` et ID de sujet canonique `chatId:topic:topicId` dans `match.peer.id` : champs de liaison ACP persistante par sujet (voir [Agents ACP](/tools/acp-agents#channel-specific-settings)).
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention` : remplacement par sujet du filtrage par mention.
- `bindings[]` de niveau supérieur avec `type: "acp"` et ID de sujet canonique `chatId:topic:topicId` dans `match.peer.id` : champs de liaison persistante de sujet ACP (voir [Agents ACP](/fr/tools/acp-agents#channel-specific-settings)).
- `channels.telegram.direct.<id>.topics.<threadId>.agentId` : route les sujets DM vers un agent spécifique (même comportement que les sujets de forum).
- `channels.telegram.execApprovals.enabled` : active Telegram comme client d’approbation exec basé sur le chat pour ce compte.
- `channels.telegram.execApprovals.approvers` : ID utilisateur Telegram autorisés à approuver ou refuser des demandes exec. Facultatif lorsque `channels.telegram.allowFrom` ou un `channels.telegram.defaultTo` direct identifie déjà le propriétaire.
- `channels.telegram.execApprovals.target` : `dm | channel | both` (par défaut : `dm`). `channel` et `both` préservent le sujet Telegram d’origine lorsqu’il est présent.
- `channels.telegram.execApprovals.agentFilter` : filtre facultatif sur les ID d’agent pour les invites d’approbation transférées.
- `channels.telegram.execApprovals.sessionFilter` : filtre facultatif sur les clés de session (sous-chaîne ou regex) pour les invites d’approbation transférées.
- `channels.telegram.execApprovals.agentFilter` : filtre facultatif d’ID d’agent pour les invites d’approbation transférées.
- `channels.telegram.execApprovals.sessionFilter` : filtre facultatif de clé de session (sous-chaîne ou regex) pour les invites d’approbation transférées.
- `channels.telegram.accounts.<account>.execApprovals` : remplacement par compte pour le routage des approbations exec Telegram et l’autorisation des approbateurs.
- `channels.telegram.capabilities.inlineButtons` : `off | dm | group | all | allowlist` (par défaut : allowlist).
- `channels.telegram.accounts.<account>.capabilities.inlineButtons` : remplacement par compte.
- `channels.telegram.commands.nativeSkills` : activer/désactiver les commandes natives de Skills Telegram.
- `channels.telegram.commands.nativeSkills` : activer/désactiver les commandes natives Skills de Telegram.
- `channels.telegram.replyToMode` : `off | first | all` (par défaut : `off`).
- `channels.telegram.textChunkLimit` : taille de segmentation sortante (caractères).
- `channels.telegram.chunkMode` : `length` (par défaut) ou `newline` pour segmenter sur les lignes vides (frontières de paragraphe) avant la segmentation par longueur.
- `channels.telegram.linkPreview` : activer/désactiver les aperçus de liens pour les messages sortants (par défaut : true).
- `channels.telegram.streaming` : `off | partial | block | progress` (aperçu de flux en direct ; par défaut : `partial` ; `progress` correspond à `partial` ; `block` est une compatibilité héritée avec le mode d’aperçu). Le flux d’aperçu Telegram utilise un unique message d’aperçu modifié sur place.
- `channels.telegram.mediaMaxMb` : limite de médias Telegram entrants/sortants (MB, par défaut : 100).
- `channels.telegram.retry` : politique de nouvelle tentative pour les helpers d’envoi Telegram (CLI/outils/actions) sur les erreurs API sortantes récupérables (tentatives, minDelayMs, maxDelayMs, jitter).
- `channels.telegram.textChunkLimit` : taille de fragment sortant (caractères).
- `channels.telegram.chunkMode` : `length` (par défaut) ou `newline` pour découper sur les lignes vides (limites de paragraphe) avant le découpage par longueur.
- `channels.telegram.linkPreview` : active/désactive les aperçus de liens pour les messages sortants (par défaut : true).
- `channels.telegram.streaming` : `off | partial | block | progress` (aperçu du flux en direct ; par défaut : `partial` ; `progress` est mappé vers `partial` ; `block` est la compatibilité avec l’ancien mode d’aperçu). Le flux d’aperçu Telegram utilise un unique message d’aperçu modifié sur place.
- `channels.telegram.mediaMaxMb` : limite de médias Telegram entrants/sortants (Mo, 100 par défaut).
- `channels.telegram.retry` : politique de nouvelle tentative pour les helpers d’envoi Telegram (CLI/outils/actions) sur les erreurs récupérables de l’API sortante (tentatives, minDelayMs, maxDelayMs, jitter).
- `channels.telegram.network.autoSelectFamily` : remplace Node autoSelectFamily (true=activer, false=désactiver). Activé par défaut sur Node 22+, avec WSL2 désactivé par défaut.
- `channels.telegram.network.dnsResultOrder` : remplace l’ordre des résultats DNS (`ipv4first` ou `verbatim`). `ipv4first` par défaut sur Node 22+.
- `channels.telegram.network.dangerouslyAllowPrivateNetwork` : opt-in dangereux pour les environnements de faux IP ou proxy transparent de confiance où les téléchargements de médias Telegram résolvent `api.telegram.org` vers des adresses privées/internes/spéciales en dehors de la plage de benchmark RFC 2544 autorisée par défaut.
- `channels.telegram.proxy` : URL du proxy pour les appels Bot API (SOCKS/HTTP).
- `channels.telegram.webhookUrl` : active le mode webhook (nécessite `channels.telegram.webhookSecret`).
- `channels.telegram.webhookSecret` : secret webhook (obligatoire lorsque `webhookUrl` est défini).
- `channels.telegram.webhookPath` : chemin webhook local (par défaut `/telegram-webhook`).
- `channels.telegram.webhookHost` : hôte de liaison du webhook local (par défaut `127.0.0.1`).
- `channels.telegram.webhookPort` : port de liaison du webhook local (par défaut `8787`).
- `channels.telegram.actions.reactions` : restreint les réactions d’outil Telegram.
- `channels.telegram.actions.sendMessage` : restreint les envois de message d’outil Telegram.
- `channels.telegram.actions.deleteMessage` : restreint les suppressions de message d’outil Telegram.
- `channels.telegram.actions.sticker` : restreint les actions de sticker Telegram — envoi et recherche (par défaut : false).
- `channels.telegram.reactionNotifications` : `off | own | all` — contrôle quelles réactions déclenchent des événements système (par défaut : `own` si non défini).
- `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` — contrôle la capacité de réaction de l’agent (par défaut : `minimal` si non défini).
- `channels.telegram.network.dnsResultOrder` : remplace l’ordre de résultat DNS (`ipv4first` ou `verbatim`). `ipv4first` par défaut sur Node 22+.
- `channels.telegram.network.dangerouslyAllowPrivateNetwork` : option dangereuse pour les environnements de fake-IP ou de proxy transparent de confiance où les téléchargements de médias Telegram résolvent `api.telegram.org` vers des adresses privées/internes/à usage spécial en dehors de l’autorisation par défaut de la plage de benchmark RFC 2544.
- `channels.telegram.proxy` : URL de proxy pour les appels API Bot (SOCKS/HTTP).
- `channels.telegram.webhookUrl` : active le mode Webhook (nécessite `channels.telegram.webhookSecret`).
- `channels.telegram.webhookSecret` : secret Webhook (obligatoire lorsque webhookUrl est défini).
- `channels.telegram.webhookPath` : chemin Webhook local (par défaut `/telegram-webhook`).
- `channels.telegram.webhookHost` : hôte de liaison Webhook local (par défaut `127.0.0.1`).
- `channels.telegram.webhookPort` : port de liaison Webhook local (par défaut `8787`).
- `channels.telegram.actions.reactions` : limite les réactions des outils Telegram.
- `channels.telegram.actions.sendMessage` : limite les envois de messages des outils Telegram.
- `channels.telegram.actions.deleteMessage` : limite les suppressions de messages des outils Telegram.
- `channels.telegram.actions.sticker` : limite les actions de sticker Telegram — envoi et recherche (par défaut : false).
- `channels.telegram.reactionNotifications` : `off | own | all` — contrôle quelles réactions déclenchent des événements système (par défaut : `own` lorsqu’il n’est pas défini).
- `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` — contrôle la capacité de réaction de l’agent (par défaut : `minimal` lorsqu’il n’est pas défini).
- `channels.telegram.errorPolicy` : `reply | silent` — contrôle le comportement des réponses d’erreur (par défaut : `reply`). Remplacements par compte/groupe/sujet pris en charge.
- `channels.telegram.errorCooldownMs` : nombre minimal de ms entre deux réponses d’erreur au même chat (par défaut : `60000`). Empêche le spam d’erreurs pendant les pannes.
- `channels.telegram.errorCooldownMs` : nombre minimal de ms entre les réponses d’erreur vers le même chat (par défaut : `60000`). Empêche le spam d’erreurs pendant les pannes.
- [Référence de configuration - Telegram](/gateway/configuration-reference#telegram)
- [Référence de configuration - Telegram](/fr/gateway/configuration-reference#telegram)
Champs Telegram spécifiques à fort signal :
- démarrage/authentification : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier ordinaire ; les liens symboliques sont rejetés)
- démarrage/auth : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier ordinaire ; les liens symboliques sont rejetés)
- contrôle d’accès : `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de niveau supérieur (`type: "acp"`)
- approbations exec : `execApprovals`, `accounts.*.execApprovals`
- commande/menu : `commands.native`, `commands.nativeSkills`, `customCommands`
@ -1063,17 +1063,17 @@ Champs Telegram spécifiques à fort signal :
- streaming : `streaming` (aperçu), `blockStreaming`
- formatage/livraison : `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
- média/réseau : `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
- webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- Webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- actions/capacités : `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- réactions : `reactionNotifications`, `reactionLevel`
- erreurs : `errorPolicy`, `errorCooldownMs`
- écritures/historique : `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
## Liens associés
## Associé
- [Appairage](/channels/pairing)
- [Groupes](/channels/groups)
- [Sécurité](/gateway/security)
- [Routage des canaux](/channels/channel-routing)
- [Routage multi-agent](/concepts/multi-agent)
- [Dépannage](/channels/troubleshooting)
- [Appairage](/fr/channels/pairing)
- [Groupes](/fr/channels/groups)
- [Sécurité](/fr/gateway/security)
- [Routage des canaux](/fr/channels/channel-routing)
- [Routage multi-agent](/fr/concepts/multi-agent)
- [Dépannage](/fr/channels/troubleshooting)

143
docs/fr/channels/troubleshooting.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Le transport du canal indique connecté, mais les réponses échouent
- Vous avez besoin de vérifications spécifiques au canal avant la documentation approfondie du fournisseur
summary: Dépannage rapide au niveau des canaux avec signatures de panne et correctifs par canal
- Le transport du canal indique qu’il est connecté, mais les réponses échouent
- Vous avez besoin de vérifications spécifiques au canal avant de consulter en détail la documentation du fournisseur.
summary: Dépannage rapide au niveau des canaux avec signatures d’échec et correctifs par canal
title: Dépannage des canaux
x-i18n:
generated_at: "2026-04-05T12:36:45Z"
generated_at: "2026-04-20T07:05:27Z"
model: gpt-5.4
provider: openai
source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528
source_path: channels/troubleshooting.md
workflow: 15
---
# Dépannage des canaux
Utilisez cette page lorsqu’un canal se connecte, mais que son comportement est incorrect.
Utilisez cette page lorsqu’un canal se connecte, mais que le comportement est incorrect.
## Échelle de commandes
Exécutez d’abord celles-ci dans l’ordre :
Exécutez d’abord celles-ci dans cet ordre :
```bash
openclaw status
@ -29,112 +29,113 @@ openclaw doctor
openclaw channels status --probe
```
Base de référence saine :
Référence saine :
- `Runtime: running`
- `RPC probe: ok`
- La sonde du canal indique que le transport est connecté et, lorsque pris en charge, `works` ou `audit ok`
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable` ou `admin-capable`
- La sonde du canal indique que le transport est connecté et, lorsque c’est pris en charge, `works` ou `audit ok`
## WhatsApp
### Signatures de panne WhatsApp
### Signatures d’échec WhatsApp
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------------- |
| Connecté mais aucune réponse DM | `openclaw pairing list whatsapp` | Approuvez l’expéditeur ou changez la politique DM/la liste d’autorisation. |
| Messages de groupe ignorés | Vérifiez `requireMention` et les motifs de mention dans la configuration | Mentionnez le bot ou assouplissez la politique de mention pour ce groupe. |
| Boucles aléatoires de déconnexion/reconnexion | `openclaw channels status --probe` + journaux | Reconnectez-vous et vérifiez que le répertoire d’identifiants est sain. |
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------- | --------------------------------------------------- | ------------------------------------------------------------- |
| Connecté mais aucune réponse en DM | `openclaw pairing list whatsapp` | Approuvez l’expéditeur ou modifiez la politique DM/la liste d’autorisation. |
| Messages de groupe ignorés | Vérifiez `requireMention` + les motifs de mention dans la configuration | Mentionnez le bot ou assouplissez la politique de mention pour ce groupe. |
| Déconnexions/boucles de reconnexion aléatoires | `openclaw channels status --probe` + journaux | Reconnectez-vous et vérifiez que le répertoire des identifiants est sain. |
Dépannage complet : [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
Dépannage complet : [/channels/whatsapp#troubleshooting](/fr/channels/whatsapp#troubleshooting)
## Telegram
### Signatures de panne Telegram
### Signatures d’échec Telegram
| Symptôme | Vérification la plus rapide | Correctif |
| ----------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
| `/start` mais aucun flux de réponse exploitable | `openclaw pairing list telegram` | Approuvez l’appairage ou modifiez la politique DM. |
| Bot en ligne mais groupe silencieux | Vérifiez l’obligation de mention et le mode confidentialité du bot | Désactivez le mode confidentialité pour la visibilité en groupe ou mentionnez le bot. |
| Échecs d’envoi avec erreurs réseau | Inspectez les journaux pour les échecs d’appel à l’API Telegram | Corrigez le routage DNS/IPv6/proxy vers `api.telegram.org`. |
| `setMyCommands` rejeté au démarrage | Inspectez les journaux pour `BOT_COMMANDS_TOO_MUCH` | Réduisez les commandes Telegram de plugin/Skills/personnalisées ou désactivez les menus natifs. |
| Après mise à niveau, la liste d’autorisation vous bloque | `openclaw security audit` et les listes d’autorisation de la configuration | Exécutez `openclaw doctor --fix` ou remplacez `@username` par des identifiants numériques d’expéditeur. |
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------- |
| `/start` mais aucun flux de réponse exploitable | `openclaw pairing list telegram` | Approuvez l’association ou modifiez la politique DM. |
| Bot en ligne mais groupe silencieux | Vérifiez l’exigence de mention et le mode confidentialité du bot | Désactivez le mode confidentialité pour la visibilité du groupe ou mentionnez le bot. |
| Échecs d’envoi avec erreurs réseau | Inspectez les journaux pour les échecs d’appel à l’API Telegram | Corrigez le routage DNS/IPv6/proxy vers `api.telegram.org`. |
| `setMyCommands` rejeté au démarrage | Inspectez les journaux pour `BOT_COMMANDS_TOO_MUCH` | Réduisez les commandes Telegram de Plugin/Skills/personnalisées ou désactivez les menus natifs. |
| Mise à niveau effectuée et la liste d’autorisation vous bloque | `openclaw security audit` et les listes d’autorisation de la configuration | Exécutez `openclaw doctor --fix` ou remplacez `@username` par des identifiants numériques d’expéditeur. |
Dépannage complet : [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
Dépannage complet : [/channels/telegram#troubleshooting](/fr/channels/telegram#troubleshooting)
## Discord
### Signatures de panne Discord
### Signatures d’échec Discord
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------ | ------------------------------------ | -------------------------------------------------------- |
| Bot en ligne mais aucune réponse dans la guilde | `openclaw channels status --probe` | Autorisez la guilde/le canal et vérifiez l’intention de contenu des messages. |
| Messages de groupe ignorés | Vérifiez dans les journaux les rejets dus au filtrage par mention | Mentionnez le bot ou définissez `requireMention: false` pour la guilde/le canal. |
| Réponses DM manquantes | `openclaw pairing list discord` | Approuvez l’appairage DM ou ajustez la politique DM. |
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
| Bot en ligne mais aucune réponse sur le serveur | `openclaw channels status --probe` | Autorisez le serveur/le canal et vérifiez l’intent de contenu des messages. |
| Messages de groupe ignorés | Vérifiez dans les journaux les rejets par filtrage de mention | Mentionnez le bot ou définissez `requireMention: false` pour le serveur/le canal. |
| Réponses DM absentes | `openclaw pairing list discord` | Approuvez l’association DM ou ajustez la politique DM. |
Dépannage complet : [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
Dépannage complet : [/channels/discord#troubleshooting](/fr/channels/discord#troubleshooting)
## Slack
### Signatures de panne Slack
### Signatures d’échec Slack
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Mode socket connecté mais aucune réponse | `openclaw channels status --probe` | Vérifiez le jeton d’application + le jeton de bot et les scopes requis ; surveillez `botTokenStatus` / `appTokenStatus = configured_unavailable` dans les configurations basées sur SecretRef. |
| DMs bloqués | `openclaw pairing list slack` | Approuvez l’appairage ou assouplissez la politique DM. |
| Message de canal ignoré | Vérifiez `groupPolicy` et la liste d’autorisation des canaux | Autorisez le canal ou changez la politique en `open`. |
| Symptôme | Vérification la plus rapide | Correctif |
| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Socket mode connecté mais aucune réponse | `openclaw channels status --probe` | Vérifiez le jeton d’application + le jeton du bot et les permissions requises ; surveillez `botTokenStatus` / `appTokenStatus = configured_unavailable` dans les configurations basées sur SecretRef. |
| DMs bloqués | `openclaw pairing list slack` | Approuvez l’association ou assouplissez la politique DM. |
| Message de canal ignoré | Vérifiez `groupPolicy` et la liste d’autorisation des canaux | Autorisez le canal ou basculez la politique sur `open`. |
Dépannage complet : [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
Dépannage complet : [/channels/slack#troubleshooting](/fr/channels/slack#troubleshooting)
## iMessage et BlueBubbles
### Signatures de panne iMessage et BlueBubbles
### Signatures d’échec iMessage et BlueBubbles
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------- | ------------------------------------------------------ | ----------------------------------------------------- |
| Aucun événement entrant | Vérifiez l’accessibilité du webhook/serveur et les autorisations de l’application | Corrigez l’URL du webhook ou l’état du serveur BlueBubbles. |
| Symptôme | Vérification la plus rapide | Correctif |
| --------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------- |
| Aucun événement entrant | Vérifiez l’accessibilité du Webhook/serveur et les autorisations de l’application | Corrigez l’URL du Webhook ou l’état du serveur BlueBubbles. |
| Peut envoyer mais ne reçoit pas sur macOS | Vérifiez les autorisations de confidentialité macOS pour l’automatisation de Messages | Réaccordez les autorisations TCC et redémarrez le processus du canal. |
| Expéditeur DM bloqué | `openclaw pairing list imessage` ou `openclaw pairing list bluebubbles` | Approuvez l’appairage ou mettez à jour la liste d’autorisation. |
| Expéditeur DM bloqué | `openclaw pairing list imessage` ou `openclaw pairing list bluebubbles` | Approuvez l’association ou mettez à jour la liste d’autorisation. |
Dépannage complet :
Dépannage complet :
- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
- [/channels/imessage#troubleshooting](/fr/channels/imessage#troubleshooting)
- [/channels/bluebubbles#troubleshooting](/fr/channels/bluebubbles#troubleshooting)
## Signal
### Signatures de panne Signal
### Signatures d’échec Signal
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------ | --------------------------------------- | -------------------------------------------------------- |
| Daemon joignable mais bot silencieux | `openclaw channels status --probe` | Vérifiez l’URL/le compte du daemon `signal-cli` et le mode de réception. |
| DM bloqué | `openclaw pairing list signal` | Approuvez l’expéditeur ou ajustez la politique DM. |
| Les réponses de groupe ne se déclenchent pas | Vérifiez la liste d’autorisation des groupes et les motifs de mention | Ajoutez l’expéditeur/le groupe ou assouplissez le filtrage. |
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| Démon accessible mais bot silencieux | `openclaw channels status --probe` | Vérifiez l’URL/le compte du démon `signal-cli` et le mode de réception. |
| DM bloqué | `openclaw pairing list signal` | Approuvez l’expéditeur ou ajustez la politique DM. |
| Les réponses de groupe ne se déclenchent pas | Vérifiez la liste d’autorisation du groupe et les motifs de mention | Ajoutez l’expéditeur/le groupe ou assouplissez le filtrage. |
Dépannage complet : [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
Dépannage complet : [/channels/signal#troubleshooting](/fr/channels/signal#troubleshooting)
## QQ Bot
### Signatures de panne QQ Bot
### Signatures d’échec QQ Bot
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------ | ------------------------------------------ | -------------------------------------------------------------- |
| Le bot répond "gone to Mars" | Vérifiez `appId` et `clientSecret` dans la configuration | Définissez les identifiants ou redémarrez la gateway. |
| Aucun message entrant | `openclaw channels status --probe` | Vérifiez les identifiants sur la QQ Open Platform. |
| La voix n’est pas transcrite | Vérifiez la configuration du fournisseur STT | Configurez `channels.qqbot.stt` ou `tools.media.audio`. |
| Symptôme | Vérification la plus rapide | Correctif |
| -------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
| Le bot répond « gone to Mars » | Vérifiez `appId` et `clientSecret` dans la configuration | Définissez les identifiants ou redémarrez la Gateway. |
| Aucun message entrant | `openclaw channels status --probe` | Vérifiez les identifiants sur la QQ Open Platform. |
| La voix n’est pas transcrite | Vérifiez la configuration du fournisseur STT | Configurez `channels.qqbot.stt` ou `tools.media.audio`. |
| Les messages proactifs n’arrivent pas | Vérifiez les exigences d’interaction de la plateforme QQ | QQ peut bloquer les messages initiés par le bot sans interaction récente. |
Dépannage complet : [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting)
Dépannage complet : [/channels/qqbot#troubleshooting](/fr/channels/qqbot#troubleshooting)
## Matrix
### Signatures de panne Matrix
### Signatures d’échec Matrix
| Symptôme | Vérification la plus rapide | Correctif |
| ----------------------------------- | --------------------------------------- | -------------------------------------------------------------------------- |
| Connecté mais ignore les messages du salon | `openclaw channels status --probe` | Vérifiez `groupPolicy`, la liste d’autorisation des salons et le filtrage par mention. |
| Les DMs ne sont pas traités | `openclaw pairing list matrix` | Approuvez l’expéditeur ou ajustez la politique DM. |
| Les salons chiffrés échouent | `openclaw matrix verify status` | Revérifiez l’appareil, puis vérifiez `openclaw matrix verify backup status`. |
| La restauration de sauvegarde est en attente/cassée | `openclaw matrix verify backup status` | Exécutez `openclaw matrix verify backup restore` ou relancez avec une clé de récupération. |
| La signature croisée/bootstrap semble incorrecte | `openclaw matrix verify bootstrap` | Réparez le stockage des secrets, la signature croisée et l’état de sauvegarde en un seul passage. |
| Symptôme | Vérification la plus rapide | Correctif |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- |
| Connecté mais ignore les messages de salon | `openclaw channels status --probe` | Vérifiez `groupPolicy`, la liste d’autorisation des salons et le filtrage par mention. |
| Les DMs ne sont pas traités | `openclaw pairing list matrix` | Approuvez l’expéditeur ou ajustez la politique DM. |
| Échec des salons chiffrés | `openclaw matrix verify status` | Revérifiez l’appareil, puis consultez `openclaw matrix verify backup status`. |
| La restauration de sauvegarde est en attente/cassée | `openclaw matrix verify backup status` | Exécutez `openclaw matrix verify backup restore` ou relancez avec une clé de récupération. |
| L’apparence de la signature croisée/du bootstrap semble incorrecte | `openclaw matrix verify bootstrap` | Réparez en une seule passe le stockage des secrets, la signature croisée et l’état de la sauvegarde. |
Configuration et installation complètes : [Matrix](/channels/matrix)
Configuration et installation complètes : [Matrix](/fr/channels/matrix)

223
docs/fr/concepts/qa-e2e-automation.md
View File

@ -1,37 +1,37 @@
---
read_when:
- Extension de qa-lab ou de qa-channel
- Extension de qa-lab ou qa-channel
- Ajout de scénarios QA adossés au dépôt
- Création d’une automatisation QA de plus grand réalisme autour du tableau de bord Gateway
- Création d’une automatisation QA plus réaliste autour du tableau de bord Gateway
summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios initialisés et les rapports de protocole
title: Automatisation QA E2E
x-i18n:
generated_at: "2026-04-18T06:43:38Z"
generated_at: "2026-04-20T07:05:28Z"
model: gpt-5.4
provider: openai
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Automatisation QA E2E
La pile QA privée a pour objectif d’exercer OpenClaw d’une manière plus réaliste,
façonnée comme un canal, qu’un simple test unitaire ne peut le faire.
La pile QA privée est conçue pour exercer OpenClaw d’une manière plus réaliste,
calquée sur les canaux, qu’un simple test unitaire ne peut le faire.
Éléments actuels :
- `extensions/qa-channel` : canal de messages synthétique avec des surfaces de MP, canal, fil,
réaction, modification et suppression.
- `extensions/qa-channel` : canal de messages synthétique avec des surfaces pour les DM, canaux, fils,
réactions, modifications et suppressions.
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
injecter des messages entrants et exporter un rapport Markdown.
- `qa/` : ressources initiales adossées au dépôt pour la tâche de lancement et les
scénarios QA de référence.
- `qa/` : ressources d’initialisation adossées au dépôt pour la tâche de démarrage et les
scénarios QA de base.
Le flux opérateur QA actuel est un site QA à deux volets :
Le flux opérateur QA actuel est un site QA en deux panneaux :
- Gauche : tableau de bord Gateway (Control UI) avec l’agent.
- Droite : QA Lab, affichant une transcription de type Slack et le plan de scénario.
- Droite : QA Lab, affichant la transcription de type Slack et le plan du scénario.
Exécutez-le avec :
@ -40,11 +40,11 @@ pnpm qa:lab:up
```
Cela construit le site QA, démarre la voie Gateway adossée à Docker et expose la
page QA Lab où un opérateur ou une boucle d’automatisation peut donner à l’agent une
mission QA, observer le comportement réel du canal et consigner ce qui a fonctionné, échoué
ou est resté bloqué.
page QA Lab où un opérateur ou une boucle d’automatisation peut confier à l’agent une mission QA,
observer le comportement réel du canal et consigner ce qui a fonctionné, échoué ou
est resté bloqué.
Pour une itération plus rapide sur l’interface de QA Lab sans reconstruire l’image Docker à chaque fois,
Pour une itération plus rapide sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois,
démarrez la pile avec un bundle QA Lab monté par liaison :
```bash
@ -57,50 +57,52 @@ pnpm qa:lab:watch
`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte par liaison
`extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch`
reconstruit ce bundle à chaque modification, et le navigateur se recharge automatiquement lorsque le hachage
des ressources de QA Lab change.
des ressources QA Lab change.
Pour une voie smoke Matrix avec transport réel, exécutez :
Pour une voie de smoke test Matrix sur transport réel, exécutez :
```bash
pnpm openclaw qa matrix
```
Cette voie provisionne un homeserver Tuwunel jetable dans Docker, enregistre
des utilisateurs temporaires de pilote, SUT et observateur, crée un salon privé, puis exécute
le vrai plugin Matrix dans un processus enfant QA Gateway. La voie de transport en direct conserve
la configuration enfant limitée au transport testé, afin que Matrix s’exécute sans
Cette voie provisionne un homeserver Tuwunel jetable dans Docker, enregistre des
utilisateurs temporaires driver, SUT et observateur, crée un salon privé, puis exécute
le véritable Plugin Matrix dans un enfant Gateway QA. La voie de transport réel garde
la configuration enfant limitée au transport testé, afin que Matrix fonctionne sans
`qa-channel` dans la configuration enfant. Elle écrit les artefacts de rapport structurés et
un journal combiné stdout/stderr dans le répertoire de sortie Matrix QA sélectionné. Pour
capturer également la sortie de construction/lancement externe de `scripts/run-node.mjs`, définissez
capturer également la sortie de build/lancement externe de `scripts/run-node.mjs`, définissez
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` vers un fichier journal local au dépôt.
Pour une voie smoke Telegram avec transport réel, exécutez :
Pour une voie de smoke test Telegram sur transport réel, exécutez :
```bash
pnpm openclaw qa telegram
```
Cette voie cible un vrai groupe Telegram privé au lieu de provisionner un
serveur jetable. Elle nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
Cette voie cible un véritable groupe privé Telegram au lieu de provisionner un serveur
jetable. Elle nécessite `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` et
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, ainsi que deux bots distincts dans le même
groupe privé. Le bot SUT doit avoir un nom d’utilisateur Telegram, et l’observation
bot à bot fonctionne au mieux lorsque les deux bots ont le mode de communication
bot à bot activé dans `@BotFather`.
bot à bot fonctionne mieux lorsque les deux bots ont le mode Bot-to-Bot Communication
activé dans `@BotFather`.
La commande se termine avec un code de sortie non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque
vous voulez les artefacts sans code de sortie en échec.
Les voies de transport en direct partagent désormais un contrat plus restreint au lieu que chacune invente
sa propre forme de liste de scénarios.
Les voies de transport réel partagent désormais un contrat plus réduit au lieu d’inventer
chacune leur propre forme de liste de scénarios :
`qa-channel` reste la suite large de comportement produit synthétique et ne fait pas partie
de la matrice de couverture de transport en direct.
`qa-channel` reste la suite large de comportements produit synthétiques et ne fait pas partie
de la matrice de couverture des transports réels.
| Voie | Canary | Filtrage des mentions | Blocage de la liste d’autorisation | Réponse de niveau supérieur | Reprise après redémarrage | Suivi dans le fil | Isolation du fil | Observation des réactions | Commande help |
| -------- | ------ | --------------------- | ---------------------------------- | --------------------------- | ------------------------- | ----------------- | ---------------- | ------------------------- | ------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
| Voie | Canary | Contrôle des mentions | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi dans un fil | Isolation des fils | Observation des réactions | Commande d’aide |
| -------- | ------ | --------------------- | -------------------------------- | ------------------------- | ------------------------- | ----------------- | ------------------ | ------------------------- | --------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
Cela permet de conserver `qa-channel` comme suite large de comportement produit tandis que Matrix,
Telegram et les futurs transports en direct partagent une checklist explicite de contrat de transport.
Cela permet de conserver `qa-channel` comme la suite large de comportements produit, tandis que Matrix,
Telegram et les futurs transports réels partagent une liste de contrôle explicite de contrat de transport.
Pour une voie VM Linux jetable sans faire entrer Docker dans le chemin QA, exécutez :
@ -108,27 +110,29 @@ Pour une voie VM Linux jetable sans faire entrer Docker dans le chemin QA, exéc
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Cela démarre un invité Multipass neuf, installe les dépendances, construit OpenClaw
dans l’invité, exécute `qa suite`, puis copie le rapport QA et le
résumé habituels vers `.artifacts/qa-e2e/...` sur l’hôte.
Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw
dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le résumé dans
`.artifacts/qa-e2e/...` sur l’hôte.
Cela réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte.
Les exécutions de suite sur hôte et Multipass exécutent plusieurs scénarios sélectionnés en parallèle
avec des workers Gateway isolés par défaut, jusqu’à 64 workers ou au nombre
de scénarios sélectionnés. Utilisez `--concurrency <count>` pour ajuster le nombre de workers, ou
`--concurrency 1` pour une exécution en série.
Les exécutions en direct transmettent les entrées d’auth QA prises en charge qui sont pratiques pour
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur QA en direct, et
`CODEX_HOME` lorsqu’il est présent. Gardez `--output-dir` sous la racine du dépôt afin que l’invité
puisse réécrire via l’espace de travail monté.
Les exécutions de suite sur l’hôte et sous Multipass exécutent plusieurs scénarios sélectionnés en parallèle
avec des workers Gateway isolés par défaut. `qa-channel` utilise par défaut une concurrence de
4, plafonnée par le nombre de scénarios sélectionnés. Utilisez `--concurrency <count>` pour ajuster
le nombre de workers, ou `--concurrency 1` pour une exécution en série.
La commande se termine avec un code de sortie non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque
vous voulez les artefacts sans code de sortie en échec.
Les exécutions live transmettent les entrées d’auth QA prises en charge qui sont pratiques pour
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA, et
`CODEX_HOME` lorsqu’il est présent. Conservez `--output-dir` sous la racine du dépôt afin que l’invité
puisse écrire en retour via l’espace de travail monté.
## Ressources initiales adossées au dépôt
## Amorces adossées au dépôt
Les ressources initiales se trouvent dans `qa/` :
Les ressources d’initialisation se trouvent dans `qa/` :
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Elles sont volontairement dans git pour que le plan QA soit visible à la fois des humains et de
Elles sont intentionnellement versionnées dans git afin que le plan QA soit visible à la fois pour les humains et pour
l’agent.
`qa-lab` doit rester un exécuteur Markdown générique. Chaque fichier Markdown de scénario est
@ -136,76 +140,75 @@ la source de vérité pour une exécution de test et doit définir :
- les métadonnées du scénario
- des métadonnées facultatives de catégorie, capacité, voie et risque
- les références de documentation et de code
- des exigences de plugin facultatives
- un patch de configuration Gateway facultatif
- des références de documentation et de code
- des exigences facultatives de Plugin
- un correctif facultatif de configuration Gateway
- le `qa-flow` exécutable
La surface d’exécution réutilisable qui sous-tend `qa-flow` peut rester générique
et transversale. Par exemple, les scénarios Markdown peuvent combiner des helpers côté
transport avec des helpers côté navigateur qui pilotent la Control UI intégrée via la
jointure Gateway `browser.request` sans ajouter d’exécuteur spécifique.
La surface d’exécution réutilisable qui sous-tend `qa-flow` est autorisée à rester générique
et transversale. Par exemple, les scénarios Markdown peuvent combiner des
helpers côté transport avec des helpers côté navigateur qui pilotent la Control UI embarquée via la
surface Gateway `browser.request` sans ajouter d’exécuteur à cas particulier.
Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier
de l’arborescence source. Gardez les ID de scénario stables lorsque les fichiers sont déplacés ; utilisez
`docsRefs` et `codeRefs` pour la traçabilité de l’implémentation.
de l’arborescence source. Gardez les ID de scénario stables quand les fichiers changent d’emplacement ; utilisez `docsRefs` et `codeRefs`
pour la traçabilité d’implémentation.
La liste de référence doit rester suffisamment large pour couvrir :
La liste de base doit rester assez large pour couvrir :
- les MP et le chat en canal
- le comportement des fils
- le cycle de vie des actions sur les messages
- les rappels Cron
- le rappel mémoire
- le changement de modèle
- le transfert à un sous-agent
- la lecture du dépôt et de la documentation
- une petite tâche de build telle que Lobster Invaders
- chat DM et canal
- comportement des fils
- cycle de vie des actions sur les messages
- rappels Cron
- rappel de mémoire
- changement de modèle
- transfert à un sous-agent
- lecture du dépôt et de la documentation
- une petite tâche de build comme Lobster Invaders
## Voies mock de fournisseur
## Voies de mock de fournisseur
`qa suite` dispose de deux voies mock locales de fournisseur :
`qa suite` possède deux voies locales de mock de fournisseur :
- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste la
voie mock déterministe par défaut pour la QA adossée au dépôt et les contrôles de parité.
- `aimock` démarre un serveur de fournisseur adossé à AIMock pour une couverture expérimentale de protocole,
de fixtures, d’enregistrement/relecture et de chaos. Il est additionnel et ne remplace pas
- `mock-openai` est le mock OpenClaw sensible aux scénarios. Il reste la
voie de mock déterministe par défaut pour la QA adossée au dépôt et les portes de parité.
- `aimock` démarre un serveur de fournisseur adossé à AIMock pour une couverture expérimentale du protocole,
des fixtures, de l’enregistrement/relecture et du chaos. Il est additif et ne remplace pas
le répartiteur de scénarios `mock-openai`.
L’implémentation des voies de fournisseur se trouve dans `extensions/qa-lab/src/providers/`.
Chaque fournisseur possède ses valeurs par défaut, le démarrage du serveur local, la configuration
du modèle Gateway, les besoins de préparation du profil d’authentification, et les drapeaux de capacité live/mock.
Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu
de brancher sur les noms des fournisseurs.
L’implémentation des voies de fournisseur se trouve sous `extensions/qa-lab/src/providers/`.
Chaque fournisseur est propriétaire de ses valeurs par défaut, du démarrage du serveur local, de la configuration du modèle Gateway,
des besoins de préparation du profil d’authentification, et des indicateurs de capacité live/mock. Le code partagé
de suite et de Gateway doit passer par le registre des fournisseurs au lieu d’effectuer des branchements sur les noms de fournisseurs.
## Adaptateurs de transport
`qa-lab` possède une jointure de transport générique pour les scénarios QA Markdown.
`qa-channel` est le premier adaptateur sur cette jointure, mais l’objectif de conception est plus large :
`qa-lab` possède une interface de transport générique pour les scénarios QA Markdown.
`qa-channel` est le premier adaptateur sur cette interface, mais l’objectif de conception est plus large :
les futurs canaux réels ou synthétiques doivent se brancher sur le même exécuteur de suite
au lieu d’ajouter un exécuteur QA spécifique au transport.
Au niveau de l’architecture, la séparation est la suivante :
Au niveau de l’architecture, la répartition est la suivante :
- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting.
- l’adaptateur de transport possède la configuration Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé.
- les fichiers de scénario Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute.
- `qa-lab` est responsable de l’exécution générique des scénarios, de la concurrence des workers, de l’écriture des artefacts et du reporting.
- l’adaptateur de transport est responsable de la configuration Gateway, de la disponibilité, de l’observation entrante et sortante, des actions de transport et de l’état de transport normalisé.
- les fichiers de scénario Markdown sous `qa/scenarios/` définissent l’exécution du test ; `qa-lab` fournit la surface d’exécution réutilisable qui les exécute.
Les consignes d’adoption destinées aux mainteneurs pour les nouveaux adaptateurs de canal se trouvent dans
[Testing](/fr/help/testing#adding-a-channel-to-qa).
## Rapports
## Reporting
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie observée du bus.
Le rapport doit répondre à :
Le rapport doit répondre à ces questions :
- Ce qui a fonctionné
- Ce qui a échoué
- Ce qui est resté bloqué
- Quels scénarios de suivi valent la peine d’être ajoutés
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références
de modèles live et écrivez un rapport Markdown évalué :
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles live
et rédigez un rapport Markdown évalué :
```bash
pnpm openclaw qa character-eval \
@ -224,31 +227,31 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
La commande exécute des processus enfants QA Gateway locaux, pas Docker. Les
scénarios d’évaluation du caractère doivent définir le persona via `SOUL.md`, puis exécuter des tours
utilisateur ordinaires tels que le chat, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle
candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque transcription complète,
enregistre les statistiques d’exécution de base, puis demande aux modèles juges en mode fast avec
La commande exécute des processus enfants locaux QA Gateway, pas Docker. Les scénarios d’évaluation du caractère
doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires
comme du chat, de l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle candidat
ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque transcription complète,
enregistre des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
un raisonnement `xhigh` de classer les exécutions selon le naturel, l’ambiance et l’humour.
Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours
chaque transcription et état d’exécution, mais les références candidates sont remplacées par des
étiquettes neutres telles que `candidate-01` ; le rapport remappe les classements aux vraies références après
Utilisez `--blind-judge-models` lorsque vous comparez des fournisseurs : l’invite du juge reçoit toujours
chaque transcription et statut d’exécution, mais les références candidates sont remplacées par des
étiquettes neutres comme `candidate-01` ; le rapport remappe les classements vers les références réelles après
l’analyse.
Les exécutions candidates utilisent par défaut un niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui
le prennent en charge. Remplacez un candidat spécifique en ligne avec
`--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours une
Les exécutions candidates utilisent par défaut le niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui
le prennent en charge. Remplacez un candidat précis en ligne avec
`--model provider/model,thinking=<level>`. `--thinking <level>` continue de définir une
valeur de repli globale, et l’ancienne forme `--model-thinking <provider/model=level>` est
conservée pour compatibilité.
Les références candidates OpenAI utilisent par défaut le mode fast afin que le traitement prioritaire soit utilisé là où
Les références candidates OpenAI utilisent par défaut le mode rapide afin d’employer le traitement prioritaire lorsque
le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un
candidat ou juge donné a besoin d’une substitution. Passez `--fast` uniquement si vous souhaitez
forcer le mode fast pour tous les modèles candidats. Les durées des candidats et des juges sont
enregistrées dans le rapport pour l’analyse comparative, mais les invites des juges indiquent explicitement
de ne pas classer selon la vitesse.
candidat ou juge particulier a besoin d’une dérogation. Passez `--fast` uniquement si vous souhaitez
forcer le mode rapide pour tous les modèles candidats. Les durées des candidats et des juges sont
enregistrées dans le rapport pour l’analyse comparative, mais les invites des juges indiquent explicitement de
ne pas classer selon la vitesse.
Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez
`--concurrency` ou `--judge-concurrency` lorsque les limites des fournisseurs ou la pression sur la Gateway locale
`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression sur la Gateway locale
rendent une exécution trop bruyante.
Lorsqu’aucun `--model` candidat n’est transmis, l’évaluation du caractère utilise par défaut
Lorsqu’aucun candidat `--model` n’est transmis, l’évaluation du caractère utilise par défaut
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5`, et

1318
docs/fr/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

535
docs/fr/gateway/doctor.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Ajouter ou modifier des migrations doctor
- Introduire des changements de configuration incompatibles
summary: 'Commande Doctor : vérifications d’état, migrations de configuration et étapes de réparation'
title: Doctor
- Introduire des modifications de configuration incompatibles
summary: 'Commande doctor : vérifications d’état, migrations de configuration et étapes de réparation'
title: Médecin
x-i18n:
generated_at: "2026-04-09T01:29:22Z"
generated_at: "2026-04-20T07:05:38Z"
model: gpt-5.4
provider: openai
source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce
source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b
source_path: gateway/doctor.md
workflow: 15
---
@ -16,7 +16,7 @@ x-i18n:
# Doctor
`openclaw doctor` est l’outil de réparation + migration pour OpenClaw. Il corrige les
configurations/états obsolètes, vérifie l’état du système et fournit des étapes de réparation exploitables.
configurations/états obsolètes, vérifie l’état de santé et fournit des étapes de réparation exploitables.
## Démarrage rapide
@ -24,19 +24,19 @@ configurations/états obsolètes, vérifie l’état du système et fournit des
openclaw doctor
```
### Sans interface / automatisation
### Mode headless / automatisation
```bash
openclaw doctor --yes
```
Accepte les valeurs par défaut sans demander de confirmation (y compris les étapes de réparation de redémarrage/service/sandbox lorsque c’est applicable).
Accepte les valeurs par défaut sans invite (y compris les étapes de réparation de redémarrage/service/sandbox lorsque cela s’applique).
```bash
openclaw doctor --repair
```
Applique les réparations recommandées sans demander de confirmation (réparations + redémarrages lorsque cela est sûr).
Applique les réparations recommandées sans invite (réparations + redémarrages lorsque c’est sûr).
```bash
openclaw doctor --repair --force
@ -48,7 +48,7 @@ Applique aussi les réparations agressives (écrase les configurations de superv
openclaw doctor --non-interactive
```
S’exécute sans invites et applique uniquement les migrations sûres (normalisation de la configuration + déplacements d’état sur disque). Ignore les actions de redémarrage/service/sandbox qui nécessitent une confirmation humaine.
S’exécute sans invites et applique uniquement les migrations sûres (normalisation de configuration + déplacements d’état sur disque). Ignore les actions de redémarrage/service/sandbox qui nécessitent une confirmation humaine.
Les migrations d’état héritées s’exécutent automatiquement lorsqu’elles sont détectées.
```bash
@ -57,126 +57,127 @@ openclaw doctor --deep
Analyse les services système pour détecter des installations Gateway supplémentaires (launchd/systemd/schtasks).
Si vous voulez examiner les modifications avant l’écriture, ouvrez d’abord le fichier de configuration :
Si vous voulez examiner les changements avant l’écriture, ouvrez d’abord le fichier de configuration :
```bash
cat ~/.openclaw/openclaw.json
```
## Ce que fait la commande (résumé)
## Ce qu’il fait (résumé)
- Mise à jour préalable facultative pour les installations git (interactif uniquement).
- Vérification de fraîcheur du protocole UI (reconstruit la Control UI lorsque le schéma de protocole est plus récent).
- Mise à jour préalable optionnelle pour les installations git (mode interactif uniquement).
- Vérification de fraîcheur du protocole UI (reconstruit l’interface de contrôle si le schéma du protocole est plus récent).
- Vérification d’état + invite de redémarrage.
- Résumé de l’état des Skills (éligibles/manquants/bloqués) et état des plugins.
- Résumé d’état des Skills (éligibles/manquantes/bloquées) et état des plugins.
- Normalisation de la configuration pour les valeurs héritées.
- Migration de la configuration Talk depuis les champs plats hérités `talk.*` vers `talk.provider` + `talk.providers.<provider>`.
- Vérifications de migration du navigateur pour les anciennes configurations d’extension Chrome et de préparation Chrome MCP.
- Migration de la configuration Talk des champs plats hérités `talk.*` vers `talk.provider` + `talk.providers.<provider>`.
- Vérifications de migration du navigateur pour les configurations héritées de l’extension Chrome et la préparation de Chrome MCP.
- Avertissements sur les remplacements de fournisseur OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Avertissements de masquage OAuth Codex (`models.providers.openai-codex`).
- Avertissements sur le masquage OAuth Codex (`models.providers.openai-codex`).
- Vérification des prérequis TLS OAuth pour les profils OAuth OpenAI Codex.
- Migration d’état héritée sur disque (sessions/répertoire d’agent/authentification WhatsApp).
- Migration des anciennes clés de contrat de manifeste de plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migration de l’ancien magasin cron (`jobId`, `schedule.cron`, champs delivery/payload de niveau supérieur, `provider` dans payload, tâches de secours webhook simples `notify: true`).
- Migration de l’état hérité sur disque (sessions/répertoire agent/authentification WhatsApp).
- Migration de clé de contrat de manifeste Plugin héritée (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migration héritée du stockage Cron (`jobId`, `schedule.cron`, champs delivery/payload de niveau supérieur, `provider` de payload, tâches de secours Webhook simples `notify: true`).
- Inspection des fichiers de verrouillage de session et nettoyage des verrous obsolètes.
- Vérifications d’intégrité et de permissions de l’état (sessions, transcriptions, répertoire d’état).
- Vérifications des permissions du fichier de configuration (`chmod 600`) lors d’une exécution en local.
- État de l’authentification des modèles : vérifie l’expiration OAuth, peut rafraîchir les jetons proches de l’expiration et signale les états de délai d’attente/désactivation des profils d’authentification.
- Détection de répertoires d’espace de travail supplémentaires (`~/openclaw`).
- État de l’authentification des modèles : vérifie l’expiration OAuth, peut actualiser les jetons proches de l’expiration et signale les états de cooldown/désactivation des profils d’authentification.
- Détection d’un répertoire de workspace supplémentaire (`~/openclaw`).
- Réparation de l’image sandbox lorsque le sandboxing est activé.
- Migration des anciens services et détection de passerelles supplémentaires.
- Migration de l’état hérité du canal Matrix (en mode `--fix` / `--repair`).
- Vérifications d’exécution Gateway (service installé mais non démarré ; libellé launchd mis en cache).
- Avertissements sur l’état des canaux (testés depuis la passerelle en cours d’exécution).
- Audit de la configuration du superviseur (launchd/systemd/schtasks) avec réparation facultative.
- Vérifications de bonnes pratiques d’exécution Gateway (Node vs Bun, chemins de gestionnaires de versions).
- Diagnostic de collision de port Gateway (par défaut `18789`).
- Migration de service héritée et détection de Gateway supplémentaires.
- Migration d’état hérité du canal Matrix (en mode `--fix` / `--repair`).
- Vérifications d’exécution Gateway (service installé mais non démarré ; étiquette launchd en cache).
- Avertissements d’état des canaux (testés à partir de la Gateway en cours d’exécution).
- Audit de configuration du superviseur (launchd/systemd/schtasks) avec réparation optionnelle.
- Vérifications des bonnes pratiques d’exécution Gateway (Node vs Bun, chemins du gestionnaire de versions).
- Diagnostics de collision de port Gateway (par défaut `18789`).
- Avertissements de sécurité pour les politiques DM ouvertes.
- Vérifications d’authentification Gateway pour le mode jeton local (propose la génération d’un jeton lorsqu’aucune source de jeton n’existe ; n’écrase pas les configurations `SecretRef` de jeton).
- Vérification de persistance systemd sur Linux.
- Vérification de la taille des fichiers bootstrap de l’espace de travail (avertissements de troncature/proximité de limite pour les fichiers de contexte).
- Vérification de l’état des complétions shell et installation/mise à niveau automatiques.
- Vérifications d’authentification Gateway pour le mode jeton local (propose une génération de jeton lorsqu’aucune source de jeton n’existe ; n’écrase pas les configurations SecretRef de jeton).
- Détection des problèmes d’appairage d’appareil (premières demandes d’appairage en attente, mises à niveau de rôle/scope en attente, dérive obsolète du cache local de jeton d’appareil et dérive d’authentification des enregistrements appairés).
- Vérification de linger systemd sous Linux.
- Vérification de la taille du fichier bootstrap du workspace (avertissements de troncature/proche de la limite pour les fichiers de contexte).
- Vérification de l’état des complétions shell et auto-installation/mise à niveau.
- Vérification de préparation du fournisseur d’embeddings pour la recherche mémoire (modèle local, clé API distante ou binaire QMD).
- Vérifications d’installation source (incohérence d’espace de travail pnpm, ressources UI manquantes, binaire tsx manquant).
- Vérifications des installations source (incohérence de workspace pnpm, ressources UI manquantes, binaire tsx manquant).
- Écrit la configuration mise à jour + les métadonnées de l’assistant.
## Dreams UI : backfill et réinitialisation
## Complétion et réinitialisation de l’interface Dreams
La scène Dreams de la Control UI inclut des actions **Backfill**, **Reset** et **Clear Grounded**
pour le flux de travail de grounded dreaming. Ces actions utilisent des
méthodes RPC de style doctor de la passerelle, mais elles ne font **pas** partie de la réparation/migration CLI
de `openclaw doctor`.
La scène Dreams de l’interface de contrôle inclut les actions **Backfill**, **Reset** et **Clear Grounded**
pour le flux de travail de Dreaming fondé. Ces actions utilisent des méthodes RPC
de type doctor de Gateway, mais elles ne font **pas** partie de la
réparation/migration de la CLI `openclaw doctor`.
Ce qu’elles font :
Ce qu’elles font :
- **Backfill** analyse les fichiers historiques `memory/YYYY-MM-DD.md` dans l’espace de travail
actif, exécute le passage de journal REM grounded et écrit des entrées de backfill réversibles
dans `DREAMS.md`.
- **Reset** supprime uniquement ces entrées de journal de backfill marquées de `DREAMS.md`.
- **Clear Grounded** supprime uniquement les entrées à court terme staged, grounded-only,
issues de la relecture historique et qui n’ont pas encore accumulé de rappel en direct ni
de support quotidien.
- **Backfill** analyse les fichiers historiques `memory/YYYY-MM-DD.md` dans le
workspace actif, exécute le passage grounded REM diary et écrit des entrées de
complétion réversibles dans `DREAMS.md`.
- **Reset** supprime uniquement ces entrées de journal de complétion marquées de `DREAMS.md`.
- **Clear Grounded** supprime uniquement les entrées à court terme provisoires, uniquement fondées,
issues d’une relecture historique et qui n’ont pas encore accumulé de rappel en direct
ni de support quotidien.
Ce qu’elles ne font **pas** à elles seules :
Ce qu’elles ne font **pas** à elles seules :
- elles ne modifient pas `MEMORY.md`
- elles n’exécutent pas les migrations doctor complètes
- elles ne placent pas automatiquement les candidats grounded dans le magasin de promotion
actif à court terme sauf si vous exécutez explicitement d’abord le chemin CLI staged
- elles ne mettent pas automatiquement en préparation les candidats fondés dans le stockage
vivant de promotion à court terme sauf si vous exécutez explicitement d’abord le chemin CLI en préparation
Si vous voulez que la relecture historique grounded influence la voie normale de promotion profonde,
utilisez plutôt le flux CLI :
Si vous voulez que la relecture historique fondée influence le flux normal de promotion profonde,
utilisez plutôt le flux CLI :
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Cela place des candidats durables grounded dans le magasin de dreaming à court terme tout en
conservant `DREAMS.md` comme surface de révision.
Cela met en préparation les candidats durables fondés dans le stockage Dreaming à court terme tout en
gardant `DREAMS.md` comme surface de révision.
## Comportement détaillé et justification
### 0) Mise à jour facultative (installations git)
### 0) Mise à jour optionnelle (installations git)
S’il s’agit d’un checkout git et que doctor s’exécute en mode interactif, il propose de
mettre à jour (fetch/rebase/build) avant d’exécuter doctor.
S’il s’agit d’un checkout git et que doctor s’exécute en mode interactif, il propose
de mettre à jour (fetch/rebase/build) avant d’exécuter doctor.
### 1) Normalisation de la configuration
Si la configuration contient des formes de valeurs héritées (par exemple `messages.ackReaction`
sans remplacement spécifique à un canal), doctor les normalise selon le schéma
actuel.
sans remplacement spécifique à un canal), doctor les normalise vers le
schéma actuel.
Cela inclut les champs plats Talk hérités. La configuration Talk publique actuelle est
Cela inclut les champs plats hérités de Talk. La configuration publique actuelle de Talk est
`talk.provider` + `talk.providers.<provider>`. Doctor réécrit les anciennes formes
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` dans la map des fournisseurs.
`talk.apiKey` dans la table des fournisseurs.
### 2) Migrations des clés de configuration héritées
### 2) Migrations de clés de configuration héritées
Lorsque la configuration contient des clés obsolètes, les autres commandes refusent de s’exécuter et demandent
d’exécuter `openclaw doctor`.
Doctor va :
Doctor va :
- Expliquer quelles clés héritées ont été trouvées.
- Afficher la migration qu’il a appliquée.
- Montrer la migration qu’il a appliquée.
- Réécrire `~/.openclaw/openclaw.json` avec le schéma mis à jour.
La Gateway exécute aussi automatiquement les migrations doctor au démarrage lorsqu’elle détecte un
format de configuration hérité, afin que les configurations obsolètes soient réparées sans intervention manuelle.
Les migrations du magasin de tâches cron sont gérées par `openclaw doctor --fix`.
La Gateway exécute également automatiquement les migrations doctor au démarrage lorsqu’elle détecte un
format de configuration hérité, de sorte que les configurations obsolètes sont réparées sans intervention manuelle.
Les migrations du stockage des tâches Cron sont gérées par `openclaw doctor --fix`.
Migrations actuelles :
Migrations actuelles :
- `routing.allowFrom` → `channels.whatsapp.allowFrom`
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` au niveau supérieur
- `routing.bindings` → `bindings` de niveau supérieur
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- ancien `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- héritage `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -189,361 +190,389 @@ Migrations actuelles :
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Pour les canaux avec des `accounts` nommés mais avec encore des valeurs de canal de niveau supérieur à compte unique, déplacer ces valeurs liées au compte dans le compte promu choisi pour ce canal (`accounts.default` pour la plupart des canaux ; Matrix peut conserver une cible nommée/par défaut existante correspondante)
- Pour les canaux avec des `accounts` nommés mais encore des valeurs de canal de niveau supérieur en mode compte unique, déplacer ces valeurs liées au compte dans le compte promu choisi pour ce canal (`accounts.default` pour la plupart des canaux ; Matrix peut conserver une cible nommée/par défaut correspondante existante)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- supprimer `browser.relayBindHost` (ancien paramètre de relais d’extension)
- supprimer `browser.relayBindHost` (paramètre hérité du relais d’extension)
Les avertissements doctor incluent aussi des recommandations sur les comptes par défaut pour les canaux multi-comptes :
Les avertissements doctor incluent aussi des conseils sur le compte par défaut pour les canaux multi-comptes :
- Si deux entrées ou plus sont configurées dans `channels.<channel>.accounts` sans `channels.<channel>.defaultAccount` ni `accounts.default`, doctor avertit que le routage de secours peut choisir un compte inattendu.
- Si `channels.<channel>.defaultAccount` est défini sur un identifiant de compte inconnu, doctor avertit et liste les identifiants de compte configurés.
- Si `channels.<channel>.defaultAccount` est défini sur un ID de compte inconnu, doctor avertit et liste les ID de compte configurés.
### 2b) Remplacements de fournisseur OpenCode
Si vous avez ajouté `models.providers.opencode`, `opencode-zen` ou `opencode-go`
manuellement, cela remplace le catalogue OpenCode intégré issu de `@mariozechner/pi-ai`.
Cela peut forcer des modèles vers la mauvaise API ou remettre les coûts à zéro. Doctor avertit afin que vous
puissiez supprimer ce remplacement et restaurer le routage API + les coûts par modèle.
Si vous avez ajouté manuellement `models.providers.opencode`, `opencode-zen` ou `opencode-go`,
cela remplace le catalogue OpenCode intégré de `@mariozechner/pi-ai`.
Cela peut forcer les modèles à utiliser la mauvaise API ou remettre les coûts à zéro. Doctor avertit afin que vous
puissiez supprimer ce remplacement et restaurer le routage API par modèle + les coûts.
### 2c) Migration du navigateur et préparation Chrome MCP
### 2c) Migration du navigateur et préparation de Chrome MCP
Si la configuration de votre navigateur pointe encore vers le chemin supprimé de l’extension Chrome, doctor
la normalise vers le modèle d’attachement Chrome MCP local à l’hôte actuel :
Si votre configuration de navigateur pointe encore vers le chemin supprimé de l’extension Chrome, doctor
la normalise vers le modèle actuel d’attachement Chrome MCP local à l’hôte :
- `browser.profiles.*.driver: "extension"` devient `"existing-session"`
- `browser.relayBindHost` est supprimé
Doctor audite aussi le chemin Chrome MCP local à l’hôte lorsque vous utilisez `defaultProfile:
"user"` ou un profil `existing-session` configuré :
Doctor audite également le chemin Chrome MCP local à l’hôte lorsque vous utilisez `defaultProfile:
"user"` ou un profil `existing-session` configuré :
- vérifie si Google Chrome est installé sur le même hôte pour les profils
d’auto-connexion par défaut
- vérifie la version Chrome détectée et avertit lorsqu’elle est inférieure à Chrome 144
- rappelle d’activer le débogage distant dans la page inspect du navigateur (par
- vérifie si Google Chrome est installé sur le même hôte pour les profils de
connexion automatique par défaut
- vérifie la version détectée de Chrome et avertit lorsqu’elle est inférieure à Chrome 144
- rappelle d’activer le débogage à distance dans la page d’inspection du navigateur (par
exemple `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
ou `edge://inspect/#remote-debugging`)
Doctor ne peut pas activer ce paramètre côté Chrome à votre place. Le Chrome MCP local à l’hôte
requiert toujours :
requiert toujours :
- un navigateur basé sur Chromium 144+ sur l’hôte gateway/node
- l’exécution locale du navigateur
- le débogage distant activé dans ce navigateur
- un navigateur basé sur Chromium 144+ sur l’hôte Gateway/Node
- le navigateur exécuté localement
- le débogage à distance activé dans ce navigateur
- l’approbation de la première invite de consentement d’attachement dans le navigateur
La préparation ici concerne uniquement les prérequis d’attachement local. Existing-session conserve
les limites actuelles des routes Chrome MCP ; les routes avancées comme `responsebody`, l’export PDF,
l’interception des téléchargements et les actions par lots requièrent toujours un
les limites de routage actuelles de Chrome MCP ; des routes avancées comme `responsebody`, l’export PDF,
l’interception des téléchargements et les actions par lot nécessitent toujours un
navigateur géré ou un profil CDP brut.
Cette vérification ne s’applique **pas** à Docker, sandbox, remote-browser ni aux autres
flux headless. Ceux-ci continuent d’utiliser CDP brut.
Cette vérification ne s’applique **pas** à Docker, au sandbox, au navigateur distant ni aux autres
flux headless. Ceux-ci continuent d’utiliser du CDP brut.
### 2d) Prérequis TLS OAuth
Lorsqu’un profil OAuth OpenAI Codex est configuré, doctor sonde le point de terminaison d’autorisation OpenAI
pour vérifier que la pile TLS locale Node/OpenSSL peut
Lorsqu’un profil OAuth OpenAI Codex est configuré, doctor sonde le point de terminaison
d’autorisation OpenAI pour vérifier que la pile TLS locale Node/OpenSSL peut
valider la chaîne de certificats. Si la sonde échoue avec une erreur de certificat (par
exemple `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificat expiré ou certificat autosigné),
doctor affiche des indications de correction spécifiques à la plateforme. Sur macOS avec un Node Homebrew, la
doctor affiche des conseils de correction spécifiques à la plateforme. Sur macOS avec un Node Homebrew, la
correction est généralement `brew postinstall ca-certificates`. Avec `--deep`, la sonde s’exécute
même si la passerelle est saine.
même si la Gateway est en bon état.
### 2c) Remplacements de fournisseur OAuth Codex
Si vous avez précédemment ajouté d’anciens paramètres de transport OpenAI sous
`models.providers.openai-codex`, ils peuvent masquer le chemin de fournisseur
OAuth Codex intégré que les versions récentes utilisent automatiquement. Doctor avertit lorsqu’il voit
ces anciens paramètres de transport en même temps que Codex OAuth afin que vous puissiez supprimer ou réécrire
le remplacement de transport obsolète et retrouver le comportement intégré de routage/secours.
Les proxies personnalisés et les remplacements uniquement par en-têtes restent pris en charge et ne
Si vous avez précédemment ajouté des paramètres hérités de transport OpenAI sous
`models.providers.openai-codex`, ils peuvent masquer le chemin du fournisseur
OAuth Codex intégré que les versions plus récentes utilisent automatiquement. Doctor avertit lorsqu’il voit
ces anciens paramètres de transport en même temps que Codex OAuth afin que vous puissiez supprimer
ou réécrire le remplacement de transport obsolète et retrouver le comportement
intégré de routage/secours. Les proxys personnalisés et les remplacements limités aux en-têtes restent pris en charge et ne
déclenchent pas cet avertissement.
### 3) Migrations d’état héritées (organisation sur disque)
### 3) Migrations d’état héritées (disposition sur disque)
Doctor peut migrer d’anciennes organisations sur disque vers la structure actuelle :
Doctor peut migrer d’anciennes dispositions sur disque vers la structure actuelle :
- Magasin de sessions + transcriptions :
- Stockage des sessions + transcriptions :
- de `~/.openclaw/sessions/` vers `~/.openclaw/agents/<agentId>/sessions/`
- Répertoire d’agent :
- Répertoire agent :
- de `~/.openclaw/agent/` vers `~/.openclaw/agents/<agentId>/agent/`
- État d’authentification WhatsApp (Baileys) :
- depuis les anciens `~/.openclaw/credentials/*.json` (sauf `oauth.json`)
- vers `~/.openclaw/credentials/whatsapp/<accountId>/...` (identifiant de compte par défaut : `default`)
- État d’authentification WhatsApp (Baileys) :
- de l’héritage `~/.openclaw/credentials/*.json` (sauf `oauth.json`)
- vers `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID de compte par défaut : `default`)
Ces migrations sont réalisées au mieux et sont idempotentes ; doctor émet des avertissements lorsqu’il
Ces migrations sont en mode meilleur effort et idempotentes ; doctor émettra des avertissements lorsqu’il
laisse des dossiers hérités en place comme sauvegardes. La Gateway/CLI migre aussi automatiquement
au démarrage les anciennes sessions + le répertoire d’agent afin que l’historique/l’authentification/les modèles aboutissent dans le chemin
par agent sans exécution manuelle de doctor. L’authentification WhatsApp est volontairement migrée uniquement
via `openclaw doctor`. La normalisation du fournisseur Talk/de la map de fournisseurs compare désormais
par égalité structurelle ; ainsi, les différences d’ordre des clés ne déclenchent plus de
modifications répétées et sans effet avec `doctor --fix`.
les sessions héritées + le répertoire agent au démarrage afin que l’historique/l’authentification/les modèles aboutissent dans le
chemin par agent sans exécution manuelle de doctor. L’authentification WhatsApp est intentionnellement
migrée uniquement via `openclaw doctor`. La normalisation du fournisseur/de la table des fournisseurs Talk
compare désormais selon l’égalité structurelle, donc les différences de seul ordre des clés ne déclenchent plus
de changements no-op répétés de `doctor --fix`.
### 3a) Migrations héritées de manifeste de plugin
### 3a) Migrations héritées de manifeste Plugin
Doctor analyse tous les manifestes de plugins installés pour détecter les clés de capacité de niveau supérieur
obsolètes (`speechProviders`, `realtimeTranscriptionProviders`,
Doctor analyse tous les manifestes de plugins installés à la recherche de clés de capacité
obsolètes de niveau supérieur (`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). Lorsqu’elles sont trouvées, il propose de les déplacer dans l’objet `contracts`
et de réécrire le fichier manifeste en place. Cette migration est idempotente ;
et de réécrire le fichier manifeste sur place. Cette migration est idempotente ;
si la clé `contracts` contient déjà les mêmes valeurs, la clé héritée est supprimée
sans dupliquer les données.
### 3b) Migrations héritées du magasin cron
### 3b) Migrations héritées du stockage Cron
Doctor vérifie aussi le magasin de tâches cron (`~/.openclaw/cron/jobs.json` par défaut,
ou `cron.store` en cas de remplacement) pour détecter d’anciennes formes de tâches que l’ordonnanceur accepte encore
pour compatibilité.
Doctor vérifie également le stockage des tâches Cron (`~/.openclaw/cron/jobs.json` par défaut,
ou `cron.store` si remplacé) à la recherche d’anciennes formes de tâches que le planificateur
accepte encore pour compatibilité.
Nettoyages cron actuels :
Les nettoyages Cron actuels incluent :
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- champs payload de niveau supérieur (`message`, `model`, `thinking`, ...) → `payload`
- champs delivery de niveau supérieur (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- alias de delivery `provider` dans payload → `delivery.channel` explicite
- tâches de secours webhook héritées simples `notify: true` → `delivery.mode="webhook"` explicite avec `delivery.to=cron.webhook`
- tâches de secours Webhook héritées simples `notify: true` → `delivery.mode="webhook"` explicite avec `delivery.to=cron.webhook`
Doctor ne migre automatiquement les tâches `notify: true` que lorsqu’il peut le faire sans
modifier le comportement. Si une tâche combine le secours notify hérité avec un mode de
delivery existant non-webhook, doctor avertit et laisse cette tâche pour révision manuelle.
changer le comportement. Si une tâche combine un secours notify hérité avec un mode
delivery non-Webhook existant, doctor avertit et laisse cette tâche pour révision manuelle.
### 3c) Nettoyage des verrous de session
Doctor analyse chaque répertoire de session d’agent à la recherche de fichiers de verrouillage d’écriture obsolètes — des fichiers laissés
derrière lorsqu’une session s’est terminée anormalement. Pour chaque fichier de verrouillage trouvé, il signale :
Doctor analyse chaque répertoire de session d’agent à la recherche de fichiers de verrouillage d’écriture obsolètes — fichiers laissés
derrière lorsqu’une session s’est terminée anormalement. Pour chaque fichier de verrouillage trouvé, il signale :
le chemin, le PID, si le PID est encore actif, l’âge du verrou et s’il est
considéré comme obsolète (PID mort ou plus ancien que 30 minutes). En mode `--fix` / `--repair`,
il supprime automatiquement les fichiers de verrouillage obsolètes ; sinon, il affiche une note et
considéré comme obsolète (PID mort ou plus de 30 minutes). En mode `--fix` / `--repair`,
il supprime automatiquement les fichiers de verrouillage obsolètes ; sinon il affiche une note et
vous demande de relancer avec `--fix`.
### 4) Vérifications d’intégrité de l’état (persistance des sessions, routage et sécurité)
Le répertoire d’état est le tronc cérébral opérationnel. S’il disparaît, vous perdez
les sessions, les identifiants, les journaux et la configuration (sauf si vous avez des sauvegardes ailleurs).
les sessions, identifiants, journaux et la configuration (sauf si vous avez des sauvegardes ailleurs).
Doctor vérifie :
Doctor vérifie :
- **Répertoire d’état manquant** : avertit d’une perte d’état catastrophique, propose de recréer
- **Répertoire d’état manquant** : avertit d’une perte d’état catastrophique, propose de recréer
le répertoire et rappelle qu’il ne peut pas récupérer les données manquantes.
- **Permissions du répertoire d’état** : vérifie l’inscriptibilité ; propose de réparer les permissions
(et affiche une indication `chown` lorsqu’une incohérence propriétaire/groupe est détectée).
- **Répertoire d’état macOS synchronisé par le cloud** : avertit lorsque l’état se résout sous iCloud Drive
- **Permissions du répertoire d’état** : vérifie l’écriture ; propose de réparer les permissions
(et affiche une indication `chown` lorsqu’une discordance propriétaire/groupe est détectée).
- **Répertoire d’état macOS synchronisé dans le cloud** : avertit lorsque l’état se résout sous iCloud Drive
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou
`~/Library/CloudStorage/...` car les chemins adossés à la synchronisation peuvent causer des E/S plus lentes
`~/Library/CloudStorage/...` parce que les chemins adossés à la synchronisation peuvent provoquer des E/S plus lentes
et des courses de verrouillage/synchronisation.
- **Répertoire d’état Linux sur SD ou eMMC** : avertit lorsque l’état se résout vers une source de montage `mmcblk*`,
car les E/S aléatoires adossées à une carte SD ou à eMMC peuvent être plus lentes et s’user
plus vite sous les écritures de session et d’identifiants.
- **Répertoires de session manquants** : `sessions/` et le répertoire de stockage des sessions sont
requis pour persister l’historique et éviter les plantages `ENOENT`.
- **Incohérence de transcription** : avertit lorsque des entrées de session récentes ont des
- **Répertoire d’état Linux sur SD ou eMMC** : avertit lorsque l’état se résout vers une source de montage `mmcblk*`,
car les E/S aléatoires sur SD ou eMMC peuvent être plus lentes et user
plus vite avec les écritures de sessions et d’identifiants.
- **Répertoires de session manquants** : `sessions/` et le répertoire de stockage des sessions sont
nécessaires pour persister l’historique et éviter les crashs `ENOENT`.
- **Incohérence de transcription** : avertit lorsque des entrées de session récentes ont des
fichiers de transcription manquants.
- **Session principale “JSONL sur 1 ligne”** : signale lorsque la transcription principale n’a qu’une seule
ligne (l’historique ne s’accumule pas).
- **Répertoires d’état multiples** : avertit lorsque plusieurs dossiers `~/.openclaw` existent entre
des répertoires personnels ou lorsque `OPENCLAW_STATE_DIR` pointe ailleurs (l’historique peut
se fragmenter entre les installations).
- **Rappel du mode distant** : si `gateway.mode=remote`, doctor rappelle de l’exécuter
sur l’hôte distant (l’état s’y trouve).
- **Permissions du fichier de configuration** : avertit si `~/.openclaw/openclaw.json` est
lisible par le groupe ou le monde et propose de le restreindre à `600`.
- **Session principale « JSONL sur 1 ligne »** : signale lorsque la transcription principale n’a qu’une
seule ligne (l’historique ne s’accumule pas).
- **Multiples répertoires d’état** : avertit lorsque plusieurs dossiers `~/.openclaw` existent entre
différents répertoires personnels ou lorsque `OPENCLAW_STATE_DIR` pointe ailleurs (l’historique peut
se répartir entre plusieurs installations).
- **Rappel mode distant** : si `gateway.mode=remote`, doctor rappelle de l’exécuter
sur l’hôte distant (l’état y réside).
- **Permissions du fichier de configuration** : avertit si `~/.openclaw/openclaw.json` est
lisible par le groupe/le monde et propose de le restreindre à `600`.
### 5) État de l’authentification des modèles (expiration OAuth)
Doctor inspecte les profils OAuth dans le magasin d’authentification, avertit lorsque les jetons sont
proches de l’expiration ou expirés, et peut les rafraîchir lorsque c’est sûr. Si le profil
Doctor inspecte les profils OAuth dans le magasin d’authentification, avertit lorsque les jetons
expirent ou ont expiré et peut les actualiser lorsque c’est sûr. Si le profil
OAuth/jeton Anthropic est obsolète, il suggère une clé API Anthropic ou le
chemin de setup-token Anthropic.
Les invites de rafraîchissement n’apparaissent qu’en mode interactif (TTY) ; `--non-interactive`
ignore les tentatives de rafraîchissement.
chemin setup-token Anthropic.
Les invites d’actualisation n’apparaissent qu’en mode interactif (TTY) ; `--non-interactive`
ignore les tentatives d’actualisation.
Lorsqu’un rafraîchissement OAuth échoue de manière permanente (par exemple `refresh_token_reused`,
`invalid_grant`, ou lorsqu’un fournisseur vous indique de vous reconnecter), doctor signale
Lorsqu’une actualisation OAuth échoue de manière permanente (par exemple `refresh_token_reused`,
`invalid_grant`, ou lorsqu’un fournisseur vous dit de vous reconnecter), doctor signale
qu’une réauthentification est requise et affiche la commande exacte `openclaw models auth login --provider ...`
à exécuter.
Doctor signale aussi les profils d’authentification temporairement inutilisables à cause de :
Doctor signale aussi les profils d’authentification temporairement inutilisables à cause de :
- courts délais d’attente (limites de débit/timeouts/échecs d’authentification)
- courtes périodes de cooldown (limites de débit/timeouts/échecs d’authentification)
- désactivations plus longues (échecs de facturation/crédit)
### 6) Validation du modèle Hooks
Si `hooks.gmail.model` est défini, doctor valide la référence de modèle par rapport au
catalogue et à la liste d’autorisation et avertit lorsqu’elle ne se résout pas ou n’est pas autorisée.
catalogue et à la liste d’autorisation et avertit lorsqu’elle ne se résoudra pas ou n’est pas autorisée.
### 7) Réparation de l’image sandbox
Lorsque le sandboxing est activé, doctor vérifie les images Docker et propose de construire ou
de basculer vers d’anciens noms si l’image actuelle est absente.
Lorsque le sandboxing est activé, doctor vérifie les images Docker et propose de les construire ou
de basculer vers les noms hérités si l’image actuelle est manquante.
### 7b) Dépendances d’exécution des plugins intégrés
Doctor vérifie que les dépendances d’exécution des plugins intégrés (par exemple les
packages d’exécution du plugin Discord) sont présentes dans la racine d’installation OpenClaw.
Si certaines sont manquantes, doctor signale les packages et les installe en
mode `openclaw doctor --fix` / `openclaw doctor --repair`.
packages d’exécution du plugin Discord) sont présentes à la racine d’installation d’OpenClaw.
S’il en manque, doctor signale les packages et les installe en mode
`openclaw doctor --fix` / `openclaw doctor --repair`.
### 8) Migrations des services Gateway et indications de nettoyage
Doctor détecte les anciens services Gateway (launchd/systemd/schtasks) et
propose de les supprimer puis d’installer le service OpenClaw avec le port de passerelle
actuel. Il peut aussi rechercher des services supplémentaires de type passerelle et afficher des indications de nettoyage.
Les services de passerelle OpenClaw nommés par profil sont considérés comme de première classe et ne sont pas
signalés comme « supplémentaires ».
Doctor détecte les services Gateway hérités (launchd/systemd/schtasks) et
propose de les supprimer et d’installer le service OpenClaw en utilisant le port Gateway
actuel. Il peut également analyser les services supplémentaires de type Gateway et afficher des indications de nettoyage.
Les services Gateway OpenClaw nommés par profil sont considérés comme de première classe et ne sont pas
signalés comme « supplémentaires ».
### 8b) Migration Matrix au démarrage
Lorsqu’un compte de canal Matrix a une migration d’état héritée en attente ou exploitable,
doctor (en mode `--fix` / `--repair`) crée un instantané avant migration puis
exécute les étapes de migration au mieux : migration de l’état Matrix hérité et préparation héritée
de l’état chiffré. Les deux étapes ne sont pas fatales ; les erreurs sont journalisées et
le démarrage se poursuit. En mode lecture seule (`openclaw doctor` sans `--fix`), cette vérification
exécute les étapes de migration en mode meilleur effort : migration de l’état Matrix hérité et préparation héritée
de l’état chiffré. Les deux étapes sont non fatales ; les erreurs sont journalisées et
le démarrage continue. En mode lecture seule (`openclaw doctor` sans `--fix`), cette vérification
est entièrement ignorée.
### 8c) Dérive d’appairage d’appareil et d’authentification
Doctor inspecte désormais l’état d’appairage des appareils dans le cadre du passage normal de vérification d’état.
Ce qu’il signale :
- premières demandes d’appairage en attente
- mises à niveau de rôle en attente pour des appareils déjà appairés
- mises à niveau de scope en attente pour des appareils déjà appairés
- réparations de discordance de clé publique lorsque l’ID d’appareil correspond toujours mais que l’identité
de l’appareil ne correspond plus à l’enregistrement approuvé
- enregistrements appairés sans jeton actif pour un rôle approuvé
- jetons appairés dont les scopes dérivent hors de la base de référence d’appairage approuvée
- entrées locales en cache de jeton d’appareil pour la machine actuelle qui sont antérieures à une
rotation de jeton côté Gateway ou portent des métadonnées de scope obsolètes
Doctor n’approuve pas automatiquement les demandes d’appairage et ne fait pas non plus pivoter automatiquement les jetons d’appareil. Il
affiche à la place les étapes suivantes exactes :
- inspecter les demandes en attente avec `openclaw devices list`
- approuver la demande exacte avec `openclaw devices approve <requestId>`
- faire pivoter un nouveau jeton avec `openclaw devices rotate --device <deviceId> --role <role>`
- supprimer et réapprouver un enregistrement obsolète avec `openclaw devices remove <deviceId>`
Cela ferme le cas courant « déjà appairé mais reçoit toujours pairing required » :
doctor distingue désormais le premier appairage des mises à niveau de rôle/scope
en attente et de la dérive d’identité d’appareil/jeton obsolète.
### 9) Avertissements de sécurité
Doctor émet des avertissements lorsqu’un fournisseur est ouvert aux DM sans liste d’autorisation, ou
lorsqu’une politique est configurée de manière dangereuse.
lorsqu’une politique est configurée d’une manière dangereuse.
### 10) Persistance systemd (Linux)
### 10) systemd linger (Linux)
En cas d’exécution comme service utilisateur systemd, doctor s’assure que la persistance est activée afin que la
passerelle reste active après la déconnexion.
En cas d’exécution comme service utilisateur systemd, doctor s’assure que le mode lingering est activé afin que la
Gateway reste active après la déconnexion.
### 11) État de l’espace de travail (Skills, plugins et répertoires hérités)
### 11) État du workspace (Skills, plugins et répertoires hérités)
Doctor affiche un résumé de l’état de l’espace de travail pour l’agent par défaut :
Doctor affiche un résumé de l’état du workspace pour l’agent par défaut :
- **État des Skills** : compte les Skills éligibles, à prérequis manquants et bloqués par la liste d’autorisation.
- **Répertoires d’espace de travail hérités** : avertit lorsque `~/openclaw` ou d’autres anciens répertoires d’espace de travail
existent à côté de l’espace de travail actuel.
- **État des plugins** : compte les plugins chargés/désactivés/en erreur ; liste les identifiants de plugin pour les
erreurs ; signale les capacités des plugins bundle.
- **Avertissements de compatibilité de plugins** : signale les plugins qui ont des problèmes de compatibilité avec
- **État des Skills** : compte les Skills éligibles, à exigences manquantes et bloquées par la liste d’autorisation.
- **Répertoires de workspace hérités** : avertit lorsque `~/openclaw` ou d’autres répertoires de workspace hérités
existent à côté du workspace actuel.
- **État des plugins** : compte les plugins chargés/désactivés/en erreur ; liste les ID des plugins pour les
erreurs ; signale les capacités des plugins intégrés.
- **Avertissements de compatibilité des plugins** : signale les plugins ayant des problèmes de compatibilité avec
l’exécution actuelle.
- **Diagnostics des plugins** : met en avant tous les avertissements ou erreurs de chargement émis par le
registre des plugins.
- **Diagnostics des plugins** : expose les avertissements ou erreurs au chargement émis par le
registre de plugins.
### 11b) Taille du fichier bootstrap
Doctor vérifie si les fichiers bootstrap de l’espace de travail (par exemple `AGENTS.md`,
`CLAUDE.md` ou d’autres fichiers de contexte injectés) sont proches ou au-delà du budget
de caractères configuré. Il signale, fichier par fichier, le nombre brut de caractères vs. injectés, le pourcentage
de troncature, la cause de la troncature (`max/file` ou `max/total`) et le total des caractères injectés
en fraction du budget total. Lorsque des fichiers sont tronqués ou proches de la limite, doctor affiche des conseils pour ajuster `agents.defaults.bootstrapMaxChars`
Doctor vérifie si les fichiers bootstrap du workspace (par exemple `AGENTS.md`,
`CLAUDE.md` ou d’autres fichiers de contexte injectés) sont proches ou au-dessus du
budget de caractères configuré. Il signale, par fichier, le nombre brut de caractères par rapport au nombre injecté, le
pourcentage de troncature, la cause de la troncature (`max/file` ou `max/total`) et le total des
caractères injectés en fraction du budget total. Lorsque des fichiers sont tronqués ou proches
de la limite, doctor affiche des conseils pour ajuster `agents.defaults.bootstrapMaxChars`
et `agents.defaults.bootstrapTotalMaxChars`.
### 11c) Complétion shell
Doctor vérifie si la complétion par tabulation est installée pour le shell actuel
(zsh, bash, fish ou PowerShell) :
(zsh, bash, fish ou PowerShell) :
- Si le profil shell utilise un modèle de complétion dynamique lent
(`source <(openclaw completion ...)`), doctor le met à niveau vers la variante
plus rapide par fichier en cache.
- Si le profil shell utilise un modèle lent de complétion dynamique
(`source <(openclaw completion ...)`), doctor le met à niveau vers la
variante plus rapide avec fichier en cache.
- Si la complétion est configurée dans le profil mais que le fichier de cache est manquant,
doctor régénère automatiquement le cache.
- Si aucune complétion n’est configurée, doctor propose de l’installer
(mode interactif uniquement ; ignoré avec `--non-interactive`).
(mode interactif uniquement ; ignoré avec `--non-interactive`).
Exécutez `openclaw completion --write-state` pour régénérer le cache manuellement.
Exécutez `openclaw completion --write-state` pour régénérer manuellement le cache.
### 12) Vérifications d’authentification Gateway (jeton local)
Doctor vérifie l’état de préparation de l’authentification par jeton de la passerelle locale.
Doctor vérifie la préparation de l’authentification par jeton de la Gateway locale.
- Si le mode jeton nécessite un jeton et qu’aucune source de jeton n’existe, doctor propose d’en générer un.
- Si `gateway.auth.token` est géré par `SecretRef` mais indisponible, doctor avertit et ne l’écrase pas avec du texte brut.
- `openclaw doctor --generate-gateway-token` force la génération uniquement lorsqu’aucun `SecretRef` de jeton n’est configuré.
- Si le mode jeton a besoin d’un jeton et qu’aucune source de jeton n’existe, doctor propose d’en générer un.
- Si `gateway.auth.token` est géré par SecretRef mais indisponible, doctor avertit et ne l’écrase pas avec du texte brut.
- `openclaw doctor --generate-gateway-token` force la génération uniquement lorsqu’aucun SecretRef de jeton n’est configuré.
### 12b) Réparations en lecture seule conscientes de SecretRef
### 12b) Réparations en lecture seule compatibles SecretRef
Certains flux de réparation doivent inspecter les identifiants configurés sans affaiblir le comportement fail-fast à l’exécution.
Certains flux de réparation doivent inspecter les identifiants configurés sans affaiblir le comportement d’échec rapide à l’exécution.
- `openclaw doctor --fix` utilise désormais le même modèle de résumé `SecretRef` en lecture seule que les commandes de la famille status pour les réparations ciblées de configuration.
- Exemple : la réparation Telegram `allowFrom` / `groupAllowFrom` avec `@username` essaie d’utiliser les identifiants du bot configurés lorsqu’ils sont disponibles.
- Si le jeton du bot Telegram est configuré via `SecretRef` mais indisponible dans le chemin de commande actuel, doctor signale que l’identifiant est configuré mais indisponible et ignore la résolution automatique au lieu de planter ou d’indiquer à tort que le jeton est manquant.
- `openclaw doctor --fix` utilise désormais le même modèle récapitulatif SecretRef en lecture seule que les commandes de la famille status pour les réparations ciblées de configuration.
- Exemple : la réparation Telegram `allowFrom` / `groupAllowFrom` `@username` essaie d’utiliser les identifiants du bot configurés lorsqu’ils sont disponibles.
- Si le jeton du bot Telegram est configuré via SecretRef mais indisponible dans le chemin de commande actuel, doctor signale que l’identifiant est configuré-mais-indisponible et ignore la résolution automatique au lieu de planter ou de signaler à tort que le jeton est manquant.
### 13) Vérification d’état Gateway + redémarrage
Doctor exécute une vérification d’état et propose de redémarrer la passerelle lorsqu’elle semble
défaillante.
Doctor exécute une vérification d’état et propose de redémarrer la Gateway lorsqu’elle semble
en mauvais état.
### 13b) Préparation de la recherche mémoire
Doctor vérifie si le fournisseur d’embeddings configuré pour la recherche mémoire est prêt
pour l’agent par défaut. Le comportement dépend du backend et du fournisseur configurés :
pour l’agent par défaut. Le comportement dépend du backend et du fournisseur configurés :
- **Backend QMD** : vérifie si le binaire `qmd` est disponible et peut démarrer.
Sinon, affiche des indications de correction, y compris le package npm et une option de chemin binaire manuel.
- **Fournisseur local explicite** : vérifie la présence d’un fichier de modèle local ou d’une URL de modèle distante/téléchargeable reconnue. S’il manque, suggère de passer à un fournisseur distant.
- **Fournisseur distant explicite** (`openai`, `voyage`, etc.) : vérifie qu’une clé API est
présente dans l’environnement ou dans le magasin d’authentification. Affiche des indications de correction exploitables si elle manque.
- **Fournisseur automatique** : vérifie d’abord la disponibilité du modèle local, puis essaie chaque
fournisseur distant dans l’ordre de sélection automatique.
- **Backend QMD** : sonde si le binaire `qmd` est disponible et peut être démarré.
Sinon, affiche des conseils de correction, y compris le package npm et une option manuelle de chemin du binaire.
- **Fournisseur local explicite** : vérifie la présence d’un fichier de modèle local ou d’une URL de modèle distante/téléchargeable reconnue. Si absent, suggère de basculer vers un fournisseur distant.
- **Fournisseur distant explicite** (`openai`, `voyage`, etc.) : vérifie qu’une clé API est
présente dans l’environnement ou le magasin d’authentification. Affiche des indications de correction exploitables si elle est absente.
- **Fournisseur auto** : vérifie d’abord la disponibilité d’un modèle local, puis essaie chaque fournisseur distant dans l’ordre de sélection automatique.
Lorsqu’un résultat de sonde de passerelle est disponible (la passerelle était saine au moment de la
vérification), doctor le recoupe avec la configuration visible côté CLI et note
Lorsqu’un résultat de sonde Gateway est disponible (la Gateway était en bon état au moment de la
vérification), doctor le recoupe avec la configuration visible par la CLI et signale
toute divergence.
Utilisez `openclaw memory status --deep` pour vérifier la préparation des embeddings à l’exécution.
### 14) Avertissements sur l’état des canaux
### 14) Avertissements d’état des canaux
Si la passerelle est saine, doctor exécute une sonde d’état des canaux et signale
Si la Gateway est en bon état, doctor exécute une sonde d’état des canaux et signale
les avertissements avec des corrections suggérées.
### 15) Audit de configuration du superviseur + réparation
### 15) Audit + réparation de la configuration du superviseur
Doctor vérifie la configuration de superviseur installée (launchd/systemd/schtasks) pour détecter
les valeurs par défaut manquantes ou obsolètes (par ex. dépendances systemd network-online et
délai de redémarrage). Lorsqu’il détecte une incohérence, il recommande une mise à jour et peut
réécrire le fichier service/tâche selon les valeurs par défaut actuelles.
Doctor vérifie la configuration installée du superviseur (launchd/systemd/schtasks) pour détecter
des valeurs par défaut manquantes ou obsolètes (par ex. dépendances systemd network-online et
délai de redémarrage). Lorsqu’il trouve une différence, il recommande une mise à jour et peut
réécrire le fichier de service/la tâche vers les valeurs par défaut actuelles.
Remarques :
Remarques :
- `openclaw doctor` demande une confirmation avant de réécrire la configuration du superviseur.
- `openclaw doctor` demande confirmation avant de réécrire la configuration du superviseur.
- `openclaw doctor --yes` accepte les invites de réparation par défaut.
- `openclaw doctor --repair` applique les corrections recommandées sans invite.
- `openclaw doctor --repair` applique les corrections recommandées sans invites.
- `openclaw doctor --repair --force` écrase les configurations de superviseur personnalisées.
- Si l’authentification par jeton exige un jeton et que `gateway.auth.token` est géré par `SecretRef`, la validation d’installation/réparation du service vérifie le `SecretRef` mais ne persiste pas les valeurs de jeton en texte brut résolues dans les métadonnées d’environnement du service superviseur.
- Si l’authentification par jeton exige un jeton et que le `SecretRef` de jeton configuré n’est pas résolu, doctor bloque le chemin d’installation/réparation avec des indications exploitables.
- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés et que `gateway.auth.mode` n’est pas défini, doctor bloque l’installation/réparation jusqu’à ce que le mode soit explicitement défini.
- Pour les unités user-systemd Linux, les vérifications d’écart de jeton de doctor incluent désormais à la fois les sources `Environment=` et `EnvironmentFile=` lors de la comparaison des métadonnées d’authentification du service.
- Si l’authentification par jeton exige un jeton et que `gateway.auth.token` est géré par SecretRef, la voie d’installation/réparation du service doctor valide le SecretRef mais ne persiste pas les valeurs résolues de jeton en texte brut dans les métadonnées d’environnement du service superviseur.
- Si l’authentification par jeton exige un jeton et que le SecretRef de jeton configuré n’est pas résolu, doctor bloque la voie d’installation/réparation avec des conseils exploitables.
- Si `gateway.auth.token` et `gateway.auth.password` sont tous deux configurés et que `gateway.auth.mode` n’est pas défini, doctor bloque l’installation/réparation jusqu’à ce que le mode soit défini explicitement.
- Pour les unités user-systemd Linux, les vérifications de dérive de jeton doctor incluent désormais à la fois les sources `Environment=` et `EnvironmentFile=` lors de la comparaison des métadonnées d’authentification du service.
- Vous pouvez toujours forcer une réécriture complète via `openclaw gateway install --force`.
### 16) Diagnostics d’exécution Gateway + port
### 16) Diagnostics d’exécution Gateway + de port
Doctor inspecte l’exécution du service (PID, dernier statut de sortie) et avertit lorsque le
service est installé mais n’est pas réellement en cours d’exécution. Il vérifie aussi les collisions de port
sur le port Gateway (par défaut `18789`) et signale les causes probables (passerelle déjà
service est installé mais n’est pas réellement en cours d’exécution. Il vérifie également les collisions de port
sur le port Gateway (par défaut `18789`) et signale les causes probables (Gateway déjà
en cours d’exécution, tunnel SSH).
### 17) Bonnes pratiques d’exécution Gateway
Doctor avertit lorsque le service Gateway s’exécute sur Bun ou sur un chemin Node géré par un gestionnaire de versions
(`nvm`, `fnm`, `volta`, `asdf`, etc.). Les canaux WhatsApp + Telegram requièrent Node,
et les chemins de gestionnaire de versions peuvent casser après des mises à niveau car le service ne
charge pas l’initialisation de votre shell. Doctor propose de migrer vers une installation Node système lorsqu’elle
est disponible (Homebrew/apt/choco).
(`nvm`, `fnm`, `volta`, `asdf`, etc.). Les canaux WhatsApp + Telegram nécessitent Node,
et les chemins de gestionnaire de versions peuvent se casser après les mises à niveau parce que le service ne
charge pas l’initialisation de votre shell. Doctor propose de migrer vers une installation système de Node lorsqu’elle est
disponible (Homebrew/apt/choco).
### 18) Écriture de la configuration + métadonnées de l’assistant
Doctor persiste toutes les modifications de configuration et marque les métadonnées de l’assistant pour enregistrer l’exécution
Doctor persiste toutes les modifications de configuration et appose des métadonnées de l’assistant pour enregistrer l’exécution
de doctor.
### 19) Conseils pour l’espace de travail (sauvegarde + système mémoire)
### 19) Conseils pour le workspace (sauvegarde + système mémoire)
Doctor suggère un système de mémoire d’espace de travail lorsqu’il est absent et affiche un conseil de sauvegarde
si l’espace de travail n’est pas déjà sous git.
Doctor suggère un système mémoire du workspace lorsqu’il est absent et affiche un conseil de sauvegarde
si le workspace n’est pas déjà sous git.
Voir [/concepts/agent-workspace](/fr/concepts/agent-workspace) pour un guide complet sur la
structure de l’espace de travail et la sauvegarde git (GitHub ou GitLab privé recommandé).
Voir [/concepts/agent-workspace](/fr/concepts/agent-workspace) pour un guide complet de la
structure du workspace et de la sauvegarde git (GitHub ou GitLab privés recommandés).

164
docs/fr/gateway/index.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Exécution ou débogage du processus gateway
- Exécution ou débogage du processus Gateway
summary: Runbook pour le service Gateway, son cycle de vie et ses opérations
title: Runbook Gateway
title: Runbook du Gateway
x-i18n:
generated_at: "2026-04-07T06:50:17Z"
generated_at: "2026-04-20T07:05:23Z"
model: gpt-5.4
provider: openai
source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd
source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8
source_path: gateway/index.md
workflow: 15
---
# Runbook Gateway
# Runbook du Gateway
Utilisez cette page pour le démarrage au jour 1 et les opérations au jour 2 du service Gateway.
Utilisez cette page pour le démarrage du premier jour et les opérations du deuxième jour du service Gateway.
<CardGroup cols={2}>
<Card title="Dépannage approfondi" icon="siren" href="/fr/gateway/troubleshooting">
Diagnostics orientés symptômes avec des séquences de commandes exactes et des signatures de journaux.
</Card>
<Card title="Configuration" icon="sliders" href="/fr/gateway/configuration">
Guide de configuration orienté tâches + référence de configuration complète.
Guide de configuration orienté tâches + référence complète de configuration.
</Card>
<Card title="Gestion des secrets" icon="key-round" href="/fr/gateway/secrets">
Contrat SecretRef, comportement des instantanés d’exécution, et opérations de migration/rechargement.
</Card>
<Card title="Contrat du plan de secrets" icon="shield-check" href="/fr/gateway/secrets-plan-contract">
Règles exactes de cible/chemin pour `secrets apply` et comportement des profils d’authentification en mode ref-only.
<Card title="Contrat du plan des secrets" icon="shield-check" href="/fr/gateway/secrets-plan-contract">
Règles exactes des cibles/chemins de `secrets apply` et comportement des profils d’authentification en mode ref-only.
</Card>
</CardGroup>
## Démarrage local en 5 minutes
<Steps>
<Step title="Démarrer la Gateway">
<Step title="Démarrer le Gateway">
```bash
openclaw gateway --port 18789
# debug/trace mirrored to stdio
# débogage/trace recopiés vers stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
# force l’arrêt de l’écouteur sur le port sélectionné, puis démarre
openclaw gateway --force
```
@ -54,7 +54,7 @@ openclaw status
openclaw logs --follow
```
Référence saine : `Runtime: running` et `RPC probe: ok`.
Référence saine : `Runtime: running`, `Connectivity probe: ok`, et `Capability: ...` qui correspond à ce que vous attendez. Utilisez `openclaw gateway status --require-rpc` lorsque vous avez besoin d’une preuve RPC en portée lecture, et pas seulement d’une joignabilité.
</Step>
@ -64,35 +64,35 @@ Référence saine : `Runtime: running` et `RPC probe: ok`.
openclaw channels status --probe
```
Avec une Gateway joignable, cette commande exécute des sondes de canal en direct par compte ainsi que des audits facultatifs.
Si la Gateway est inaccessible, la CLI revient à des résumés de canaux basés uniquement sur la configuration
au lieu d’une sortie de sonde en direct.
Avec un gateway joignable, cela exécute des sondes de canaux en direct par compte ainsi que des audits facultatifs.
Si le gateway est inaccessible, la CLI bascule vers des résumés de canaux basés uniquement sur la configuration
au lieu de la sortie des sondes en direct.
</Step>
</Steps>
<Note>
Le rechargement de configuration de la Gateway surveille le chemin du fichier de configuration actif (résolu à partir des valeurs par défaut du profil/de l’état, ou `OPENCLAW_CONFIG_PATH` s’il est défini).
Le rechargement de la configuration du Gateway surveille le chemin du fichier de configuration actif (résolu à partir des valeurs par défaut du profil/de l’état, ou de `OPENCLAW_CONFIG_PATH` lorsqu’il est défini).
Le mode par défaut est `gateway.reload.mode="hybrid"`.
Après le premier chargement réussi, le processus en cours d’exécution sert l’instantané de configuration actif en mémoire ; un rechargement réussi remplace cet instantané de manière atomique.
</Note>
## Modèle d’exécution
- Un processus toujours actif pour le routage, le plan de contrôle et les connexions aux canaux.
- Un processus toujours actif pour le routage, le plan de contrôle et les connexions de canaux.
- Un port multiplexé unique pour :
- le contrôle/RPC WebSocket
- les API HTTP, compatibles OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
- l’interface de contrôle et les hooks
- l’interface utilisateur de contrôle et les hooks
- Mode de liaison par défaut : `loopback`.
- L’authentification est requise par défaut. Les configurations à secret partagé utilisent
`gateway.auth.token` / `gateway.auth.password` (ou
`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), et les configurations
avec proxy inverse hors loopback peuvent utiliser `gateway.auth.mode: "trusted-proxy"`.
de proxy inverse non-loopback peuvent utiliser `gateway.auth.mode: "trusted-proxy"`.
## Endpoints compatibles OpenAI
La surface de compatibilité à plus fort impact d’OpenClaw est désormais :
La surface de compatibilité la plus utile d’OpenClaw est désormais :
- `GET /v1/models`
- `GET /v1/models/{id}`
@ -102,39 +102,39 @@ La surface de compatibilité à plus fort impact d’OpenClaw est désormais :
Pourquoi cet ensemble est important :
- La plupart des intégrations Open WebUI, LobeChat et LibreChat sondent d’abord `/v1/models`.
- La plupart des intégrations Open WebUI, LobeChat et LibreChat interrogent d’abord `/v1/models`.
- De nombreux pipelines RAG et de mémoire attendent `/v1/embeddings`.
- Les clients natifs pour agents préfèrent de plus en plus `/v1/responses`.
Note de planification :
- `/v1/models` est orienté agent en priorité : il renvoie `openclaw`, `openclaw/default` et `openclaw/<agentId>`.
- `/v1/models` est orienté agent : il renvoie `openclaw`, `openclaw/default` et `openclaw/<agentId>`.
- `openclaw/default` est l’alias stable qui pointe toujours vers l’agent par défaut configuré.
- Utilisez `x-openclaw-model` lorsque vous souhaitez un remplacement du fournisseur/modèle backend ; sinon, le modèle normal et la configuration d’embeddings de l’agent sélectionné gardent le contrôle.
- Utilisez `x-openclaw-model` lorsque vous souhaitez un remplacement du fournisseur/modèle backend ; sinon, la configuration normale du modèle et des embeddings de l’agent sélectionné reste maîtresse.
Tous ces endpoints s’exécutent sur le port principal de la Gateway et utilisent la même frontière d’authentification d’opérateur de confiance que le reste de l’API HTTP Gateway.
Tous ceux-ci s’exécutent sur le port principal du Gateway et utilisent la même limite d’authentification d’opérateur de confiance que le reste de l’API HTTP du Gateway.
### Priorité du port et du mode de liaison
| Paramètre | Ordre de résolution |
| ------------ | ------------------------------------------------------------ |
| Port Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
| Mode de liaison | CLI/override → `gateway.bind` → `loopback` |
| Paramètre | Ordre de résolution |
| ------------- | -------------------------------------------------------------- |
| Port Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
| Mode de liaison | CLI/override → `gateway.bind` → `loopback` |
### Modes de rechargement à chaud
| `gateway.reload.mode` | Comportement |
| --------------------- | ---------------------------------------------- |
| `off` | Aucun rechargement de configuration |
| `hot` | Applique uniquement les modifications sûres à chaud |
| `restart` | Redémarre lors de modifications nécessitant un rechargement |
| `hybrid` (par défaut) | Applique à chaud quand c’est sûr, redémarre si nécessaire |
| `gateway.reload.mode` | Comportement |
| --------------------- | ---------------------------------------- |
| `off` | Aucun rechargement de configuration |
| `hot` | Applique uniquement les changements sûrs à chaud |
| `restart` | Redémarre sur les changements nécessitant un rechargement |
| `hybrid` (par défaut) | Applique à chaud quand c’est sûr, redémarre quand c’est nécessaire |
## Ensemble de commandes opérateur
## Jeu de commandes opérateur
```bash
openclaw gateway status
openclaw gateway status --deep # adds a system-level service scan
openclaw gateway status --deep # ajoute une analyse du service au niveau système
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
@ -144,15 +144,15 @@ openclaw logs --follow
openclaw doctor
```
`gateway status --deep` sert à la découverte supplémentaire de services (unités système
LaunchDaemons/systemd/schtasks), pas à une sonde de santé RPC plus approfondie.
`gateway status --deep` sert à une découverte de services supplémentaire (LaunchDaemons/unités systemd système
/schtasks), pas à une sonde d’état de santé RPC plus approfondie.
## Gateways multiples (même hôte)
## Plusieurs gateways (même hôte)
La plupart des installations doivent exécuter une gateway par machine. Une seule gateway peut héberger plusieurs
La plupart des installations doivent exécuter un gateway par machine. Un seul gateway peut héberger plusieurs
agents et canaux.
Vous n’avez besoin de plusieurs gateways que si vous souhaitez délibérément une isolation ou un bot de secours.
Vous n’avez besoin de plusieurs gateways que si vous voulez délibérément de l’isolation ou un bot de secours.
Vérifications utiles :
@ -165,15 +165,15 @@ Ce à quoi s’attendre :
- `gateway status --deep` peut signaler `Other gateway-like services detected (best effort)`
et afficher des conseils de nettoyage lorsque d’anciennes installations launchd/systemd/schtasks sont encore présentes.
- `gateway probe` peut avertir avec `multiple reachable gateways` lorsque plus d’une cible
- `gateway probe` peut avertir de `multiple reachable gateways` lorsque plus d’une cible
répond.
- Si c’est intentionnel, isolez les ports, la configuration/l’état et les racines d’espace de travail par gateway.
- Si cela est intentionnel, isolez les ports, la configuration/l’état et les racines d’espace de travail pour chaque gateway.
Configuration détaillée : [/gateway/multiple-gateways](/fr/gateway/multiple-gateways).
## Accès à distance
## Accès distant
Méthode préférée : Tailscale/VPN.
Préféré : Tailscale/VPN.
Solution de repli : tunnel SSH.
```bash
@ -183,16 +183,16 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
Connectez ensuite les clients localement à `ws://127.0.0.1:18789`.
<Warning>
Les tunnels SSH ne contournent pas l’authentification de la gateway. Avec une authentification à secret partagé, les clients
doivent toujours envoyer `token`/`password`, même via le tunnel. Pour les modes avec identité,
Les tunnels SSH ne contournent pas l’authentification du gateway. Pour une authentification à secret partagé, les clients doivent toujours
envoyer `token`/`password` même via le tunnel. Pour les modes porteurs d’identité,
la requête doit toujours satisfaire ce chemin d’authentification.
</Warning>
Voir : [Gateway distante](/fr/gateway/remote), [Authentification](/fr/gateway/authentication), [Tailscale](/fr/gateway/tailscale).
Voir : [Gateway distant](/fr/gateway/remote), [Authentification](/fr/gateway/authentication), [Tailscale](/fr/gateway/tailscale).
## Supervision et cycle de vie du service
Utilisez des exécutions supervisées pour une fiabilité proche de la production.
Utilisez des exécutions supervisées pour une fiabilité de niveau production.
<Tabs>
<Tab title="macOS (launchd)">
@ -204,11 +204,11 @@ openclaw gateway restart
openclaw gateway stop
```
Les labels LaunchAgent sont `ai.openclaw.gateway` (par défaut) ou `ai.openclaw.<profile>` (profil nommé). `openclaw doctor` audite et répare la dérive de configuration du service.
Les libellés LaunchAgent sont `ai.openclaw.gateway` (par défaut) ou `ai.openclaw.<profile>` (profil nommé). `openclaw doctor` audite et répare les dérives de configuration du service.
</Tab>
<Tab title="Linux (systemd user)">
<Tab title="Linux (systemd utilisateur)">
```bash
openclaw gateway install
@ -255,8 +255,8 @@ openclaw gateway stop
```
Le démarrage géré natif sous Windows utilise une tâche planifiée nommée `OpenClaw Gateway`
(ou `OpenClaw Gateway (<profile>)` pour les profils nommés). Si la création de tâche planifiée
est refusée, OpenClaw revient à un lanceur par utilisateur dans le dossier de démarrage
(ou `OpenClaw Gateway (<profile>)` pour les profils nommés). Si la création de la tâche planifiée
est refusée, OpenClaw revient à un lanceur par utilisateur dans le dossier Startup
qui pointe vers `gateway.cmd` dans le répertoire d’état.
</Tab>
@ -277,10 +277,10 @@ Utilisez le même corps de service que pour l’unité utilisateur, mais install
</Tab>
</Tabs>
## Gateways multiples sur un même hôte
## Plusieurs gateways sur un même hôte
La plupart des configurations doivent exécuter **une seule** Gateway.
N’en utilisez plusieurs que pour une isolation/redondance stricte (par exemple un profil de secours).
La plupart des configurations doivent exécuter **un** Gateway.
N’utilisez plusieurs gateways que pour une isolation/redondance stricte (par exemple un profil de secours).
Liste de contrôle par instance :
@ -296,9 +296,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
```
Voir : [Gateways multiples](/fr/gateway/multiple-gateways).
Voir : [Plusieurs gateways](/fr/gateway/multiple-gateways).
### Chemin rapide pour le profil de développement
### Chemin rapide du profil dev
```bash
openclaw --dev setup
@ -306,23 +306,23 @@ openclaw --dev gateway --allow-unconfigured
openclaw --dev status
```
Les valeurs par défaut incluent un état/une configuration isolés et un port de base de gateway `19001`.
Les valeurs par défaut incluent un état/une configuration isolés et un port Gateway de base `19001`.
## Référence rapide du protocole (vue opérateur)
- La première trame client doit être `connect`.
- La Gateway renvoie un instantané `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limites/politique).
- `hello-ok.features.methods` / `events` est une liste de découverte prudente, et non
un dump généré de chaque route d’assistance appelable.
- La première trame cliente doit être `connect`.
- Le Gateway renvoie un instantané `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
- `hello-ok.features.methods` / `events` sont une liste de découverte prudente, et non
un dump généré de toutes les routes d’assistance appelables.
- Requêtes : `req(method, params)` → `res(ok/payload|error)`.
- Les événements courants incluent `connect.challenge`, `agent`, `chat`,
`session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`,
`health`, `heartbeat`, les événements du cycle de vie d’appairage/d’approbation, et `shutdown`.
`health`, `heartbeat`, les événements du cycle de vie d’appairage/approbation, et `shutdown`.
Les exécutions d’agent comportent deux étapes :
Les exécutions d’agent se déroulent en deux étapes :
1. Accusé de réception immédiat (`status:"accepted"`)
2. Réponse finale d’achèvement (`status:"ok"|"error"`), avec des événements `agent` diffusés entre les deux.
1. Accusé de réception immédiat accepté (`status:"accepted"`)
2. Réponse finale de fin (`status:"ok"|"error"`), avec des événements `agent` diffusés entre les deux.
Voir la documentation complète du protocole : [Protocole Gateway](/fr/gateway/protocol).
@ -330,7 +330,7 @@ Voir la documentation complète du protocole : [Protocole Gateway](/fr/gateway/p
### Disponibilité
- Ouvrez une connexion WS et envoyez `connect`.
- Ouvrez un WS et envoyez `connect`.
- Attendez une réponse `hello-ok` avec instantané.
### État de préparation
@ -341,30 +341,30 @@ openclaw channels status --probe
openclaw health
```
### Récupération après interruption
### Récupération après rupture
Les événements ne sont pas rejoués. En cas de trou dans la séquence, actualisez l’état (`health`, `system-presence`) avant de continuer.
Les événements ne sont pas rejoués. En cas de trou de séquence, actualisez l’état (`health`, `system-presence`) avant de continuer.
## Signatures d’échec courantes
| Signature | Problème probable |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `refusing to bind gateway ... without auth` | Liaison hors loopback sans chemin d’authentification gateway valide |
| `another gateway instance is already listening` / `EADDRINUSE` | Conflit de port |
| `Gateway start blocked: set gateway.mode=local` | Configuration définie en mode distant, ou estampille du mode local absente d’une configuration endommagée |
| `unauthorized` during connect | Incompatibilité d’authentification entre le client et la gateway |
| Signature | Problème probable |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `refusing to bind gateway ... without auth` | Liaison non-loopback sans chemin d’authentification gateway valide |
| `another gateway instance is already listening` / `EADDRINUSE` | Conflit de port |
| `Gateway start blocked: set gateway.mode=local` | Configuration définie en mode distant, ou tampon de mode local manquant dans une configuration endommagée |
| `unauthorized` during connect | Incompatibilité d’authentification entre le client et le gateway |
Pour les séquences complètes de diagnostic, utilisez [Dépannage Gateway](/fr/gateway/troubleshooting).
Pour des séquences complètes de diagnostic, utilisez [Dépannage Gateway](/fr/gateway/troubleshooting).
## Garanties de sécurité
- Les clients du protocole Gateway échouent rapidement lorsque la Gateway n’est pas disponible (pas de repli implicite vers un canal direct).
- Les premières trames invalides/non `connect` sont rejetées et la connexion est fermée.
- Un arrêt gracieux émet un événement `shutdown` avant la fermeture du socket.
- Les clients du protocole Gateway échouent rapidement lorsque le Gateway n’est pas disponible (pas de bascule implicite directe vers le canal).
- Les premières trames invalides/non-`connect` sont rejetées et la connexion est fermée.
- L’arrêt propre émet un événement `shutdown` avant la fermeture du socket.
---
Voir aussi :
Associé :
- [Dépannage](/fr/gateway/troubleshooting)
- [Processus en arrière-plan](/fr/gateway/background-process)

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

@ -1,26 +1,26 @@
---
read_when:
- Le centre de dépannage vous a orienté ici pour un diagnostic plus approfondi
- Vous avez besoin de sections de guide basées sur les symptômes, stables, avec des commandes exactes
summary: Guide de dépannage approfondi pour la gateway, les canaux, l’automatisation, les nœuds et le navigateur
- Vous avez besoin de sections de guide de dépannage stables, basées sur les symptômes, avec des commandes exactes
summary: Guide de dépannage approfondi pour Gateway, les canaux, l’automatisation, les Nodes et le navigateur
title: Dépannage
x-i18n:
generated_at: "2026-04-11T02:45:02Z"
generated_at: "2026-04-20T07:05:27Z"
model: gpt-5.4
provider: openai
source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5
source_hash: d93a82407dbb1314b91a809ff9433114e1e9a3b56d46547ef53a8196bac06260
source_path: gateway/troubleshooting.md
workflow: 15
---
# Dépannage de la gateway
# Dépannage de Gateway
Cette page est le guide approfondi.
Cette page est le guide de dépannage approfondi.
Commencez par [/help/troubleshooting](/fr/help/troubleshooting) si vous voulez d’abord le flux de triage rapide.
## Échelle de commandes
Exécutez-les d’abord, dans cet ordre :
Exécutez-les d’abord, dans cet ordre :
```bash
openclaw status
@ -30,16 +30,15 @@ openclaw doctor
openclaw channels status --probe
```
Signaux attendus d’un état sain :
Signaux attendus lorsque tout fonctionne correctement :
- `openclaw gateway status` affiche `Runtime: running` et `RPC probe: ok`.
- `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 channels status --probe` affiche l’état de transport en direct par compte et,
lorsque c’est pris en charge, des résultats de sonde/audit tels que `works` ou `audit ok`.
- `openclaw channels status --probe` affiche l’état de transport en direct par compte et, lorsqu’ils sont pris en charge, les résultats de sonde/audit comme `works` ou `audit ok`.
## Anthropic 429 : usage supplémentaire requis pour un long contexte
## Anthropic 429 : usage supplémentaire requis pour le contexte long
Utilisez cette section lorsque les journaux/erreurs incluent :
Utilisez ceci lorsque les journaux/erreurs contiennent :
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
```bash
@ -48,19 +47,19 @@ openclaw models status
openclaw config get agents.defaults.models
```
Recherchez :
À rechercher :
- Le modèle Anthropic Opus/Sonnet sélectionné a `params.context1m: true`.
- L’identifiant Anthropic actuel n’est pas éligible à l’usage en long contexte.
- Les requêtes échouent uniquement sur les longues sessions/exécutions de modèle qui nécessitent la voie bêta 1M.
- Les identifiants Anthropic actuels ne sont pas éligibles à l’usage 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 long contexte, ou passez à une clé API Anthropic.
3. Configurez des modèles de secours afin que les exécutions continuent lorsque les requêtes Anthropic en long contexte sont rejetées.
2. Utilisez des identifiants Anthropic éligibles aux requêtes à 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 à contexte long sont rejetées.
Voir aussi :
Voir aussi :
- [/providers/anthropic](/fr/providers/anthropic)
- [/reference/token-use](/fr/reference/token-use)
@ -68,11 +67,11 @@ Voir aussi :
## Un 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
- de 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èles OpenClaw échouent uniquement lors des tours d’agent normaux
```bash
curl http://127.0.0.1:1234/v1/models
@ -83,32 +82,26 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```
Recherchez :
À rechercher :
- les petits appels directs réussissent, mais les exécutions OpenClaw échouent uniquement avec des prompts plus volumineux
- 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 n’apparaissent qu’avec un plus grand nombre de jetons de prompt ou avec les prompts complets du runtime d’agent
- des plantages du backend qui n’apparaissent qu’avec des nombres de tokens de prompt plus élevés ou avec les prompts complets du runtime d’agent
Signatures courantes :
Signatures courantes :
- `messages[...].content: invalid type: sequence, expected a string` → le backend
rejette des 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 de backend/modèle
(par exemple Gemma sur certaines versions de `inferrs`) → le transport OpenClaw est
probablement déjà correct ; le backend échoue sur la forme plus volumineuse du prompt du runtime d’agent.
- les échecs diminuent après avoir désactivé les outils mais ne disparaissent pas → les schémas d’outils faisaient
partie de la pression, mais le problème restant relève toujours de la capacité du modèle/serveur en amont ou d’un bug backend.
- `messages[...].content: invalid type: sequence, expected a string` → le backend 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 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 plus volumineuse des prompts du runtime d’agent.
- les échecs diminuent après la désactivation des outils, mais ne disparaissent pas → les schémas d’outils faisaient partie de la pression, mais le problème restant vient toujours en amont de la capacité du modèle/serveur ou d’un bogue 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 la pression sur le prompt lorsque c’est possible : bootstrap d’espace de travail plus petit, historique de session plus court, modèle local plus léger, ou backend avec un meilleur support du long contexte.
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 ouvrez-y un rapport avec une reproduction incluant la forme de payload acceptée.
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 la pression sur les prompts lorsque c’est possible : initialisation d’espace de travail plus petite, historique de session plus court, modèle local plus léger ou backend avec une 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 signalez-y un cas de reproduction avec la forme de payload acceptée.
Voir aussi :
Voir aussi :
- [/gateway/local-models](/fr/gateway/local-models)
- [/gateway/configuration](/fr/gateway/configuration)
@ -116,7 +109,7 @@ Voir aussi :
## 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
@ -126,27 +119,27 @@ openclaw config get channels
openclaw logs --follow
```
Recherchez :
À rechercher :
- Appairage en attente pour les expéditeurs de messages privés.
- Appairage en attente pour les expéditeurs de messages directs.
- Contrôle des mentions de groupe (`requireMention`, `mentionPatterns`).
- Incohérences de liste d’autorisation de canal/groupe.
Signatures courantes :
Signatures courantes :
- `drop guild message (mention required` → message de groupe ignoré jusqu’à mention.
- `pairing request` → l’expéditeur a besoin d’une approbation.
- `blocked` / `allowlist` → expéditeur/canal filtré par la politique.
- `blocked` / `allowlist` → l’expéditeur/canal a été filtré par la stratégie.
Voir aussi :
Voir aussi :
- [/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 le tableau de bord / la 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
@ -156,49 +149,38 @@ openclaw doctor
openclaw gateway status --json
```
Recherchez :
À rechercher :
- URL de sonde et URL du tableau de bord correctes.
- Incohérence de mode d’authentification/jeton entre le client et la gateway.
- URL de sonde et URL de tableau de bord correctes.
- Incohérence de mode d’authentification / jeton entre le client et Gateway.
- Utilisation de HTTP là où une identité d’appareil est requise.
Signatures courantes :
Signatures courantes :
- `device identity required` → contexte non sécurisé ou authentification d’appareil manquante.
- `origin not allowed` → l’`Origin` du navigateur n’est pas dans `gateway.controlUi.allowedOrigins`
(ou vous vous connectez depuis une origine de 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é le mauvais
payload (ou un horodatage périmé) pour le handshake actuel.
- `AUTH_TOKEN_MISMATCH` avec `canRetryWithDeviceToken=true` → le client peut faire une nouvelle tentative de confiance avec un jeton d’appareil en cache.
- Cette nouvelle tentative avec jeton en cache réutilise l’ensemble de portées en cache stocké avec le
jeton d’appareil appairé. Les appelants avec `deviceToken` explicite / `scopes` explicites conservent leur
ensemble de portées demandé.
- En dehors de cette voie de nouvelle tentative, la priorité d’authentification à la connexion est d’abord
le jeton/mot de passe partagé explicite, puis le `deviceToken` explicite, puis le jeton d’appareil stocké,
puis le jeton de bootstrap.
- Sur la voie 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 depuis le même client peuvent donc faire apparaître `retry later`
à la deuxième 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é/du jeton d’appareil ; actualisez la configuration du jeton et réapprouvez/faites tourner le jeton d’appareil si nécessaire.
- `gateway connect failed:` → cible hôte/port/url incorrecte.
- `origin not allowed` → l’`Origin` du navigateur n’est pas dans `gateway.controlUi.allowedOrigins` (ou vous vous connectez depuis une origine de navigateur non loopback sans liste d’autorisation explicite).
- `device nonce required` / `device nonce mismatch` → le client ne termine pas le flux d’authentification d’appareil basé sur défi (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → le client a signé le mauvais payload (ou un horodatage périmé) pour la poignée de main en cours.
- `AUTH_TOKEN_MISMATCH` avec `canRetryWithDeviceToken=true` → le client peut effectuer une nouvelle tentative approuvée avec le jeton d’appareil mis en cache.
- Cette nouvelle tentative avec jeton en cache réutilise l’ensemble de portées mis en cache stocké avec le jeton d’appareil appairé. Les appelants avec `deviceToken` explicite / `scopes` explicites conservent à la place l’ensemble de portées demandé.
- En dehors de ce chemin de nouvelle tentative, la priorité d’authentification de connexion est d’abord le jeton/mot de passe partagé explicite, puis le `deviceToken` explicite, puis le jeton d’appareil stocké, puis le jeton d’amorçage.
- Sur le chemin asynchrone de la Control UI via Tailscale Serve, 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 provenant du même client peuvent donc faire apparaître `retry later` lors de 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 séparé.
- `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 tourner le jeton d’appareil si nécessaire.
- `gateway connect failed:` → mauvaise cible d’hôte/port/URL.
### Carte rapide des codes de détail d’authentification
### Résumé rapide des codes de détail d’authentification
Utilisez `error.details.code` de la réponse `connect` échouée pour choisir l’action suivante :
Utilisez `error.details.code` dans la réponse `connect` échouée pour choisir l’action suivante :
| Code de détail | 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 paramètres de l’interface de contrôle. |
| `AUTH_TOKEN_MISMATCH` | Le jeton partagé ne correspond pas au jeton d’authentification de la gateway. | Si `canRetryWithDeviceToken=true`, autorisez une nouvelle tentative de confiance. 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 cela échoue encore, exécutez la [checklist de récupération après dérive de jeton](/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Le jeton par appareil en cache est périmé ou révoqué. | Faites tourner/réapprouvez le jeton d’appareil via le [CLI devices](/cli/devices), puis reconnectez-vous. |
| `PAIRING_REQUIRED` | L’identité de l’appareil est connue mais non approuvée pour ce rôle. | Approuvez la demande en attente : `openclaw devices list` puis `openclaw devices approve <requestId>`. |
| Code de détail | 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 paramètres de la 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 [check-list de récupération de dérive de jeton](/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Le jeton par appareil en cache est périmé ou révoqué. | Faites tourner/réapprouvez le jeton d’appareil à l’aide de la [CLI des appareils](/cli/devices), puis reconnectez-vous. |
| `PAIRING_REQUIRED` | L’identité de l’appareil doit être approuvée. 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 vers l’authentification d’appareil v2 :
Vérification de migration vers l’authentification d’appareil v2 :
```bash
openclaw --version
@ -206,63 +188,61 @@ openclaw doctor
openclaw gateway status
```
Si les journaux affichent 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 le payload lié au challenge
3. envoie `connect.params.device.nonce` avec le même nonce de challenge
2. signe le payload lié au défi
3. envoie `connect.params.device.nonce` avec le même nonce du défi
Si `openclaw devices rotate` / `revoke` / `remove` est refusé de manière inattendue :
Si `openclaw devices rotate` / `revoke` / `remove` est refusé de manière inattendue :
- les sessions à jeton d’appareil appairé peuvent gérer uniquement **leur propre**
appareil, sauf si l’appelant a aussi `operator.admin`
- `openclaw devices rotate --scope ...` ne peut demander que des portées opérateur que
la session appelante détient déjà
- 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 portées opérateur que la session appelante détient déjà
Voir aussi :
Voir aussi :
- [/web/control-ui](/web/control-ui)
- [/gateway/configuration](/fr/gateway/configuration) (modes d’authentification de la 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](/cli/devices)
## Le service gateway n’est pas en cours d’exécution
## Le service Gateway ne s’exécute pas
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
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # analyse aussi les services au niveau système
openclaw gateway status --deep # also scan system-level services
```
Recherchez :
À rechercher :
- `Runtime: stopped` avec indices de sortie.
- Incohérence de configuration de service (`Config (cli)` vs `Config (service)`).
- `Runtime: stopped` avec des indications de sortie.
- Incohérence de configuration du service (`Config (cli)` vs `Config (service)`).
- Conflits de port/écoute.
- Installations launchd/systemd/schtasks supplémentaires lorsque `--deep` est utilisé.
- Indices de nettoyage `Other gateway-like services detected (best effort)`.
- Indications 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`. Correctif : 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 lorsque 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 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 lorsque configuré).
- `another gateway instance is already listening` / `EADDRINUSE` → conflit de port.
- `Other gateway-like services detected (best effort)` → il existe des unités launchd/systemd/schtasks obsolètes ou parallèles. La plupart des configurations doivent conserver une seule gateway par machine ; si vous en avez réellement 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).
- `Other gateway-like services detected (best effort)` → des unités launchd/systemd/schtasks obsolètes ou parallèles existent. La plupart des installations devraient 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).
Voir aussi :
Voir aussi :
- [/gateway/background-process](/fr/gateway/background-process)
- [/gateway/configuration](/fr/gateway/configuration)
- [/gateway/doctor](/fr/gateway/doctor)
## Avertissements de sonde de la gateway
## Avertissements de sonde Gateway
Utilisez cette section lorsque `openclaw gateway probe` atteint bien quelque chose, mais affiche quand 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
@ -270,27 +250,28 @@ openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```
Recherchez :
À rechercher :
- `warnings[].code` et `primaryTargetId` dans la sortie JSON.
- Si l’avertissement concerne le fallback SSH, plusieurs gateways, des portées manquantes, ou des références d’authentification non résolues.
- Si l’avertissement concerne le 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 configuration SSH a échoué, mais la commande a quand même essayé les cibles directes configurées/en loopback.
- `multiple reachable gateways detected` → plus d’une cible a répondu. En général, cela indique une configuration multi-gateway intentionnelle ou des écouteurs obsolètes/dupliqués.
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → la connexion a réussi, mais le RPC détaillé est limité par les portées ; appairez une identité d’appareil ou utilisez des identifiants avec `operator.read`.
- 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 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 portées ; 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 un accès opérateur normal.
- texte d’avertissement `gateway.auth.*` / `gateway.remote.*` SecretRef non résolu → le matériel d’authentification n’était pas disponible dans ce chemin de commande pour la cible en échec.
Voir aussi :
Voir aussi :
- [/cli/gateway](/cli/gateway)
- [/gateway#multiple-gateways-same-host](/fr/gateway#multiple-gateways-same-host)
- [/gateway/remote](/fr/gateway/remote)
## Canal connecté mais messages qui ne circulent pas
## Canal connecté mais messages non transmis
Si l’état du canal est connecté mais que le flux de messages est interrompu, concentrez-vous sur la politique, les autorisations 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 propres au canal.
```bash
openclaw channels status --probe
@ -300,28 +281,28 @@ openclaw logs --follow
openclaw config get channels
```
Recherchez :
À rechercher :
- Politique DM (`pairing`, `allowlist`, `open`, `disabled`).
- Liste d’autorisation de groupe et exigences de mention.
- Permissions/portées API du canal manquantes.
- Stratégie de message direct (`pairing`, `allowlist`, `open`, `disabled`).
- Liste d’autorisation des groupes et exigences de mention.
- Autorisations/portées API du canal manquantes.
Signatures courantes :
Signatures courantes :
- `mention required` → message ignoré par la politique de mention de groupe.
- traces `pairing` / d’approbation en attente → l’expéditeur n’est pas approuvé.
- `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/autorisations du canal.
Voir aussi :
Voir aussi :
- [/channels/troubleshooting](/fr/channels/troubleshooting)
- [/channels/whatsapp](/fr/channels/whatsapp)
- [/channels/telegram](/fr/channels/telegram)
- [/channels/discord](/fr/channels/discord)
## Livraison cron et heartbeat
## Livraison Cron et Heartbeat
Si cron ou heartbeat ne s’est pas exécuté ou n’a pas été livré, vérifiez d’abord l’état du planificateur, puis la cible de livraison.
Si Cron ou Heartbeat ne s’est pas exécuté ou n’a pas été livré, vérifiez d’abord l’état du planificateur, puis la cible de livraison.
```bash
openclaw cron status
@ -331,31 +312,31 @@ openclaw system heartbeat last
openclaw logs --follow
```
Recherchez :
À rechercher :
- Cron activé et prochaine activation présente.
- État de l’historique d’exécution des jobs (`ok`, `skipped`, `error`).
- Raisons de saut de heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
- Cron activé et prochain réveil présent.
- État de l’historique des exécutions de tâche (`ok`, `skipped`, `error`).
- Raisons d’omission 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` → l’impulsion du planificateur a échoué ; vérifiez les erreurs de fichiers/journaux/runtime.
- `heartbeat skipped` avec `reason=quiet-hours` → hors 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.
- `cron: scheduler disabled; jobs will not run automatically` → Cron est désactivé.
- `cron: timer tick failed` → l’impulsion du planificateur a échoué ; vérifiez les erreurs de fichier/journal/runtime.
- `heartbeat skipped` avec `reason=quiet-hours` → en dehors de la plage d’heures actives.
- `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 du modèle.
- `heartbeat skipped` avec `reason=no-tasks-due` → `HEARTBEAT.md` contient un bloc `tasks:`, mais aucune tâche n’est due à cette impulsion.
- `heartbeat: unknown accountId` → id de compte invalide pour la cible de livraison heartbeat.
- `heartbeat skipped` avec `reason=dm-blocked` → la cible heartbeat a été résolue en destination de type DM alors que `agents.defaults.heartbeat.directPolicy` (ou la surcharge par agent) est défini sur `block`.
- `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 message direct alors que `agents.defaults.heartbeat.directPolicy` (ou une surcharge par agent) est défini sur `block`.
Voir aussi :
Voir aussi :
- [/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 de nœud appairé
## Échec d’un outil Node appairé
Si un nœud est appairé mais que les outils échouent, isolez l’état de premier plan, les permissions et l’état 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
@ -365,20 +346,20 @@ openclaw logs --follow
openclaw status
```
Recherchez :
À rechercher :
- Nœud en ligne avec les capacités attendues.
- Autorisations système accordées pour caméra/micro/localisation/écran.
- Node en ligne avec les capacités attendues.
- Autorisations du système d’exploitation pour la caméra/le micro/la localisation/l’écran.
- État des approbations d’exécution et de la liste d’autorisation.
Signatures courantes :
Signatures courantes :
- `NODE_BACKGROUND_UNAVAILABLE` → l’app du nœud doit être au premier plan.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → autorisation système manquante.
- `NODE_BACKGROUND_UNAVAILABLE` → l’application Node doit être au premier plan.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → autorisation du système d’exploitation 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.
Voir aussi :
Voir aussi :
- [/nodes/troubleshooting](/fr/nodes/troubleshooting)
- [/nodes/index](/fr/nodes/index)
@ -386,7 +367,7 @@ Voir aussi :
## Échec de l’outil navigateur
Utilisez cette section lorsque les actions de l’outil navigateur échouent alors que la gateway elle-même est saine.
Utilisez ceci lorsque les actions de l’outil navigateur échouent même si la Gateway elle-même est saine.
```bash
openclaw browser status
@ -396,41 +377,41 @@ openclaw logs --follow
openclaw doctor
```
Recherchez :
À rechercher :
- Si `plugins.allow` est défini et inclut `browser`.
- Un chemin d’exécutable du navigateur valide.
- Un chemin d’exécutable de 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 intégré 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 du navigateur n’a pas pu être lancé.
- `unknown command "browser"` ou `unknown command 'browser'` → le Plugin navigateur fourni 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 pu démarrer.
- `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 tel que `file:` ou `ftp:`.
- `browser.cdpUrl has invalid port` → l’URL CDP configurée contient un port invalide ou hors plage.
- `browser.cdpUrl has invalid port` → l’URL CDP configurée a un port incorrect ou hors plage.
- `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 en attachement seul 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 de la gateway n’inclut pas le package Playwright complet ; 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 a mélangé `--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 d’envoi de fichiers Chrome MCP nécessitent des refs d’instantané, pas des sélecteurs CSS.
- `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 pas de 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 de Gateway n’inclut pas le paquet Playwright complet ; 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éments via sélecteur CSS et l’export PDF restent indisponibles.
- `fullPage is not supported for element screenshots` → la requête 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` d’instantané, et non 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 références 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 surcharges 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 surcharges de délai d’attente.
- `response body is not supported for existing-session profiles yet.` → `responsebody` nécessite encore un navigateur géré ou un profil CDP brut.
- surcharges persistantes de viewport / mode sombre / langue / hors ligne sur des profils en attachement seul ou CDP distant → 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.
- remplacements persistants de viewport / mode sombre / langue / 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.
Voir aussi :
Voir aussi :
- [/tools/browser-linux-troubleshooting](/fr/tools/browser-linux-troubleshooting)
- [/tools/browser](/fr/tools/browser)
## Si vous avez effectué une mise à niveau et que quelque chose s’est soudainement cassé
La plupart des cassures 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 proviennent 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 surcharge d’URL a changé
@ -441,17 +422,17 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
À vérifier :
Ce qu’il faut vérifier :
- Si `gateway.mode=remote`, les appels CLI peuvent cibler le remote alors que votre service local fonctionne bien.
- Si `gateway.mode=remote`, les appels CLI peuvent cibler le distant alors que votre service local fonctionne bien.
- Les appels explicites avec `--url` ne reviennent pas aux identifiants stockés.
Signatures courantes :
Signatures courantes :
- `gateway connect failed:` → mauvaise URL cible.
- `gateway connect failed:` → mauvaise cible d’URL.
- `unauthorized` → point de terminaison accessible mais mauvaise authentification.
### 2) Les garde-fous de bind et d’authentification sont plus stricts
### 2) Les garde-fous de liaison et d’authentification sont plus stricts
```bash
openclaw config get gateway.bind
@ -461,17 +442,17 @@ openclaw gateway status
openclaw logs --follow
```
À vérifier :
Ce qu’il faut vérifier :
- Les binds 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/mot de passe partagé, 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` → bind non-loopback sans chemin d’authentification gateway valide.
- `RPC probe: failed` alors que le runtime est en cours d’exécution → gateway active 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 → la Gateway est active mais inaccessible avec l’authentification/l’URL actuelles.
### 3) L’état d’appairage et d’identité d’appareil a changé
### 3) L’état d’appairage et d’identité de l’appareil a changé
```bash
openclaw devices list
@ -480,24 +461,24 @@ openclaw logs --follow
openclaw doctor
```
À vérifier :
Ce qu’il faut vérifier :
- Approbations d’appareil en attente pour tableau de bord/nœuds.
- Approbations d’appairage DM en attente après des changements de politique ou d’identité.
- Approbations d’appareil en attente pour le tableau de bord/les Nodes.
- Approbations d’appairage DM en attente après des changements de stratégie ou d’identité.
Signatures courantes :
Signatures courantes :
- `device identity required` → authentification d’appareil non satisfaite.
- `pairing required` → expéditeur/appareil doit être approuvé.
- `device identity required` → l’authentification de l’appareil n’est pas satisfaite.
- `pairing required` → l’expéditeur/l’appareil doit être approuvé.
Si la configuration du service et le runtime ne concordent toujours pas après ces vérifications, réinstallez les métadonnées du service à partir du même répertoire de profil/d’état :
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 depuis le même répertoire de profil/d’état :
```bash
openclaw gateway install --force
openclaw gateway restart
```
Voir aussi :
Voir aussi :
- [/gateway/pairing](/fr/gateway/pairing)
- [/gateway/authentication](/fr/gateway/authentication)

1706
docs/fr/help/faq.md
View File

File diff suppressed because it is too large Load Diff

1111
docs/fr/help/testing.md
View File

File diff suppressed because it is too large Load Diff

211
docs/fr/help/troubleshooting.md
View File

@ -1,14 +1,14 @@
---
read_when:
- OpenClaw ne fonctionne pas et vous avez besoin du chemin le plus rapide vers une correction
- Vous voulez un flux de triage avant de vous plonger dans des guides détaillés
summary: Centre de dépannage d’OpenClaw orienté symptômes
- Vous voulez un flux de triage avant de vous plonger dans des runbooks détaillés
summary: Centre de dépannage orienté symptômes pour OpenClaw
title: Dépannage général
x-i18n:
generated_at: "2026-04-11T02:45:09Z"
generated_at: "2026-04-20T07:06:13Z"
model: gpt-5.4
provider: openai
source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a
source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88
source_path: help/troubleshooting.md
workflow: 15
---
@ -17,9 +17,9 @@ x-i18n:
Si vous n’avez que 2 minutes, utilisez cette page comme point d’entrée de triage.
## Les 60 premières secondes
## 60 premières secondes
Exécutez exactement cette séquence dans l’ordre :
Exécutez exactement cette séquence dans cet ordre :
```bash
openclaw status
@ -35,41 +35,45 @@ Bon résultat en une ligne :
- `openclaw status` → affiche les canaux configurés et aucune erreur d’authentification évidente.
- `openclaw status --all` → le rapport complet est présent et partageable.
- `openclaw gateway probe` → la cible gateway attendue est accessible (`Reachable: yes`). `RPC: limited - missing scope: operator.read` indique des diagnostics dégradés, pas un échec de connexion.
- `openclaw gateway status` → `Runtime: running` et `RPC probe: ok`.
- `openclaw gateway probe` → la cible Gateway attendue est joignable (`Reachable: yes`). `Capability: ...` indique quel niveau d’authentification la sonde a pu prouver, et `Read probe: limited - missing scope: operator.read` correspond à un diagnostic dégradé, pas à un échec de connexion.
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok`, et une ligne `Capability: ...` plausible. Utilisez `--require-rpc` si vous avez aussi besoin d’une preuve RPC à portée lecture.
- `openclaw doctor` → aucune erreur bloquante de configuration/service.
- `openclaw channels status --probe` → si le gateway est accessible, renvoie l’état de transport en direct par compte ainsi que les résultats de sonde/audit comme `works` ou `audit ok` ; si le gateway est inaccessible, la commande revient à des résumés basés uniquement sur la configuration.
- `openclaw logs --follow` → activité régulière, aucune erreur fatale répétée.
- `openclaw channels status --probe` → un gateway joignable renvoie l’état de transport en direct par compte
ainsi que les résultats des sondes/audits tels que `works` ou `audit ok` ; si le
gateway est inaccessible, la commande revient à des résumés basés uniquement sur la configuration.
- `openclaw logs --follow` → activité régulière, sans erreurs fatales répétées.
## 429 Anthropic sur contexte long
## 429 Anthropic sur un long contexte
Si vous voyez :
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`,
allez à [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/fr/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
## Le backend local compatible OpenAI fonctionne directement mais échoue dans OpenClaw
## Le backend local compatible OpenAI fonctionne en direct mais échoue dans OpenClaw
Si votre backend local ou auto-hébergé `/v1` répond à de petites sondes directes
`/v1/chat/completions` mais échoue sur `openclaw infer model run` ou sur des
`/v1/chat/completions` mais échoue avec `openclaw infer model run` ou pendant des
tours d’agent normaux :
1. Si l’erreur mentionne `messages[].content` qui attend une chaîne, définissez
1. Si l’erreur mentionne que `messages[].content` attend une chaîne, définissez
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
2. Si le backend échoue toujours uniquement sur les tours d’agent OpenClaw, définissez
`models.providers.<provider>.models[].compat.supportsTools: false` et réessayez.
3. Si de minuscules appels directs fonctionnent toujours mais que des prompts OpenClaw plus volumineux font planter le backend, traitez le problème restant comme une limitation amont du modèle/serveur et poursuivez dans le guide détaillé :
2. Si le backend échoue toujours uniquement pendant les tours d’agent OpenClaw, définissez
`models.providers.<provider>.models[].compat.supportsTools: false` puis réessayez.
3. Si de minuscules appels directs fonctionnent toujours mais que des prompts OpenClaw plus volumineux font planter le
backend, considérez le problème restant comme une limitation du modèle/serveur amont et
poursuivez dans le runbook détaillé :
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/fr/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
## L’installation du plugin échoue avec des extensions openclaw manquantes
## L’installation du Plugin échoue avec des extensions openclaw manquantes
Si l’installation échoue avec `package.json missing openclaw.extensions`, le package du plugin
utilise une ancienne forme qu’OpenClaw n’accepte plus.
Si l’installation échoue avec `package.json missing openclaw.extensions`, le package du Plugin
utilise une ancienne structure qu’OpenClaw n’accepte plus.
Corrigez dans le package du plugin :
Correction dans le package du Plugin :
1. Ajoutez `openclaw.extensions` à `package.json`.
2. Faites pointer les entrées vers les fichiers runtime compilés (généralement `./dist/index.js`).
3. Republiez le plugin et exécutez de nouveau `openclaw plugins install <package>`.
2. Faites pointer les entrées vers les fichiers d’exécution compilés (généralement `./dist/index.js`).
3. Republiez le Plugin et exécutez à nouveau `openclaw plugins install <package>`.
Exemple :
@ -91,20 +95,20 @@ Référence : [Architecture des plugins](/fr/plugins/architecture)
flowchart TD
A[OpenClaw ne fonctionne pas] --> B{Qu’est-ce qui casse en premier}
B --> C[Pas de réponses]
B --> D[Le tableau de bord ou la Control UI ne se connecte pas]
B --> E[Le Gateway ne démarre pas ou le service ne fonctionne pas]
B --> D[Le tableau de bord ou l’interface utilisateur de contrôle ne se connecte pas]
B --> E[Le Gateway ne démarre pas ou le service n’est pas en cours d’exécution]
B --> F[Le canal se connecte mais les messages ne circulent pas]
B --> G[Cron ou heartbeat ne s’est pas déclenché ou n’a rien livré]
B --> H[Le nœud est appairé mais l’exécution screen exec du canvas caméra échoue]
B --> I[L’outil navigateur échoue]
B --> G[Cron ou Heartbeat ne s’est pas déclenché ou n’a pas livré]
B --> H[Le Node est appairé mais l’exécution camera canvas screen échoue]
B --> I[L’outil browser échoue]
C --> C1[/Section Pas de réponses/]
D --> D1[/Section Control UI/]
D --> D1[/Section Interface utilisateur de contrôle/]
E --> E1[/Section Gateway/]
F --> F1[/Section Flux du canal/]
F --> F1[/Section Flux des canaux/]
G --> G1[/Section Automatisation/]
H --> H1[/Section Outils du nœud/]
I --> I1[/Section Navigateur/]
H --> H1[/Section Outils Node/]
I --> I1[/Section Browser/]
```
<AccordionGroup>
@ -120,15 +124,16 @@ flowchart TD
Un bon résultat ressemble à ceci :
- `Runtime: running`
- `RPC probe: ok`
- Votre canal affiche un transport connecté et, là où c’est pris en charge, `works` ou `audit ok` dans `channels status --probe`
- L’expéditeur apparaît comme approuvé (ou la politique de DM est ouverte / en allowlist)
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable`, ou `admin-capable`
- Votre canal affiche le transport connecté et, lorsque c’est pris en charge, `works` ou `audit ok` dans `channels status --probe`
- L’expéditeur apparaît comme approuvé (ou la politique DM est ouverte/avec liste d’autorisation)
Signatures de logs courantes :
Signatures de journaux courantes :
- `drop guild message (mention required` → le filtrage par mention a bloqué le message dans Discord.
- `pairing request` → l’expéditeur n’est pas approuvé et attend l’approbation de l’appairage DM.
- `blocked` / `allowlist` dans les logs du canal → l’expéditeur, le salon ou le groupe est filtré.
- `drop guild message (mention required` → la contrainte de mention a bloqué le message dans Discord.
- `pairing request` → l’expéditeur n’est pas approuvé et attend une approbation d’appairage DM.
- `blocked` / `allowlist` dans les journaux du canal → l’expéditeur, le salon ou le groupe est filtré.
Pages détaillées :
@ -138,7 +143,7 @@ flowchart TD
</Accordion>
<Accordion title="Le tableau de bord ou la Control UI ne se connecte pas">
<Accordion title="Le tableau de bord ou l’interface utilisateur de contrôle ne se connecte pas">
```bash
openclaw status
openclaw gateway status
@ -150,19 +155,26 @@ flowchart TD
Un bon résultat ressemble à ceci :
- `Dashboard: http://...` est affiché dans `openclaw gateway status`
- `RPC probe: ok`
- Aucune boucle d’authentification dans les logs
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable`, ou `admin-capable`
- Aucune boucle d’authentification dans les journaux
Signatures de logs courantes :
Signatures de journaux courantes :
- `device identity required` → le contexte HTTP / non sécurisé ne peut pas terminer l’authentification de l’appareil.
- `origin not allowed` → l’`Origin` du navigateur n’est pas autorisé pour la cible gateway de la Control UI.
- `AUTH_TOKEN_MISMATCH` avec des indications de nouvelle tentative (`canRetryWithDeviceToken=true`) → une nouvelle tentative avec un device token approuvé peut avoir lieu automatiquement.
- Cette nouvelle tentative avec token en cache réutilise l’ensemble de scopes mis en cache, stocké avec le device token appairé. Les appelants `deviceToken` explicites / `scopes` explicites conservent à la place l’ensemble de scopes demandé.
- Sur le chemin async Tailscale Serve de la Control UI, les tentatives échouées pour le même `{scope, ip}` sont sérialisées avant que le limiteur n’enregistre l’échec, donc une deuxième mauvaise tentative concurrente peut déjà afficher `retry later`.
- `too many failed authentication attempts (retry later)` depuis une origine de navigateur localhost → les échecs répétés depuis cette même `Origin` sont temporairement bloqués ; une autre origine localhost utilise un compartiment distinct.
- `unauthorized` répété après cette nouvelle tentative → mauvais token/mot de passe, incompatibilité de mode d’authentification ou device token appairé obsolète.
- `gateway connect failed:` → l’UI cible la mauvaise URL/le mauvais port ou un gateway inaccessible.
- `device identity required` → le contexte HTTP/non sécurisé ne peut pas terminer l’authentification de l’appareil.
- `origin not allowed` → l’`Origin` du navigateur n’est pas autorisé pour la
cible Gateway de l’interface utilisateur de contrôle.
- `AUTH_TOKEN_MISMATCH` avec des indications de nouvelle tentative (`canRetryWithDeviceToken=true`) → une nouvelle tentative avec un device token de confiance peut se produire automatiquement.
- Cette nouvelle tentative avec jeton en cache réutilise l’ensemble des portées en cache stocké avec le
device token appairé. Les appelants avec `deviceToken` explicite / `scopes` explicites conservent
plutôt l’ensemble de portées demandé.
- Sur le chemin asynchrone de l’interface utilisateur de contrôle Tailscale Serve, les tentatives échouées pour le même
`{scope, ip}` sont sérialisées avant que le limiteur n’enregistre l’échec ; ainsi, une
deuxième mauvaise tentative concurrente peut déjà afficher `retry later`.
- `too many failed authentication attempts (retry later)` depuis une origine de navigateur localhost
→ des échecs répétés depuis cette même `Origin` sont temporairement bloqués ; une autre origine localhost utilise un compartiment distinct.
- `repeated unauthorized` après cette nouvelle tentative → mauvais token/mot de passe, incompatibilité de mode d’authentification ou device token appairé obsolète.
- `gateway connect failed:` → l’interface cible la mauvaise URL/le mauvais port ou un gateway inaccessible.
Pages détaillées :
@ -172,7 +184,7 @@ flowchart TD
</Accordion>
<Accordion title="Le Gateway ne démarre pas ou le service est installé mais ne fonctionne pas">
<Accordion title="Le Gateway ne démarre pas ou le service est installé mais n’est pas en cours d’exécution">
```bash
openclaw status
openclaw gateway status
@ -185,13 +197,14 @@ flowchart TD
- `Service: ... (loaded)`
- `Runtime: running`
- `RPC probe: ok`
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable`, ou `admin-capable`
Signatures de logs courantes :
Signatures de journaux courantes :
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → le mode gateway est distant, ou le fichier de configuration n’a pas l’indication de mode local et doit être réparé.
- `refusing to bind gateway ... without auth` → liaison hors loopback sans chemin d’authentification gateway valide (token/mot de passe, ou trusted-proxy si configuré).
- `another gateway instance is already listening` ou `EADDRINUSE` → le port est déjà pris.
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → le mode gateway est distant, ou il manque le tampon de mode local dans le fichier de configuration et celui-ci doit être réparé.
- `refusing to bind gateway ... without auth` → liaison non-loopback sans chemin d’authentification gateway valide (token/mot de passe, ou trusted-proxy lorsque configuré).
- `another gateway instance is already listening` ou `EADDRINUSE` → port déjà utilisé.
Pages détaillées :
@ -213,14 +226,14 @@ flowchart TD
Un bon résultat ressemble à ceci :
- Le transport du canal est connecté.
- Les vérifications d’appairage / d’allowlist réussissent.
- Les mentions sont détectées lorsque nécessaire.
- Les vérifications d’appairage/liste d’autorisation réussissent.
- Les mentions sont détectées lorsque requis.
Signatures de logs courantes :
Signatures de journaux courantes :
- `mention required` → le filtrage par mention dans le groupe a bloqué le traitement.
- `mention required` → la contrainte de mention de groupe a bloqué le traitement.
- `pairing` / `pending` → l’expéditeur du DM n’est pas encore approuvé.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problème de permissions du canal ou du token.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problème de jeton d’autorisation du canal.
Pages détaillées :
@ -229,7 +242,7 @@ flowchart TD
</Accordion>
<Accordion title="Cron ou heartbeat ne s’est pas déclenché ou n’a rien livré">
<Accordion title="Cron ou Heartbeat ne s’est pas déclenché ou n’a pas livré">
```bash
openclaw status
openclaw gateway status
@ -241,19 +254,19 @@ flowchart TD
Un bon résultat ressemble à ceci :
- `cron.status` indique qu’il est activé avec un prochain réveil.
- `cron runs` montre des entrées récentes `ok`.
- Heartbeat est activé et n’est pas en dehors des heures actives.
- `cron.status` indique activé avec un prochain réveil.
- `cron runs` affiche des entrées récentes `ok`.
- Heartbeat est activé et n’est pas hors des heures actives.
Signatures de logs courantes :
Signatures de journaux courantes :
- `cron: scheduler disabled; jobs will not run automatically` → cron est désactivé.
- `cron: scheduler disabled; jobs will not run automatically` → Cron est désactivé.
- `heartbeat skipped` avec `reason=quiet-hours` → en dehors des heures actives configurées.
- `heartbeat skipped` avec `reason=empty-heartbeat-file` → `HEARTBEAT.md` existe mais ne contient qu’une structure vide ou uniquement des en-têtes.
- `heartbeat skipped` avec `reason=empty-heartbeat-file` → `HEARTBEAT.md` existe mais ne contient qu’une structure vide/ou seulement des en-têtes.
- `heartbeat skipped` avec `reason=no-tasks-due` → le mode tâche de `HEARTBEAT.md` est actif mais aucun intervalle de tâche n’est encore arrivé à échéance.
- `heartbeat skipped` avec `reason=alerts-disabled` → toute la visibilité heartbeat est désactivée (`showOk`, `showAlerts` et `useIndicator` sont tous désactivés).
- `requests-in-flight` → la voie principale est occupée ; le réveil heartbeat a été différé.
- `unknown accountId` → le compte cible de livraison heartbeat n’existe pas.
- `heartbeat skipped` avec `reason=alerts-disabled` → toute la visibilité Heartbeat est désactivée (`showOk`, `showAlerts` et `useIndicator` sont tous désactivés).
- `requests-in-flight` → voie principale occupée ; le réveil Heartbeat a été différé.
- `unknown accountId` → le compte cible de livraison Heartbeat n’existe pas.
Pages détaillées :
@ -263,7 +276,7 @@ flowchart TD
</Accordion>
<Accordion title="Le nœud est appairé mais l’outil échoue sur camera canvas screen exec">
<Accordion title="Le Node est appairé mais l’outil échoue sur camera canvas screen exec">
```bash
openclaw status
openclaw gateway status
@ -274,16 +287,16 @@ flowchart TD
Un bon résultat ressemble à ceci :
- Le nœud apparaît comme connecté et appairé pour le rôle `node`.
- Le Node est répertorié comme connecté et appairé pour le rôle `node`.
- La capacité existe pour la commande que vous invoquez.
- L’état de permission est accordé pour l’outil.
- L’état d’autorisation est accordé pour l’outil.
Signatures de logs courantes :
Signatures de journaux courantes :
- `NODE_BACKGROUND_UNAVAILABLE` → amenez l’application du nœud au premier plan.
- `*_PERMISSION_REQUIRED` → la permission du système d’exploitation a été refusée ou est manquante.
- `NODE_BACKGROUND_UNAVAILABLE` → faites passer l’application node au premier plan.
- `*_PERMISSION_REQUIRED` → l’autorisation OS a été refusée/manque.
- `SYSTEM_RUN_DENIED: approval required` → l’approbation d’exécution est en attente.
- `SYSTEM_RUN_DENIED: allowlist miss` → la commande n’est pas dans l’allowlist d’exécution.
- `SYSTEM_RUN_DENIED: allowlist miss` → la commande n’est pas dans la liste d’autorisation d’exécution.
Pages détaillées :
@ -304,11 +317,11 @@ flowchart TD
Ce qui a changé :
- Si `tools.exec.host` n’est pas défini, la valeur par défaut est `auto`.
- `host=auto` se résout en `sandbox` lorsqu’un runtime sandbox est actif, sinon en `gateway`.
- `host=auto` ne gère que le routage ; le comportement sans invite « YOLO » vient de `security=full` plus `ask=off` sur gateway/node.
- Sur `gateway` et `node`, si `tools.exec.security` n’est pas défini, la valeur par défaut est `full`.
- Si `tools.exec.ask` n’est pas défini, la valeur par défaut est `off`.
- Résultat : si vous voyez des approbations, une politique locale à l’hôte ou propre à la session a renforcé exec par rapport aux valeurs par défaut actuelles.
- `host=auto` se résout vers `sandbox` lorsqu’un environnement d’exécution sandbox est actif, sinon vers `gateway`.
- `host=auto` ne concerne que le routage ; le comportement sans invite « YOLO » vient de `security=full` plus `ask=off` sur gateway/node.
- Sur `gateway` et `node`, `tools.exec.security` non défini vaut par défaut `full`.
- `tools.exec.ask` non défini vaut par défaut `off`.
- Résultat : si vous voyez des demandes d’approbation, une politique locale à l’hôte ou propre à la session a durci exec par rapport aux valeurs par défaut actuelles.
Restaurer le comportement actuel par défaut sans approbation :
@ -321,15 +334,15 @@ flowchart TD
Alternatives plus sûres :
- Définissez uniquement `tools.exec.host=gateway` si vous voulez seulement un routage hôte stable.
- Utilisez `security=allowlist` avec `ask=on-miss` si vous voulez l’exécution sur l’hôte tout en conservant une revue lors des absences dans l’allowlist.
- Définissez uniquement `tools.exec.host=gateway` si vous voulez simplement un routage hôte stable.
- Utilisez `security=allowlist` avec `ask=on-miss` si vous voulez l’exécution sur l’hôte tout en conservant une revue en cas d’absence dans la liste d’autorisation.
- Activez le mode sandbox si vous voulez que `host=auto` se résolve de nouveau vers `sandbox`.
Signatures de logs courantes :
Signatures de journaux courantes :
- `Approval required.` → la commande attend `/approve ...`.
- `SYSTEM_RUN_DENIED: approval required` → l’approbation de l’exécution exec sur l’hôte du nœud est en attente.
- `exec host=sandbox requires a sandbox runtime for this session` → sélection implicite/explicite du sandbox alors que le mode sandbox est désactivé.
- `SYSTEM_RUN_DENIED: approval required` → l’approbation de l’exécution sur l’hôte node est en attente.
- `exec host=sandbox requires a sandbox runtime for this session` → sélection sandbox implicite/explicite alors que le mode sandbox est désactivé.
Pages détaillées :
@ -339,7 +352,7 @@ flowchart TD
</Accordion>
<Accordion title="L’outil navigateur échoue">
<Accordion title="L’outil browser échoue">
```bash
openclaw status
openclaw gateway status
@ -350,10 +363,10 @@ flowchart TD
Un bon résultat ressemble à ceci :
- L’état du navigateur affiche `running: true` et un navigateur/profil choisi.
- L’état du browser affiche `running: true` ainsi qu’un navigateur/profil sélectionné.
- `openclaw` démarre, ou `user` peut voir les onglets Chrome locaux.
Signatures de logs courantes :
Signatures de journaux courantes :
- `unknown command "browser"` ou `unknown command 'browser'` → `plugins.allow` est défini et n’inclut pas `browser`.
- `Failed to start Chrome CDP on port` → le lancement du navigateur local a échoué.
@ -361,9 +374,9 @@ flowchart TD
- `browser.cdpUrl must be http(s) or ws(s)` → l’URL CDP configurée utilise un schéma non pris en charge.
- `browser.cdpUrl has invalid port` → l’URL CDP configurée a un port incorrect ou hors plage.
- `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` → l’endpoint CDP distant configuré n’est pas accessible depuis cet hôte.
- `Browser attachOnly is enabled ... not reachable` ou `Browser attachOnly is enabled and CDP websocket ... is not reachable` → le profil attach-only n’a pas de cible CDP active.
- remplacements obsolètes de viewport / mode sombre / langue / 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 sans redémarrer le gateway.
- `Remote CDP for profile "<name>" is not reachable` → l’endpoint CDP distant configuré n’est pas joignable depuis cet hôte.
- `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 CDP active.
- remplacements obsolètes 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 sans redémarrer le gateway.
Pages détaillées :
@ -376,10 +389,10 @@ flowchart TD
</AccordionGroup>
## Liens associés
## Associé
- [FAQ](/fr/help/faq) — questions fréquemment posées
- [Dépannage du Gateway](/fr/gateway/troubleshooting) — problèmes spécifiques au gateway
- [Doctor](/fr/gateway/doctor) — vérifications automatiques de l’état et réparations
- [Dépannage Gateway](/fr/gateway/troubleshooting) — problèmes spécifiques au Gateway
- [Doctor](/fr/gateway/doctor) — vérifications automatiques de l’état de santé et réparations
- [Dépannage des canaux](/fr/channels/troubleshooting) — problèmes de connectivité des canaux
- [Dépannage de l’automatisation](/fr/automation/cron-jobs#troubleshooting) — problèmes de cron et heartbeat
- [Dépannage de l’automatisation](/fr/automation/cron-jobs#troubleshooting) — problèmes de Cron et Heartbeat

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

@ -1,15 +1,15 @@
---
read_when:
- 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 du navigateur + du cycle de vie dans l’app macOS
summary: Service de contrôle de navigateur intégré + commandes d’action
- Débogage pour comprendre 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 de contrôle intégré du navigateur + commandes d’action
title: Navigateur (géré par OpenClaw)
x-i18n:
generated_at: "2026-04-14T13:04:20Z"
generated_at: "2026-04-20T07:06:21Z"
model: gpt-5.4
provider: openai
source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2
source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b
source_path: tools/browser.md
workflow: 15
---
@ -17,24 +17,24 @@ x-i18n:
# Navigateur (géré par openclaw)
OpenClaw peut exécuter un **profil Chrome/Brave/Edge/Chromium dédié** que l’agent contrôle.
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).
Il est isolé de votre navigateur personnel et géré via un petit service local de
contrôle à l’intérieur de Gateway (loopback uniquement).
Vue débutant :
- Voyez-le comme un **navigateur séparé, réservé à l’agent**.
- Le profil `openclaw` ne **modifie pas** le profil de votre navigateur personnel.
- L’agent peut **ouvrir des onglets, lire des pages, cliquer et saisir du texte** dans un environnement sûr.
- Le profil intégré `user` se rattache à votre vraie session Chrome connectée via Chrome MCP.
- Considérez-le comme un **navigateur distinct, réservé à l’agent**.
- Le profil `openclaw` ne **touche pas** au profil de votre navigateur personnel.
- L’agent peut **ouvrir des onglets, lire des pages, cliquer et saisir du texte** dans une voie sûre.
- Le profil intégré `user` se rattache à votre véritable session Chrome connectée via Chrome MCP.
## Ce que vous obtenez
- Un profil de navigateur distinct nommé **openclaw** (accent orange par défaut).
- Un contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
- Actions de l’agent (cliquer/saisir/faire glisser/sélectionner), instantanés, captures d’écran, PDF.
- Actions de l’agent (cliquer/saisir/glisser/sélectionner), instantanés, captures d’écran, PDF.
- 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
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
@ -46,17 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
Si vous obtenez « Browser disabled », activez-le dans la config (voir ci-dessous) et redémarrez le
Si vous obtenez « Browser disabled », activez-le dans la configuration (voir ci-dessous) puis redémarrez
Gateway.
Si `openclaw browser` est totalement absent, ou si l’agent indique que l’outil de navigateur
est indisponible, allez à [Commande ou outil navigateur manquant](/fr/tools/browser#missing-browser-command-or-tool).
n’est pas disponible, passez à [Commande ou outil navigateur manquant](/fr/tools/browser#missing-browser-command-or-tool).
## Contrôle du Plugin
L’outil `browser` par défaut est maintenant un Plugin intégré livré activé par
défaut. Cela signifie que vous pouvez le désactiver ou le remplacer sans supprimer le reste du
système de plugins d’OpenClaw :
L’outil `browser` par défaut est maintenant un Plugin groupé livré activé par
défaut. Cela signifie que vous pouvez le désactiver ou le remplacer sans retirer le reste du
système de Plugin d’OpenClaw :
```json5
{
@ -70,24 +70,24 @@ système de plugins d’OpenClaw :
}
```
Désactivez le Plugin intégré avant d’installer un autre Plugin qui fournit le
Désactivez le Plugin groupé avant d’installer un autre Plugin qui fournit le
même nom d’outil `browser`. L’expérience de navigateur par défaut nécessite les deux éléments suivants :
- `plugins.entries.browser.enabled` non désactivé
- `browser.enabled=true`
Si vous désactivez uniquement le Plugin, la CLI de navigateur intégrée (`openclaw browser`),
la méthode gateway (`browser.request`), l’outil agent et le service de contrôle de navigateur par défaut
disparaissent tous ensemble. Votre config `browser.*` reste intacte pour qu’un
Plugin de remplacement puisse la réutiliser.
Si vous désactivez uniquement le Plugin, la CLI de navigateur groupée (`openclaw browser`),
la méthode Gateway (`browser.request`), l’outil de l’agent et le service de contrôle
du navigateur par défaut disparaissent tous ensemble. Votre configuration `browser.*` reste intacte pour
qu’un Plugin de remplacement puisse la réutiliser.
Le Plugin de navigateur intégré possède maintenant aussi l’implémentation d’exécution du navigateur.
Le cœur ne conserve que les assistants partagés du Plugin SDK ainsi que des réexportations de compatibilité pour
les anciens chemins d’import internes. En pratique, supprimer ou remplacer le package du Plugin navigateur
supprime l’ensemble des fonctionnalités du navigateur au lieu de laisser derrière lui une seconde
implémentation d’exécution gérée par le cœur.
Le Plugin de navigateur groupé est aussi désormais propriétaire de l’implémentation d’exécution du navigateur.
Le cœur ne conserve que les helpers partagés du Plugin SDK ainsi que des réexportations de compatibilité pour
les anciens chemins d’import internes. En pratique, retirer ou remplacer le package du Plugin de navigateur
supprime l’ensemble des fonctionnalités navigateur au lieu de laisser derrière lui une seconde exécution
gérée par le cœur.
Les changements de configuration du navigateur nécessitent toujours un redémarrage du Gateway afin que le Plugin intégré
Les changements de configuration du navigateur nécessitent toujours un redémarrage de Gateway afin que le Plugin groupé
puisse réenregistrer son service de navigateur avec les nouveaux paramètres.
## Commande ou outil navigateur manquant
@ -96,7 +96,7 @@ Si `openclaw browser` devient soudainement une commande inconnue après une mise
si l’agent signale que l’outil navigateur est manquant, la cause la plus fréquente est une liste
`plugins.allow` restrictive qui n’inclut pas `browser`.
Exemple de configuration défaillante :
Exemple de configuration cassée :
```json5
{
@ -116,12 +116,12 @@ Corrigez-la en ajoutant `browser` à la liste d’autorisation des plugins :
}
```
Remarques importantes :
Notes importantes :
- `browser.enabled=true` ne suffit pas à lui seul lorsque `plugins.allow` est défini.
- `plugins.entries.browser.enabled=true` ne suffit pas non plus à lui seul lorsque `plugins.allow` est défini.
- `tools.alsoAllow: ["browser"]` ne charge **pas** le Plugin navigateur intégré. Cela ajuste seulement la politique des outils une fois le Plugin déjà chargé.
- Si vous n’avez pas besoin d’une liste d’autorisation de plugins restrictive, supprimer `plugins.allow` rétablit également le comportement par défaut du navigateur intégré.
- `tools.alsoAllow: ["browser"]` ne charge **pas** le Plugin de navigateur groupé. Cela ajuste seulement la politique des outils une fois le Plugin déjà chargé.
- Si vous n’avez pas besoin d’une liste d’autorisation de plugins restrictive, supprimer `plugins.allow` rétablit aussi le comportement groupé par défaut du navigateur.
Symptômes typiques :
@ -132,14 +132,14 @@ Symptômes typiques :
## Profils : `openclaw` vs `user`
- `openclaw` : navigateur géré et isolé (aucune extension requise).
- `user` : profil intégré de rattachement Chrome MCP à votre **vraie session Chrome connectée**.
- `user` : profil intégré de rattachement Chrome MCP pour votre **véritable session Chrome connectée**.
Pour les appels d’outil navigateur de l’agent :
Pour les appels à l’outil navigateur de l’agent :
- Par défaut : utiliser le navigateur isolé `openclaw`.
- Préférez `profile="user"` lorsque des sessions déjà connectées importent et que l’utilisateur
est devant l’ordinateur pour cliquer/approuver toute invite de rattachement.
- `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 les sessions déjà connectées sont importantes et que l’utilisateur
est à l’ordinateur pour cliquer/approuver toute invite de rattachement.
- `profile` est la dérogation explicite lorsque vous souhaitez un mode de navigateur précis.
Définissez `browser.defaultProfile: "openclaw"` si vous voulez le mode géré par défaut.
@ -150,16 +150,16 @@ Les paramètres du navigateur se trouvent dans `~/.openclaw/openclaw.json`.
```json5
{
browser: {
enabled: true, // défaut : true
enabled: true, // default: true
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // activez uniquement pour un accès réseau privé de confiance
// allowPrivateNetwork: true, // alias historique
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
// allowPrivateNetwork: true, // legacy alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
// cdpUrl: "http://127.0.0.1:18792", // surcharge historique à profil unique
remoteCdpTimeoutMs: 1500, // délai d’expiration HTTP CDP distant (ms)
remoteCdpHandshakeTimeoutMs: 3000, // délai d’expiration de la poignée de main WebSocket CDP distante (ms)
// 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)
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@ -186,33 +186,33 @@ Les paramètres du navigateur se trouvent dans `~/.openclaw/openclaw.json`.
}
```
Remarques :
Notes :
- Le service de contrôle du navigateur se lie au loopback sur un port dérivé de `gateway.port`
- Le service de contrôle du navigateur se lie à loopback sur un port dérivé de `gateway.port`
(par défaut : `18791`, soit gateway + 2).
- Si vous surchargez le port du Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
les ports du navigateur dérivés se décalent pour rester dans la même « famille ».
- Si vous redéfinissez le port Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
les ports de navigateur dérivés se décalent pour rester dans la même « famille ».
- `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é CDP distantes (hors loopback).
- `remoteCdpHandshakeTimeoutMs` s’applique aux vérifications d’accessibilité WebSocket CDP distantes.
- La navigation/ouverture d’onglet du navigateur est protégée contre la SSRF avant la navigation et revérifiée au mieux sur l’URL finale `http(s)` après navigation.
- En mode SSRF strict, la découverte/les sondes de points de terminaison CDP distants (`cdpUrl`, y compris les recherches `/json/version`) sont également vérifiées.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé par défaut. Définissez-le sur `true` uniquement lorsque vous faites intentionnellement confiance à l’accès navigateur au réseau privé.
- `browser.ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias historique pour compatibilité.
- `attachOnly: true` signifie « ne jamais lancer un navigateur local ; se rattacher uniquement s’il est déjà en cours d’exécution ».
- `color` + `color` par profil teintent l’interface du navigateur afin que vous puissiez voir quel profil est actif.
- Le profil par défaut est `openclaw` (navigateur autonome géré par OpenClaw). Utilisez `defaultProfile: "user"` pour opter pour le navigateur utilisateur connecté.
- `remoteCdpTimeoutMs` s’applique aux vérifications de joignabilité CDP distantes (hors loopback).
- `remoteCdpHandshakeTimeoutMs` s’applique aux vérifications de joignabilité de handshake WebSocket CDP distantes.
- La navigation du navigateur et l’ouverture d’onglet sont protégées contre la SSRF avant la navigation et revérifiées au mieux sur l’URL finale `http(s)` après navigation.
- En mode SSRF strict, la découverte et les sondes des points de terminaison CDP distants (`cdpUrl`, y compris les recherches `/json/version`) sont aussi vérifiées.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` est désactivé par défaut. Définissez-le sur `true` uniquement lorsque vous faites délibérément confiance à l’accès navigateur sur réseau privé.
- `browser.ssrfPolicy.allowPrivateNetwork` reste pris en charge comme alias hérité pour compatibilité.
- `attachOnly: true` signifie « ne jamais lancer un navigateur local ; s’y rattacher uniquement s’il est déjà en cours d’exécution ».
- `color` + la `color` par profil teintent l’interface du navigateur afin que vous puissiez voir quel profil est actif.
- Le profil par défaut est `openclaw` (navigateur autonome géré par OpenClaw). Utilisez `defaultProfile: "user"` pour choisir le navigateur connecté de l’utilisateur.
- Ordre d’auto-détection : navigateur système par défaut s’il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
- Les profils `openclaw` locaux assignent automatiquement `cdpPort`/`cdpUrl` — définissez-les uniquement pour le CDP distant.
- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu du CDP brut. Ne
- Les profils `openclaw` locaux attribuent automatiquement `cdpPort`/`cdpUrl` — définissez-les uniquement pour CDP distant.
- `driver: "existing-session"` utilise Chrome DevTools MCP au lieu de CDP brut. Ne
définissez pas `cdpUrl` pour ce driver.
- Définissez `browser.profiles.<name>.userDataDir` lorsqu’un profil existing-session
doit se rattacher à un profil utilisateur Chromium non par défaut comme Brave ou Edge.
doit se rattacher à un profil utilisateur Chromium non par défaut, comme Brave ou Edge.
## Utiliser Brave (ou un autre navigateur basé sur Chromium)
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 surcharger
Si votre navigateur **système par défaut** est basé sur Chromium (Chrome/Brave/Edge/etc),
OpenClaw l’utilise automatiquement. Définissez `browser.executablePath` pour redéfinir
l’auto-détection :
Exemple CLI :
@ -246,51 +246,51 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
## 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 du navigateur.
- **Contrôle local (par défaut) :** 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 ; Gateway y relaie les actions du navigateur.
- **CDP distant :** définissez `browser.profiles.<name>.cdpUrl` (ou `browser.cdpUrl`) pour
vous rattacher à 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 du profil :
Le comportement d’arrêt diffère selon le mode du profil :
- profils gérés locaux : `openclaw browser stop` arrête le processus de navigateur que
OpenClaw a lancé
- profils attach-only et 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 état similaire), même
- profils attach-only et CDP distants : `openclaw browser stop` ferme la session de
contrôle active et libère les dérogations d’émulation Playwright/CDP (viewport,
schéma de couleurs, locale, fuseau horaire, mode hors ligne et états similaires), même
si aucun processus de navigateur n’a été lancé par OpenClaw
Les URL CDP distantes peuvent inclure une authentification :
- Jetons de requête (par ex., `https://provider.example?token=<token>`)
- Auth HTTP Basic (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 lors des appels aux points de terminaison `/json/*` et lors de la connexion
au WebSocket CDP. Préférez les variables d’environnement ou les gestionnaires de secrets pour les
jetons plutôt que de les valider dans des fichiers de configuration.
jetons au lieu de les versionner dans les fichiers de configuration.
## Proxy navigateur node (par défaut sans configuration)
## Proxy de navigateur node (valeur par défaut sans configuration)
Si vous exécutez un **hôte node** sur la machine qui possède votre navigateur, OpenClaw peut
acheminer automatiquement les appels d’outil navigateur vers ce node sans configuration de navigateur supplémentaire.
C’est le chemin par défaut pour les gateways distants.
rediriger automatiquement les appels à l’outil navigateur vers ce node sans configuration de navigateur supplémentaire.
C’est le chemin par défaut pour les Gateway distants.
Remarques :
Notes :
- L’hôte node expose son serveur local de contrôle du navigateur via une **commande proxy**.
- Les profils proviennent de la propre config `browser.profiles` du node (identique au mode local).
- `nodeHost.browserProxy.allowProfiles` est facultatif. Laissez-le vide pour le comportement historique/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 limite 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 du proxy.
- Désactivez-le si vous n’en voulez pas :
- 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 profils.
- 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 profils sont bloquées sur la surface du proxy.
- Désactivez-le si vous ne le voulez pas :
- Sur le node : `nodeHost.browserProxy.enabled=false`
- Sur la 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 les deux formes, mais
[Browserless](https://browserless.io) est un service Chromium hébergé qui expose des
URL de connexion CDP en 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 de Browserless.
figurant dans la documentation de connexion de Browserless.
Exemple :
@ -311,9 +311,9 @@ Exemple :
}
```
Remarques :
Notes :
- Remplacez `<BROWSERLESS_API_KEY>` par votre vrai jeton Browserless.
- Remplacez `<BROWSERLESS_API_KEY>` par votre véritable jeton Browserless.
- 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
@ -322,18 +322,34 @@ Remarques :
## Fournisseurs CDP WebSocket directs
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 prend en charge les deux :
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 :
- **Points de terminaison HTTP(S)** — OpenClaw appelle `/json/version` pour découvrir l’URL WebSocket du débogueur, puis s’y connecte.
- **Points de terminaison WebSocket** (`ws://` / `wss://`) — OpenClaw se connecte directement, en ignorant `/json/version`. Utilisez cette option pour des services comme
[Browserless](https://browserless.io),
[Browserbase](https://www.browserbase.com), ou tout fournisseur qui vous fournit une
URL WebSocket.
- **Découverte HTTP(S)** — `http://host[:port]` ou `https://host[:port]`.
OpenClaw appelle `/json/version` pour découvrir l’URL WebSocket du débogueur, puis
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 un handshake WebSocket et ignore
entièrement `/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 tente d’abord une 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
se replie sur un handshake WebSocket direct à la racine nue. Cela couvre
à la fois les ports de débogage distant de type Chrome et les fournisseurs uniquement WebSocket.
Le format simple `ws://host:port` / `wss://host:port` sans chemin `/devtools/...`
pointant vers une instance locale de Chrome est pris en charge via le repli
avec découverte d’abord — Chrome n’accepte les upgrades WebSocket que sur le chemin spécifique
par navigateur ou par cible renvoyé par `/json/version`, donc un simple handshake à la racine
échouerait.
### Browserbase
[Browserbase](https://www.browserbase.com) est une plateforme cloud permettant d’exécuter
des navigateurs headless avec résolution CAPTCHA intégrée, mode furtif et proxys
[Browserbase](https://www.browserbase.com) est une plateforme cloud permettant d’exécuter des
navigateurs headless avec résolution CAPTCHA intégrée, mode furtif et proxys
résidentiels.
```json5
@ -353,38 +369,38 @@ résidentiels.
}
```
Remarques :
Notes :
- [Inscrivez-vous](https://www.browserbase.com/sign-up) puis 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.
- Remplacez `<BROWSERBASE_API_KEY>` par votre véritable clé API Browserbase.
- 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.
- L’offre gratuite autorise une session simultanée et une heure de navigateur par mois.
- L’offre gratuite 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.
complète, les guides SDK et des exemples d’intégration.
## Sécurité
Idées clés :
- Le contrôle du navigateur est limité au loopback ; l’accès passe par l’authentification du Gateway ou l’appairage du node.
- Le contrôle du navigateur est limité au loopback ; l’accès passe par l’authentification Gateway ou l’appairage node.
- L’API HTTP autonome du navigateur en loopback utilise **uniquement une authentification par secret partagé** :
auth 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"` ne
**n’authentifient pas** cette API autonome du navigateur en loopback.
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 en 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 config.
- OpenClaw ne **génère pas automatiquement** ce jeton lorsque `gateway.auth.mode` vaut 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.
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` est
déjà `password`, `none` ou `trusted-proxy`.
- Conservez Gateway et tout hôte node sur un réseau privé (Tailscale) ; évitez toute exposition publique.
- Traitez les URL/jetons CDP distants comme des secrets ; préférez les variables d’environnement ou un gestionnaire de secrets.
Conseils CDP distants :
Conseils pour 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 des points de terminaison chiffrés (HTTPS ou WSS) et des jetons de courte durée quand c’est possible.
- Évitez d’intégrer directement des jetons de longue durée dans les fichiers de configuration.
## Profils (multi-navigateur)
@ -392,26 +408,26 @@ Conseils CDP distants :
OpenClaw prend en charge plusieurs profils nommés (configurations de routage). Les profils peuvent être :
- **gérés par openclaw** : une instance de navigateur dédiée basée 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
- **distant** : 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 :
- Le profil `openclaw` est créé automatiquement s’il est absent.
- Le profil `user` est intégré pour le rattachement existing-session Chrome MCP.
- Les profils existing-session sont optionnels 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 local de données vers la corbeille.
- Le profil `openclaw` est créé automatiquement s’il manque.
- Le profil `user` est intégré pour le rattachement à une session existante via Chrome MCP.
- Les profils de session existante sont facultatifs au-delà de `user` ; créez-les avec `--driver existing-session`.
- Les ports CDP locaux sont alloués par défaut dans la plage **18800–18899**.
- 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>` ; la CLI utilise `--browser-profile`.
## Existing-session via Chrome DevTools MCP
## Session existante via Chrome DevTools MCP
OpenClaw peut également se rattacher à un profil de navigateur basé sur Chromium déjà en cours d’exécution via le
OpenClaw peut aussi se rattacher à un profil de navigateur déjà en cours d’exécution basé sur Chromium 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 de contexte et de configuration :
Références officielles pour le contexte et l’installation :
- [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)
@ -420,12 +436,12 @@ Profil intégré :
- `user`
Facultatif : créez votre propre profil existing-session personnalisé si vous souhaitez un
nom, une couleur ou un répertoire de données de navigateur différent.
Facultatif : créez votre propre profil de session existante si vous souhaitez un
nom, une couleur ou un répertoire de données du navigateur différents.
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 :
@ -445,11 +461,11 @@ 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. Laissez le navigateur en cours d’exécution et approuvez l’invite de connexion quand OpenClaw se rattache.
1. Ouvrez la page d’inspection de ce navigateur pour le débogage distant.
2. Activez le débogage distant.
3. Gardez le navigateur en cours d’exécution et approuvez l’invite de connexion lorsque OpenClaw s’y rattache.
Pages d’inspection courantes :
@ -457,7 +473,7 @@ Pages d’inspection courantes :
- Brave : `brave://inspect/#remote-debugging`
- Edge : `edge://inspect/#remote-debugging`
Test rapide de rattachement en direct :
Smoke test d’attachement live :
```bash
openclaw browser --browser-profile user start
@ -466,73 +482,75 @@ openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
À quoi ressemble un succès :
À quoi ressemble un rattachement réussi :
- `status` affiche `driver: existing-session`
- `status` affiche `transport: chrome-mcp`
- `status` affiche `running: true`
- `tabs` liste vos onglets de navigateur déjà ouverts
- `snapshot` renvoie des refs depuis l’onglet actif sélectionné
- `tabs` liste les onglets déjà ouverts dans votre navigateur
- `snapshot` renvoie des références depuis l’onglet live sélectionné
Que vérifier si le rattachement ne fonctionne pas :
Points à vérifier si le rattachement ne fonctionne pas :
- 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 débogage distant est activé dans la page d’inspection de ce navigateur
- le navigateur a affiché l’invite de consentement au rattachement 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 de connexion automatique par défaut, mais il ne peut
pas activer le débogage à distance côté navigateur à votre place
Chrome est installé localement pour les profils d’auto-connexion par défaut, mais il ne peut pas
activer pour vous le débogage distant côté navigateur
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.
- Choisissez ce mode uniquement lorsque l’utilisateur est devant l’ordinateur pour approuver l’invite
- Utilisez `profile="user"` lorsque vous avez besoin de l’état connecté du navigateur de l’utilisateur.
- Si vous utilisez un profil de session existante personnalisé, transmettez ce nom de profil explicite.
- Choisissez ce mode uniquement lorsque l’utilisateur est à l’ordinateur pour approuver l’invite
de rattachement.
- le Gateway ou l’hôte node peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
- Gateway ou l’hôte node peut lancer `npx chrome-devtools-mcp@latest --autoConnect`
Remarques :
Notes :
- Cette voie présente plus de risques que le profil isolé `openclaw` parce qu’elle peut
- Ce chemin est plus risqué que le profil isolé `openclaw` car il peut
agir dans votre session de navigateur connectée.
- OpenClaw ne lance pas le navigateur pour ce driver ; il se rattache uniquement à une
session existante.
- OpenClaw utilise ici le flux officiel Chrome DevTools MCP `--autoConnect`. Si
- OpenClaw utilise ici le flux officiel `--autoConnect` de Chrome DevTools MCP. Si
`userDataDir` est défini, OpenClaw le transmet pour cibler explicitement ce
répertoire de données utilisateur Chromium.
- Les captures d’écran existing-session prennent en charge les captures de page et les captures d’élément `--ref`
issues de la sortie de snapshot, mais pas les sélecteurs CSS `--element`.
- Les captures d’écran de page existing-session fonctionnent sans Playwright via Chrome MCP.
Les captures d’élément par ref (`--ref`) y fonctionnent aussi, mais `--full-page`
- Les captures d’écran en session existante prennent en charge les captures de page et les captures d’élément `--ref`
depuis les instantanés, mais pas les sélecteurs CSS `--element`.
- Les captures d’écran de page en session existante fonctionnent sans Playwright via Chrome MCP.
Les captures d’élément basées sur une référence (`--ref`) y fonctionnent aussi, mais `--full-page`
ne peut pas être combiné avec `--ref` ou `--element`.
- Les actions existing-session restent plus limitées que le chemin du navigateur
géré :
- `click`, `type`, `hover`, `scrollIntoView`, `drag`, et `select` exigent
des refs de snapshot plutôt que des sélecteurs CSS
- `click` est limité au bouton gauche (pas de surcharge du bouton ni de modificateurs)
- Les actions en session existante restent plus limitées que dans le
chemin du navigateur géré :
- `click`, `type`, `hover`, `scrollIntoView`, `drag` et `select` exigent
des références d’instantané au lieu de sélecteurs CSS
- `click` fonctionne uniquement avec le bouton gauche (pas de redéfinition de bouton ni de modificateurs)
- `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 les surcharges de délai d’expiration par appel
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` et `evaluate` ne
prennent pas en charge les redéfinitions de délai d’attente par appel
- `select` ne prend actuellement en charge qu’une seule valeur
- Existing-session `wait --url` prend en charge les motifs exacts, par sous-chaîne et glob
- `wait --url` en session existante prend en charge les motifs exacts, sous-chaîne et glob
comme les autres drivers de navigateur. `wait --load networkidle` n’est pas encore pris en charge.
- Les hooks de téléversement existing-session exigent `ref` ou `inputRef`, prennent en charge un seul fichier à la fois et ne prennent pas en charge le ciblage CSS `element`.
- Les hooks de boîte de dialogue existing-session ne prennent pas en charge les surcharges de délai d’expiration.
- Certaines fonctionnalités nécessitent encore le chemin du navigateur géré, notamment les
actions par lot, l’export PDF, l’interception des téléchargements et `responsebody`.
- Existing-session est local à l’hôte. Si Chrome se trouve sur une autre machine ou dans un
autre espace de noms réseau, utilisez plutôt le CDP distant ou un hôte node.
- Les hooks d’upload en session existante exigent `ref` ou `inputRef`, prennent en charge un seul fichier
à la fois et ne prennent pas en charge le ciblage CSS `element`.
- Les hooks de boîte de dialogue en session existante ne prennent pas en charge les redéfinitions de délai d’attente.
- Certaines fonctionnalités exigent encore le chemin du navigateur géré, notamment les actions par lot,
l’export PDF, l’interception des téléchargements et `responsebody`.
- La session existante peut se rattacher sur l’hôte sélectionné ou via un node
de navigateur connecté. Si Chrome se trouve ailleurs et qu’aucun node de navigateur n’est connecté, utilisez
plutôt CDP distant ou un hôte node.
## 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** : ciblez les onglets par `targetId`, pas par « dernier onglet ».
- **Répertoire de données utilisateur dédié** : ne touche jamais au profil de votre 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`, et non par « dernier onglet ».
## Sélection du navigateur
Lors du lancement local, OpenClaw choisit le premier disponible :
Lors d’un lancement local, OpenClaw choisit le premier disponible :
1. Chrome
2. Brave
@ -540,7 +558,7 @@ Lors du lancement local, OpenClaw choisit le premier disponible :
4. Chromium
5. Chrome Canary
Vous pouvez surcharger cela avec `browser.executablePath`.
Vous pouvez redéfinir ce comportement avec `browser.executablePath`.
Plateformes :
@ -550,11 +568,11 @@ Plateformes :
## API de contrôle (facultative)
Pour les intégrations locales uniquement, le Gateway expose une petite API HTTP en loopback :
Pour les intégrations locales uniquement, Gateway expose une petite API HTTP loopback :
- Statut/démarrage/arrêt : `GET /`, `POST /start`, `POST /stop`
- Onglets : `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
- Snapshot/capture d’écran : `GET /snapshot`, `POST /screenshot`
- Instantané/capture d’écran : `GET /snapshot`, `POST /screenshot`
- Actions : `POST /navigate`, `POST /act`
- Hooks : `POST /hooks/file-chooser`, `POST /hooks/dialog`
- Téléchargements : `POST /download`, `POST /wait/download`
@ -567,16 +585,17 @@ Pour les intégrations locales uniquement, le Gateway expose une petite API HTTP
Tous les points de terminaison acceptent `?profile=<name>`.
Si une authentification gateway par secret partagé est configurée, les routes HTTP du navigateur exigent aussi une authentification :
Si une authentification Gateway par secret partagé est configurée, les routes HTTP du navigateur exigent aussi une authentification :
- `Authorization: Bearer <gateway token>`
- `x-openclaw-password: <gateway password>` ou authentification HTTP Basic avec ce mot de passe
Remarques :
Notes :
- Cette API autonome du navigateur en loopback ne consomme **pas** les en-têtes d’identité trusted-proxy ni Tailscale Serve.
- Si `gateway.auth.mode` vaut `none` ou `trusted-proxy`, ces routes de navigateur en loopback
n’héritent pas de ces modes porteurs d’identité ; conservez-les en loopback uniquement.
- Cette API autonome du navigateur en loopback ne consomme **pas** les en-têtes d’identité trusted-proxy ou
Tailscale Serve.
- Si `gateway.auth.mode` vaut `none` ou `trusted-proxy`, ces routes navigateur en loopback
n’héritent pas de ces modes porteurs d’identité ; gardez-les limitées au loopback.
### Contrat d’erreur `/act`
@ -589,37 +608,37 @@ de politique :
Valeurs actuelles de `code` :
- `ACT_KIND_REQUIRED` (HTTP 400) : `kind` est absent ou non reconnu.
- `ACT_KIND_REQUIRED` (HTTP 400) : `kind` est manquant ou non reconnu.
- `ACT_INVALID_REQUEST` (HTTP 400) : la charge utile de l’action a échoué à la normalisation ou à la validation.
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400) : `selector` a été utilisé avec un type d’action non pris en charge.
- `ACT_EVALUATE_DISABLED` (HTTP 403) : `evaluate` (ou `wait --fn`) est désactivé par la config.
- `ACT_TARGET_ID_MISMATCH` (HTTP 403) : `targetId` de niveau supérieur ou en lot est en conflit avec la cible de la requête.
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501) : l’action n’est pas prise en charge pour les profils existing-session.
- `ACT_EVALUATE_DISABLED` (HTTP 403) : `evaluate` (ou `wait --fn`) est désactivé par la configuration.
- `ACT_TARGET_ID_MISMATCH` (HTTP 403) : le `targetId` de niveau supérieur ou en lot est en conflit avec la cible de la requête.
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501) : l’action n’est pas prise en charge pour les profils de session existante.
D’autres échecs d’exécution peuvent toujours renvoyer `{ "error": "<message>" }` sans champ
`code`.
D’autres erreurs d’exécution peuvent toujours renvoyer `{ "error": "<message>" }` sans
champ `code`.
### Exigence Playwright
Certaines fonctionnalités (navigate/act/snapshot IA/snapshot de rôle, captures d’écran d’élément,
PDF) nécessitent Playwright. Si Playwright n’est pas installé, ces points de terminaison renvoient
Certaines fonctionnalités (`navigate`/`act`/instantané AI/instantané de rôle, captures d’écran d’élément,
PDF) exigent Playwright. Si Playwright n’est pas installé, ces points de terminaison renvoient
une erreur 501 claire.
Ce qui fonctionne encore sans Playwright :
- Snapshots ARIA
- Captures d’écran de page pour le navigateur `openclaw` géré lorsqu’un WebSocket
CDP par onglet est disponible
- Captures d’écran de page pour les profils `existing-session` / Chrome MCP
- Captures d’écran existing-session basées sur ref (`--ref`) à partir de la sortie de snapshot
- instantanés ARIA
- captures d’écran de page pour le navigateur géré `openclaw` lorsqu’un WebSocket CDP
par onglet est disponible
- captures d’écran de page pour les profils `existing-session` / Chrome MCP
- captures d’écran basées sur une référence `existing-session` (`--ref`) à partir de la sortie d’instantané
Ce qui nécessite toujours Playwright :
Ce qui exige encore Playwright :
- `navigate`
- `act`
- Snapshots IA / snapshots de rôle
- Captures d’écran d’élément par sélecteur CSS (`--element`)
- Export PDF complet du navigateur
- instantanés AI / instantanés de rôle
- captures d’écran d’élément par sélecteur CSS (`--element`)
- export PDF complet du navigateur
Les captures d’écran d’élément rejettent aussi `--full-page` ; la route renvoie `fullPage is
not supported for element screenshots`.
@ -630,16 +649,16 @@ OpenClaw avec la prise en charge du navigateur.
#### Installation de Playwright dans Docker
Si votre Gateway s’exécute dans Docker, évitez `npx playwright` (conflits de surcharge npm).
Utilisez plutôt la CLI intégrée :
Si votre Gateway s’exécute dans Docker, évitez `npx playwright` (conflits d’override npm).
Utilisez plutôt la CLI groupée :
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
Pour conserver les téléchargements du navigateur, définissez `PLAYWRIGHT_BROWSERS_PATH` (par exemple,
`/home/node/.cache/ms-playwright`) et assurez-vous que `/home/node` est conservé via
Pour rendre persistants les téléchargements du navigateur, définissez `PLAYWRIGHT_BROWSERS_PATH` (par exemple,
`/home/node/.cache/ms-playwright`) et assurez-vous que `/home/node` est persistant via
`OPENCLAW_HOME_VOLUME` ou un montage bind. Voir [Docker](/fr/install/docker).
## Fonctionnement (interne)
@ -648,17 +667,17 @@ Flux de haut niveau :
- Un petit **serveur de contrôle** accepte les requêtes HTTP.
- Il se connecte aux navigateurs basés sur Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
- Pour les actions avancées (clic/saisie/snapshot/PDF), il utilise **Playwright** par-dessus
- Pour les actions avancées (clic/saisie/instantané/PDF), il utilise **Playwright** par-dessus
CDP.
- Lorsque Playwright est absent, seules les opérations ne dépendant pas de Playwright sont disponibles.
- Lorsque Playwright est absent, seules les opérations sans Playwright sont disponibles.
Cette conception maintient l’agent sur une interface stable et déterministe tout en vous permettant
de changer de navigateurs et de profils locaux/distants.
Cette conception maintient une interface stable et déterministe pour l’agent tout en vous permettant
de permuter les navigateurs et profils locaux/distants.
## Référence rapide CLI
Toutes les commandes acceptent `--browser-profile <name>` pour cibler un profil spécifique.
Toutes les commandes acceptent également `--json` pour une sortie lisible par machine (charges utiles stables).
Toutes les commandes acceptent `--browser-profile <name>` pour cibler un profil précis.
Toutes les commandes acceptent aussi `--json` pour une sortie lisible par machine (charges utiles stables).
Bases :
@ -689,11 +708,11 @@ Inspection :
- `openclaw browser snapshot --frame "iframe#main" --interactive`
- `openclaw browser console --level error`
Remarque sur le cycle de vie :
Note sur le cycle de vie :
- Pour les profils attach-only et CDP distants, `openclaw browser stop` reste la
bonne commande de nettoyage après les tests. Elle ferme la session de contrôle active et
efface les surcharges d’émulation temporaires au lieu de tuer le navigateur
efface les redéfinitions temporaires d’émulation au lieu de tuer le navigateur
sous-jacent.
- `openclaw browser errors --clear`
- `openclaw browser requests --filter api --clear`
@ -743,51 +762,51 @@ Actions :
- `openclaw browser set locale en-US`
- `openclaw browser set device "iPhone 14"`
Remarques :
Notes :
- `upload` et `dialog` sont des appels d’**armement** ; exécutez-les avant le clic/la pression
qui déclenche le sélecteur/la boîte de dialogue.
- Les chemins de sortie de téléchargement et de trace sont limités aux racines temporaires d’OpenClaw :
- Les chemins de sortie de téléchargement et de trace sont limités aux racines temporaires OpenClaw :
- traces : `/tmp/openclaw` (repli : `${os.tmpdir()}/openclaw`)
- téléchargements : `/tmp/openclaw/downloads` (repli : `${os.tmpdir()}/openclaw/downloads`)
- Les chemins d’upload sont limités à une racine temporaire d’uploads OpenClaw :
- uploads : `/tmp/openclaw/uploads` (repli : `${os.tmpdir()}/openclaw/uploads`)
- `upload` peut aussi définir directement des entrées de fichier via `--input-ref` ou `--element`.
- `snapshot` :
- `--format ai` (par défaut quand Playwright est installé) : renvoie un snapshot IA avec des refs numériques (`aria-ref="<n>"`).
- `--format aria` : renvoie l’arbre d’accessibilité (sans refs ; inspection uniquement).
- `--efficient` (ou `--mode efficient`) : préréglage de snapshot de rôle compact (interactive + compact + depth + maxChars réduit).
- Valeur par défaut de config (outil/CLI uniquement) : définissez `browser.snapshotDefaults.mode: "efficient"` pour utiliser des snapshots efficaces lorsque l’appelant ne passe pas de mode (voir [Configuration de la Gateway](/fr/gateway/configuration-reference#browser)).
- Les options de snapshot de rôle (`--interactive`, `--compact`, `--depth`, `--selector`) forcent un snapshot basé sur les rôles avec des refs comme `ref=e12`.
- `--frame "<iframe selector>"` limite les snapshots de rôle à une iframe (s’associe à des refs de rôle comme `e12`).
- `--format ai` (par défaut quand Playwright est installé) : renvoie un instantané AI avec des références numériques (`aria-ref="<n>"`).
- `--format aria` : renvoie l’arbre d’accessibilité (sans références ; inspection uniquement).
- `--efficient` (ou `--mode efficient`) : préréglage compact d’instantané de rôle (interactive + compact + depth + maxChars plus faible).
- Valeur par défaut de configuration (outil/CLI uniquement) : définissez `browser.snapshotDefaults.mode: "efficient"` pour utiliser des instantanés efficaces lorsque l’appelant ne passe pas de mode (voir [Configuration Gateway](/fr/gateway/configuration-reference#browser)).
- Les options d’instantané de rôle (`--interactive`, `--compact`, `--depth`, `--selector`) forcent un instantané basé sur les rôles avec des références comme `ref=e12`.
- `--frame "<iframe selector>"` limite les instantanés de rôle à une iframe (s’associe à des références de rôle comme `e12`).
- `--interactive` produit une liste plate et facile à sélectionner des éléments interactifs (idéal pour piloter des actions).
- `--labels` ajoute une capture d’écran du viewport avec des étiquettes de ref superposées (affiche `MEDIA:<path>`).
- `click`/`type`/etc nécessitent une `ref` provenant de `snapshot` (soit la forme numérique `12`, soit la ref de rôle `e12`).
- `--labels` ajoute une capture d’écran du viewport uniquement avec des étiquettes de référence superposées (affiche `MEDIA:<path>`).
- `click`/`type`/etc exigent une `ref` issue de `snapshot` (soit une référence numérique `12`, soit une référence de rôle `e12`).
Les sélecteurs CSS ne sont volontairement pas pris en charge pour les actions.
## Snapshots et refs
## Instantanés et références
OpenClaw prend en charge deux styles de « snapshot » :
OpenClaw prend en charge deux styles d’« instantané » :
- **Snapshot IA (refs numériques)** : `openclaw browser snapshot` (par défaut ; `--format ai`)
- Sortie : un snapshot texte qui inclut des refs numériques.
- **Instantané AI (références numériques)** : `openclaw browser snapshot` (par défaut ; `--format ai`)
- Sortie : un instantané texte qui inclut des références numériques.
- Actions : `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
- En interne, la ref est résolue via `aria-ref` de Playwright.
- En interne, la référence est résolue via le `aria-ref` de Playwright.
- **Snapshot de rôle (refs de rôle comme `e12`)** : `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
- **Instantané de rôle (références de rôle comme `e12`)** : `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
- Sortie : une liste/arborescence basée sur les rôles avec `[ref=e12]` (et éventuellement `[nth=1]`).
- Actions : `openclaw browser click e12`, `openclaw browser highlight e12`.
- En interne, la ref est résolue via `getByRole(...)` (plus `nth()` pour les doublons).
- Ajoutez `--labels` pour inclure une capture d’écran du viewport avec les étiquettes `e12` superposées.
- En interne, la référence est résolue via `getByRole(...)` (plus `nth()` pour les doublons).
- Ajoutez `--labels` pour inclure une capture d’écran du viewport avec des étiquettes `e12` superposées.
Comportement des refs :
Comportement des références :
- Les refs ne sont **pas stables d’une navigation à l’autre** ; si quelque chose échoue, relancez `snapshot` et utilisez une nouvelle ref.
- Si le snapshot de rôle a été pris avec `--frame`, les refs de rôle sont limitées à cette iframe jusqu’au prochain snapshot de rôle.
- Les références ne sont **pas stables entre les navigations** ; si quelque chose échoue, réexécutez `snapshot` et utilisez une nouvelle référence.
- Si l’instantané de rôle a été pris avec `--frame`, les références de rôle sont limitées à cette iframe jusqu’au prochain instantané de rôle.
## Attentes renforcées
## Améliorations de `wait`
Vous pouvez attendre plus que du simple temps/texte :
Vous pouvez attendre plus que le simple temps/texte :
- Attendre une URL (globs pris en charge par Playwright) :
- `openclaw browser wait --url "**/dash"`
@ -798,7 +817,7 @@ Vous pouvez attendre plus que du simple temps/texte :
- Attendre qu’un sélecteur devienne visible :
- `openclaw browser wait "#main"`
Ces conditions peuvent être combinées :
Ces options peuvent être combinées :
```bash
openclaw browser wait "#main" \
@ -808,12 +827,12 @@ openclaw browser wait "#main" \
--timeout-ms 15000
```
## Workflows de débogage
## Flux de débogage
Quand une action échoue (par ex. « not visible », « strict mode violation », « covered ») :
Lorsqu’une action échoue (par ex. « not visible », « strict mode violation », « covered ») :
1. `openclaw browser snapshot --interactive`
2. Utilisez `click <ref>` / `type <ref>` (préférez les refs de rôle en mode interactif)
2. Utilisez `click <ref>` / `type <ref>` (préférez les références de rôle en mode interactif)
3. Si cela échoue encore : `openclaw browser highlight <ref>` pour voir ce que Playwright cible
4. Si la page se comporte bizarrement :
- `openclaw browser errors --clear`
@ -825,7 +844,7 @@ Quand une action échoue (par ex. « not visible », « strict mode violation »
## Sortie JSON
`--json` est destiné aux scripts et aux outils structurés.
`--json` est destiné au scripting et aux outils structurés.
Exemples :
@ -836,22 +855,22 @@ openclaw browser requests --filter api --json
openclaw browser cookies --json
```
Les snapshots de rôle en JSON incluent `refs` ainsi qu’un petit bloc `stats` (lines/chars/refs/interactive) afin que les outils puissent raisonner sur la taille et la densité de la charge utile.
Les instantanés de rôle en JSON incluent `refs` plus un petit bloc `stats` (lignes/caractères/références/éléments interactifs) afin que les outils puissent raisonner sur la taille et la densité de la charge utile.
## Réglages d’état et d’environnement
Ils sont utiles pour les workflows « faire se comporter le site comme X » :
Ils sont utiles pour les flux « faire se comporter le site comme X » :
- Cookies : `cookies`, `cookies set`, `cookies clear`
- Storage : `storage local|session get|set|clear`
- Stockage : `storage local|session get|set|clear`
- Hors ligne : `set offline on|off`
- En-têtes : `set headers --headers-json '{"X-Debug":"1"}'` (l’ancien `set headers --json '{"X-Debug":"1"}'` reste pris en charge)
- Auth HTTP Basic : `set credentials user pass` (ou `--clear`)
- Authentification HTTP Basic : `set credentials user pass` (ou `--clear`)
- Géolocalisation : `set geo <lat> <lon> --origin "https://example.com"` (ou `--clear`)
- Média : `set media dark|light|no-preference|none`
- Fuseau horaire / langue : `set timezone ...`, `set locale ...`
- Appareil / viewport :
- `set device "iPhone 14"` (préréglages d’appareil Playwright)
- `set device "iPhone 14"` (préréglages d’appareils Playwright)
- `set viewport 1280 720`
## Sécurité et confidentialité
@ -860,11 +879,11 @@ Ils sont utiles pour les workflows « faire se comporter le site comme X » :
- `browser act kind=evaluate` / `openclaw browser evaluate` et `wait --fn`
exécutent du JavaScript arbitraire dans le contexte de la page. L’injection de prompt peut orienter
cela. Désactivez-le avec `browser.evaluateEnabled=false` si vous n’en avez pas besoin.
- Pour les connexions et les notes anti-bot (X/Twitter, etc.), voir [Connexion au navigateur + publication sur X/Twitter](/fr/tools/browser-login).
- Gardez la Gateway/l’hôte node privés (loopback ou tailnet uniquement).
- Pour les connexions et les notes anti-bot (X/Twitter, etc.), voir [Connexion navigateur + publication X/Twitter](/fr/tools/browser-login).
- Conservez la Gateway/l’hôte node privés (loopback ou tailnet uniquement).
- Les points de terminaison CDP distants sont puissants ; tunnelisez-les et protégez-les.
Exemple en mode strict (bloquer par défaut les destinations privées/internes) :
Exemple de mode strict (bloquer par défaut les destinations privées/internes) :
```json5
{
@ -880,15 +899,15 @@ Exemple en mode strict (bloquer par défaut les destinations privées/internes)
## Dépannage
Pour les problèmes spécifiques à Linux (notamment Chromium snap), voir
Pour les problèmes spécifiques à Linux (en particulier Chromium snap), voir
[Dépannage du navigateur](/fr/tools/browser-linux-troubleshooting).
Pour les configurations WSL2 Gateway + Chrome Windows hôte séparé, voir
[Dépannage WSL2 + Windows + CDP Chrome distant](/fr/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
Pour les configurations hôte scindé WSL2 Gateway + Chrome Windows, voir
[Dépannage WSL2 + Windows + Chrome distant CDP](/fr/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
### Échec de démarrage CDP vs blocage SSRF de navigation
Il s’agit de deux classes d’échec différentes, et elles pointent vers des chemins de code différents.
Il s’agit de deux classes d’échec différentes, et elles renvoient à 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.
@ -899,7 +918,7 @@ Exemples courants :
- `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 navigateur/réseau alors que `start` et `tabs` fonctionnent toujours
- les flux `open`, `navigate`, `snapshot` ou d’ouverture d’onglet échouent avec une erreur de politique navigateur/réseau alors que `start` et `tabs` fonctionnent encore
Utilisez cette séquence minimale pour distinguer les deux :
@ -911,22 +930,22 @@ openclaw browser --browser-profile openclaw open https://example.com
Comment interpréter les résultats :
- Si `start` échoue avec `not reachable after start`, dépannez d’abord la disponibilité CDP.
- Si `start` réussit mais que `tabs` échoue, le plan de contrôle reste malsain. Traitez 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` échoue, le plan de contrôle du navigateur est opérationnel et l’échec se situe dans la politique de navigation ou la page cible.
- 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 de joignabilité 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 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 du comportement :
Détails importants sur le comportement :
- 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` en 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 `start` ou `tabs` réussi ne signifie pas qu’une cible ultérieure de `open` ou `navigate` est autorisée.
- Pour le profil géré local loopback `openclaw`, les vérifications d’état CDP ignorent volontairement l’application de la politique de joignabilité SSRF du navigateur pour le propre plan de contrôle local d’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.
Consignes de sécurité :
- N’assouplissez **pas** la politique SSRF du navigateur par défaut.
- Préférez des exceptions d’hôte étroites comme `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 du navigateur au réseau privé est nécessaire et vérifié.
- **N’assouplissez pas** la politique SSRF du navigateur par défaut.
- Préférez des exceptions d’hôte étroites comme `hostnameAllowlist` ou `allowedHostnames` à un accès large au réseau privé.
- Utilisez `dangerouslyAllowPrivateNetwork: true` uniquement dans des environnements explicitement approuvés où l’accès navigateur au réseau privé est nécessaire et a été examiné.
Exemple : navigation bloquée, plan de contrôle sain
@ -936,35 +955,35 @@ Exemple : navigation bloquée, plan de contrôle sain
Cela signifie généralement que le démarrage du navigateur fonctionne correctement et que la cible de navigation nécessite un examen de politique.
Exemple : démarrage bloqué avant que la navigation n’importe
Exemple : démarrage bloqué avant que la navigation ne soit pertinente
- `start` échoue avec `not reachable after start`
- `tabs` échoue aussi ou ne peut pas s’exécuter
- `tabs` échoue également ou ne peut pas s’exécuter
Cela pointe vers un lancement du navigateur ou une accessibilité CDP, pas vers un problème de liste d’autorisation d’URL de page.
Cela indique un problème de lancement du navigateur ou de joignabilité CDP, et non un problème de liste d’autorisation d’URL de page.
## Outils agent + fonctionnement du contrôle
## Outils de l’agent + fonctionnement du contrôle
L’agent reçoit **un seul outil** pour l’automatisation du navigateur :
L’agent reçoit **un outil** pour l’automatisation du navigateur :
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
Correspondance :
- `browser snapshot` renvoie un arbre d’interface stable (IA ou ARIA).
- `browser act` utilise les ID `ref` du snapshot pour cliquer/saisir/faire glisser/sélectionner.
- `browser snapshot` renvoie un arbre d’interface stable (AI ou ARIA).
- `browser act` utilise les ID `ref` de l’instantané pour cliquer/saisir/glisser/sélectionner.
- `browser screenshot` capture les pixels (page entière ou élément).
- `browser` accepte :
- `profile` pour choisir un profil de navigateur nommé (openclaw, chrome, ou CDP distant).
- `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 en sandbox, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
- Si `target` est omis : les sessions en sandbox utilisent par défaut `sandbox`, les sessions hors sandbox utilisent par défaut `host`.
- Si un node capable de navigateur est connecté, l’outil peut y être routé automatiquement sauf si vous forcez `target="host"` ou `target="node"`.
- Dans les sessions sandboxées, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
- 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 capable de gérer le navigateur est connecté, l’outil peut automatiquement s’y router sauf si vous fixez `target="host"` ou `target="node"`.
Cela maintient le comportement de l’agent déterministe et évite les sélecteurs fragiles.
Cela permet de garder l’agent déterministe et d’éviter les sélecteurs fragiles.
## Voir aussi
## Liens associés
- [Vue d’ensemble des outils](/fr/tools) — tous les outils agent disponibles
- [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 et renforcement du contrôle du navigateur
- [Security](/fr/gateway/security) — risques et durcissement du contrôle du navigateur