chore(i18n): refresh fr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4748ef0b96
commit
41efbd8e97
File diff suppressed because it is too large
Load Diff
@ -1,47 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Configuration de Slack ou débogage du mode socket/HTTP de Slack
|
||||
summary: Configuration de Slack et comportement à l’exécution (mode Socket + URL de requête HTTP)
|
||||
- Configurer Slack ou déboguer le mode socket/HTTP de Slack
|
||||
summary: Configuration de Slack et comportement à l’exécution (mode Socket + URL de requêtes HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:22:23Z"
|
||||
generated_at: "2026-05-04T07:02:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
|
||||
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
|
||||
source_path: channels/slack.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Prêt pour la production pour les DM et les canaux via les intégrations d’application Slack. Le mode par défaut est Socket Mode ; les URL de requête HTTP sont également prises en charge.
|
||||
Prêt pour la production pour les MD et les canaux via les intégrations d’app Slack. Le mode par défaut est Socket Mode ; les URL de requête HTTP sont également prises en charge.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/fr/channels/pairing">
|
||||
Les DM Slack utilisent le mode d’association par défaut.
|
||||
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
|
||||
Les MD Slack utilisent par défaut le mode d’appairage.
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/fr/tools/slash-commands">
|
||||
Comportement des commandes natives et catalogue des commandes.
|
||||
<Card title="Commandes slash" icon="terminal" href="/fr/tools/slash-commands">
|
||||
Comportement des commandes natives et catalogue de commandes.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/fr/channels/troubleshooting">
|
||||
Diagnostics inter-canaux et guides de réparation.
|
||||
<Card title="Dépannage des canaux" icon="wrench" href="/fr/channels/troubleshooting">
|
||||
Diagnostics intercanaux et procédures de réparation.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configuration rapide
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (par défaut)">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
Dans les paramètres de l’application Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
|
||||
<Step title="Créer une nouvelle app Slack">
|
||||
Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
|
||||
|
||||
- choisissez **from a manifest** et sélectionnez un espace de travail pour votre application
|
||||
- collez le [manifeste d’exemple](#manifest-and-scope-checklist) ci-dessous et continuez pour créer
|
||||
- choisissez **from a manifest** et sélectionnez un espace de travail pour votre app
|
||||
- collez l’[exemple de manifeste](#manifest-and-scope-checklist) ci-dessous et continuez pour créer
|
||||
- générez un **App-Level Token** (`xapp-...`) avec `connections:write`
|
||||
- installez l’application et copiez le **Bot Token** (`xoxb-...`) affiché
|
||||
- installez l’app et copiez le **Bot Token** (`xoxb-...`) affiché
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configurer OpenClaw">
|
||||
|
||||
Configuration SecretRef recommandée :
|
||||
|
||||
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
|
||||
openclaw config patch --file ./slack.socket.patch.json5
|
||||
```
|
||||
|
||||
Repli par variable d’environnement (compte par défaut uniquement) :
|
||||
Solution de repli avec variables d’environnement (compte par défaut uniquement) :
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Démarrer le Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -84,19 +84,19 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Tab title="URL de requête HTTP">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
Dans les paramètres de l’application Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
|
||||
<Step title="Créer une nouvelle app Slack">
|
||||
Dans les paramètres de l’app Slack, appuyez sur le bouton **[Create New App](https://api.slack.com/apps/new)** :
|
||||
|
||||
- choisissez **from a manifest** et sélectionnez un espace de travail pour votre application
|
||||
- collez le [manifeste d’exemple](#manifest-and-scope-checklist) et mettez à jour les URL avant la création
|
||||
- choisissez **from a manifest** et sélectionnez un espace de travail pour votre app
|
||||
- collez l’[exemple de manifeste](#manifest-and-scope-checklist) et mettez à jour les URL avant de créer
|
||||
- enregistrez le **Signing Secret** pour la vérification des requêtes
|
||||
- installez l’application et copiez le **Bot Token** (`xoxb-...`) affiché
|
||||
- installez l’app et copiez le **Bot Token** (`xoxb-...`) affiché
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configurer OpenClaw">
|
||||
|
||||
Configuration SecretRef recommandée :
|
||||
|
||||
@ -123,12 +123,12 @@ openclaw config patch --file ./slack.http.patch.json5
|
||||
<Note>
|
||||
Utilisez des chemins Webhook uniques pour le HTTP multicomptes
|
||||
|
||||
Attribuez à chaque compte un `webhookPath` distinct (`/slack/events` par défaut) afin que les enregistrements n’entrent pas en conflit.
|
||||
Donnez à chaque compte un `webhookPath` distinct (`/slack/events` par défaut) afin que les inscriptions n’entrent pas en conflit.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Démarrer le Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -142,7 +142,7 @@ openclaw gateway
|
||||
|
||||
## Réglage du transport Socket Mode
|
||||
|
||||
OpenClaw définit par défaut le délai d’attente pong du client SDK Slack à 15 secondes pour Socket Mode. Ne remplacez les paramètres de transport que lorsque vous avez besoin d’un réglage propre à l’espace de travail ou à l’hôte :
|
||||
OpenClaw définit par défaut le délai d’attente pong du client Slack SDK à 15 secondes pour Socket Mode. Remplacez les paramètres de transport uniquement lorsque vous avez besoin d’un réglage propre à un espace de travail ou à un hôte :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,11 +159,11 @@ OpenClaw définit par défaut le délai d’attente pong du client SDK Slack à
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez cela uniquement pour les espaces de travail Socket Mode qui journalisent des délais d’attente pong/websocket ou server-ping Slack, ou qui s’exécutent sur des hôtes avec une famine connue de la boucle d’événements. `clientPingTimeout` est l’attente du pong après que le SDK a envoyé un ping client ; `serverPingTimeout` est l’attente des pings serveur Slack. Les messages et événements d’application restent de l’état applicatif, pas des signaux de vivacité du transport.
|
||||
Utilisez cela uniquement pour les espaces de travail Socket Mode qui journalisent des délais d’attente de pong websocket Slack ou de ping serveur, ou qui s’exécutent sur des hôtes avec une famine connue de la boucle d’événements. `clientPingTimeout` est l’attente du pong après l’envoi d’un ping client par le SDK ; `serverPingTimeout` est l’attente des pings serveur Slack. Les messages et événements de l’app restent un état applicatif, pas des signaux de disponibilité du transport.
|
||||
|
||||
## Liste de contrôle du manifeste et des portées
|
||||
|
||||
Le manifeste de base de l’application Slack est le même pour Socket Mode et les URL de requête HTTP. Seul le bloc `settings` (et l’`url` de la commande slash) diffère.
|
||||
Le manifeste de base de l’app Slack est le même pour Socket Mode et les URL de requête HTTP. Seul le bloc `settings` (et l’`url` de la commande slash) diffère.
|
||||
|
||||
Manifeste de base (Socket Mode par défaut) :
|
||||
|
||||
@ -240,7 +240,7 @@ Manifeste de base (Socket Mode par défaut) :
|
||||
}
|
||||
```
|
||||
|
||||
Pour le **mode URL de requête HTTP**, remplacez `settings` par la variante HTTP et ajoutez `url` à chaque commande slash. Une URL publique est requise :
|
||||
Pour le **mode URL de requête HTTP**, remplacez `settings` par la variante HTTP et ajoutez `url` à chaque commande slash. URL publique requise :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -282,24 +282,24 @@ Pour le **mode URL de requête HTTP**, remplacez `settings` par la variante HTTP
|
||||
}
|
||||
```
|
||||
|
||||
### Paramètres supplémentaires du manifeste
|
||||
### Paramètres de manifeste supplémentaires
|
||||
|
||||
Exposez différentes fonctionnalités qui étendent les valeurs par défaut ci-dessus.
|
||||
Exposez différentes fonctionnalités qui étendent les paramètres par défaut ci-dessus.
|
||||
|
||||
Le manifeste par défaut active l’onglet **Home** de Slack App Home et s’abonne à `app_home_opened`. Lorsqu’un membre de l’espace de travail ouvre l’onglet Home, OpenClaw publie une vue Home sûre par défaut avec `views.publish` ; aucune charge utile de conversation ni configuration privée n’est incluse. L’onglet **Messages** reste activé pour les DM Slack.
|
||||
Le manifeste par défaut active l’onglet **Home** de Slack App Home et s’abonne à `app_home_opened`. Lorsqu’un membre de l’espace de travail ouvre l’onglet Home, OpenClaw publie une vue Home sûre par défaut avec `views.publish` ; aucune charge utile de conversation ni configuration privée n’est incluse. L’onglet **Messages** reste activé pour les MD Slack.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Optional native slash commands">
|
||||
<Accordion title="Commandes slash natives facultatives">
|
||||
|
||||
Plusieurs [commandes slash natives](#commands-and-slash-behavior) peuvent être utilisées à la place d’une seule commande configurée, avec quelques nuances :
|
||||
Plusieurs [commandes slash natives](#commands-and-slash-behavior) peuvent être utilisées au lieu d’une seule commande configurée, avec certaines nuances :
|
||||
|
||||
- Utilisez `/agentstatus` au lieu de `/status`, car la commande `/status` est réservée.
|
||||
- Pas plus de 25 commandes slash ne peuvent être rendues disponibles à la fois.
|
||||
- Pas plus de 25 commandes slash peuvent être disponibles simultanément.
|
||||
|
||||
Remplacez votre section `features.slash_commands` existante par un sous-ensemble des [commandes disponibles](/fr/tools/slash-commands#command-list) :
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (par défaut)">
|
||||
|
||||
```json
|
||||
{
|
||||
@ -422,7 +422,7 @@ Le manifeste par défaut active l’onglet **Home** de Slack App Home et s’abo
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Tab title="URL de requête HTTP">
|
||||
Utilisez la même liste `slash_commands` que pour Socket Mode ci-dessus, et ajoutez `"url": "https://gateway-host.example.com/slack/events"` à chaque entrée. Exemple :
|
||||
|
||||
```json
|
||||
@ -449,13 +449,13 @@ Le manifeste par défaut active l’onglet **Home** de Slack App Home et s’abo
|
||||
</Tabs>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Portées d’auteur facultatives (opérations d’écriture)">
|
||||
<Accordion title="Portées d’attribution facultatives (opérations d’écriture)">
|
||||
Ajoutez la portée de bot `chat:write.customize` si vous voulez que les messages sortants utilisent l’identité de l’agent actif (nom d’utilisateur et icône personnalisés) au lieu de l’identité par défaut de l’application Slack.
|
||||
|
||||
Si vous utilisez une icône emoji, Slack attend la syntaxe `:emoji_name:`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Portées facultatives de jeton utilisateur (opérations de lecture)">
|
||||
<Accordion title="Portées facultatives du jeton utilisateur (opérations de lecture)">
|
||||
Si vous configurez `channels.slack.userToken`, les portées de lecture typiques sont :
|
||||
|
||||
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
|
||||
@ -469,67 +469,67 @@ Le manifeste par défaut active l’onglet **Home** de Slack App Home et s’abo
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Modèle de jeton
|
||||
## Modèle de jetons
|
||||
|
||||
- `botToken` + `appToken` sont requis pour le Socket Mode.
|
||||
- Le mode HTTP nécessite `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent des chaînes en texte brut
|
||||
ou des objets SecretRef.
|
||||
- Les jetons de configuration remplacent le recours aux variables d’environnement.
|
||||
- Le recours aux variables d’environnement `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` s’applique uniquement au compte par défaut.
|
||||
- `userToken` (`xoxp-...`) est uniquement configurable (aucun recours aux variables d’environnement) et utilise par défaut un comportement en lecture seule (`userTokenReadOnly: true`).
|
||||
- `botToken` + `appToken` sont requis pour le mode Socket.
|
||||
- Le mode HTTP requiert `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` et `userToken` acceptent les chaînes en texte clair
|
||||
ou les objets SecretRef.
|
||||
- Les jetons de configuration remplacent le repli env.
|
||||
- Le repli env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` s’applique uniquement au compte par défaut.
|
||||
- `userToken` (`xoxp-...`) est uniquement configurable (aucun repli env) et utilise par défaut un comportement en lecture seule (`userTokenReadOnly: true`).
|
||||
|
||||
Comportement de l’instantané d’état :
|
||||
|
||||
- L’inspection des comptes Slack suit les champs `*Source` et `*Status`
|
||||
par identifiant d’accès (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- L’inspection du compte Slack suit les champs `*Source` et `*Status`
|
||||
par identifiant (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- L’état est `available`, `configured_unavailable` ou `missing`.
|
||||
- `configured_unavailable` signifie que le compte est configuré via SecretRef
|
||||
ou une autre source de secret non intégrée, mais que la commande ou le chemin d’exécution actuel
|
||||
ou une autre source de secret non inline, mais que le chemin de commande/d’exécution actuel
|
||||
n’a pas pu résoudre la valeur réelle.
|
||||
- En mode HTTP, `signingSecretStatus` est inclus ; en Socket Mode, la
|
||||
- En mode HTTP, `signingSecretStatus` est inclus ; en mode Socket, la
|
||||
paire requise est `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Pour les actions et les lectures d’annuaire, le jeton utilisateur peut être préféré lorsqu’il est configuré. Pour les écritures, le jeton de bot reste préféré ; les écritures avec jeton utilisateur ne sont autorisées que lorsque `userTokenReadOnly: false` et que le jeton de bot est indisponible.
|
||||
Pour les actions/lectures de répertoire, le jeton utilisateur peut être préféré lorsqu’il est configuré. Pour les écritures, le jeton de bot reste préféré ; les écritures avec jeton utilisateur ne sont autorisées que lorsque `userTokenReadOnly: false` et que le jeton de bot est indisponible.
|
||||
</Tip>
|
||||
|
||||
## Actions et contrôles
|
||||
## Actions et garde-fous
|
||||
|
||||
Les actions Slack sont contrôlées par `channels.slack.actions.*`.
|
||||
|
||||
Groupes d’actions disponibles dans l’outillage Slack actuel :
|
||||
|
||||
| Groupe | Par défaut |
|
||||
| ---------- | ---------- |
|
||||
| messages | activé |
|
||||
| reactions | activé |
|
||||
| pins | activé |
|
||||
| memberInfo | activé |
|
||||
| emojiList | activé |
|
||||
| Groupe | Valeur par défaut |
|
||||
| ---------- | ----------------- |
|
||||
| messages | activé |
|
||||
| reactions | activé |
|
||||
| pins | activé |
|
||||
| memberInfo | activé |
|
||||
| emojiList | activé |
|
||||
|
||||
Les actions de message Slack actuelles incluent `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` et `emoji-list`. `download-file` accepte les ID de fichiers Slack affichés dans les placeholders de fichiers entrants et renvoie des aperçus d’image pour les images ou des métadonnées de fichier local pour les autres types de fichiers.
|
||||
Les actions de message Slack actuelles incluent `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` et `emoji-list`. `download-file` accepte les ID de fichiers Slack affichés dans les placeholders de fichiers entrants et renvoie des aperçus d’image pour les images ou les métadonnées de fichier local pour les autres types de fichiers.
|
||||
|
||||
## Contrôle d’accès et routage
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Politique de MP">
|
||||
`channels.slack.dmPolicy` contrôle l’accès aux MP. `channels.slack.allowFrom` est la liste d’autorisation canonique des MP.
|
||||
<Tab title="Politique de DM">
|
||||
`channels.slack.dmPolicy` contrôle l’accès aux DM. `channels.slack.allowFrom` est la liste d’autorisation canonique des DM.
|
||||
|
||||
- `pairing` (par défaut)
|
||||
- `allowlist`
|
||||
- `open` (nécessite que `channels.slack.allowFrom` inclue `"*"`)
|
||||
- `open` (requiert que `channels.slack.allowFrom` inclue `"*"`)
|
||||
- `disabled`
|
||||
|
||||
Options de MP :
|
||||
Indicateurs DM :
|
||||
|
||||
- `dm.enabled` (true par défaut)
|
||||
- `channels.slack.allowFrom`
|
||||
- `dm.allowFrom` (hérité)
|
||||
- `dm.groupEnabled` (MP de groupe false par défaut)
|
||||
- `dm.groupEnabled` (DM de groupe false par défaut)
|
||||
- `dm.groupChannels` (liste d’autorisation MPIM facultative)
|
||||
|
||||
Précédence multi-comptes :
|
||||
Priorité multicomptes :
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` s’applique uniquement au compte `default`.
|
||||
- Les comptes nommés héritent de `channels.slack.allowFrom` lorsque leur propre `allowFrom` n’est pas défini.
|
||||
@ -537,7 +537,7 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download
|
||||
|
||||
Les anciens `channels.slack.dm.policy` et `channels.slack.dm.allowFrom` sont toujours lus pour compatibilité. `openclaw doctor --fix` les migre vers `dmPolicy` et `allowFrom` lorsqu’il peut le faire sans modifier l’accès.
|
||||
|
||||
L’association dans les MP utilise `openclaw pairing approve slack <code>`.
|
||||
L’appairage dans les DM utilise `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -548,20 +548,20 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
La liste d’autorisation des canaux se trouve sous `channels.slack.channels` et **doit utiliser des ID de canal Slack stables** (par exemple `C12345678`) comme clés de configuration.
|
||||
La liste d’autorisation des canaux se trouve sous `channels.slack.channels` et **doit utiliser des ID de canaux Slack stables** (par exemple `C12345678`) comme clés de configuration.
|
||||
|
||||
Note d’exécution : si `channels.slack` est complètement absent (configuration uniquement par variables d’environnement), l’exécution revient à `groupPolicy="allowlist"` et journalise un avertissement (même si `channels.defaults.groupPolicy` est défini).
|
||||
Note d’exécution : si `channels.slack` est totalement absent (configuration env uniquement), l’exécution se rabat sur `groupPolicy="allowlist"` et journalise un avertissement (même si `channels.defaults.groupPolicy` est défini).
|
||||
|
||||
Résolution nom/ID :
|
||||
|
||||
- les entrées de liste d’autorisation de canal et les entrées de liste d’autorisation de MP sont résolues au démarrage lorsque l’accès par jeton le permet
|
||||
- les entrées de nom de canal non résolues sont conservées comme configurées, mais ignorées par défaut pour le routage
|
||||
- l’autorisation entrante et le routage des canaux sont centrés sur l’ID par défaut ; la correspondance directe par nom d’utilisateur ou slug nécessite `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- les entrées de liste d’autorisation de canaux et les entrées de liste d’autorisation de DM sont résolues au démarrage lorsque l’accès au jeton le permet
|
||||
- les entrées de noms de canaux non résolues sont conservées telles que configurées, mais ignorées par défaut pour le routage
|
||||
- l’autorisation entrante et le routage des canaux privilégient l’ID par défaut ; la correspondance directe par nom d’utilisateur/slug requiert `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
<Warning>
|
||||
Les clés basées sur le nom (`#channel-name` ou `channel-name`) ne correspondent **pas** avec `groupPolicy: "allowlist"`. La recherche de canal est centrée sur l’ID par défaut, donc une clé basée sur le nom ne sera jamais routée correctement et tous les messages de ce canal seront bloqués silencieusement. Cela diffère de `groupPolicy: "open"`, où la clé du canal n’est pas requise pour le routage et où une clé basée sur le nom semble fonctionner.
|
||||
Les clés basées sur le nom (`#channel-name` ou `channel-name`) ne correspondent **pas** sous `groupPolicy: "allowlist"`. La recherche de canal privilégie l’ID par défaut, donc une clé basée sur le nom ne sera jamais routée correctement et tous les messages dans ce canal seront bloqués silencieusement. Cela diffère de `groupPolicy: "open"`, où la clé de canal n’est pas requise pour le routage et où une clé basée sur le nom semble fonctionner.
|
||||
|
||||
Utilisez toujours l’ID de canal Slack comme clé. Pour le trouver : faites un clic droit sur le canal dans Slack → **Copier le lien** — l’ID (`C...`) apparaît à la fin de l’URL.
|
||||
Utilisez toujours l’ID du canal Slack comme clé. Pour le trouver : faites un clic droit sur le canal dans Slack → **Copier le lien** — l’ID (`C...`) apparaît à la fin de l’URL.
|
||||
|
||||
Correct :
|
||||
|
||||
@ -578,7 +578,7 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download
|
||||
}
|
||||
```
|
||||
|
||||
Incorrect (bloqué silencieusement avec `groupPolicy: "allowlist"`) :
|
||||
Incorrect (bloqué silencieusement avec `groupPolicy: "allowlist"`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -597,14 +597,14 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download
|
||||
</Tab>
|
||||
|
||||
<Tab title="Mentions et utilisateurs de canal">
|
||||
Les messages de canal sont soumis à une mention par défaut.
|
||||
Les messages de canal sont soumis à une exigence de mention par défaut.
|
||||
|
||||
Sources de mention :
|
||||
|
||||
- mention explicite de l’application (`<@botId>`)
|
||||
- mention de groupe d’utilisateurs Slack (`<!subteam^S...>`) lorsque l’utilisateur bot est membre de ce groupe d’utilisateurs ; nécessite `usergroups:read`
|
||||
- motifs regex de mention (`agents.list[].groupChat.mentionPatterns`, recours à `messages.groupChat.mentionPatterns`)
|
||||
- comportement implicite des fils répondant au bot (désactivé lorsque `thread.requireExplicitMention` vaut `true`)
|
||||
- motifs regex de mention (`agents.list[].groupChat.mentionPatterns`, repli `messages.groupChat.mentionPatterns`)
|
||||
- comportement implicite de fil en réponse au bot (désactivé lorsque `thread.requireExplicitMention` vaut `true`)
|
||||
|
||||
Contrôles par canal (`channels.slack.channels.<id>` ; noms uniquement via la résolution au démarrage ou `dangerouslyAllowNameMatching`) :
|
||||
|
||||
@ -614,30 +614,30 @@ Les actions de message Slack actuelles incluent `send`, `upload-file`, `download
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- format de clé `toolsBySender` : caractères génériques `id:`, `e164:`, `username:`, `name:` ou `"*"`
|
||||
- format de clé `toolsBySender` : `id:`, `e164:`, `username:`, `name:`, ou caractère générique `"*"`
|
||||
(les anciennes clés sans préfixe correspondent toujours uniquement à `id:`)
|
||||
|
||||
`allowBots` est conservateur pour les canaux et les canaux privés : les messages de salon rédigés par un bot ne sont acceptés que lorsque le bot expéditeur est explicitement répertorié dans la liste d’autorisation `users` de ce salon, ou lorsqu’au moins un ID de propriétaire Slack explicite provenant de `channels.slack.allowFrom` est actuellement membre du salon. Les caractères génériques et les entrées de propriétaire par nom d’affichage ne satisfont pas la présence du propriétaire. La présence du propriétaire utilise Slack `conversations.members` ; assurez-vous que l’application dispose de la portée de lecture correspondante pour le type de salon (`channels:read` pour les canaux publics, `groups:read` pour les canaux privés). Si la recherche de membres échoue, OpenClaw abandonne le message de salon rédigé par un bot.
|
||||
`allowBots` est conservateur pour les canaux et les canaux privés : les messages de salon rédigés par des bots sont acceptés uniquement lorsque le bot expéditeur est explicitement listé dans la liste d’autorisation `users` de ce salon, ou lorsqu’au moins un ID de propriétaire Slack explicite provenant de `channels.slack.allowFrom` est actuellement membre du salon. Les caractères génériques et les entrées de propriétaire basées sur le nom d’affichage ne satisfont pas la présence du propriétaire. La présence du propriétaire utilise Slack `conversations.members` ; assurez-vous que l’application dispose du périmètre de lecture correspondant au type de salon (`channels:read` pour les canaux publics, `groups:read` pour les canaux privés). Si la recherche des membres échoue, OpenClaw ignore le message de salon rédigé par le bot.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Fils, sessions et balises de réponse
|
||||
|
||||
- Les MP sont routés comme `direct` ; les canaux comme `channel` ; les MPIM comme `group`.
|
||||
- Les liaisons de route Slack acceptent les ID bruts de pair ainsi que les formes de cible Slack comme `channel:C12345678`, `user:U12345678` et `<@U12345678>`.
|
||||
- Avec `session.dmScope=main` par défaut, les MP Slack sont regroupés dans la session principale de l’agent.
|
||||
- Les DM sont acheminés comme `direct` ; les canaux comme `channel` ; les MPIM comme `group`.
|
||||
- Les liaisons de route Slack acceptent les ID de pairs bruts ainsi que les formes de cible Slack telles que `channel:C12345678`, `user:U12345678` et `<@U12345678>`.
|
||||
- Avec la valeur par défaut `session.dmScope=main`, les DM Slack sont regroupés dans la session principale de l’agent.
|
||||
- Sessions de canal : `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Les réponses de fil peuvent créer des suffixes de session de fil (`:thread:<threadTs>`) le cas échéant.
|
||||
- La valeur par défaut de `channels.slack.thread.historyScope` est `thread` ; la valeur par défaut de `thread.inheritParent` est `false`.
|
||||
- Les réponses dans un fil peuvent créer des suffixes de session de fil (`:thread:<threadTs>`) le cas échéant.
|
||||
- La valeur par défaut de `channels.slack.thread.historyScope` est `thread` ; celle de `thread.inheritParent` est `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` contrôle combien de messages de fil existants sont récupérés lorsqu’une nouvelle session de fil démarre (par défaut `20` ; définissez `0` pour désactiver).
|
||||
- `channels.slack.thread.requireExplicitMention` (par défaut `false`) : lorsque `true`, supprime les mentions implicites dans les fils afin que le bot ne réponde qu’aux mentions explicites `@bot` dans les fils, même lorsque le bot a déjà participé au fil. Sans cela, les réponses dans un fil auquel le bot a participé contournent le contrôle `requireMention`.
|
||||
- `channels.slack.thread.requireExplicitMention` (par défaut `false`) : lorsque défini sur `true`, supprime les mentions implicites dans les fils afin que le bot réponde uniquement aux mentions explicites `@bot` dans les fils, même lorsque le bot a déjà participé au fil. Sans cela, les réponses dans un fil auquel le bot a participé contournent le contrôle `requireMention`.
|
||||
|
||||
Contrôles des fils de réponse :
|
||||
|
||||
- `channels.slack.replyToMode` : `off|first|all|batched` (par défaut `off`)
|
||||
- `channels.slack.replyToModeByChatType` : par `direct|group|channel`
|
||||
- recours hérité pour les conversations directes : `channels.slack.dm.replyToMode`
|
||||
- repli hérité pour les conversations directes : `channels.slack.dm.replyToMode`
|
||||
|
||||
Les balises de réponse manuelles sont prises en charge :
|
||||
|
||||
@ -645,7 +645,7 @@ Les balises de réponse manuelles sont prises en charge :
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
<Note>
|
||||
`replyToMode="off"` désactive **tous** les fils de réponse dans Slack, y compris les balises explicites `[[reply_to_*]]`. Cela diffère de Telegram, où les balises explicites sont toujours honorées en mode `"off"`. Les fils Slack masquent les messages du canal, tandis que les réponses Telegram restent visibles en ligne.
|
||||
`replyToMode="off"` désactive **tous** les fils de réponse dans Slack, y compris les balises explicites `[[reply_to_*]]`. Cela diffère de Telegram, où les balises explicites restent honorées en mode `"off"`. Les fils Slack masquent les messages du canal, tandis que les réponses Telegram restent visibles en ligne.
|
||||
</Note>
|
||||
|
||||
## Réactions d’accusé de réception
|
||||
@ -657,33 +657,52 @@ Ordre de résolution :
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- recours à l’emoji de l’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
|
||||
- repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
|
||||
|
||||
Notes :
|
||||
|
||||
- Slack attend des shortcodes (par exemple `"eyes"`).
|
||||
- Utilisez `""` pour désactiver la réaction pour le compte Slack ou globalement.
|
||||
|
||||
## Diffusion du texte
|
||||
## Diffusion de texte en continu
|
||||
|
||||
`channels.slack.streaming` contrôle le comportement d’aperçu en direct :
|
||||
`channels.slack.streaming` contrôle le comportement de l’aperçu en direct :
|
||||
|
||||
- `off` : désactiver la diffusion d’aperçu en direct.
|
||||
- `off` : désactiver la diffusion de l’aperçu en direct.
|
||||
- `partial` (par défaut) : remplacer le texte d’aperçu par la dernière sortie partielle.
|
||||
- `block` : ajouter des mises à jour d’aperçu par fragments.
|
||||
- `progress` : afficher le texte d’état de progression pendant la génération, puis envoyer le texte final.
|
||||
- `streaming.preview.toolProgress` : lorsque l’aperçu de brouillon est actif, router les mises à jour d’outil/progression vers le même message d’aperçu modifié (par défaut : `true`). Définissez `false` pour conserver des messages d’outil/progression séparés.
|
||||
- `progress` : afficher un texte d’état de progression pendant la génération, puis envoyer le texte final.
|
||||
- `streaming.preview.toolProgress` : lorsque l’aperçu de brouillon est actif, acheminer les mises à jour d’outil/de progression vers le même message d’aperçu modifié (par défaut : `true`). Définissez `false` pour conserver des messages d’outil/de progression séparés.
|
||||
- `streaming.preview.commandText` / `streaming.progress.commandText` : définir sur `status` pour conserver des lignes compactes de progression d’outil tout en masquant le texte brut de commande/d’exécution (par défaut : `raw`).
|
||||
|
||||
`channels.slack.streaming.nativeTransport` contrôle la diffusion de texte native Slack lorsque `channels.slack.streaming.mode` vaut `partial` (par défaut : `true`).
|
||||
Masquer le texte brut de commande/d’exécution tout en conservant des lignes compactes de progression :
|
||||
|
||||
- Un fil de réponse doit être disponible pour que la diffusion de texte native et l’état de fil d’assistant Slack apparaissent. La sélection du fil suit toujours `replyToMode`.
|
||||
- Les canaux, les discussions de groupe et les racines de MP de premier niveau peuvent toujours utiliser l’aperçu de brouillon normal lorsque la diffusion native est indisponible ou qu’aucun fil de réponse n’existe.
|
||||
- Les MP Slack de premier niveau restent hors fil par défaut ; ils n’affichent donc pas l’aperçu de flux/état natif de style fil de Slack ; OpenClaw publie et modifie plutôt un aperçu de brouillon dans le MP.
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`channels.slack.streaming.nativeTransport` contrôle la diffusion native de texte Slack lorsque `channels.slack.streaming.mode` vaut `partial` (par défaut : `true`).
|
||||
|
||||
- Un fil de réponse doit être disponible pour que la diffusion native de texte et l’état de fil de l’assistant Slack apparaissent. La sélection du fil suit toujours `replyToMode`.
|
||||
- Les racines de canaux, de conversations de groupe et de DM de premier niveau peuvent toujours utiliser l’aperçu de brouillon normal lorsque la diffusion native est indisponible ou qu’aucun fil de réponse n’existe.
|
||||
- Les DM Slack de premier niveau restent hors fil par défaut ; ils n’affichent donc pas l’aperçu de diffusion/état natif de style fil de Slack. OpenClaw publie et modifie plutôt un aperçu de brouillon dans le DM.
|
||||
- Les médias et les charges utiles non textuelles reviennent à la livraison normale.
|
||||
- Les résultats finaux de média/erreur annulent les modifications d’aperçu en attente ; les résultats finaux de texte/bloc admissibles ne sont envoyés que lorsqu’ils peuvent modifier l’aperçu sur place.
|
||||
- Les finaux média/erreur annulent les modifications d’aperçu en attente ; les finaux texte/bloc éligibles ne sont vidés que lorsqu’ils peuvent modifier l’aperçu en place.
|
||||
- Si la diffusion échoue au milieu d’une réponse, OpenClaw revient à la livraison normale pour les charges utiles restantes.
|
||||
|
||||
Utilisez l’aperçu de brouillon au lieu de la diffusion de texte native Slack :
|
||||
Utiliser l’aperçu de brouillon au lieu de la diffusion native de texte Slack :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -698,15 +717,15 @@ Utilisez l’aperçu de brouillon au lieu de la diffusion de texte native Slack
|
||||
}
|
||||
```
|
||||
|
||||
Anciennes clés :
|
||||
Clés héritées :
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) est migré automatiquement vers `channels.slack.streaming.mode`.
|
||||
- le booléen `channels.slack.streaming` est migré automatiquement vers `channels.slack.streaming.mode` et `channels.slack.streaming.nativeTransport`.
|
||||
- l’ancien `channels.slack.nativeStreaming` est migré automatiquement vers `channels.slack.streaming.nativeTransport`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) est automatiquement migré vers `channels.slack.streaming.mode`.
|
||||
- le booléen `channels.slack.streaming` est automatiquement migré vers `channels.slack.streaming.mode` et `channels.slack.streaming.nativeTransport`.
|
||||
- l’ancien `channels.slack.nativeStreaming` est automatiquement migré vers `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Recours par réaction de saisie
|
||||
## Repli de réaction de saisie
|
||||
|
||||
`typingReaction` ajoute une réaction temporaire au message Slack entrant pendant qu’OpenClaw traite une réponse, puis la supprime lorsque l’exécution se termine. C’est particulièrement utile en dehors des réponses de fil, qui utilisent un indicateur d’état par défaut "est en train d’écrire...".
|
||||
`typingReaction` ajoute une réaction temporaire au message Slack entrant pendant qu’OpenClaw traite une réponse, puis la retire lorsque l’exécution se termine. C’est surtout utile en dehors des réponses de fil, qui utilisent un indicateur d’état par défaut « is typing... ».
|
||||
|
||||
Ordre de résolution :
|
||||
|
||||
@ -716,42 +735,42 @@ Ordre de résolution :
|
||||
Notes :
|
||||
|
||||
- Slack attend des shortcodes (par exemple `"hourglass_flowing_sand"`).
|
||||
- La réaction est appliquée au mieux, et le nettoyage est tenté automatiquement une fois le chemin de réponse ou d’échec terminé.
|
||||
- La réaction est appliquée au mieux et le nettoyage est tenté automatiquement une fois le chemin de réponse ou d’échec terminé.
|
||||
|
||||
## Médias, découpage en fragments et livraison
|
||||
## Médias, découpage et livraison
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Pièces jointes entrantes">
|
||||
Les pièces jointes Slack sont téléchargées depuis des URL privées hébergées par Slack (flux de requête authentifié par jeton) et écrites dans le magasin de médias lorsque la récupération réussit et que les limites de taille le permettent. Les espaces réservés de fichier incluent le `fileId` Slack afin que les agents puissent récupérer le fichier d’origine avec `download-file`.
|
||||
<Accordion title="Inbound attachments">
|
||||
Les pièces jointes de fichier Slack sont téléchargées depuis les URL privées hébergées par Slack (flux de requête authentifiée par jeton) et écrites dans le magasin de médias lorsque la récupération réussit et que les limites de taille le permettent. Les placeholders de fichier incluent le `fileId` Slack afin que les agents puissent récupérer le fichier original avec `download-file`.
|
||||
|
||||
Les téléchargements utilisent des délais d’expiration bornés pour l’inactivité et la durée totale. Si la récupération de fichier Slack se bloque ou échoue, OpenClaw continue de traiter le message et revient à l’espace réservé du fichier.
|
||||
Les téléchargements utilisent des délais d’inactivité et totaux bornés. Si la récupération de fichier Slack se bloque ou échoue, OpenClaw continue à traiter le message et se rabat sur le placeholder de fichier.
|
||||
|
||||
La limite de taille entrante à l’exécution est par défaut de `20MB`, sauf remplacement par `channels.slack.mediaMaxMb`.
|
||||
Le plafond de taille entrante à l’exécution vaut par défaut `20MB`, sauf s’il est remplacé par `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Texte et fichiers sortants">
|
||||
<Accordion title="Outbound text and files">
|
||||
- les fragments de texte utilisent `channels.slack.textChunkLimit` (4000 par défaut)
|
||||
- `channels.slack.chunkMode="newline"` active un découpage donnant la priorité aux paragraphes
|
||||
- les envois de fichiers utilisent les API d’import Slack et peuvent inclure des réponses de fil (`thread_ts`)
|
||||
- la limite de médias sortants suit `channels.slack.mediaMaxMb` lorsqu’elle est configurée ; sinon, les envois de canal utilisent les valeurs par défaut par type MIME du pipeline de médias
|
||||
- les envois de fichiers utilisent les API de téléversement Slack et peuvent inclure des réponses de fil (`thread_ts`)
|
||||
- le plafond de médias sortants suit `channels.slack.mediaMaxMb` lorsqu’il est configuré ; sinon les envois de canal utilisent les valeurs par défaut par type MIME du pipeline média
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cibles de livraison">
|
||||
<Accordion title="Delivery targets">
|
||||
Cibles explicites préférées :
|
||||
|
||||
- `user:<id>` pour les messages directs
|
||||
- `user:<id>` pour les DM
|
||||
- `channel:<id>` pour les canaux
|
||||
|
||||
Les messages directs Slack contenant uniquement du texte ou des blocs peuvent être publiés directement vers des identifiants utilisateur ; les imports de fichiers et les envois en fil ouvrent d’abord le message direct via les API de conversation Slack, car ces chemins nécessitent un identifiant de conversation concret.
|
||||
Les DM Slack contenant uniquement du texte ou des blocs peuvent publier directement vers des ID utilisateur ; les téléversements de fichiers et les envois dans des fils ouvrent d’abord le DM via les API de conversation Slack, car ces chemins nécessitent un ID de conversation concret.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Commandes et comportement des commandes slash
|
||||
## Commandes et comportement slash
|
||||
|
||||
Les commandes slash apparaissent dans Slack soit comme une seule commande configurée, soit comme plusieurs commandes natives. Configurez `channels.slack.slashCommand` pour modifier les valeurs par défaut des commandes :
|
||||
Les commandes slash apparaissent dans Slack soit comme une commande configurée unique, soit comme plusieurs commandes natives. Configurez `channels.slack.slashCommand` pour modifier les valeurs par défaut des commandes :
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -762,30 +781,30 @@ Les commandes slash apparaissent dans Slack soit comme une seule commande config
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
Les commandes natives nécessitent des [paramètres de manifeste supplémentaires](#additional-manifest-settings) dans votre application Slack et sont plutôt activées avec `channels.slack.commands.native: true` ou `commands.native: true` dans les configurations globales.
|
||||
Les commandes natives nécessitent des [paramètres de manifeste supplémentaires](#additional-manifest-settings) dans votre application Slack et sont activées avec `channels.slack.commands.native: true` ou `commands.native: true` dans les configurations globales à la place.
|
||||
|
||||
- Le mode automatique des commandes natives est **désactivé** pour Slack, donc `commands.native: "auto"` n’active pas les commandes natives Slack.
|
||||
- Le mode automatique des commandes natives est **désactivé** pour Slack ; `commands.native: "auto"` n’active donc pas les commandes natives Slack.
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
Les menus d’arguments natifs utilisent une stratégie de rendu adaptative qui affiche une fenêtre modale de confirmation avant de distribuer la valeur d’option sélectionnée :
|
||||
Les menus d’arguments natifs utilisent une stratégie de rendu adaptative qui affiche une fenêtre modale de confirmation avant de distribuer une valeur d’option sélectionnée :
|
||||
|
||||
- jusqu’à 5 options : blocs de boutons
|
||||
- 6 à 100 options : menu de sélection statique
|
||||
- plus de 100 options : sélection externe avec filtrage asynchrone des options lorsque des gestionnaires d’options d’interactivité sont disponibles
|
||||
- limites Slack dépassées : les valeurs d’option encodées reviennent à des boutons
|
||||
- plus de 100 options : sélection externe avec filtrage asynchrone des options lorsque les gestionnaires d’options d’interactivité sont disponibles
|
||||
- limites Slack dépassées : les valeurs d’option encodées se rabattent sur des boutons
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
Les sessions slash utilisent des clés isolées comme `agent:<agentId>:slack:slash:<userId>` et routent toujours les exécutions de commandes vers la session de conversation cible à l’aide de `CommandTargetSessionKey`.
|
||||
Les sessions slash utilisent des clés isolées comme `agent:<agentId>:slack:slash:<userId>` et acheminent toujours les exécutions de commandes vers la session de conversation cible avec `CommandTargetSessionKey`.
|
||||
|
||||
## Réponses interactives
|
||||
|
||||
Slack peut afficher des contrôles de réponse interactifs rédigés par l’agent, mais cette fonctionnalité est désactivée par défaut.
|
||||
Slack peut afficher des contrôles de réponse interactive rédigés par l’agent, mais cette fonctionnalité est désactivée par défaut.
|
||||
|
||||
Activez-la globalement :
|
||||
|
||||
@ -819,44 +838,44 @@ Ou activez-la pour un seul compte Slack :
|
||||
}
|
||||
```
|
||||
|
||||
Lorsqu’elle est activée, les agents peuvent émettre des directives de réponse propres à Slack :
|
||||
Une fois activée, les agents peuvent émettre des directives de réponse propres à Slack :
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
Ces directives sont compilées en Slack Block Kit et routent les clics ou les sélections via le chemin d’événements d’interaction Slack existant.
|
||||
Ces directives sont compilées en Slack Block Kit et réacheminent les clics ou sélections via le chemin d’événement d’interaction Slack existant.
|
||||
|
||||
Remarques :
|
||||
Notes :
|
||||
|
||||
- Il s’agit d’une interface propre à Slack. Les autres canaux ne traduisent pas les directives Slack Block Kit dans leurs propres systèmes de boutons.
|
||||
- Les valeurs de rappel interactif sont des jetons opaques générés par OpenClaw, et non des valeurs brutes rédigées par l’agent.
|
||||
- Si les blocs interactifs générés dépassaient les limites de Slack Block Kit, OpenClaw revient à la réponse textuelle d’origine au lieu d’envoyer une charge utile de blocs invalide.
|
||||
- Les valeurs de rappel interactives sont des jetons opaques générés par OpenClaw, et non des valeurs brutes rédigées par l’agent.
|
||||
- Si les blocs interactifs générés dépassaient les limites de Slack Block Kit, OpenClaw se rabat sur la réponse textuelle originale au lieu d’envoyer une charge utile de blocs invalide.
|
||||
|
||||
## Approbations d’exécution dans Slack
|
||||
|
||||
Slack peut agir comme client d’approbation natif avec des boutons et interactions interactifs, au lieu de revenir à l’interface web ou au terminal.
|
||||
Slack peut agir comme client d’approbation natif avec des boutons et interactions interactifs, au lieu de se rabattre sur l’interface Web ou le terminal.
|
||||
|
||||
- Les approbations d’exécution utilisent `channels.slack.execApprovals.*` pour le routage natif des messages directs/canaux.
|
||||
- Les approbations de Plugin peuvent toujours se résoudre via la même surface de boutons native Slack lorsque la demande arrive déjà dans Slack et que le type d’identifiant d’approbation est `plugin:`.
|
||||
- L’autorisation de l’approbateur reste appliquée : seuls les utilisateurs identifiés comme approbateurs peuvent approuver ou refuser des demandes via Slack.
|
||||
- Les approbations d’exécution utilisent `channels.slack.execApprovals.*` pour le routage DM/canal natif.
|
||||
- Les approbations de Plugin peuvent toujours se résoudre via la même surface de boutons native Slack lorsque la requête arrive déjà dans Slack et que le type d’ID d’approbation est `plugin:`.
|
||||
- L’autorisation des approbateurs reste appliquée : seuls les utilisateurs identifiés comme approbateurs peuvent approuver ou refuser des requêtes via Slack.
|
||||
|
||||
Cela utilise la même surface partagée de boutons d’approbation que les autres canaux. Lorsque `interactivity` est activé dans les paramètres de votre application Slack, les invites d’approbation s’affichent sous forme de boutons Block Kit directement dans la conversation.
|
||||
Lorsque ces boutons sont présents, ils constituent l’expérience d’approbation principale ; OpenClaw
|
||||
ne doit inclure une commande manuelle `/approve` que lorsque le résultat de l’outil indique que les
|
||||
approbations par chat sont indisponibles ou que l’approbation manuelle est le seul chemin.
|
||||
Cela utilise la même surface partagée de boutons d’approbation que les autres canaux. Lorsque `interactivity` est activé dans les paramètres de votre application Slack, les invites d’approbation s’affichent comme des boutons Block Kit directement dans la conversation.
|
||||
Lorsque ces boutons sont présents, ils constituent l’UX d’approbation principale ; OpenClaw
|
||||
ne doit inclure une commande `/approve` manuelle que lorsque le résultat de l’outil indique que les approbations
|
||||
par chat sont indisponibles ou que l’approbation manuelle est le seul chemin.
|
||||
|
||||
Chemin de configuration :
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers` (facultatif ; revient à `commands.ownerAllowFrom` lorsque possible)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, par défaut : `dm`)
|
||||
- `channels.slack.execApprovals.approvers` (facultatif ; se rabat sur `commands.ownerAllowFrom` lorsque possible)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, valeur par défaut : `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack active automatiquement les approbations d’exécution natives lorsque `enabled` n’est pas défini ou vaut `"auto"` et qu’au moins un
|
||||
approbateur est résolu. Définissez `enabled: false` pour désactiver explicitement Slack comme client d’approbation natif.
|
||||
Définissez `enabled: true` pour forcer l’activation des approbations natives lorsque des approbateurs sont résolus.
|
||||
Définissez `enabled: true` pour forcer les approbations natives lorsque des approbateurs sont résolus.
|
||||
|
||||
Comportement par défaut sans configuration explicite des approbations d’exécution Slack :
|
||||
Comportement par défaut sans configuration explicite d’approbation d’exécution Slack :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -866,8 +885,8 @@ Comportement par défaut sans configuration explicite des approbations d’exéc
|
||||
}
|
||||
```
|
||||
|
||||
Une configuration native Slack explicite n’est nécessaire que lorsque vous souhaitez remplacer les approbateurs, ajouter des filtres ou
|
||||
opter pour la livraison vers le chat d’origine :
|
||||
La configuration native Slack explicite n’est nécessaire que lorsque vous souhaitez remplacer les approbateurs, ajouter des filtres ou
|
||||
opter pour la livraison dans le chat d’origine :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -883,35 +902,35 @@ opter pour la livraison vers le chat d’origine :
|
||||
}
|
||||
```
|
||||
|
||||
Le transfert partagé `approvals.exec` est séparé. Utilisez-le uniquement lorsque les invites d’approbation d’exécution doivent aussi
|
||||
être routées vers d’autres chats ou des cibles explicites hors bande. Le transfert partagé `approvals.plugin` est également
|
||||
séparé ; les boutons natifs Slack peuvent toujours résoudre les approbations de Plugin lorsque ces demandes arrivent déjà
|
||||
Le transfert partagé `approvals.exec` est distinct. Utilisez-le uniquement lorsque les invites d’approbation d’exécution doivent aussi
|
||||
être routées vers d’autres chats ou des cibles hors bande explicites. Le transfert partagé `approvals.plugin` est également
|
||||
distinct ; les boutons natifs Slack peuvent toujours résoudre les approbations de Plugin lorsque ces requêtes arrivent déjà
|
||||
dans Slack.
|
||||
|
||||
La commande `/approve` dans le même chat fonctionne également dans les canaux et messages directs Slack qui prennent déjà en charge les commandes. Consultez [Approbations d’exécution](/fr/tools/exec-approvals) pour le modèle complet de transfert des approbations.
|
||||
`/approve` dans le même chat fonctionne aussi dans les canaux Slack et les DM qui prennent déjà en charge les commandes. Consultez [Approbations d’exécution](/fr/tools/exec-approvals) pour le modèle complet de transfert d’approbation.
|
||||
|
||||
## Événements et comportement opérationnel
|
||||
|
||||
- Les modifications/suppressions de messages sont mappées en événements système.
|
||||
- Les diffusions de fil (réponses de fil « Envoyer aussi au canal ») sont traitées comme des messages utilisateur normaux.
|
||||
- Les événements d’ajout/suppression de réactions sont mappés en événements système.
|
||||
- Les événements d’arrivée/départ de membres, de création/renommage de canal et d’ajout/suppression d’épingles sont mappés en événements système.
|
||||
- Les modifications/suppressions de messages sont mappées vers des événements système.
|
||||
- Les diffusions de fil (réponses de fil « Also send to channel ») sont traitées comme des messages utilisateur normaux.
|
||||
- Les événements d’ajout/retrait de réaction sont mappés vers des événements système.
|
||||
- Les événements d’arrivée/départ de membre, de création/renommage de canal et d’ajout/retrait d’épingle sont mappés vers des événements système.
|
||||
- `channel_id_changed` peut migrer les clés de configuration de canal lorsque `configWrites` est activé.
|
||||
- Les métadonnées de sujet/objectif de canal sont traitées comme du contexte non approuvé et peuvent être injectées dans le contexte de routage.
|
||||
- L’amorçage du contexte de démarreur de fil et d’historique initial de fil est filtré par les listes d’autorisation d’expéditeurs configurées, le cas échéant.
|
||||
- Les actions de blocs et les interactions de modales émettent des événements système structurés `Slack interaction: ...` avec des champs de charge utile riches :
|
||||
- actions de blocs : valeurs sélectionnées, libellés, valeurs de sélecteur et métadonnées `workflow_*`
|
||||
- événements de modale `view_submission` et `view_closed` avec métadonnées de canal routées et entrées de formulaire
|
||||
- Les métadonnées de sujet/objectif de canal sont traitées comme du contexte non fiable et peuvent être injectées dans le contexte de routage.
|
||||
- Le démarrage de fil et l’amorçage du contexte d’historique initial de fil sont filtrés par les listes d’autorisation d’expéditeurs configurées lorsqu’elles s’appliquent.
|
||||
- Les actions de bloc et les interactions modales émettent des événements système structurés `Slack interaction: ...` avec des champs de charge utile riches :
|
||||
- actions de bloc : valeurs sélectionnées, libellés, valeurs de sélecteur et métadonnées `workflow_*`
|
||||
- événements modaux `view_submission` et `view_closed` avec métadonnées de canal routées et entrées de formulaire
|
||||
|
||||
## Référence de configuration
|
||||
|
||||
Référence principale : [Référence de configuration - Slack](/fr/gateway/config-channels#slack).
|
||||
|
||||
<Accordion title="Champs Slack à fort signal">
|
||||
<Accordion title="High-signal Slack fields">
|
||||
|
||||
- mode/authentification : `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- accès aux messages directs : `dm.enabled`, `dmPolicy`, `allowFrom` (héritage : `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- bascule de compatibilité : `dangerouslyAllowNameMatching` (solution d’urgence ; laissez désactivé sauf nécessité)
|
||||
- accès DM : `dm.enabled`, `dmPolicy`, `allowFrom` (hérité : `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- bascule de compatibilité : `dangerouslyAllowNameMatching` (option d’urgence ; gardez-la désactivée sauf nécessité)
|
||||
- accès aux canaux : `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- fils/historique : `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- livraison : `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
@ -922,13 +941,13 @@ Référence principale : [Référence de configuration - Slack](/fr/gateway/conf
|
||||
## Dépannage
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Aucune réponse dans les canaux">
|
||||
<Accordion title="No replies in channels">
|
||||
Vérifiez, dans l’ordre :
|
||||
|
||||
- `groupPolicy`
|
||||
- liste d’autorisation des canaux (`channels.slack.channels`) — **les clés doivent être des identifiants de canal** (`C12345678`), pas des noms (`#channel-name`). Les clés fondées sur les noms échouent silencieusement avec `groupPolicy: "allowlist"`, car le routage de canal utilise d’abord les identifiants par défaut. Pour trouver un identifiant : faites un clic droit sur le canal dans Slack → **Copier le lien** — la valeur `C...` à la fin de l’URL est l’identifiant du canal.
|
||||
- liste d’autorisation de canaux (`channels.slack.channels`) — **les clés doivent être des ID de canal** (`C12345678`), pas des noms (`#channel-name`). Les clés basées sur le nom échouent silencieusement sous `groupPolicy: "allowlist"` parce que le routage de canal privilégie les ID par défaut. Pour trouver un ID : faites un clic droit sur le canal dans Slack → **Copy link** — la valeur `C...` à la fin de l’URL est l’ID du canal.
|
||||
- `requireMention`
|
||||
- liste d’autorisation `users` propre au canal
|
||||
- liste d’autorisation `users` par canal
|
||||
|
||||
Commandes utiles :
|
||||
|
||||
@ -940,13 +959,13 @@ openclaw doctor
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Messages directs ignorés">
|
||||
<Accordion title="DM messages ignored">
|
||||
Vérifiez :
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (ou l’héritage `channels.slack.dm.policy`)
|
||||
- approbations d’association / entrées de liste d’autorisation
|
||||
- Événements de message direct de l’assistant Slack : les journaux détaillés mentionnant `drop message_changed`
|
||||
- `channels.slack.dmPolicy` (ou l’ancien `channels.slack.dm.policy`)
|
||||
- approbations d’appairage / entrées de liste d’autorisation
|
||||
- Événements DM de Slack Assistant : les journaux détaillés mentionnant `drop message_changed`
|
||||
signifient généralement que Slack a envoyé un événement de fil Assistant modifié sans
|
||||
expéditeur humain récupérable dans les métadonnées du message
|
||||
|
||||
@ -956,8 +975,8 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Le mode socket ne se connecte pas">
|
||||
Validez les jetons de bot et d’application ainsi que l’activation du Socket Mode dans les paramètres de l’application Slack.
|
||||
<Accordion title="Socket mode not connecting">
|
||||
Validez les jetons bot + app et l’activation de Socket Mode dans les paramètres de l’application Slack.
|
||||
|
||||
Si `openclaw channels status --probe --json` affiche `botTokenStatus` ou
|
||||
`appTokenStatus: "configured_unavailable"`, le compte Slack est
|
||||
@ -965,69 +984,69 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Le mode HTTP ne reçoit pas les événements">
|
||||
<Accordion title="HTTP mode not receiving events">
|
||||
Validez :
|
||||
|
||||
- le secret de signature
|
||||
- le chemin Webhook
|
||||
- les URL de requête Slack (événements + interactivité + commandes slash)
|
||||
- un `webhookPath` unique par compte HTTP
|
||||
- `webhookPath` unique par compte HTTP
|
||||
|
||||
Si `signingSecretStatus: "configured_unavailable"` apparaît dans les
|
||||
instantanés de compte, le compte HTTP est configuré, mais l’exécution actuelle n’a pas pu
|
||||
Si `signingSecretStatus: "configured_unavailable"` apparaît dans les instantanés de compte,
|
||||
le compte HTTP est configuré, mais l’exécution actuelle n’a pas pu
|
||||
résoudre le secret de signature adossé à SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Les commandes natives/slash ne se déclenchent pas">
|
||||
Vérifiez ce que vous aviez l’intention d’utiliser :
|
||||
<Accordion title="Native/slash commands not firing">
|
||||
Vérifiez ce que vous vouliez utiliser :
|
||||
|
||||
- le mode de commande native (`channels.slack.commands.native: true`) avec des commandes slash correspondantes enregistrées dans Slack
|
||||
- ou le mode de commande slash unique (`channels.slack.slashCommand.enabled: true`)
|
||||
- mode de commande native (`channels.slack.commands.native: true`) avec des commandes slash correspondantes enregistrées dans Slack
|
||||
- ou mode de commande slash unique (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Vérifiez également `commands.useAccessGroups` ainsi que les listes d’autorisation de canaux/utilisateurs.
|
||||
Vérifiez également `commands.useAccessGroups` et les listes d’autorisation de canal/utilisateur.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Référence de vision pour les pièces jointes
|
||||
## Référence de vision des pièces jointes
|
||||
|
||||
Slack peut joindre les médias téléchargés au tour de l’agent lorsque les téléchargements de fichiers Slack réussissent et que les limites de taille le permettent. Les fichiers image peuvent passer par le chemin de compréhension des médias ou directement vers un modèle de réponse compatible vision ; les autres fichiers sont conservés comme contexte de fichier téléchargeable plutôt que traités comme entrée image.
|
||||
Slack peut joindre les médias téléchargés au tour de l’agent lorsque les téléchargements de fichiers Slack réussissent et que les limites de taille le permettent. Les fichiers image peuvent passer par le chemin de compréhension des médias ou directement vers un modèle de réponse compatible avec la vision ; les autres fichiers sont conservés comme contexte de fichier téléchargeable plutôt que traités comme entrée image.
|
||||
|
||||
### Types de médias pris en charge
|
||||
|
||||
| Type de média | Source | Comportement actuel | Notes |
|
||||
| ------------------------------ | -------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Images JPEG / PNG / GIF / WebP | URL de fichier Slack | Téléchargées et jointes au tour pour une gestion compatible avec la vision | Limite par fichier : `channels.slack.mediaMaxMb` (20 Mo par défaut) |
|
||||
| Fichiers PDF | URL de fichier Slack | Téléchargés et exposés comme contexte de fichier pour des outils comme `download-file` ou `pdf` | Le flux entrant Slack ne convertit pas automatiquement les PDF en entrée de vision d’image |
|
||||
| Autres fichiers | URL de fichier Slack | Téléchargés lorsque possible et exposés comme contexte de fichier | Les fichiers binaires ne sont pas traités comme entrée d’image |
|
||||
| Réponses de fil | Fichiers du message initial du fil | Les fichiers du message racine peuvent être hydratés comme contexte lorsque la réponse n’a aucun média direct | Les messages initiaux contenant uniquement des fichiers utilisent un espace réservé de pièce jointe |
|
||||
| Messages multi-images | Plusieurs fichiers Slack | Chaque fichier est évalué indépendamment | Le traitement Slack est limité à huit fichiers par message |
|
||||
| Type de média | Source | Comportement actuel | Notes |
|
||||
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Images JPEG / PNG / GIF / WebP | URL de fichier Slack | Téléchargées et jointes au tour pour une prise en charge compatible avec la vision | Limite par fichier : `channels.slack.mediaMaxMb` (par défaut 20 Mo) |
|
||||
| Fichiers PDF | URL de fichier Slack | Téléchargés et exposés comme contexte de fichier pour des outils tels que `download-file` ou `pdf` | L’entrée Slack ne convertit pas automatiquement les PDF en entrée de vision d’image |
|
||||
| Autres fichiers | URL de fichier Slack | Téléchargés lorsque c’est possible et exposés comme contexte de fichier | Les fichiers binaires ne sont pas traités comme entrée d’image |
|
||||
| Réponses de fil | Fichiers du message initial du fil | Les fichiers du message racine peuvent être hydratés comme contexte lorsque la réponse n’a pas de média direct | Les messages initiaux ne contenant que des fichiers utilisent un placeholder de pièce jointe |
|
||||
| Messages multi-images | Plusieurs fichiers Slack | Chaque fichier est évalué indépendamment | Le traitement Slack est limité à huit fichiers par message |
|
||||
|
||||
### Pipeline entrant
|
||||
|
||||
Lorsqu’un message Slack avec des pièces jointes de fichier arrive :
|
||||
|
||||
1. OpenClaw télécharge le fichier depuis l’URL privée de Slack à l’aide du jeton du bot (`xoxb-...`).
|
||||
2. Le fichier est écrit dans le stockage média en cas de succès.
|
||||
1. OpenClaw télécharge le fichier depuis l’URL privée de Slack à l’aide du token de bot (`xoxb-...`).
|
||||
2. Le fichier est écrit dans le stockage des médias en cas de réussite.
|
||||
3. Les chemins des médias téléchargés et les types de contenu sont ajoutés au contexte entrant.
|
||||
4. Les chemins de modèle ou d’outil compatibles avec les images peuvent utiliser les pièces jointes d’image de ce contexte.
|
||||
5. Les fichiers non image restent disponibles comme métadonnées de fichier ou références média pour les outils capables de les gérer.
|
||||
4. Les chemins de modèle/outil compatibles avec l’image peuvent utiliser les pièces jointes d’image depuis ce contexte.
|
||||
5. Les fichiers non image restent disponibles comme métadonnées de fichier ou références média pour les outils capables de les traiter.
|
||||
|
||||
### Héritage des pièces jointes de la racine du fil
|
||||
|
||||
Lorsqu’un message arrive dans un fil (avec un parent `thread_ts`) :
|
||||
|
||||
- Si la réponse elle-même n’a aucun média direct et que le message racine inclus contient des fichiers, Slack peut hydrater les fichiers racine comme contexte du message initial du fil.
|
||||
- Les pièces jointes directes de la réponse ont priorité sur les pièces jointes du message racine.
|
||||
- Un message racine qui ne contient que des fichiers et aucun texte est représenté avec un espace réservé de pièce jointe afin que le repli puisse toujours inclure ses fichiers.
|
||||
- Si la réponse elle-même n’a pas de média direct et que le message racine inclus contient des fichiers, Slack peut hydrater les fichiers racine comme contexte du message initial du fil.
|
||||
- Les pièces jointes directes de la réponse sont prioritaires sur les pièces jointes du message racine.
|
||||
- Un message racine qui ne contient que des fichiers et aucun texte est représenté avec un placeholder de pièce jointe afin que le fallback puisse toujours inclure ses fichiers.
|
||||
|
||||
### Gestion de plusieurs pièces jointes
|
||||
|
||||
Lorsqu’un seul message Slack contient plusieurs pièces jointes de fichier :
|
||||
|
||||
- Chaque pièce jointe est traitée indépendamment via le pipeline média.
|
||||
- Les références média téléchargées sont agrégées dans le contexte du message.
|
||||
- Les références des médias téléchargés sont agrégées dans le contexte du message.
|
||||
- L’ordre de traitement suit l’ordre des fichiers Slack dans la charge utile de l’événement.
|
||||
- L’échec du téléchargement d’une pièce jointe ne bloque pas les autres.
|
||||
|
||||
@ -1039,13 +1058,13 @@ Lorsqu’un seul message Slack contient plusieurs pièces jointes de fichier :
|
||||
|
||||
### Limites connues
|
||||
|
||||
| Scénario | Comportement actuel | Solution de contournement |
|
||||
| Scénario | Comportement actuel | Solution de contournement |
|
||||
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| URL de fichier Slack expirée | Fichier ignoré ; aucune erreur affichée | Retéléverser le fichier dans Slack |
|
||||
| URL de fichier Slack expirée | Fichier ignoré ; aucune erreur affichée | Téléverser à nouveau le fichier dans Slack |
|
||||
| Modèle de vision non configuré | Les pièces jointes d’image sont stockées comme références média, mais ne sont pas analysées comme images | Configurer `agents.defaults.imageModel` ou utiliser un modèle de réponse compatible avec la vision |
|
||||
| Images très volumineuses (> 20 Mo par défaut) | Ignorées selon la limite de taille | Augmenter `channels.slack.mediaMaxMb` si Slack l’autorise |
|
||||
| Pièces jointes transférées/partagées | Le texte et les médias image/fichier hébergés par Slack sont traités au mieux | Repartager directement dans le fil OpenClaw |
|
||||
| Pièces jointes PDF | Stockées comme contexte fichier/média, sans routage automatique par la vision d’image | Utiliser `download-file` pour les métadonnées de fichier ou l’outil `pdf` pour l’analyse PDF |
|
||||
| Images très volumineuses (> 20 Mo par défaut) | Ignorées selon la limite de taille | Augmenter `channels.slack.mediaMaxMb` si Slack l’autorise |
|
||||
| Pièces jointes transférées/partagées | Le texte et les médias image/fichier hébergés par Slack sont traités au mieux | Repartager directement dans le fil OpenClaw |
|
||||
| Pièces jointes PDF | Stockées comme contexte de fichier/média, sans routage automatique via la vision d’image | Utiliser `download-file` pour les métadonnées de fichier ou l’outil `pdf` pour l’analyse PDF |
|
||||
|
||||
### Documentation associée
|
||||
|
||||
@ -1058,22 +1077,22 @@ Lorsqu’un seul message Slack contient plusieurs pièces jointes de fichier :
|
||||
## Associé
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
|
||||
<Card title="Pairing" icon="link" href="/fr/channels/pairing">
|
||||
Associer un utilisateur Slack au Gateway.
|
||||
</Card>
|
||||
<Card title="Groupes" icon="users" href="/fr/channels/groups">
|
||||
<Card title="Groups" icon="users" href="/fr/channels/groups">
|
||||
Comportement des canaux et des MP de groupe.
|
||||
</Card>
|
||||
<Card title="Routage des canaux" icon="route" href="/fr/channels/channel-routing">
|
||||
Acheminer les messages entrants vers les agents.
|
||||
<Card title="Channel routing" icon="route" href="/fr/channels/channel-routing">
|
||||
Router les messages entrants vers des agents.
|
||||
</Card>
|
||||
<Card title="Sécurité" icon="shield" href="/fr/gateway/security">
|
||||
<Card title="Security" icon="shield" href="/fr/gateway/security">
|
||||
Modèle de menace et durcissement.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/fr/gateway/configuration">
|
||||
Structure et priorité de la configuration.
|
||||
Agencement et précédence de la configuration.
|
||||
</Card>
|
||||
<Card title="Commandes slash" icon="terminal" href="/fr/tools/slash-commands">
|
||||
<Card title="Slash commands" icon="terminal" href="/fr/tools/slash-commands">
|
||||
Catalogue et comportement des commandes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- Travailler sur les fonctionnalités Telegram ou les Webhooks
|
||||
summary: État de la prise en charge du bot Telegram, fonctionnalités et configuration
|
||||
summary: État de la prise en charge du bot Telegram, capacités et configuration
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:16Z"
|
||||
generated_at: "2026-05-04T07:02:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Prêt pour la production pour les messages privés de bots et les groupes via grammY. Le mode par défaut est le long polling ; le mode Webhook est facultatif.
|
||||
Prêt pour la production pour les DM de bots et les groupes via grammY. L’interrogation longue est le mode par défaut ; le mode Webhook est facultatif.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Association" icon="link" href="/fr/channels/pairing">
|
||||
La stratégie de messages privés par défaut pour Telegram est l’association.
|
||||
<Card title="Appairage" icon="link" href="/fr/channels/pairing">
|
||||
La politique de DM par défaut pour Telegram est l’appairage.
|
||||
</Card>
|
||||
<Card title="Dépannage des canaux" icon="wrench" href="/fr/channels/troubleshooting">
|
||||
Diagnostics intercanaux et guides de réparation.
|
||||
@ -30,13 +30,13 @@ Prêt pour la production pour les messages privés de bots et les groupes via gr
|
||||
|
||||
<Steps>
|
||||
<Step title="Créer le jeton du bot dans BotFather">
|
||||
Ouvrez Telegram et discutez avec **@BotFather** (vérifiez que l’identifiant est exactement `@BotFather`).
|
||||
Ouvrez Telegram et discutez avec **@BotFather** (confirmez que l’identifiant est exactement `@BotFather`).
|
||||
|
||||
Exécutez `/newbot`, suivez les invites et enregistrez le jeton.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configurer le jeton et la stratégie des messages privés">
|
||||
<Step title="Configurer le jeton et la politique de DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -52,11 +52,11 @@ Prêt pour la production pour les messages privés de bots et les groupes via gr
|
||||
```
|
||||
|
||||
Solution de repli par variable d’environnement : `TELEGRAM_BOT_TOKEN=...` (compte par défaut uniquement).
|
||||
Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans la configuration ou l’environnement, puis démarrez le Gateway.
|
||||
Telegram n’utilise **pas** `openclaw channels login telegram` ; configurez le jeton dans la config/l’environnement, puis démarrez le Gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Démarrer le Gateway et approuver le premier message privé">
|
||||
<Step title="Démarrer le Gateway et approuver le premier DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,31 +64,31 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Les codes d’association expirent après 1 heure.
|
||||
Les codes d’appairage expirent après 1 heure.
|
||||
|
||||
</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 correspondre à votre modèle d’accès.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
L’ordre de résolution des jetons tient compte du compte. En pratique, les valeurs de configuration priment sur la solution de repli par variable d’environnement, et `TELEGRAM_BOT_TOKEN` ne s’applique qu’au compte par défaut.
|
||||
L’ordre de résolution des jetons tient compte du compte. En pratique, les valeurs de configuration l’emportent sur la solution de repli par variable d’environnement, et `TELEGRAM_BOT_TOKEN` s’applique uniquement au compte par défaut.
|
||||
</Note>
|
||||
|
||||
## Paramètres côté Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Mode de confidentialité et visibilité des groupes">
|
||||
Par défaut, les bots Telegram utilisent le **Mode de confidentialité**, qui limite les messages de groupe qu’ils reçoivent.
|
||||
Les bots Telegram utilisent par défaut le **mode de confidentialité**, qui limite les messages de groupe qu’ils reçoivent.
|
||||
|
||||
Si le bot doit voir tous les messages de groupe, vous pouvez :
|
||||
Si le bot doit voir tous les messages de groupe, vous pouvez soit :
|
||||
|
||||
- désactiver le mode de confidentialité avec `/setprivacy`, ou
|
||||
- désactiver le mode de confidentialité via `/setprivacy`, soit
|
||||
- faire du bot un administrateur du groupe.
|
||||
|
||||
Lorsque vous modifiez le mode de confidentialité, retirez puis réajoutez le bot dans chaque groupe afin que Telegram applique le changement.
|
||||
Lorsque vous activez ou désactivez le mode de confidentialité, supprimez puis rajoutez le bot dans chaque groupe afin que Telegram applique la modification.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -101,8 +101,8 @@ L’ordre de résolution des jetons tient compte du compte. En pratique, les val
|
||||
|
||||
<Accordion title="Options BotFather utiles">
|
||||
|
||||
- `/setjoingroups` pour autoriser ou refuser les ajouts aux groupes
|
||||
- `/setprivacy` pour le comportement de visibilité dans les groupes
|
||||
- `/setjoingroups` pour autoriser/refuser les ajouts aux groupes
|
||||
- `/setprivacy` pour le comportement de visibilité des groupes
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -110,7 +110,7 @@ L’ordre de résolution des jetons tient compte du compte. En pratique, les val
|
||||
## Contrôle d’accès et activation
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Stratégie de messages privés">
|
||||
<Tab title="Politique de DM">
|
||||
`channels.telegram.dmPolicy` contrôle l’accès aux messages directs :
|
||||
|
||||
- `pairing` (par défaut)
|
||||
@ -121,24 +121,24 @@ L’ordre de résolution des jetons tient compte du compte. En pratique, les val
|
||||
`dmPolicy: "open"` avec `allowFrom: ["*"]` permet à tout compte Telegram qui trouve ou devine le nom d’utilisateur du bot de commander le bot. Utilisez-le uniquement pour des bots volontairement publics avec des outils strictement restreints ; les bots à propriétaire unique doivent utiliser `allowlist` avec des ID utilisateur numériques.
|
||||
|
||||
`channels.telegram.allowFrom` accepte les ID utilisateur Telegram numériques. Les préfixes `telegram:` / `tg:` sont acceptés et normalisés.
|
||||
Dans les configurations multicomptes, un `channels.telegram.allowFrom` restrictif au niveau supérieur est traité comme une frontière de sécurité : les entrées `allowFrom: ["*"]` au niveau du compte ne rendent pas ce compte public, sauf si la liste d’autorisation effective du compte contient encore un joker explicite après la fusion.
|
||||
`dmPolicy: "allowlist"` avec un `allowFrom` vide bloque tous les messages privés et est rejeté par la validation de configuration.
|
||||
Dans les configurations multicompte, un `channels.telegram.allowFrom` restrictif de premier niveau est traité comme une limite de sécurité : les entrées `allowFrom: ["*"]` au niveau du compte ne rendent pas ce compte public, sauf si la liste d’autorisation effective du compte contient toujours un caractère générique explicite après la fusion.
|
||||
`dmPolicy: "allowlist"` avec `allowFrom` vide bloque tous les DM et est rejeté par la validation de configuration.
|
||||
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 utilisiez auparavant des fichiers de liste d’autorisation du magasin d’association, `openclaw doctor --fix` peut récupérer les 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 de liste d’autorisation (par exemple lorsque `dmPolicy: "allowlist"` n’a pas encore d’ID explicites).
|
||||
|
||||
Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID numériques explicites dans `allowFrom` afin de conserver une stratégie d’accès durable dans la configuration (au lieu de dépendre des approbations d’association précédentes).
|
||||
Pour les bots à propriétaire unique, préférez `dmPolicy: "allowlist"` avec des ID `allowFrom` numériques explicites afin de garder la politique d’accès durable dans la configuration (au lieu de dépendre des approbations d’appairage précédentes).
|
||||
|
||||
Confusion courante : l’approbation d’association par message privé ne signifie pas « cet expéditeur est autorisé partout ».
|
||||
L’association accorde l’accès aux messages privés. S’il n’existe pas encore de propriétaire des commandes, la première association approuvée définit aussi `commands.ownerAllowFrom` afin que les commandes réservées au propriétaire et les approbations d’exécution aient un compte opérateur explicite.
|
||||
L’autorisation des expéditeurs dans les groupes provient toujours des listes d’autorisation explicites de la configuration.
|
||||
Si vous voulez « je suis autorisé une fois, et les messages privés comme les commandes de groupe fonctionnent », placez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom` ; pour les commandes réservées au propriétaire, assurez-vous que `commands.ownerAllowFrom` contient `telegram:<your user id>`.
|
||||
Confusion courante : l’approbation d’appairage des DM ne signifie pas « cet expéditeur est autorisé partout ».
|
||||
L’appairage accorde l’accès aux DM. Si aucun propriétaire de commande n’existe encore, le premier appairage approuvé définit aussi `commands.ownerAllowFrom` afin que les commandes réservées au propriétaire et les approbations d’exécution aient un compte opérateur explicite.
|
||||
L’autorisation des expéditeurs de groupe provient toujours des listes d’autorisation explicites de la configuration.
|
||||
Si vous voulez « je suis autorisé une fois et les DM comme les commandes de groupe fonctionnent », mettez votre ID utilisateur Telegram numérique dans `channels.telegram.allowFrom` ; pour les commandes réservées au propriétaire, assurez-vous que `commands.ownerAllowFrom` contient `telegram:<your user id>`.
|
||||
|
||||
### Trouver votre ID utilisateur Telegram
|
||||
|
||||
Plus sûr (aucun bot tiers) :
|
||||
Plus sûr (sans bot tiers)
|
||||
|
||||
1. Envoyez un message privé à votre bot.
|
||||
1. Envoyez un message direct à votre bot.
|
||||
2. Exécutez `openclaw logs --follow`.
|
||||
3. Lisez `from.id`.
|
||||
|
||||
@ -152,12 +152,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Stratégie de groupe et listes d’autorisation">
|
||||
<Tab title="Group policy and allowlists">
|
||||
Deux contrôles s’appliquent ensemble :
|
||||
|
||||
1. **Quels groupes sont autorisés** (`channels.telegram.groups`)
|
||||
- pas de configuration `groups` :
|
||||
- avec `groupPolicy: "open"` : n’importe quel groupe peut réussir les contrôles d’ID de groupe
|
||||
- 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 `"*"`)
|
||||
|
||||
@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
`groupAllowFrom` est utilisé pour filtrer les expéditeurs de groupe. 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 mettez pas d’ID de discussion de groupe ou de supergroupe Telegram dans `groupAllowFrom`. Les ID de discussion négatifs doivent être placés sous `channels.telegram.groups`.
|
||||
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.
|
||||
Frontière de sécurité (`2026.2.25+`) : l’authentification des expéditeurs de groupe n’hérite **pas** des approbations du magasin d’association des messages privés.
|
||||
L’association reste limitée aux messages privés. Pour les groupes, définissez `groupAllowFrom` ou un `allowFrom` par groupe ou par sujet.
|
||||
Si `groupAllowFrom` n’est pas défini, Telegram se rabat sur la configuration `allowFrom`, et non sur le magasin d’association.
|
||||
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 des messages directs.
|
||||
L’appairage reste limité aux messages directs. Pour les groupes, définissez `groupAllowFrom` ou `allowFrom` par groupe/par sujet.
|
||||
Si `groupAllowFrom` n’est pas défini, Telegram se rabat sur la configuration `allowFrom`, pas 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 d’exécution : si `channels.telegram` est totalement absent, l’exécution adopte par défaut un comportement fermé avec `groupPolicy="allowlist"`, sauf si `channels.defaults.groupPolicy` est explicitement défini.
|
||||
Note d’exécution : si `channels.telegram` est complètement absent, l’exécution utilise par défaut une stratégie fermée `groupPolicy="allowlist"`, sauf si `channels.defaults.groupPolicy` est explicitement défini.
|
||||
|
||||
Exemple : autoriser n’importe quel membre dans un groupe spécifique :
|
||||
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Exemple : autoriser uniquement certains utilisateurs dans un groupe spécifique :
|
||||
Exemple : n’autoriser que des utilisateurs spécifiques dans un groupe spécifique :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,30 +213,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Erreur courante : `groupAllowFrom` n’est pas une liste d’autorisation de groupes Telegram.
|
||||
|
||||
- Placez les ID de discussion de groupe ou de supergroupe Telegram négatifs comme `-1001234567890` sous `channels.telegram.groups`.
|
||||
- Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes qui, dans un groupe autorisé, peuvent déclencher le bot.
|
||||
- Placez les ID de chat de groupe ou de supergroupe Telegram négatifs comme `-1001234567890` sous `channels.telegram.groups`.
|
||||
- Placez les ID utilisateur Telegram comme `8734062810` sous `groupAllowFrom` lorsque vous voulez limiter les personnes, au sein d’un groupe autorisé, qui 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 nécessitent une mention par défaut.
|
||||
<Tab title="Mention behavior">
|
||||
Les réponses de groupe exigent une mention par défaut.
|
||||
|
||||
La mention peut provenir de :
|
||||
La mention peut provenir :
|
||||
|
||||
- une mention native `@botusername`, ou
|
||||
- des motifs de mention dans :
|
||||
- d’une mention native `@botusername`, ou
|
||||
- de modèles de mention dans :
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Options de commande au niveau de la session :
|
||||
Bascules de commande au niveau de la session :
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Elles mettent uniquement à jour l’état de la session. Utilisez la configuration pour la persistance.
|
||||
Elles ne mettent à jour que l’état de session. Utilisez la configuration pour la persistance.
|
||||
|
||||
Exemple de configuration persistante :
|
||||
|
||||
@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Obtenir l’ID de discussion du groupe :
|
||||
Obtenir l’ID du chat de groupe :
|
||||
|
||||
- transférez un message de groupe à `@userinfobot` / `@getidsbot`
|
||||
- ou lisez `chat.id` depuis `openclaw logs --follow`
|
||||
@ -261,35 +261,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportement à l’exécution
|
||||
## Comportement d’exécution
|
||||
|
||||
- Telegram appartient au processus Gateway.
|
||||
- Le routage est déterministe : les messages entrants Telegram reçoivent une réponse sur Telegram (le modèle ne choisit pas les canaux).
|
||||
- Le routage est déterministe : les réponses entrantes 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 les métadonnées de réponse et les espaces réservés de 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 privés peuvent porter `message_thread_id` ; OpenClaw préserve l’ID de fil pour les réponses, mais garde les messages privés sur la session plate par défaut. Configurez `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true`, ou une configuration de sujet correspondante lorsque vous voulez intentionnellement isoler les sessions par sujet dans les messages privés.
|
||||
- Le long polling utilise grammY runner avec un séquencement par discussion et par fil. La concurrence globale du puits du runner utilise `agents.defaults.maxConcurrent`.
|
||||
- Le long polling est protégé dans chaque processus Gateway afin qu’un seul poller actif puisse utiliser un jeton de bot à la fois. Si vous voyez encore des conflits `getUpdates` 409, un autre Gateway OpenClaw, un script ou un poller externe utilise probablement le même jeton.
|
||||
- Les redémarrages du watchdog de long polling se déclenchent par défaut après 120 secondes sans activité `getUpdates` terminée. Augmentez `channels.telegram.pollingStallThresholdMs` uniquement si votre déploiement voit encore de faux redémarrages pour blocage de polling pendant des tâches longues. La valeur est en millisecondes et autorisée de `30000` à `600000` ; les remplacements par compte sont pris en charge.
|
||||
- Les messages directs peuvent transporter `message_thread_id` ; OpenClaw conserve l’ID de fil pour les réponses, mais garde par défaut les messages directs sur la session plate. Configurez `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true`, ou une configuration de sujet correspondante lorsque vous voulez intentionnellement isoler les sessions de sujet en message direct.
|
||||
- L’interrogation longue utilise le runner grammY avec un séquencement par chat/par fil. La concurrence globale du puits du runner utilise `agents.defaults.maxConcurrent`.
|
||||
- L’interrogation longue est protégée dans chaque processus Gateway afin qu’un seul poller actif puisse utiliser un token de bot à la fois. Si vous voyez encore des conflits `getUpdates` 409, un autre Gateway OpenClaw, script ou poller externe utilise probablement le même token.
|
||||
- Les redémarrages du chien de garde d’interrogation longue se déclenchent par défaut après 120 secondes sans vivacité `getUpdates` terminée. Augmentez `channels.telegram.pollingStallThresholdMs` uniquement si votre déploiement observe encore de faux redémarrages pour blocage d’interrogation pendant des tâches longues. La valeur est en millisecondes et est autorisée de `30000` à `600000` ; les remplacements par compte sont pris en charge.
|
||||
- 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 du flux en direct (modifications de message)">
|
||||
<Accordion title="Live stream preview (message edits)">
|
||||
OpenClaw peut diffuser des réponses partielles en temps réel :
|
||||
|
||||
- discussions directes : message d’aperçu + `editMessageText`
|
||||
- chats directs : message d’aperçu + `editMessageText`
|
||||
- groupes/sujets : message d’aperçu + `editMessageText`
|
||||
|
||||
Exigence :
|
||||
|
||||
- `channels.telegram.streaming` est `off | partial | block | progress` (par défaut : `partial`)
|
||||
- `channels.telegram.streaming` vaut `off | partial | block | progress` (par défaut : `partial`)
|
||||
- `progress` conserve un brouillon d’état modifiable et le met à jour avec la progression des outils jusqu’à la livraison finale
|
||||
- `streaming.preview.toolProgress` contrôle si les mises à jour d’outil/progression réutilisent le même message d’aperçu modifié (par défaut : `true` lorsque le streaming d’aperçu est actif)
|
||||
- les anciens `channels.telegram.streamMode` et les valeurs booléennes `streaming` sont détectés ; exécutez `openclaw doctor --fix` pour les migrer vers `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.commandText` contrôle les détails de commande/d’exécution dans ces lignes de progression d’outil : `raw` (par défaut, conserve le comportement publié) ou `status` (étiquette de l’outil uniquement)
|
||||
- les anciens `channels.telegram.streamMode` et valeurs booléennes `streaming` sont détectés ; exécutez `openclaw doctor --fix` pour les migrer vers `channels.telegram.streaming.mode`
|
||||
|
||||
Les mises à jour d’aperçu de progression des outils sont les courtes lignes d’état affichées pendant l’exécution des outils, par exemple l’exécution de commandes, les lectures de fichiers, les mises à jour de planification ou les résumés de patch. Telegram les garde activées par défaut afin de correspondre au comportement publié d’OpenClaw depuis `v2026.4.22` et versions ultérieures. Pour conserver l’aperçu modifié pour le texte de réponse, mais masquer les lignes de progression des outils, définissez :
|
||||
Les mises à jour d’aperçu de progression d’outil sont les courtes lignes d’état affichées pendant l’exécution des outils, par exemple l’exécution de commandes, les lectures de fichiers, les mises à jour de planification ou les résumés de correctifs. Telegram les garde activées par défaut pour correspondre au comportement OpenClaw publié depuis `v2026.4.22` et versions ultérieures. Pour conserver l’aperçu modifié pour le texte de réponse mais masquer les lignes de progression d’outil, définissez :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,34 +307,70 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez `streaming.mode: "off"` uniquement lorsque vous souhaitez une livraison finale uniquement : les modifications d’aperçu Telegram sont désactivées et les échanges génériques d’outils/de progression sont supprimés au lieu d’être envoyés comme messages d’état autonomes. Les invites d’approbation, les charges utiles multimédias et les erreurs passent toujours par la livraison finale normale. Utilisez `streaming.preview.toolProgress: false` lorsque vous voulez seulement conserver les modifications d’aperçu de réponse tout en masquant les lignes d’état de progression des outils.
|
||||
Pour garder la progression d’outil visible mais masquer le texte de commande/d’exécution, définissez :
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Pour le mode brouillon de progression, placez la même stratégie de texte de commande sous `streaming.progress` :
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez `streaming.mode: "off"` uniquement lorsque vous voulez une livraison finale uniquement : les modifications d’aperçu Telegram sont désactivées et le bavardage générique d’outil/progression est supprimé au lieu d’être envoyé comme messages d’état autonomes. Les demandes d’approbation, les charges utiles multimédias et les erreurs passent toujours par la livraison finale normale. Utilisez `streaming.preview.toolProgress: false` lorsque vous voulez seulement conserver les modifications d’aperçu de réponse tout en masquant les lignes d’état de progression des outils.
|
||||
|
||||
<Note>
|
||||
Les réponses avec citation sélectionnée Telegram sont l’exception. Lorsque `replyToMode` vaut `"first"`, `"all"` ou `"batched"` et que le message entrant inclut du texte de citation sélectionné, OpenClaw envoie la réponse finale via le chemin natif de réponse avec citation de Telegram au lieu de modifier l’aperçu de réponse ; `streaming.preview.toolProgress` ne peut donc pas afficher les courtes lignes d’état pour ce tour. Les réponses au message courant sans texte de citation sélectionné conservent toujours le streaming d’aperçu. Définissez `replyToMode: "off"` lorsque la visibilité de la progression des outils compte davantage que les réponses avec citation natives, ou définissez `streaming.preview.toolProgress: false` pour accepter le compromis.
|
||||
Les réponses avec citation sélectionnée Telegram font exception. Lorsque `replyToMode` vaut `"first"`, `"all"` ou `"batched"` et que le message entrant inclut du texte de citation sélectionné, OpenClaw envoie la réponse finale via le chemin de réponse avec citation natif de Telegram au lieu de modifier l’aperçu de réponse, de sorte que `streaming.preview.toolProgress` ne peut pas afficher les courtes lignes d’état pour ce tour. Les réponses au message actuel sans texte de citation sélectionné conservent toujours le streaming d’aperçu. Définissez `replyToMode: "off"` lorsque la visibilité de la progression des outils est plus importante que les réponses avec citation natives, ou définissez `streaming.preview.toolProgress: false` pour reconnaître ce compromis.
|
||||
</Note>
|
||||
|
||||
Pour les réponses uniquement textuelles :
|
||||
Pour les réponses en texte uniquement :
|
||||
|
||||
- aperçus courts en message privé/groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place, sauf si un message visible hors aperçu a été envoyé après l’apparition de l’aperçu
|
||||
- aperçus suivis d’une sortie visible hors aperçu : OpenClaw envoie la réponse terminée comme nouveau message final et nettoie l’ancien aperçu, de sorte que la réponse finale apparaisse après la sortie intermédiaire
|
||||
- aperçus vieux d’environ plus d’une minute : OpenClaw envoie la réponse terminée comme nouveau message final, puis nettoie l’aperçu, de sorte que l’horodatage visible de Telegram reflète l’heure de fin plutôt que l’heure de création de l’aperçu
|
||||
- aperçus courts en DM/groupe/sujet : OpenClaw conserve le même message d’aperçu et effectue une modification finale sur place, sauf si un message visible qui n’est pas un aperçu a été envoyé après l’apparition de l’aperçu
|
||||
- aperçus suivis d’une sortie visible qui n’est pas un aperçu : OpenClaw envoie la réponse terminée comme nouveau message final et nettoie l’ancien aperçu, de sorte que la réponse finale apparaisse après la sortie intermédiaire
|
||||
- aperçus de plus d’environ une minute : OpenClaw envoie la réponse terminée comme nouveau message final, puis nettoie l’aperçu, de sorte que l’horodatage visible de Telegram reflète l’heure d’achèvement plutôt que l’heure de création de l’aperçu
|
||||
|
||||
Pour les réponses complexes (par exemple les charges utiles multimédias), OpenClaw revient à la livraison finale normale, puis nettoie le message d’aperçu.
|
||||
|
||||
Le streaming d’aperçu est distinct du streaming par blocs. Lorsque le streaming par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter un double streaming.
|
||||
Le streaming d’aperçu est distinct du streaming par blocs. Lorsque le streaming par blocs est explicitement activé pour Telegram, OpenClaw ignore le flux d’aperçu pour éviter le double streaming.
|
||||
|
||||
Flux de raisonnement propre à Telegram :
|
||||
|
||||
- `/reasoning stream` envoie le raisonnement à l’aperçu en direct pendant la génération
|
||||
- l’aperçu du raisonnement est supprimé après la livraison finale ; utilisez `/reasoning on` lorsque le raisonnement doit rester visible
|
||||
- la réponse finale est envoyée sans texte de raisonnement
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formatage et solution de repli HTML">
|
||||
<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 compatible avec Telegram.
|
||||
- Le HTML brut du modèle est échappé afin de réduire les échecs d’analyse 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`.
|
||||
@ -341,13 +378,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Commandes natives et commandes personnalisées">
|
||||
L’enregistrement du menu des commandes Telegram est géré au démarrage avec `setMyCommands`.
|
||||
L’enregistrement du menu de commandes Telegram est géré au démarrage avec `setMyCommands`.
|
||||
|
||||
Valeurs par défaut des commandes natives :
|
||||
|
||||
- `commands.native: "auto"` active les commandes natives pour Telegram
|
||||
|
||||
Ajouter des entrées de menu de commandes personnalisées :
|
||||
Ajoutez des entrées personnalisées au menu de commandes :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -367,35 +404,35 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- les noms sont normalisés (suppression du `/` initial, minuscules)
|
||||
- motif valide : `a-z`, `0-9`, `_`, longueur `1..32`
|
||||
- les commandes personnalisées ne peuvent pas remplacer les commandes natives
|
||||
- les conflits/doublons sont ignorés et consignés
|
||||
- les conflits/doublons sont ignorés et journalisés
|
||||
|
||||
Notes :
|
||||
|
||||
- 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
|
||||
- les commandes de plugin/skill 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 s’enregistrer 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 toujours s’enregistrer si elles sont configurées.
|
||||
|
||||
Échecs de configuration courants :
|
||||
|
||||
- `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 `BOT_COMMANDS_TOO_MUCH` signifie que le menu Telegram déborde toujours après réduction ; réduisez les commandes de plugin/skill/personnalisées ou désactivez `channels.telegram.commands.native`.
|
||||
- L’échec de `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` avec `404: Not Found` alors que les commandes curl directes de l’API Bot fonctionnent peut signifier que `channels.telegram.apiRoot` a été défini sur le point de terminaison complet `/bot<TOKEN>`. `apiRoot` doit être uniquement la racine de l’API Bot, et `openclaw doctor --fix` supprime un `/bot<TOKEN>` final accidentel.
|
||||
- `getMe returned 401` signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation, ce qui évite que cela soit signalé comme un échec de nettoyage de Webhook.
|
||||
- `setMyCommands failed` avec des erreurs réseau/fetch signifie généralement que le DNS/HTTPS sortant vers `api.telegram.org` est bloqué.
|
||||
- `getMe returned 401` signifie que Telegram a rejeté le jeton de bot configuré. Mettez à jour `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` avec le jeton BotFather actuel ; OpenClaw s’arrête avant l’interrogation, ce n’est donc pas signalé comme un échec de nettoyage Webhook.
|
||||
- `setMyCommands failed` avec des erreurs réseau/fetch signifie généralement que les sorties DNS/HTTPS vers `api.telegram.org` sont bloquées.
|
||||
|
||||
### 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 le code de configuration
|
||||
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 (rôle/portées inclus)
|
||||
3. `/pair pending` liste les demandes en attente (y compris rôle/portées)
|
||||
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 d’amorçage à courte durée de vie. Le transfert d’amorçage intégré conserve le jeton du nœud principal à `scopes: []` ; tout jeton d’opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les vérifications de portée d’amorçage sont préfixées par rôle, de sorte que cette liste d’autorisation d’opérateur ne satisfait que les demandes d’opérateur ; les rôles non opérateur nécessitent toujours des portées sous leur propre préfixe de rôle.
|
||||
Le code de configuration transporte un jeton de bootstrap de courte durée. Le transfert de bootstrap intégré conserve le jeton du nœud principal avec `scopes: []` ; tout jeton opérateur transféré reste limité à `operator.approvals`, `operator.read`, `operator.talk.secrets` et `operator.write`. Les contrôles de portée de bootstrap sont préfixés par rôle, de sorte que cette liste d’autorisation d’opérateur ne satisfait que les demandes d’opérateur ; les rôles non opérateurs ont toujours besoin de portées 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 `requestId` différent. Réexécutez `/pair pending` avant d’approuver.
|
||||
|
||||
@ -404,7 +441,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Boutons intégrés">
|
||||
Configurer la portée du clavier intégré :
|
||||
Configurez la portée du clavier intégré :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -469,18 +506,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Actions de message Telegram pour les agents et l’automatisation">
|
||||
<Accordion title="Actions de message Telegram pour agents et automatisation">
|
||||
Les actions d’outil Telegram incluent :
|
||||
|
||||
- `sendMessage` (`to`, `content`, `mediaUrl` facultatif, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, optionnel `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, `iconColor` facultatif, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, optionnel `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Les actions de message de canal exposent des alias ergonomiques (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Contrôles de filtrage :
|
||||
Contrôles de gating :
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -488,27 +525,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (par défaut : désactivé)
|
||||
|
||||
Note : `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 d’exécution utilisent l’instantané actif de configuration/secrets (démarrage/rechargement), de sorte que les chemins d’action ne réévaluent pas ponctuellement les SecretRef à chaque envoi.
|
||||
Les envois à l’exécution utilisent l’instantané actif de configuration/secrets (démarrage/rechargement), de sorte que les chemins d’action ne réévaluent pas les SecretRef de manière ad hoc à chaque envoi.
|
||||
|
||||
Sémantique de suppression des réactions : [/tools/reactions](/fr/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 les balises explicites de fil de réponse dans la sortie générée :
|
||||
<Accordion title="Balises de fil de réponses">
|
||||
Telegram prend en charge les balises explicites de fil de réponses 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
|
||||
|
||||
`channels.telegram.replyToMode` contrôle la gestion :
|
||||
`channels.telegram.replyToMode` contrôle le traitement :
|
||||
|
||||
- `off` (par défaut)
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Lorsque le fil de réponse est activé et que le texte ou la légende Telegram d’origine est disponible, OpenClaw inclut automatiquement un extrait de citation natif Telegram. Telegram limite le texte de citation natif à 1024 unités de code UTF-16 ; les messages plus longs sont donc cités depuis le début et reviennent à une réponse simple si Telegram rejette la citation.
|
||||
Lorsque le fil de réponses est activé et que le texte ou la légende Telegram d’origine est disponible, OpenClaw inclut automatiquement un extrait de citation Telegram natif. Telegram limite le texte de citation natif à 1024 unités de code UTF-16, donc les messages plus longs sont cités depuis le début et reviennent à une réponse simple si Telegram rejette la citation.
|
||||
|
||||
Note : `off` désactive le fil de réponse implicite. Les balises explicites `[[reply_to_*]]` restent honorées.
|
||||
Note : `off` désactive le fil de réponses implicite. Les balises explicites `[[reply_to_*]]` restent honorées.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -525,10 +562,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- les envois de message omettent `message_thread_id` (Telegram rejette `sendMessage(...thread_id=1)`)
|
||||
- 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`).
|
||||
Héritage des sujets : les entrées de sujet héritent des paramètres de groupe sauf remplacement (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`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 mémoire et sa session isolés. 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 mémoire et sa session isolés. Exemple :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -548,26 +585,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Chaque sujet dispose ensuite de sa propre clé de session : `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Chaque sujet possède ensuite sa propre clé de session : `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Liaison de sujet ACP persistante** : les sujets de forum peuvent épingler des sessions de harnais ACP via des liaisons ACP typées de premier niveau (`bindings[]` avec `type: "acp"` et `match.channel: "telegram"`, `peer.kind: "group"`, ainsi qu’un identifiant qualifié par sujet comme `-1001234567890:topic:42`). Actuellement limité aux sujets de forum dans les groupes/supergroupes. Voir [Agents ACP](/fr/tools/acp-agents).
|
||||
**Liaison persistante de sujet ACP** : les sujets de forum peuvent épingler des sessions de harnais ACP via des liaisons ACP typées de premier niveau (`bindings[]` avec `type: "acp"` et `match.channel: "telegram"`, `peer.kind: "group"` et un identifiant qualifié par sujet comme `-1001234567890:topic:42`). Actuellement limité aux sujets de forum dans les groupes/supergroupes. Consultez [Agents ACP](/fr/tools/acp-agents).
|
||||
|
||||
**Création ACP liée au fil depuis le chat** : `/acp spawn <agent> --thread here|auto` lie le sujet courant à une nouvelle session ACP ; les suites y sont routées directement. OpenClaw épingle la confirmation de création dans le sujet. Nécessite que `channels.telegram.threadBindings.spawnSessions` reste activé (par défaut : `true`).
|
||||
**Lancement ACP lié au fil depuis le chat** : `/acp spawn <agent> --thread here|auto` lie le sujet actuel à une nouvelle session ACP ; les suivis y sont routés directement. OpenClaw épingle la confirmation de lancement dans le sujet. Nécessite que `channels.telegram.threadBindings.spawnSessions` reste activé (par défaut : `true`).
|
||||
|
||||
Le contexte de modèle expose `MessageThreadId` et `IsForum`. Les conversations en message privé avec `message_thread_id` conservent par défaut le routage de message privé et les métadonnées de réponse sur des sessions plates ; elles n’utilisent des clés de session conscientes des fils que lorsqu’elles sont configurées avec `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou une configuration de sujet correspondante. Utilisez `channels.telegram.dm.threadReplies` de premier niveau comme valeur par défaut du compte, ou `direct.<chatId>.threadReplies` pour un message privé.
|
||||
Le contexte du modèle expose `MessageThreadId` et `IsForum`. Les conversations DM avec `message_thread_id` conservent par défaut le routage DM et les métadonnées de réponse sur des sessions plates ; elles n’utilisent des clés de session tenant compte des fils que lorsqu’elles sont configurées avec `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou une configuration de sujet correspondante. Utilisez `channels.telegram.dm.threadReplies` au niveau supérieur pour la valeur par défaut du compte, ou `direct.<chatId>.threadReplies` pour un DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Audio, vidéo et stickers">
|
||||
<Accordion title="Audio, vidéo et autocollants">
|
||||
### Messages audio
|
||||
|
||||
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
|
||||
- les transcriptions de notes vocales entrantes sont présentées comme du texte généré par machine,
|
||||
non fiable dans le contexte de l’agent ; la détection des mentions utilise toujours la
|
||||
transcription brute afin que les messages vocaux soumis à mention continuent de fonctionner.
|
||||
- les transcriptions de notes vocales entrantes sont encadrées comme du texte généré par machine,
|
||||
non fiable, dans le contexte de l’agent ; la détection des mentions utilise toujours la transcription
|
||||
brute, de sorte que les messages vocaux soumis à mention continuent de fonctionner.
|
||||
|
||||
Exemple d’action de message :
|
||||
|
||||
@ -599,15 +636,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Les notes vidéo ne prennent pas en charge les légendes ; le texte de message fourni est envoyé séparément.
|
||||
|
||||
### Stickers
|
||||
### Autocollants
|
||||
|
||||
Gestion des stickers entrants :
|
||||
Gestion des autocollants entrants :
|
||||
|
||||
- WEBP statique : téléchargé et traité (placeholder `<media:sticker>`)
|
||||
- TGS animé : ignoré
|
||||
- WEBM vidéo : ignoré
|
||||
|
||||
Champs de contexte des stickers :
|
||||
Champs de contexte des autocollants :
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -615,13 +652,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `Sticker.fileUniqueId`
|
||||
- `Sticker.cachedDescription`
|
||||
|
||||
Fichier de cache des stickers :
|
||||
Fichier de cache des autocollants :
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Les stickers sont décrits une fois (quand c’est possible) et mis en cache pour réduire les appels de vision répétés.
|
||||
Les autocollants sont décrits une fois (si possible) et mis en cache afin de réduire les appels de vision répétés.
|
||||
|
||||
Activer les actions de sticker :
|
||||
Activer les actions d’autocollants :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -635,7 +672,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Action d’envoi de sticker :
|
||||
Envoyer une action d’autocollant :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -646,7 +683,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Rechercher dans les stickers en cache :
|
||||
Rechercher des autocollants en cache :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -659,31 +696,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Notifications de réaction">
|
||||
Les réactions Telegram arrivent comme mises à jour `message_reaction` (séparées des payloads de message).
|
||||
<Accordion title="Notifications de réactions">
|
||||
Les réactions Telegram arrivent sous forme de mises à jour `message_reaction` (distinctes des charges utiles de messages).
|
||||
|
||||
Quand elles sont activées, OpenClaw met en file d’attente des événements système comme :
|
||||
Lorsque cette option est activée, OpenClaw met en file d’attente des événements système comme :
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
Config :
|
||||
Configuration :
|
||||
|
||||
- `channels.telegram.reactionNotifications` : `off | own | all` (par défaut : `own`)
|
||||
- `channels.telegram.reactionLevel` : `off | ack | minimal | extensive` (par défaut : `minimal`)
|
||||
|
||||
Notes :
|
||||
|
||||
- `own` signifie uniquement les réactions des utilisateurs aux 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 rejetés.
|
||||
- Telegram ne fournit pas d’identifiants de thread 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`), pas vers le sujet d’origine exact
|
||||
- `own` signifie uniquement les réactions d’utilisateurs aux 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éactions.
|
||||
- les groupes non forum sont routés vers la session de conversation du 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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Réactions ack">
|
||||
<Accordion title="Réactions Ack">
|
||||
`ackReaction` envoie un emoji d’accusé de réception pendant qu’OpenClaw traite un message entrant.
|
||||
|
||||
Ordre de résolution :
|
||||
@ -691,17 +728,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- repli vers l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
|
||||
- solution de repli sur l’emoji d’identité de l’agent (`agents.list[].identity.emoji`, sinon "👀")
|
||||
|
||||
Notes :
|
||||
|
||||
- Telegram attend des emoji unicode (par exemple "👀").
|
||||
- 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 config depuis les événements et commandes Telegram">
|
||||
Les écritures de config du canal sont activées par défaut (`configWrites !== false`).
|
||||
<Accordion title="Écritures de configuration depuis les événements et commandes Telegram">
|
||||
Les écritures de configuration de canal sont activées par défaut (`configWrites !== false`).
|
||||
|
||||
Les écritures déclenchées par Telegram incluent :
|
||||
|
||||
@ -722,32 +759,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling ou Webhook">
|
||||
La valeur par défaut est le long polling. Pour le mode Webhook, définissez `channels.telegram.webhookUrl` et `channels.telegram.webhookSecret` ; `webhookPath`, `webhookHost`, `webhookPort` sont facultatifs (valeurs par défaut `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling vs webhook">
|
||||
Le mode par défaut est le long polling. Pour le mode Webhook, définissez `channels.telegram.webhookUrl` et `channels.telegram.webhookSecret` ; `webhookPath`, `webhookHost`, `webhookPort` sont facultatifs (valeurs par défaut `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Le listener local se lie à `127.0.0.1:8787`. Pour une entrée publique, placez soit un proxy inverse devant le port local, soit définissez intentionnellement `webhookHost: "0.0.0.0"`.
|
||||
L’écouteur local se lie à `127.0.0.1:8787`. Pour une entrée publique, placez un proxy inverse devant le port local ou définissez intentionnellement `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Le mode Webhook valide les protections de requête, le token secret Telegram et le corps JSON avant de renvoyer `200` à Telegram.
|
||||
OpenClaw traite ensuite la mise à jour de manière asynchrone via les mêmes lanes de bot par chat/par sujet que celles utilisées par le long polling, donc les tours d’agent lents ne bloquent pas l’ACK de livraison de Telegram.
|
||||
Le mode Webhook valide les protections de requête, le jeton secret Telegram et le corps JSON avant de renvoyer `200` à Telegram.
|
||||
OpenClaw traite ensuite la mise à jour de manière asynchrone au moyen des mêmes files de bot par conversation/par sujet que celles utilisées par le long polling, afin que les tours d’agent lents ne bloquent pas l’ACK de livraison de Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limites, nouvelle tentative et cibles CLI">
|
||||
<Accordion title="Limites, nouvelles tentatives et cibles CLI">
|
||||
- `channels.telegram.textChunkLimit` vaut 4000 par défaut.
|
||||
- `channels.telegram.chunkMode="newline"` préfère 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.mediaGroupFlushMs` (500 par défaut) contrôle combien de temps les albums/groupes de médias Telegram sont mis en tampon avant qu’OpenClaw ne les distribue comme un seul message entrant. Augmentez cette valeur si des parties d’album arrivent tard ; diminuez-la pour réduire la latence de réponse aux albums.
|
||||
- `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). Les clients de bot plafonnent les valeurs configurées sous la protection de requête de texte/typing sortante de 60 secondes, afin que grammY n’abandonne pas la livraison de réponse visible avant que la protection de transport d’OpenClaw et le repli puissent s’exécuter. Le long polling utilise toujours une protection de requête `getUpdates` de 45 secondes afin que les polls inactifs ne soient pas abandonnés indéfiniment.
|
||||
- `channels.telegram.pollingStallThresholdMs` vaut `120000` par défaut ; ajustez entre `30000` et `600000` uniquement pour les redémarrages dus à de faux positifs de blocage de polling.
|
||||
- `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) plafonne la taille des médias Telegram entrants et sortants.
|
||||
- `channels.telegram.mediaGroupFlushMs` (500 par défaut) contrôle la durée pendant laquelle les albums/groupes de médias Telegram sont mis en mémoire tampon avant qu’OpenClaw ne les distribue comme un seul message entrant. Augmentez-la si des parties d’album arrivent en retard ; diminuez-la pour réduire la latence de réponse aux albums.
|
||||
- `channels.telegram.timeoutSeconds` remplace le délai d’expiration du client API Telegram (s’il n’est pas défini, la valeur par défaut de grammY s’applique). Les clients de bot plafonnent les valeurs configurées sous la protection de requête sortante texte/saisie de 60 secondes, afin que grammY n’annule pas la livraison visible de la réponse avant que la protection de transport et la solution de repli d’OpenClaw puissent s’exécuter. Le long polling utilise toujours une protection de requête `getUpdates` de 45 secondes afin que les polls inactifs ne soient pas abandonnés indéfiniment.
|
||||
- `channels.telegram.pollingStallThresholdMs` vaut `120000` par défaut ; ajustez entre `30000` et `600000` uniquement pour les redémarrages de polling bloqué faussement positifs.
|
||||
- l’historique de contexte de groupe utilise `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (50 par défaut) ; `0` le désactive.
|
||||
- le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel qu’il est reçu.
|
||||
- les listes d’autorisation Telegram contrôlent principalement qui peut déclencher l’agent, pas une frontière complète de caviardage du contexte supplémentaire.
|
||||
- Contrôles d’historique des DM :
|
||||
- le contexte supplémentaire de réponse/citation/transfert est actuellement transmis tel que reçu.
|
||||
- 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 config `channels.telegram.retry` s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de réponse finale entrante utilise aussi une nouvelle tentative d’envoi sûr bornée pour les échecs Telegram avant connexion, mais elle ne réessaie pas les enveloppes réseau ambiguës après envoi qui pourraient dupliquer des messages visibles.
|
||||
- La configuration `channels.telegram.retry` s’applique aux helpers d’envoi Telegram (CLI/outils/actions) pour les erreurs d’API sortantes récupérables. La livraison de réponse finale entrante utilise également une nouvelle tentative d’envoi sûre et bornée pour les échecs Telegram avant connexion, mais elle ne réessaie pas les enveloppes réseau ambiguës après envoi qui pourraient dupliquer les messages visibles.
|
||||
|
||||
La cible d’envoi CLI peut être un identifiant numérique de chat ou un nom d’utilisateur :
|
||||
La cible d’envoi CLI peut être un ID de conversation numérique ou un nom d’utilisateur :
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -764,7 +801,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Flags de poll propres à Telegram :
|
||||
Indicateurs de poll propres à Telegram :
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
@ -774,8 +811,8 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
L’envoi Telegram prend aussi en charge :
|
||||
|
||||
- `--presentation` avec des blocs `buttons` pour les claviers inline lorsque `channels.telegram.capabilities.inlineButtons` l’autorise
|
||||
- `--pin` ou `--delivery '{"pin":true}'` pour demander une livraison épinglée lorsque le bot peut épingler dans ce chat
|
||||
- `--force-document` pour envoyer des images et GIF sortants comme documents plutôt que comme téléversements de photo compressée ou de média animé
|
||||
- `--pin` ou `--delivery '{"pin":true}'` pour demander une livraison épinglée lorsque le bot peut épingler dans cette conversation
|
||||
- `--force-document` pour envoyer les images et GIF sortants comme documents au lieu de téléversements photo compressés ou média animé
|
||||
|
||||
Contrôle des actions :
|
||||
|
||||
@ -785,20 +822,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Approbations exec dans Telegram">
|
||||
Telegram prend en charge les approbations exec dans les DM des approbateurs et peut éventuellement publier les invites dans le chat ou le sujet d’origine. Les approbateurs doivent être des identifiants numériques d’utilisateurs Telegram.
|
||||
Telegram prend en charge les approbations exec dans les DM des approbateurs et peut facultativement publier les invites dans la conversation ou le sujet d’origine. Les approbateurs doivent être des ID d’utilisateurs Telegram numériques.
|
||||
|
||||
Chemin de config :
|
||||
Chemin de configuration :
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (s’active automatiquement quand au moins un approbateur peut être résolu)
|
||||
- `channels.telegram.execApprovals.approvers` (se replie sur les identifiants numériques de propriétaire depuis `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.enabled` (s’active automatiquement lorsqu’au moins un approbateur peut être résolu)
|
||||
- `channels.telegram.execApprovals.approvers` (se replie sur les ID de propriétaires numériques depuis `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target` : `dm` (par défaut) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` et `defaultTo` contrôlent qui peut parler au bot et où il envoie les réponses normales. Ils ne font de personne un approbateur exec. Le premier appairage DM approuvé initialise `commands.ownerAllowFrom` lorsqu’aucun propriétaire de commande n’existe encore, donc la configuration à propriétaire unique fonctionne toujours sans dupliquer les identifiants sous `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` et `defaultTo` contrôlent qui peut parler au bot et où celui-ci envoie les réponses normales. Ils ne transforment pas quelqu’un en approbateur exec. Le premier appairage DM approuvé amorce `commands.ownerAllowFrom` lorsqu’aucun propriétaire de commande n’existe encore, de sorte que la configuration à un seul propriétaire fonctionne toujours sans dupliquer les ID sous `execApprovals.approvers`.
|
||||
|
||||
La livraison au canal affiche le texte de commande dans le chat ; n’activez `channel` ou `both` que dans les groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw conserve le sujet pour l’invite d’approbation et le suivi. Les approbations exec expirent après 30 minutes par défaut.
|
||||
La livraison dans le canal affiche le texte de la commande dans la conversation ; n’activez `channel` ou `both` que dans des groupes/sujets de confiance. Lorsque l’invite arrive dans un sujet de forum, OpenClaw conserve le sujet pour l’invite d’approbation et le suivi. Les approbations exec expirent par défaut après 30 minutes.
|
||||
|
||||
Les boutons d’approbation inline exigent aussi que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`). Les identifiants d’approbation préfixés par `plugin:` sont résolus via les approbations de Plugin ; les autres sont d’abord résolus via les approbations exec.
|
||||
Les boutons d’approbation inline nécessitent également que `channels.telegram.capabilities.inlineButtons` autorise la surface cible (`dm`, `group` ou `all`). Les ID d’approbation préfixés par `plugin:` sont résolus via les approbations Plugin ; les autres sont d’abord résolus via les approbations exec.
|
||||
|
||||
Voir [Approbations exec](/fr/tools/exec-approvals).
|
||||
|
||||
@ -807,14 +844,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
## Contrôles des réponses d’erreur
|
||||
|
||||
Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut soit répondre avec le texte de l’erreur, soit la supprimer. Deux clés de config contrôlent ce comportement :
|
||||
Lorsque l’agent rencontre une erreur de livraison ou de fournisseur, Telegram peut répondre avec le texte d’erreur ou 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 au chat. `silent` supprime entièrement les réponses d’erreur. |
|
||||
| `channels.telegram.errorCooldownMs` | nombre (ms) | `60000` | Temps minimal entre les réponses d’erreur au même chat. Empêche le spam d’erreurs pendant les interruptions de service. |
|
||||
| Clé | Valeurs | Par défaut | Description |
|
||||
| ----------------------------------- | ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envoie un message d’erreur convivial à la conversation. `silent` supprime entièrement les réponses d’erreur. |
|
||||
| `channels.telegram.errorCooldownMs` | nombre (ms) | `60000` | Temps minimal entre les réponses d’erreur à la même conversation. 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 les autres clés de config Telegram).
|
||||
Les remplacements par compte, par groupe et par sujet sont pris en charge (même héritage que les autres clés de configuration Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -837,11 +874,11 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
|
||||
<AccordionGroup>
|
||||
<Accordion title="Le bot ne répond pas aux messages de groupe sans mention">
|
||||
|
||||
- Si `requireMention=false`, le mode de confidentialité Telegram doit permettre une visibilité complète.
|
||||
- Si `requireMention=false`, le mode confidentialité Telegram doit autoriser la visibilité complète.
|
||||
- BotFather : `/setprivacy` -> Disable
|
||||
- puis retirez et rajoutez le bot au groupe
|
||||
- `openclaw channels status` avertit lorsque la config attend des messages de groupe sans mention.
|
||||
- `openclaw channels status --probe` peut vérifier des identifiants numériques de groupe explicites ; le caractère générique `"*"` ne peut pas être vérifié par appartenance.
|
||||
- puis supprimez et 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 faire l’objet d’une vérification d’appartenance.
|
||||
- test rapide de session : `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
@ -850,41 +887,41 @@ Les remplacements par compte, par groupe et par sujet sont pris en charge (même
|
||||
|
||||
- lorsque `channels.telegram.groups` existe, le groupe doit être listé (ou inclure `"*"`)
|
||||
- vérifiez l’appartenance du bot au groupe
|
||||
- consultez les journaux : `openclaw logs --follow` pour les raisons d’ignorance
|
||||
- consultez les journaux : `openclaw logs --follow` pour connaître les raisons des ignorés
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Les commandes fonctionnent partiellement ou pas du tout">
|
||||
|
||||
- autorisez votre identité d’expéditeur (appairage et/ou `allowFrom` numérique)
|
||||
- l’autorisation de commande s’applique toujours même lorsque la stratégie de groupe est `open`
|
||||
- `setMyCommands failed` avec `BOT_COMMANDS_TOO_MUCH` signifie que le menu natif contient trop d’entrées ; réduisez les commandes de Plugin/skill/personnalisées ou désactivez les menus natifs
|
||||
- les appels de démarrage `deleteMyCommands` / `setMyCommands` et les appels de typing `sendChatAction` sont bornés et réessayés une fois via le repli de transport de Telegram en cas d’expiration de requête. Les erreurs réseau/fetch persistantes indiquent généralement des problèmes d’accessibilité DNS/HTTPS vers `api.telegram.org`
|
||||
- autorisez votre identité d’expéditeur (association 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 contient trop d’entrées ; réduisez les commandes de Plugin/Skills/personnalisées ou désactivez les menus natifs
|
||||
- les appels de démarrage `deleteMyCommands` / `setMyCommands` et les appels de saisie `sendChatAction` sont bornés et réessayés une fois via le transport de secours de Telegram en cas de délai d’expiration de la requête. Les erreurs réseau/fetch persistantes indiquent généralement des problèmes d’accessibilité DNS/HTTPS vers `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Le démarrage signale un token non autorisé">
|
||||
<Accordion title="Le démarrage signale un jeton non autorisé">
|
||||
|
||||
- `getMe returned 401` est un échec d’authentification Telegram pour le jeton du bot configuré.
|
||||
- `getMe returned 401` est un échec d’authentification Telegram pour le jeton de bot configuré.
|
||||
- Recopiez ou régénérez le jeton du bot dans BotFather, puis mettez à jour `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` ou `TELEGRAM_BOT_TOKEN` pour le compte par défaut.
|
||||
- `deleteWebhook 401 Unauthorized` au démarrage est aussi un échec d’authentification ; le traiter comme « aucun webhook n’existe » ne ferait que reporter le même échec dû au jeton invalide aux appels d’API ultérieurs.
|
||||
- `deleteWebhook 401 Unauthorized` pendant le démarrage est aussi un échec d’authentification ; le traiter comme « aucun webhook n’existe » ne ferait que reporter le même échec dû à un mauvais jeton aux appels API ultérieurs.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polling or network instability">
|
||||
<Accordion title="Instabilité du polling ou du réseau">
|
||||
|
||||
- Node 22+ avec un fetch/proxy personnalisé peut déclencher un comportement d’abandon immédiat si les types AbortSignal ne correspondent pas.
|
||||
- Certains hôtes résolvent d’abord `api.telegram.org` en IPv6 ; une sortie IPv6 défectueuse peut provoquer des échecs intermittents de l’API Telegram.
|
||||
- Si les journaux incluent `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, OpenClaw les réessaie maintenant comme des erreurs réseau récupérables.
|
||||
- Pendant le démarrage du polling, OpenClaw réutilise la sonde de démarrage `getMe` réussie pour grammY afin que le runner n’ait pas besoin d’un deuxième `getMe` avant le premier `getUpdates`.
|
||||
- Si `deleteWebhook` échoue avec une erreur réseau transitoire pendant le démarrage du polling, OpenClaw passe au long polling au lieu d’effectuer un autre appel de plan de contrôle avant le polling. Un webhook encore actif apparaît comme un conflit `getUpdates` ; OpenClaw reconstruit alors le transport Telegram et réessaie le nettoyage du webhook.
|
||||
- Si les sockets Telegram sont recyclés selon une cadence fixe courte, vérifiez si `channels.telegram.timeoutSeconds` est bas ; les clients de bot bornent les valeurs configurées en dessous des garde-fous des requêtes sortantes et `getUpdates`, mais les anciennes versions pouvaient abandonner chaque polling ou réponse lorsque cette valeur était définie sous ces garde-fous.
|
||||
- Si les journaux incluent `Polling stall detected`, OpenClaw redémarre le polling et reconstruit le transport Telegram après 120 secondes sans liveness de long polling terminée par défaut.
|
||||
- `openclaw channels status --probe` et `openclaw doctor` avertissent lorsqu’un compte de polling en cours d’exécution n’a pas terminé `getUpdates` après la période de grâce au démarrage, lorsqu’un compte webhook en cours d’exécution n’a pas terminé `setWebhook` après la période de grâce au démarrage, ou lorsque la dernière activité réussie du transport de polling est obsolète.
|
||||
- Augmentez `channels.telegram.pollingStallThresholdMs` uniquement lorsque les appels `getUpdates` longs sont sains, mais que votre hôte signale encore à tort des redémarrages pour blocage de polling. Des blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou sortie TLS entre l’hôte et `api.telegram.org`.
|
||||
- Telegram respecte aussi les variables d’environnement de proxy du processus pour le transport de l’API Bot, notamment `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` et leurs variantes en minuscules. `NO_PROXY` / `no_proxy` peuvent toujours contourner `api.telegram.org`.
|
||||
- Si le proxy géré par OpenClaw est configuré via `OPENCLAW_PROXY_URL` pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise aussi cette URL pour le transport de l’API Bot.
|
||||
- Sur les hôtes VPS dont la sortie directe/TLS est instable, routez les appels à l’API Telegram via `channels.telegram.proxy` :
|
||||
- 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 d’abord `api.telegram.org` en IPv6 ; une sortie IPv6 défaillante peut provoquer des échecs intermittents de l’API Telegram.
|
||||
- Si les journaux incluent `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, OpenClaw réessaie désormais ces erreurs comme des erreurs réseau récupérables.
|
||||
- Pendant le démarrage du polling, OpenClaw réutilise la sonde `getMe` réussie du démarrage pour grammY, afin que le runner n’ait pas besoin d’un second `getMe` avant le premier `getUpdates`.
|
||||
- Si `deleteWebhook` échoue avec une erreur réseau transitoire pendant le démarrage du polling, OpenClaw continue en long polling au lieu d’effectuer un autre appel de plan de contrôle avant le polling. Un webhook encore actif apparaît comme un conflit `getUpdates` ; OpenClaw reconstruit alors le transport Telegram et réessaie le nettoyage du webhook.
|
||||
- Si les sockets Telegram sont recyclés selon une cadence fixe courte, vérifiez si `channels.telegram.timeoutSeconds` est faible ; les clients de bot bornent les valeurs configurées sous les garde-fous des requêtes sortantes et `getUpdates`, mais les anciennes versions pouvaient interrompre chaque polling ou réponse lorsque cette valeur était définie sous ces garde-fous.
|
||||
- Si les journaux incluent `Polling stall detected`, OpenClaw redémarre le polling et reconstruit le transport Telegram après 120 secondes sans signal de vivacité de long polling terminé par défaut.
|
||||
- `openclaw channels status --probe` et `openclaw doctor` avertissent lorsqu’un compte de polling en cours d’exécution n’a pas terminé `getUpdates` après la période de grâce du démarrage, lorsqu’un compte webhook en cours d’exécution n’a pas terminé `setWebhook` après la période de grâce du démarrage, ou lorsque la dernière activité réussie du transport de polling est obsolète.
|
||||
- N’augmentez `channels.telegram.pollingStallThresholdMs` que lorsque les appels `getUpdates` longue durée sont sains mais que votre hôte signale toujours à tort des redémarrages pour blocage du polling. Des blocages persistants indiquent généralement des problèmes de proxy, DNS, IPv6 ou de sortie TLS entre l’hôte et `api.telegram.org`.
|
||||
- Telegram respecte aussi les variables d’environnement de proxy du processus pour le transport Bot API, notamment `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` et leurs variantes en minuscules. `NO_PROXY` / `no_proxy` peuvent toujours contourner `api.telegram.org`.
|
||||
- Si le proxy géré par OpenClaw est configuré via `OPENCLAW_PROXY_URL` pour un environnement de service et qu’aucune variable d’environnement de proxy standard n’est présente, Telegram utilise aussi cette URL pour le transport Bot API.
|
||||
- Sur les hôtes VPS avec une sortie directe/TLS instable, routez les appels à l’API Telegram via `channels.telegram.proxy` :
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -892,7 +929,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ utilise par défaut `autoSelectFamily=true` (sauf WSL2). L’ordre des résultats DNS Telegram respecte `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, puis `channels.telegram.network.dnsResultOrder`, puis la valeur par défaut du processus comme `NODE_OPTIONS=--dns-result-order=ipv4first` ; si aucune ne s’applique, Node 22+ revient à `ipv4first`.
|
||||
- Node 22+ utilise par défaut `autoSelectFamily=true` (sauf WSL2). L’ordre des résultats DNS de Telegram respecte `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, puis `channels.telegram.network.dnsResultOrder`, puis la valeur par défaut du processus comme `NODE_OPTIONS=--dns-result-order=ipv4first` ; si rien ne s’applique, Node 22+ revient à `ipv4first`.
|
||||
- Si votre hôte est WSL2 ou fonctionne explicitement mieux avec un comportement IPv4 uniquement, forcez la sélection de famille :
|
||||
|
||||
```yaml
|
||||
@ -902,11 +939,11 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Les réponses de plage de benchmark RFC 2544 (`198.18.0.0/15`) sont déjà autorisées
|
||||
- Les réponses dans la plage de référence 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 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 limité à Telegram :
|
||||
activer le contournement réservé à Telegram :
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -917,19 +954,19 @@ channels:
|
||||
|
||||
- La même activation est disponible par compte à
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Si votre proxy résout les hôtes de médias Telegram vers `198.18.x.x`, laissez d’abord
|
||||
l’indicateur 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 de médias Telegram en `198.18.x.x`, laissez d’abord
|
||||
l’indicateur dangereux désactivé. Les médias Telegram autorisent déjà la plage de référence
|
||||
RFC 2544 par défaut.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les protections SSRF
|
||||
des médias Telegram. Utilisez-le uniquement pour des environnements de proxy de confiance
|
||||
contrôlés par l’opérateur, comme 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
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` affaiblit les
|
||||
protections SSRF des médias Telegram. Utilisez-le uniquement pour des environnements de proxy
|
||||
de confiance contrôlés par l’opérateur, tels que le routage de faux IP Clash, Mihomo ou Surge,
|
||||
lorsqu’ils synthétisent des réponses privées ou à usage spécial hors de la plage de référence
|
||||
RFC 2544. Laissez-le désactivé pour un accès Telegram normal à l’internet public.
|
||||
</Warning>
|
||||
|
||||
- Remplacements par l’environnement (temporaires) :
|
||||
- Remplacements d’environnement (temporaires) :
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
@ -949,17 +986,17 @@ Aide supplémentaire : [Dépannage des canaux](/fr/channels/troubleshooting).
|
||||
|
||||
Référence principale : [Référence de configuration - Telegram](/fr/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="High-signal Telegram fields">
|
||||
<Accordion title="Champs Telegram à fort signal">
|
||||
|
||||
- démarrage/authentification : `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` doit pointer vers un fichier standard ; les liens symboliques sont rejetés)
|
||||
- démarrage/authentification : `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 premier niveau (`type: "acp"`)
|
||||
- approbations d’exécution : `execApprovals`, `accounts.*.execApprovals`
|
||||
- approbations exec : `execApprovals`, `accounts.*.execApprovals`
|
||||
- commande/menu : `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- fils/réponses : `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming : `streaming` (aperçu), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- mise en forme/livraison : `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- médias/réseau : `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- racine d’API personnalisée : `apiRoot` (racine de l’API Bot uniquement ; n’incluez pas `/bot<TOKEN>`)
|
||||
- racine d’API personnalisée : `apiRoot` (racine Bot API uniquement ; n’incluez pas `/bot<TOKEN>`)
|
||||
- webhook : `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- actions/capacités : `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- réactions : `reactionNotifications`, `reactionLevel`
|
||||
@ -969,28 +1006,28 @@ Référence principale : [Référence de configuration - Telegram](/fr/gateway/c
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Priorité multi-compte : lorsque deux identifiants 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. Sinon, OpenClaw revient au premier identifiant de compte normalisé et `openclaw doctor` émet un avertissement. Les comptes nommés héritent de `channels.telegram.allowFrom` / `groupAllowFrom`, mais pas des valeurs `accounts.default.*`.
|
||||
Priorité multi-compte : lorsque deux ID de compte ou plus sont configurés, définissez `channels.telegram.defaultAccount` (ou incluez `channels.telegram.accounts.default`) afin de rendre le routage par défaut explicite. Sinon, OpenClaw revient au premier ID de compte normalisé et `openclaw doctor` émet un avertissement. Les comptes nommés héritent de `channels.telegram.allowFrom` / `groupAllowFrom`, mais pas des valeurs `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Connexe
|
||||
## Associés
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/fr/channels/pairing">
|
||||
Associer un utilisateur Telegram au gateway.
|
||||
<Card title="Association" icon="link" href="/fr/channels/pairing">
|
||||
Associez un utilisateur Telegram à la passerelle.
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/fr/channels/groups">
|
||||
<Card title="Groupes" icon="users" href="/fr/channels/groups">
|
||||
Comportement de liste d’autorisation des groupes et des sujets.
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/fr/channels/channel-routing">
|
||||
Router les messages entrants vers les agents.
|
||||
<Card title="Routage de canal" icon="route" href="/fr/channels/channel-routing">
|
||||
Routez les messages entrants vers les agents.
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/fr/gateway/security">
|
||||
<Card title="Sécurité" icon="shield" href="/fr/gateway/security">
|
||||
Modèle de menace et durcissement.
|
||||
</Card>
|
||||
<Card title="Multi-agent routing" icon="sitemap" href="/fr/concepts/multi-agent">
|
||||
Associer les groupes et les sujets aux agents.
|
||||
<Card title="Routage multi-agent" icon="sitemap" href="/fr/concepts/multi-agent">
|
||||
Mappez les groupes et les sujets aux agents.
|
||||
</Card>
|
||||
<Card title="Troubleshooting" icon="wrench" href="/fr/channels/troubleshooting">
|
||||
Diagnostics intercanaux.
|
||||
<Card title="Dépannage" icon="wrench" href="/fr/channels/troubleshooting">
|
||||
Diagnostics inter-canaux.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
482
docs/fr/ci.md
482
docs/fr/ci.md
@ -3,92 +3,92 @@ read_when:
|
||||
- Vous devez comprendre pourquoi une tâche CI s’est exécutée ou non
|
||||
- Vous déboguez une vérification GitHub Actions en échec
|
||||
- Vous coordonnez une exécution ou une réexécution de validation de version
|
||||
- Vous modifiez le déclenchement de ClawSweeper ou le transfert d’activité GitHub
|
||||
summary: Graphe des jobs CI, gates de périmètre, regroupements de publication et équivalents des commandes locales
|
||||
- Vous modifiez la répartition ClawSweeper ou la transmission de l’activité GitHub
|
||||
summary: Graphe des jobs CI, garde-fous de périmètre, regroupements de publication et équivalents des commandes locales
|
||||
title: Pipeline CI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:40Z"
|
||||
generated_at: "2026-05-04T07:03:15Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e07fc44aa844cb66ce529c570cbbbbf502a61bcbcbc3d9488557abb459ef7678
|
||||
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
|
||||
source_path: ci.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw CI s’exécute à chaque push vers `main` et à chaque pull request. Le job `preflight` classe le diff et désactive les lanes coûteuses lorsque seules des zones sans rapport ont changé. Les exécutions manuelles `workflow_dispatch` contournent volontairement le ciblage intelligent et déploient tout le graphe pour les release candidates et les validations larges. Les lanes Android restent opt-in via `include_android`. La couverture Plugin réservée aux releases se trouve dans le workflow séparé [`Plugin Prerelease`](#plugin-prerelease) et ne s’exécute qu’à partir de [`Full Release Validation`](#full-release-validation) ou d’un dispatch manuel explicite.
|
||||
OpenClaw CI s’exécute à chaque push vers `main` et pour chaque pull request. Le job `preflight` classe le diff et désactive les lanes coûteuses quand seules des zones sans rapport ont changé. Les exécutions manuelles `workflow_dispatch` contournent volontairement le périmétrage intelligent et déploient tout le graphe pour les release candidates et les validations larges. Les lanes Android restent optionnelles via `include_android`. La couverture Plugin réservée aux releases vit dans le workflow séparé [`Plugin Prerelease`](#plugin-prerelease) et ne s’exécute que depuis [`Full Release Validation`](#full-release-validation) ou une dispatch manuelle explicite.
|
||||
|
||||
## Vue d’ensemble du pipeline
|
||||
|
||||
| Job | Objectif | Quand il s’exécute |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| `preflight` | Détecter les changements limités aux docs, les portées modifiées, les extensions modifiées, et construire le manifeste CI | Toujours sur les pushs et PRs non draft |
|
||||
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushs et PRs non draft |
|
||||
| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux advisories npm | Toujours sur les pushs et PRs non draft |
|
||||
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs et PRs non draft |
|
||||
| `check-dependencies` | Passe Knip de production limitée aux dépendances plus garde de l’allowlist des fichiers inutilisés | Changements concernant Node |
|
||||
| `build-artifacts` | Construire `dist/`, Control UI, les vérifications d’artifacts construits, et les artifacts réutilisables en aval | Changements concernant Node |
|
||||
| `checks-fast-core` | Lanes de correction Linux rapides comme les vérifications bundled/plugin-contract/protocol | Changements concernant Node |
|
||||
| `checks-fast-contracts-channels` | Vérifications shardées des contrats de canaux avec un résultat de vérification agrégé stable | Changements concernant Node |
|
||||
| `checks-node-core-test` | Shards de tests Node cœur, hors lanes canaux, bundled, contrats et extensions | Changements concernant Node |
|
||||
| `check` | Équivalent shardé de la gate locale principale : types prod, lint, gardes, types de test, et smoke strict | Changements concernant Node |
|
||||
| `check-additional` | Architecture, dérive shardée boundary/prompt, gardes d’extensions, frontière de package et surveillance Gateway | Changements concernant Node |
|
||||
| `build-smoke` | Tests smoke de la CLI construite et smoke de mémoire au démarrage | Changements concernant Node |
|
||||
| `checks` | Vérificateur pour les tests de canaux sur artifacts construits | Changements concernant Node |
|
||||
| `checks-node-compat-node22` | Lane de build et smoke de compatibilité Node 22 | Dispatch CI manuel pour les releases |
|
||||
| `check-docs` | Formatage, lint et vérifications de liens cassés des docs | Docs modifiées |
|
||||
| `skills-python` | Ruff + pytest pour les Skills adossés à Python | Changements concernant les Skills Python |
|
||||
| `checks-windows` | Tests spécifiques Windows de processus/chemins plus régressions partagées de spécificateurs d’import runtime | Changements concernant Windows |
|
||||
| `macos-node` | Lane de tests TypeScript macOS utilisant les artifacts construits partagés | Changements concernant macOS |
|
||||
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements concernant macOS |
|
||||
| `android` | Tests unitaires Android pour les deux flavors plus un build d’APK debug | Changements concernant Android |
|
||||
| `test-performance-agent` | Optimisation quotidienne des tests lents Codex après activité fiable | Succès de la CI principale ou dispatch manuel |
|
||||
| `openclaw-performance` | Rapports de performance runtime Kova quotidiens/à la demande avec lanes mock-provider, deep-profile et GPT 5.4 live | Planifié et dispatch manuel |
|
||||
| Job | Objectif | Quand il s’exécute |
|
||||
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
|
||||
| `preflight` | Détecter les changements docs-only, les portées modifiées, les extensions modifiées et générer le manifeste CI | Toujours sur les pushs et PRs non draft |
|
||||
| `security-scm-fast` | Détection de clés privées et audit des workflows via `zizmor` | Toujours sur les pushs et PRs non draft |
|
||||
| `security-dependency-audit` | Audit du lockfile de production sans dépendances par rapport aux avis npm | Toujours sur les pushs et PRs non draft |
|
||||
| `security-fast` | Agrégat requis pour les jobs de sécurité rapides | Toujours sur les pushs et PRs non draft |
|
||||
| `check-dependencies` | Passe Knip de production limitée aux dépendances, plus garde de l’allowlist des fichiers inutilisés | Changements pertinents pour Node |
|
||||
| `build-artifacts` | Générer `dist/`, Control UI, les vérifications d’artefacts générés et les artefacts aval réutilisables | Changements pertinents pour Node |
|
||||
| `checks-fast-core` | Lanes Linux rapides de correction, comme les vérifications bundled/plugin-contract/protocol | Changements pertinents pour Node |
|
||||
| `checks-fast-contracts-channels` | Vérifications de contrats de channels shardées avec un résultat de vérification agrégé stable | Changements pertinents pour Node |
|
||||
| `checks-node-core-test` | Shards de tests Node du cœur, hors lanes de channel, bundled, contract et extension | Changements pertinents pour Node |
|
||||
| `check` | Équivalent shardé de la gate locale principale : types prod, lint, guards, types de test et smoke strict | Changements pertinents pour Node |
|
||||
| `check-additional` | Architecture, boundary/prompt drift shardés, guards d’extension, boundary de package et gateway watch | Changements pertinents pour Node |
|
||||
| `build-smoke` | Tests smoke de la CLI générée et smoke de mémoire au démarrage | Changements pertinents pour Node |
|
||||
| `checks` | Vérificateur pour les tests de channel sur artefacts générés | Changements pertinents pour Node |
|
||||
| `checks-node-compat-node22` | Lane de build et smoke de compatibilité Node 22 | Dispatch CI manuelle pour les releases |
|
||||
| `check-docs` | Formatage, lint et vérifications de liens cassés de la documentation | Docs modifiées |
|
||||
| `skills-python` | Ruff + pytest pour les Skills adossés à Python | Changements pertinents pour les Skills Python |
|
||||
| `checks-windows` | Tests Windows spécifiques aux processus/chemins, plus régressions partagées de spécificateurs d’import runtime | Changements pertinents pour Windows |
|
||||
| `macos-node` | Lane de tests TypeScript macOS utilisant les artefacts générés partagés | Changements pertinents pour macOS |
|
||||
| `macos-swift` | Lint, build et tests Swift pour l’app macOS | Changements pertinents pour macOS |
|
||||
| `android` | Tests unitaires Android pour les deux flavors, plus un build d’APK debug | Changements pertinents pour Android |
|
||||
| `test-performance-agent` | Optimisation quotidienne des tests lents par Codex après une activité fiable | Succès de la CI principale ou dispatch manuelle |
|
||||
| `openclaw-performance` | Rapports de performance runtime Kova quotidiens/à la demande avec lanes mock-provider, deep-profile et GPT 5.4 live | Planification et dispatch manuelle |
|
||||
|
||||
## Ordre fail-fast
|
||||
## Ordre de fail-fast
|
||||
|
||||
1. `preflight` décide quelles lanes existent réellement. Les logiques `docs-scope` et `changed-scope` sont des étapes de ce job, pas des jobs autonomes.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds d’artifacts et de matrices de plateformes.
|
||||
3. `build-artifacts` chevauche les lanes Linux rapides afin que les consommateurs en aval puissent démarrer dès que le build partagé est prêt.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` et `skills-python` échouent rapidement sans attendre les jobs plus lourds d’artefacts et de matrices de plateformes.
|
||||
3. `build-artifacts` chevauche les lanes Linux rapides afin que les consommateurs aval puissent démarrer dès que le build partagé est prêt.
|
||||
4. Les lanes plus lourdes de plateformes et de runtime se déploient ensuite : `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` et `android`.
|
||||
|
||||
GitHub peut marquer des jobs remplacés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou ref `main`. Traitez cela comme du bruit CI sauf si l’exécution la plus récente pour la même ref échoue aussi. Les vérifications agrégées de shards utilisent `!cancelled() && always()` afin de toujours signaler les échecs normaux de shards, sans toutefois se mettre en file après que tout le workflow a déjà été remplacé. La clé de concurrence CI automatique est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file ne puisse pas bloquer indéfiniment les exécutions plus récentes de main. Les exécutions manuelles de la suite complète utilisent `CI-manual-v1-*` et n’annulent pas les exécutions en cours.
|
||||
GitHub peut marquer des jobs supplantés comme `cancelled` lorsqu’un push plus récent arrive sur la même PR ou ref `main`. Traitez cela comme du bruit CI, sauf si la plus récente exécution pour la même ref échoue aussi. Les vérifications agrégées de shards utilisent `!cancelled() && always()` afin de toujours signaler les échecs normaux de shards sans se mettre en file après que tout le workflow a déjà été supplanté. La clé de concurrence CI automatique est versionnée (`CI-v7-*`) afin qu’un zombie côté GitHub dans un ancien groupe de file ne puisse pas bloquer indéfiniment les exécutions main plus récentes. Les exécutions manuelles de suite complète utilisent `CI-manual-v1-*` et n’annulent pas les exécutions en cours.
|
||||
|
||||
## Portée et routage
|
||||
|
||||
La logique de portée se trouve dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`. Le dispatch manuel ignore la détection `changed-scope` et fait agir le manifeste preflight comme si chaque zone portée avait changé.
|
||||
La logique de portée vit dans `scripts/ci-changed-scope.mjs` et est couverte par des tests unitaires dans `src/scripts/ci-changed-scope.test.ts`. La dispatch manuelle saute la détection `changed-scope` et fait agir le manifeste preflight comme si chaque zone délimitée avait changé.
|
||||
|
||||
- **Les modifications du workflow CI** valident le graphe CI Node plus le lint des workflows, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces lanes de plateformes restent limitées aux changements de sources de plateforme.
|
||||
- **Les modifications limitées au routage CI, certaines modifications peu coûteuses de fixtures de core-test, et les modifications étroites de helpers/tests de routage de contrats Plugin** utilisent un chemin de manifeste rapide Node uniquement : `preflight`, sécurité, et une seule tâche `checks-fast-core`. Ce chemin ignore les artifacts de build, la compatibilité Node 22, les contrats de canaux, les shards cœur complets, les shards de Plugins bundled et les matrices de gardes supplémentaires lorsque le changement est limité aux surfaces de routage ou de helpers exercées directement par la tâche rapide.
|
||||
- **Les vérifications Node Windows** sont limitées aux wrappers de processus/chemins spécifiques Windows, aux helpers de runners npm/pnpm/UI, à la config du gestionnaire de packages et aux surfaces du workflow CI qui exécutent cette lane ; les changements sans rapport dans les sources, Plugins, install-smoke et tests restent sur les lanes Node Linux.
|
||||
- **Les modifications de workflow CI** valident le graphe CI Node plus le linting de workflow, mais ne forcent pas à elles seules les builds natifs Windows, Android ou macOS ; ces lanes de plateforme restent limitées aux changements de sources de plateforme.
|
||||
- **Les modifications limitées au routage CI, certaines modifications peu coûteuses de fixtures de tests core et les modifications étroites d’helpers/tests de routage de contrats Plugin** utilisent un chemin rapide de manifeste Node-only : `preflight`, sécurité et une seule tâche `checks-fast-core`. Ce chemin saute les artefacts de build, la compatibilité Node 22, les contrats de channels, les shards core complets, les shards de bundled plugins et les matrices de guards additionnelles lorsque le changement est limité aux surfaces de routage ou d’helpers que la tâche rapide exerce directement.
|
||||
- **Les vérifications Node Windows** sont limitées aux wrappers processus/chemins spécifiques à Windows, aux helpers de runners npm/pnpm/UI, à la configuration du gestionnaire de packages et aux surfaces du workflow CI qui exécutent cette lane ; les changements de sources sans rapport, de plugins, d’install-smoke et de tests seuls restent sur les lanes Node Linux.
|
||||
|
||||
Les familles de tests Node les plus lentes sont scindées ou équilibrées afin que chaque job reste petit sans sur-réserver des runners : les contrats de canaux s’exécutent en trois shards pondérés, les lanes core unit fast/support s’exécutent séparément, l’infra runtime cœur est scindée entre shards état et processus/config, auto-reply s’exécute avec des workers équilibrés (avec le sous-arbre reply scindé en shards agent-runner, dispatch et commands/state-routing), et les configs agentiques gateway/server sont scindées sur des lanes chat/auth/model/http-plugin/runtime/startup au lieu d’attendre les artifacts construits. Les tests larges navigateur, QA, média et plugins divers utilisent leurs configs Vitest dédiées au lieu du catch-all Plugin partagé. Les shards à motifs d’inclusion enregistrent des entrées de timing avec le nom du shard CI, afin que `.artifacts/vitest-shard-timings.json` puisse distinguer une config entière d’un shard filtré. `check-additional` garde ensemble le travail de compilation/canary de frontière de package et sépare l’architecture de topologie runtime de la couverture de surveillance Gateway ; la liste de gardes de frontière est répartie sur quatre shards de matrice, chacun exécutant simultanément des gardes indépendantes sélectionnées et imprimant les timings par vérification, y compris `pnpm prompt:snapshots:check`, afin que la dérive de prompt du chemin heureux runtime Codex soit rattachée à la PR qui l’a causée. La surveillance Gateway, les tests de canaux et le shard de frontière de support cœur s’exécutent simultanément dans `build-artifacts` après que `dist/` et `dist-runtime/` ont déjà été construits.
|
||||
Les familles de tests Node les plus lentes sont divisées ou équilibrées afin que chaque job reste petit sans réserver trop de runners : les contrats de channels s’exécutent en trois shards pondérés, les lanes core unit fast/support s’exécutent séparément, l’infra runtime core est divisée entre shards state et process/config, auto-reply s’exécute comme des workers équilibrés (avec le sous-arbre reply divisé en shards agent-runner, dispatch et commands/state-routing), et les configs agentic gateway/server sont divisées entre lanes chat/auth/model/http-plugin/runtime/startup au lieu d’attendre les artefacts générés. Les tests larges browser, QA, media et de plugins divers utilisent leurs configs Vitest dédiées au lieu du catch-all partagé des plugins. Les shards include-pattern enregistrent les entrées de timing avec le nom de shard CI, afin que `.artifacts/vitest-shard-timings.json` puisse distinguer une config entière d’un shard filtré. `check-additional` garde ensemble le travail compile/canary de package-boundary et sépare l’architecture de topologie runtime de la couverture gateway watch ; la liste de guards boundary est répartie sur quatre shards de matrice, chacun exécutant des guards indépendants sélectionnés en parallèle et affichant les timings par vérification, y compris `pnpm prompt:snapshots:check` afin que la dérive de prompt du chemin nominal du runtime Codex soit rattachée à la PR qui l’a causée. Gateway watch, les tests de channels et le shard core support-boundary s’exécutent en parallèle dans `build-artifacts` après que `dist/` et `dist-runtime/` ont déjà été générés.
|
||||
|
||||
La CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis construit l’APK debug Play. Le flavor tiers n’a pas de source set ni de manifeste séparé ; sa lane de tests unitaires compile tout de même le flavor avec les flags BuildConfig SMS/call-log, tout en évitant un job de packaging d’APK debug en double à chaque push concernant Android.
|
||||
La CI Android exécute à la fois `testPlayDebugUnitTest` et `testThirdPartyDebugUnitTest`, puis génère l’APK debug Play. Le flavor third-party n’a pas de source set ni de manifeste séparé ; sa lane de tests unitaires compile quand même le flavor avec les flags BuildConfig SMS/call-log, tout en évitant un job de packaging d’APK debug dupliqué à chaque push pertinent pour Android.
|
||||
|
||||
Le shard `check-dependencies` exécute `pnpm deadcode:dependencies` (une passe Knip de production limitée aux dépendances, épinglée à la dernière version de Knip, avec l’âge minimal de release de pnpm désactivé pour l’installation `dlx`) et `pnpm deadcode:unused-files`, qui compare les résultats de fichiers de production inutilisés de Knip à `scripts/deadcode-unused-files.allowlist.mjs`. La garde des fichiers inutilisés échoue lorsqu’une PR ajoute un nouveau fichier inutilisé non revu ou laisse une entrée d’allowlist obsolète, tout en préservant les surfaces intentionnelles de Plugin dynamique, générées, build, live-test et pont de package que Knip ne peut pas résoudre statiquement.
|
||||
Le shard `check-dependencies` exécute `pnpm deadcode:dependencies` (une passe Knip de production limitée aux dépendances, épinglée à la dernière version de Knip, avec l’âge minimal de publication de pnpm désactivé pour l’installation `dlx`) et `pnpm deadcode:unused-files`, qui compare les résultats de fichiers de production inutilisés trouvés par Knip à `scripts/deadcode-unused-files.allowlist.mjs`. Le guard des fichiers inutilisés échoue lorsqu’une PR ajoute un nouveau fichier inutilisé non revu ou laisse une entrée d’allowlist obsolète, tout en préservant les surfaces intentionnelles de plugins dynamiques, générées, de build, de live-test et de pont de package que Knip ne peut pas résoudre statiquement.
|
||||
|
||||
## Transfert de l’activité ClawSweeper
|
||||
## Transfert d’activité ClawSweeper
|
||||
|
||||
`.github/workflows/clawsweeper-dispatch.yml` est le pont côté cible entre l’activité du dépôt OpenClaw et ClawSweeper. Il ne checkout ni n’exécute de code de pull request non fiable. Le workflow crée un token GitHub App à partir de `CLAWSWEEPER_APP_PRIVATE_KEY`, puis dispatch des payloads `repository_dispatch` compacts vers `openclaw/clawsweeper`.
|
||||
`.github/workflows/clawsweeper-dispatch.yml` est le pont côté cible entre l’activité du dépôt OpenClaw et ClawSweeper. Il ne checkout pas et n’exécute pas de code de pull request non fiable. Le workflow crée un token GitHub App à partir de `CLAWSWEEPER_APP_PRIVATE_KEY`, puis envoie des payloads `repository_dispatch` compacts à `openclaw/clawsweeper`.
|
||||
|
||||
Le workflow comporte quatre lanes :
|
||||
|
||||
- `clawsweeper_item` pour les demandes exactes de revue d’issue et de pull request ;
|
||||
- `clawsweeper_item` pour les demandes exactes de revue d’issues et de pull requests ;
|
||||
- `clawsweeper_comment` pour les commandes ClawSweeper explicites dans les commentaires d’issues ;
|
||||
- `clawsweeper_commit_review` pour les demandes de revue au niveau commit sur les pushs vers `main` ;
|
||||
- `github_activity` pour l’activité GitHub générale que l’agent ClawSweeper peut inspecter.
|
||||
|
||||
La lane `github_activity` transfère uniquement des métadonnées normalisées : type d’événement, action, acteur, dépôt, numéro d’élément, URL, titre, état, et courts extraits de commentaires ou de reviews lorsqu’ils sont présents. Elle évite volontairement de transférer le corps complet du Webhook. Le workflow récepteur dans `openclaw/clawsweeper` est `.github/workflows/github-activity.yml`, qui publie l’événement normalisé vers le hook OpenClaw Gateway pour l’agent ClawSweeper.
|
||||
La lane `github_activity` transfère uniquement des métadonnées normalisées : type d’événement, action, acteur, dépôt, numéro d’élément, URL, titre, état et courts extraits pour les commentaires ou reviews lorsqu’ils sont présents. Elle évite volontairement de transférer le corps complet du Webhook. Le workflow récepteur dans `openclaw/clawsweeper` est `.github/workflows/github-activity.yml`, qui publie l’événement normalisé vers le hook OpenClaw Gateway pour l’agent ClawSweeper.
|
||||
|
||||
L’activité générale relève de l’observation, pas d’une livraison par défaut. L’agent ClawSweeper reçoit la cible Discord dans son prompt et ne devrait publier dans `#clawsweeper` que lorsque l’événement est surprenant, actionnable, risqué ou utile sur le plan opérationnel. Les ouvertures routinières, éditions, bruit de bots, bruit de Webhook en doublon et trafic normal de reviews devraient produire `NO_REPLY`.
|
||||
L’activité générale est une observation, pas une livraison par défaut. L’agent ClawSweeper reçoit la cible Discord dans son prompt et ne doit publier dans `#clawsweeper` que lorsque l’événement est surprenant, actionnable, risqué ou utile sur le plan opérationnel. Les ouvertures routinières, modifications, agitation de bots, bruit de Webhook dupliqué et trafic normal de review doivent produire `NO_REPLY`.
|
||||
|
||||
Traitez les titres, commentaires, corps, textes de review, noms de branches et messages de commit GitHub comme des données non fiables tout au long de ce chemin. Ce sont des entrées pour la synthèse et le triage, pas des instructions pour le workflow ou le runtime de l’agent.
|
||||
|
||||
## Dispatchs manuels
|
||||
## Dispatchs manuelles
|
||||
|
||||
Les dispatchs CI manuels exécutent le même graphe de jobs que la CI normale, mais activent de force chaque lane scoped non Android : shards Linux Node, shards de plugins intégrés, contrats de canaux, compatibilité Node 22, `check`, `check-additional`, smoke build, vérifications docs, Skills Python, Windows, macOS et i18n de Control UI. Les dispatchs CI manuels autonomes exécutent uniquement Android avec `include_android=true` ; l’umbrella de release complète active Android en passant `include_android=true`. Les vérifications statiques de prérelease de Plugin, le shard `agentic-plugins` réservé à la release, le sweep complet par lot des extensions et les lanes Docker de prérelease de plugin sont exclus de la CI. La suite Docker de prérelease s’exécute uniquement lorsque `Full Release Validation` déclenche le workflow séparé `Plugin Prerelease` avec le gate de validation de release activé.
|
||||
Les dispatchs CI manuels exécutent le même graphe de jobs que la CI normale, mais activent de force chaque lane à portée non Android : fragments Linux Node, fragments de Plugins groupés, contrats de canaux, compatibilité Node 22, `check`, `check-additional`, smoke de build, vérifications docs, Skills Python, Windows, macOS et i18n de Control UI. Les dispatchs CI manuels autonomes exécutent uniquement Android avec `include_android=true` ; l’ombrelle de release complète active Android en transmettant `include_android=true`. Les vérifications statiques de préversion de Plugin, le fragment `agentic-plugins` réservé aux releases, le sweep complet par lot des extensions et les lanes Docker de préversion de Plugin sont exclus de la CI. La suite Docker de préversion s’exécute uniquement lorsque `Full Release Validation` déclenche le workflow `Plugin Prerelease` séparé avec la gate de validation de release activée.
|
||||
|
||||
Les exécutions manuelles utilisent un groupe de concurrence unique afin qu’une suite complète de release candidate ne soit pas annulée par une autre exécution push ou PR sur la même ref. L’entrée optionnelle `target_ref` permet à un appelant de confiance d’exécuter ce graphe sur une branche, un tag ou un SHA de commit complet tout en utilisant le fichier de workflow depuis la ref de dispatch sélectionnée.
|
||||
Les exécutions manuelles utilisent un groupe de concurrence unique afin qu’une suite complète de release candidate ne soit pas annulée par un autre push ou une exécution de PR sur la même ref. L’entrée facultative `target_ref` permet à un appelant de confiance d’exécuter ce graphe sur une branche, un tag ou un SHA de commit complet tout en utilisant le fichier de workflow depuis la ref de dispatch sélectionnée.
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref release/YYYY.M.D
|
||||
@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
|
||||
|
||||
## Runners
|
||||
|
||||
| Runner | Jobs |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, jobs de sécurité rapides et agrégats (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/bundled, vérifications de contrats de canaux shardées, shards `check` sauf lint, shards et agrégats `check-additional`, vérificateurs d’agrégats de tests Node, vérifications docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight install-smoke utilise aussi Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse être mise en file plus tôt |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards d’extensions plus légers, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` et `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de tests Linux Node, shards de tests de plugins intégrés, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (assez sensible au CPU pour que 8 vCPU coûtent plus qu’ils n’économisent) ; builds Docker install-smoke (le temps de file de 32 vCPU coûtait plus qu’il n’économisait) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks se replient sur `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks se replient sur `macos-latest` |
|
||||
| Runner | Jobs |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, jobs de sécurité rapides et agrégats (`security-scm-fast`, `security-dependency-audit`, `security-fast`), vérifications rapides de protocole/contrat/groupées, vérifications fragmentées de contrats de canaux, fragments `check` sauf lint, fragments et agrégats `check-additional`, vérificateurs d’agrégats de tests Node, vérifications docs, Skills Python, workflow-sanity, labeler, auto-response ; le preflight install-smoke utilise aussi Ubuntu hébergé par GitHub afin que la matrice Blacksmith puisse être mise en file plus tôt |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragments d’extensions plus légers, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` et `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragments de tests Linux Node, fragments de tests de Plugins groupés, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (assez sensible au CPU pour que 8 vCPU coûtent plus qu’ils n’économisent) ; builds Docker install-smoke (le temps de file d’attente 32 vCPU coûtait plus qu’il n’économisait) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` sur `openclaw/openclaw` ; les forks reviennent à `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` sur `openclaw/openclaw` ; les forks reviennent à `macos-latest` |
|
||||
|
||||
## Équivalents locaux
|
||||
|
||||
@ -145,30 +145,30 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
|
||||
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
|
||||
```
|
||||
|
||||
Le dispatch manuel benchmarke normalement la ref du workflow. Définissez `target_ref` pour benchmarker un tag de release ou une autre branche avec l’implémentation de workflow actuelle. Les chemins de rapports publiés et les pointeurs latest sont indexés par la ref testée, et chaque `index.md` enregistre la ref/SHA testé, la ref/SHA du workflow, la ref Kova, le profil, le mode d’authentification de lane, le modèle, le nombre de répétitions et les filtres de scénarios.
|
||||
Un dispatch manuel benchmarke normalement la ref du workflow. Définissez `target_ref` pour benchmarker un tag de release ou une autre branche avec l’implémentation actuelle du workflow. Les chemins de rapports publiés et les pointeurs les plus récents sont indexés par la ref testée, et chaque `index.md` enregistre la ref/SHA testée, la ref/SHA du workflow, la ref Kova, le profil, le mode d’authentification de lane, le modèle, le nombre de répétitions et les filtres de scénarios.
|
||||
|
||||
Le workflow installe OCM depuis une release épinglée et Kova depuis `openclaw/Kova` à l’entrée `kova_ref` épinglée, puis exécute trois lanes :
|
||||
|
||||
- `mock-provider` : scénarios de diagnostic Kova sur un runtime buildé localement avec une fausse authentification déterministe compatible OpenAI.
|
||||
- `mock-deep-profile` : profiling CPU/heap/trace pour les hotspots de démarrage, Gateway et tour d’agent.
|
||||
- `mock-provider` : scénarios de diagnostic Kova contre un runtime de build local avec une fausse auth déterministe compatible OpenAI.
|
||||
- `mock-deep-profile` : profilage CPU/heap/trace pour les points chauds du démarrage, du Gateway et des tours d’agent.
|
||||
- `live-gpt54` : un vrai tour d’agent OpenAI `openai/gpt-5.4`, ignoré lorsque `OPENAI_API_KEY` n’est pas disponible.
|
||||
|
||||
La lane mock-provider exécute aussi des sondes source natives OpenClaw après le passage Kova : timing de démarrage Gateway et mémoire pour les cas de démarrage par défaut, hook et 50 plugins ; boucles hello répétées mock-OpenAI `channel-chat-baseline` ; et commandes de démarrage CLI contre le Gateway démarré. Le résumé Markdown de sonde source se trouve dans `source/index.md` dans le bundle de rapport, avec le JSON brut à côté.
|
||||
La lane mock-provider exécute aussi des sondes de source natives OpenClaw après le passage Kova : temps de démarrage et mémoire du Gateway sur les cas de démarrage par défaut, hook et 50 Plugins ; boucles hello répétées `channel-chat-baseline` mock-OpenAI ; et commandes de démarrage CLI contre le Gateway démarré. Le résumé Markdown des sondes de source se trouve dans `source/index.md` dans le bundle de rapport, avec le JSON brut à côté.
|
||||
|
||||
Chaque lane téléverse des artefacts GitHub. Lorsque `CLAWGRIT_REPORTS_TOKEN` est configuré, le workflow commite aussi `report.json`, `report.md`, les bundles, `index.md` et les artefacts de sonde source dans `openclaw/clawgrit-reports` sous `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Le pointeur de la ref testée actuelle est écrit sous `openclaw-performance/<tested-ref>/latest-<lane>.json`.
|
||||
Chaque lane téléverse des artefacts GitHub. Lorsque `CLAWGRIT_REPORTS_TOKEN` est configuré, le workflow commit aussi `report.json`, `report.md`, les bundles, `index.md` et les artefacts de sondes de source dans `openclaw/clawgrit-reports` sous `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Le pointeur actuel de la ref testée est écrit sous `openclaw-performance/<tested-ref>/latest-<lane>.json`.
|
||||
|
||||
## Validation de release complète
|
||||
## Validation complète de release
|
||||
|
||||
`Full Release Validation` est le workflow umbrella manuel pour « tout exécuter avant la release ». Il accepte une branche, un tag ou un SHA de commit complet, déclenche le workflow manuel `CI` avec cette cible, déclenche `Plugin Prerelease` pour les preuves plugin/package/statique/Docker réservées à la release, et déclenche `OpenClaw Release Checks` pour install smoke, acceptation de package, suites Docker du chemin de release, live/E2E, OpenWebUI, parité QA Lab, Matrix et lanes Telegram. Avec `rerun_group=all` et `release_profile=full`, il exécute aussi `NPM Telegram Beta E2E` contre l’artefact `release-package-under-test` des release checks. Après publication, passez `npm_telegram_package_spec` pour réexécuter la même lane de package Telegram contre le package npm publié.
|
||||
`Full Release Validation` est le workflow ombrelle manuel pour « tout exécuter avant la release ». Il accepte une branche, un tag ou un SHA de commit complet, déclenche le workflow manuel `CI` avec cette cible, déclenche `Plugin Prerelease` pour la preuve Plugin/package/statique/Docker réservée aux releases, et déclenche `OpenClaw Release Checks` pour le smoke d’installation, l’acceptation de package, les suites de chemin de release Docker, live/E2E, OpenWebUI, la parité QA Lab, Matrix et les lanes Telegram. Avec `rerun_group=all` et `release_profile=full`, il exécute aussi `NPM Telegram Beta E2E` contre l’artefact `release-package-under-test` des vérifications de release. Après publication, transmettez `npm_telegram_package_spec` pour réexécuter la même lane de package Telegram contre le package npm publié.
|
||||
|
||||
Consultez [Validation de release complète](/fr/reference/full-release-validation) pour la
|
||||
matrice d’étapes, les noms exacts des jobs de workflow, les différences de profils, les artefacts et les
|
||||
handles de réexécution ciblée.
|
||||
Voir [Validation complète de release](/fr/reference/full-release-validation) pour la
|
||||
matrice d’étapes, les noms exacts des jobs de workflow, les différences de
|
||||
profils, les artefacts et les identifiants de réexécution ciblée.
|
||||
|
||||
`OpenClaw Release Publish` est le workflow de release mutateur manuel. Déclenchez-le
|
||||
`OpenClaw Release Publish` est le workflow manuel de release qui modifie l’état. Déclenchez-le
|
||||
depuis `release/YYYY.M.D` ou `main` après l’existence du tag de release et après la
|
||||
réussite du preflight npm OpenClaw. Il vérifie `pnpm plugins:sync:check`,
|
||||
déclenche `Plugin NPM Release` pour tous les packages de plugins publiables, déclenche
|
||||
déclenche `Plugin NPM Release` pour tous les packages de Plugins publiables, déclenche
|
||||
`Plugin ClawHub Release` pour le même SHA de release, puis déclenche seulement ensuite
|
||||
`OpenClaw NPM Release` avec le `preflight_run_id` enregistré.
|
||||
|
||||
@ -180,45 +180,40 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Pour la preuve par commit épinglé sur une branche qui évolue rapidement, utilisez l’assistant au lieu de
|
||||
Pour une preuve de commit épinglé sur une branche qui évolue rapidement, utilisez l’assistant plutôt que
|
||||
`gh workflow run ... --ref main -f ref=<sha>` :
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
Les refs de dispatch de workflow GitHub doivent être des branches ou des tags, pas des SHA de commit bruts. L’assistant pousse une branche temporaire `release-ci/<sha>-...` au SHA cible,
|
||||
déclenche `Full Release Validation` depuis cette ref épinglée, vérifie que chaque `headSha` de workflow enfant correspond à la cible, et supprime la branche temporaire lorsque
|
||||
l’exécution se termine. Le vérificateur umbrella échoue aussi si un workflow enfant s’est exécuté à un
|
||||
SHA différent.
|
||||
Les refs de dispatch de workflow GitHub doivent être des branches ou des tags, pas des SHA de commit bruts. L’assistant pousse une branche temporaire `release-ci/<sha>-...` au SHA cible, déclenche `Full Release Validation` depuis cette ref épinglée, vérifie que chaque `headSha` de workflow enfant correspond à la cible, et supprime la branche temporaire lorsque l’exécution se termine. Le vérificateur ombrelle échoue aussi si un workflow enfant s’est exécuté sur un SHA différent.
|
||||
|
||||
`release_profile` contrôle l’étendue live/fournisseur transmise aux vérifications de release. Les
|
||||
workflows de release manuelle utilisent `stable` par défaut ; utilisez `full` uniquement lorsque vous
|
||||
voulez intentionnellement la large matrice consultative fournisseur/média.
|
||||
`release_profile` contrôle l’étendue live/fournisseurs transmise aux contrôles de publication. Les workflows manuels de publication utilisent `stable` par défaut ; utilisez `full` uniquement lorsque vous voulez intentionnellement la matrice consultative étendue fournisseurs/médias.
|
||||
|
||||
- `minimum` conserve les lanes OpenAI/noyau critiques pour la release les plus rapides.
|
||||
- `stable` ajoute l’ensemble stable de fournisseurs/backends.
|
||||
- `full` exécute la large matrice consultative fournisseur/média.
|
||||
- `minimum` conserve les lanes OpenAI/cœur critiques pour la publication les plus rapides.
|
||||
- `stable` ajoute l’ensemble stable des fournisseurs/backends.
|
||||
- `full` exécute la matrice consultative étendue fournisseurs/médias.
|
||||
|
||||
Le workflow englobant enregistre les identifiants des exécutions enfants déclenchées, et la tâche finale `Verify full validation` revérifie les conclusions actuelles des exécutions enfants et ajoute des tableaux des tâches les plus lentes pour chaque exécution enfant. Si un workflow enfant est relancé et passe au vert, relancez uniquement la tâche de vérification parente pour actualiser le résultat englobant et le résumé des temps.
|
||||
Le workflow chapeau enregistre les ids d’exécution des workflows enfants déclenchés, et le job final `Verify full validation` revérifie les conclusions actuelles des exécutions enfants et ajoute des tableaux des jobs les plus lents pour chaque exécution enfant. Si un workflow enfant est relancé et passe au vert, relancez uniquement le job vérificateur parent pour actualiser le résultat chapeau et le résumé des temps.
|
||||
|
||||
Pour la reprise, `Full Release Validation` et `OpenClaw Release Checks` acceptent tous deux `rerun_group`. Utilisez `all` pour un candidat de release, `ci` uniquement pour l’enfant CI complet normal, `plugin-prerelease` uniquement pour l’enfant de prérelease de Plugin, `release-checks` pour chaque enfant de release, ou un groupe plus étroit : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` sur le workflow englobant. Cela maintient bornée la relance d’une boîte de release en échec après un correctif ciblé.
|
||||
Pour la récupération, `Full Release Validation` et `OpenClaw Release Checks` acceptent tous deux `rerun_group`. Utilisez `all` pour une candidate de publication, `ci` pour seulement l’enfant CI complet normal, `plugin-prerelease` pour seulement l’enfant de prépublication des plugins, `release-checks` pour chaque enfant de publication, ou un groupe plus restreint : `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, ou `npm-telegram` sur le workflow chapeau. Cela limite la relance d’une boîte de publication échouée après un correctif ciblé.
|
||||
|
||||
`OpenClaw Release Checks` utilise la référence de workflow approuvée pour résoudre une seule fois la référence sélectionnée en une archive `release-package-under-test`, puis transmet cet artefact au workflow Docker live/E2E du chemin de release et au shard d’acceptation de package. Cela garde les octets du package cohérents entre les boîtes de release et évite de repackager le même candidat dans plusieurs tâches enfants.
|
||||
`OpenClaw Release Checks` utilise la ref de workflow de confiance pour résoudre une seule fois la ref sélectionnée en une archive `release-package-under-test`, puis transmet cet artefact au workflow Docker du chemin de publication live/E2E et au shard d’acceptation du paquet. Cela garde les octets du paquet cohérents entre les boîtes de publication et évite de repaqueter la même candidate dans plusieurs jobs enfants.
|
||||
|
||||
Les exécutions `Full Release Validation` dupliquées pour `ref=main` et `rerun_group=all`
|
||||
remplacent le workflow englobant plus ancien. Le moniteur parent annule tout workflow enfant qu’il
|
||||
a déjà déclenché lorsque le parent est annulé, de sorte qu’une validation plus récente de main
|
||||
ne reste pas bloquée derrière une ancienne exécution de release-check de deux heures. La validation de branche/tag
|
||||
de release et les groupes de relance ciblés gardent `cancel-in-progress: false`.
|
||||
Les exécutions `Full Release Validation` en double pour `ref=main` et `rerun_group=all`
|
||||
remplacent l’ancien workflow chapeau. Le moniteur parent annule tout workflow enfant qu’il
|
||||
a déjà déclenché lorsque le parent est annulé, afin qu’une validation plus récente de main
|
||||
ne reste pas bloquée derrière une exécution de contrôles de publication obsolète de deux heures. La validation de branche/tag de publication
|
||||
et les groupes de relance ciblés gardent `cancel-in-progress: false`.
|
||||
|
||||
## Shards live et E2E
|
||||
|
||||
L’enfant live/E2E de release conserve une large couverture native `pnpm test:live`, mais l’exécute comme shards nommés via `scripts/test-live-shard.mjs` au lieu d’une seule tâche série :
|
||||
L’enfant live/E2E de publication conserve une large couverture native `pnpm test:live`, mais l’exécute comme shards nommés via `scripts/test-live-shard.mjs` au lieu d’un seul job sériel :
|
||||
|
||||
- `native-live-src-agents`
|
||||
- `native-live-src-gateway-core`
|
||||
- tâches `native-live-src-gateway-profiles` filtrées par fournisseur
|
||||
- jobs `native-live-src-gateway-profiles` filtrés par fournisseur
|
||||
- `native-live-src-gateway-backends`
|
||||
- `native-live-test`
|
||||
- `native-live-extensions-a-k`
|
||||
@ -226,61 +221,61 @@ L’enfant live/E2E de release conserve une large couverture native `pnpm test:l
|
||||
- `native-live-extensions-openai`
|
||||
- `native-live-extensions-o-z-other`
|
||||
- `native-live-extensions-xai`
|
||||
- shards audio/vidéo média séparés et shards musicaux filtrés par fournisseur
|
||||
- shards audio/vidéo médias séparés et shards musique filtrés par fournisseur
|
||||
|
||||
Cela conserve la même couverture de fichiers tout en facilitant la relance et le diagnostic des échecs lents de fournisseurs live. Les noms de shards agrégés `native-live-extensions-o-z`, `native-live-extensions-media` et `native-live-extensions-media-music` restent valides pour les relances manuelles ponctuelles.
|
||||
Cela garde la même couverture de fichiers tout en rendant les échecs lents de fournisseurs live plus faciles à relancer et à diagnostiquer. Les noms de shards agrégés `native-live-extensions-o-z`, `native-live-extensions-media` et `native-live-extensions-media-music` restent valides pour des relances manuelles ponctuelles.
|
||||
|
||||
Les shards média live natifs s’exécutent dans `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, construit par le workflow `Live Media Runner Image`. Cette image préinstalle `ffmpeg` et `ffprobe` ; les tâches média ne vérifient que les binaires avant la configuration. Gardez les suites live adossées à Docker sur des runners Blacksmith normaux — les tâches conteneurisées ne conviennent pas au lancement de tests Docker imbriqués.
|
||||
Les shards médias live natifs s’exécutent dans `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, construit par le workflow `Live Media Runner Image`. Cette image préinstalle `ffmpeg` et `ffprobe` ; les jobs médias vérifient seulement les binaires avant la configuration. Gardez les suites live adossées à Docker sur des runners Blacksmith normaux — les jobs conteneurisés ne sont pas l’endroit approprié pour lancer des tests Docker imbriqués.
|
||||
|
||||
Les shards live de modèles/backends adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:<sha>` par commit sélectionné. Le workflow de release live construit et pousse cette image une fois, puis les shards Docker live de modèle, de Gateway shardé par fournisseur, de backend CLI, de liaison ACP et de harnais Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Les shards Docker Gateway portent des limites `timeout` explicites au niveau du script, inférieures au délai d’expiration de la tâche de workflow, afin qu’un conteneur bloqué ou un chemin de nettoyage échoue rapidement au lieu de consommer tout le budget de release-check. Si ces shards reconstruisent indépendamment la cible Docker complète des sources, l’exécution de release est mal configurée et gaspillera du temps horloge en builds d’image dupliqués.
|
||||
Les shards live de modèles/backends adossés à Docker utilisent une image partagée distincte `ghcr.io/openclaw/openclaw-live-test:<sha>` par commit sélectionné. Le workflow live de publication construit et pousse cette image une seule fois, puis les shards de modèle live Docker, de Gateway shardé par fournisseur, de backend CLI, de liaison ACP et de harness Codex s’exécutent avec `OPENCLAW_SKIP_DOCKER_BUILD=1`. Les shards Docker Gateway portent des plafonds `timeout` explicites au niveau script sous le timeout du job de workflow afin qu’un conteneur bloqué ou un chemin de nettoyage échoue rapidement au lieu de consommer tout le budget des contrôles de publication. Si ces shards reconstruisent indépendamment la cible Docker source complète, l’exécution de publication est mal configurée et gaspillera du temps réel sur des builds d’image en double.
|
||||
|
||||
## Acceptation de package
|
||||
## Acceptation du paquet
|
||||
|
||||
Utilisez `Package Acceptance` lorsque la question est : « ce package OpenClaw installable fonctionne-t-il comme un produit ? » C’est différent de la CI normale : la CI normale valide l’arborescence des sources, tandis que l’acceptation de package valide une seule archive tar via le même harnais Docker E2E que les utilisateurs exercent après installation ou mise à jour.
|
||||
Utilisez `Package Acceptance` lorsque la question est « ce paquet OpenClaw installable fonctionne-t-il comme produit ? » C’est différent de la CI normale : la CI normale valide l’arborescence source, tandis que l’acceptation du paquet valide une seule archive via le même harness Docker E2E que les utilisateurs exercent après installation ou mise à jour.
|
||||
|
||||
### Tâches
|
||||
### Jobs
|
||||
|
||||
1. `resolve_package` extrait `workflow_ref`, résout un candidat de package, écrit `.artifacts/docker-e2e-package/openclaw-current.tgz`, écrit `.artifacts/docker-e2e-package/package-candidate.json`, téléverse les deux comme artefact `package-under-test`, et imprime la source, la référence de workflow, la référence de package, la version, le SHA-256 et le profil dans le résumé d’étape GitHub.
|
||||
2. `docker_acceptance` appelle `openclaw-live-and-e2e-checks-reusable.yml` avec `ref=workflow_ref` et `package_artifact_name=package-under-test`. Le workflow réutilisable télécharge cet artefact, valide l’inventaire de l’archive tar, prépare les images Docker de digest de package lorsque nécessaire, et exécute les lanes Docker sélectionnées contre ce package au lieu d’empaqueter l’extraction du workflow. Lorsqu’un profil sélectionne plusieurs `docker_lanes` ciblées, le workflow réutilisable prépare le package et les images partagées une seule fois, puis déploie ces lanes comme tâches Docker ciblées parallèles avec des artefacts uniques.
|
||||
3. `package_telegram` appelle éventuellement `NPM Telegram Beta E2E`. Il s’exécute lorsque `telegram_mode` n’est pas `none` et installe le même artefact `package-under-test` quand Package Acceptance en a résolu un ; un déclenchement Telegram autonome peut toujours installer une spécification npm publiée.
|
||||
4. `summary` fait échouer le workflow si la résolution du package, l’acceptation Docker ou la lane Telegram optionnelle a échoué.
|
||||
1. `resolve_package` extrait `workflow_ref`, résout une candidate de paquet, écrit `.artifacts/docker-e2e-package/openclaw-current.tgz`, écrit `.artifacts/docker-e2e-package/package-candidate.json`, téléverse les deux comme artefact `package-under-test`, et affiche la source, la ref de workflow, la ref du paquet, la version, le SHA-256 et le profil dans le résumé d’étape GitHub.
|
||||
2. `docker_acceptance` appelle `openclaw-live-and-e2e-checks-reusable.yml` avec `ref=workflow_ref` et `package_artifact_name=package-under-test`. Le workflow réutilisable télécharge cet artefact, valide l’inventaire de l’archive, prépare les images Docker à condensé de paquet si nécessaire, et exécute les lanes Docker sélectionnées contre ce paquet au lieu de paqueter l’extraction du workflow. Lorsqu’un profil sélectionne plusieurs `docker_lanes` ciblées, le workflow réutilisable prépare le paquet et les images partagées une seule fois, puis déploie ces lanes en jobs Docker ciblés parallèles avec des artefacts uniques.
|
||||
3. `package_telegram` appelle facultativement `NPM Telegram Beta E2E`. Il s’exécute lorsque `telegram_mode` n’est pas `none` et installe le même artefact `package-under-test` lorsque l’acceptation du paquet en a résolu un ; un déclenchement Telegram autonome peut toujours installer une spécification npm publiée.
|
||||
4. `summary` fait échouer le workflow si la résolution du paquet, l’acceptation Docker ou la lane Telegram facultative a échoué.
|
||||
|
||||
### Sources candidates
|
||||
|
||||
- `source=npm` accepte uniquement `openclaw@beta`, `openclaw@latest` ou une version de release OpenClaw exacte telle que `openclaw@2026.4.27-beta.2`. Utilisez cela pour l’acceptation de prérelease/stable publiée.
|
||||
- `source=ref` empaquette une branche, un tag ou un SHA de commit complet `package_ref` approuvé. Le résolveur récupère les branches/tags OpenClaw, vérifie que le commit sélectionné est joignable depuis l’historique de branche du dépôt ou un tag de release, installe les dépendances dans un worktree détaché, et l’empaquette avec `scripts/package-openclaw-for-docker.mjs`.
|
||||
- `source=npm` accepte seulement `openclaw@beta`, `openclaw@latest`, ou une version exacte de publication OpenClaw comme `openclaw@2026.4.27-beta.2`. Utilisez cela pour l’acceptation de prépublication/publication stable publiée.
|
||||
- `source=ref` paquete une branche, un tag ou un SHA de commit complet `package_ref` de confiance. Le résolveur récupère les branches/tags OpenClaw, vérifie que le commit sélectionné est atteignable depuis l’historique des branches du dépôt ou un tag de publication, installe les dépendances dans un worktree détaché, et le paquete avec `scripts/package-openclaw-for-docker.mjs`.
|
||||
- `source=url` télécharge un `.tgz` HTTPS ; `package_sha256` est requis.
|
||||
- `source=artifact` télécharge un `.tgz` depuis `artifact_run_id` et `artifact_name` ; `package_sha256` est facultatif mais doit être fourni pour les artefacts partagés en externe.
|
||||
- `source=artifact` télécharge un `.tgz` depuis `artifact_run_id` et `artifact_name` ; `package_sha256` est facultatif mais devrait être fourni pour les artefacts partagés en externe.
|
||||
|
||||
Gardez `workflow_ref` et `package_ref` séparés. `workflow_ref` est le code de workflow/harnais approuvé qui exécute le test. `package_ref` est le commit source qui est empaqueté lorsque `source=ref`. Cela permet au harnais de test actuel de valider d’anciens commits source approuvés sans exécuter l’ancienne logique de workflow.
|
||||
Gardez `workflow_ref` et `package_ref` séparés. `workflow_ref` est le code de workflow/harness de confiance qui exécute le test. `package_ref` est le commit source qui est paqueté lorsque `source=ref`. Cela permet au harness de test actuel de valider d’anciens commits source de confiance sans exécuter l’ancienne logique de workflow.
|
||||
|
||||
### Profils de suite
|
||||
|
||||
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
|
||||
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
|
||||
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
|
||||
- `full` — chunks complets Docker de chemin de release avec OpenWebUI
|
||||
- `full` — segments complets du chemin de publication Docker avec OpenWebUI
|
||||
- `custom` — `docker_lanes` exactes ; requis lorsque `suite_profile=custom`
|
||||
|
||||
Le profil `package` utilise une couverture Plugin hors ligne afin que la validation de package publié ne dépende pas de la disponibilité live de ClawHub. La lane Telegram optionnelle réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, avec le chemin de spécification npm publiée conservé pour les déclenchements autonomes.
|
||||
Le profil `package` utilise une couverture de plugins hors ligne afin que la validation du paquet publié ne dépende pas de la disponibilité live de ClawHub. La lane Telegram facultative réutilise l’artefact `package-under-test` dans `NPM Telegram Beta E2E`, le chemin de spécification npm publié étant conservé pour les déclenchements autonomes.
|
||||
|
||||
Pour la politique dédiée aux tests de mise à jour et de Plugin, y compris les commandes locales,
|
||||
les lanes Docker, les entrées Package Acceptance, les valeurs par défaut de release et le triage des échecs,
|
||||
consultez [Tester les mises à jour et les Plugins](/fr/help/testing-updates-plugins).
|
||||
Pour la politique dédiée aux tests de mise à jour et de plugins, y compris les commandes locales,
|
||||
les lanes Docker, les entrées d’acceptation du paquet, les valeurs par défaut de publication et le triage des échecs,
|
||||
consultez [Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins).
|
||||
|
||||
Les vérifications de release appellent Package Acceptance avec `source=artifact`, l’artefact de package de release préparé, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` et `telegram_mode=mock-openai`. Cela maintient la migration de package, la mise à jour, le nettoyage de dépendances de Plugin obsolètes, la réparation d’installation de Plugin configuré, le Plugin hors ligne, la mise à jour de Plugin et la preuve Telegram sur la même archive tar de package résolue. Définissez `package_acceptance_package_spec` sur Full Release Validation ou OpenClaw Release Checks pour exécuter cette même matrice contre un package npm livré au lieu de l’artefact construit depuis le SHA. Les vérifications de release multi-OS couvrent toujours l’onboarding, l’installateur et le comportement de plateforme spécifiques à l’OS ; la validation produit package/mise à jour doit commencer par Package Acceptance. La lane Docker `published-upgrade-survivor` valide une base de référence de package publié par exécution. Dans Package Acceptance, l’archive tar `package-under-test` résolue est toujours le candidat et `published_upgrade_survivor_baseline` sélectionne la base de référence publiée de repli, avec `openclaw@latest` par défaut ; les commandes de relance de lane échouée préservent cette base de référence. Définissez `published_upgrade_survivor_baselines=all-since-2026.4.23` pour étendre la CI Full Release à chaque release npm stable de `2026.4.23` à `latest` ; `release-history` reste disponible pour un échantillonnage manuel plus large avec l’ancien point d’ancrage antérieur à cette date. Définissez `published_upgrade_survivor_scenarios=reported-issues` pour étendre les mêmes bases de référence à des fixtures façonnées comme des issues pour la configuration Feishu, les fichiers bootstrap/persona préservés, les installations de Plugins OpenClaw configurés, les chemins de journaux avec tilde et les racines de dépendances de Plugin héritées obsolètes. Le workflow séparé `Update Migration` utilise la lane Docker `update-migration` avec `all-since-2026.4.23` et `plugin-deps-cleanup` lorsque la question porte sur le nettoyage exhaustif des mises à jour publiées, et non sur l’étendue normale de la CI Full Release. Les exécutions agrégées locales peuvent passer des spécifications de package exactes avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, garder une seule lane avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` telle que `openclaw@2026.4.15`, ou définir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` pour la matrice de scénarios. La lane publiée configure la base de référence avec une recette de commande `openclaw config set` intégrée, enregistre les étapes de recette dans `summary.json`, et sonde `/healthz`, `/readyz`, ainsi que le statut RPC après le démarrage du Gateway. Les lanes fraîches Windows empaquetées et installateur vérifient aussi qu’un package installé peut importer une surcharge browser-control depuis un chemin Windows absolu brut. Le smoke OpenAI multi-OS de tour d’agent utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsqu’il est défini, sinon `openai/gpt-5.4`, afin que la preuve d’installation et de Gateway reste sur un modèle de test GPT-5 tout en évitant les valeurs par défaut GPT-4.x.
|
||||
Les contrôles de publication appellent l’acceptation du paquet avec `source=artifact`, l’artefact de paquet de publication préparé, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues`, et `telegram_mode=mock-openai`. Cela garde la migration du paquet, la mise à jour, le nettoyage des dépendances obsolètes de plugins, la réparation d’installation de plugin configuré, le plugin hors ligne, la mise à jour de plugin et la preuve Telegram sur la même archive de paquet résolue. Définissez `package_acceptance_package_spec` sur Full Release Validation ou OpenClaw Release Checks pour exécuter cette même matrice contre un paquet npm livré au lieu de l’artefact construit depuis le SHA. Les contrôles de publication inter-OS couvrent toujours l’onboarding, l’installeur et le comportement de plateforme spécifiques aux OS ; la validation produit paquet/mise à jour devrait commencer par l’acceptation du paquet. La lane Docker `published-upgrade-survivor` valide une baseline de paquet publié par exécution. Dans l’acceptation du paquet, l’archive `package-under-test` résolue est toujours la candidate et `published_upgrade_survivor_baseline` sélectionne la baseline publiée de repli, par défaut `openclaw@latest` ; les commandes de relance de lanes échouées préservent cette baseline. Définissez `published_upgrade_survivor_baselines=all-since-2026.4.23` pour étendre la CI complète de publication à chaque publication npm stable de `2026.4.23` à `latest` ; `release-history` reste disponible pour un échantillonnage manuel plus large avec l’ancre antérieure plus ancienne. Définissez `published_upgrade_survivor_scenarios=reported-issues` pour étendre les mêmes baselines aux fixtures en forme d’issues pour la configuration Feishu, les fichiers bootstrap/persona préservés, les installations de plugins OpenClaw configurés, les chemins de logs avec tilde, et les racines de dépendances de plugins hérités obsolètes. Le workflow séparé `Update Migration` utilise la lane Docker `update-migration` avec `all-since-2026.4.23` et `plugin-deps-cleanup` lorsque la question porte sur le nettoyage exhaustif des mises à jour publiées, pas sur l’étendue normale de la CI complète de publication. Les exécutions agrégées locales peuvent passer des spécifications exactes de paquets avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, garder une seule lane avec `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` comme `openclaw@2026.4.15`, ou définir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` pour la matrice de scénarios. La lane publiée configure la baseline avec une recette de commande `openclaw config set` intégrée, enregistre les étapes de recette dans `summary.json`, et sonde `/healthz`, `/readyz`, ainsi que le statut RPC après le démarrage du Gateway. Les lanes fraîches Windows empaquetée et installeur vérifient aussi qu’un paquet installé peut importer un override browser-control depuis un chemin Windows absolu brut. La smoke inter-OS de tour d’agent OpenAI utilise par défaut `OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsqu’il est défini, sinon `openai/gpt-5.4`, afin que la preuve d’installation et de Gateway reste sur un modèle de test GPT-5 tout en évitant les valeurs par défaut GPT-4.x.
|
||||
|
||||
### Fenêtres de compatibilité héritée
|
||||
|
||||
Package Acceptance dispose de fenêtres de compatibilité héritée bornées pour les packages déjà publiés. Les packages jusqu’à `2026.4.25`, y compris `2026.4.25-beta.*`, peuvent utiliser le chemin de compatibilité :
|
||||
L’acceptation du paquet dispose de fenêtres bornées de compatibilité héritée pour les paquets déjà publiés. Les paquets jusqu’à `2026.4.25`, y compris `2026.4.25-beta.*`, peuvent utiliser le chemin de compatibilité :
|
||||
|
||||
- les entrées QA privées connues dans `dist/postinstall-inventory.json` peuvent pointer vers des fichiers omis de l’archive tar ;
|
||||
- `doctor-switch` peut ignorer le sous-cas de persistance `gateway install --wrapper` lorsque le package n’expose pas ce flag ;
|
||||
- `update-channel-switch` peut élaguer les `pnpm.patchedDependencies` manquantes de la fixture fake git dérivée de l’archive tar et peut journaliser l’absence de `update.channel` persisté ;
|
||||
- les smokes Plugin peuvent lire des emplacements hérités d’enregistrements d’installation ou accepter l’absence de persistance d’enregistrement d’installation de marketplace ;
|
||||
- `plugin-update` peut autoriser la migration des métadonnées de configuration tout en exigeant toujours que l’enregistrement d’installation et le comportement sans réinstallation restent inchangés.
|
||||
- les entrées QA privées connues dans `dist/postinstall-inventory.json` peuvent pointer vers des fichiers omis de l’archive ;
|
||||
- `doctor-switch` peut ignorer le sous-cas de persistance `gateway install --wrapper` lorsque le paquet n’expose pas ce flag ;
|
||||
- `update-channel-switch` peut élaguer les `pnpm.patchedDependencies` manquantes depuis la fixture git factice dérivée de l’archive et peut journaliser un `update.channel` persistant manquant ;
|
||||
- les smokes de plugins peuvent lire les anciens emplacements d’enregistrements d’installation ou accepter une persistance manquante des enregistrements d’installation de marketplace ;
|
||||
- `plugin-update` peut autoriser la migration des métadonnées de configuration tout en exigeant que l’enregistrement d’installation et le comportement sans réinstallation restent inchangés.
|
||||
|
||||
Le package `2026.4.26` publié peut également avertir pour les fichiers de tampon de métadonnées de build local qui ont déjà été livrés. Les packages ultérieurs doivent satisfaire les contrats modernes ; les mêmes conditions échouent au lieu d’avertir ou d’être ignorées.
|
||||
Le paquet publié `2026.4.26` peut aussi avertir pour les fichiers d’estampille de métadonnées de build local déjà livrés. Les paquets ultérieurs doivent satisfaire les contrats modernes ; les mêmes conditions échouent au lieu d’avertir ou d’être ignorées.
|
||||
|
||||
### Exemples
|
||||
|
||||
@ -323,151 +318,151 @@ gh workflow run package-acceptance.yml \
|
||||
-f docker_lanes='install-e2e plugin-update'
|
||||
```
|
||||
|
||||
Lors du débogage d’une exécution d’acceptation de package échouée, commencez par le résumé `resolve_package` pour confirmer la source du package, la version et le SHA-256. Inspectez ensuite l’exécution enfant `docker_acceptance` et ses artefacts Docker : `.artifacts/docker-tests/**/summary.json`, `failures.json`, les journaux de lanes, les minutages de phases et les commandes de réexécution. Préférez réexécuter le profil de package échoué ou les lanes Docker exactes plutôt que de relancer toute la validation de release.
|
||||
Lors du débogage d’une exécution d’acceptation de package échouée, commencez par le résumé `resolve_package` pour confirmer la source, la version et le SHA-256 du package. Inspectez ensuite l’exécution enfant `docker_acceptance` et ses artefacts Docker : `.artifacts/docker-tests/**/summary.json`, `failures.json`, les journaux de lanes, les timings de phases et les commandes de réexécution. Préférez réexécuter le profil de package échoué ou les lanes Docker exactes plutôt que de relancer la validation complète de publication.
|
||||
|
||||
## Smoke test d’installation
|
||||
|
||||
Le workflow distinct `Install Smoke` réutilise le même script de périmètre via son propre job `preflight`. Il divise la couverture smoke en `run_fast_install_smoke` et `run_full_install_smoke`.
|
||||
Le workflow `Install Smoke` séparé réutilise le même script de portée via son propre job `preflight`. Il divise la couverture smoke entre `run_fast_install_smoke` et `run_full_install_smoke`.
|
||||
|
||||
- **Chemin rapide** s’exécute pour les pull requests qui touchent les surfaces Docker/package, les changements de package/manifeste de Plugin intégré, ou les surfaces principales de Plugin/canal/Gateway/SDK Plugin exercées par les jobs de smoke Docker. Les changements de Plugin intégré limités au code source, les modifications limitées aux tests et les modifications limitées à la documentation ne réservent pas de workers Docker. Le chemin rapide construit une fois l’image Dockerfile racine, vérifie la CLI, exécute le smoke CLI de suppression des agents dans l’espace de travail partagé, exécute l’e2e du réseau Gateway de conteneur, vérifie un argument de build de Plugin intégré et exécute le profil Docker borné de Plugin intégré sous un délai d’expiration agrégé de 240 secondes pour la commande, chaque exécution Docker de scénario étant plafonnée séparément.
|
||||
- **Chemin complet** conserve la couverture d’installation de package QR et Docker/update de l’installateur pour les exécutions planifiées nocturnes, les déclenchements manuels, les vérifications de release via workflow-call et les pull requests qui touchent réellement les surfaces installateur/package/Docker. En mode complet, install-smoke prépare ou réutilise une image smoke GHCR Dockerfile racine pour le SHA cible, puis exécute l’installation de package QR, les smokes Dockerfile racine/Gateway, les smokes installateur/update et l’E2E Docker rapide de Plugin intégré en tant que jobs séparés afin que le travail d’installation n’attende pas derrière les smokes de l’image racine.
|
||||
- **Chemin rapide** s’exécute pour les pull requests touchant les surfaces Docker/package, les changements de package/manifeste de Plugin groupé, ou les surfaces Plugin SDK, Plugin, canal ou Gateway centrales que les jobs smoke Docker exercent. Les changements de source uniquement dans un Plugin groupé, les modifications limitées aux tests et les modifications limitées à la documentation ne réservent pas de workers Docker. Le chemin rapide construit une fois l’image Dockerfile racine, vérifie la CLI, exécute le smoke CLI de suppression d’agents en espace de travail partagé, exécute l’e2e container gateway-network, vérifie un argument de build d’extension groupée, et exécute le profil Docker de Plugin groupé borné sous un délai global de commande de 240 secondes (chaque exécution Docker de scénario étant plafonnée séparément).
|
||||
- **Chemin complet** conserve l’installation de package QR et la couverture Docker d’installation/mise à jour pour les exécutions planifiées nocturnes, les déclenchements manuels, les contrôles de publication par workflow-call et les pull requests qui touchent réellement les surfaces installeur/package/Docker. En mode complet, install-smoke prépare ou réutilise une image smoke GHCR Dockerfile racine de SHA cible, puis exécute l’installation de package QR, les smokes Dockerfile racine/Gateway, les smokes installeur/mise à jour et l’E2E Docker rapide de Plugin groupé comme jobs séparés afin que le travail d’installation n’attende pas derrière les smokes de l’image racine.
|
||||
|
||||
Les pushes sur `main`, y compris les commits de merge, ne forcent pas le chemin complet ; lorsque la logique de périmètre modifié demanderait une couverture complète sur un push, le workflow conserve le smoke Docker rapide et laisse le smoke d’installation complet à la validation nocturne ou de release.
|
||||
Les pushs sur `main` (y compris les commits de merge) ne forcent pas le chemin complet ; lorsque la logique de portée modifiée demanderait une couverture complète sur un push, le workflow conserve le smoke Docker rapide et laisse le smoke d’installation complet à la validation nocturne ou de publication.
|
||||
|
||||
Le smoke lent d’installation globale Bun pour le fournisseur d’image est contrôlé séparément par `run_bun_global_install_smoke`. Il s’exécute lors de la planification nocturne et depuis le workflow de vérifications de release, et les déclenchements manuels de `Install Smoke` peuvent l’activer, mais les pull requests et les pushes sur `main` ne le font pas. Les tests Docker QR et installateur conservent leurs propres Dockerfiles axés sur l’installation.
|
||||
Le smoke lent du fournisseur d’images avec installation globale Bun est contrôlé séparément par `run_bun_global_install_smoke`. Il s’exécute selon la planification nocturne et depuis le workflow des contrôles de publication, et les déclenchements manuels de `Install Smoke` peuvent l’activer explicitement, mais les pull requests et les pushs sur `main` ne le font pas. Les tests Docker QR et installeur conservent leurs propres Dockerfiles centrés sur l’installation.
|
||||
|
||||
## E2E Docker local
|
||||
|
||||
`pnpm test:docker:all` préconstruit une image de test live partagée, empaquette OpenClaw une seule fois sous forme de tarball npm et construit deux images partagées `scripts/e2e/Dockerfile` :
|
||||
`pnpm test:docker:all` préconstruit une image live-test partagée, empaquette OpenClaw une fois sous forme de tarball npm, et construit deux images `scripts/e2e/Dockerfile` partagées :
|
||||
|
||||
- un runner Node/Git minimal pour les lanes installateur/update/dépendances de Plugin ;
|
||||
- un runner Node/Git minimal pour les lanes installeur/mise à jour/dépendances de Plugin ;
|
||||
- une image fonctionnelle qui installe le même tarball dans `/app` pour les lanes de fonctionnalité normales.
|
||||
|
||||
Les définitions de lanes Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique de planification se trouve dans `scripts/lib/docker-e2e-plan.mjs`, et le runner exécute uniquement le plan sélectionné. Le planificateur sélectionne l’image par lane avec `OPENCLAW_DOCKER_E2E_BARE_IMAGE` et `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, puis exécute les lanes avec `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
Les définitions de lanes Docker se trouvent dans `scripts/lib/docker-e2e-scenarios.mjs`, la logique du planificateur dans `scripts/lib/docker-e2e-plan.mjs`, et le runner n’exécute que le plan sélectionné. L’ordonnanceur sélectionne l’image par lane avec `OPENCLAW_DOCKER_E2E_BARE_IMAGE` et `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, puis exécute les lanes avec `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
|
||||
### Paramètres réglables
|
||||
### Paramètres ajustables
|
||||
|
||||
| Variable | Valeur par défaut | Objectif |
|
||||
| -------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre de slots du pool principal pour les lanes normales. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Nombre de slots du pool final sensible aux fournisseurs. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Plafond de lanes live concurrentes afin que les fournisseurs ne limitent pas le débit. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Plafond de lanes d’installation npm concurrentes. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Plafond de lanes multi-services concurrentes. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Décalage entre les démarrages de lanes pour éviter les tempêtes de création du démon Docker ; définissez `0` pour aucun décalage. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai d’expiration de secours par lane (120 minutes) ; certaines lanes live/finales utilisent des plafonds plus stricts. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` affiche le plan du planificateur sans exécuter les lanes. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Liste exacte de lanes séparées par des virgules ; ignore le smoke de nettoyage afin que les agents puissent reproduire une lane échouée. |
|
||||
| Variable | Par défaut | Objectif |
|
||||
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Nombre de slots du pool principal pour les lanes normales. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Nombre de slots du pool de queue sensible aux fournisseurs. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Plafond de lanes live concurrentes afin que les fournisseurs ne limitent pas le débit. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Plafond de lanes d’installation npm concurrentes. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Plafond de lanes multi-services concurrentes. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Décalage entre les démarrages de lanes pour éviter les tempêtes de création du démon Docker ; définissez `0` pour aucun décalage. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Délai de secours par lane (120 minutes) ; certaines lanes live/de queue sélectionnées utilisent des plafonds plus serrés. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | non défini | `1` affiche le plan de l’ordonnanceur sans exécuter les lanes. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | non défini | Liste exacte de lanes séparées par des virgules ; ignore le smoke de nettoyage afin que les agents puissent reproduire une lane échouée. |
|
||||
|
||||
Une lane plus lourde que son plafond effectif peut tout de même démarrer depuis un pool vide, puis s’exécuter seule jusqu’à libérer de la capacité. Le préflight agrégé local vérifie Docker, supprime les anciens conteneurs E2E OpenClaw, émet l’état des lanes actives, persiste les minutages de lanes pour un ordre du plus long au plus court, et arrête par défaut de planifier de nouvelles lanes groupées après le premier échec.
|
||||
Une lane plus lourde que son plafond effectif peut tout de même démarrer depuis un pool vide, puis s’exécute seule jusqu’à libérer de la capacité. Les précontrôles locaux agrégés vérifient Docker, suppriment les conteneurs E2E OpenClaw périmés, émettent l’état des lanes actives, persistent les timings des lanes pour l’ordre du plus long au plus court, et arrêtent par défaut de planifier de nouvelles lanes en pool après le premier échec.
|
||||
|
||||
### Workflow live/E2E réutilisable
|
||||
|
||||
Le workflow live/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quelle couverture de package, type d’image, image live, lane et identifiants est requise. `scripts/docker-e2e.mjs` convertit ensuite ce plan en sorties et résumés GitHub. Il empaquette OpenClaw via `scripts/package-openclaw-for-docker.mjs`, télécharge un artefact de package de l’exécution courante, ou télécharge un artefact de package depuis `package_artifact_run_id` ; valide l’inventaire du tarball ; construit et pousse des images E2E Docker GHCR minimales/fonctionnelles étiquetées par digest de package via le cache de couches Docker de Blacksmith lorsque le plan nécessite des lanes avec package installé ; et réutilise les entrées `docker_e2e_bare_image`/`docker_e2e_functional_image` fournies ou les images existantes par digest de package au lieu de reconstruire. Les récupérations d’images Docker sont retentées avec un délai d’expiration borné de 180 secondes par tentative afin qu’un flux de registre/cache bloqué réessaie rapidement au lieu de consommer la majeure partie du chemin critique CI.
|
||||
Le workflow live/E2E réutilisable demande à `scripts/test-docker-all.mjs --plan-json` quelle couverture de package, de type d’image, d’image live, de lane et d’identifiants est requise. `scripts/docker-e2e.mjs` convertit ensuite ce plan en sorties et résumés GitHub. Il empaquette OpenClaw via `scripts/package-openclaw-for-docker.mjs`, télécharge un artefact de package de l’exécution courante ou télécharge un artefact de package depuis `package_artifact_run_id` ; valide l’inventaire du tarball ; construit et pousse les images E2E Docker GHCR bare/fonctionnelles étiquetées par digest de package via le cache de couches Docker de Blacksmith lorsque le plan nécessite des lanes avec package installé ; et réutilise les entrées `docker_e2e_bare_image`/`docker_e2e_functional_image` fournies ou des images existantes par digest de package au lieu de reconstruire. Les pulls d’images Docker sont retentés avec un délai borné de 180 secondes par tentative afin qu’un flux de registre/cache bloqué retente rapidement au lieu de consommer la majeure partie du chemin critique CI.
|
||||
|
||||
### Chunks du chemin de release
|
||||
### Morceaux du chemin de publication
|
||||
|
||||
La couverture Docker de release exécute de plus petits jobs découpés avec `OPENCLAW_SKIP_DOCKER_BUILD=1` afin que chaque chunk récupère uniquement le type d’image dont il a besoin et exécute plusieurs lanes via le même planificateur pondéré :
|
||||
La couverture Docker de publication exécute des jobs découpés plus petits avec `OPENCLAW_SKIP_DOCKER_BUILD=1` afin que chaque morceau ne tire que le type d’image dont il a besoin et exécute plusieurs lanes via le même ordonnanceur pondéré :
|
||||
|
||||
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
|
||||
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
|
||||
|
||||
Les chunks Docker de release actuels sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, et `plugins-runtime-install-a` à `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés Plugin/runtime. L’alias de lane `install-e2e` reste l’alias de réexécution manuelle agrégé pour les deux lanes d’installation de fournisseurs.
|
||||
Les morceaux Docker de publication actuels sont `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, et `plugins-runtime-install-a` à `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` et `plugins-integrations` restent des alias agrégés Plugin/runtime. L’alias de lane `install-e2e` reste l’alias agrégé de réexécution manuelle pour les deux lanes d’installation fournisseur.
|
||||
|
||||
OpenWebUI est intégré à `plugins-runtime-services` lorsque la couverture complète du chemin de release le demande, et conserve un chunk autonome `openwebui` uniquement pour les déclenchements OpenWebUI seuls. Les lanes de mise à jour de canaux intégrés réessaient une fois en cas d’échecs réseau npm transitoires.
|
||||
OpenWebUI est intégré à `plugins-runtime-services` lorsque la couverture release-path complète le demande, et conserve un morceau autonome `openwebui` uniquement pour les déclenchements limités à OpenWebUI. Les lanes de mise à jour de canaux groupés réessaient une fois en cas d’échecs réseau npm transitoires.
|
||||
|
||||
Chaque chunk téléverse `.artifacts/docker-tests/` avec les journaux de lanes, les minutages, `summary.json`, `failures.json`, les minutages de phases, le JSON du plan du planificateur, les tableaux de lanes lentes et les commandes de réexécution par lane. L’entrée `docker_lanes` du workflow exécute les lanes sélectionnées sur les images préparées au lieu des jobs de chunks, ce qui limite le débogage d’une lane échouée à un seul job Docker ciblé et prépare, télécharge ou réutilise l’artefact de package pour cette exécution ; si une lane sélectionnée est une lane Docker live, le job ciblé construit localement l’image de test live pour cette réexécution. Les commandes GitHub générées de réexécution par lane incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, afin qu’une lane échouée puisse réutiliser le package et les images exacts de l’exécution échouée.
|
||||
Chaque morceau téléverse `.artifacts/docker-tests/` avec les journaux de lanes, les timings, `summary.json`, `failures.json`, les timings de phases, le JSON du plan de l’ordonnanceur, les tableaux de lanes lentes et les commandes de réexécution par lane. L’entrée `docker_lanes` du workflow exécute les lanes sélectionnées contre les images préparées au lieu des jobs de morceaux, ce qui limite le débogage d’une lane échouée à un job Docker ciblé et prépare, télécharge ou réutilise l’artefact de package pour cette exécution ; si une lane sélectionnée est une lane Docker live, le job ciblé construit localement l’image live-test pour cette réexécution. Les commandes GitHub de réexécution générées par lane incluent `package_artifact_run_id`, `package_artifact_name` et les entrées d’images préparées lorsque ces valeurs existent, afin qu’une lane échouée puisse réutiliser le package et les images exacts de l’exécution échouée.
|
||||
|
||||
```bash
|
||||
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
|
||||
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
|
||||
```
|
||||
|
||||
Le workflow live/E2E planifié exécute quotidiennement la suite Docker complète du chemin de release.
|
||||
Le workflow live/E2E planifié exécute quotidiennement toute la suite Docker release-path.
|
||||
|
||||
## Prérelease Plugin
|
||||
## Prépublication de Plugin
|
||||
|
||||
`Plugin Prerelease` est une couverture produit/package plus coûteuse ; il s’agit donc d’un workflow séparé déclenché par `Full Release Validation` ou par un opérateur explicite. Les pull requests normales, les pushes sur `main` et les déclenchements CI manuels autonomes gardent cette suite désactivée. Il répartit les tests de Plugins intégrés sur huit workers d’extension ; ces jobs de shards d’extension exécutent jusqu’à deux groupes de configuration de Plugin à la fois, avec un worker Vitest par groupe et un heap Node plus grand afin que les lots de Plugins lourds en imports ne créent pas de jobs CI supplémentaires. Le chemin Docker de prérelease réservé aux releases regroupe les lanes Docker ciblées en petits groupes pour éviter de réserver des dizaines de runners pour des jobs d’une à trois minutes.
|
||||
`Plugin Prerelease` est une couverture produit/package plus coûteuse ; il s’agit donc d’un workflow séparé déclenché par `Full Release Validation` ou par un opérateur explicite. Les pull requests normales, les pushs sur `main` et les déclenchements CI manuels autonomes gardent cette suite désactivée. Il équilibre les tests de Plugins groupés entre huit workers d’extensions ; ces jobs de shards d’extensions exécutent jusqu’à deux groupes de configuration de Plugin à la fois avec un worker Vitest par groupe et un tas Node plus grand, afin que les lots de Plugins lourds en imports ne créent pas de jobs CI supplémentaires. Le chemin de prépublication Docker réservé à la publication regroupe les lanes Docker ciblées en petits groupes pour éviter de réserver des dizaines de runners pour des jobs d’une à trois minutes.
|
||||
|
||||
## Labo QA
|
||||
## Laboratoire QA
|
||||
|
||||
Le Labo QA dispose de lanes CI dédiées en dehors du workflow principal à périmètre intelligent. La parité agentique est imbriquée sous les harnais QA et de release larges, et non dans un workflow PR autonome. Utilisez `Full Release Validation` avec `rerun_group=qa-parity` lorsque la parité doit accompagner une exécution de validation large.
|
||||
QA Lab dispose de lanes CI dédiées en dehors du workflow principal à portée intelligente. La parité agentique est imbriquée sous les harnais QA et de publication larges, et non dans un workflow PR autonome. Utilisez `Full Release Validation` avec `rerun_group=qa-parity` lorsque la parité doit accompagner une exécution de validation large.
|
||||
|
||||
- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et lors d’un déclenchement manuel ; il déploie la lane de parité simulée, la lane Matrix live, ainsi que les lanes Telegram et Discord live comme jobs parallèles. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des baux Convex.
|
||||
- Le workflow `QA-Lab - All Lanes` s’exécute chaque nuit sur `main` et lors d’un déclenchement manuel ; il déploie en parallèle la lane de parité mock, la lane Matrix live, ainsi que les lanes Telegram et Discord live sous forme de jobs parallèles. Les jobs live utilisent l’environnement `qa-live-shared`, et Telegram/Discord utilisent des leases Convex.
|
||||
|
||||
Les vérifications de release exécutent les lanes de transport live Matrix et Telegram avec le fournisseur mock déterministe et des modèles qualifiés mock (`mock-openai/gpt-5.5` et `mock-openai/gpt-5.5-alt`) afin que le contrat de canal soit isolé de la latence des modèles live et du démarrage normal du Plugin fournisseur. Le Gateway de transport live désactive la recherche mémoire, car la parité QA couvre séparément le comportement mémoire ; la connectivité des fournisseurs est couverte par les suites distinctes modèle live, fournisseur natif et fournisseur Docker.
|
||||
Les contrôles de publication exécutent les lanes de transport live Matrix et Telegram avec le fournisseur mock déterministe et des modèles qualifiés mock (`mock-openai/gpt-5.5` et `mock-openai/gpt-5.5-alt`) afin que le contrat de canal soit isolé de la latence des modèles live et du démarrage normal des Plugins fournisseurs. Le Gateway de transport live désactive la recherche mémoire, car la parité QA couvre séparément le comportement mémoire ; la connectivité fournisseur est couverte par les suites séparées de modèles live, fournisseurs natifs et fournisseurs Docker.
|
||||
|
||||
Matrix utilise `--profile fast` pour les gates planifiés et de release, en ajoutant `--fail-fast` uniquement lorsque la CLI extraite le prend en charge. La valeur par défaut de la CLI et l’entrée manuelle du workflow restent `all` ; un déclenchement manuel `matrix_profile=all` segmente toujours la couverture Matrix complète en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`.
|
||||
Matrix utilise `--profile fast` pour les gates planifiées et de publication, en ajoutant `--fail-fast` uniquement lorsque la CLI extraite le prend en charge. La valeur par défaut de la CLI et l’entrée de workflow manuelle restent `all` ; un déclenchement manuel `matrix_profile=all` fragmente toujours la couverture Matrix complète en jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` et `e2ee-cli`.
|
||||
|
||||
`OpenClaw Release Checks` exécute également les lanes QA Lab critiques pour la release avant l’approbation de la release ; son gate de parité QA exécute les packs candidat et de référence comme jobs de lanes parallèles, puis télécharge les deux artefacts dans un petit job de rapport pour la comparaison finale de parité.
|
||||
`OpenClaw Release Checks` exécute également les lanes QA Lab critiques pour la publication avant l’approbation de publication ; son gate de parité QA exécute les packs candidat et de référence comme jobs de lanes parallèles, puis télécharge les deux artefacts dans un petit job de rapport pour la comparaison finale de parité.
|
||||
|
||||
Pour les PR normales, suivez les preuves CI/check à périmètre limité au lieu de traiter la parité comme un statut requis.
|
||||
Pour les PR normales, suivez les preuves CI/contrôles à portée limitée au lieu de traiter la parité comme un statut requis.
|
||||
|
||||
## CodeQL
|
||||
|
||||
Le workflow `CodeQL` est volontairement un scanner de sécurité de premier passage restreint, et non une analyse complète du dépôt. Les exécutions quotidiennes, manuelles et de garde pour les pull requests non brouillon analysent le code des workflows Actions ainsi que les surfaces JavaScript/TypeScript les plus risquées, avec des requêtes de sécurité à haute confiance filtrées sur `security-severity` élevée/critique.
|
||||
Le workflow `CodeQL` est intentionnellement un scanner de sécurité de premier passage à périmètre étroit, pas une analyse complète du dépôt. Les exécutions quotidiennes, manuelles et de garde des pull requests non brouillon analysent le code des workflows Actions ainsi que les surfaces JavaScript/TypeScript les plus risquées avec des requêtes de sécurité à haute confiance filtrées sur les niveaux `security-severity` élevé/critique.
|
||||
|
||||
La garde des pull requests reste légère : elle ne démarre que pour les changements sous `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, et elle exécute la même matrice de sécurité à haute confiance que le workflow planifié. CodeQL Android et macOS restent hors des valeurs par défaut des PR.
|
||||
La garde de pull request reste légère : elle ne démarre que pour les changements sous `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, et elle exécute la même matrice de sécurité à haute confiance que le workflow planifié. Android et macOS CodeQL restent exclus des valeurs par défaut des PR.
|
||||
|
||||
### Catégories de sécurité
|
||||
|
||||
| Catégorie | Surface |
|
||||
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-security-high/core-auth-secrets` | Authentification, secrets, sandbox, cron et base de référence du Gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation des canaux du cœur, plus runtime des Plugins de canal, Gateway, Plugin SDK, secrets et points de contact d’audit |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Surfaces de stratégie SSRF du cœur, analyse d’IP, garde réseau, récupération web et Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, assistants d’exécution de processus, livraison sortante et gardes d’exécution d’outils d’agent |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | Surfaces de confiance de l’installation de Plugin, loader, manifeste, registre, installation par gestionnaire de paquets, chargement de source et contrat de paquet du Plugin SDK |
|
||||
| `/codeql-security-high/core-auth-secrets` | Authentification, secrets, sandbox, Cron et base de référence Gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Contrats d’implémentation des canaux du cœur, ainsi que l’exécution du Plugin de canal, le Gateway, le Plugin SDK, les secrets et les points de contact d’audit |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Surfaces SSRF du cœur, analyse d’IP, garde réseau, récupération web et politique SSRF du Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | Serveurs MCP, assistants d’exécution de processus, livraison sortante et barrières d’exécution d’outils d’agent |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | Surfaces de confiance de l’installation de Plugin, du chargeur, du manifeste, du registre, de l’installation via gestionnaire de paquets, du chargement de source et du contrat de paquet du Plugin SDK |
|
||||
|
||||
### Fragments de sécurité propres à la plateforme
|
||||
### Éclats de sécurité propres aux plateformes
|
||||
|
||||
- `CodeQL Android Critical Security` — fragment de sécurité Android planifié. Construit manuellement l’application Android pour CodeQL sur le plus petit exécuteur Blacksmith Linux accepté par la vérification de cohérence du workflow. Téléverse sous `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — fragment de sécurité macOS hebdomadaire/manuel. Construit manuellement l’application macOS pour CodeQL sur Blacksmith macOS, filtre les résultats de build des dépendances hors du SARIF téléversé, et téléverse sous `/codeql-critical-security/macos`. Conservé hors des valeurs par défaut quotidiennes parce que le build macOS domine le temps d’exécution même lorsqu’il est propre.
|
||||
- `CodeQL Android Critical Security` — éclat de sécurité Android planifié. Construit manuellement l’application Android pour CodeQL sur le plus petit runner Linux Blacksmith accepté par la validation de cohérence du workflow. Téléverse sous `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — éclat de sécurité macOS hebdomadaire/manuel. Construit manuellement l’application macOS pour CodeQL sur Blacksmith macOS, filtre les résultats de construction des dépendances hors du SARIF téléversé et téléverse sous `/codeql-critical-security/macos`. Conservé en dehors des valeurs par défaut quotidiennes parce que la construction macOS domine le temps d’exécution même lorsqu’elle est propre.
|
||||
|
||||
### Catégories de qualité critique
|
||||
|
||||
`CodeQL Critical Quality` est le fragment non sécuritaire correspondant. Il n’exécute que des requêtes de qualité JavaScript/TypeScript de sévérité erreur et non sécuritaires sur des surfaces restreintes à forte valeur, sur le plus petit exécuteur Blacksmith Linux. Sa garde de pull request est volontairement plus réduite que le profil planifié : les PR non brouillon n’exécutent que les fragments correspondants `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` et `plugin-sdk-reply-runtime` pour les changements de code d’exécution de commandes/modèles/outils d’agent et de distribution des réponses, de schéma/migration/E/S de configuration, d’authentification/secrets/sandbox/sécurité, de canaux du cœur et runtime des Plugins de canal groupés, de protocole Gateway/méthodes serveur, de runtime mémoire/glue SDK, de MCP/processus/livraison sortante, de runtime fournisseur/catalogue de modèles, de diagnostics de session/files de livraison, de loader de Plugin, de contrat Plugin SDK/paquet ou de runtime de réponse du Plugin SDK. Les changements de configuration CodeQL et de workflow qualité exécutent les douze fragments qualité de PR.
|
||||
`CodeQL Critical Quality` est l’éclat non lié à la sécurité correspondant. Il exécute uniquement des requêtes de qualité JavaScript/TypeScript de sévérité erreur et non liées à la sécurité, sur des surfaces étroites à forte valeur, sur le plus petit runner Linux Blacksmith. Sa garde de pull request est intentionnellement plus petite que le profil planifié : les PR non brouillon n’exécutent que les éclats correspondants `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` et `plugin-sdk-reply-runtime` pour les changements touchant le code d’exécution des commandes/modèles/outils d’agent et de distribution des réponses, le schéma/la migration/les E/S de configuration, le code d’authentification/secrets/sandbox/sécurité, l’exécution des canaux du cœur et des Plugins de canal groupés, le protocole Gateway/la méthode serveur, la colle d’exécution mémoire/SDK, MCP/processus/livraison sortante, le catalogue de modèles/l’exécution fournisseur, les diagnostics de session/files de livraison, le chargeur de Plugin, le contrat Plugin SDK/paquet ou l’exécution de réponse du Plugin SDK. Les changements de configuration CodeQL et de workflow de qualité exécutent les douze éclats de qualité PR.
|
||||
|
||||
Le déclenchement manuel accepte :
|
||||
La distribution manuelle accepte :
|
||||
|
||||
```
|
||||
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
|
||||
```
|
||||
|
||||
Les profils restreints sont des points d’accroche d’apprentissage/itération pour exécuter un fragment qualité isolément.
|
||||
Les profils étroits sont des points d’ancrage d’apprentissage/itération pour exécuter un éclat de qualité isolément.
|
||||
|
||||
| Catégorie | Surface |
|
||||
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Code de frontière de sécurité pour authentification, secrets, sandbox, cron et Gateway |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Code de frontière de sécurité pour l’authentification, les secrets, la sandbox, Cron et le Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | Contrats de schéma de configuration, migration, normalisation et E/S |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas du protocole Gateway et contrats de méthodes serveur |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Schémas de protocole Gateway et contrats de méthodes serveur |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | Contrats d’implémentation des canaux du cœur et des Plugins de canal groupés |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Contrats de runtime pour exécution de commandes, distribution modèle/fournisseur, distribution et files d’auto-réponse, et plan de contrôle ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serveurs MCP et passerelles d’outils, assistants de supervision de processus, et contrats de livraison sortante |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hôte mémoire, façades de runtime mémoire, alias mémoire du Plugin SDK, glue d’activation du runtime mémoire, et commandes doctor mémoire |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Internes de file de réponses, files de livraison de session, assistants de liaison/livraison de session sortante, surfaces d’événements diagnostiques/bundles de journaux, et contrats CLI doctor de session |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Distribution des réponses entrantes du Plugin SDK, assistants de payload/découpage/runtime de réponse, options de réponse de canal, files de livraison et assistants de liaison session/thread |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte des fournisseurs, enregistrement du runtime fournisseur, valeurs par défaut/catalogues fournisseur, et registres web/recherche/récupération/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Amorçage de l’UI de contrôle, persistance locale, flux de contrôle Gateway et contrats de runtime du plan de contrôle des tâches |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | Contrats de runtime pour récupération/recherche web du cœur, E/S média, compréhension média, génération d’images et génération média |
|
||||
| `/codeql-critical-quality/plugin-boundary` | Contrats de loader, registre, surface publique et points d’entrée du Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | Source du Plugin SDK côté paquet publié et assistants de contrat de paquet Plugin |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Exécution de commandes, distribution modèle/fournisseur, distribution et files de réponses automatiques, et contrats d’exécution du plan de contrôle ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Serveurs MCP et ponts d’outils, assistants de supervision de processus, et contrats de livraison sortante |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK hôte de mémoire, façades d’exécution mémoire, alias mémoire du Plugin SDK, colle d’activation de l’exécution mémoire et commandes doctor mémoire |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Internes de file de réponses, files de livraison de session, assistants de liaison/livraison de session sortante, surfaces de bundles d’événements/logs de diagnostic et contrats CLI doctor de session |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Distribution des réponses entrantes du Plugin SDK, assistants de payload/découpage/exécution de réponse, options de réponse de canal, files de livraison et assistants de liaison session/thread |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisation du catalogue de modèles, authentification et découverte fournisseur, enregistrement de l’exécution fournisseur, valeurs par défaut/catalogues fournisseur, et registres web/recherche/récupération/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Amorçage de l’interface de contrôle, persistance locale, flux de contrôle Gateway et contrats d’exécution du plan de contrôle des tâches |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | Récupération/recherche web du cœur, E/S média, compréhension des médias, génération d’images et contrats d’exécution de génération de médias |
|
||||
| `/codeql-critical-quality/plugin-boundary` | Contrats de chargeur, registre, surface publique et points d’entrée du Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | Source du Plugin SDK côté paquet publié et assistants de contrat de paquet de plugin |
|
||||
|
||||
La qualité reste séparée de la sécurité afin que les constats de qualité puissent être planifiés, mesurés, désactivés ou étendus sans brouiller le signal de sécurité. L’extension CodeQL à Swift, Python et aux Plugins groupés devrait être réintroduite sous forme de suivi restreint ou fragmenté uniquement après stabilisation du runtime et du signal des profils restreints.
|
||||
La qualité reste séparée de la sécurité afin que les constats de qualité puissent être planifiés, mesurés, désactivés ou étendus sans masquer le signal de sécurité. L’extension CodeQL Swift, Python et Plugins groupés doit être réintroduite comme travail de suivi à périmètre défini ou fragmenté uniquement après que les profils étroits disposent d’un temps d’exécution et d’un signal stables.
|
||||
|
||||
## Workflows de maintenance
|
||||
|
||||
### Docs Agent
|
||||
|
||||
Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par événements pour garder les docs existantes alignées avec les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie d’un push non bot sur `main` peut le déclencher, et le déclenchement manuel peut l’exécuter directement. Les invocations par workflow-run sont ignorées lorsque `main` a avancé ou lorsqu’une autre exécution Docs Agent non ignorée a été créée au cours de la dernière heure. Lorsqu’il s’exécute, il examine la plage de commits depuis le SHA source du précédent Docs Agent non ignoré jusqu’au `main` actuel, de sorte qu’une exécution horaire peut couvrir tous les changements de main accumulés depuis le dernier passage docs.
|
||||
Le workflow `Docs Agent` est une voie de maintenance Codex pilotée par événements pour garder les docs existantes alignées avec les changements récemment intégrés. Il n’a pas de planification pure : une exécution CI réussie sur `main` après push non bot peut le déclencher, et la distribution manuelle peut l’exécuter directement. Les invocations par workflow-run sont ignorées lorsque `main` a avancé ou lorsqu’une autre exécution Docs Agent non ignorée a été créée dans l’heure précédente. Lorsqu’il s’exécute, il examine la plage de commits depuis le SHA source du précédent Docs Agent non ignoré jusqu’au `main` courant, de sorte qu’une exécution horaire peut couvrir tous les changements de main accumulés depuis le dernier passage docs.
|
||||
|
||||
### Test Performance Agent
|
||||
|
||||
Le workflow `Test Performance Agent` est une voie de maintenance Codex pilotée par événements pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie d’un push non bot sur `main` peut le déclencher, mais il est ignoré si une autre invocation par workflow-run a déjà été exécutée ou est en cours ce jour UTC. Le déclenchement manuel contourne cette garde d’activité quotidienne. La voie construit un rapport de performance Vitest groupé sur toute la suite, laisse Codex n’effectuer que de petites corrections de performance de tests préservant la couverture au lieu de refactorisations larges, puis relance le rapport sur toute la suite et rejette les changements qui réduisent le nombre de tests réussis dans la base de référence. Si la base de référence contient des tests en échec, Codex ne peut corriger que les échecs évidents et le rapport sur toute la suite après agent doit réussir avant tout commit. Lorsque `main` avance avant que le push du bot n’arrive, la voie rebase le patch validé, relance `pnpm check:changed`, puis réessaie le push ; les patchs obsolètes en conflit sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex puisse conserver la même posture de sécurité drop-sudo que l’agent docs.
|
||||
Le workflow `Test Performance Agent` est une voie de maintenance Codex pilotée par événements pour les tests lents. Il n’a pas de planification pure : une exécution CI réussie sur `main` après push non bot peut le déclencher, mais il s’ignore si une autre invocation par workflow-run a déjà été exécutée ou est en cours ce jour UTC. La distribution manuelle contourne cette garde d’activité quotidienne. La voie construit un rapport de performance Vitest groupé sur toute la suite, laisse Codex effectuer uniquement de petites corrections de performance de tests préservant la couverture au lieu de refactorisations larges, puis réexécute le rapport de toute la suite et rejette les changements qui réduisent le nombre de tests de base réussis. Si la base de référence contient des tests en échec, Codex peut ne corriger que les échecs évidents et le rapport de toute la suite après l’agent doit réussir avant toute validation. Lorsque `main` avance avant que le push du bot n’atterrisse, la voie rebase le patch validé, réexécute `pnpm check:changed` et réessaie le push ; les patchs obsolètes conflictuels sont ignorés. Elle utilise Ubuntu hébergé par GitHub afin que l’action Codex puisse conserver la même posture de sécurité sans sudo que l’agent docs.
|
||||
|
||||
### PR en double après fusion
|
||||
### PR dupliquées après fusion
|
||||
|
||||
Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel pour le nettoyage des doublons après intégration. Il utilise par défaut un dry-run et ne ferme que les PR explicitement listées lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est fusionnée et que chaque doublon possède soit une issue référencée commune, soit des hunks modifiés qui se chevauchent.
|
||||
Le workflow `Duplicate PRs After Merge` est un workflow mainteneur manuel pour le nettoyage des doublons après intégration. Il utilise par défaut le mode dry-run et ne ferme que les PR explicitement listées lorsque `apply=true`. Avant de modifier GitHub, il vérifie que la PR intégrée est fusionnée et que chaque doublon a soit un ticket référencé commun, soit des hunks modifiés qui se chevauchent.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -478,38 +473,115 @@ gh workflow run duplicate-after-merge.yml \
|
||||
|
||||
## Portes de vérification locales et routage des changements
|
||||
|
||||
La logique locale des voies modifiées vit dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte de vérification locale est plus stricte sur les frontières d’architecture que le périmètre large de la plateforme CI :
|
||||
La logique locale des voies de changement se trouve dans `scripts/changed-lanes.mjs` et est exécutée par `scripts/check-changed.mjs`. Cette porte de vérification locale est plus stricte sur les frontières d’architecture que le périmètre large de la plateforme CI :
|
||||
|
||||
- les changements de production du cœur exécutent le typecheck prod du cœur et test du cœur, plus lint/gardes du cœur ;
|
||||
- les changements uniquement de tests du cœur exécutent seulement le typecheck test du cœur, plus le lint du cœur ;
|
||||
- les changements de production d’extension exécutent le typecheck prod d’extension et test d’extension, plus le lint d’extension ;
|
||||
- les changements uniquement de tests d’extension exécutent le typecheck test d’extension, plus le lint d’extension ;
|
||||
- les changements publics du Plugin SDK ou de contrat Plugin s’étendent au typecheck d’extension parce que les extensions dépendent de ces contrats du cœur (les analyses Vitest d’extensions restent un travail de test explicite) ;
|
||||
- les montées de version uniquement de métadonnées de release exécutent des vérifications ciblées de version/configuration/dépendances racine ;
|
||||
- les changements root/config inconnus échouent prudemment vers toutes les voies de vérification.
|
||||
- les changements de production du cœur exécutent le typecheck prod du cœur et le typecheck des tests du cœur, plus le lint/les gardes du cœur ;
|
||||
- les changements touchant uniquement les tests du cœur n’exécutent que le typecheck des tests du cœur plus le lint du cœur ;
|
||||
- les changements de production d’extension exécutent le typecheck prod d’extension et le typecheck des tests d’extension, plus le lint d’extension ;
|
||||
- les changements touchant uniquement les tests d’extension exécutent le typecheck des tests d’extension plus le lint d’extension ;
|
||||
- les changements de Plugin SDK public ou de contrat de plugin s’étendent au typecheck d’extension parce que les extensions dépendent de ces contrats du cœur (les balayages Vitest d’extension restent du travail de test explicite) ;
|
||||
- les incréments de version portant uniquement sur les métadonnées de release exécutent des vérifications ciblées version/configuration/dépendances racine ;
|
||||
- les changements racine/config inconnus échouent prudemment vers toutes les voies de vérification.
|
||||
|
||||
Le routage local des tests modifiés vit dans `scripts/test-projects.test-support.mjs` et est volontairement moins coûteux que `check:changed` : les modifications directes de tests s’exécutent elles-mêmes, les modifications de source privilégient les mappings explicites, puis les tests frères et les dépendants du graphe d’imports. La configuration partagée de livraison group-room fait partie des mappings explicites : les changements de configuration de réponse visible de groupe, du mode de livraison de réponse source ou du prompt système de l’outil de message passent par les tests de réponse du cœur plus les régressions de livraison Discord et Slack, afin qu’un changement de valeur par défaut partagée échoue avant le premier push de PR. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque le changement est assez transversal au harnais pour que l’ensemble mappé économique ne soit pas un proxy fiable.
|
||||
Le routage local des tests modifiés se trouve dans `scripts/test-projects.test-support.mjs` et est intentionnellement moins coûteux que `check:changed` : les modifications directes de tests s’exécutent elles-mêmes, les modifications de source privilégient les mappages explicites, puis les tests frères et les dépendants du graphe d’importation. La configuration de livraison de salle de groupe partagée fait partie des mappages explicites : les changements de la configuration de réponse visible de groupe, du mode de livraison des réponses source ou du prompt système de l’outil de message passent par les tests de réponse du cœur ainsi que les régressions de livraison Discord et Slack, afin qu’un changement de valeur par défaut partagé échoue avant le premier push de PR. Utilisez `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` uniquement lorsque le changement est assez transversal au harnais pour que l’ensemble mappé peu coûteux ne soit pas un proxy fiable.
|
||||
|
||||
## Validation Testbox
|
||||
|
||||
Exécutez Testbox depuis la racine du dépôt et privilégiez une instance fraîchement préparée pour une validation large. Avant de lancer une vérification lente sur une instance réutilisée, expirée ou qui vient de signaler une synchronisation anormalement volumineuse, exécutez d’abord `pnpm testbox:sanity` dans l’instance.
|
||||
Exécutez Testbox depuis la racine du dépôt et préférez une box fraîche préchauffée pour une validation étendue. Avant de lancer un gate lent sur une box qui a été réutilisée, a expiré ou vient de signaler une synchronisation étonnamment volumineuse, exécutez d’abord `pnpm testbox:sanity` dans la box.
|
||||
|
||||
La vérification de cohérence échoue rapidement lorsque des fichiers racine requis comme `pnpm-lock.yaml` ont disparu ou lorsque `git status --short` affiche au moins 200 suppressions de fichiers suivis. Cela signifie généralement que l’état de synchronisation distant n’est pas une copie fiable de la PR ; arrêtez cette instance et préparez-en une nouvelle au lieu de déboguer l’échec du test produit. Pour les PRs avec de nombreuses suppressions intentionnelles, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution de cohérence.
|
||||
Le contrôle d’intégrité échoue rapidement lorsque des fichiers racine requis comme `pnpm-lock.yaml` ont disparu ou lorsque `git status --short` affiche au moins 200 suppressions suivies. Cela signifie généralement que l’état de synchronisation distant n’est pas une copie fiable de la PR ; arrêtez cette box et préchauffez-en une fraîche au lieu de déboguer l’échec du test produit. Pour les PRs comportant intentionnellement de nombreuses suppressions, définissez `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` pour cette exécution d’intégrité.
|
||||
|
||||
`pnpm testbox:run` termine aussi une invocation locale de la CLI Blacksmith qui reste en phase de synchronisation pendant plus de cinq minutes sans sortie post-synchronisation. Définissez `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` pour désactiver cette protection, ou utilisez une valeur en millisecondes plus élevée pour des diffs locaux exceptionnellement volumineux.
|
||||
`pnpm testbox:run` termine aussi une invocation locale de la CLI Blacksmith qui reste en phase de synchronisation pendant plus de cinq minutes sans sortie après synchronisation. Définissez `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` pour désactiver cette protection, ou utilisez une valeur plus grande en millisecondes pour des diffs locaux exceptionnellement volumineux.
|
||||
|
||||
Crabbox est le second chemin d’instance distante propre au dépôt pour la validation Linux lorsque Blacksmith n’est pas disponible ou lorsque la capacité cloud détenue est préférable. Préparez une instance, hydratez-la via le workflow du projet, puis exécutez les commandes avec la CLI Crabbox :
|
||||
Crabbox est le wrapper de box distante appartenant au dépôt pour les validations Linux des mainteneurs. Utilisez-le quand une vérification est trop large pour une boucle d’édition locale, quand la parité avec la CI importe, ou quand la validation nécessite des secrets, Docker, des lanes de paquet, des boxes réutilisables ou des journaux distants. Le backend OpenClaw normal est `blacksmith-testbox` ; la capacité AWS/Hetzner détenue est une solution de repli pour les pannes Blacksmith, les problèmes de quota ou les tests explicites sur capacité détenue.
|
||||
|
||||
Avant une première exécution, vérifiez le wrapper depuis la racine du dépôt :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id>
|
||||
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
|
||||
pnpm crabbox:stop -- <cbx_id>
|
||||
pnpm crabbox:run -- --help | sed -n '1,120p'
|
||||
```
|
||||
|
||||
`.crabbox.yaml` détient les valeurs par défaut du fournisseur, de la synchronisation et de l’hydratation GitHub Actions. Il exclut le `.git` local afin que le checkout Actions hydraté conserve ses propres métadonnées Git distantes au lieu de synchroniser les remotes et les magasins d’objets locaux du mainteneur, et il exclut les artefacts locaux d’exécution et de build qui ne doivent jamais être transférés. `.github/workflows/crabbox-hydrate.yml` détient le checkout, la configuration Node/pnpm, la récupération de `origin/main` et la transmission de l’environnement non secret que les commandes ultérieures `crabbox run --id <cbx_id>` sourcent.
|
||||
Le wrapper du dépôt refuse un binaire Crabbox obsolète qui n’annonce pas `blacksmith-testbox`. Passez le fournisseur explicitement même si `.crabbox.yaml` contient des valeurs par défaut owned-cloud.
|
||||
|
||||
## Liens connexes
|
||||
Gate des modifications :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
```
|
||||
|
||||
Relance de test ciblée :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
|
||||
```
|
||||
|
||||
Suite complète :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox \
|
||||
--blacksmith-org openclaw \
|
||||
--blacksmith-workflow .github/workflows/ci-check-testbox.yml \
|
||||
--blacksmith-job check \
|
||||
--blacksmith-ref main \
|
||||
--idle-timeout 90m \
|
||||
--ttl 240m \
|
||||
--timing-json \
|
||||
--shell -- \
|
||||
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
|
||||
```
|
||||
|
||||
Lisez le résumé JSON final. Les champs utiles sont `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` et `totalMs`. Les exécutions ponctuelles de Crabbox adossées à Blacksmith doivent arrêter la Testbox automatiquement ; si une exécution est interrompue ou si le nettoyage n’est pas clair, inspectez les boxes actives et arrêtez uniquement celles que vous avez créées :
|
||||
|
||||
```bash
|
||||
blacksmith testbox list
|
||||
blacksmith testbox stop --id <tbx_id>
|
||||
```
|
||||
|
||||
N’utilisez la réutilisation que lorsque vous avez intentionnellement besoin de plusieurs commandes sur la même box hydratée :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
|
||||
pnpm crabbox:stop -- <tbx_id>
|
||||
```
|
||||
|
||||
Si Crabbox est la couche défaillante mais que Blacksmith lui-même fonctionne, utilisez directement Blacksmith comme solution de repli limitée :
|
||||
|
||||
```bash
|
||||
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
|
||||
blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
blacksmith testbox stop --id <tbx_id>
|
||||
```
|
||||
|
||||
N’escaladez vers la capacité Crabbox détenue que lorsque Blacksmith est indisponible, limité par quota, privé de l’environnement nécessaire, ou que la capacité détenue est explicitement l’objectif :
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id-or-slug>
|
||||
pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
|
||||
pnpm crabbox:stop -- <cbx_id-or-slug>
|
||||
```
|
||||
|
||||
`.crabbox.yaml` détient les valeurs par défaut de fournisseur, de synchronisation et d’hydratation GitHub Actions pour les lanes owned-cloud. Il exclut le `.git` local afin que le checkout Actions hydraté conserve ses propres métadonnées Git distantes au lieu de synchroniser les remotes et magasins d’objets locaux du mainteneur, et il exclut les artefacts locaux d’exécution/de build qui ne doivent jamais être transférés. `.github/workflows/crabbox-hydrate.yml` détient le checkout, la configuration Node/pnpm, la récupération de `origin/main` et le transfert d’environnement non secret pour les commandes owned-cloud `crabbox run --id <cbx_id>`.
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Vue d’ensemble de l’installation](/fr/install)
|
||||
- [Canaux de développement](/fr/install/development-channels)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez installer ou gérer des plugins Gateway ou des paquets compatibles
|
||||
- Vous souhaitez déboguer les échecs de chargement des Plugins
|
||||
- Vous voulez installer ou gérer des plugins Gateway ou des bundles compatibles
|
||||
- Vous voulez déboguer les échecs de chargement des Plugins
|
||||
sidebarTitle: Plugins
|
||||
summary: Référence CLI pour `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
summary: Référence CLI pour `openclaw plugins` (liste, installation, place de marché, désinstallation, activation/désactivation, diagnostic)
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:29:28Z"
|
||||
generated_at: "2026-05-04T07:03:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d854d052b0a012a86f9c775775676a9a8fe8ae86b2c38a18118f1abf0732174c
|
||||
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,19 +17,19 @@ x-i18n:
|
||||
Gérer les plugins Gateway, les packs de hooks et les bundles compatibles.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugin system" href="/fr/tools/plugin">
|
||||
Guide utilisateur final pour installer, activer et dépanner les plugins.
|
||||
<Card title="Système de Plugin" href="/fr/tools/plugin">
|
||||
Guide utilisateur pour installer, activer et dépanner les plugins.
|
||||
</Card>
|
||||
<Card title="Manage plugins" href="/fr/plugins/manage-plugins">
|
||||
<Card title="Gérer les plugins" href="/fr/plugins/manage-plugins">
|
||||
Exemples rapides pour installer, lister, mettre à jour, désinstaller et publier.
|
||||
</Card>
|
||||
<Card title="Plugin bundles" href="/fr/plugins/bundles">
|
||||
<Card title="Bundles de Plugin" href="/fr/plugins/bundles">
|
||||
Modèle de compatibilité des bundles.
|
||||
</Card>
|
||||
<Card title="Plugin manifest" href="/fr/plugins/manifest">
|
||||
<Card title="Manifeste de Plugin" href="/fr/plugins/manifest">
|
||||
Champs du manifeste et schéma de configuration.
|
||||
</Card>
|
||||
<Card title="Security" href="/fr/gateway/security">
|
||||
<Card title="Sécurité" href="/fr/gateway/security">
|
||||
Renforcement de la sécurité pour les installations de plugins.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -62,14 +62,12 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
Pour examiner une installation, une inspection, une désinstallation ou une actualisation de registre lente, exécutez la
|
||||
commande avec `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. La trace écrit les temps des phases
|
||||
sur stderr et garde la sortie JSON analysable. Consultez [Débogage](/fr/help/debugging#plugin-lifecycle-trace).
|
||||
Pour examiner une installation, une inspection, une désinstallation ou une actualisation de registre lente, exécutez la commande avec `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. La trace écrit les durées des phases dans stderr et conserve une sortie JSON analysable. Consultez [Débogage](/fr/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
Les plugins groupés sont fournis avec OpenClaw. Certains sont activés par défaut (par exemple les fournisseurs de modèles groupés, les fournisseurs de synthèse vocale groupés et le plugin de navigateur groupé) ; d’autres nécessitent `plugins enable`.
|
||||
Les plugins groupés sont livrés avec OpenClaw. Certains sont activés par défaut (par exemple les fournisseurs de modèles groupés, les fournisseurs de synthèse vocale groupés et le plugin de navigateur groupé) ; d’autres nécessitent `plugins enable`.
|
||||
|
||||
Les plugins OpenClaw natifs doivent fournir `openclaw.plugin.json` avec un schéma JSON en ligne (`configSchema`, même vide). Les bundles compatibles utilisent plutôt leurs propres manifestes de bundle.
|
||||
Les plugins OpenClaw natifs doivent livrer `openclaw.plugin.json` avec un schéma JSON en ligne (`configSchema`, même vide). Les bundles compatibles utilisent plutôt leurs propres manifestes de bundle.
|
||||
|
||||
`plugins list` affiche `Format: openclaw` ou `Format: bundle`. La sortie détaillée de list/info affiche aussi le sous-type du bundle (`codex`, `claude` ou `cursor`) ainsi que les capacités de bundle détectées.
|
||||
</Note>
|
||||
@ -93,71 +91,63 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Les noms de paquets nus s’installent depuis npm par défaut pendant la transition de lancement. Utilisez `clawhub:<package>` pour ClawHub. Traitez les installations de plugins comme l’exécution de code. Préférez les versions épinglées.
|
||||
Les noms de packages nus s’installent depuis npm par défaut pendant la transition de lancement. Utilisez `clawhub:<package>` pour ClawHub. Traitez les installations de plugins comme l’exécution de code. Préférez les versions épinglées.
|
||||
</Warning>
|
||||
|
||||
`plugins search` interroge ClawHub pour trouver des paquets de plugins installables et affiche
|
||||
des noms de paquets prêts à installer. La recherche porte sur les paquets de plugins de code et de plugins de bundle,
|
||||
pas sur les Skills. Utilisez `openclaw skills search` pour les Skills ClawHub.
|
||||
`plugins search` interroge ClawHub pour trouver des packages de plugins installables et affiche des noms de packages prêts à installer. La recherche porte sur les packages de plugins de code et de plugins de bundle, pas sur les Skills. Utilisez `openclaw skills search` pour les Skills ClawHub.
|
||||
|
||||
<Note>
|
||||
ClawHub est la principale surface de distribution et de découverte pour la plupart des plugins. Npm
|
||||
reste une solution de secours prise en charge et une voie d’installation directe. Les paquets de plugins
|
||||
`@openclaw/*` détenus par OpenClaw sont de nouveau publiés sur npm ; consultez la liste actuelle
|
||||
sur [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou
|
||||
[l’inventaire des plugins](/fr/plugins/plugin-inventory). Les installations stables utilisent `latest`.
|
||||
Les installations et mises à jour du canal bêta préfèrent le dist-tag npm `beta` lorsque cette balise
|
||||
est disponible, puis se rabattent sur `latest`.
|
||||
ClawHub est la principale surface de distribution et de découverte pour la plupart des plugins. Npm reste une solution de repli prise en charge et un chemin d’installation directe. Les packages de plugins `@openclaw/*` appartenant à OpenClaw sont de nouveau publiés sur npm ; consultez la liste actuelle sur [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou l’[inventaire des plugins](/fr/plugins/plugin-inventory). Les installations stables utilisent `latest`. Les installations et mises à jour du canal bêta privilégient le dist-tag npm `beta` lorsque cette étiquette est disponible, puis se rabattent sur `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Config includes and invalid-config repair">
|
||||
Si votre section `plugins` est adossée à un `$include` fichier unique, `plugins install/update/enable/disable/uninstall` écrit dans ce fichier inclus et laisse `openclaw.json` intact. Les includes racine, les tableaux d’includes et les includes avec des remplacements voisins échouent de manière fermée au lieu d’être aplatis. Consultez [Includes de configuration](/fr/gateway/configuration) pour les formes prises en charge.
|
||||
<Accordion title="Inclus de configuration et réparation des configurations invalides">
|
||||
Si votre section `plugins` repose sur un `$include` à fichier unique, `plugins install/update/enable/disable/uninstall` écrit dans ce fichier inclus et laisse `openclaw.json` intact. Les inclus racine, les tableaux d’inclus et les inclus avec remplacements voisins échouent de manière fermée au lieu d’être aplatis. Consultez [Inclus de configuration](/fr/gateway/configuration) pour les formes prises en charge.
|
||||
|
||||
Si la configuration est invalide pendant l’installation, `plugins install` échoue normalement de manière fermée et vous indique d’exécuter d’abord `openclaw doctor --fix`. Au démarrage du Gateway et lors du rechargement à chaud, une configuration de plugin invalide échoue de manière fermée comme toute autre configuration invalide ; `openclaw doctor --fix` peut mettre en quarantaine l’entrée de plugin invalide. La seule exception documentée au moment de l’installation est un chemin de récupération étroit pour plugins groupés, réservé aux plugins qui optent explicitement pour `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Si la configuration est invalide pendant l’installation, `plugins install` échoue normalement de manière fermée et vous indique d’exécuter d’abord `openclaw doctor --fix`. Pendant le démarrage du Gateway et le rechargement à chaud, une configuration de plugin invalide échoue de manière fermée comme toute autre configuration invalide ; `openclaw doctor --fix` peut mettre en quarantaine l’entrée de plugin invalide. La seule exception documentée au moment de l’installation est un chemin de récupération étroit pour plugin groupé destiné aux plugins qui optent explicitement pour `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force and reinstall vs update">
|
||||
`--force` réutilise la cible d’installation existante et remplace sur place un plugin ou un pack de hooks déjà installé. Utilisez-le lorsque vous réinstallez intentionnellement le même identifiant depuis un nouveau chemin local, une archive, un paquet ClawHub ou un artefact npm. Pour les mises à niveau courantes d’un plugin npm déjà suivi, préférez `openclaw plugins update <id-or-npm-spec>`.
|
||||
<Accordion title="--force et réinstallation ou mise à jour">
|
||||
`--force` réutilise la cible d’installation existante et écrase sur place un plugin ou un pack de hooks déjà installé. Utilisez-le lorsque vous réinstallez intentionnellement le même identifiant depuis un nouveau chemin local, une archive, un package ClawHub ou un artefact npm. Pour les mises à niveau courantes d’un plugin npm déjà suivi, préférez `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Si vous exécutez `plugins install` pour un identifiant de plugin déjà installé, OpenClaw s’arrête et vous dirige vers `plugins update <id-or-npm-spec>` pour une mise à niveau normale, ou vers `plugins install <package> --force` lorsque vous voulez réellement remplacer l’installation actuelle depuis une autre source.
|
||||
Si vous exécutez `plugins install` pour un identifiant de plugin déjà installé, OpenClaw s’arrête et vous renvoie vers `plugins update <id-or-npm-spec>` pour une mise à niveau normale, ou vers `plugins install <package> --force` lorsque vous voulez réellement écraser l’installation actuelle depuis une autre source.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--pin scope">
|
||||
`--pin` s’applique uniquement aux installations npm. Il n’est pas pris en charge avec les installations `git:` ; utilisez une référence git explicite comme `git:github.com/acme/plugin@v1.2.3` lorsque vous voulez une source épinglée. Il n’est pas pris en charge avec `--marketplace`, car les installations marketplace conservent les métadonnées de source marketplace au lieu d’une spec npm.
|
||||
<Accordion title="Portée de --pin">
|
||||
`--pin` s’applique uniquement aux installations npm. Il n’est pas pris en charge avec les installations `git:` ; utilisez une référence git explicite telle que `git:github.com/acme/plugin@v1.2.3` lorsque vous voulez une source épinglée. Il n’est pas pris en charge avec `--marketplace`, car les installations marketplace conservent les métadonnées de source marketplace au lieu d’une spécification npm.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` est une option de dernier recours pour les faux positifs dans l’analyseur de code dangereux intégré. Elle permet à l’installation de continuer même lorsque l’analyseur intégré signale des résultats `critical`, mais elle ne contourne **pas** les blocages de politique des hooks `before_install` du plugin et ne contourne **pas** les échecs d’analyse.
|
||||
`--dangerously-force-unsafe-install` est une option d’urgence pour les faux positifs du scanner de code dangereux intégré. Elle permet à l’installation de continuer même lorsque le scanner intégré signale des résultats `critical`, mais elle ne contourne **pas** les blocages de politique du hook `before_install` du plugin et ne contourne **pas** les échecs d’analyse.
|
||||
|
||||
Ce flag CLI s’applique aux flux d’installation/mise à jour de plugins. Les installations de dépendances de Skills adossées au Gateway utilisent le remplacement de requête correspondant `dangerouslyForceUnsafeInstall`, tandis que `openclaw skills install` reste un flux séparé de téléchargement/installation de Skills ClawHub.
|
||||
Cet indicateur CLI s’applique aux flux d’installation/mise à jour de plugins. Les installations de dépendances de Skills adossées au Gateway utilisent le remplacement de requête correspondant `dangerouslyForceUnsafeInstall`, tandis que `openclaw skills install` reste un flux séparé de téléchargement/installation de Skills ClawHub.
|
||||
|
||||
Si un plugin que vous avez publié sur ClawHub est bloqué par une analyse de registre, utilisez les étapes de publication dans [ClawHub](/fr/tools/clawhub).
|
||||
Si un plugin que vous avez publié sur ClawHub est bloqué par une analyse de registre, utilisez les étapes éditeur dans [ClawHub](/fr/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hook packs and npm specs">
|
||||
`plugins install` est aussi la surface d’installation des packs de hooks qui exposent `openclaw.hooks` dans `package.json`. Utilisez `openclaw hooks` pour une visibilité filtrée des hooks et l’activation par hook, pas pour l’installation de paquets.
|
||||
<Accordion title="Packs de hooks et spécifications npm">
|
||||
`plugins install` est aussi la surface d’installation pour les packs de hooks qui exposent `openclaw.hooks` dans `package.json`. Utilisez `openclaw hooks` pour une visibilité filtrée des hooks et l’activation par hook, pas pour l’installation de packages.
|
||||
|
||||
Les specs npm sont **uniquement registre** (nom de paquet + **version exacte** ou **dist-tag** facultatif). Les specs Git/URL/fichier et les plages semver sont rejetées. Les installations de dépendances s’exécutent localement au projet avec `--ignore-scripts` pour la sécurité, même lorsque votre shell a des paramètres globaux d’installation npm.
|
||||
Les spécifications npm sont **réservées au registre** (nom de package + **version exacte** facultative ou **dist-tag**). Les spécifications Git/URL/fichier et les plages semver sont rejetées. Les installations de dépendances s’exécutent localement au projet avec `--ignore-scripts` pour la sécurité, même lorsque votre shell dispose de paramètres d’installation npm globaux.
|
||||
|
||||
Utilisez `npm:<package>` lorsque vous voulez rendre la résolution npm explicite. Les specs de paquets nues s’installent aussi directement depuis npm pendant la transition de lancement.
|
||||
Utilisez `npm:<package>` lorsque vous voulez rendre la résolution npm explicite. Les spécifications de package nues s’installent aussi directement depuis npm pendant la transition de lancement.
|
||||
|
||||
Les specs nues et `@latest` restent sur le canal stable. Si npm résout l’une d’elles vers une préversion, OpenClaw s’arrête et vous demande d’opter explicitement avec une balise de préversion comme `@beta`/`@rc` ou une version de préversion exacte comme `@1.2.3-beta.4`.
|
||||
Les spécifications nues et `@latest` restent sur la piste stable. Les versions correctives OpenClaw datées telles que `2026.5.3-1` sont des versions stables pour cette vérification. Si npm résout l’une d’elles en préversion, OpenClaw s’arrête et vous demande d’opter explicitement pour une étiquette de préversion telle que `@beta`/`@rc` ou pour une version de préversion exacte telle que `@1.2.3-beta.4`.
|
||||
|
||||
Si une spec d’installation nue correspond à un identifiant officiel de plugin (par exemple `diffs`), OpenClaw installe directement l’entrée du catalogue. Pour installer un paquet npm portant le même nom, utilisez une spec scoped explicite (par exemple `@scope/diffs`).
|
||||
Si une spécification d’installation nue correspond à un identifiant de plugin officiel (par exemple `diffs`), OpenClaw installe directement l’entrée du catalogue. Pour installer un package npm portant le même nom, utilisez une spécification à portée explicite (par exemple `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Git repositories">
|
||||
Utilisez `git:<repo>` pour installer directement depuis un dépôt git. Les formes prises en charge incluent `git:github.com/owner/repo`, `git:owner/repo`, les URL de clonage complètes `https://`, `ssh://`, `git://`, `file://` et `git@host:owner/repo.git`. Ajoutez `@<ref>` ou `#<ref>` pour extraire une branche, une balise ou un commit avant l’installation.
|
||||
<Accordion title="Dépôts Git">
|
||||
Utilisez `git:<repo>` pour installer directement depuis un dépôt git. Les formes prises en charge incluent `git:github.com/owner/repo`, `git:owner/repo`, les URL de clonage complètes `https://`, `ssh://`, `git://`, `file://` et `git@host:owner/repo.git`. Ajoutez `@<ref>` ou `#<ref>` pour extraire une branche, une étiquette ou un commit avant l’installation.
|
||||
|
||||
Les installations Git clonent dans un répertoire temporaire, extraient la référence demandée lorsqu’elle est présente, puis utilisent l’installateur normal de répertoire de plugin. Cela signifie que la validation du manifeste, l’analyse de code dangereux, le travail d’installation du gestionnaire de paquets et les enregistrements d’installation se comportent comme pour les installations npm. Les installations git enregistrées incluent l’URL/la référence source ainsi que le commit résolu afin que `openclaw plugins update` puisse résoudre de nouveau la source plus tard.
|
||||
Les installations Git clonent dans un répertoire temporaire, extraient la référence demandée lorsqu’elle est présente, puis utilisent l’installateur de répertoire de plugin normal. Cela signifie que la validation du manifeste, l’analyse de code dangereux, le travail d’installation du gestionnaire de packages et les enregistrements d’installation se comportent comme pour les installations npm. Les installations git enregistrées incluent l’URL/la référence source plus le commit résolu afin que `openclaw plugins update` puisse résoudre de nouveau la source ultérieurement.
|
||||
|
||||
Après une installation depuis git, utilisez `openclaw plugins inspect <id> --runtime --json` pour vérifier les enregistrements d’exécution comme les méthodes du Gateway et les commandes CLI. Si le plugin a enregistré une racine CLI avec `api.registerCli`, exécutez cette commande directement via la CLI racine OpenClaw, par exemple `openclaw demo-plugin ping`.
|
||||
Après une installation depuis git, utilisez `openclaw plugins inspect <id> --runtime --json` pour vérifier les enregistrements runtime tels que les méthodes Gateway et les commandes CLI. Si le plugin a enregistré une racine CLI avec `api.registerCli`, exécutez cette commande directement via la CLI racine OpenClaw, par exemple `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Archives">
|
||||
Archives prises en charge : `.zip`, `.tgz`, `.tar.gz`, `.tar`. Les archives de plugins OpenClaw natifs doivent contenir un `openclaw.plugin.json` valide à la racine du plugin extrait ; les archives qui contiennent seulement `package.json` sont rejetées avant qu’OpenClaw n’écrive les enregistrements d’installation.
|
||||
Archives prises en charge : `.zip`, `.tgz`, `.tar.gz`, `.tar`. Les archives de plugins OpenClaw natifs doivent contenir un `openclaw.plugin.json` valide à la racine du plugin extrait ; les archives qui ne contiennent que `package.json` sont rejetées avant qu’OpenClaw n’écrive les enregistrements d’installation.
|
||||
|
||||
Les installations depuis la marketplace Claude sont également prises en charge.
|
||||
Les installations marketplace Claude sont également prises en charge.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -169,21 +159,21 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Les specs de plugins nues compatibles npm s’installent depuis npm par défaut pendant la transition de lancement :
|
||||
Les spécifications de plugins nues compatibles npm s’installent depuis npm par défaut pendant la transition de lancement :
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
Utilisez `npm:` pour rendre la résolution npm uniquement explicite :
|
||||
Utilisez `npm:` pour rendre explicite la résolution limitée à npm :
|
||||
|
||||
```bash
|
||||
openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw vérifie la compatibilité annoncée de l’API du plugin / Gateway minimal avant l’installation. Lorsque la version ClawHub sélectionnée publie un artefact ClawPack, OpenClaw télécharge le `.tgz` npm-pack versionné, vérifie l’en-tête de digest ClawHub et le digest de l’artefact, puis l’installe via le chemin d’archive normal. Les anciennes versions ClawHub sans métadonnées ClawPack s’installent encore via l’ancien chemin de vérification d’archive de paquet. Les installations enregistrées conservent leurs métadonnées de source ClawHub, le type d’artefact, l’intégrité npm, le shasum npm, le nom du tarball et les faits de digest ClawPack pour les mises à jour ultérieures.
|
||||
Les installations ClawHub sans version conservent une spec enregistrée sans version afin que `openclaw plugins update` puisse suivre les nouvelles versions ClawHub ; les sélecteurs explicites de version ou de balise comme `clawhub:pkg@1.2.3` et `clawhub:pkg@beta` restent épinglés à ce sélecteur.
|
||||
OpenClaw vérifie la compatibilité annoncée de l’API de plugin / Gateway minimal avant l’installation. Lorsque la version ClawHub sélectionnée publie un artefact ClawPack, OpenClaw télécharge le `.tgz` versionné du npm-pack, vérifie l’en-tête de condensat ClawHub et le condensat de l’artefact, puis l’installe via le chemin d’archive normal. Les anciennes versions ClawHub sans métadonnées ClawPack s’installent toujours via l’ancien chemin de vérification d’archive de package. Les installations enregistrées conservent leurs métadonnées de source ClawHub, le type d’artefact, l’intégrité npm, le shasum npm, le nom du tarball et les informations de condensat ClawPack pour les mises à jour ultérieures.
|
||||
Les installations ClawHub sans version conservent une spécification enregistrée sans version afin que `openclaw plugins update` puisse suivre les versions ClawHub plus récentes ; les sélecteurs explicites de version ou d’étiquette tels que `clawhub:pkg@1.2.3` et `clawhub:pkg@beta` restent épinglés à ce sélecteur.
|
||||
|
||||
#### Raccourci marketplace
|
||||
|
||||
@ -204,31 +194,31 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Sources de marketplace">
|
||||
- un nom de marketplace Claude connu issu de `~/.claude/plugins/known_marketplaces.json`
|
||||
- une racine de marketplace locale ou un chemin `marketplace.json`
|
||||
- un raccourci de dépôt GitHub comme `owner/repo`
|
||||
- une URL de dépôt GitHub comme `https://github.com/owner/repo`
|
||||
<Tab title="Sources de place de marché">
|
||||
- un nom de place de marché Claude connu depuis `~/.claude/plugins/known_marketplaces.json`
|
||||
- une racine de place de marché locale ou un chemin `marketplace.json`
|
||||
- un raccourci de dépôt GitHub tel que `owner/repo`
|
||||
- une URL de dépôt GitHub telle que `https://github.com/owner/repo`
|
||||
- une URL git
|
||||
|
||||
</Tab>
|
||||
<Tab title="Règles de marketplace distant">
|
||||
Pour les marketplaces distants chargés depuis GitHub ou git, les entrées de plugins doivent rester dans le dépôt de marketplace cloné. OpenClaw accepte les sources par chemin relatif depuis ce dépôt et rejette les sources de plugins HTTP(S), à chemin absolu, git, GitHub et autres sources non basées sur des chemins provenant de manifestes distants.
|
||||
<Tab title="Règles des places de marché distantes">
|
||||
Pour les places de marché distantes chargées depuis GitHub ou git, les entrées de plugin doivent rester dans le dépôt de place de marché cloné. OpenClaw accepte les sources avec chemin relatif depuis ce dépôt et rejette les sources de plugin HTTP(S), avec chemin absolu, git, GitHub et autres sources de plugin qui ne sont pas des chemins depuis les manifestes distants.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Pour les chemins locaux et les archives, OpenClaw détecte automatiquement :
|
||||
|
||||
- les plugins OpenClaw natifs (`openclaw.plugin.json`)
|
||||
- les bundles compatibles Codex (`.codex-plugin/plugin.json`)
|
||||
- les bundles compatibles Claude (`.claude-plugin/plugin.json` ou la disposition de composants Claude par défaut)
|
||||
- les bundles compatibles Cursor (`.cursor-plugin/plugin.json`)
|
||||
- les bundles compatibles avec Codex (`.codex-plugin/plugin.json`)
|
||||
- les bundles compatibles avec Claude (`.claude-plugin/plugin.json` ou la disposition de composants Claude par défaut)
|
||||
- les bundles compatibles avec Cursor (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
Les bundles compatibles s’installent dans la racine normale des plugins et participent au même flux list/info/enable/disable. Aujourd’hui, les Skills de bundle, les command-skills Claude, les valeurs par défaut Claude de `settings.json`, les valeurs par défaut Claude de `.lsp.json` / `lspServers` déclarées par le manifeste, les command-skills Cursor et les répertoires de hooks compatibles Codex sont pris en charge ; les autres capacités de bundle détectées sont affichées dans les diagnostics/info mais ne sont pas encore raccordées à l’exécution runtime.
|
||||
Les bundles compatibles s’installent dans la racine normale des plugins et participent au même flux list/info/enable/disable. Aujourd’hui, les skills de bundle, les command-skills Claude, les valeurs par défaut Claude `settings.json`, les valeurs par défaut Claude `.lsp.json` / `lspServers` déclarées dans le manifeste, les command-skills Cursor et les répertoires de hooks Codex compatibles sont pris en charge ; les autres capacités de bundle détectées sont affichées dans les diagnostics/info, mais ne sont pas encore connectées à l’exécution runtime.
|
||||
</Note>
|
||||
|
||||
### Lister
|
||||
### Liste
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
@ -241,30 +231,41 @@ openclaw plugins search <query> --json
|
||||
```
|
||||
|
||||
<ParamField path="--enabled" type="boolean">
|
||||
Afficher uniquement les plugins activés.
|
||||
Affiche uniquement les plugins activés.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Passer de la vue en tableau à des lignes de détail par plugin avec les métadonnées source/origine/version/activation.
|
||||
Passe de la vue tableau à des lignes de détail par plugin avec les métadonnées de source/origine/version/activation.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Inventaire lisible par machine, avec diagnostics du registre et état d’installation des dépendances de package.
|
||||
Inventaire lisible par machine avec diagnostics du registre et état d’installation des dépendances de package.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` lit d’abord le registre local persistant des plugins, avec un repli dérivé uniquement du manifeste lorsque le registre est manquant ou invalide. Il est utile pour vérifier si un plugin est installé, activé et visible pour la planification du démarrage à froid, mais ce n’est pas une sonde runtime live d’un processus Gateway déjà en cours d’exécution. Après avoir modifié le code d’un plugin, son activation, la politique des hooks ou `plugins.load.paths`, redémarrez le Gateway qui sert le canal avant d’attendre l’exécution du nouveau code `register(api)` ou des hooks. Pour les déploiements distants/conteneurisés, vérifiez que vous redémarrez bien l’enfant `openclaw gateway run` réel, et pas seulement un processus wrapper.
|
||||
`plugins list` lit d’abord le registre de plugins local persistant, avec un repli dérivé uniquement du manifeste lorsque le registre est manquant ou invalide. Cette commande est utile pour vérifier si un plugin est installé, activé et visible par la planification du démarrage à froid, mais ce n’est pas une sonde runtime en direct d’un processus Gateway déjà en cours d’exécution. Après avoir modifié le code d’un plugin, son activation, la politique de hooks ou `plugins.load.paths`, redémarrez le Gateway qui sert le canal avant de vous attendre à ce que le nouveau code `register(api)` ou les hooks s’exécutent. Pour les déploiements distants/conteneurisés, vérifiez que vous redémarrez bien l’enfant `openclaw gateway run` réel, et pas seulement un processus wrapper.
|
||||
|
||||
`plugins list --json` inclut le `dependencyStatus` de chaque plugin depuis les `dependencies` et `optionalDependencies` de `package.json`. OpenClaw vérifie si ces noms de packages sont présents le long du chemin de recherche Node `node_modules` normal du plugin ; il n’importe pas le code runtime du plugin, n’exécute pas de gestionnaire de packages et ne répare pas les dépendances manquantes.
|
||||
`plugins list --json` inclut le `dependencyStatus` de chaque plugin depuis les
|
||||
`dependencies` et `optionalDependencies` de `package.json`. OpenClaw vérifie si ces noms de package
|
||||
sont présents le long du chemin de recherche Node `node_modules` normal du plugin ; il
|
||||
n’importe pas le code runtime du plugin, n’exécute pas de gestionnaire de packages et ne répare pas les
|
||||
dépendances manquantes.
|
||||
</Note>
|
||||
|
||||
`plugins search` est une recherche dans le catalogue distant ClawHub. Elle n’inspecte pas l’état local, ne modifie pas la configuration, n’installe pas de packages et ne charge pas le code runtime des plugins. Les résultats de recherche incluent le nom de package ClawHub, la famille, le canal, la version, le résumé et une indication d’installation comme `openclaw plugins install clawhub:<package>`.
|
||||
`plugins search` est une recherche distante dans le catalogue ClawHub. Cette commande n’inspecte pas l’état
|
||||
local, ne modifie pas la configuration, n’installe pas de packages et ne charge pas le code runtime du plugin. Les
|
||||
résultats de recherche incluent le nom du package ClawHub, la famille, le canal, la version, le résumé et
|
||||
une indication d’installation telle que `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
Pour travailler sur un plugin groupé dans une image Docker packagée, montez par bind mount le répertoire source du plugin par-dessus le chemin source packagé correspondant, comme `/app/extensions/synology-chat`. OpenClaw découvrira cette superposition de source montée avant `/app/dist/extensions/synology-chat` ; un simple répertoire source copié reste inerte, de sorte que les installations packagées normales utilisent toujours le dist compilé.
|
||||
Pour travailler sur un plugin groupé dans une image Docker packagée, montez en bind le répertoire source
|
||||
du plugin par-dessus le chemin source packagé correspondant, par exemple
|
||||
`/app/extensions/synology-chat`. OpenClaw découvrira cette surcouche source montée
|
||||
avant `/app/dist/extensions/synology-chat` ; un répertoire source simplement copié
|
||||
reste inerte afin que les installations packagées normales utilisent toujours le dist compilé.
|
||||
|
||||
Pour déboguer les hooks runtime :
|
||||
Pour le débogage des hooks runtime :
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` affiche les hooks enregistrés et les diagnostics issus d’une passe d’inspection avec chargement de module. L’inspection runtime n’installe jamais de dépendances ; utilisez `openclaw doctor --fix` pour nettoyer l’état des dépendances héritées ou installer les plugins téléchargeables configurés manquants.
|
||||
- `openclaw gateway status --deep --require-rpc` confirme le Gateway joignable, les indications de service/processus, le chemin de configuration et l’état de santé RPC.
|
||||
- Les hooks de conversation non groupés (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigent `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- `openclaw plugins inspect <id> --runtime --json` affiche les hooks enregistrés et les diagnostics issus d’une passe d’inspection avec module chargé. L’inspection runtime n’installe jamais de dépendances ; utilisez `openclaw doctor --fix` pour nettoyer l’état des dépendances héritées ou installer les plugins téléchargeables configurés manquants.
|
||||
- `openclaw gateway status --deep --require-rpc` confirme le Gateway joignable, les indications de service/processus, le chemin de configuration et l’état RPC.
|
||||
- Les hooks de conversation non groupés (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) nécessitent `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Utilisez `--link` pour éviter de copier un répertoire local (ajoute à `plugins.load.paths`) :
|
||||
|
||||
@ -278,13 +279,13 @@ openclaw plugins install -l ./my-plugin
|
||||
Utilisez `--pin` sur les installations npm pour enregistrer la spécification exacte résolue (`name@version`) dans l’index des plugins gérés, tout en conservant le comportement par défaut non épinglé.
|
||||
</Note>
|
||||
|
||||
### Index des plugins
|
||||
### Index des Plugins
|
||||
|
||||
Les métadonnées d’installation des Plugins sont un état géré par la machine, pas une configuration utilisateur. Les installations et mises à jour les écrivent dans `plugins/installs.json` sous le répertoire d’état OpenClaw actif. Sa carte de premier niveau `installRecords` est la source durable des métadonnées d’installation, y compris les enregistrements pour les manifestes de plugins cassés ou manquants. Le tableau `plugins` est le cache de registre à froid dérivé du manifeste. Le fichier inclut un avertissement de ne pas le modifier et est utilisé par `openclaw plugins update`, la désinstallation, les diagnostics et le registre à froid des plugins.
|
||||
Les métadonnées d’installation de Plugin sont un état géré par machine, pas une configuration utilisateur. Les installations et mises à jour les écrivent dans `plugins/installs.json` sous le répertoire d’état OpenClaw actif. Sa carte de premier niveau `installRecords` est la source durable des métadonnées d’installation, y compris les enregistrements pour les manifestes de plugin cassés ou manquants. Le tableau `plugins` est le cache de registre à froid dérivé du manifeste. Le fichier inclut un avertissement de ne pas modifier et est utilisé par `openclaw plugins update`, la désinstallation, les diagnostics et le registre de plugins à froid.
|
||||
|
||||
Quand OpenClaw voit dans la configuration des enregistrements hérités livrés `plugins.installs`, il les déplace vers l’index des plugins et supprime la clé de configuration ; si l’une des écritures échoue, les enregistrements de configuration sont conservés afin que les métadonnées d’installation ne soient pas perdues.
|
||||
Quand OpenClaw voit des enregistrements hérités livrés `plugins.installs` dans la configuration, il les déplace dans l’index des plugins et supprime la clé de configuration ; si l’une des écritures échoue, les enregistrements de configuration sont conservés afin que les métadonnées d’installation ne soient pas perdues.
|
||||
|
||||
### Désinstaller
|
||||
### Désinstallation
|
||||
|
||||
```bash
|
||||
openclaw plugins uninstall <id>
|
||||
@ -292,13 +293,13 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` supprime les enregistrements de plugin de `plugins.entries`, de l’index persistant des plugins, des entrées de liste d’autorisation/refus de plugins et, le cas échéant, des entrées liées de `plugins.load.paths`. Sauf si `--keep-files` est défini, la désinstallation supprime aussi le répertoire d’installation géré suivi lorsqu’il se trouve dans la racine des extensions de plugins d’OpenClaw. Pour les plugins Active Memory, l’emplacement mémoire est réinitialisé à `memory-core`.
|
||||
`uninstall` supprime les enregistrements de plugin de `plugins.entries`, de l’index de plugins persistant, des entrées de listes allow/deny de plugin et des entrées liées `plugins.load.paths` lorsque cela s’applique. Sauf si `--keep-files` est défini, la désinstallation supprime aussi le répertoire d’installation géré suivi lorsqu’il se trouve dans la racine des extensions de plugins d’OpenClaw. Pour les plugins de mémoire active, l’emplacement mémoire est réinitialisé à `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` est pris en charge comme alias déprécié de `--keep-files`.
|
||||
`--keep-config` est pris en charge comme alias obsolète de `--keep-files`.
|
||||
</Note>
|
||||
|
||||
### Mettre à jour
|
||||
### Mise à jour
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id-or-npm-spec>
|
||||
@ -316,25 +317,25 @@ Les mises à jour s’appliquent aux installations de plugins suivies dans l’i
|
||||
|
||||
Pour les installations npm, vous pouvez aussi passer une spécification de package npm explicite avec un dist-tag ou une version exacte. OpenClaw résout ce nom de package vers l’enregistrement de plugin suivi, met à jour ce plugin installé et enregistre la nouvelle spécification npm pour les futures mises à jour basées sur l’identifiant.
|
||||
|
||||
Passer le nom du package npm sans version ni tag résout également vers l’enregistrement de plugin suivi. Utilisez cela lorsqu’un plugin était épinglé à une version exacte et que vous voulez le ramener vers la ligne de publication par défaut du registre.
|
||||
Passer le nom du package npm sans version ni tag se résout aussi vers l’enregistrement de plugin suivi. Utilisez cette option lorsqu’un plugin était épinglé à une version exacte et que vous voulez le ramener vers la ligne de publication par défaut du registre.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Mises à jour du canal bêta">
|
||||
`openclaw plugins update` réutilise la spécification de plugin suivie sauf si vous passez une nouvelle spécification. `openclaw update` connaît en plus le canal de mise à jour OpenClaw actif : sur le canal bêta, les enregistrements de plugins npm et ClawHub sur la ligne par défaut essaient d’abord `@beta`, puis se rabattent sur la spécification default/latest enregistrée si aucune publication bêta du plugin n’existe. Les versions exactes et tags explicites restent épinglés à ce sélecteur.
|
||||
`openclaw plugins update` réutilise la spécification de plugin suivie sauf si vous passez une nouvelle spécification. `openclaw update` connaît en plus le canal de mise à jour OpenClaw actif : sur le canal bêta, les enregistrements de plugins npm et ClawHub sur la ligne par défaut essaient d’abord `@beta`, puis se replient sur la spécification default/latest enregistrée si aucune publication bêta de plugin n’existe. Les versions exactes et les tags explicites restent épinglés à ce sélecteur.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Contrôles de version et dérive d’intégrité">
|
||||
Avant une mise à jour npm live, OpenClaw vérifie la version du package installé par rapport aux métadonnées du registre npm. Si la version installée et l’identité d’artefact enregistrée correspondent déjà à la cible résolue, la mise à jour est ignorée sans téléchargement, réinstallation ni réécriture de `openclaw.json`.
|
||||
<Accordion title="Vérifications de version et dérive d’intégrité">
|
||||
Avant une mise à jour npm en direct, OpenClaw vérifie la version du package installé par rapport aux métadonnées du registre npm. Si la version installée et l’identité d’artefact enregistrée correspondent déjà à la cible résolue, la mise à jour est ignorée sans téléchargement, réinstallation ni réécriture de `openclaw.json`.
|
||||
|
||||
Lorsqu’un hash d’intégrité stocké existe et que le hash de l’artefact récupéré change, OpenClaw traite cela comme une dérive d’artefact npm. La commande interactive `openclaw plugins update` affiche les hash attendus et réels, puis demande confirmation avant de poursuivre. Les assistants de mise à jour non interactifs échouent en mode fermé sauf si l’appelant fournit une politique de continuation explicite.
|
||||
Lorsqu’un hachage d’intégrité stocké existe et que le hachage de l’artefact récupéré change, OpenClaw traite cela comme une dérive d’artefact npm. La commande interactive `openclaw plugins update` affiche les hachages attendu et réel et demande confirmation avant de continuer. Les assistants de mise à jour non interactifs échouent fermés sauf si l’appelant fournit une politique de continuation explicite.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install lors de la mise à jour">
|
||||
`--dangerously-force-unsafe-install` est aussi disponible sur `plugins update` comme dérogation de dernier recours pour les faux positifs de l’analyse intégrée de code dangereux pendant les mises à jour de plugins. Il ne contourne toujours pas les blocages de politique `before_install` des plugins ni le blocage en cas d’échec de l’analyse, et il ne s’applique qu’aux mises à jour de plugins, pas aux mises à jour de packs de hooks.
|
||||
`--dangerously-force-unsafe-install` est aussi disponible sur `plugins update` comme dérogation de dernier recours pour les faux positifs de l’analyse de code dangereux intégrée pendant les mises à jour de plugins. Cette option ne contourne toujours pas les blocages de politique `before_install` du plugin ni le blocage sur échec d’analyse, et elle ne s’applique qu’aux mises à jour de plugins, pas aux mises à jour de packs de hooks.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Inspecter
|
||||
### Inspection
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <id>
|
||||
@ -342,21 +343,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Inspecter affiche l’identité, l’état de chargement, la source, les capacités du manifeste, les indicateurs de politique, les diagnostics, les métadonnées d’installation, les capacités de bundle et toute prise en charge détectée de serveurs MCP ou LSP, sans importer par défaut le runtime du plugin. Ajoutez `--runtime` pour charger le module du plugin et inclure les hooks, outils, commandes, services, méthodes Gateway et routes HTTP enregistrés. L’inspection runtime signale directement les dépendances de plugin manquantes ; les installations et réparations restent dans `openclaw plugins install`, `openclaw plugins update` et `openclaw doctor --fix`.
|
||||
Inspect affiche l’identité, l’état de chargement, la source, les capacités du manifeste, les indicateurs de politique, les diagnostics, les métadonnées d’installation, les capacités de bundle et toute prise en charge détectée de serveur MCP ou LSP sans importer le runtime du plugin par défaut. Ajoutez `--runtime` pour charger le module du plugin et inclure les hooks, outils, commandes, services, méthodes Gateway et routes HTTP enregistrés. L’inspection runtime signale directement les dépendances de plugin manquantes ; les installations et réparations restent dans `openclaw plugins install`, `openclaw plugins update` et `openclaw doctor --fix`.
|
||||
|
||||
Les commandes CLI détenues par un plugin sont installées comme groupes de commandes racine `openclaw`. Après que `inspect --runtime` affiche une commande sous `cliCommands`, exécutez-la comme `openclaw <command> ...` ; par exemple, un plugin qui enregistre `demo-git` peut être vérifié avec `openclaw demo-git ping`.
|
||||
Les commandes CLI détenues par des plugins sont installées comme groupes de commandes racine `openclaw`. Après que `inspect --runtime` affiche une commande sous `cliCommands`, exécutez-la sous la forme `openclaw <command> ...` ; par exemple, un plugin qui enregistre `demo-git` peut être vérifié avec `openclaw demo-git ping`.
|
||||
|
||||
Chaque plugin est classé selon ce qu’il enregistre réellement au runtime :
|
||||
|
||||
- **plain-capability** — un type de capacité (par exemple, un plugin uniquement fournisseur)
|
||||
- **hybrid-capability** — plusieurs types de capacités (par exemple, texte + parole + images)
|
||||
- **hook-only** — uniquement des hooks, sans capacités ni surfaces
|
||||
- **plain-capability** — un type de capacité (p. ex. un plugin seulement provider)
|
||||
- **hybrid-capability** — plusieurs types de capacités (p. ex. texte + parole + images)
|
||||
- **hook-only** — uniquement des hooks, aucune capacité ni surface
|
||||
- **non-capability** — outils/commandes/services mais aucune capacité
|
||||
|
||||
Consultez [Formes de plugins](/fr/plugins/architecture#plugin-shapes) pour en savoir plus sur le modèle de capacités.
|
||||
Consultez [Formes de Plugin](/fr/plugins/architecture#plugin-shapes) pour en savoir plus sur le modèle de capacités.
|
||||
|
||||
<Note>
|
||||
L’option `--json` produit un rapport lisible par machine adapté aux scripts et aux audits. `inspect --all` affiche un tableau pour tout le parc avec des colonnes de forme, types de capacités, avis de compatibilité, capacités de bundle et résumé des hooks. `info` est un alias de `inspect`.
|
||||
L’indicateur `--json` génère un rapport lisible par machine adapté aux scripts et aux audits. `inspect --all` affiche un tableau couvrant toute la flotte avec des colonnes pour la forme, les types de capacités, les avis de compatibilité, les capacités de bundle et le résumé des hooks. `info` est un alias de `inspect`.
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -365,11 +366,11 @@ L’option `--json` produit un rapport lisible par machine adapté aux scripts e
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` signale les erreurs de chargement de plugins, les diagnostics de manifeste/découverte et les avis de compatibilité. Lorsque tout est propre, il affiche `No plugin issues detected.`
|
||||
`doctor` signale les erreurs de chargement de plugin, les diagnostics de manifeste/découverte et les avis de compatibilité. Lorsque tout est propre, il affiche `No plugin issues detected.`
|
||||
|
||||
Si un plugin configuré est présent sur le disque mais bloqué par les contrôles de sécurité des chemins du chargeur, la validation de configuration conserve l’entrée du plugin et la signale comme `present but blocked`. Corrigez le diagnostic de plugin bloqué précédent, comme la propriété du chemin ou des permissions world-writable, au lieu de supprimer la configuration `plugins.entries.<id>` ou `plugins.allow`.
|
||||
Si un plugin configuré est présent sur disque mais bloqué par les vérifications de sécurité de chemin du chargeur, la validation de configuration conserve l’entrée du plugin et la signale comme `present but blocked`. Corrigez le diagnostic de plugin bloqué précédent, par exemple la propriété du chemin ou les permissions world-writable, au lieu de supprimer la configuration `plugins.entries.<id>` ou `plugins.allow`.
|
||||
|
||||
Pour les échecs de forme de module, comme des exports `register`/`activate` manquants, relancez avec `OPENCLAW_PLUGIN_LOAD_DEBUG=1` pour inclure un résumé compact de la forme des exports dans la sortie de diagnostic.
|
||||
Pour les échecs de forme de module comme des exports `register`/`activate` manquants, relancez avec `OPENCLAW_PLUGIN_LOAD_DEBUG=1` pour inclure un résumé compact de la forme des exports dans la sortie de diagnostic.
|
||||
|
||||
### Registre
|
||||
|
||||
@ -379,12 +380,12 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
Le registre local des plugins est le modèle de lecture à froid persistant d’OpenClaw pour l’identité des plugins installés, leur activation, les métadonnées de source et la propriété des contributions. Le démarrage normal, la recherche de propriétaire fournisseur, la classification de configuration des canaux et l’inventaire des plugins peuvent le lire sans importer les modules runtime des plugins.
|
||||
Le registre de plugins local est le modèle de lecture à froid persistant d’OpenClaw pour l’identité des plugins installés, leur activation, les métadonnées de source et la propriété des contributions. Le démarrage normal, la recherche du propriétaire du provider, la classification de configuration de canal et l’inventaire des plugins peuvent le lire sans importer les modules runtime des plugins.
|
||||
|
||||
Utilisez `plugins registry` pour vérifier si le registre persistant est présent, à jour ou obsolète. Utilisez `--refresh` pour le reconstruire à partir de l’index de plugins persistant, de la stratégie de configuration et des métadonnées de manifeste/package. Il s’agit d’un chemin de réparation, pas d’un chemin d’activation à l’exécution.
|
||||
Utilisez `plugins registry` pour vérifier si le registre persistant est présent, à jour ou obsolète. Utilisez `--refresh` pour le reconstruire à partir de l’index persistant des plugins, de la politique de configuration et des métadonnées de manifeste/package. C’est un chemin de réparation, pas un chemin d’activation à l’exécution.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` est un commutateur de compatibilité d’urgence obsolète pour les échecs de lecture du registre. Préférez `plugins registry --refresh` ou `openclaw doctor --fix` ; le repli par variable d’environnement est réservé à la récupération d’urgence au démarrage pendant le déploiement de la migration.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` est un interrupteur de compatibilité d’urgence obsolète pour les échecs de lecture du registre. Préférez `plugins registry --refresh` ou `openclaw doctor --fix` ; le repli par variable d’environnement est réservé à la récupération d’urgence au démarrage pendant le déploiement de la migration.
|
||||
</Warning>
|
||||
|
||||
### Place de marché
|
||||
@ -394,10 +395,10 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
La liste de la place de marché accepte un chemin local de place de marché, un chemin `marketplace.json`, une abréviation GitHub comme `owner/repo`, une URL de dépôt GitHub ou une URL git. `--json` affiche le libellé de source résolu, ainsi que le manifeste de place de marché analysé et les entrées de plugins.
|
||||
La liste de la place de marché accepte un chemin local de place de marché, un chemin `marketplace.json`, un raccourci GitHub comme `owner/repo`, une URL de dépôt GitHub ou une URL git. `--json` affiche le libellé de source résolu ainsi que le manifeste de place de marché analysé et les entrées de plugins.
|
||||
|
||||
## Associé
|
||||
## Connexe
|
||||
|
||||
- [Création de plugins](/fr/plugins/building-plugins)
|
||||
- [Référence CLI](/fr/cli)
|
||||
- [Plugins communautaires](/fr/plugins/community)
|
||||
- [Créer des plugins](/fr/plugins/building-plugins)
|
||||
- [Référence de la CLI](/fr/cli)
|
||||
- [Plugins de la communauté](/fr/plugins/community)
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous devez valider le routage du proxy géré par l’opérateur avant le déploiement
|
||||
- Vous devez capturer le trafic de transport OpenClaw localement pour le débogage
|
||||
- Vous voulez inspecter des sessions de proxy de débogage, des blobs ou des préréglages de requêtes intégrés
|
||||
- Vous devez capturer localement le trafic de transport d’OpenClaw à des fins de débogage
|
||||
- Vous souhaitez inspecter des sessions de proxy de débogage, des objets binaires ou des préréglages de requêtes intégrés
|
||||
summary: Référence CLI pour `openclaw proxy`, incluant la validation du proxy géré par l’opérateur et l’inspecteur de capture du proxy de débogage local
|
||||
title: Proxy
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T07:13:18Z"
|
||||
generated_at: "2026-05-04T07:03:06Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
|
||||
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
|
||||
source_path: cli/proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw proxy`
|
||||
|
||||
Validez le routage proxy géré par l’opérateur, ou exécutez le proxy de débogage explicite local
|
||||
et inspectez le trafic capturé.
|
||||
Valider le routage proxy géré par l'opérateur, ou exécuter le proxy de débogage explicite local
|
||||
et inspecter le trafic capturé.
|
||||
|
||||
Utilisez `validate` pour vérifier en amont un proxy de transfert géré par l’opérateur avant d’activer
|
||||
le routage proxy d’OpenClaw. Les autres commandes sont des outils de débogage pour
|
||||
l’investigation au niveau du transport : elles peuvent démarrer un proxy local, exécuter une commande enfant
|
||||
Utilisez `validate` pour contrôler en amont un proxy direct géré par l'opérateur avant d'activer
|
||||
le routage proxy d'OpenClaw. Les autres commandes sont des outils de débogage pour
|
||||
l'investigation au niveau du transport : elles peuvent démarrer un proxy local, exécuter une commande enfant
|
||||
avec la capture activée, lister les sessions de capture, interroger les modèles de trafic courants, lire
|
||||
les blobs capturés et purger les données de capture locales.
|
||||
|
||||
@ -38,25 +38,26 @@ openclaw proxy blob --id <blobId>
|
||||
openclaw proxy purge
|
||||
```
|
||||
|
||||
## Validation
|
||||
## Valider
|
||||
|
||||
`openclaw proxy validate` vérifie l’URL effective du proxy géré par l’opérateur à partir de
|
||||
`--proxy-url`, de la configuration ou de `OPENCLAW_PROXY_URL`. Il signale un problème de configuration lorsque
|
||||
aucun proxy n’est activé et configuré ; utilisez `--proxy-url` pour une vérification ponctuelle
|
||||
avant de modifier la configuration. Par défaut, il vérifie qu’une destination publique réussit
|
||||
`openclaw proxy validate` vérifie l'URL effective du proxy géré par l'opérateur depuis
|
||||
`--proxy-url`, la configuration ou `OPENCLAW_PROXY_URL`. Elle signale un problème de configuration lorsqu'
|
||||
aucun proxy n'est activé et configuré ; utilisez `--proxy-url` pour un contrôle en amont ponctuel
|
||||
avant de modifier la configuration. Par défaut, elle vérifie qu'une destination publique réussit
|
||||
via le proxy et que le proxy ne peut pas atteindre un canari loopback temporaire.
|
||||
Les destinations refusées personnalisées échouent en mode fermé : les réponses HTTP et les échecs de transport
|
||||
ambigus échouent tous deux, sauf si vous pouvez vérifier séparément un signal de refus propre au déploiement.
|
||||
Les destinations refusées personnalisées échouent fermées : les réponses HTTP et les échecs de
|
||||
transport ambigus échouent tous deux, sauf si vous pouvez vérifier séparément un signal de refus
|
||||
spécifique au déploiement.
|
||||
|
||||
Options :
|
||||
|
||||
- `--json` : afficher du JSON lisible par machine.
|
||||
- `--proxy-url <url>` : valider cette URL de proxy au lieu de la configuration ou de l’environnement.
|
||||
- `--proxy-url <url>` : valider cette URL de proxy au lieu de la configuration ou de l'environnement.
|
||||
- `--allowed-url <url>` : ajouter une destination censée réussir via le proxy. Répétez pour vérifier plusieurs destinations.
|
||||
- `--denied-url <url>` : ajouter une destination censée être bloquée par le proxy. Répétez pour vérifier plusieurs destinations.
|
||||
- `--timeout-ms <ms>` : délai d’expiration par requête en millisecondes.
|
||||
- `--timeout-ms <ms>` : délai d'expiration par requête en millisecondes.
|
||||
|
||||
Consultez [Proxy réseau](/fr/security/network-proxy) pour les recommandations de déploiement et la sémantique
|
||||
Consultez [Proxy réseau](/fr/security/network-proxy) pour les conseils de déploiement et la sémantique
|
||||
de refus.
|
||||
|
||||
## Préréglages de requête
|
||||
@ -70,15 +71,16 @@ de refus.
|
||||
- `missing-ack`
|
||||
- `error-bursts`
|
||||
|
||||
## Notes
|
||||
## Remarques
|
||||
|
||||
- `start` utilise `127.0.0.1` par défaut, sauf si `--host` est défini.
|
||||
- `run` démarre un proxy de débogage local, puis exécute la commande après `--`.
|
||||
- `validate` quitte avec le code 1 lorsque la configuration du proxy ou les vérifications de destination échouent.
|
||||
- Le transfert direct vers l'amont du proxy de débogage ouvre des sockets amont à des fins de diagnostic. Lorsque le mode proxy géré d'OpenClaw est actif, le transfert direct pour les requêtes proxy et les tunnels CONNECT est désactivé par défaut ; définissez `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` uniquement pour les diagnostics locaux approuvés.
|
||||
- `validate` se termine avec le code 1 lorsque la configuration du proxy ou les vérifications de destination échouent.
|
||||
- Les captures sont des données de débogage locales ; utilisez `openclaw proxy purge` lorsque vous avez terminé.
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Référence CLI](/fr/cli)
|
||||
- [Proxy réseau](/fr/security/network-proxy)
|
||||
- [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth)
|
||||
- [Authentification de proxy approuvé](/fr/gateway/trusted-proxy-auth)
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous voulez répertorier les sessions enregistrées et consulter l’activité récente
|
||||
summary: Référence CLI pour `openclaw sessions` (lister les sessions enregistrées + utilisation)
|
||||
- Vous souhaitez lister les sessions enregistrées et consulter l’activité récente
|
||||
summary: Référence CLI pour `openclaw sessions` (lister les sessions stockées + utilisation)
|
||||
title: Sessions
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:43:01Z"
|
||||
generated_at: "2026-05-04T07:02:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
|
||||
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
|
||||
source_path: cli/sessions.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -16,7 +16,9 @@ x-i18n:
|
||||
|
||||
Liste les sessions de conversation stockées.
|
||||
|
||||
Les listes de sessions ne sont pas des vérifications de disponibilité de canal/fournisseur. Elles affichent les lignes de conversation persistées depuis les stockages de sessions. Un canal Discord, Slack, Telegram ou autre silencieux peut se reconnecter correctement sans créer de nouvelle ligne de session tant qu’un message n’est pas traité. Utilisez `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` lorsque vous avez besoin de la connectivité en direct des canaux.
|
||||
Les listes de sessions ne sont pas des vérifications d’activité des canaux/fournisseurs. Elles affichent les lignes de conversation persistées depuis les magasins de sessions. Un canal Discord, Slack, Telegram ou autre silencieux peut se reconnecter correctement sans créer de nouvelle ligne de session tant qu’un message n’est pas traité. Utilisez `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` lorsque vous avez besoin de vérifier la connectivité en direct des canaux.
|
||||
|
||||
Les réponses Gateway `sessions.list` sont bornées par défaut afin que les grands magasins à longue durée de vie ne puissent pas monopoliser la boucle d’événements du Gateway. Passez une valeur `limit` positive explicite depuis les clients RPC lorsqu’une fenêtre de résultats différente est nécessaire ; les réponses incluent `totalCount`, `limitApplied` et `hasMore` lorsque les appelants doivent indiquer que d’autres lignes existent.
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
@ -29,11 +31,11 @@ openclaw sessions --json
|
||||
|
||||
Sélection de la portée :
|
||||
|
||||
- par défaut : stockage de l’agent par défaut configuré
|
||||
- par défaut : magasin de l’agent par défaut configuré
|
||||
- `--verbose` : journalisation détaillée
|
||||
- `--agent <id>` : un stockage d’agent configuré
|
||||
- `--all-agents` : agrège tous les stockages d’agents configurés
|
||||
- `--store <path>` : chemin de stockage explicite (ne peut pas être combiné avec `--agent` ou `--all-agents`)
|
||||
- `--agent <id>` : un magasin d’agent configuré
|
||||
- `--all-agents` : agréger tous les magasins d’agents configurés
|
||||
- `--store <path>` : chemin explicite du magasin (ne peut pas être combiné avec `--agent` ou `--all-agents`)
|
||||
|
||||
Exporter un bundle de trajectoire pour une session stockée :
|
||||
|
||||
@ -42,9 +44,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
|
||||
```
|
||||
|
||||
C’est le chemin de commande utilisé par la commande slash `/export-trajectory` après l’approbation de la requête d’exécution par le propriétaire. Le répertoire de sortie est toujours résolu dans `.openclaw/trajectory-exports/` sous l’espace de travail sélectionné.
|
||||
Il s’agit du chemin de commande utilisé par la commande slash `/export-trajectory` après que le propriétaire a approuvé la demande d’exécution. Le répertoire de sortie est toujours résolu dans `.openclaw/trajectory-exports/` sous l’espace de travail sélectionné.
|
||||
|
||||
`openclaw sessions --all-agents` lit les stockages d’agents configurés. La découverte des sessions Gateway et ACP est plus large : elle inclut aussi les stockages uniquement sur disque trouvés sous la racine `agents/` par défaut ou une racine `session.store` basée sur un modèle. Ces stockages découverts doivent se résoudre en fichiers `sessions.json` ordinaires à l’intérieur de la racine de l’agent ; les liens symboliques et les chemins hors racine sont ignorés.
|
||||
`openclaw sessions --all-agents` lit les magasins d’agents configurés. La découverte des sessions Gateway et ACP est plus large : elle inclut aussi les magasins présents uniquement sur disque trouvés sous la racine `agents/` par défaut ou une racine `session.store` modélisée. Ces magasins découverts doivent se résoudre en fichiers `sessions.json` ordinaires à l’intérieur de la racine de l’agent ; les liens symboliques et les chemins hors racine sont ignorés.
|
||||
|
||||
Exemples JSON :
|
||||
|
||||
@ -82,19 +84,19 @@ openclaw sessions cleanup --json
|
||||
|
||||
`openclaw sessions cleanup` utilise les paramètres `session.maintenance` de la configuration :
|
||||
|
||||
- Note sur la portée : `openclaw sessions cleanup` maintient les stockages de sessions, les transcriptions et les sidecars de trajectoire. Il ne purge pas les journaux d’exécution Cron (`cron/runs/<jobId>.jsonl`), qui sont gérés par `cron.runLog.maxBytes` et `cron.runLog.keepLines` dans la [configuration Cron](/fr/automation/cron-jobs#configuration) et expliqués dans la [maintenance Cron](/fr/automation/cron-jobs#maintenance).
|
||||
- Note sur la portée : `openclaw sessions cleanup` maintient les magasins de sessions, les transcriptions et les fichiers auxiliaires de trajectoire. Il ne purge pas les journaux d’exécution Cron (`cron/runs/<jobId>.jsonl`), qui sont gérés par `cron.runLog.maxBytes` et `cron.runLog.keepLines` dans la [configuration Cron](/fr/automation/cron-jobs#configuration) et expliqués dans la [maintenance Cron](/fr/automation/cron-jobs#maintenance).
|
||||
|
||||
- `--dry-run` : prévisualise le nombre d’entrées qui seraient purgées/limitées sans écrire.
|
||||
- En mode texte, dry-run affiche un tableau d’actions par session (`Action`, `Key`, `Age`, `Model`, `Flags`) afin que vous puissiez voir ce qui serait conservé ou supprimé.
|
||||
- `--enforce` : applique la maintenance même lorsque `session.maintenance.mode` vaut `warn`.
|
||||
- `--fix-missing` : supprime les entrées dont les fichiers de transcription sont manquants, même si elles ne seraient normalement pas encore retirées par âge/nombre.
|
||||
- `--active-key <key>` : protège une clé active spécifique de l’éviction liée au budget disque. Les pointeurs de conversation externes durables, comme les sessions de groupe et les sessions de discussion limitées à un fil, sont aussi conservés par la maintenance d’âge, de nombre et de budget disque.
|
||||
- `--agent <id>` : exécute le nettoyage pour un stockage d’agent configuré.
|
||||
- `--all-agents` : exécute le nettoyage pour tous les stockages d’agents configurés.
|
||||
- `--store <path>` : s’exécute sur un fichier `sessions.json` spécifique.
|
||||
- `--json` : affiche un résumé JSON. Avec `--all-agents`, la sortie inclut un résumé par stockage.
|
||||
- `--dry-run` : prévisualiser le nombre d’entrées qui seraient purgées/plafonnées sans écrire.
|
||||
- En mode texte, l’exécution à blanc affiche un tableau d’actions par session (`Action`, `Key`, `Age`, `Model`, `Flags`) afin que vous puissiez voir ce qui serait conservé ou supprimé.
|
||||
- `--enforce` : appliquer la maintenance même lorsque `session.maintenance.mode` vaut `warn`.
|
||||
- `--fix-missing` : supprimer les entrées dont les fichiers de transcription sont manquants, même si elles ne seraient normalement pas encore exclues par l’âge/le nombre.
|
||||
- `--active-key <key>` : protéger une clé active spécifique contre l’éviction liée au budget disque. Les pointeurs de conversation externes durables, comme les sessions de groupe et les sessions de discussion limitées à un fil, sont également conservés par la maintenance selon l’âge, le nombre et le budget disque.
|
||||
- `--agent <id>` : exécuter le nettoyage pour un magasin d’agent configuré.
|
||||
- `--all-agents` : exécuter le nettoyage pour tous les magasins d’agents configurés.
|
||||
- `--store <path>` : exécuter sur un fichier `sessions.json` spécifique.
|
||||
- `--json` : afficher un résumé JSON. Avec `--all-agents`, la sortie inclut un résumé par magasin.
|
||||
|
||||
Lorsqu’un Gateway est joignable, le nettoyage sans dry-run pour les stockages d’agents configurés est envoyé via le Gateway afin de partager le même writer de stockage de sessions que le trafic d’exécution. Utilisez `--store <path>` pour la réparation hors ligne explicite d’un fichier de stockage.
|
||||
Lorsqu’un Gateway est joignable, le nettoyage hors exécution à blanc des magasins d’agents configurés est envoyé via le Gateway afin de partager le même rédacteur de magasin de sessions que le trafic d’exécution. Utilisez `--store <path>` pour la réparation hors ligne explicite d’un fichier de magasin.
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json` :
|
||||
|
||||
@ -126,9 +128,9 @@ Lorsqu’un Gateway est joignable, le nettoyage sans dry-run pour les stockages
|
||||
|
||||
Connexe :
|
||||
|
||||
- Configuration des sessions : [Référence de configuration](/fr/gateway/config-agents#session)
|
||||
- Configuration des sessions : [référence de configuration](/fr/gateway/config-agents#session)
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Référence CLI](/fr/cli)
|
||||
- [Gestion des sessions](/fr/concepts/session)
|
||||
- [référence CLI](/fr/cli)
|
||||
- [gestion des sessions](/fr/concepts/session)
|
||||
|
||||
@ -1,58 +1,58 @@
|
||||
---
|
||||
read_when:
|
||||
- Création ou exécution de l’assurance qualité visuelle en direct pour les bogues OpenClaw
|
||||
- Mettre en place ou exécuter un contrôle qualité visuel en direct pour les bogues OpenClaw
|
||||
- Ajout d’une vérification avant et après pour une demande de tirage
|
||||
- Ajout de scénarios de transport en direct pour Discord, Slack, WhatsApp ou d’autres
|
||||
- Ajout de scénarios de transport en direct pour Discord, Slack, WhatsApp ou autres
|
||||
- Débogage des exécutions QA nécessitant des captures d’écran, l’automatisation du navigateur ou un accès VNC
|
||||
summary: Mantis est le système de vérification visuelle de bout en bout permettant de reproduire les bogues OpenClaw sur des transports en direct, de capturer des preuves avant et après, et de joindre des artefacts aux PR.
|
||||
summary: Mantis est le système de vérification visuelle de bout en bout permettant de reproduire les bogues d’OpenClaw sur des transports en direct, de capturer des preuves avant et après, et de joindre des artefacts aux PR.
|
||||
title: Mante
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:18Z"
|
||||
generated_at: "2026-05-04T07:03:09Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
|
||||
source_hash: 9d3f3fa3db111b1b5c85f8efeccd749fbd5885cee6b7843ca4c8d049acfd9164
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis est le système de vérification de bout en bout d’OpenClaw pour les bugs qui nécessitent un vrai runtime, un vrai transport et une preuve visible. Il exécute un scénario sur une référence connue comme défectueuse, capture les preuves, exécute le même scénario sur une référence candidate, puis publie la comparaison sous forme d’artefacts qu’un mainteneur peut inspecter depuis une PR ou depuis une commande locale.
|
||||
Mantis est le système de vérification de bout en bout d’OpenClaw pour les bugs qui nécessitent un environnement d’exécution réel, un transport réel et une preuve visible. Il exécute un scénario contre une ref connue comme défectueuse, capture les preuves, exécute le même scénario contre une ref candidate, puis publie la comparaison sous forme d’artefacts qu’un mainteneur peut inspecter depuis une PR ou depuis une commande locale.
|
||||
|
||||
Mantis commence par Discord, car Discord nous offre une première voie à forte valeur ajoutée : authentification réelle du bot, vrais salons de guildes, réactions, fils de discussion, commandes natives et une interface navigateur où les humains peuvent confirmer visuellement ce que le transport a montré.
|
||||
Mantis commence avec Discord parce que Discord nous donne une première voie à forte valeur : authentification de bot réelle, vrais salons de guilde, réactions, fils de discussion, commandes natives et une interface navigateur où les humains peuvent confirmer visuellement ce que le transport a montré.
|
||||
|
||||
## Objectifs
|
||||
|
||||
- Reproduire un bug issu d’une issue ou PR GitHub avec la même forme de transport que celle vue par les utilisateurs.
|
||||
- Capturer un artefact **avant** sur la référence de base avant d’appliquer le correctif.
|
||||
- Capturer un artefact **après** sur la référence candidate après avoir appliqué le correctif.
|
||||
- Reproduire un bug depuis une issue ou une PR GitHub avec la même forme de transport que celle vue par les utilisateurs.
|
||||
- Capturer un artefact **avant** sur la ref de référence avant d’appliquer le correctif.
|
||||
- Capturer un artefact **après** sur la ref candidate après avoir appliqué le correctif.
|
||||
- Utiliser un oracle déterministe chaque fois que possible, comme une lecture de réaction via l’API REST Discord ou une vérification de transcription de salon.
|
||||
- Capturer des captures d’écran lorsque le bug possède une surface d’interface visible.
|
||||
- Exécuter localement depuis une CLI contrôlée par agent et à distance depuis GitHub.
|
||||
- Préserver assez d’état machine pour un secours VNC lorsque la connexion, l’automatisation du navigateur ou l’authentification du fournisseur se bloque.
|
||||
- S’exécuter localement depuis une CLI contrôlée par un agent et à distance depuis GitHub.
|
||||
- Préserver suffisamment d’état machine pour un secours VNC lorsque la connexion, l’automatisation du navigateur ou l’authentification du fournisseur se bloque.
|
||||
- Publier un statut concis dans un salon Discord opérateur lorsque l’exécution est bloquée, nécessite une aide VNC manuelle ou se termine.
|
||||
|
||||
## Non-objectifs
|
||||
|
||||
- Mantis ne remplace pas les tests unitaires. Une exécution Mantis devrait généralement devenir un test de régression plus petit une fois le correctif compris.
|
||||
- Mantis n’est pas la porte CI rapide normale. Il est plus lent, utilise des identifiants réels et est réservé aux bugs pour lesquels l’environnement réel compte.
|
||||
- Mantis ne devrait pas nécessiter d’humain en fonctionnement normal. Le VNC manuel est un chemin de secours, pas le chemin nominal.
|
||||
- Mantis n’est pas le portail CI rapide normal. Il est plus lent, utilise des identifiants réels et est réservé aux bugs où l’environnement réel compte.
|
||||
- Mantis ne devrait pas nécessiter d’humain en fonctionnement normal. Le VNC manuel est une voie de secours, pas le chemin nominal.
|
||||
- Mantis ne stocke pas de secrets bruts dans les artefacts, journaux, captures d’écran, rapports Markdown ou commentaires de PR.
|
||||
|
||||
## Propriété
|
||||
|
||||
Mantis vit dans la stack QA d’OpenClaw.
|
||||
Mantis vit dans la pile QA d’OpenClaw.
|
||||
|
||||
- OpenClaw possède le runtime de scénario, les adaptateurs de transport, le schéma de preuves et la CLI locale sous `pnpm openclaw qa mantis`.
|
||||
- OpenClaw possède l’environnement d’exécution des scénarios, les adaptateurs de transport, le schéma de preuves et la CLI locale sous `pnpm openclaw qa mantis`.
|
||||
- QA Lab possède les éléments du harnais de transport réel, les assistants de capture navigateur et les rédacteurs d’artefacts.
|
||||
- Crabbox possède les machines Linux préchauffées lorsqu’une VM distante est nécessaire.
|
||||
- GitHub Actions possède le point d’entrée du workflow distant et la conservation des artefacts.
|
||||
- ClawSweeper possède le routage des commentaires GitHub : analyse des commandes de mainteneur, déclenchement du workflow et publication du commentaire PR final.
|
||||
- GitHub Actions possède le point d’entrée du workflow distant et la rétention des artefacts.
|
||||
- ClawSweeper possède le routage des commentaires GitHub : analyse des commandes mainteneur, déclenchement du workflow et publication du commentaire final sur la PR.
|
||||
- Les agents OpenClaw pilotent Mantis via Codex lorsqu’un scénario nécessite une configuration agentique, du débogage ou un signalement d’état bloqué.
|
||||
|
||||
Cette frontière garde la connaissance du transport dans OpenClaw, la planification des machines dans Crabbox et la colle de workflow mainteneur dans ClawSweeper.
|
||||
Cette limite garde la connaissance du transport dans OpenClaw, la planification des machines dans Crabbox et la colle du workflow mainteneur dans ClawSweeper.
|
||||
|
||||
## Forme des commandes
|
||||
## Forme de commande
|
||||
|
||||
La première commande locale vérifie le bot Discord, la guilde, le salon, l’envoi de message, l’envoi de réaction et le chemin des artefacts :
|
||||
La première commande locale vérifie le bot Discord, la guilde, le salon, l’envoi de message, l’envoi de réaction et le chemin d’artefact :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis discord-smoke \
|
||||
@ -70,7 +70,7 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
L’exécuteur crée des worktrees de base et candidats détachés sous le répertoire de sortie, installe les dépendances, construit chaque référence, exécute le scénario avec `--allow-failures`, puis écrit `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md`. Pour le premier scénario Discord, une vérification réussie signifie que le statut de base est `fail` et que le statut candidat est `pass`.
|
||||
L’exécuteur crée des worktrees détachés de référence et candidats sous le répertoire de sortie, installe les dépendances, construit chaque ref, exécute le scénario avec `--allow-failures`, puis écrit `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md`. Pour le premier scénario Discord, une vérification réussie signifie que le statut de référence est `fail` et que le statut candidat est `pass`.
|
||||
|
||||
La première primitive VM/navigateur est le smoke desktop :
|
||||
|
||||
@ -79,30 +79,62 @@ pnpm openclaw qa mantis desktop-browser-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
|
||||
```
|
||||
|
||||
Elle loue ou réutilise une machine desktop Crabbox, démarre un navigateur visible dans la session VNC, capture le bureau, rapatrie les artefacts vers le répertoire de sortie local et écrit la commande de reconnexion dans le rapport. La commande utilise par défaut le fournisseur Hetzner parce qu’il est le premier fournisseur avec une couverture desktop/VNC fonctionnelle dans la voie Mantis. Remplacez-le avec `--provider`, `--crabbox-bin` ou `OPENCLAW_MANTIS_CRABBOX_PROVIDER` lors d’une exécution sur une autre flotte Crabbox.
|
||||
Elle loue ou réutilise une machine desktop Crabbox, démarre un navigateur visible dans la session VNC, capture le desktop, rapatrie les artefacts dans le répertoire de sortie local et écrit la commande de reconnexion dans le rapport. La commande utilise par défaut le fournisseur Hetzner parce qu’il est le premier fournisseur avec une couverture desktop/VNC fonctionnelle dans la voie Mantis. Remplacez-le avec `--provider`, `--crabbox-bin` ou `OPENCLAW_MANTIS_CRABBOX_PROVIDER` lors de l’exécution contre une autre flotte Crabbox.
|
||||
|
||||
Indicateurs utiles pour le smoke desktop :
|
||||
Options utiles du smoke desktop :
|
||||
|
||||
- `--lease-id <cbx_...>` ou `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` réutilise un desktop préchauffé.
|
||||
- `--browser-url <url>` change la page ouverte dans le navigateur visible.
|
||||
- `--html-file <path>` affiche un artefact HTML local au dépôt dans le navigateur visible. Mantis l’utilise pour capturer la chronologie générée des réactions de statut Discord via un vrai desktop Crabbox.
|
||||
- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` garde ouverte une location nouvellement créée et réussie pour inspection VNC. Les exécutions échouées gardent la location par défaut lorsqu’une location a été créée afin qu’un opérateur puisse se reconnecter.
|
||||
- `--class`, `--idle-timeout` et `--ttl` règlent la taille de la machine et la durée de vie de la location.
|
||||
- `--html-file <path>` rend un artefact HTML local au dépôt dans le navigateur visible. Mantis l’utilise pour capturer la chronologie générée des réactions de statut Discord via un vrai desktop Crabbox.
|
||||
- `--keep-lease` ou `OPENCLAW_MANTIS_KEEP_VM=1` garde ouverte une location nouvellement créée et réussie pour inspection VNC. Les exécutions échouées gardent la location par défaut lorsqu’elle a été créée afin qu’un opérateur puisse se reconnecter.
|
||||
- `--class`, `--idle-timeout` et `--ttl` ajustent la taille de machine et la durée de vie de la location.
|
||||
|
||||
Le workflow smoke GitHub est `Mantis Discord Smoke`. Le workflow GitHub avant et après pour le premier vrai scénario est `Mantis Discord Status Reactions`. Il accepte :
|
||||
La première primitive complète de transport desktop est le smoke desktop Slack :
|
||||
|
||||
- `baseline_ref` : la référence censée reproduire le comportement file d’attente uniquement.
|
||||
- `candidate_ref` : la référence censée montrer `queued -> thinking -> done`.
|
||||
```bash
|
||||
pnpm openclaw qa mantis slack-desktop-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/slack-desktop \
|
||||
--gateway-setup \
|
||||
--scenario slack-canary \
|
||||
--keep-lease
|
||||
```
|
||||
|
||||
Il récupère la référence du harnais de workflow, construit des worktrees de base et candidats séparés, exécute `discord-status-reactions-tool-only` sur chaque worktree et téléverse `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md` comme artefacts Actions. Il rend aussi le HTML de chronologie de chaque voie dans un navigateur desktop Crabbox et publie ces captures d’écran VNC à côté des PNG de chronologie déterministes dans le commentaire PR. Le workflow construit la CLI Crabbox depuis `openclaw/crabbox` main afin de pouvoir utiliser les indicateurs de location desktop/navigateur actuels avant la prochaine publication du binaire Crabbox.
|
||||
Elle loue ou réutilise une machine desktop Crabbox, synchronise le checkout courant dans la VM, exécute `pnpm openclaw qa slack` dans cette VM, ouvre Slack Web dans le navigateur VNC, capture le desktop visible et recopie à la fois les artefacts QA Slack et la capture d’écran VNC dans le répertoire de sortie local. C’est la première forme Mantis où le Gateway OpenClaw SUT et le navigateur vivent tous deux dans la même VM desktop Linux.
|
||||
|
||||
Vous pouvez aussi déclencher directement l’exécution status-reactions depuis un commentaire de PR :
|
||||
Avec `--gateway-setup`, la commande prépare un home OpenClaw jetable persistant dans `$HOME/.openclaw-mantis/slack-openclaw`, corrige la configuration Slack Socket Mode pour le salon sélectionné, démarre `openclaw gateway run` sur le port `38973` et garde Chrome en cours d’exécution dans la session VNC. C’est le mode « laisse-moi un desktop Linux avec Slack et un claw en cours d’exécution » ; la voie QA Slack bot-à-bot reste la valeur par défaut lorsque `--gateway-setup` est omis.
|
||||
|
||||
Entrées requises pour `--credential-source env` :
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
|
||||
- `OPENCLAW_LIVE_OPENAI_KEY` pour la voie modèle distante. Si seul `OPENAI_API_KEY` est défini localement, Mantis le mappe vers `OPENCLAW_LIVE_OPENAI_KEY` avant d’invoquer Crabbox afin que le transfert d’env `OPENCLAW_*` de Crabbox puisse le transporter dans la VM.
|
||||
|
||||
Options utiles du desktop Slack :
|
||||
|
||||
- `--lease-id <cbx_...>` réexécute contre une machine où un opérateur s’est déjà connecté à Slack Web via VNC.
|
||||
- `--gateway-setup` démarre un Gateway Slack OpenClaw persistant dans la VM au lieu d’exécuter uniquement la voie QA bot-à-bot.
|
||||
- `--slack-url <url>` ouvre une URL Slack Web spécifique. Sans celle-ci, Mantis dérive `https://app.slack.com/client/<team>/<channel>` depuis `auth.test` de Slack lorsque le jeton du bot SUT est disponible.
|
||||
- `--slack-channel-id <id>` contrôle la liste d’autorisation des salons Slack utilisée par la configuration du Gateway.
|
||||
- `OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR` contrôle le profil Chrome persistant dans la VM. La valeur par défaut est `$HOME/.config/openclaw-mantis/slack-chrome-profile`, afin qu’une connexion manuelle à Slack Web survive aux réexécutions sur la même location.
|
||||
- `--credential-source convex --credential-role ci` utilise le pool d’identifiants partagé au lieu des jetons env Slack directs.
|
||||
- `--provider-mode`, `--model`, `--alt-model` et `--fast` sont transmis à la voie Slack réelle.
|
||||
|
||||
Le workflow de smoke GitHub est `Mantis Discord Smoke`. Le workflow GitHub avant et après pour le premier vrai scénario est `Mantis Discord Status Reactions`. Il accepte :
|
||||
|
||||
- `baseline_ref` : la ref censée reproduire le comportement uniquement en file d’attente.
|
||||
- `candidate_ref` : la ref censée montrer `queued -> thinking -> done`.
|
||||
|
||||
Il checkout la ref du harnais de workflow, construit des worktrees distincts de référence et candidats, exécute `discord-status-reactions-tool-only` contre chaque worktree et téléverse `baseline/`, `candidate/`, `comparison.json` et `mantis-report.md` comme artefacts Actions. Il rend aussi le HTML de chronologie de chaque voie dans un navigateur desktop Crabbox et publie ces captures d’écran VNC à côté des PNG de chronologie déterministes dans le commentaire de PR. Le workflow construit la CLI Crabbox depuis `openclaw/crabbox` main afin de pouvoir utiliser les options de location desktop/navigateur actuelles avant la prochaine publication du binaire Crabbox.
|
||||
|
||||
Vous pouvez aussi déclencher l’exécution des réactions de statut directement depuis un commentaire de PR :
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions
|
||||
```
|
||||
|
||||
Le déclencheur de commentaire est volontairement étroit. Il ne s’exécute que sur les commentaires de pull request provenant d’utilisateurs ayant un accès write, maintain ou admin, et il ne reconnaît que les demandes de réactions de statut Discord. Par défaut, il utilise la référence de base connue comme défectueuse et le SHA HEAD de la PR courante comme candidat. Les mainteneurs peuvent remplacer l’une ou l’autre référence :
|
||||
Le déclencheur par commentaire est volontairement étroit. Il ne s’exécute que sur les commentaires de pull request provenant d’utilisateurs disposant des droits write, maintain ou admin, et il ne reconnaît que les requêtes de réactions de statut Discord. Par défaut, il utilise la ref de référence connue comme défectueuse et le SHA de tête de la PR courante comme candidat. Les mainteneurs peuvent remplacer l’une ou l’autre ref :
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions baseline=origin/main candidate=HEAD
|
||||
@ -115,32 +147,32 @@ Exemples de commandes ClawSweeper :
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
La première commande est explicite et centrée sur le scénario. La seconde pourra plus tard associer une PR ou une issue aux scénarios Mantis recommandés à partir des labels, des fichiers modifiés et des constats de revue ClawSweeper.
|
||||
La première commande est explicite et centrée sur le scénario. La seconde pourra plus tard mapper une PR ou une issue vers des scénarios Mantis recommandés à partir des libellés, des fichiers modifiés et des constats de revue ClawSweeper.
|
||||
|
||||
## Cycle d’exécution
|
||||
## Cycle de vie de l’exécution
|
||||
|
||||
1. Acquérir les identifiants.
|
||||
2. Allouer ou réutiliser une VM.
|
||||
3. Préparer le profil desktop/navigateur lorsque le scénario nécessite une preuve d’interface.
|
||||
4. Préparer un checkout propre pour la référence de base.
|
||||
4. Préparer un checkout propre pour la ref de référence.
|
||||
5. Installer les dépendances et construire uniquement ce dont le scénario a besoin.
|
||||
6. Démarrer un Gateway OpenClaw enfant avec un répertoire d’état isolé.
|
||||
7. Configurer le transport réel, le fournisseur, le modèle et le profil navigateur.
|
||||
8. Exécuter le scénario et capturer les preuves de base.
|
||||
8. Exécuter le scénario et capturer les preuves de référence.
|
||||
9. Arrêter le Gateway et préserver les journaux.
|
||||
10. Préparer la référence candidate dans la même VM.
|
||||
10. Préparer la ref candidate dans la même VM.
|
||||
11. Exécuter le même scénario et capturer les preuves candidates.
|
||||
12. Comparer les résultats de l’oracle et les preuves visuelles.
|
||||
13. Écrire Markdown, JSON, journaux, captures d’écran et artefacts de trace optionnels.
|
||||
13. Écrire le Markdown, le JSON, les journaux, les captures d’écran et les artefacts de trace facultatifs.
|
||||
14. Téléverser les artefacts GitHub Actions.
|
||||
15. Publier un message de statut concis dans la PR ou Discord.
|
||||
15. Publier un message de statut concis sur la PR ou Discord.
|
||||
|
||||
Le scénario devrait pouvoir échouer de deux manières différentes :
|
||||
Le scénario devrait pouvoir échouer de deux façons différentes :
|
||||
|
||||
- **Bug reproduit** : la base a échoué de la manière attendue.
|
||||
- **Échec du harnais** : la configuration de l’environnement, les identifiants, l’API Discord, le navigateur ou le fournisseur a échoué avant que l’oracle du bug ne soit significatif.
|
||||
- **Bug reproduit** : la référence a échoué de la façon attendue.
|
||||
- **Échec du harnais** : la configuration de l’environnement, les identifiants, l’API Discord, le navigateur ou le fournisseur ont échoué avant que l’oracle du bug ne soit significatif.
|
||||
|
||||
Le rapport final doit séparer ces cas afin que les mainteneurs ne confondent pas un environnement instable avec le comportement du produit.
|
||||
Le rapport final doit séparer ces cas afin que les mainteneurs ne confondent pas un environnement flaky avec le comportement du produit.
|
||||
|
||||
## MVP Discord
|
||||
|
||||
@ -148,10 +180,10 @@ Le premier scénario devrait cibler les réactions de statut Discord dans les sa
|
||||
|
||||
Pourquoi c’est une bonne graine Mantis :
|
||||
|
||||
- C’est visible dans Discord comme réactions sur le message déclencheur.
|
||||
- Il dispose d’un oracle REST solide via l’état des réactions du message Discord.
|
||||
- Il exerce un vrai Gateway OpenClaw, l’authentification du bot Discord, la répartition des messages, le mode de livraison de réponse source, l’état des réactions de statut et le cycle de vie du tour de modèle.
|
||||
- Il est suffisamment étroit pour garder la première implémentation honnête.
|
||||
- C’est visible dans Discord sous forme de réactions sur le message déclencheur.
|
||||
- Il possède un oracle REST solide via l’état des réactions au message Discord.
|
||||
- Il exerce un vrai Gateway OpenClaw, l’authentification du bot Discord, la distribution de messages, le mode de livraison de réponse source, l’état des réactions de statut et le cycle de vie du tour du modèle.
|
||||
- Il est assez étroit pour garder la première implémentation honnête.
|
||||
|
||||
Forme de scénario attendue :
|
||||
|
||||
@ -184,7 +216,7 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
Les preuves de base devraient montrer la réaction d’accusé de réception en file d’attente, mais aucune transition de cycle de vie en mode tool-only. Les preuves candidates devraient montrer les réactions de statut de cycle de vie en cours d’exécution lorsque `messages.statusReactions.enabled` est explicitement `true`.
|
||||
Les preuves de référence devraient montrer la réaction d’accusé de réception en file d’attente, mais aucune transition de cycle de vie en mode tool-only. Les preuves candidates devraient montrer les réactions de statut de cycle de vie s’exécutant lorsque `messages.statusReactions.enabled` est explicitement `true`.
|
||||
|
||||
La première tranche exécutable est le scénario QA Discord réel opt-in :
|
||||
|
||||
@ -198,20 +230,20 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
Il configure le SUT avec une gestion de guilde toujours active, `visibleReplies:
|
||||
Il configure le SUT avec une gestion des serveurs toujours activée, `visibleReplies:
|
||||
"message_tool"`, `ackReaction: "👀"` et des réactions de statut explicites. L’oracle interroge le vrai message déclencheur Discord et attend la séquence observée `👀 -> 🤔 -> 👍`. Les artefacts incluent `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html` et `discord-status-reactions-tool-only-timeline.png`.
|
||||
|
||||
## Éléments QA existants
|
||||
## Composants QA existants
|
||||
|
||||
Mantis devrait s’appuyer sur la stack QA privée existante au lieu de repartir de zéro :
|
||||
Mantis doit s’appuyer sur la pile QA privée existante au lieu de repartir de zéro :
|
||||
|
||||
- `pnpm openclaw qa discord` exécute déjà une voie Discord réelle avec des bots pilote et SUT.
|
||||
- L’exécuteur de transport réel écrit déjà des rapports et des artefacts de messages observés sous `.artifacts/qa-e2e/`.
|
||||
- Les locations d’identifiants Convex fournissent déjà un accès exclusif aux identifiants de transport réel partagés.
|
||||
- Le service de contrôle navigateur prend déjà en charge les captures d’écran, instantanés, profils gérés headless et profils CDP distants.
|
||||
- QA Lab dispose déjà d’une interface de débogage et d’un bus pour les tests en forme de transport.
|
||||
- `pnpm openclaw qa discord` exécute déjà une voie Discord en direct avec des bots pilote et SUT.
|
||||
- Le runner de transport en direct écrit déjà les rapports et les artefacts de messages observés sous `.artifacts/qa-e2e/`.
|
||||
- Les baux d’identifiants Convex fournissent déjà un accès exclusif aux identifiants de transport en direct partagés.
|
||||
- Le service de contrôle du navigateur prend déjà en charge les captures d’écran, les instantanés, les profils gérés headless et les profils CDP distants.
|
||||
- QA Lab dispose déjà d’une interface de débogage et d’un bus pour les tests de type transport.
|
||||
|
||||
La première implémentation de Mantis peut être un mince exécuteur avant/après par-dessus ces éléments, plus une couche de preuves visuelles.
|
||||
La première implémentation de Mantis peut être un runner avant/après léger par-dessus ces composants, avec une couche de preuve visuelle.
|
||||
|
||||
## Modèle de preuves
|
||||
|
||||
@ -235,72 +267,63 @@ Chaque exécution écrit un répertoire d’artefacts stable :
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` devrait être la source de vérité lisible par machine. Le rapport Markdown sert aux commentaires PR et à la revue humaine.
|
||||
`mantis-summary.json` doit être la source de vérité lisible par machine. Le rapport Markdown est destiné aux commentaires de PR et à la revue humaine.
|
||||
|
||||
Le résumé doit inclure :
|
||||
|
||||
- les références et SHA testés
|
||||
- le transport et l’identifiant de scénario
|
||||
- le fournisseur de machine et l’identifiant de machine ou de location
|
||||
- les refs et les SHA testés
|
||||
- le transport et l’id du scénario
|
||||
- le fournisseur de machine et l’id de machine ou l’id de bail
|
||||
- la source des identifiants sans valeurs secrètes
|
||||
- le résultat de base
|
||||
- le résultat candidat
|
||||
- si le bug a été reproduit sur la base
|
||||
- le résultat de la baseline
|
||||
- le résultat du candidat
|
||||
- si le bug s’est reproduit sur la baseline
|
||||
- si le candidat l’a corrigé
|
||||
- les chemins d’artefacts
|
||||
- les problèmes de configuration ou de nettoyage assainis
|
||||
- les chemins des artefacts
|
||||
- les problèmes de configuration ou de nettoyage nettoyés
|
||||
|
||||
Les captures d’écran sont des preuves, pas des secrets. Elles nécessitent tout de même une discipline de rédaction : noms de salons privés, noms d’utilisateurs ou contenu de messages peuvent apparaître. Pour les PR publiques, préférez les liens vers les artefacts GitHub Actions plutôt que les images intégrées jusqu’à ce que la stratégie de rédaction soit plus solide.
|
||||
Les captures d’écran sont des preuves, pas des secrets. Elles exigent tout de même une discipline de caviardage : des noms de canaux privés, des noms d’utilisateurs ou le contenu de messages peuvent apparaître. Pour les PR publiques, préférez les liens d’artefacts GitHub Actions aux images intégrées tant que la stratégie de caviardage n’est pas plus solide.
|
||||
|
||||
## Navigateur et VNC
|
||||
|
||||
La voie navigateur possède deux modes :
|
||||
La voie navigateur dispose de deux modes :
|
||||
|
||||
- **Automatisation headless** : par défaut pour la CI. Chrome s’exécute avec CDP activé, et Playwright ou le contrôle navigateur OpenClaw capture les captures d’écran.
|
||||
- **Secours VNC** : activé sur la même VM lorsque la connexion, la MFA, l’anti-automatisation Discord ou le débogage visuel nécessite un humain.
|
||||
- **Automatisation headless** : par défaut pour la CI. Chrome s’exécute avec CDP activé, et Playwright ou le contrôle de navigateur OpenClaw capture les captures d’écran.
|
||||
- **Secours VNC** : activé sur la même VM lorsque la connexion, le MFA, l’anti-automatisation Discord ou le débogage visuel nécessitent un humain.
|
||||
|
||||
Le profil de navigateur observateur Discord doit être suffisamment persistant pour éviter
|
||||
de se reconnecter à chaque exécution, mais isolé de l’état du navigateur personnel. Un profil
|
||||
appartient au pool de machines Mantis, pas à l’ordinateur portable d’un développeur.
|
||||
Le profil de navigateur observateur Discord doit être suffisamment persistant pour éviter une connexion à chaque exécution, mais isolé de l’état du navigateur personnel. Un profil appartient au pool de machines Mantis, pas à un ordinateur portable de développeur.
|
||||
|
||||
Quand Mantis reste bloqué, il publie un message de statut Discord avec :
|
||||
Quand Mantis se bloque, il publie un message de statut Discord avec :
|
||||
|
||||
- id d’exécution
|
||||
- id de scénario
|
||||
- fournisseur de machine
|
||||
- répertoire des artefacts
|
||||
- instructions de connexion VNC ou noVNC si disponibles
|
||||
- texte court décrivant le blocage
|
||||
- l’id d’exécution
|
||||
- l’id du scénario
|
||||
- le fournisseur de machine
|
||||
- le répertoire d’artefacts
|
||||
- les instructions de connexion VNC ou noVNC si disponibles
|
||||
- un court texte décrivant le blocage
|
||||
|
||||
Le premier déploiement privé peut publier ces messages dans le canal opérateur
|
||||
existant et passer plus tard à un canal Mantis dédié.
|
||||
Le premier déploiement privé peut publier ces messages dans le canal opérateur existant et migrer plus tard vers un canal Mantis dédié.
|
||||
|
||||
## Machines
|
||||
|
||||
Mantis doit privilégier AWS via Crabbox pour la première implémentation distante.
|
||||
Crabbox nous fournit des machines préchauffées, le suivi des baux, l’hydratation,
|
||||
les journaux, les résultats et le nettoyage. Si la capacité AWS est trop lente ou
|
||||
indisponible, ajoutez un fournisseur Hetzner derrière la même interface de machine.
|
||||
Mantis doit privilégier AWS via Crabbox pour la première implémentation distante. Crabbox nous fournit des machines préchauffées, le suivi des baux, l’hydratation, les journaux, les résultats et le nettoyage. Si la capacité AWS est trop lente ou indisponible, ajoutez un fournisseur Hetzner derrière la même interface de machine.
|
||||
|
||||
Exigences minimales pour la VM :
|
||||
|
||||
- Linux avec une installation Chrome ou Chromium compatible avec un bureau
|
||||
- Linux avec une installation Chrome ou Chromium capable d’exécuter un bureau
|
||||
- accès CDP pour l’automatisation du navigateur
|
||||
- VNC ou noVNC pour la récupération
|
||||
- VNC ou noVNC pour le secours
|
||||
- Node 22 et pnpm
|
||||
- checkout OpenClaw et cache des dépendances
|
||||
- cache du navigateur Playwright Chromium quand Playwright est utilisé
|
||||
- suffisamment de CPU et de mémoire pour un OpenClaw Gateway, un navigateur et une exécution de modèle
|
||||
- accès sortant à Discord, GitHub, aux fournisseurs de modèles et au courtier d’identifiants
|
||||
- cache du navigateur Chromium Playwright lorsque Playwright est utilisé
|
||||
- suffisamment de CPU et de mémoire pour un Gateway OpenClaw, un navigateur et une exécution de modèle
|
||||
- accès sortant vers Discord, GitHub, les fournisseurs de modèles et le courtier d’identifiants
|
||||
|
||||
La VM ne doit pas conserver de secrets bruts à longue durée de vie en dehors des
|
||||
magasins d’identifiants ou de profils de navigateur attendus.
|
||||
La VM ne doit pas conserver de secrets bruts de longue durée en dehors des magasins d’identifiants ou de profils de navigateur attendus.
|
||||
|
||||
## Secrets
|
||||
|
||||
Les secrets résident dans les secrets d’organisation ou de dépôt GitHub pour les
|
||||
exécutions distantes, et dans un fichier de secrets local contrôlé par l’opérateur
|
||||
pour les exécutions locales.
|
||||
Les secrets résident dans les secrets d’organisation ou de dépôt GitHub pour les exécutions distantes, et dans un fichier de secrets local contrôlé par l’opérateur pour les exécutions locales.
|
||||
|
||||
Noms de secrets recommandés :
|
||||
|
||||
@ -310,53 +333,32 @@ Noms de secrets recommandés :
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour les téléversements d’artefacts GitHub publics
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour les téléversements publics d’artefacts GitHub
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
|
||||
|
||||
À long terme, le pool d’identifiants Convex doit rester la source normale des
|
||||
identifiants de transport en direct. Les secrets GitHub amorcent le courtier et
|
||||
les voies de secours. Le workflow des réactions de statut Discord mappe les
|
||||
secrets Mantis Crabbox vers les variables d’environnement `CRABBOX_COORDINATOR`
|
||||
et `CRABBOX_COORDINATOR_TOKEN` attendues par la CLI Crabbox. Les noms de secrets
|
||||
GitHub `CRABBOX_*` simples restent acceptés comme solution de compatibilité.
|
||||
À long terme, le pool d’identifiants Convex doit rester la source normale des identifiants de transport en direct. Les secrets GitHub initialisent le courtier et les voies de secours. Le workflow de réactions de statut Discord remappe les secrets Crabbox Mantis vers les variables d’environnement `CRABBOX_COORDINATOR` et `CRABBOX_COORDINATOR_TOKEN` attendues par la CLI Crabbox. Les noms de secrets GitHub `CRABBOX_*` simples restent acceptés comme solution de compatibilité.
|
||||
|
||||
Le runner Mantis ne doit jamais afficher :
|
||||
|
||||
- jetons de bots Discord
|
||||
- clés d’API de fournisseurs
|
||||
- cookies de navigateur
|
||||
- contenu des profils d’authentification
|
||||
- mots de passe VNC
|
||||
- charges utiles d’identifiants brutes
|
||||
- les tokens de bot Discord
|
||||
- les clés API de fournisseur
|
||||
- les cookies de navigateur
|
||||
- le contenu des profils d’authentification
|
||||
- les mots de passe VNC
|
||||
- les charges utiles d’identifiants bruts
|
||||
|
||||
Les téléversements d’artefacts publics doivent aussi caviarder les métadonnées de
|
||||
cible Discord telles que les ids de bot, serveur, canal et message. Le workflow
|
||||
smoke GitHub active `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour cette raison.
|
||||
Les téléversements d’artefacts publics doivent aussi caviarder les métadonnées de cible Discord telles que les ids de bot, de serveur, de canal et de message. Le workflow de smoke GitHub active `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` pour cette raison.
|
||||
|
||||
Si un jeton est accidentellement collé dans une issue, une PR, un chat ou un
|
||||
journal, faites-le tourner après avoir stocké le nouveau secret.
|
||||
Si un token est accidentellement collé dans une issue, une PR, une discussion ou un journal, faites-le pivoter après avoir stocké le nouveau secret.
|
||||
|
||||
## Artefacts GitHub et commentaires de PR
|
||||
|
||||
Les workflows Mantis doivent téléverser le paquet complet de preuves sous forme
|
||||
d’artefact Actions à courte durée de vie. Quand le workflow est exécuté pour un
|
||||
rapport de bogue ou une PR de correction, il doit aussi publier les captures
|
||||
d’écran PNG caviardées dans la branche `qa-artifacts` et insérer ou mettre à jour
|
||||
un commentaire sur ce bogue ou cette PR de correction avec des captures d’écran
|
||||
avant/après intégrées. Ne publiez pas la preuve principale uniquement sur une PR
|
||||
générique d’automatisation QA. Les journaux bruts, messages observés et autres
|
||||
preuves volumineuses restent dans l’artefact Actions.
|
||||
Les workflows Mantis doivent téléverser le bundle de preuves complet comme artefact Actions à durée de vie courte. Lorsque le workflow est exécuté pour un rapport de bug ou une PR de correctif, il doit aussi publier les captures d’écran PNG caviardées sur la branche `qa-artifacts` et mettre à jour ou créer un commentaire sur ce bug ou cette PR de correctif avec des captures d’écran avant/après intégrées. Ne publiez pas la preuve principale uniquement sur une PR générique d’automatisation QA. Les journaux bruts, les messages observés et les autres preuves volumineuses restent dans l’artefact Actions.
|
||||
|
||||
Les workflows de production doivent publier ces commentaires avec la GitHub App
|
||||
Mantis, pas avec `github-actions[bot]`. Stockez l’id de l’app et la clé privée
|
||||
comme secrets GitHub Actions `MANTIS_GITHUB_APP_ID` et
|
||||
`MANTIS_GITHUB_APP_PRIVATE_KEY`. Le workflow utilise un marqueur masqué comme clé
|
||||
d’upsert, met à jour ce commentaire quand le jeton peut le modifier, et crée un
|
||||
nouveau commentaire appartenant à Mantis quand un ancien marqueur appartenant à
|
||||
un bot ne peut pas être modifié.
|
||||
Les workflows de production doivent publier ces commentaires avec la GitHub App Mantis, pas avec `github-actions[bot]`. Stockez l’id d’application et la clé privée dans les secrets GitHub Actions `MANTIS_GITHUB_APP_ID` et `MANTIS_GITHUB_APP_PRIVATE_KEY`. Le workflow utilise un marqueur masqué comme clé de mise à jour, met à jour ce commentaire lorsque le token peut le modifier, et crée un nouveau commentaire appartenant à Mantis lorsqu’un ancien marqueur appartenant au bot ne peut pas être modifié.
|
||||
|
||||
Le commentaire de PR doit être court et visuel :
|
||||
|
||||
@ -378,76 +380,60 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
Quand l’exécution échoue parce que le harnais a échoué, le commentaire doit le
|
||||
dire au lieu de laisser entendre que le candidat a échoué.
|
||||
Lorsque l’exécution échoue parce que le harnais a échoué, le commentaire doit le dire au lieu de laisser entendre que le candidat a échoué.
|
||||
|
||||
## Notes de déploiement privé
|
||||
|
||||
Un déploiement privé peut déjà disposer d’une application Discord Mantis.
|
||||
Réutilisez cette application au lieu d’en créer une autre quand elle dispose des
|
||||
bonnes autorisations de bot et peut faire l’objet d’une rotation en toute sécurité.
|
||||
Un déploiement privé peut déjà disposer d’une application Discord Mantis. Réutilisez cette application au lieu de créer une autre application lorsqu’elle dispose des bonnes autorisations de bot et peut être tournée en toute sécurité.
|
||||
|
||||
Définissez le canal initial de notification des opérateurs via des secrets ou la
|
||||
configuration de déploiement. Il peut d’abord pointer vers un canal mainteneur ou
|
||||
opérations existant, puis passer à un canal Mantis dédié dès qu’il existe.
|
||||
Définissez le canal initial de notification opérateur via des secrets ou la configuration de déploiement. Il peut d’abord pointer vers un canal de maintenance ou d’opérations existant, puis migrer vers un canal Mantis dédié lorsqu’il existera.
|
||||
|
||||
Ne mettez pas d’ids de serveur, d’ids de canal, de jetons de bot, de cookies de
|
||||
navigateur ou de mots de passe VNC dans ce document. Stockez-les dans les secrets
|
||||
GitHub, le courtier d’identifiants ou le magasin local de secrets de l’opérateur.
|
||||
Ne mettez pas d’ids de serveur, d’ids de canal, de tokens de bot, de cookies de navigateur ni de mots de passe VNC dans ce document. Stockez-les dans les secrets GitHub, le courtier d’identifiants ou le magasin de secrets local de l’opérateur.
|
||||
|
||||
## Ajouter un scénario
|
||||
|
||||
Un scénario Mantis doit déclarer :
|
||||
|
||||
- id et titre
|
||||
- transport
|
||||
- identifiants requis
|
||||
- politique de référence de base
|
||||
- politique de référence candidate
|
||||
- correctif de configuration OpenClaw
|
||||
- étapes de configuration
|
||||
- stimulus
|
||||
- oracle de référence attendu
|
||||
- oracle candidat attendu
|
||||
- cibles de capture visuelle
|
||||
- budget de délai d’expiration
|
||||
- étapes de nettoyage
|
||||
- un id et un titre
|
||||
- le transport
|
||||
- les identifiants requis
|
||||
- la politique de ref de baseline
|
||||
- la politique de ref de candidat
|
||||
- le patch de configuration OpenClaw
|
||||
- les étapes de configuration
|
||||
- le stimulus
|
||||
- l’oracle attendu pour la baseline
|
||||
- l’oracle attendu pour le candidat
|
||||
- les cibles de capture visuelle
|
||||
- le budget de délai d’expiration
|
||||
- les étapes de nettoyage
|
||||
|
||||
Les scénarios doivent privilégier de petits oracles typés :
|
||||
|
||||
- état des réactions Discord pour les bogues de réactions
|
||||
- références de messages Discord pour les bogues de fils de discussion
|
||||
- ts de fil Slack et état de l’API de réactions pour les bogues Slack
|
||||
- ids et en-têtes de messages e-mail pour les bogues e-mail
|
||||
- captures d’écran du navigateur quand l’UI est le seul observable fiable
|
||||
- l’état des réactions Discord pour les bugs de réaction
|
||||
- les références de messages Discord pour les bugs de fil de discussion
|
||||
- le ts de fil Slack et l’état de l’API de réactions pour les bugs Slack
|
||||
- les ids et en-têtes de messages e-mail pour les bugs e-mail
|
||||
- les captures d’écran du navigateur lorsque l’UI est le seul observable fiable
|
||||
|
||||
Les vérifications par vision doivent être additives. Si une API de plateforme peut
|
||||
prouver le bogue, utilisez l’API comme oracle de réussite/échec et conservez les
|
||||
captures d’écran pour la confiance humaine.
|
||||
Les vérifications par vision doivent être additives. Si une API de plateforme peut prouver le bug, utilisez l’API comme oracle de réussite/échec et gardez les captures d’écran pour renforcer la confiance humaine.
|
||||
|
||||
## Extension des fournisseurs
|
||||
|
||||
Après Discord, le même runner peut ajouter :
|
||||
|
||||
- Slack : réactions, fils, mentions d’app, modales, téléversements de fichiers.
|
||||
- E-mail : authentification Gmail et fils de messages avec `gog` quand les connecteurs ne
|
||||
suffisent pas.
|
||||
- WhatsApp : connexion QR, ré-identification, livraison des messages, médias, réactions.
|
||||
- Telegram : contrôle des mentions de groupe, commandes, réactions quand disponibles.
|
||||
- Slack : réactions, fils, mentions d’application, modales, téléversements de fichiers.
|
||||
- E-mail : authentification Gmail et threading de messages avec `gog` lorsque les connecteurs ne suffisent pas.
|
||||
- WhatsApp : connexion par QR code, réidentification, livraison de messages, médias, réactions.
|
||||
- Telegram : contrôle des mentions de groupe, commandes, réactions lorsque disponibles.
|
||||
- Matrix : salons chiffrés, relations de fil ou de réponse, reprise après redémarrage.
|
||||
|
||||
Chaque transport doit avoir un scénario smoke peu coûteux et un ou plusieurs
|
||||
scénarios par classe de bogues. Les scénarios visuels coûteux doivent rester
|
||||
optionnels.
|
||||
Chaque transport doit avoir un scénario smoke peu coûteux et un ou plusieurs scénarios par classe de bugs. Les scénarios visuels coûteux doivent rester opt-in.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
- Quel bot Discord doit être le pilote, et lequel doit être le SUT, quand le
|
||||
bot Mantis existant est réutilisé ?
|
||||
- La connexion du navigateur observateur doit-elle utiliser un compte Discord
|
||||
humain, un compte de test, ou seulement des preuves REST lisibles par bot pour
|
||||
la première phase ?
|
||||
- Quel bot Discord doit être le pilote, et lequel doit être le SUT, lorsque le bot Mantis existant est réutilisé ?
|
||||
- La connexion du navigateur observateur doit-elle utiliser un compte Discord humain, un compte de test ou seulement des preuves REST lisibles par bot pour la première phase ?
|
||||
- Combien de temps GitHub doit-il conserver les artefacts Mantis pour les PR ?
|
||||
- Quand ClawSweeper doit-il recommander automatiquement Mantis au lieu d’attendre
|
||||
une commande de mainteneur ?
|
||||
- Les captures d’écran doivent-elles être caviardées ou rognées avant le téléversement pour les PR publiques ?
|
||||
- Quand ClawSweeper doit-il recommander automatiquement Mantis au lieu d’attendre une commande d’un mainteneur ?
|
||||
- Les captures d’écran doivent-elles être caviardées ou recadrées avant le téléversement pour les PR publiques ?
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Expliquer comment les messages entrants deviennent des réponses
|
||||
- Clarification des sessions, des modes de mise en file d’attente ou du comportement de diffusion en continu
|
||||
- Documenter la visibilité du raisonnement et les implications d’utilisation
|
||||
- Clarification des sessions, des modes de mise en file d’attente ou du comportement de streaming
|
||||
- Documenter la visibilité du raisonnement et les implications d'utilisation
|
||||
summary: Flux des messages, sessions, mise en file d’attente et visibilité du raisonnement
|
||||
title: Messages
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T16:27:51Z"
|
||||
generated_at: "2026-05-04T07:03:35Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
|
||||
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw gère les messages entrants au moyen d’un pipeline de résolution de session, de mise en file d’attente, de streaming, d’exécution d’outils et de visibilité du raisonnement. Cette page cartographie le chemin d’un message entrant jusqu’à la réponse.
|
||||
OpenClaw gère les messages entrants au moyen d’un pipeline de résolution de session, de mise en file d’attente, de streaming, d’exécution d’outils et de visibilité du raisonnement. Cette page décrit le chemin d’un message entrant jusqu’à la réponse.
|
||||
|
||||
## Flux des messages (vue d’ensemble)
|
||||
|
||||
@ -30,17 +30,21 @@ Les principaux réglages se trouvent dans la configuration :
|
||||
|
||||
- `messages.*` pour les préfixes, la mise en file d’attente et le comportement des groupes.
|
||||
- `agents.defaults.*` pour les valeurs par défaut du streaming par blocs et du découpage.
|
||||
- Les remplacements par canal (`channels.whatsapp.*`, `channels.telegram.*`, etc.) pour les limites et les bascules de streaming.
|
||||
- Les remplacements par canal (`channels.whatsapp.*`, `channels.telegram.*`, etc.) pour les limites et les options de streaming.
|
||||
|
||||
Consultez [Configuration](/fr/gateway/configuration) pour le schéma complet.
|
||||
Voir [Configuration](/fr/gateway/configuration) pour le schéma complet.
|
||||
|
||||
## Déduplication entrante
|
||||
|
||||
Les canaux peuvent relivrer le même message après des reconnexions. OpenClaw conserve un cache de courte durée indexé par canal/compte/pair/session/ID de message, afin que les livraisons en double ne déclenchent pas une autre exécution de l’agent.
|
||||
Les canaux peuvent renvoyer le même message après des reconnexions. OpenClaw conserve un
|
||||
cache de courte durée indexé par canal/compte/paire/session/identifiant de message afin que les livraisons
|
||||
dupliquées ne déclenchent pas une autre exécution d’agent.
|
||||
|
||||
## Anti-rebond entrant
|
||||
|
||||
Les messages consécutifs rapides provenant du **même expéditeur** peuvent être regroupés en un seul tour d’agent via `messages.inbound`. L’anti-rebond est limité à chaque canal + conversation et utilise le message le plus récent pour le fil de réponse et les ID.
|
||||
Des messages rapides et consécutifs du **même expéditeur** peuvent être regroupés en un seul
|
||||
tour d’agent via `messages.inbound`. L’anti-rebond est limité à chaque canal + conversation
|
||||
et utilise le message le plus récent pour le threading et les identifiants de réponse.
|
||||
|
||||
Configuration (valeur globale par défaut + remplacements par canal) :
|
||||
|
||||
@ -61,37 +65,46 @@ Configuration (valeur globale par défaut + remplacements par canal) :
|
||||
|
||||
Notes :
|
||||
|
||||
- L’anti-rebond s’applique aux messages **texte uniquement** ; les médias/pièces jointes sont vidés immédiatement.
|
||||
- Les commandes de contrôle contournent l’anti-rebond afin de rester autonomes — **sauf** lorsqu’un canal opte explicitement pour la fusion des DM du même expéditeur (par ex. [BlueBubbles `coalesceSameSenderDms`](/fr/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), où les commandes DM attendent dans la fenêtre d’anti-rebond afin qu’une charge utile envoyée en plusieurs parties puisse rejoindre le même tour d’agent.
|
||||
- L’anti-rebond s’applique aux messages **texte uniquement** ; les médias/pièces jointes sont envoyés immédiatement.
|
||||
- Les commandes de contrôle contournent l’anti-rebond afin de rester autonomes — **sauf** lorsqu’un canal choisit explicitement de regrouper les DM du même expéditeur (par exemple [BlueBubbles `coalesceSameSenderDms`](/fr/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), où les commandes DM attendent dans la fenêtre d’anti-rebond afin qu’une charge utile envoyée en plusieurs parties puisse rejoindre le même tour d’agent.
|
||||
|
||||
## Sessions et appareils
|
||||
|
||||
Les sessions appartiennent au Gateway, pas aux clients.
|
||||
|
||||
- Les discussions directes sont regroupées dans la clé de session principale de l’agent.
|
||||
- Les discussions directes sont ramenées à la clé de session principale de l’agent.
|
||||
- Les groupes/canaux obtiennent leurs propres clés de session.
|
||||
- Le magasin de sessions et les transcriptions résident sur l’hôte Gateway.
|
||||
- Le stockage des sessions et les transcriptions résident sur l’hôte du Gateway.
|
||||
|
||||
Plusieurs appareils/canaux peuvent correspondre à la même session, mais l’historique n’est pas entièrement resynchronisé vers chaque client. Recommandation : utilisez un appareil principal pour les longues conversations afin d’éviter un contexte divergent. L’interface de contrôle et la TUI affichent toujours la transcription de session fournie par le Gateway ; elles constituent donc la source de vérité.
|
||||
Plusieurs appareils/canaux peuvent pointer vers la même session, mais l’historique n’est pas entièrement
|
||||
resynchronisé vers chaque client. Recommandation : utilisez un appareil principal pour les longues
|
||||
conversations afin d’éviter un contexte divergent. L’interface de contrôle et la TUI affichent toujours la
|
||||
transcription de session adossée au Gateway ; elles constituent donc la source de vérité.
|
||||
|
||||
Détails : [Gestion des sessions](/fr/concepts/session).
|
||||
|
||||
## Métadonnées des résultats d’outil
|
||||
|
||||
Le `content` d’un résultat d’outil est le résultat visible par le modèle. Les `details` d’un résultat d’outil sont les métadonnées d’exécution destinées au rendu de l’interface, aux diagnostics, à la livraison de médias et aux plugins.
|
||||
Le `content` d’un résultat d’outil est le résultat visible par le modèle. Le `details` d’un résultat d’outil contient
|
||||
les métadonnées d’exécution pour le rendu d’interface, les diagnostics, la livraison de médias et les plugins.
|
||||
|
||||
OpenClaw garde cette frontière explicite :
|
||||
|
||||
- `toolResult.details` est retiré avant la relecture par le fournisseur et l’entrée de Compaction.
|
||||
- Les transcriptions de session persistées ne conservent que des `details` bornés ; les métadonnées trop volumineuses sont remplacées par un résumé compact marqué `persistedDetailsTruncated: true`.
|
||||
- Les plugins et outils doivent placer le texte que le modèle doit lire dans `content`, et pas seulement dans `details`.
|
||||
- `toolResult.details` est supprimé avant la relecture par le fournisseur et l’entrée de compaction.
|
||||
- Les transcriptions de session persistées ne conservent que des `details` bornés ; les métadonnées trop volumineuses
|
||||
sont remplacées par un résumé compact marqué `persistedDetailsTruncated: true`.
|
||||
- Les plugins et les outils doivent placer le texte que le modèle doit lire dans `content`, pas seulement
|
||||
dans `details`.
|
||||
|
||||
## Corps entrants et contexte d’historique
|
||||
|
||||
OpenClaw sépare le **corps de prompt** du **corps de commande** :
|
||||
|
||||
- `BodyForAgent` : texte principal destiné au modèle pour le message actuel. Les plugins de canal doivent le garder centré sur le texte actuel de l’expéditeur qui porte le prompt.
|
||||
- `Body` : solution de repli historique pour le prompt. Cela peut inclure des enveloppes de canal et des wrappers d’historique facultatifs, mais les canaux actuels ne doivent pas s’y fier comme entrée principale du modèle lorsque `BodyForAgent` est disponible.
|
||||
- `BodyForAgent` : texte principal destiné au modèle pour le message actuel. Les plugins de canal
|
||||
doivent le garder centré sur le texte actuel de l’expéditeur qui porte le prompt.
|
||||
- `Body` : repli de prompt historique. Il peut inclure des enveloppes de canal et
|
||||
des wrappers d’historique facultatifs, mais les canaux actuels ne doivent pas s’y fier comme
|
||||
entrée principale du modèle lorsque `BodyForAgent` est disponible.
|
||||
- `CommandBody` : texte utilisateur brut pour l’analyse des directives/commandes.
|
||||
- `RawBody` : alias historique de `CommandBody` (conservé pour compatibilité).
|
||||
|
||||
@ -100,30 +113,48 @@ Lorsqu’un canal fournit un historique, il utilise un wrapper partagé :
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
Pour les **discussions non directes** (groupes/canaux/salons), le **corps du message actuel** est préfixé par le libellé de l’expéditeur (même style que celui utilisé pour les entrées d’historique). Cela garantit la cohérence des messages en temps réel et des messages mis en file d’attente/historique dans le prompt de l’agent.
|
||||
Pour les **discussions non directes** (groupes/canaux/salles), le **corps du message actuel** est préfixé par le
|
||||
libellé de l’expéditeur (dans le même style que les entrées d’historique). Cela maintient la cohérence des messages en temps réel et en file d’attente/historique
|
||||
dans le prompt de l’agent.
|
||||
|
||||
Les tampons d’historique sont **uniquement en attente** : ils incluent les messages de groupe qui n’ont _pas_ déclenché d’exécution (par exemple, les messages filtrés par mention) et **excluent** les messages déjà présents dans la transcription de session.
|
||||
Les tampons d’historique sont **uniquement en attente** : ils incluent les messages de groupe qui n’ont _pas_
|
||||
déclenché d’exécution (par exemple, les messages soumis à une mention) et **excluent** les messages
|
||||
déjà présents dans la transcription de session.
|
||||
|
||||
La suppression des directives ne s’applique qu’à la section du **message actuel**, afin que l’historique reste intact. Les canaux qui enveloppent l’historique doivent définir `CommandBody` (ou `RawBody`) sur le texte du message original et conserver `Body` comme prompt combiné. L’historique structuré, les réponses, les messages transférés et les métadonnées de canal sont rendus comme des blocs de contexte non fiables de rôle utilisateur lors de l’assemblage du prompt.
|
||||
Les tampons d’historique sont configurables via `messages.groupChat.historyLimit` (valeur globale par défaut) et les remplacements par canal comme `channels.slack.historyLimit` ou `channels.telegram.accounts.<id>.historyLimit` (définissez `0` pour désactiver).
|
||||
La suppression des directives ne s’applique qu’à la section du **message actuel**, afin que l’historique
|
||||
reste intact. Les canaux qui enveloppent l’historique doivent définir `CommandBody` (ou
|
||||
`RawBody`) sur le texte original du message et conserver `Body` comme prompt combiné.
|
||||
L’historique structuré, les réponses, les transferts et les métadonnées de canal sont rendus comme
|
||||
blocs de contexte non fiable au rôle utilisateur lors de l’assemblage du prompt.
|
||||
Les tampons d’historique sont configurables via `messages.groupChat.historyLimit` (valeur globale
|
||||
par défaut) et des remplacements par canal comme `channels.slack.historyLimit` ou
|
||||
`channels.telegram.accounts.<id>.historyLimit` (définissez `0` pour désactiver).
|
||||
|
||||
## Mise en file d’attente et suivis
|
||||
|
||||
Si une exécution est déjà active, les messages entrants peuvent être mis en file d’attente, orientés vers l’exécution actuelle ou collectés pour un tour de suivi.
|
||||
Si une exécution est déjà active, les messages entrants peuvent être mis en file d’attente, orientés vers
|
||||
l’exécution actuelle ou collectés pour un tour de suivi.
|
||||
|
||||
- Configurez via `messages.queue` (et `messages.queue.byChannel`).
|
||||
- Le mode par défaut est `steer`, avec un anti-rebond de suivi de 500 ms lorsque le guidage retombe sur la livraison de suivi en file d’attente.
|
||||
- Modes : `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` et le mode historique un-à-la-fois `queue`.
|
||||
- Le mode par défaut est `steer`, avec un anti-rebond de suivi de 500 ms lorsque l’orientation revient
|
||||
à une livraison de suivi mise en file d’attente.
|
||||
- Modes : `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` et le mode historique
|
||||
un-à-la-fois `queue`.
|
||||
|
||||
Détails : [File d’attente des commandes](/fr/concepts/queue) et [File d’attente de guidage](/fr/concepts/queue-steering).
|
||||
Détails : [File de commandes](/fr/concepts/queue) et [File d’orientation](/fr/concepts/queue-steering).
|
||||
|
||||
## Propriété des exécutions de canal
|
||||
## Propriété d’exécution des canaux
|
||||
|
||||
Les plugins de canal peuvent préserver l’ordre, appliquer un anti-rebond aux entrées et appliquer une contre-pression de transport avant qu’un message n’entre dans la file de session. Ils ne doivent pas imposer un délai d’expiration séparé autour du tour d’agent lui-même. Une fois qu’un message est routé vers une session, les travaux de longue durée sont régis par le cycle de vie de la session, des outils et du runtime, afin que tous les canaux signalent les tours lents et s’en rétablissent de manière cohérente.
|
||||
Les plugins de canal peuvent préserver l’ordre, appliquer un anti-rebond à l’entrée et appliquer une contre-pression
|
||||
de transport avant qu’un message n’entre dans la file de session. Ils ne doivent pas imposer de
|
||||
délai d’expiration séparé autour du tour d’agent lui-même. Une fois qu’un message est routé vers une
|
||||
session, les travaux de longue durée sont régis par la session, l’outil et le cycle de vie
|
||||
d’exécution, afin que tous les canaux signalent les tours lents et s’en remettent de manière cohérente.
|
||||
|
||||
## Streaming, découpage et regroupement
|
||||
|
||||
Le streaming par blocs envoie des réponses partielles à mesure que le modèle produit des blocs de texte. Le découpage respecte les limites de texte des canaux et évite de diviser les blocs de code clôturés.
|
||||
Le streaming par blocs envoie des réponses partielles à mesure que le modèle produit des blocs de texte.
|
||||
Le découpage respecte les limites de texte du canal et évite de scinder les blocs de code clôturés.
|
||||
|
||||
Paramètres clés :
|
||||
|
||||
@ -132,44 +163,53 @@ Paramètres clés :
|
||||
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
|
||||
- `agents.defaults.blockStreamingCoalesce` (regroupement basé sur l’inactivité)
|
||||
- `agents.defaults.humanDelay` (pause de type humain entre les réponses par blocs)
|
||||
- Remplacements par canal : `*.blockStreaming` et `*.blockStreamingCoalesce` (les canaux autres que Telegram exigent un `*.blockStreaming: true` explicite)
|
||||
- Remplacements par canal : `*.blockStreaming` et `*.blockStreamingCoalesce` (les canaux non-Telegram nécessitent un `*.blockStreaming: true` explicite)
|
||||
|
||||
Détails : [Streaming + découpage](/fr/concepts/streaming).
|
||||
|
||||
## Visibilité du raisonnement et jetons
|
||||
## Visibilité du raisonnement et tokens
|
||||
|
||||
OpenClaw peut exposer ou masquer le raisonnement du modèle :
|
||||
|
||||
- `/reasoning on|off|stream` contrôle la visibilité.
|
||||
- Le contenu de raisonnement compte quand même dans l’utilisation des jetons lorsqu’il est produit par le modèle.
|
||||
- Telegram prend en charge le flux de raisonnement dans la bulle de brouillon.
|
||||
- Le contenu de raisonnement compte toujours dans l’utilisation des tokens lorsqu’il est produit par le modèle.
|
||||
- Telegram prend en charge le flux de raisonnement dans une bulle de brouillon transitoire supprimée après la livraison finale ; utilisez `/reasoning on` pour une sortie de raisonnement persistante.
|
||||
|
||||
Détails : [Directives de réflexion + raisonnement](/fr/tools/thinking) et [Utilisation des jetons](/fr/reference/token-use).
|
||||
Détails : [Directives de pensée + raisonnement](/fr/tools/thinking) et [Utilisation des tokens](/fr/reference/token-use).
|
||||
|
||||
## Préfixes, fils et réponses
|
||||
## Préfixes, threading et réponses
|
||||
|
||||
Le formatage des messages sortants est centralisé dans `messages` :
|
||||
La mise en forme des messages sortants est centralisée dans `messages` :
|
||||
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` et `channels.<channel>.accounts.<id>.responsePrefix` (cascade de préfixes sortants), plus `channels.whatsapp.messagePrefix` (préfixe entrant WhatsApp)
|
||||
- Fil de réponse via `replyToMode` et valeurs par défaut par canal
|
||||
- Threading des réponses via `replyToMode` et les valeurs par défaut par canal
|
||||
|
||||
Détails : [Configuration](/fr/gateway/config-agents#messages) et documentation des canaux.
|
||||
|
||||
## Réponses silencieuses
|
||||
|
||||
Le jeton silencieux exact `NO_REPLY` / `no_reply` signifie « ne pas livrer de réponse visible par l’utilisateur ».
|
||||
Lorsqu’un tour comporte aussi un média d’outil en attente, comme un audio TTS généré, OpenClaw retire le texte silencieux mais livre quand même la pièce jointe multimédia.
|
||||
Le token silencieux exact `NO_REPLY` / `no_reply` signifie « ne pas livrer de réponse visible par l’utilisateur ».
|
||||
Lorsqu’un tour contient aussi des médias d’outil en attente, comme un audio TTS généré, OpenClaw
|
||||
supprime le texte silencieux mais livre quand même la pièce jointe média.
|
||||
OpenClaw résout ce comportement selon le type de conversation :
|
||||
|
||||
- Les conversations directes interdisent le silence par défaut et réécrivent une réponse silencieuse nue en une courte solution de repli visible.
|
||||
- Les conversations directes interdisent le silence par défaut et réécrivent une réponse
|
||||
silencieuse seule en un court repli visible.
|
||||
- Les groupes/canaux autorisent le silence par défaut.
|
||||
- L’orchestration interne autorise le silence par défaut.
|
||||
|
||||
OpenClaw utilise également les réponses silencieuses pour les échecs internes du runner qui se produisent avant toute réponse de l’assistant dans les discussions non directes, afin que les groupes/canaux ne voient pas de texte d’erreur standard du Gateway. Les discussions directes affichent par défaut un texte d’échec compact ; les détails bruts du runner ne sont affichés que lorsque `/verbose` est `on` ou `full`.
|
||||
OpenClaw utilise aussi les réponses silencieuses pour les échecs internes d’exécuteur qui surviennent
|
||||
avant toute réponse d’assistant dans les discussions non directes, afin que les groupes/canaux ne voient pas
|
||||
de texte passe-partout d’erreur du Gateway. Les discussions directes affichent par défaut une copie d’échec compacte ;
|
||||
les détails bruts de l’exécuteur ne sont affichés que lorsque `/verbose` est `on` ou `full`.
|
||||
|
||||
Les valeurs par défaut se trouvent sous `agents.defaults.silentReply` et `agents.defaults.silentReplyRewrite` ; `surfaces.<id>.silentReply` et `surfaces.<id>.silentReplyRewrite` peuvent les remplacer par surface.
|
||||
Les valeurs par défaut résident sous `agents.defaults.silentReply` et
|
||||
`agents.defaults.silentReplyRewrite` ; `surfaces.<id>.silentReply` et
|
||||
`surfaces.<id>.silentReplyRewrite` peuvent les remplacer par surface.
|
||||
|
||||
Lorsque la session parente comporte une ou plusieurs exécutions de sous-agent lancé en attente, les réponses silencieuses nues sont supprimées sur toutes les surfaces au lieu d’être réécrites, afin que le parent reste silencieux jusqu’à ce que l’événement de fin de l’enfant livre la vraie réponse.
|
||||
Lorsque la session parente possède une ou plusieurs exécutions de sous-agent engendrées en attente, les réponses
|
||||
silencieuses seules sont supprimées sur toutes les surfaces au lieu d’être réécrites, afin que le
|
||||
parent reste silencieux jusqu’à ce que l’événement d’achèvement enfant livre la vraie réponse.
|
||||
|
||||
## Connexe
|
||||
|
||||
|
||||
@ -1,23 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurer les mises à jour de progression visibles pour les tours de conversation de longue durée
|
||||
- Choisir entre les modes de diffusion partielle, par bloc et avec progression
|
||||
- Explication de la manière dont OpenClaw met à jour un seul message de canal pendant que le travail est en cours
|
||||
- Dépannage des brouillons de progression, des messages de progression autonomes ou du mécanisme de repli de finalisation
|
||||
summary: 'Brouillons de progression : un seul message visible de travail en cours qui se met à jour pendant l’exécution d’un agent'
|
||||
title: Brouillons d’avancement
|
||||
- Configuration des mises à jour de progression visibles pour les tours de conversation de longue durée
|
||||
- Choisir entre les modes de diffusion partielle, par bloc et de progression
|
||||
- Explication de la manière dont OpenClaw met à jour un message de canal pendant que le travail est en cours
|
||||
- Résolution des problèmes liés aux brouillons de progression, aux messages de progression autonomes ou à la solution de repli de finalisation
|
||||
summary: 'Brouillons de progression : un message visible de travail en cours qui se met à jour pendant l’exécution d’un agent'
|
||||
title: Avancer les brouillons
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:31Z"
|
||||
generated_at: "2026-05-04T07:04:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
|
||||
source_hash: f78c07866cd7f613012a80a40413e5866c1dd2edd477088f9fc141347f5f3788
|
||||
source_path: concepts/progress-drafts.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Les brouillons de progression donnent vie aux longues interactions d’agent dans le chat sans transformer la conversation en pile de réponses d’état temporaires.
|
||||
Les brouillons de progression donnent de la vie aux tours d’agent longs dans le chat sans transformer
|
||||
la conversation en pile de réponses d’état temporaires.
|
||||
|
||||
Lorsque les brouillons de progression sont activés, OpenClaw crée un seul message visible de travail en cours uniquement après que l’interaction a prouvé qu’elle effectue un vrai travail, le met à jour pendant que l’agent lit, planifie, appelle des outils ou attend une approbation, puis transforme ce brouillon en réponse finale lorsque le canal peut le faire en toute sécurité.
|
||||
Lorsque les brouillons de progression sont activés, OpenClaw crée un seul message visible
|
||||
de travail en cours seulement une fois que le tour prouve qu’il effectue un vrai travail,
|
||||
le met à jour pendant que l’agent lit, planifie, appelle des outils ou attend une approbation,
|
||||
puis transforme ce brouillon en réponse finale lorsque le canal peut le faire en toute sécurité.
|
||||
|
||||
```text
|
||||
Shelling...
|
||||
@ -26,7 +30,8 @@ Shelling...
|
||||
🛠️ Exec: run tests
|
||||
```
|
||||
|
||||
Utilisez les brouillons de progression lorsque vous voulez un seul message d’état propre pendant un travail intensif en outils, puis la réponse finale une fois l’interaction terminée.
|
||||
Utilisez les brouillons de progression lorsque vous voulez un seul message d’état bien rangé
|
||||
pendant un travail intensif en outils, puis la réponse finale une fois le tour terminé.
|
||||
|
||||
## Démarrage rapide
|
||||
|
||||
@ -44,42 +49,59 @@ Activez les brouillons de progression par canal avec `streaming.mode: "progress"
|
||||
}
|
||||
```
|
||||
|
||||
Cela suffit généralement. OpenClaw choisira une étiquette automatique d’un mot, attendra que le travail dure au moins cinq secondes ou émette un deuxième événement de travail, ajoutera des lignes de progression compactes pendant l’exécution d’un travail utile, et supprimera les bavardages de progression autonomes en double pour cette interaction.
|
||||
C’est généralement suffisant. OpenClaw choisira automatiquement un libellé d’un mot,
|
||||
attendra que le travail dure au moins cinq secondes ou émette un second événement de travail,
|
||||
ajoutera des lignes de progression compactes pendant que du travail utile a lieu,
|
||||
et supprimera les messages de progression autonomes en double pour ce tour.
|
||||
|
||||
## Ce que voient les utilisateurs
|
||||
|
||||
Un brouillon de progression comporte deux parties :
|
||||
|
||||
| Partie | Objectif |
|
||||
| --------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| Étiquette | Un titre court comme `Thinking...` ou `Shelling...`. |
|
||||
| Partie | Objectif |
|
||||
| --------------------- | ----------------------------------------------------------------------------------- |
|
||||
| Libellé | Un court titre comme `Thinking...` ou `Shelling...`. |
|
||||
| Lignes de progression | Des mises à jour d’exécution compactes utilisant les mêmes libellés et icônes d’outils que la sortie détaillée. |
|
||||
|
||||
L’étiquette apparaît après que l’agent commence un travail significatif et reste occupé pendant cinq secondes ou émet un deuxième événement de travail. Les réponses en texte brut uniquement n’affichent pas de brouillon de progression. Les lignes de progression ne sont ajoutées que lorsque l’agent émet des mises à jour de travail utiles, par exemple `🛠️ Exec`, `🔎 Web Search` ou `✍️ Write: to /tmp/file`. Par défaut, elles utilisent le même mode d’explication compact que `/verbose` ; définissez `agents.defaults.toolProgressDetail: "raw"` lors du débogage si vous voulez aussi ajouter les commandes/détails bruts.
|
||||
La réponse finale remplace le brouillon lorsque c’est possible ; sinon, OpenClaw envoie normalement la réponse finale et nettoie le brouillon ou cesse de le mettre à jour selon le transport du canal.
|
||||
Le libellé apparaît lorsque l’agent commence un travail significatif et reste occupé
|
||||
pendant cinq secondes ou émet un second événement de travail. Les réponses en texte seul
|
||||
n’affichent pas de brouillon de progression. Les lignes de progression ne sont ajoutées
|
||||
que lorsque l’agent émet des mises à jour de travail utiles, par exemple `🛠️ Exec`,
|
||||
`🔎 Web Search` ou `✍️ Write: to /tmp/file`.
|
||||
Par défaut, elles utilisent le même mode d’explication compact que `/verbose` ; définissez
|
||||
`agents.defaults.toolProgressDetail: "raw"` lors du débogage si vous voulez aussi ajouter
|
||||
les commandes/détails bruts.
|
||||
La réponse finale remplace le brouillon lorsque c’est possible ; sinon
|
||||
OpenClaw envoie la réponse finale normalement et nettoie le brouillon ou arrête de le mettre
|
||||
à jour selon le transport du canal.
|
||||
|
||||
## Choisir un mode
|
||||
|
||||
`channels.<channel>.streaming.mode` contrôle le comportement visible en cours :
|
||||
|
||||
| Mode | Idéal pour | Ce qui apparaît dans le chat |
|
||||
| ---------- | ---------------------------------------------- | --------------------------------------------------------- |
|
||||
| `off` | Canaux silencieux | Uniquement la réponse finale. |
|
||||
| `partial` | Observer l’apparition du texte de la réponse | Un brouillon modifié avec le texte de réponse le plus récent. |
|
||||
| `block` | Morceaux d’aperçu de réponse plus grands | Un aperçu mis à jour ou ajouté en morceaux plus grands. |
|
||||
| `progress` | Interactions longues ou intensives en outils | Un brouillon d’état, puis la réponse finale. |
|
||||
| Mode | Idéal pour | Ce qui apparaît dans le chat |
|
||||
| ---------- | ------------------------------------------ | ---------------------------------------------------- |
|
||||
| `off` | Canaux silencieux | Uniquement la réponse finale. |
|
||||
| `partial` | Regarder le texte de réponse apparaître | Un brouillon modifié avec le dernier texte de réponse. |
|
||||
| `block` | Morceaux d’aperçu de réponse plus grands | Un aperçu mis à jour ou ajouté par gros morceaux. |
|
||||
| `progress` | Tours longs ou avec beaucoup d’outils | Un brouillon d’état, puis la réponse finale. |
|
||||
|
||||
Choisissez `progress` lorsque les utilisateurs s’intéressent davantage à « ce qui se passe » qu’à voir le texte de réponse défiler jeton par jeton.
|
||||
Choisissez `progress` lorsque les utilisateurs se soucient davantage de « ce qui se passe »
|
||||
que de voir le texte de la réponse défiler jeton par jeton.
|
||||
|
||||
Choisissez `partial` lorsque la réponse elle-même est le signal de progression.
|
||||
|
||||
Choisissez `block` lorsque vous voulez des mises à jour de brouillon d’aperçu en morceaux de texte plus grands. Sur Discord et Telegram, `streaming.mode: "block"` reste du streaming d’aperçu, pas une livraison normale par blocs. Utilisez `streaming.block.enabled` ou l’ancien `blockStreaming` lorsque vous voulez des réponses normales par blocs.
|
||||
Choisissez `block` lorsque vous voulez des mises à jour d’aperçu du brouillon en morceaux
|
||||
de texte plus grands. Sur Discord et Telegram, `streaming.mode: "block"` reste une diffusion
|
||||
d’aperçu, pas une livraison normale par blocs. Utilisez `streaming.block.enabled` ou l’ancien
|
||||
`blockStreaming` lorsque vous voulez des réponses normales par blocs.
|
||||
|
||||
## Configurer les étiquettes
|
||||
## Configurer les libellés
|
||||
|
||||
Les étiquettes de progression se trouvent sous `channels.<channel>.streaming.progress`.
|
||||
Les libellés de progression se trouvent sous `channels.<channel>.streaming.progress`.
|
||||
|
||||
L’étiquette par défaut est `auto`, qui choisit dans le groupe d’étiquettes intégrées d’OpenClaw, composées d’un seul mot avec points de suspension :
|
||||
Le libellé par défaut est `auto`, qui choisit dans le groupe intégré de libellés
|
||||
OpenClaw d’un seul mot avec points de suspension :
|
||||
|
||||
```text
|
||||
Thinking...
|
||||
@ -104,7 +126,7 @@ Snapping...
|
||||
Surfacing...
|
||||
```
|
||||
|
||||
Utilisez une étiquette fixe :
|
||||
Utilisez un libellé fixe :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -121,7 +143,7 @@ Utilisez une étiquette fixe :
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez votre propre groupe d’étiquettes automatiques :
|
||||
Utilisez votre propre groupe de libellés automatiques :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -139,7 +161,7 @@ Utilisez votre propre groupe d’étiquettes automatiques :
|
||||
}
|
||||
```
|
||||
|
||||
Masquez l’étiquette et n’affichez que les lignes de progression :
|
||||
Masquez le libellé et affichez uniquement les lignes de progression :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -158,7 +180,9 @@ Masquez l’étiquette et n’affichez que les lignes de progression :
|
||||
|
||||
## Contrôler les lignes de progression
|
||||
|
||||
Les lignes de progression sont activées par défaut en mode progression. Elles proviennent d’événements d’exécution réels : démarrages d’outils, mises à jour d’éléments, plans de tâche, approbations, sortie de commande, résumés de correctifs et activités similaires de l’agent.
|
||||
Les lignes de progression sont activées par défaut en mode progression. Elles proviennent
|
||||
d’événements d’exécution réels : démarrages d’outils, mises à jour d’éléments, plans de tâche,
|
||||
approbations, sortie de commande, résumés de correctifs et activité d’agent similaire.
|
||||
|
||||
OpenClaw utilise le même formateur pour les brouillons de progression et `/verbose` :
|
||||
|
||||
@ -172,13 +196,16 @@ OpenClaw utilise le même formateur pour les brouillons de progression et `/verb
|
||||
}
|
||||
```
|
||||
|
||||
`"explain"` est la valeur par défaut et maintient les brouillons stables avec des libellés concis comme `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` ajoute la commande ou le détail sous-jacent lorsque disponible, ce qui est utile pendant le débogage mais plus bruyant dans le chat.
|
||||
`"explain"` est la valeur par défaut et garde les brouillons stables avec des libellés concis
|
||||
comme `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` ajoute la commande ou le détail
|
||||
sous-jacent lorsqu’il est disponible, ce qui est utile pendant le débogage mais plus bruyant
|
||||
dans le chat.
|
||||
|
||||
Par exemple, la même commande apparaît différemment selon le mode de détail :
|
||||
|
||||
| Mode | Ligne de progression |
|
||||
| --------- | ---------------------------------------------------------------- |
|
||||
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
|
||||
| Mode | Ligne de progression |
|
||||
| --------- | ----------------------------------------------------------------- |
|
||||
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
|
||||
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
|
||||
|
||||
Limitez le nombre de lignes qui restent visibles :
|
||||
@ -198,7 +225,37 @@ Limitez le nombre de lignes qui restent visibles :
|
||||
}
|
||||
```
|
||||
|
||||
Conservez le brouillon de progression unique, mais masquez les lignes d’outils et de tâches :
|
||||
Les lignes de progression sont compactées automatiquement afin de réduire les redispositions
|
||||
des bulles de chat pendant la modification du brouillon.
|
||||
|
||||
OpenClaw tronque par défaut les longues lignes de progression afin que les modifications
|
||||
répétées du brouillon ne passent pas à la ligne différemment à chaque mise à jour. Le préfixe
|
||||
reste lisible, et les longs détails comme les chemins ou les commandes brutes sont raccourcis
|
||||
avec des points de suspension.
|
||||
|
||||
Slack peut rendre les lignes de progression sous forme de champs Block Kit structurés au lieu
|
||||
d’un seul corps de texte :
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
slack: {
|
||||
streaming: {
|
||||
mode: "progress",
|
||||
progress: {
|
||||
render: "rich",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Le rendu riche conserve le même repli en texte brut afin que les canaux et clients qui ne
|
||||
prennent pas en charge la forme plus riche puissent tout de même afficher le texte de progression
|
||||
compact.
|
||||
|
||||
Conservez le brouillon de progression unique mais masquez les lignes d’outils et de tâches :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -215,58 +272,79 @@ Conservez le brouillon de progression unique, mais masquez les lignes d’outils
|
||||
}
|
||||
```
|
||||
|
||||
Avec `toolProgress: false`, OpenClaw supprime toujours les anciens messages autonomes de progression d’outils pour cette interaction. Le canal reste visuellement discret jusqu’à la réponse finale, sauf pour l’étiquette si elle est configurée.
|
||||
Avec `toolProgress: false`, OpenClaw supprime toujours les anciens messages autonomes de
|
||||
progression des outils pour ce tour. Le canal reste visuellement silencieux jusqu’à la réponse
|
||||
finale, sauf pour le libellé si l’un est configuré.
|
||||
|
||||
## Comportement des canaux
|
||||
|
||||
Chaque canal utilise le transport le plus propre qu’il prend en charge :
|
||||
|
||||
| Canal | Transport de progression | Remarques |
|
||||
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Discord | Envoyer un message, puis le modifier. | Le texte final est modifié sur place lorsqu’il tient dans un seul message d’aperçu sûr. |
|
||||
| Matrix | Envoyer un événement, puis le modifier. | La configuration de streaming au niveau du compte contrôle les brouillons au niveau du compte. |
|
||||
| Microsoft Teams | Flux Teams natif dans les chats personnels. | `streaming.mode: "block"` correspond à la livraison par blocs de Teams. |
|
||||
| Canal | Transport de progression | Notes |
|
||||
| --------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| Discord | Envoyer un message, puis le modifier. | Le texte final est modifié sur place lorsqu’il tient dans un message d’aperçu sûr. |
|
||||
| Matrix | Envoyer un événement, puis le modifier. | La configuration de streaming au niveau du compte contrôle les brouillons au niveau du compte. |
|
||||
| Microsoft Teams | Flux Teams natif dans les conversations personnelles. | `streaming.mode: "block"` correspond à la livraison par blocs Teams. |
|
||||
| Slack | Flux natif ou publication de brouillon modifiable. | La disponibilité du fil affecte la possibilité d’utiliser le streaming natif. |
|
||||
| Telegram | Envoyer un message, puis le modifier. | Les anciens brouillons visibles peuvent être remplacés pour que les horodatages finaux restent utiles. |
|
||||
| Mattermost | Publication de brouillon modifiable. | L’activité des outils est intégrée dans la même publication de type brouillon. |
|
||||
| Telegram | Envoyer un message, puis le modifier. | Les anciens brouillons visibles peuvent être remplacés pour que les horodatages finaux restent utiles. |
|
||||
| Mattermost | Publication de brouillon modifiable. | L’activité des outils est intégrée à la même publication de style brouillon. |
|
||||
|
||||
Les canaux sans prise en charge sûre de la modification reviennent généralement aux indicateurs de saisie ou à une livraison uniquement finale.
|
||||
Les canaux sans prise en charge sûre de la modification se replient généralement sur les
|
||||
indicateurs de saisie ou la livraison finale uniquement.
|
||||
|
||||
## Finalisation
|
||||
|
||||
Lorsque la réponse finale est prête, OpenClaw essaie de garder le chat propre :
|
||||
Lorsque la réponse finale est prête, OpenClaw tente de garder le chat propre :
|
||||
|
||||
- Si le brouillon peut devenir la réponse finale en toute sécurité, OpenClaw le modifie sur place.
|
||||
- Si le canal utilise le streaming de progression natif, OpenClaw finalise ce flux lorsque le transport natif accepte le texte final.
|
||||
- Si la réponse finale contient des médias, une invite d’approbation, une cible de réponse explicite, trop de morceaux, ou une modification/un envoi échoué, OpenClaw envoie la réponse finale par le chemin de livraison normal du canal.
|
||||
- Si le canal utilise un streaming de progression natif, OpenClaw finalise ce flux
|
||||
lorsque le transport natif accepte le texte final.
|
||||
- Si la réponse finale contient des médias, une demande d’approbation, une cible de réponse explicite,
|
||||
trop de morceaux, ou un échec de modification/envoi, OpenClaw envoie la réponse finale via
|
||||
le chemin normal de livraison du canal.
|
||||
|
||||
Le chemin de repli est intentionnel. Il vaut mieux envoyer une nouvelle réponse finale que perdre du texte, mal placer une réponse dans un fil, ou écraser un brouillon avec une charge utile que le canal ne peut pas représenter en toute sécurité.
|
||||
Le chemin de repli est intentionnel. Il vaut mieux envoyer une nouvelle réponse finale que
|
||||
perdre du texte, envoyer une réponse dans le mauvais fil ou remplacer un brouillon par une charge utile
|
||||
que le canal ne peut pas représenter en toute sécurité.
|
||||
|
||||
## Dépannage
|
||||
|
||||
**Je ne vois que la réponse finale.**
|
||||
|
||||
Vérifiez que `channels.<channel>.streaming.mode` est défini sur `progress` pour le compte ou le canal qui a traité le message. Certains chemins de groupe ou de réponse avec citation peuvent désactiver les aperçus de brouillon pour une interaction lorsque le canal ne peut pas modifier en toute sécurité le bon message.
|
||||
Vérifiez que `channels.<channel>.streaming.mode` est défini sur `progress` pour le compte
|
||||
ou le canal qui a traité le message. Certains chemins de groupe ou de réponse avec citation
|
||||
peuvent désactiver les aperçus de brouillon pour un tour lorsque le canal ne peut pas modifier
|
||||
en toute sécurité le bon message.
|
||||
|
||||
**Je vois l’étiquette, mais aucune ligne d’outil.**
|
||||
**Je vois le libellé mais aucune ligne d’outil.**
|
||||
|
||||
Vérifiez `streaming.progress.toolProgress`. Si la valeur est `false`, OpenClaw conserve le comportement de brouillon unique, mais masque les lignes de progression d’outils et de tâches.
|
||||
Vérifiez `streaming.progress.toolProgress`. S’il vaut `false`, OpenClaw conserve le
|
||||
comportement de brouillon unique mais masque les lignes de progression des outils et des tâches.
|
||||
|
||||
**Je vois un nouveau message final au lieu d’un brouillon modifié.**
|
||||
|
||||
Il s’agit d’un repli de sécurité. Cela peut se produire pour les réponses avec médias, les réponses longues, les cibles de réponse explicites, les anciens brouillons Telegram, les cibles de fil Slack manquantes, les messages d’aperçu supprimés ou l’échec de la finalisation d’un flux natif.
|
||||
Il s’agit d’un repli de sécurité. Cela peut se produire pour les réponses avec médias,
|
||||
les longues réponses, les cibles de réponse explicites, les anciens brouillons Telegram,
|
||||
les cibles de fil Slack manquantes, les messages d’aperçu supprimés ou l’échec de finalisation
|
||||
d’un flux natif.
|
||||
|
||||
**Je vois encore des messages de progression autonomes.**
|
||||
|
||||
Le mode progression supprime les messages autonomes de progression d’outils par défaut lorsqu’un brouillon est actif. Si des messages autonomes apparaissent encore, vérifiez que l’interaction utilise réellement le mode progression et non `streaming.mode: "off"` ou un chemin de canal qui ne peut pas créer de brouillon pour ce message.
|
||||
Le mode progression supprime les messages de progression d’outils autonomes par défaut lorsqu’un
|
||||
brouillon est actif. Si des messages autonomes apparaissent encore, vérifiez que le tour utilise
|
||||
bien le mode progression et non `streaming.mode: "off"` ou un chemin de canal qui ne peut pas
|
||||
créer de brouillon pour ce message.
|
||||
|
||||
**Teams se comporte différemment de Discord ou Telegram.**
|
||||
|
||||
Microsoft Teams utilise un flux natif dans les chats personnels au lieu du transport générique d’aperçu par envoi puis modification. Teams traite aussi `streaming.mode: "block"` comme une livraison par blocs Teams, car il ne dispose pas du même mode de blocs d’aperçu de brouillon utilisé par Discord et Telegram.
|
||||
Microsoft Teams utilise un flux natif dans les conversations personnelles au lieu du transport
|
||||
générique d’aperçu par envoi puis modification. Teams traite également `streaming.mode: "block"`
|
||||
comme une livraison par blocs Teams, car il ne dispose pas du même mode de blocs d’aperçu de brouillon
|
||||
utilisé par Discord et Telegram.
|
||||
|
||||
## Associé
|
||||
## Articles connexes
|
||||
|
||||
- [Streaming et découpage en morceaux](/fr/concepts/streaming)
|
||||
- [Streaming et découpage](/fr/concepts/streaming)
|
||||
- [Messages](/fr/concepts/messages)
|
||||
- [Configuration des canaux](/fr/gateway/config-channels)
|
||||
- [Discord](/fr/channels/discord)
|
||||
|
||||
@ -3,65 +3,66 @@ read_when:
|
||||
- Comprendre comment la pile d’assurance qualité s’articule
|
||||
- Étendre qa-lab, qa-channel ou un adaptateur de transport
|
||||
- Ajout de scénarios d’assurance qualité adossés au dépôt
|
||||
- Créer une automatisation d’assurance qualité plus réaliste autour du tableau de bord Gateway
|
||||
summary: 'Vue d’ensemble de la pile QA : qa-lab, qa-channel, scénarios adossés au dépôt, voies de transport en direct, adaptateurs de transport et rapports.'
|
||||
title: Vue d’ensemble de l’assurance qualité
|
||||
- Créer une automatisation de l’assurance qualité plus réaliste autour du tableau de bord Gateway
|
||||
summary: 'Présentation de la pile QA : qa-lab, qa-channel, scénarios adossés au dépôt, voies de transport en direct, adaptateurs de transport et rapports.'
|
||||
title: Présentation de l’assurance qualité
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:23:55Z"
|
||||
generated_at: "2026-05-04T07:04:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0b376767b967a51cc8a45ca5ce420f78067b52e6368d2abe921ffed533f6f9ba
|
||||
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
La stack QA privée sert à exercer OpenClaw d’une manière plus réaliste,
|
||||
structurée comme un canal, qu’un simple test unitaire ne peut le faire.
|
||||
La pile QA privée vise à exercer OpenClaw d’une manière plus réaliste,
|
||||
façonnée par les canaux, que ne le peut un seul test unitaire.
|
||||
|
||||
Éléments actuels :
|
||||
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec surfaces de DM, canal, fil,
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec surfaces de MP, canal, thread,
|
||||
réaction, modification et suppression.
|
||||
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
|
||||
- `extensions/qa-lab` : UI de débogage et bus QA pour observer la transcription,
|
||||
injecter des messages entrants et exporter un rapport Markdown.
|
||||
- `extensions/qa-matrix`, futurs plugins de runner : adaptateurs de transport live qui
|
||||
- `extensions/qa-matrix`, futurs plugins de runner : adaptateurs de transport en direct qui
|
||||
pilotent un vrai canal dans un Gateway QA enfant.
|
||||
- `qa/` : ressources initiales adossées au dépôt pour la tâche de lancement et les scénarios
|
||||
QA de référence.
|
||||
- [Mantis](/fr/concepts/mantis) : vérification live avant et après pour les bugs qui
|
||||
nécessitent de vrais transports, des captures d’écran de navigateur, un état de VM et des preuves de PR.
|
||||
- `qa/` : ressources d’amorçage adossées au dépôt pour la tâche de lancement et les scénarios QA
|
||||
de référence.
|
||||
- [Mantis](/fr/concepts/mantis) : vérification en direct avant et après pour les bugs qui
|
||||
nécessitent de vrais transports, des captures d’écran de navigateur, l’état d’une VM et des preuves de PR.
|
||||
|
||||
## Surface de commande
|
||||
|
||||
Chaque flux QA s’exécute sous `pnpm openclaw qa <subcommand>`. Beaucoup ont des alias de scripts `pnpm qa:*` ; les deux formes sont prises en charge.
|
||||
Chaque flux QA s’exécute sous `pnpm openclaw qa <subcommand>`. Beaucoup ont des alias de script `pnpm qa:*` ;
|
||||
les deux formes sont prises en charge.
|
||||
|
||||
| Commande | Objectif |
|
||||
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `qa run` | Auto-vérification QA intégrée ; écrit un rapport Markdown. |
|
||||
| `qa suite` | Exécuter les scénarios adossés au dépôt contre la lane Gateway QA. Alias : `pnpm openclaw qa suite --runner multipass` pour une VM Linux jetable. |
|
||||
| `qa coverage` | Afficher l’inventaire Markdown de couverture des scénarios (`--json` pour une sortie machine). |
|
||||
| `qa parity-report` | Comparer deux fichiers `qa-suite-summary.json` et écrire le rapport de parité agentique. |
|
||||
| `qa character-eval` | Exécuter le scénario QA de caractère sur plusieurs modèles live avec un rapport jugé. Voir [Rapports](#reporting). |
|
||||
| `qa manual` | Exécuter une invite ponctuelle contre la lane du fournisseur/modèle sélectionné. |
|
||||
| `qa ui` | Démarrer l’interface de débogage QA et le bus QA local (alias : `pnpm qa:lab:ui`). |
|
||||
| `qa docker-build-image` | Construire l’image Docker QA préintégrée. |
|
||||
| `qa docker-scaffold` | Écrire un échafaudage docker-compose pour le tableau de bord QA + la lane Gateway. |
|
||||
| `qa up` | Construire le site QA, démarrer la stack adossée à Docker, afficher l’URL (alias : `pnpm qa:lab:up` ; la variante `:fast` ajoute `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
|
||||
| `qa aimock` | Démarrer uniquement le serveur fournisseur AIMock. |
|
||||
| `qa mock-openai` | Démarrer uniquement le serveur fournisseur `mock-openai` sensible aux scénarios. |
|
||||
| `qa credentials doctor` / `add` / `list` / `remove` | Gérer le pool partagé d’identifiants Convex. |
|
||||
| `qa matrix` | Lane de transport live contre un homeserver Tuwunel jetable. Voir [QA Matrix](/fr/concepts/qa-matrix). |
|
||||
| `qa telegram` | Lane de transport live contre un vrai groupe Telegram privé. |
|
||||
| `qa discord` | Lane de transport live contre un vrai canal de guilde Discord privé. |
|
||||
| `qa slack` | Lane de transport live contre un vrai canal Slack privé. |
|
||||
| `qa mantis` | Runner de vérification avant et après pour les bugs de transport live, avec preuves de réactions de statut Discord et smoke Crabbox desktop/navigateur. Voir [Mantis](/fr/concepts/mantis). |
|
||||
| Commande | Objectif |
|
||||
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `qa run` | Auto-vérification QA intégrée ; écrit un rapport Markdown. |
|
||||
| `qa suite` | Exécuter les scénarios adossés au dépôt contre la voie du Gateway QA. Alias : `pnpm openclaw qa suite --runner multipass` pour une VM Linux jetable. |
|
||||
| `qa coverage` | Afficher l’inventaire Markdown de couverture des scénarios (`--json` pour une sortie machine). |
|
||||
| `qa parity-report` | Comparer deux fichiers `qa-suite-summary.json` et écrire le rapport de parité agentique. |
|
||||
| `qa character-eval` | Exécuter le scénario QA de caractère sur plusieurs modèles en direct avec un rapport évalué. Voir [Rapports](#reporting). |
|
||||
| `qa manual` | Exécuter une invite ponctuelle contre la voie fournisseur/modèle sélectionnée. |
|
||||
| `qa ui` | Démarrer l’UI de débogage QA et le bus QA local (alias : `pnpm qa:lab:ui`). |
|
||||
| `qa docker-build-image` | Construire l’image Docker QA précuite. |
|
||||
| `qa docker-scaffold` | Écrire un échafaudage docker-compose pour le tableau de bord QA + la voie Gateway. |
|
||||
| `qa up` | Construire le site QA, démarrer la pile adossée à Docker, afficher l’URL (alias : `pnpm qa:lab:up` ; la variante `:fast` ajoute `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
|
||||
| `qa aimock` | Démarrer uniquement le serveur fournisseur AIMock. |
|
||||
| `qa mock-openai` | Démarrer uniquement le serveur fournisseur `mock-openai` sensible aux scénarios. |
|
||||
| `qa credentials doctor` / `add` / `list` / `remove` | Gérer le pool partagé d’identifiants Convex. |
|
||||
| `qa matrix` | Voie de transport en direct contre un homeserver Tuwunel jetable. Voir [Matrix QA](/fr/concepts/qa-matrix). |
|
||||
| `qa telegram` | Voie de transport en direct contre un vrai groupe Telegram privé. |
|
||||
| `qa discord` | Voie de transport en direct contre un vrai canal de guilde Discord privé. |
|
||||
| `qa slack` | Voie de transport en direct contre un vrai canal Slack privé. |
|
||||
| `qa mantis` | Runner de vérification avant et après pour les bugs de transport en direct, avec preuves de réactions de statut Discord, smoke desktop/navigateur Crabbox et smoke Slack-dans-VNC. Voir [Mantis](/fr/concepts/mantis). |
|
||||
|
||||
## Flux opérateur
|
||||
|
||||
Le flux opérateur QA actuel est un site QA à deux panneaux :
|
||||
|
||||
- Gauche : tableau de bord Gateway (Control UI) avec l’agent.
|
||||
- Droite : QA Lab, affichant la transcription de style Slack et le plan de scénario.
|
||||
- Droite : QA Lab, affichant la transcription façon Slack et le plan de scénario.
|
||||
|
||||
Exécutez-le avec :
|
||||
|
||||
@ -69,13 +70,13 @@ Exécutez-le avec :
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Cela construit le site QA, démarre la lane Gateway adossée à Docker et expose la
|
||||
page QA Lab où un opérateur ou une boucle d’automatisation peut donner une mission
|
||||
QA à l’agent, observer le vrai comportement du canal et enregistrer ce qui a fonctionné,
|
||||
échoué ou est resté bloqué.
|
||||
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 vrai comportement du canal et consigner ce qui a fonctionné, échoué ou
|
||||
est resté bloqué.
|
||||
|
||||
Pour une itération plus rapide de l’interface QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
démarrez la stack avec un bundle QA Lab monté en bind :
|
||||
Pour itérer plus rapidement sur l’UI QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
démarrez la pile avec un paquet QA Lab monté en bind :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -84,40 +85,40 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` garde les services Docker sur une image préconstruite et monte en bind
|
||||
`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte en bind
|
||||
`extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch`
|
||||
reconstruit ce bundle lors des changements, et le navigateur se recharge automatiquement lorsque le hash des ressources QA Lab
|
||||
reconstruit ce paquet à chaque changement, et le navigateur se recharge automatiquement lorsque le hash des ressources QA Lab
|
||||
change.
|
||||
|
||||
Pour un smoke de trace OpenTelemetry local, exécutez :
|
||||
Pour un smoke local de trace OpenTelemetry, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm qa:otel:smoke
|
||||
```
|
||||
|
||||
Ce script démarre un récepteur de traces OTLP/HTTP local, exécute le scénario QA
|
||||
`otel-trace-smoke` avec le plugin `diagnostics-otel` activé, puis
|
||||
Ce script démarre un récepteur local de traces OTLP/HTTP, exécute le scénario QA
|
||||
`otel-trace-smoke` avec le Plugin `diagnostics-otel` activé, puis
|
||||
décode les spans protobuf exportés et vérifie la forme critique pour la release :
|
||||
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
|
||||
`openclaw.context.assembled` et `openclaw.message.delivery` doivent être présents ;
|
||||
les appels de modèle ne doivent pas exporter `StreamAbandoned` lors des tours réussis ; les ID de diagnostic bruts et les attributs
|
||||
`openclaw.content.*` doivent rester hors de la trace. Il écrit
|
||||
les appels de modèle ne doivent pas exporter `StreamAbandoned` sur les tours réussis ; les ID de diagnostic bruts et les
|
||||
attributs `openclaw.content.*` doivent rester hors de la trace. Il écrit
|
||||
`otel-smoke-summary.json` à côté des artefacts de la suite QA.
|
||||
|
||||
La QA d’observabilité reste réservée aux checkouts source. Le tarball npm omet volontairement
|
||||
QA Lab, donc les lanes de release Docker de package n’exécutent pas de commandes `qa`. Utilisez
|
||||
`pnpm qa:otel:smoke` depuis un checkout source construit lorsque vous modifiez l’instrumentation
|
||||
La QA d’observabilité reste réservée au checkout source. Le tarball npm omet volontairement
|
||||
QA Lab, donc les voies de release Docker du package n’exécutent pas de commandes `qa`. Utilisez
|
||||
`pnpm qa:otel:smoke` depuis un checkout source construit lors de modifications de l’instrumentation
|
||||
de diagnostic.
|
||||
|
||||
Pour une lane smoke Matrix avec transport réel, exécutez :
|
||||
Pour une voie smoke Matrix avec transport réel, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix --profile fast --fail-fast
|
||||
```
|
||||
|
||||
La référence CLI complète, le catalogue des profils/scénarios, les variables d’environnement et la disposition des artefacts de cette lane se trouvent dans [QA Matrix](/fr/concepts/qa-matrix). En bref : elle provisionne un homeserver Tuwunel jetable dans Docker, enregistre des utilisateurs temporaires driver/SUT/observateur, exécute le vrai plugin Matrix dans un Gateway QA enfant limité à ce transport (sans `qa-channel`), puis écrit un rapport Markdown, un résumé JSON, un artefact d’événements observés et un journal de sortie combiné sous `.artifacts/qa-e2e/matrix-<timestamp>/`.
|
||||
La référence CLI complète, le catalogue de profils/scénarios, les variables d’environnement et l’agencement des artefacts de cette voie se trouvent dans [Matrix QA](/fr/concepts/qa-matrix). En bref : elle provisionne un homeserver Tuwunel jetable dans Docker, enregistre des utilisateurs temporaires driver/SUT/observer, exécute le vrai Plugin Matrix dans un Gateway QA enfant limité à ce transport (pas de `qa-channel`), puis écrit un rapport Markdown, un résumé JSON, un artefact d’événements observés et un journal de sortie combiné sous `.artifacts/qa-e2e/matrix-<timestamp>/`.
|
||||
|
||||
Pour les lanes smoke Telegram, Discord et Slack avec transport réel :
|
||||
Pour les voies smoke à transport réel Telegram, Discord et Slack :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
@ -125,73 +126,89 @@ pnpm openclaw qa discord
|
||||
pnpm openclaw qa slack
|
||||
```
|
||||
|
||||
Elles ciblent un vrai canal préexistant avec deux bots (driver + SUT). Les variables d’environnement requises, les listes de scénarios, les artefacts de sortie et le pool d’identifiants Convex sont documentés dans la [référence QA Telegram, Discord et Slack](#telegram-discord-and-slack-qa-reference) ci-dessous.
|
||||
Elles ciblent un vrai canal préexistant avec deux bots (driver + SUT). Les variables d’environnement requises, listes de scénarios, artefacts de sortie et le pool d’identifiants Convex sont documentés dans la [référence QA Telegram, Discord et Slack](#telegram-discord-and-slack-qa-reference) ci-dessous.
|
||||
|
||||
Avant d’utiliser des identifiants live mutualisés, exécutez :
|
||||
Pour une exécution complète de VM desktop Slack avec secours VNC, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis slack-desktop-smoke \
|
||||
--gateway-setup \
|
||||
--scenario slack-canary \
|
||||
--keep-lease
|
||||
```
|
||||
|
||||
Cette commande loue une machine desktop/navigateur Crabbox, exécute la voie live Slack
|
||||
dans la VM, ouvre Slack Web dans le navigateur VNC, capture le bureau et
|
||||
copie `slack-qa/` ainsi que `slack-desktop-smoke.png` dans le répertoire d’artefacts
|
||||
Mantis. Réutilisez `--lease-id <cbx_...>` après vous être connecté manuellement à Slack Web
|
||||
via VNC. Avec `--gateway-setup`, Mantis laisse un Gateway Slack OpenClaw persistant
|
||||
en cours d’exécution dans la VM sur le port `38973` ; sans cette option, la commande exécute la
|
||||
voie QA Slack bot-à-bot normale et quitte après la capture des artefacts.
|
||||
|
||||
Avant d’utiliser les identifiants live mutualisés, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa credentials doctor
|
||||
```
|
||||
|
||||
Le doctor vérifie l’environnement du broker Convex, valide les réglages d’endpoint et vérifie l’accessibilité admin/liste lorsque le secret mainteneur est présent. Il ne signale que l’état défini/manquant des secrets.
|
||||
Le doctor vérifie l’environnement du broker Convex, valide les paramètres d’endpoint et vérifie l’accessibilité admin/list lorsque le secret mainteneur est présent. Il ne signale que l’état défini/manquant des secrets.
|
||||
|
||||
## Couverture du transport live
|
||||
## Couverture des transports en direct
|
||||
|
||||
Les lanes de transport live partagent un seul contrat au lieu d’inventer chacune leur propre forme de liste de scénarios. `qa-channel` est la suite large de comportements produit synthétiques et ne fait pas partie de la matrice de couverture du transport live.
|
||||
Les voies de transport en direct partagent un seul contrat au lieu d’inventer chacune leur propre forme de liste de scénarios. `qa-channel` est la large suite synthétique de comportement produit et ne fait pas partie de la matrice de couverture des transports en direct.
|
||||
|
||||
| Lane | Canary | Filtrage des mentions | Bot-à-bot | Blocage par allowlist | Réponse de premier niveau | Reprise après redémarrage | Suivi de fil | Isolation de fil | Observation des réactions | Commande d’aide | Enregistrement de commande native |
|
||||
| -------- | ------ | --------------------- | ---------- | --------------------- | ------------------------- | ------------------------- | ------------ | ---------------- | ------------------------- | --------------- | ---------------------------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | x | | |
|
||||
| Telegram | x | x | x | | | | | | | x | |
|
||||
| Discord | x | x | x | | | | | | | | x |
|
||||
| Slack | x | x | x | | | | | | | | |
|
||||
| Voie | Canary | Filtrage des mentions | Bot-à-bot | Blocage par liste d’autorisation | Réponse de premier niveau | Reprise après redémarrage | Suivi de thread | Isolation de thread | Observation des réactions | Commande d’aide | Enregistrement de commande native |
|
||||
| -------- | ------ | --------------------- | ---------- | -------------------------------- | ------------------------- | ------------------------- | ---------------- | ------------------- | -------------------------- | --------------- | --------------------------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | x | | |
|
||||
| Telegram | x | x | x | | | | | | | x | |
|
||||
| Discord | x | x | x | | | | | | | | x |
|
||||
| Slack | x | x | x | | | | | | | | |
|
||||
|
||||
Cela garde `qa-channel` comme suite large de comportements produit tandis que Matrix,
|
||||
Telegram et les futurs transports live partagent une checklist explicite de contrat
|
||||
de transport.
|
||||
Cela conserve `qa-channel` comme large suite de comportement produit tandis que Matrix,
|
||||
Telegram et les futurs transports en direct partagent une checklist explicite de contrat de transport.
|
||||
|
||||
Pour une lane VM Linux jetable sans introduire Docker dans le chemin QA, exécutez :
|
||||
Pour une voie VM Linux jetable sans intégrer Docker dans le chemin QA, exécutez :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Cela démarre un invité Multipass neuf, installe les dépendances, construit OpenClaw
|
||||
Cela démarre un nouvel invité Multipass, installe les dépendances, construit OpenClaw
|
||||
dans l’invité, exécute `qa suite`, puis recopie le rapport QA normal et le
|
||||
résumé dans `.artifacts/qa-e2e/...` sur l’hôte.
|
||||
Il réutilise le même comportement de sélection de scénarios que `qa suite` sur l’hôte.
|
||||
Les exécutions de suite sur l’hôte et Multipass exécutent par défaut plusieurs scénarios sélectionnés en parallèle
|
||||
avec des workers Gateway isolés. `qa-channel` utilise une concurrence par défaut 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 série.
|
||||
Les exécutions de suites hôte et 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, limité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 non nul lorsqu’un scénario échoue. Utilisez `--allow-failures` lorsque
|
||||
vous voulez des artefacts sans code de sortie en échec.
|
||||
vous voulez obtenir des artefacts sans code de sortie d’échec.
|
||||
Les exécutions live transmettent les entrées d’authentification QA prises en charge et pratiques pour
|
||||
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA et
|
||||
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. Gardez `--output-dir` sous la racine du dépôt afin que l’invité
|
||||
puisse réécrire via l’espace de travail monté.
|
||||
|
||||
## Référence QA Telegram, Discord et Slack
|
||||
## Référence QA pour Telegram, Discord et Slack
|
||||
|
||||
Matrix a une [page dédiée](/fr/concepts/qa-matrix) en raison de son nombre de scénarios et du provisionnement de homeserver adossé à Docker. Telegram, Discord et Slack sont plus petits — une poignée de scénarios chacun, sans système de profil, contre des canaux réels préexistants — leur référence se trouve donc ici.
|
||||
Matrix dispose d’une [page dédiée](/fr/concepts/qa-matrix) en raison de son nombre de scénarios et du provisionnement de homeserver appuyé par Docker. Telegram, Discord et Slack sont plus petits — quelques scénarios chacun, aucun système de profil, contre des canaux réels préexistants — leur référence se trouve donc ici.
|
||||
|
||||
### Flags CLI partagés
|
||||
### Options CLI partagées
|
||||
|
||||
Ces lanes s’enregistrent via `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` et acceptent les mêmes flags :
|
||||
Ces lanes s’enregistrent via `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` et acceptent les mêmes options :
|
||||
|
||||
| Option | Par défaut | Description |
|
||||
| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--scenario <id>` | — | Exécute uniquement ce scénario. Peut être répétée. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Emplacement où sont écrits les rapports, le résumé, les messages observés et le journal de sortie. Les chemins relatifs sont résolus par rapport à `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Racine du dépôt lors d’un appel depuis un cwd neutre. |
|
||||
| `--sut-account <id>` | `sut` | ID de compte temporaire dans la configuration du Gateway QA. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` hérité fonctionne encore). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | modèle par défaut du fournisseur | Références des modèles principal et secondaire. |
|
||||
| `--fast` | désactivé | Mode rapide du fournisseur, lorsque pris en charge. |
|
||||
| `--credential-source <env\|convex>` | `env` | Consultez [pool d’identifiants Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `ci` dans CI, sinon `maintainer` | Rôle utilisé lorsque `--credential-source convex`. |
|
||||
| Option | Par défaut | Description |
|
||||
| ------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--scenario <id>` | — | Exécute uniquement ce scénario. Répétable. |
|
||||
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Emplacement où les rapports, résumés, messages observés et le journal de sortie sont écrits. Les chemins relatifs sont résolus par rapport à `--repo-root`. |
|
||||
| `--repo-root <path>` | `process.cwd()` | Racine du dépôt lors d’un appel depuis un cwd neutre. |
|
||||
| `--sut-account <id>` | `sut` | Id de compte temporaire dans la configuration QA Gateway. |
|
||||
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (l’ancien `live-openai` fonctionne toujours). |
|
||||
| `--model <ref>` / `--alt-model <ref>` | valeur par défaut du fournisseur | Réfs de modèle primaire/alternatif. |
|
||||
| `--fast` | désactivé | Mode rapide du fournisseur lorsque pris en charge. |
|
||||
| `--credential-source <env\|convex>` | `env` | Voir [Pool d’identifiants Convex](#convex-credential-pool). |
|
||||
| `--credential-role <maintainer\|ci>` | `ci` en CI, sinon `maintainer` | Rôle utilisé lorsque `--credential-source convex`. |
|
||||
|
||||
Chaque voie se termine avec un code non nul en cas d’échec d’un scénario. `--allow-failures` écrit les artefacts sans définir de code de sortie d’échec.
|
||||
Chaque lane se termine avec un code non nul en cas de scénario échoué. `--allow-failures` écrit les artefacts sans définir de code de sortie d’échec.
|
||||
|
||||
### QA Telegram
|
||||
|
||||
@ -199,17 +216,17 @@ Chaque voie se termine avec un code non nul en cas d’échec d’un scénario.
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Cible un vrai groupe privé Telegram avec deux bots distincts (pilote + SUT). Le bot SUT doit avoir un nom d’utilisateur Telegram ; l’observation bot-à-bot fonctionne mieux lorsque les deux bots ont **Bot-to-Bot Communication Mode** activé dans `@BotFather`.
|
||||
Cible un vrai groupe privé Telegram avec deux bots distincts (pilote + SUT). Le bot SUT doit avoir un nom d’utilisateur Telegram ; l’observation bot-à-bot fonctionne mieux lorsque les deux bots ont le **Bot-to-Bot Communication Mode** activé dans `@BotFather`.
|
||||
|
||||
Variables d’environnement requises lorsque `--credential-source env` :
|
||||
Env requis lorsque `--credential-source env` :
|
||||
|
||||
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — ID de discussion numérique (chaîne).
|
||||
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id numérique du chat (chaîne).
|
||||
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
|
||||
|
||||
Optionnel :
|
||||
Facultatif :
|
||||
|
||||
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés (masqués par défaut).
|
||||
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` conserve les corps de messages dans les artefacts de messages observés (masqués par défaut).
|
||||
|
||||
Scénarios (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`) :
|
||||
|
||||
@ -225,7 +242,7 @@ Scénarios (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtim
|
||||
Artefacts de sortie :
|
||||
|
||||
- `telegram-qa-report.md`
|
||||
- `telegram-qa-summary.json` — inclut le RTT par réponse (envoi par le pilote → réponse SUT observée) en commençant par le canary.
|
||||
- `telegram-qa-summary.json` — inclut le RTT par réponse (envoi par le pilote → réponse SUT observée) à partir du canari.
|
||||
- `telegram-qa-observed-messages.json` — corps masqués sauf si `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
|
||||
|
||||
### QA Discord
|
||||
@ -234,26 +251,26 @@ Artefacts de sortie :
|
||||
pnpm openclaw qa discord
|
||||
```
|
||||
|
||||
Cible un vrai canal de guilde privé Discord avec deux bots : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Discord intégré. Vérifie la gestion des mentions de canal, que le bot SUT a enregistré la commande native `/help` auprès de Discord, ainsi que les scénarios d’éléments de preuve Mantis à activation explicite.
|
||||
Cible un vrai canal de guilde privée Discord avec deux bots : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Discord groupé. Vérifie la gestion des mentions de canal, que le bot SUT a enregistré la commande native `/help` auprès de Discord, ainsi que les scénarios d’éléments probants Mantis avec inscription explicite.
|
||||
|
||||
Variables d’environnement requises lorsque `--credential-source env` :
|
||||
Env requis lorsque `--credential-source env` :
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_GUILD_ID`
|
||||
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — doit correspondre à l’ID utilisateur du bot SUT renvoyé par Discord (sinon la voie échoue rapidement).
|
||||
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — doit correspondre à l’id utilisateur du bot SUT renvoyé par Discord (sinon la lane échoue rapidement).
|
||||
|
||||
Optionnel :
|
||||
Facultatif :
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés.
|
||||
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` conserve les corps de messages dans les artefacts de messages observés.
|
||||
|
||||
Scénarios (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`) :
|
||||
|
||||
- `discord-canary`
|
||||
- `discord-mention-gating`
|
||||
- `discord-native-help-command-registration`
|
||||
- `discord-status-reactions-tool-only` — scénario Mantis à activation explicite. S’exécute seul parce qu’il bascule le SUT en réponses de guilde toujours actives et uniquement via outils avec `messages.statusReactions.enabled=true`, puis capture une chronologie de réactions REST ainsi qu’un artefact visuel HTML/PNG.
|
||||
- `discord-status-reactions-tool-only` — scénario Mantis avec inscription explicite. S’exécute seul car il bascule le SUT en réponses de guilde toujours actives et uniquement par outil avec `messages.statusReactions.enabled=true`, puis capture une chronologie de réactions REST plus un artefact visuel HTML/PNG.
|
||||
|
||||
Exécutez explicitement le scénario de réactions de statut Mantis :
|
||||
|
||||
@ -279,18 +296,18 @@ Artefacts de sortie :
|
||||
pnpm openclaw qa slack
|
||||
```
|
||||
|
||||
Cible un vrai canal privé Slack avec deux bots distincts : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Slack intégré.
|
||||
Cible un vrai canal privé Slack avec deux bots distincts : un bot pilote contrôlé par le harnais et un bot SUT démarré par le Gateway OpenClaw enfant via le Plugin Slack groupé.
|
||||
|
||||
Variables d’environnement requises lorsque `--credential-source env` :
|
||||
Env requis lorsque `--credential-source env` :
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
|
||||
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_SLACK_SUT_APP_TOKEN`
|
||||
|
||||
Optionnel :
|
||||
Facultatif :
|
||||
|
||||
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` conserve le corps des messages dans les artefacts de messages observés.
|
||||
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` conserve les corps de messages dans les artefacts de messages observés.
|
||||
|
||||
Scénarios (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`) :
|
||||
|
||||
@ -305,114 +322,128 @@ Artefacts de sortie :
|
||||
|
||||
### Pool d’identifiants Convex
|
||||
|
||||
Les voies Telegram, Discord et Slack peuvent louer des identifiants depuis un pool Convex partagé au lieu de lire les variables d’environnement ci-dessus. Passez `--credential-source convex` (ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) ; QA Lab acquiert un bail exclusif, lui envoie des Heartbeats pendant toute la durée de l’exécution, puis le libère à l’arrêt. Les types de pool sont `"telegram"`, `"discord"` et `"slack"`.
|
||||
Les lanes Telegram, Discord et Slack peuvent louer des identifiants depuis un pool Convex partagé au lieu de lire les variables d’environnement ci-dessus. Passez `--credential-source convex` (ou définissez `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) ; QA Lab acquiert un bail exclusif, lui envoie des Heartbeats pendant toute la durée de l’exécution, puis le libère à l’arrêt. Les types de pool sont `"telegram"`, `"discord"` et `"slack"`.
|
||||
|
||||
Formes de charge utile validées par le courtier sur `admin/add` :
|
||||
Formes de payload que le broker valide sur `admin/add` :
|
||||
|
||||
- Telegram (`kind: "telegram"`) : `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` doit être une chaîne d’ID de discussion numérique.
|
||||
- Telegram (`kind: "telegram"`) : `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` doit être une chaîne de chat-id numérique.
|
||||
- Discord (`kind: "discord"`) : `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
|
||||
|
||||
Les variables d’environnement opérationnelles et le contrat de point de terminaison du courtier Convex se trouvent dans [Tests → Identifiants Telegram partagés via Convex](/fr/help/testing#shared-telegram-credentials-via-convex-v1) (le nom de la section est antérieur à la prise en charge de Discord ; la sémantique du courtier est identique pour les deux types).
|
||||
Les variables d’environnement opérationnelles et le contrat d’endpoint du broker Convex se trouvent dans [Tests → Identifiants Telegram partagés via Convex](/fr/help/testing#shared-telegram-credentials-via-convex-v1) (le nom de la section est antérieur à la prise en charge de Discord ; les sémantiques du broker sont identiques pour les deux types).
|
||||
|
||||
## Graines basées sur le dépôt
|
||||
## Seeds appuyés par le dépôt
|
||||
|
||||
Les ressources de graines se trouvent dans `qa/` :
|
||||
Les ressources de seed se trouvent dans `qa/` :
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Elles sont intentionnellement dans git afin que le plan QA soit visible à la fois par les humains et par l’agent.
|
||||
Elles sont volontairement 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 la source de vérité d’une exécution de test et doit définir :
|
||||
`qa-lab` doit rester un runner Markdown générique. Chaque fichier Markdown de scénario est
|
||||
la source de vérité pour une exécution de test et doit définir :
|
||||
|
||||
- les métadonnées du scénario
|
||||
- les métadonnées optionnelles de catégorie, capacité, voie et risque
|
||||
- les références de documentation et de code
|
||||
- les exigences optionnelles de Plugin
|
||||
- le correctif optionnel de configuration du Gateway
|
||||
- les métadonnées de scénario
|
||||
- des métadonnées facultatives de catégorie, capacité, lane et risque
|
||||
- les références de docs et de code
|
||||
- les exigences facultatives de Plugin
|
||||
- un patch 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 l’interface Control UI embarquée via la jonction Gateway `browser.request` sans ajouter d’exécuteur spécial.
|
||||
La surface runtime réutilisable qui soutient `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 intégrée via le
|
||||
seam Gateway `browser.request` sans ajouter de runner spécial.
|
||||
|
||||
Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier de l’arborescence source. Gardez les ID de scénario stables lorsque les fichiers sont déplacés ; utilisez `docsRefs` et `codeRefs` pour la traçabilité de l’implémentation.
|
||||
Les fichiers de scénario doivent être regroupés par capacité produit plutôt que par dossier
|
||||
de l’arborescence source. Gardez les IDs de scénario stables lorsque les fichiers sont déplacés ; utilisez `docsRefs` et `codeRefs`
|
||||
pour la traçabilité de l’implémentation.
|
||||
|
||||
La liste de référence doit rester assez large pour couvrir :
|
||||
La liste de référence doit rester suffisamment large pour couvrir :
|
||||
|
||||
- les discussions en DM et en canal
|
||||
- le comportement des fils
|
||||
- les chats DM et canal
|
||||
- le comportement des threads
|
||||
- le cycle de vie des actions de message
|
||||
- les rappels cron
|
||||
- le rappel de mémoire
|
||||
- les rappels Cron
|
||||
- le rappel mémoire
|
||||
- le changement de modèle
|
||||
- le transfert à un sous-agent
|
||||
- la lecture du dépôt et la lecture de la documentation
|
||||
- une petite tâche de build telle que Lobster Invaders
|
||||
- la lecture du dépôt et de la documentation
|
||||
- une petite tâche de build comme Lobster Invaders
|
||||
|
||||
## Voies de simulation de fournisseur
|
||||
## Lanes de mock de fournisseur
|
||||
|
||||
`qa suite` dispose de deux voies locales de simulation de fournisseur :
|
||||
`qa suite` dispose de deux lanes locales de mock de fournisseur :
|
||||
|
||||
- `mock-openai` est le mock OpenClaw conscient des scénarios. Il reste la voie de mock déterministe par défaut pour la QA basée sur le dépôt et les portes de parité.
|
||||
- `aimock` démarre un serveur fournisseur basé sur AIMock pour la 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`.
|
||||
- `mock-openai` est le mock OpenClaw sensible aux scénarios. Il reste la lane de mock
|
||||
déterministe par défaut pour la QA appuyée par le dépôt et les gates de parité.
|
||||
- `aimock` démarre un serveur fournisseur appuyé par AIMock pour la couverture expérimentale de protocole,
|
||||
fixtures, enregistrement/relecture et 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 sous `extensions/qa-lab/src/providers/`. Chaque fournisseur possède ses valeurs par défaut, le démarrage de son serveur local, la configuration de modèle du Gateway, ses besoins de préparation de profil d’authentification et ses indicateurs de capacité live/mock. Le code partagé de suite et de Gateway doit passer par le registre des fournisseurs au lieu de créer des branches sur les noms de fournisseurs.
|
||||
L’implémentation des lanes de fournisseur se trouve sous `extensions/qa-lab/src/providers/`.
|
||||
Chaque fournisseur possède ses valeurs par défaut, le démarrage de serveur local, la configuration de modèle Gateway,
|
||||
les besoins de staging des profils d’authentification, ainsi que les flags de capacité live/mock. Le code de suite partagée et
|
||||
de Gateway doit passer par le registre des fournisseurs au lieu de bifurquer sur
|
||||
les noms de fournisseurs.
|
||||
|
||||
## Adaptateurs de transport
|
||||
|
||||
`qa-lab` possède une jonction de transport générique pour les scénarios QA markdown. `qa-channel` est le premier adaptateur sur cette jonction, mais la cible de conception est plus large : les futurs canaux réels ou synthétiques doivent se brancher dans le même exécuteur de suite au lieu d’ajouter un exécuteur QA propre au transport.
|
||||
`qa-lab` possède un seam de transport générique pour les scénarios QA Markdown. `qa-channel` est le premier adaptateur sur ce seam, mais la cible de conception est plus large : les futurs canaux réels ou synthétiques doivent se brancher sur le même runner de suite au lieu d’ajouter un runner QA spécifique au transport.
|
||||
|
||||
Au niveau de l’architecture, la séparation est la suivante :
|
||||
Au niveau de l’architecture, la séparation est :
|
||||
|
||||
- `qa-lab` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et les rapports.
|
||||
- L’adaptateur de transport possède la configuration du 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` possède l’exécution générique des scénarios, la concurrence des workers, l’écriture des artefacts et le reporting.
|
||||
- L’adaptateur de transport possède la configuration Gateway, l’état prêt, l’observation entrante et sortante, les actions de transport et l’état de transport normalisé.
|
||||
- Les fichiers de scénarios Markdown sous `qa/scenarios/` définissent l’exécution de test ; `qa-lab` fournit la surface runtime réutilisable qui les exécute.
|
||||
|
||||
### Ajouter un canal
|
||||
|
||||
Ajouter un canal au système QA markdown exige exactement deux éléments :
|
||||
L’ajout d’un canal au système QA Markdown nécessite exactement deux choses :
|
||||
|
||||
1. Un adaptateur de transport pour le canal.
|
||||
2. Un pack de scénarios qui exerce le contrat du canal.
|
||||
|
||||
N’ajoutez pas une nouvelle racine de commande QA de premier niveau lorsque l’hôte partagé `qa-lab` peut posséder le flux.
|
||||
N’ajoutez pas de nouvelle racine de commande QA de premier niveau lorsque l’hôte partagé `qa-lab` peut posséder le flux.
|
||||
|
||||
`qa-lab` possède les mécanismes d’hôte partagés :
|
||||
|
||||
- la racine de commande `openclaw qa`
|
||||
- le démarrage et l’arrêt de la suite
|
||||
- le démarrage et l’arrêt des suites
|
||||
- la concurrence des workers
|
||||
- l’écriture des artefacts
|
||||
- la génération de rapports
|
||||
- la génération des rapports
|
||||
- l’exécution des scénarios
|
||||
- les alias de compatibilité pour les anciens scénarios `qa-channel`
|
||||
|
||||
Les Plugins d’exécuteur possèdent le contrat de transport :
|
||||
Les plugins de runner possèdent le contrat de transport :
|
||||
|
||||
- la façon dont `openclaw qa <runner>` est monté sous la racine partagée `qa`
|
||||
- la façon dont `openclaw qa <runner>` est monté sous la racine `qa` partagée
|
||||
- la façon dont le Gateway est configuré pour ce transport
|
||||
- la façon dont l’état prêt est vérifié
|
||||
- la façon dont les événements entrants sont injectés
|
||||
- la façon dont les messages sortants sont observés
|
||||
- la façon dont les transcriptions et l’état de transport normalisé sont exposés
|
||||
- la façon dont les actions appuyées par le transport sont exécutées
|
||||
- la façon dont les actions adossées au transport sont exécutées
|
||||
- la façon dont la réinitialisation ou le nettoyage propre au transport est géré
|
||||
|
||||
La barre minimale d’adoption pour un nouveau canal :
|
||||
Le seuil minimal d’adoption pour un nouveau canal :
|
||||
|
||||
1. Gardez `qa-lab` comme propriétaire de la racine `qa` partagée.
|
||||
2. Implémentez le runner de transport sur la jointure d’hôte `qa-lab` partagée.
|
||||
3. Gardez les mécaniques propres au transport dans le Plugin runner ou le harnais de canal.
|
||||
4. Montez le runner sous `openclaw qa <runner>` au lieu d’enregistrer une commande racine concurrente. Les Plugins runners doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. Gardez `runtime-api.ts` léger ; la CLI paresseuse et l’exécution du runner doivent rester derrière des points d’entrée séparés.
|
||||
5. Rédigez ou adaptez des scénarios Markdown dans les répertoires thématiques `qa/scenarios/`.
|
||||
6. Utilisez les helpers de scénario génériques pour les nouveaux scénarios.
|
||||
7. Gardez les alias de compatibilité existants fonctionnels, sauf si le dépôt effectue une migration intentionnelle.
|
||||
1. Conserver `qa-lab` comme propriétaire de la racine `qa` partagée.
|
||||
2. Implémenter le runner de transport sur la jonction d’hôte `qa-lab` partagée.
|
||||
3. Garder les mécanismes propres au transport dans le plugin de runner ou le harness de canal.
|
||||
4. Monter le runner sous la forme `openclaw qa <runner>` au lieu d’enregistrer une commande racine concurrente. Les plugins de runner doivent déclarer `qaRunners` dans `openclaw.plugin.json` et exporter un tableau `qaRunnerCliRegistrations` correspondant depuis `runtime-api.ts`. Garder `runtime-api.ts` léger ; la CLI paresseuse et l’exécution du runner doivent rester derrière des points d’entrée séparés.
|
||||
5. Rédiger ou adapter les scénarios Markdown sous les répertoires thématiques `qa/scenarios/`.
|
||||
6. Utiliser les helpers de scénario génériques pour les nouveaux scénarios.
|
||||
7. Garder les alias de compatibilité existants fonctionnels, sauf si le dépôt effectue une migration intentionnelle.
|
||||
|
||||
La règle de décision est stricte :
|
||||
|
||||
- Si un comportement peut être exprimé une seule fois dans `qa-lab`, mettez-le dans `qa-lab`.
|
||||
- Si un comportement dépend d’un transport de canal, gardez-le dans ce Plugin runner ou ce harnais de Plugin.
|
||||
- Si un scénario a besoin d’une nouvelle capacité utilisable par plus d’un canal, ajoutez un helper générique au lieu d’une branche spécifique au canal dans `suite.ts`.
|
||||
- Si un comportement n’a de sens que pour un seul transport, gardez le scénario spécifique au transport et rendez-le explicite dans le contrat du scénario.
|
||||
- Si un comportement peut être exprimé une seule fois dans `qa-lab`, le mettre dans `qa-lab`.
|
||||
- Si un comportement dépend d’un seul transport de canal, le garder dans ce plugin de runner ou harness de plugin.
|
||||
- Si un scénario a besoin d’une nouvelle capacité utilisable par plusieurs canaux, ajouter un helper générique plutôt qu’une branche propre à un canal dans `suite.ts`.
|
||||
- Si un comportement n’a de sens que pour un seul transport, garder le scénario propre au transport et l’expliciter dans le contrat du scénario.
|
||||
|
||||
### Noms des helpers de scénario
|
||||
|
||||
@ -431,21 +462,21 @@ Helpers génériques préférés pour les nouveaux scénarios :
|
||||
- `formatTransportTranscript`
|
||||
- `resetTransport`
|
||||
|
||||
Les alias de compatibilité restent disponibles pour les scénarios existants — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mais la rédaction de nouveaux scénarios doit utiliser les noms génériques. Les alias existent pour éviter une migration basculée d’un seul coup, pas comme modèle à suivre.
|
||||
Les alias de compatibilité restent disponibles pour les scénarios existants — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mais les nouveaux scénarios doivent utiliser les noms génériques. Les alias existent pour éviter une migration à date unique, pas comme modèle à suivre à l’avenir.
|
||||
|
||||
## Rapports
|
||||
|
||||
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie de bus observée.
|
||||
Le rapport doit répondre à :
|
||||
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie du bus observée.
|
||||
Le rapport doit répondre à ces questions :
|
||||
|
||||
- Ce qui a fonctionné
|
||||
- Ce qui a échoué
|
||||
- Ce qui est resté bloqué
|
||||
- Les scénarios de suivi qu’il vaut la peine d’ajouter
|
||||
- Quels scénarios de suivi méritent d’être ajoutés
|
||||
|
||||
Pour l’inventaire des scénarios disponibles — utile pour dimensionner le travail de suivi ou câbler un nouveau transport — exécutez `pnpm openclaw qa coverage` (ajoutez `--json` pour une sortie lisible par machine).
|
||||
Pour l’inventaire des scénarios disponibles — utile pour dimensionner le travail de suivi ou raccorder un nouveau transport — exécuter `pnpm openclaw qa coverage` (ajouter `--json` pour une sortie lisible par machine).
|
||||
|
||||
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs refs de modèles live et rédigez un rapport Markdown évalué :
|
||||
Pour les vérifications de caractère et de style, exécuter le même scénario sur plusieurs refs de modèles live et écrire un rapport Markdown évalué :
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -464,17 +495,21 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
La commande exécute des processus enfants du Gateway QA local, pas Docker. Les scénarios d’évaluation de caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires comme du chat, de l’aide sur l’espace de travail et de petites tâches de fichiers. Le modèle candidat ne doit pas être informé qu’il est évalué. 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`, lorsque pris en charge, de classer les exécutions selon le naturel, l’ambiance et l’humour.
|
||||
Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : le prompt du juge reçoit toujours chaque transcription et statut d’exécution, mais les refs candidates sont remplacées par des libellés neutres comme `candidate-01` ; le rapport remappe les classements vers les vraies refs après l’analyse.
|
||||
Les exécutions candidates utilisent par défaut le raisonnement `high`, avec `medium` pour GPT-5.5 et `xhigh` pour les anciennes refs d’évaluation OpenAI qui le prennent en charge. Remplacez un candidat précis en ligne avec `--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours une valeur de repli globale, et l’ancienne forme `--model-thinking <provider/model=level>` est conservée pour compatibilité.
|
||||
Les refs candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé lorsque le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un seul candidat ou juge nécessite une surcharge. Passez `--fast` uniquement lorsque vous voulez forcer le mode rapide pour tous les modèles candidats. Les durées des candidats et des juges sont enregistrées dans le rapport pour l’analyse de benchmark, mais les prompts des juges indiquent explicitement de ne pas classer selon la vitesse.
|
||||
Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez `--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression du Gateway local rendent une exécution trop bruitée.
|
||||
Lorsqu’aucun candidat `--model` n’est passé, l’évaluation de caractère utilise par défaut `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` et `google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est passé.
|
||||
Lorsqu’aucun `--judge-model` n’est passé, les juges utilisent par défaut `openai/gpt-5.5,thinking=xhigh,fast` et `anthropic/claude-opus-4-6,thinking=high`.
|
||||
La commande lance des processus enfants locaux de Gateway QA, pas Docker. Les scénarios d’évaluation de caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires comme la discussion, l’aide dans l’espace de travail et de petites tâches sur les fichiers. Le modèle candidat ne doit pas être informé qu’il est évalué. La commande conserve chaque transcription complète, enregistre les statistiques de base de l’exécution, puis demande aux modèles juges en mode rapide avec un raisonnement `xhigh` lorsque pris en charge de classer les exécutions selon le naturel, le ton et l’humour.
|
||||
Utiliser `--blind-judge-models` lors de la comparaison de fournisseurs : le prompt du juge reçoit toujours chaque transcription et chaque statut d’exécution, mais les refs candidates sont remplacées par des libellés neutres comme `candidate-01` ; le rapport rattache les classements aux refs réelles après l’analyse.
|
||||
Les exécutions candidates utilisent par défaut une réflexion `high`, avec `medium` pour GPT-5.5 et `xhigh` pour les anciennes refs d’évaluation OpenAI qui le prennent en charge. Remplacer un candidat précis en ligne avec `--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours un repli global, et l’ancienne forme `--model-thinking <provider/model=level>` est conservée pour compatibilité.
|
||||
Les refs candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé lorsque le fournisseur le prend en charge. Ajouter `,fast`, `,no-fast` ou `,fast=false` en ligne lorsqu’un candidat ou juge unique nécessite un remplacement. Passer `--fast` uniquement pour forcer l’activation du mode rapide pour chaque modèle candidat. Les durées des candidats et des juges sont enregistrées dans le rapport pour l’analyse comparative, mais les prompts des juges indiquent explicitement de ne pas classer selon la vitesse.
|
||||
Les exécutions de modèles candidats et juges utilisent toutes deux une concurrence par défaut de 16. Réduire `--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression sur le Gateway local rendent une exécution trop bruitée.
|
||||
Lorsqu’aucun `--model` candidat n’est passé, l’évaluation de caractère utilise par défaut `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5` et
|
||||
`google/gemini-3.1-pro-preview` lorsqu’aucun `--model` n’est passé.
|
||||
Lorsqu’aucun `--judge-model` n’est passé, les juges utilisent par défaut
|
||||
`openai/gpt-5.5,thinking=xhigh,fast` et
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
## Docs associées
|
||||
## Docs connexes
|
||||
|
||||
- [QA matricielle](/fr/concepts/qa-matrix)
|
||||
- [QA Matrix](/fr/concepts/qa-matrix)
|
||||
- [Canal QA](/fr/channels/qa-channel)
|
||||
- [Tests](/fr/help/testing)
|
||||
- [Tableau de bord](/fr/web/dashboard)
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Expliquer le fonctionnement de la diffusion en continu ou du découpage en segments dans les canaux
|
||||
- Modification du comportement de diffusion en continu par blocs ou du découpage en fragments des canaux
|
||||
- Débogage des réponses de bloc en double/prématurées ou de la diffusion en continu de l’aperçu du canal
|
||||
summary: Comportement du streaming et du découpage en fragments (réponses par blocs, streaming d’aperçu de canal, correspondance des modes)
|
||||
title: Diffusion en continu et segmentation
|
||||
- Expliquer le fonctionnement de la diffusion en continu ou du découpage en fragments sur les canaux
|
||||
- Modification du comportement de diffusion en continu des blocs ou de segmentation des canaux
|
||||
- Débogage des réponses de bloc dupliquées/précoces ou du streaming de prévisualisation du canal
|
||||
summary: Comportement de diffusion en continu et de découpage en fragments (réponses par blocs, diffusion en continu de l’aperçu du canal, correspondance des modes)
|
||||
title: Diffusion en continu et découpage en segments
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:55Z"
|
||||
generated_at: "2026-05-04T07:04:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw possède deux couches de diffusion distinctes :
|
||||
OpenClaw dispose de deux couches de streaming distinctes :
|
||||
|
||||
- **Diffusion par blocs (canaux) :** émet des **blocs** terminés pendant que l’assistant écrit. Ce sont des messages de canal normaux (pas des deltas de jetons).
|
||||
- **Diffusion d’aperçu (Telegram/Discord/Slack) :** met à jour un **message d’aperçu** temporaire pendant la génération.
|
||||
- **Streaming par blocs (canaux) :** émet des **blocs** terminés pendant que l’assistant écrit. Ce sont des messages de canal normaux (pas des deltas de jetons).
|
||||
- **Streaming d’aperçu (Telegram/Discord/Slack) :** met à jour un **message d’aperçu** temporaire pendant la génération.
|
||||
|
||||
Il n’existe aujourd’hui **aucune véritable diffusion de deltas de jetons** vers les messages de canal. La diffusion d’aperçu est basée sur des messages (envoi + modifications/ajouts).
|
||||
Il n’existe aujourd’hui **aucun véritable streaming de deltas de jetons** vers les messages de canal. Le streaming d’aperçu repose sur des messages (envoi + modifications/ajouts).
|
||||
|
||||
## Diffusion par blocs (messages de canal)
|
||||
## Streaming par blocs (messages de canal)
|
||||
|
||||
La diffusion par blocs envoie la sortie de l’assistant en morceaux grossiers à mesure qu’elle devient disponible.
|
||||
Le streaming par blocs envoie la sortie de l’assistant sous forme de morceaux grossiers à mesure qu’elle devient disponible.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -37,8 +37,8 @@ Model output
|
||||
|
||||
Légende :
|
||||
|
||||
- `text_delta/events` : événements de flux du modèle (peuvent être rares pour les modèles sans diffusion).
|
||||
- `chunker` : `EmbeddedBlockChunker` appliquant les limites min/max + la préférence de coupure.
|
||||
- `text_delta/events` : événements de flux du modèle (peuvent être rares pour les modèles sans streaming).
|
||||
- `chunker` : `EmbeddedBlockChunker` appliquant des bornes min/max + une préférence de rupture.
|
||||
- `channel send` : messages sortants réels (réponses par blocs).
|
||||
|
||||
**Contrôles :**
|
||||
@ -47,93 +47,97 @@ Légende :
|
||||
- Remplacements par canal : `*.blockStreaming` (et variantes par compte) pour forcer `"on"`/`"off"` par canal.
|
||||
- `agents.defaults.blockStreamingBreak` : `"text_end"` ou `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk` : `{ minChars, maxChars, breakPreference? }`.
|
||||
- `agents.defaults.blockStreamingCoalesce` : `{ minChars?, maxChars?, idleMs? }` (fusionne les blocs diffusés avant l’envoi).
|
||||
- Plafond strict du canal : `*.textChunkLimit` (par exemple, `channels.whatsapp.textChunkLimit`).
|
||||
- Mode de découpage du canal : `*.chunkMode` (`length` par défaut, `newline` découpe sur les lignes vides (limites de paragraphes) avant le découpage par longueur).
|
||||
- Plafond souple Discord : `channels.discord.maxLinesPerMessage` (17 par défaut) découpe les réponses hautes pour éviter le rognage dans l’interface.
|
||||
- `agents.defaults.blockStreamingCoalesce` : `{ minChars?, maxChars?, idleMs? }` (fusionne les blocs streamés avant l’envoi).
|
||||
- Limite stricte du canal : `*.textChunkLimit` (par exemple, `channels.whatsapp.textChunkLimit`).
|
||||
- Mode de découpage du canal : `*.chunkMode` (`length` par défaut, `newline` découpe sur les lignes vides (limites de paragraphe) avant le découpage par longueur).
|
||||
- Limite souple Discord : `channels.discord.maxLinesPerMessage` (17 par défaut) découpe les réponses hautes pour éviter le rognage dans l’interface.
|
||||
|
||||
**Sémantique des limites :**
|
||||
|
||||
- `text_end` : diffuse les blocs dès que le découpeur les émet ; vide le tampon à chaque `text_end`.
|
||||
- `text_end` : streame les blocs dès que le découpeur les émet ; vide le tampon à chaque `text_end`.
|
||||
- `message_end` : attend que le message de l’assistant soit terminé, puis vide la sortie mise en tampon.
|
||||
|
||||
`message_end` utilise toujours le découpeur si le texte mis en tampon dépasse `maxChars`, il peut donc émettre plusieurs morceaux à la fin.
|
||||
|
||||
### Livraison des médias avec la diffusion par blocs
|
||||
### Livraison des médias avec le streaming par blocs
|
||||
|
||||
Les directives `MEDIA:` sont des métadonnées de livraison normales. Lorsque la diffusion par blocs envoie tôt un bloc média, OpenClaw mémorise cette livraison pour le tour. Si la charge utile finale de l’assistant répète la même URL de média, la livraison finale retire le média dupliqué au lieu d’envoyer à nouveau la pièce jointe.
|
||||
Les directives `MEDIA:` sont des métadonnées de livraison normales. Quand le streaming par blocs envoie tôt un bloc média, OpenClaw mémorise cette livraison pour le tour. Si la charge utile finale de l’assistant répète la même URL de média, la livraison finale supprime le média dupliqué au lieu de renvoyer la pièce jointe.
|
||||
|
||||
Les charges utiles finales exactement dupliquées sont supprimées. Si la charge utile finale ajoute du texte distinct autour d’un média déjà diffusé, OpenClaw envoie tout de même le nouveau texte tout en conservant une livraison unique du média. Cela évite les notes vocales ou fichiers en double sur des canaux comme Telegram lorsqu’un agent émet `MEDIA:` pendant la diffusion et que le fournisseur l’inclut aussi dans la réponse terminée.
|
||||
Les charges utiles finales exactement dupliquées sont supprimées. Si la charge utile finale ajoute un texte distinct autour d’un média déjà streamé, OpenClaw envoie quand même le nouveau texte tout en conservant une livraison unique du média. Cela évite les notes vocales ou fichiers en double sur des canaux comme Telegram lorsqu’un agent émet `MEDIA:` pendant le streaming et que le fournisseur l’inclut aussi dans la réponse terminée.
|
||||
|
||||
## Algorithme de découpage (limites basse/haute)
|
||||
## Algorithme de découpage (bornes basse/haute)
|
||||
|
||||
Le découpage par blocs est implémenté par `EmbeddedBlockChunker` :
|
||||
Le découpage en blocs est implémenté par `EmbeddedBlockChunker` :
|
||||
|
||||
- **Limite basse :** n’émet pas tant que le tampon >= `minChars` (sauf si forcé).
|
||||
- **Limite haute :** privilégie les coupures avant `maxChars` ; si forcé, coupe à `maxChars`.
|
||||
- **Préférence de coupure :** `paragraph` → `newline` → `sentence` → `whitespace` → coupure dure.
|
||||
- **Blocs de code :** ne coupe jamais à l’intérieur des blocs ; lorsqu’une coupure est forcée à `maxChars`, ferme puis rouvre le bloc pour garder un Markdown valide.
|
||||
- **Borne basse :** n’émet rien tant que le tampon >= `minChars` (sauf si forcé).
|
||||
- **Borne haute :** préfère les ruptures avant `maxChars` ; si forcé, découpe à `maxChars`.
|
||||
- **Préférence de rupture :** `paragraph` → `newline` → `sentence` → `whitespace` → rupture forcée.
|
||||
- **Blocs de code :** ne découpe jamais à l’intérieur des blocs ; quand un découpage est forcé à `maxChars`, ferme puis rouvre le bloc pour conserver un Markdown valide.
|
||||
|
||||
`maxChars` est plafonné à la valeur `textChunkLimit` du canal, vous ne pouvez donc pas dépasser les limites par canal.
|
||||
`maxChars` est plafonné à la valeur `textChunkLimit` du canal, vous ne pouvez donc pas dépasser les plafonds propres à chaque canal.
|
||||
|
||||
## Coalescence (fusion des blocs diffusés)
|
||||
## Coalescence (fusion des blocs streamés)
|
||||
|
||||
Lorsque la diffusion par blocs est activée, OpenClaw peut **fusionner les morceaux de blocs consécutifs** avant de les envoyer. Cela réduit le « spam sur une seule ligne » tout en fournissant une sortie progressive.
|
||||
Lorsque le streaming par blocs est activé, OpenClaw peut **fusionner des morceaux de blocs consécutifs** avant de les envoyer. Cela réduit le « spam d’une seule ligne » tout en fournissant une sortie progressive.
|
||||
|
||||
- La coalescence attend des **pauses d’inactivité** (`idleMs`) avant de vider le tampon.
|
||||
- La coalescence attend des **intervalles d’inactivité** (`idleMs`) avant de vider le tampon.
|
||||
- Les tampons sont plafonnés par `maxChars` et seront vidés s’ils le dépassent.
|
||||
- `minChars` empêche l’envoi de fragments minuscules tant qu’assez de texte ne s’est pas accumulé (le vidage final envoie toujours le texte restant).
|
||||
- Le séparateur est dérivé de `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espace).
|
||||
- Des remplacements par canal sont disponibles via `*.blockStreamingCoalesce` (y compris les configurations par compte).
|
||||
- La valeur `minChars` de coalescence par défaut est portée à 1500 pour Signal/Slack/Discord, sauf remplacement.
|
||||
- Le séparateur est dérivé de `blockStreamingChunk.breakPreference`
|
||||
(`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espace).
|
||||
- Des remplacements par canal sont disponibles via `*.blockStreamingCoalesce` (y compris les configs par compte).
|
||||
- La valeur par défaut de coalescence `minChars` est portée à 1500 pour Signal/Slack/Discord sauf remplacement.
|
||||
|
||||
## Rythme humain entre les blocs
|
||||
|
||||
Lorsque la diffusion par blocs est activée, vous pouvez ajouter une **pause aléatoire** entre les réponses par blocs (après le premier bloc). Cela rend les réponses en plusieurs bulles plus naturelles.
|
||||
Lorsque le streaming par blocs est activé, vous pouvez ajouter une **pause aléatoire** entre les réponses par blocs (après le premier bloc). Cela rend les réponses en plusieurs bulles plus naturelles.
|
||||
|
||||
- Configuration : `agents.defaults.humanDelay` (remplacement par agent via `agents.list[].humanDelay`).
|
||||
- Config : `agents.defaults.humanDelay` (remplacement par agent via `agents.list[].humanDelay`).
|
||||
- Modes : `off` (par défaut), `natural` (800–2500 ms), `custom` (`minMs`/`maxMs`).
|
||||
- S’applique uniquement aux **réponses par blocs**, pas aux réponses finales ni aux résumés d’outils.
|
||||
|
||||
## « Diffuser les morceaux ou tout »
|
||||
## « Streamer les morceaux ou tout »
|
||||
|
||||
Cela correspond à :
|
||||
|
||||
- **Diffuser les morceaux :** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (émettre au fil de l’eau). Les canaux hors Telegram nécessitent aussi `*.blockStreaming: true`.
|
||||
- **Tout diffuser à la fin :** `blockStreamingBreak: "message_end"` (vider une fois, éventuellement en plusieurs morceaux si très long).
|
||||
- **Aucune diffusion par blocs :** `blockStreamingDefault: "off"` (réponse finale uniquement).
|
||||
- **Streamer les morceaux :** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (émettre au fil de l’eau). Les canaux autres que Telegram ont aussi besoin de `*.blockStreaming: true`.
|
||||
- **Streamer tout à la fin :** `blockStreamingBreak: "message_end"` (vider une fois, avec éventuellement plusieurs morceaux si c’est très long).
|
||||
- **Pas de streaming par blocs :** `blockStreamingDefault: "off"` (réponse finale seulement).
|
||||
|
||||
**Note sur les canaux :** la diffusion par blocs est **désactivée sauf si** `*.blockStreaming` est explicitement défini sur `true`. Les canaux peuvent diffuser un aperçu en direct (`channels.<channel>.streaming`) sans réponses par blocs.
|
||||
**Note sur les canaux :** le streaming par blocs est **désactivé sauf si**
|
||||
`*.blockStreaming` est explicitement défini sur `true`. Les canaux peuvent streamer un aperçu en direct
|
||||
(`channels.<channel>.streaming`) sans réponses par blocs.
|
||||
|
||||
Rappel d’emplacement de configuration : les valeurs par défaut `blockStreaming*` se trouvent sous `agents.defaults`, pas dans la configuration racine.
|
||||
Rappel sur l’emplacement de la config : les valeurs par défaut `blockStreaming*` se trouvent sous
|
||||
`agents.defaults`, pas à la racine de la config.
|
||||
|
||||
## Modes de diffusion d’aperçu
|
||||
## Modes de streaming d’aperçu
|
||||
|
||||
Clé canonique : `channels.<channel>.streaming`
|
||||
|
||||
Modes :
|
||||
|
||||
- `off` : désactive la diffusion d’aperçu.
|
||||
- `off` : désactive le streaming d’aperçu.
|
||||
- `partial` : aperçu unique remplacé par le dernier texte.
|
||||
- `block` : mises à jour d’aperçu par étapes découpées/ajoutées.
|
||||
- `block` : mises à jour de l’aperçu par étapes découpées/ajoutées.
|
||||
- `progress` : aperçu de progression/statut pendant la génération, réponse finale à la fin.
|
||||
|
||||
`streaming.mode: "block"` est un mode de diffusion d’aperçu pour les canaux modifiables comme Discord et Telegram. Il n’active pas la livraison par blocs du canal à cet endroit. Utilisez `streaming.block.enabled` ou l’ancienne clé de canal `blockStreaming` lorsque vous voulez des réponses par blocs normales. Microsoft Teams est l’exception : il n’a pas de transport de bloc pour aperçu de brouillon, donc `streaming.mode: "block"` correspond à la livraison par blocs Teams au lieu de la diffusion partielle/progression native.
|
||||
`streaming.mode: "block"` est un mode de streaming d’aperçu pour les canaux pouvant être modifiés, comme Discord et Telegram. Il n’active pas la livraison de blocs du canal à cet endroit. Utilisez `streaming.block.enabled` ou l’ancienne clé de canal `blockStreaming` lorsque vous voulez des réponses par blocs normales. Microsoft Teams est l’exception : il ne dispose pas de transport de blocs d’aperçu brouillon, donc `streaming.mode: "block"` correspond à la livraison de blocs Teams au lieu du streaming partiel/de progression natif.
|
||||
|
||||
### Correspondance des canaux
|
||||
|
||||
| Canal | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ------------------------ |
|
||||
| Canal | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ------------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | brouillon de progression modifiable |
|
||||
| Discord | ✅ | ✅ | ✅ | brouillon de progression modifiable |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | flux de progression natif |
|
||||
|
||||
Slack uniquement :
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` active/désactive les appels à l’API de diffusion native Slack lorsque `channels.slack.streaming.mode="partial"` (par défaut : `true`).
|
||||
- La diffusion native Slack et le statut de fil d’assistant Slack nécessitent une cible de fil de réponse. Les messages privés de premier niveau n’affichent pas cet aperçu de style fil, mais ils peuvent tout de même utiliser les publications et modifications d’aperçu de brouillon Slack.
|
||||
- `channels.slack.streaming.nativeTransport` bascule les appels à l’API de streaming native Slack lorsque `channels.slack.streaming.mode="partial"` (par défaut : `true`).
|
||||
- Le streaming natif Slack et le statut de fil d’assistant Slack nécessitent une cible de fil de réponse. Les DM de premier niveau n’affichent pas cet aperçu de style fil, mais ils peuvent toujours utiliser les publications et modifications d’aperçu brouillon Slack.
|
||||
|
||||
Migration des anciennes clés :
|
||||
|
||||
@ -145,52 +149,52 @@ Migration des anciennes clés :
|
||||
|
||||
Telegram :
|
||||
|
||||
- Utilise `sendMessage` + `editMessageText` pour les mises à jour d’aperçu dans les messages privés et les groupes/sujets.
|
||||
- Envoie un nouveau message final au lieu de modifier sur place lorsqu’un aperçu est visible depuis environ une minute, puis nettoie l’aperçu afin que l’horodatage de Telegram reflète la fin de la réponse.
|
||||
- La diffusion d’aperçu est ignorée lorsque la diffusion par blocs Telegram est explicitement activée (pour éviter une double diffusion).
|
||||
- `/reasoning stream` peut écrire le raisonnement dans l’aperçu.
|
||||
- Utilise `sendMessage` + `editMessageText` pour les mises à jour d’aperçu dans les DM et les groupes/sujets.
|
||||
- Envoie un nouveau message final au lieu de modifier sur place lorsqu’un aperçu est visible depuis environ une minute, puis nettoie l’aperçu afin que l’horodatage Telegram reflète la fin de la réponse.
|
||||
- Le streaming d’aperçu est ignoré lorsque le streaming par blocs Telegram est explicitement activé (pour éviter un double streaming).
|
||||
- `/reasoning stream` peut écrire le raisonnement dans un aperçu transitoire supprimé après la livraison finale.
|
||||
|
||||
Discord :
|
||||
|
||||
- Utilise l’envoi + la modification des messages d’aperçu.
|
||||
- Utilise l’envoi + la modification de messages d’aperçu.
|
||||
- Le mode `block` utilise le découpage de brouillon (`draftChunk`).
|
||||
- La diffusion d’aperçu est ignorée lorsque la diffusion par blocs Discord est explicitement activée.
|
||||
- Les médias finaux, erreurs et charges utiles de réponse explicite annulent les aperçus en attente sans vider un nouveau brouillon, puis utilisent la livraison normale.
|
||||
- Le streaming d’aperçu est ignoré lorsque le streaming par blocs Discord est explicitement activé.
|
||||
- Les charges utiles finales de média, d’erreur et de réponse explicite annulent les aperçus en attente sans vider un nouveau brouillon, puis utilisent la livraison normale.
|
||||
|
||||
Slack :
|
||||
|
||||
- `partial` peut utiliser la diffusion native Slack (`chat.startStream`/`append`/`stop`) lorsqu’elle est disponible.
|
||||
- `block` utilise des aperçus de brouillon de type ajout.
|
||||
- `progress` utilise du texte d’aperçu de statut, puis la réponse finale.
|
||||
- Les messages privés de premier niveau sans fil de réponse utilisent des publications et modifications d’aperçu de brouillon au lieu de la diffusion native Slack.
|
||||
- Les diffusions d’aperçu native et de brouillon suppriment les réponses par blocs pour ce tour, afin qu’une réponse Slack soit diffusée par un seul chemin de livraison.
|
||||
- Les charges utiles finales de média/erreur et les finals de progression ne créent pas de messages de brouillon jetables ; seuls les finals texte/bloc pouvant modifier l’aperçu vident le texte de brouillon en attente.
|
||||
- `partial` peut utiliser le streaming natif Slack (`chat.startStream`/`append`/`stop`) lorsqu’il est disponible.
|
||||
- `block` utilise des aperçus brouillon par ajouts successifs.
|
||||
- `progress` utilise le texte d’aperçu de statut, puis la réponse finale.
|
||||
- Les DM de premier niveau sans fil de réponse utilisent des publications et modifications d’aperçu brouillon au lieu du streaming natif Slack.
|
||||
- Le streaming d’aperçu natif et brouillon supprime les réponses par blocs pour ce tour, afin qu’une réponse Slack soit streamée par un seul chemin de livraison.
|
||||
- Les charges utiles finales de média/erreur et les finales de progression ne créent pas de messages brouillon jetables ; seuls les finals de texte/bloc pouvant modifier l’aperçu vident le texte de brouillon en attente.
|
||||
|
||||
Mattermost :
|
||||
|
||||
- Diffuse la réflexion, l’activité des outils et le texte de réponse partiel dans une seule publication d’aperçu de brouillon, qui est finalisée sur place lorsque la réponse finale peut être envoyée en toute sécurité.
|
||||
- Revient à l’envoi d’une nouvelle publication finale si la publication d’aperçu a été supprimée ou est indisponible au moment de la finalisation.
|
||||
- Streame la réflexion, l’activité des outils et le texte partiel de réponse dans une seule publication d’aperçu brouillon qui se finalise sur place lorsque la réponse finale peut être envoyée en toute sécurité.
|
||||
- Revient à l’envoi d’une nouvelle publication finale si la publication d’aperçu a été supprimée ou n’est pas disponible au moment de la finalisation.
|
||||
- Les charges utiles finales de média/erreur annulent les mises à jour d’aperçu en attente avant la livraison normale au lieu de vider une publication d’aperçu temporaire.
|
||||
|
||||
Matrix :
|
||||
|
||||
- Les aperçus de brouillon sont finalisés sur place lorsque le texte final peut réutiliser l’événement d’aperçu.
|
||||
- Les finals média seuls, erreur et incompatibles avec la cible de réponse annulent les mises à jour d’aperçu en attente avant la livraison normale ; un aperçu obsolète déjà visible est masqué.
|
||||
- Les aperçus brouillon se finalisent sur place lorsque le texte final peut réutiliser l’événement d’aperçu.
|
||||
- Les finals média seuls, erreur et avec cible de réponse non correspondante annulent les mises à jour d’aperçu en attente avant la livraison normale ; un aperçu périmé déjà visible est supprimé.
|
||||
|
||||
### Mises à jour d’aperçu de progression des outils
|
||||
|
||||
La diffusion d’aperçu peut aussi inclure des mises à jour de **progression des outils** — de courtes lignes de statut comme « recherche sur le web », « lecture du fichier » ou « appel de l’outil » — qui apparaissent dans le même message d’aperçu pendant l’exécution des outils, avant la réponse finale. Cela garde les tours d’outils en plusieurs étapes visuellement actifs plutôt que silencieux entre le premier aperçu de réflexion et la réponse finale.
|
||||
Le streaming d’aperçu peut aussi inclure des mises à jour de **progression des outils** — de courtes lignes de statut comme « recherche sur le Web », « lecture du fichier » ou « appel de l’outil » — qui apparaissent dans le même message d’aperçu pendant l’exécution des outils, avant la réponse finale. Cela garde les tours d’outils en plusieurs étapes visuellement actifs plutôt que silencieux entre le premier aperçu de réflexion et la réponse finale.
|
||||
|
||||
Surfaces prises en charge :
|
||||
|
||||
- **Discord**, **Slack**, **Telegram** et **Matrix** diffusent par défaut la progression des outils dans la modification d’aperçu en direct lorsque la diffusion d’aperçu est active. Microsoft Teams utilise son flux de progression natif dans les conversations personnelles.
|
||||
- Telegram est livré avec les mises à jour d’aperçu de progression des outils activées depuis `v2026.4.22` ; les conserver activées préserve ce comportement publié.
|
||||
- **Mattermost** intègre déjà l’activité des outils dans sa seule publication d’aperçu de brouillon (voir ci-dessus).
|
||||
- Les modifications de progression des outils suivent le mode de diffusion d’aperçu actif ; elles sont ignorées lorsque la diffusion d’aperçu est `off` ou lorsque la diffusion par blocs a pris le relais du message. Sur Telegram, `streaming.mode: "off"` signifie final uniquement : le bavardage de progression générique est aussi supprimé au lieu d’être livré comme messages de statut autonomes, tandis que les invites d’approbation, les charges utiles de média et les erreurs sont toujours routées normalement.
|
||||
- Pour conserver la diffusion d’aperçu mais masquer les lignes de progression des outils, définissez `streaming.preview.toolProgress` sur `false` pour ce canal. Pour désactiver entièrement les modifications d’aperçu, définissez `streaming.mode` sur `off`.
|
||||
- Les réponses à une citation sélectionnée Telegram sont une exception : lorsque `replyToMode` n’est pas `"off"` et qu’un texte de citation sélectionné est présent, OpenClaw ignore le flux d’aperçu de réponse pour ce tour, donc les lignes d’aperçu de progression des outils ne peuvent pas s’afficher. Les réponses au message actuel sans texte de citation sélectionné conservent la diffusion d’aperçu. Consultez la [documentation du canal Telegram](/fr/channels/telegram) pour plus de détails.
|
||||
- **Discord**, **Slack**, **Telegram** et **Matrix** streament par défaut la progression des outils dans la modification d’aperçu en direct lorsque le streaming d’aperçu est actif. Microsoft Teams utilise son flux de progression natif dans les conversations personnelles.
|
||||
- Telegram est livré avec les mises à jour d’aperçu de progression des outils activées depuis `v2026.4.22` ; les garder activées préserve ce comportement publié.
|
||||
- **Mattermost** intègre déjà l’activité des outils dans sa publication d’aperçu brouillon unique (voir ci-dessus).
|
||||
- Les modifications de progression des outils suivent le mode de streaming d’aperçu actif ; elles sont ignorées lorsque le streaming d’aperçu est `off` ou lorsque le streaming par blocs a pris le contrôle du message. Sur Telegram, `streaming.mode: "off"` signifie final seulement : les messages génériques de progression sont aussi supprimés au lieu d’être livrés comme messages de statut autonomes, tandis que les invites d’approbation, les charges utiles média et les erreurs continuent d’être routées normalement.
|
||||
- Pour conserver le streaming d’aperçu mais masquer les lignes de progression des outils, définissez `streaming.preview.toolProgress` sur `false` pour ce canal. Pour garder les lignes de progression des outils visibles tout en masquant le texte de commande/exec, définissez `streaming.preview.commandText` sur `"status"` ou `streaming.progress.commandText` sur `"status"` ; la valeur par défaut est `"raw"` afin de préserver le comportement publié. Cette politique est partagée par les canaux de brouillon/progression qui utilisent le moteur de rendu de progression compact d’OpenClaw, notamment Discord, Matrix, Microsoft Teams, Mattermost, les aperçus brouillon Slack et Telegram. Pour désactiver entièrement les modifications d’aperçu, définissez `streaming.mode` sur `off`.
|
||||
- Les réponses à une citation sélectionnée Telegram sont une exception : lorsque `replyToMode` n’est pas `"off"` et qu’un texte de citation sélectionnée est présent, OpenClaw ignore le flux d’aperçu de réponse pour ce tour, si bien que les lignes d’aperçu de progression des outils ne peuvent pas s’afficher. Les réponses au message actuel sans texte de citation sélectionnée conservent le streaming d’aperçu. Consultez la [documentation du canal Telegram](/fr/channels/telegram) pour plus de détails.
|
||||
|
||||
Exemple :
|
||||
Gardez les lignes de progression visibles, mais masquez le texte brut des commandes/exécutions :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -199,7 +203,26 @@ Exemple :
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"toolProgress": false
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez la même structure sous une autre clé de canal de progression compact, par exemple `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost`, ou les aperçus de brouillons Slack. Pour le mode brouillon de progression, placez la même politique sous `streaming.progress` :
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -209,7 +232,7 @@ Exemple :
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Brouillons de progression](/fr/concepts/progress-drafts) — messages visibles de travail en cours qui se mettent à jour pendant les longs tours
|
||||
- [Brouillons de progression](/fr/concepts/progress-drafts) — messages de travail en cours visibles qui se mettent à jour pendant les longs tours
|
||||
- [Messages](/fr/concepts/messages) — cycle de vie et livraison des messages
|
||||
- [Nouvelle tentative](/fr/concepts/retry) — comportement de nouvelle tentative en cas d’échec de livraison
|
||||
- [Canaux](/fr/channels) — prise en charge de la diffusion par canal
|
||||
- [Réessayer](/fr/concepts/retry) — comportement de nouvelle tentative en cas d’échec de livraison
|
||||
- [Canaux](/fr/channels) — prise en charge du streaming par canal
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -2,22 +2,22 @@
|
||||
read_when:
|
||||
- Mise à jour d’OpenClaw
|
||||
- Quelque chose ne fonctionne plus après une mise à jour
|
||||
summary: Mettre à jour OpenClaw en toute sécurité (installation globale ou depuis les sources), avec stratégie de restauration
|
||||
summary: Mettre à jour OpenClaw en toute sécurité (installation globale ou depuis les sources), avec une stratégie de restauration
|
||||
title: Mise à jour
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:35:29Z"
|
||||
generated_at: "2026-05-04T07:04:52Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
|
||||
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
|
||||
source_path: install/updating.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gardez OpenClaw à jour.
|
||||
Maintenez OpenClaw à jour.
|
||||
|
||||
## Recommandé : `openclaw update`
|
||||
|
||||
La méthode la plus rapide pour effectuer une mise à jour. Elle détecte votre type d’installation (npm ou git), récupère la dernière version, exécute `openclaw doctor` et redémarre le Gateway.
|
||||
Le moyen le plus rapide de mettre à jour. Il détecte votre type d’installation (npm ou git), récupère la dernière version, exécute `openclaw doctor` et redémarre le Gateway.
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
@ -32,21 +32,21 @@ openclaw update --tag main
|
||||
openclaw update --dry-run # preview without applying
|
||||
```
|
||||
|
||||
`openclaw update` n’accepte pas `--verbose`. Pour diagnostiquer une mise à jour, utilisez
|
||||
`--dry-run` afin de prévisualiser les actions prévues, `--json` pour obtenir des résultats structurés, ou
|
||||
`openclaw update status --json` pour examiner l’état du canal et de la disponibilité. Le
|
||||
`openclaw update` n’accepte pas `--verbose`. Pour les diagnostics de mise à jour, utilisez
|
||||
`--dry-run` pour prévisualiser les actions prévues, `--json` pour des résultats structurés, ou
|
||||
`openclaw update status --json` pour inspecter l’état du canal et de la disponibilité. Le
|
||||
programme d’installation possède son propre indicateur `--verbose`, mais cet indicateur ne fait pas partie de
|
||||
`openclaw update`.
|
||||
|
||||
`--channel beta` privilégie la bêta, mais l’environnement d’exécution revient à la version stable/latest lorsque
|
||||
le tag bêta est absent ou plus ancien que la dernière version stable. Utilisez `--tag beta`
|
||||
si vous voulez le dist-tag npm bêta brut pour une mise à jour ponctuelle de paquet.
|
||||
`--channel beta` privilégie beta, mais le runtime se rabat sur stable/latest lorsque
|
||||
le tag beta est absent ou plus ancien que la dernière version stable. Utilisez `--tag beta`
|
||||
si vous voulez le dist-tag npm beta brut pour une mise à jour de paquet ponctuelle.
|
||||
|
||||
Consultez [Canaux de développement](/fr/install/development-channels) pour la sémantique des canaux.
|
||||
|
||||
## Basculer entre les installations npm et git
|
||||
|
||||
Utilisez les canaux lorsque vous voulez changer de type d’installation. Le programme de mise à jour conserve votre
|
||||
Utilisez les canaux lorsque vous voulez changer le type d’installation. Le programme de mise à jour conserve votre
|
||||
état, votre configuration, vos identifiants et votre espace de travail dans `~/.openclaw` ; il ne change que
|
||||
l’installation du code OpenClaw utilisée par la CLI et le Gateway.
|
||||
|
||||
@ -65,12 +65,12 @@ openclaw update --channel dev --dry-run
|
||||
openclaw update --channel stable --dry-run
|
||||
```
|
||||
|
||||
Le canal `dev` garantit un checkout git, le compile et installe la CLI globale
|
||||
Le canal `dev` garantit un checkout git, le construit et installe la CLI globale
|
||||
depuis ce checkout. Les canaux `stable` et `beta` utilisent des installations de paquets. Si le
|
||||
Gateway est déjà installé, `openclaw update` actualise les métadonnées du service
|
||||
et le redémarre, sauf si vous passez `--no-restart`.
|
||||
|
||||
## Alternative : réexécuter le programme d’installation
|
||||
## Alternative : relancer le programme d’installation
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
@ -80,32 +80,37 @@ Ajoutez `--no-onboard` pour ignorer l’intégration. Pour forcer un type d’in
|
||||
le programme d’installation, passez `--install-method git --no-onboard` ou
|
||||
`--install-method npm --no-onboard`.
|
||||
|
||||
Si `openclaw update` échoue après la phase d’installation du paquet npm, réexécutez le
|
||||
programme d’installation. Le programme d’installation n’appelle pas l’ancien programme de mise à jour ; il exécute directement
|
||||
l’installation du paquet global et peut récupérer une installation npm partiellement mise à jour.
|
||||
Si `openclaw update` échoue après la phase d’installation du paquet npm, relancez le
|
||||
programme d’installation. Le programme d’installation n’appelle pas l’ancien programme de mise à jour ; il exécute directement l’installation du
|
||||
paquet global et peut récupérer une installation npm partiellement mise à jour.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
```
|
||||
|
||||
Pour limiter la récupération à une version ou un dist-tag spécifique, ajoutez `--version` :
|
||||
Pour épingler la récupération à une version ou un dist-tag spécifique, ajoutez `--version` :
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
|
||||
```
|
||||
|
||||
## Alternative : npm, pnpm ou bun manuel
|
||||
## Alternative : npm, pnpm ou bun manuels
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
Préférez `openclaw update` pour les installations supervisées, car il peut coordonner le
|
||||
remplacement du paquet avec le service Gateway en cours d’exécution. Si vous effectuez une mise à jour manuelle pendant qu’un
|
||||
Gateway géré est en cours d’exécution, redémarrez le Gateway immédiatement après la fin du gestionnaire de
|
||||
paquets afin que l’ancien processus ne continue pas à servir depuis des fichiers de paquet remplacés.
|
||||
|
||||
Lorsque `openclaw update` gère une installation npm globale, il installe d’abord la cible dans
|
||||
un préfixe npm temporaire, vérifie l’inventaire `dist` empaqueté, puis remplace
|
||||
l’arborescence propre du paquet dans le véritable préfixe global. Cela évite que npm superpose un
|
||||
nouveau paquet à des fichiers obsolètes de l’ancien paquet. Si la commande d’installation échoue,
|
||||
un préfixe npm temporaire, vérifie l’inventaire `dist` du paquet, puis remplace
|
||||
l’arborescence propre du paquet dans le préfixe global réel. Cela évite que npm superpose un
|
||||
nouveau paquet sur des fichiers obsolètes de l’ancien paquet. Si la commande d’installation échoue,
|
||||
OpenClaw réessaie une fois avec `--omit=optional`. Cette nouvelle tentative aide les hôtes où les
|
||||
dépendances optionnelles natives ne peuvent pas être compilées, tout en gardant l’échec initial visible
|
||||
dépendances optionnelles natives ne peuvent pas compiler, tout en gardant l’échec initial visible
|
||||
si le repli échoue également.
|
||||
|
||||
```bash
|
||||
@ -119,28 +124,28 @@ bun add -g openclaw@latest
|
||||
### Sujets avancés d’installation npm
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Read-only package tree">
|
||||
OpenClaw traite les installations globales empaquetées comme étant en lecture seule à l’exécution, même lorsque le répertoire global du paquet est accessible en écriture par l’utilisateur actuel. Les installations de paquets Plugin résident dans des racines npm/git appartenant à OpenClaw sous le répertoire de configuration utilisateur, et le démarrage du Gateway ne modifie pas l’arborescence du paquet OpenClaw.
|
||||
<Accordion title="Arborescence de paquets en lecture seule">
|
||||
OpenClaw traite les installations globales empaquetées comme étant en lecture seule à l’exécution, même lorsque le répertoire global du paquet est accessible en écriture par l’utilisateur courant. Les installations de paquets Plugin résident dans des racines npm/git appartenant à OpenClaw sous le répertoire de configuration de l’utilisateur, et le démarrage du Gateway ne modifie pas l’arborescence du paquet OpenClaw.
|
||||
|
||||
Certaines configurations npm Linux installent les paquets globaux sous des répertoires appartenant à root, comme `/usr/lib/node_modules/openclaw`. OpenClaw prend en charge cette disposition, car les commandes d’installation/mise à jour de Plugin écrivent en dehors de ce répertoire global de paquet.
|
||||
Certaines configurations npm Linux installent les paquets globaux dans des répertoires appartenant à root, tels que `/usr/lib/node_modules/openclaw`. OpenClaw prend en charge cette disposition, car les commandes d’installation/mise à jour de Plugin écrivent en dehors de ce répertoire global de paquet.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hardened systemd units">
|
||||
Donnez à OpenClaw un accès en écriture à ses racines de configuration/état afin que les installations explicites de Plugin, les mises à jour de Plugin et le nettoyage par doctor puissent persister leurs changements :
|
||||
<Accordion title="Unités systemd renforcées">
|
||||
Accordez à OpenClaw un accès en écriture à ses racines de configuration/état afin que les installations explicites de Plugin, les mises à jour de Plugin et le nettoyage par doctor puissent conserver leurs changements :
|
||||
|
||||
```ini
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Disk-space preflight">
|
||||
Avant les mises à jour de paquets et les installations explicites de Plugin, OpenClaw tente une vérification opportuniste de l’espace disque pour le volume cible. Un espace faible produit un avertissement avec le chemin vérifié, mais ne bloque pas la mise à jour, car les quotas de système de fichiers, les instantanés et les volumes réseau peuvent changer après la vérification. L’installation réelle par le gestionnaire de paquets et la vérification post-installation restent l’autorité.
|
||||
<Accordion title="Vérification préalable de l’espace disque">
|
||||
Avant les mises à jour de paquets et les installations explicites de Plugin, OpenClaw tente une vérification d’espace disque au mieux pour le volume cible. Un espace insuffisant produit un avertissement avec le chemin vérifié, mais ne bloque pas la mise à jour, car les quotas de système de fichiers, les instantanés et les volumes réseau peuvent changer après la vérification. L’installation réelle par le gestionnaire de paquets et la vérification après installation restent déterminantes.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Mise à jour automatique
|
||||
## Programme de mise à jour automatique
|
||||
|
||||
La mise à jour automatique est désactivée par défaut. Activez-la dans `~/.openclaw/openclaw.json` :
|
||||
Le programme de mise à jour automatique est désactivé par défaut. Activez-le dans `~/.openclaw/openclaw.json` :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -156,20 +161,20 @@ La mise à jour automatique est désactivée par défaut. Activez-la dans `~/.op
|
||||
}
|
||||
```
|
||||
|
||||
| Canal | Comportement |
|
||||
| Canal | Comportement |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Attend `stableDelayHours`, puis applique avec un décalage déterministe sur `stableJitterHours` (déploiement réparti). |
|
||||
| `beta` | Vérifie toutes les `betaCheckIntervalHours` (par défaut : toutes les heures) et applique immédiatement. |
|
||||
| `dev` | Aucune application automatique. Utilisez `openclaw update` manuellement. |
|
||||
| `stable` | Attend `stableDelayHours`, puis applique avec une gigue déterministe sur `stableJitterHours` (déploiement étalé). |
|
||||
| `beta` | Vérifie toutes les `betaCheckIntervalHours` (par défaut : toutes les heures) et applique immédiatement. |
|
||||
| `dev` | Aucune application automatique. Utilisez `openclaw update` manuellement. |
|
||||
|
||||
Le Gateway journalise également une indication de mise à jour au démarrage (désactivez avec `update.checkOnStart: false`).
|
||||
Le Gateway journalise aussi une indication de mise à jour au démarrage (désactivez avec `update.checkOnStart: false`).
|
||||
Pour une rétrogradation ou une récupération après incident, définissez `OPENCLAW_NO_AUTO_UPDATE=1` dans l’environnement du Gateway afin de bloquer les applications automatiques même lorsque `update.auto.enabled` est configuré. Les indications de mise à jour au démarrage peuvent toujours s’exécuter, sauf si `update.checkOnStart` est également désactivé.
|
||||
|
||||
Les mises à jour du gestionnaire de paquets demandées via le gestionnaire actif du plan de contrôle du Gateway
|
||||
forcent un redémarrage de mise à jour non différé, sans délai de récupération, après le remplacement du paquet. Cela
|
||||
évite de conserver un ancien processus en mémoire assez longtemps pour charger paresseusement des morceaux
|
||||
depuis une arborescence de paquet qui a déjà été remplacée. La commande shell `openclaw update`
|
||||
reste le chemin privilégié pour les installations supervisées, car elle peut arrêter et
|
||||
Les mises à jour par gestionnaire de paquets demandées via le gestionnaire du plan de contrôle live du Gateway
|
||||
forcent un redémarrage de mise à jour non différé et sans période de refroidissement après le remplacement du paquet. Cela
|
||||
évite de laisser un ancien processus en mémoire assez longtemps pour charger paresseusement des fragments
|
||||
depuis une arborescence de paquets qui a déjà été remplacée. La commande shell `openclaw update`
|
||||
reste le chemin recommandé pour les installations supervisées, car elle peut arrêter et
|
||||
redémarrer le service autour de la mise à jour.
|
||||
|
||||
## Après la mise à jour
|
||||
@ -182,7 +187,7 @@ redémarrer le service autour de la mise à jour.
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Migre la configuration, audite les politiques de messages privés et vérifie l’état du Gateway. Détails : [Doctor](/fr/gateway/doctor)
|
||||
Migre la configuration, audite les politiques de DM et vérifie la santé du Gateway. Détails : [Doctor](/fr/gateway/doctor)
|
||||
|
||||
### Redémarrer le Gateway
|
||||
|
||||
@ -209,7 +214,7 @@ openclaw gateway restart
|
||||
```
|
||||
|
||||
<Tip>
|
||||
`npm view openclaw version` affiche la version actuellement publiée.
|
||||
`npm view openclaw version` affiche la version publiée actuelle.
|
||||
</Tip>
|
||||
|
||||
### Épingler un commit (source)
|
||||
@ -225,13 +230,13 @@ Pour revenir à la dernière version : `git checkout main && git pull`.
|
||||
|
||||
## Si vous êtes bloqué
|
||||
|
||||
- Exécutez `openclaw doctor` à nouveau et lisez attentivement la sortie.
|
||||
- Pour `openclaw update --channel dev` sur les checkouts source, le programme de mise à jour initialise automatiquement `pnpm` si nécessaire. Si vous voyez une erreur d’amorçage pnpm/corepack, installez `pnpm` manuellement (ou réactivez `corepack`) et relancez la mise à jour.
|
||||
- Vérifiez : [Dépannage](/fr/gateway/troubleshooting)
|
||||
- Demandez sur Discord : [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
- Exécutez de nouveau `openclaw doctor` et lisez attentivement la sortie.
|
||||
- Pour `openclaw update --channel dev` sur des checkouts source, le programme de mise à jour auto-initialise `pnpm` si nécessaire. Si vous voyez une erreur d’initialisation pnpm/corepack, installez `pnpm` manuellement (ou réactivez `corepack`) et relancez la mise à jour.
|
||||
- Consultez : [Dépannage](/fr/gateway/troubleshooting)
|
||||
- Demandez de l’aide sur Discord : [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
|
||||
## Associé
|
||||
## Connexe
|
||||
|
||||
- [Vue d’ensemble de l’installation](/fr/install) : toutes les méthodes d’installation.
|
||||
- [Doctor](/fr/gateway/doctor) : vérifications d’état après les mises à jour.
|
||||
- [Migration](/fr/install/migrating) : guides de migration des versions majeures.
|
||||
- [Doctor](/fr/gateway/doctor) : vérifications de santé après les mises à jour.
|
||||
- [Migration](/fr/install/migrating) : guides de migration de versions majeures.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez passer un appel vocal sortant depuis OpenClaw
|
||||
- Vous configurez ou développez le Plugin d’appel vocal
|
||||
- Vous configurez ou développez le Plugin d’appels vocaux
|
||||
- Vous avez besoin de voix en temps réel ou de transcription en continu pour la téléphonie
|
||||
sidebarTitle: Voice call
|
||||
summary: Passez des appels vocaux sortants et acceptez des appels vocaux entrants via Twilio, Telnyx ou Plivo, avec prise en charge facultative de la voix en temps réel et de la transcription en streaming
|
||||
title: Plugin d’appel vocal
|
||||
summary: Passez des appels vocaux sortants et acceptez des appels vocaux entrants via Twilio, Telnyx ou Plivo, avec voix en temps réel et transcription en streaming facultatives
|
||||
title: Plugin d'appel vocal
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:21:43Z"
|
||||
generated_at: "2026-05-04T07:05:38Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 18a9a0d7095ec92036b516cc26c69219a0a2fd9bb8e0cb2e7509123bb4f3f65a
|
||||
source_hash: 8ec2c22dcc9073572963744685a432328787bcedb14025e0326c20d9d842f857
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Appels vocaux pour OpenClaw via un Plugin. Prend en charge les notifications sortantes,
|
||||
les conversations à plusieurs tours, la voix temps réel en duplex intégral, la transcription
|
||||
en streaming et les appels entrants avec des politiques de liste d’autorisation.
|
||||
Appels vocaux pour OpenClaw via un plugin. Prend en charge les notifications sortantes,
|
||||
les conversations multi-tours, la voix en temps réel full-duplex, la
|
||||
transcription en streaming et les appels entrants avec des politiques de liste d'autorisation.
|
||||
|
||||
**Fournisseurs actuels :** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
speech), `mock` (développement/sans réseau).
|
||||
|
||||
<Note>
|
||||
Le Plugin Voice Call s’exécute **dans le processus Gateway**. Si vous utilisez un
|
||||
Gateway distant, installez et configurez le Plugin sur la machine qui exécute
|
||||
Le plugin Voice Call s'exécute **dans le processus Gateway**. Si vous utilisez un
|
||||
Gateway distant, installez et configurez le plugin sur la machine qui exécute
|
||||
le Gateway, puis redémarrez le Gateway pour le charger.
|
||||
</Note>
|
||||
|
||||
## Démarrage rapide
|
||||
|
||||
<Steps>
|
||||
<Step title="Install the plugin">
|
||||
<Step title="Installer le plugin">
|
||||
<Tabs>
|
||||
<Tab title="From npm">
|
||||
<Tab title="Depuis npm">
|
||||
```bash
|
||||
openclaw plugins install @openclaw/voice-call
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="From a local folder (dev)">
|
||||
<Tab title="Depuis un dossier local (développement)">
|
||||
```bash
|
||||
PLUGIN_SRC=./path/to/local/voice-call-plugin
|
||||
openclaw plugins install "$PLUGIN_SRC"
|
||||
@ -48,30 +48,30 @@ le Gateway, puis redémarrez le Gateway pour le charger.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Utilisez le paquet nu pour suivre le tag de publication officiel actuel. Épinglez une
|
||||
version exacte uniquement lorsque vous avez besoin d’une installation reproductible.
|
||||
Utilisez le package nu pour suivre l'étiquette de version officielle actuelle. Épinglez une
|
||||
version exacte uniquement lorsque vous avez besoin d'une installation reproductible.
|
||||
|
||||
Redémarrez ensuite le Gateway afin que le Plugin se charge.
|
||||
Redémarrez ensuite le Gateway afin que le plugin se charge.
|
||||
|
||||
</Step>
|
||||
<Step title="Configure provider and webhook">
|
||||
<Step title="Configurer le fournisseur et le Webhook">
|
||||
Définissez la configuration sous `plugins.entries.voice-call.config` (voir
|
||||
[Configuration](#configuration) ci-dessous pour la structure complète). Au minimum :
|
||||
[Configuration](#configuration) ci-dessous pour la forme complète). Au minimum :
|
||||
`provider`, les identifiants du fournisseur, `fromNumber` et une URL de Webhook
|
||||
accessible publiquement.
|
||||
</Step>
|
||||
<Step title="Verify setup">
|
||||
<Step title="Vérifier la configuration">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
La sortie par défaut est lisible dans les journaux de chat et les terminaux. Elle vérifie
|
||||
l’activation du Plugin, les identifiants du fournisseur, l’exposition du Webhook et le fait
|
||||
qu’un seul mode audio (`streaming` ou `realtime`) est actif. Utilisez
|
||||
l'activation du plugin, les identifiants du fournisseur, l'exposition du Webhook et que
|
||||
seul un mode audio (`streaming` ou `realtime`) est actif. Utilisez
|
||||
`--json` pour les scripts.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke test">
|
||||
<Step title="Test fumigatoire">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
@ -88,21 +88,21 @@ le Gateway, puis redémarrez le Gateway pour le charger.
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Pour Twilio, Telnyx et Plivo, la configuration doit aboutir à une **URL de Webhook publique**.
|
||||
Si `publicUrl`, l’URL du tunnel, l’URL Tailscale ou le repli de service
|
||||
résout vers le loopback ou un espace réseau privé, la configuration échoue au lieu de
|
||||
démarrer un fournisseur qui ne peut pas recevoir les Webhooks de l’opérateur.
|
||||
Pour Twilio, Telnyx et Plivo, la configuration doit se résoudre en une **URL de Webhook publique**.
|
||||
Si `publicUrl`, l'URL du tunnel, l'URL Tailscale ou le repli de service
|
||||
se résout vers l'espace réseau loopback ou privé, la configuration échoue au lieu de
|
||||
démarrer un fournisseur qui ne peut pas recevoir les Webhooks des opérateurs.
|
||||
</Warning>
|
||||
|
||||
## Configuration
|
||||
|
||||
Si `enabled: true` mais que les identifiants du fournisseur sélectionné manquent,
|
||||
Si `enabled: true` mais que les identifiants du fournisseur sélectionné sont manquants,
|
||||
le démarrage du Gateway consigne un avertissement de configuration incomplète avec les clés manquantes et
|
||||
ignore le démarrage du runtime. Les commandes, les appels RPC et les outils d’agent renvoient tout de même
|
||||
la configuration exacte du fournisseur manquante lorsqu’ils sont utilisés.
|
||||
ignore le démarrage de l'exécution. Les commandes, les appels RPC et les outils d'agent renvoient toujours
|
||||
la configuration exacte du fournisseur manquante lorsqu'ils sont utilisés.
|
||||
|
||||
<Note>
|
||||
Les identifiants Voice Call acceptent les SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` et `plugins.entries.voice-call.config.tts.providers.*.apiKey` sont résolus via la surface SecretRef standard ; consultez [Surface des identifiants SecretRef](/fr/reference/secretref-credential-surface).
|
||||
Les identifiants voice-call acceptent les SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` et `plugins.entries.voice-call.config.tts.providers.*.apiKey` sont résolus via la surface SecretRef standard ; voir [surface d'identifiants SecretRef](/fr/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -175,28 +175,28 @@ Les identifiants Voice Call acceptent les SecretRefs. `plugins.entries.voice-cal
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- Twilio, Telnyx et Plivo nécessitent tous une URL de Webhook **accessible publiquement**.
|
||||
<Accordion title="Notes sur l'exposition et la sécurité des fournisseurs">
|
||||
- Twilio, Telnyx et Plivo exigent tous une URL de Webhook **accessible publiquement**.
|
||||
- `mock` est un fournisseur de développement local (aucun appel réseau).
|
||||
- Telnyx nécessite `telnyx.publicKey` (ou `TELNYX_PUBLIC_KEY`), sauf si `skipSignatureVerification` vaut true.
|
||||
- Telnyx nécessite `telnyx.publicKey` (ou `TELNYX_PUBLIC_KEY`) sauf si `skipSignatureVerification` vaut true.
|
||||
- `skipSignatureVerification` est réservé aux tests locaux.
|
||||
- Sur l’offre gratuite de ngrok, définissez `publicUrl` sur l’URL ngrok exacte ; la vérification de signature est toujours appliquée.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` autorise les Webhooks Twilio avec des signatures non valides **uniquement** lorsque `tunnel.provider="ngrok"` et que `serve.bind` est le loopback (agent local ngrok). Développement local uniquement.
|
||||
- Les URL de l’offre gratuite ngrok peuvent changer ou ajouter un comportement interstitiel ; si `publicUrl` dérive, les signatures Twilio échouent. Production : privilégiez un domaine stable ou un funnel Tailscale.
|
||||
- Sur l'offre gratuite de ngrok, définissez `publicUrl` sur l'URL ngrok exacte ; la vérification de signature est toujours appliquée.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` autorise les Webhooks Twilio avec des signatures invalides **uniquement** lorsque `tunnel.provider="ngrok"` et que `serve.bind` est loopback (agent local ngrok). Développement local uniquement.
|
||||
- Les URL de l'offre gratuite de Ngrok peuvent changer ou ajouter un comportement interstitiel ; si `publicUrl` dérive, les signatures Twilio échouent. Production : privilégiez un domaine stable ou un funnel Tailscale.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Streaming connection caps">
|
||||
- `streaming.preStartTimeoutMs` ferme les sockets qui n’envoient jamais de trame `start` valide.
|
||||
- `streaming.maxPendingConnections` limite le nombre total de sockets pré-démarrage non authentifiées.
|
||||
- `streaming.maxPendingConnectionsPerIp` limite les sockets pré-démarrage non authentifiées par adresse IP source.
|
||||
- `streaming.maxConnections` limite le nombre total de sockets de flux multimédia ouvertes (en attente + actives).
|
||||
<Accordion title="Limites de connexions en streaming">
|
||||
- `streaming.preStartTimeoutMs` ferme les sockets qui n'envoient jamais de trame `start` valide.
|
||||
- `streaming.maxPendingConnections` limite le nombre total de sockets pré-démarrage non authentifiés.
|
||||
- `streaming.maxPendingConnectionsPerIp` limite les sockets pré-démarrage non authentifiés par IP source.
|
||||
- `streaming.maxConnections` limite le nombre total de sockets de flux multimédia ouverts (en attente + actifs).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Legacy config migrations">
|
||||
Les anciennes configurations utilisant `provider: "log"`, `twilio.from` ou les anciennes clés OpenAI
|
||||
`streaming.*` sont réécrites par `openclaw doctor --fix`.
|
||||
Le repli runtime accepte encore les anciennes clés voice-call pour le moment, mais
|
||||
le chemin de réécriture est `openclaw doctor --fix` et le shim de compatibilité est
|
||||
<Accordion title="Migrations de configuration héritée">
|
||||
Les anciennes configurations utilisant `provider: "log"`, `twilio.from` ou les clés OpenAI
|
||||
`streaming.*` héritées sont réécrites par `openclaw doctor --fix`.
|
||||
Le repli d'exécution accepte encore les anciennes clés voice-call pour le moment, mais
|
||||
le chemin de réécriture est `openclaw doctor --fix` et la couche de compatibilité est
|
||||
temporaire.
|
||||
|
||||
Clés de streaming migrées automatiquement :
|
||||
@ -214,49 +214,52 @@ Les identifiants Voice Call acceptent les SecretRefs. `plugins.entries.voice-cal
|
||||
|
||||
Par défaut, Voice Call utilise `sessionScope: "per-phone"` afin que les appels répétés du
|
||||
même appelant conservent la mémoire de conversation. Définissez `sessionScope: "per-call"` lorsque
|
||||
chaque appel opérateur doit démarrer avec un contexte vierge, par exemple pour les flux de réception,
|
||||
de réservation, d’IVR ou de pont Google Meet où le même numéro de téléphone peut
|
||||
chaque appel opérateur doit commencer avec un contexte neuf, par exemple pour les flux de réception,
|
||||
de réservation, IVR ou de passerelle Google Meet où le même numéro de téléphone peut
|
||||
représenter différentes réunions.
|
||||
|
||||
## Conversations vocales temps réel
|
||||
## Conversations vocales en temps réel
|
||||
|
||||
`realtime` sélectionne un fournisseur vocal temps réel en duplex intégral pour l’audio
|
||||
d’appel en direct. Il est distinct de `streaming`, qui transmet uniquement l’audio aux
|
||||
fournisseurs de transcription temps réel.
|
||||
`realtime` sélectionne un fournisseur de voix en temps réel full-duplex pour l'audio
|
||||
d'appel en direct. Il est distinct de `streaming`, qui transmet uniquement l'audio aux
|
||||
fournisseurs de transcription en temps réel.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` ne peut pas être combiné avec `streaming.enabled`. Choisissez un seul
|
||||
`realtime.enabled` ne peut pas être combiné avec `streaming.enabled`. Choisissez un
|
||||
mode audio par appel.
|
||||
</Warning>
|
||||
|
||||
Comportement runtime actuel :
|
||||
Comportement d'exécution actuel :
|
||||
|
||||
- `realtime.enabled` est pris en charge pour Twilio Media Streams.
|
||||
- `realtime.provider` est facultatif. S’il n’est pas défini, Voice Call utilise le premier fournisseur vocal temps réel enregistré.
|
||||
- Fournisseurs vocaux temps réel inclus : Google Gemini Live (`google`) et OpenAI (`openai`), enregistrés par leurs Plugins de fournisseur.
|
||||
- La configuration brute appartenant au fournisseur se trouve sous `realtime.providers.<providerId>`.
|
||||
- Voice Call expose par défaut l’outil temps réel partagé `openclaw_agent_consult`. Le modèle temps réel peut l’appeler lorsque l’appelant demande un raisonnement plus approfondi, des informations actuelles ou des outils OpenClaw normaux.
|
||||
- `realtime.fastContext.enabled` est désactivé par défaut. Lorsqu’il est activé, Voice Call recherche d’abord dans la mémoire indexée/le contexte de session pour la question de consultation et renvoie ces extraits au modèle temps réel dans le délai `realtime.fastContext.timeoutMs`, avant de revenir à l’agent de consultation complet uniquement si `realtime.fastContext.fallbackToConsult` vaut true.
|
||||
- Si `realtime.provider` pointe vers un fournisseur non enregistré, ou si aucun fournisseur vocal temps réel n’est enregistré, Voice Call consigne un avertissement et ignore le média temps réel au lieu de faire échouer tout le Plugin.
|
||||
- Les clés de session de consultation réutilisent la session d’appel stockée lorsqu’elle est disponible, puis reviennent à la configuration `sessionScope` (`per-phone` par défaut, ou `per-call` pour les appels isolés).
|
||||
- `realtime.provider` est facultatif. S'il n'est pas défini, Voice Call utilise le premier fournisseur de voix en temps réel enregistré.
|
||||
- Fournisseurs de voix en temps réel groupés : Google Gemini Live (`google`) et OpenAI (`openai`), enregistrés par leurs plugins fournisseurs.
|
||||
- La configuration brute détenue par le fournisseur se trouve sous `realtime.providers.<providerId>`.
|
||||
- Voice Call expose par défaut l'outil temps réel partagé `openclaw_agent_consult`. Le modèle temps réel peut l'appeler lorsque l'appelant demande un raisonnement plus approfondi, des informations actuelles ou des outils OpenClaw normaux.
|
||||
- `realtime.fastContext.enabled` est désactivé par défaut. Lorsqu'il est activé, Voice Call recherche d'abord dans le contexte mémoire/session indexé pour la question de consultation et renvoie ces extraits au modèle temps réel dans `realtime.fastContext.timeoutMs` avant de revenir à l'agent de consultation complet uniquement si `realtime.fastContext.fallbackToConsult` vaut true.
|
||||
- Si `realtime.provider` pointe vers un fournisseur non enregistré, ou si aucun fournisseur de voix en temps réel n'est enregistré, Voice Call consigne un avertissement et ignore le média temps réel au lieu de faire échouer tout le plugin.
|
||||
- Les clés de session de consultation réutilisent la session d'appel stockée lorsqu'elle est disponible, puis reviennent à la `sessionScope` configurée (`per-phone` par défaut, ou `per-call` pour les appels isolés).
|
||||
|
||||
### Politique d’outils
|
||||
### Politique d'outils
|
||||
|
||||
`realtime.toolPolicy` contrôle l’exécution de la consultation :
|
||||
`realtime.toolPolicy` contrôle l'exécution de consultation :
|
||||
|
||||
| Politique | Comportement |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Expose l’outil de consultation et limite l’agent standard à `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` et `memory_get`. |
|
||||
| `owner` | Expose l’outil de consultation et laisse l’agent standard utiliser la politique d’outils normale de l’agent. |
|
||||
| `none` | N’expose pas l’outil de consultation. Les `realtime.tools` personnalisés sont tout de même transmis au fournisseur temps réel. |
|
||||
| `safe-read-only` | Expose l'outil de consultation et limite l'agent standard à `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` et `memory_get`. |
|
||||
| `owner` | Expose l'outil de consultation et laisse l'agent standard utiliser la politique normale d'outils d'agent. |
|
||||
| `none` | N'expose pas l'outil de consultation. Les `realtime.tools` personnalisés sont toujours transmis au fournisseur temps réel. |
|
||||
|
||||
### Exemples de fournisseurs temps réel
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
Valeurs par défaut : clé API depuis `realtime.providers.google.apiKey`,
|
||||
Valeurs par défaut : clé d'API depuis `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY` ou `GOOGLE_GENERATIVE_AI_API_KEY` ; modèle
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025` ; voix `Kore`.
|
||||
`sessionResumption` et `contextWindowCompression` sont activés par défaut pour les appels plus longs,
|
||||
reconnectables. Utilisez `silenceDurationMs`, `startSensitivity` et
|
||||
`endSensitivity` pour ajuster une alternance de parole plus rapide sur l'audio téléphonique.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -277,6 +280,8 @@ Comportement runtime actuel :
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
model: "gemini-2.5-flash-native-audio-preview-12-2025",
|
||||
voice: "Kore",
|
||||
silenceDurationMs: 500,
|
||||
startSensitivity: "high",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -311,27 +316,27 @@ Comportement runtime actuel :
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Consultez [Fournisseur Google](/fr/providers/google) et
|
||||
[Fournisseur OpenAI](/fr/providers/openai) pour les options vocales temps réel
|
||||
propres à chaque fournisseur.
|
||||
Voir [fournisseur Google](/fr/providers/google) et
|
||||
[fournisseur OpenAI](/fr/providers/openai) pour les options de voix en temps réel
|
||||
propres au fournisseur.
|
||||
|
||||
## Transcription en streaming
|
||||
|
||||
`streaming` sélectionne un fournisseur de transcription temps réel pour l’audio d’appel en direct.
|
||||
`streaming` sélectionne un fournisseur de transcription en temps réel pour l’audio des appels en direct.
|
||||
|
||||
Comportement runtime actuel :
|
||||
Comportement actuel à l’exécution :
|
||||
|
||||
- `streaming.provider` est facultatif. S’il n’est pas défini, Appels vocaux utilise le premier fournisseur de transcription en temps réel enregistré.
|
||||
- Fournisseurs de transcription en temps réel groupés : Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) et xAI (`xai`), enregistrés par leurs plugins fournisseurs.
|
||||
- La configuration brute détenue par le fournisseur se trouve sous `streaming.providers.<providerId>`.
|
||||
- Après que Twilio a envoyé un message `start` de flux accepté, Appels vocaux enregistre immédiatement le flux, met en file d’attente les médias entrants via le fournisseur de transcription pendant que celui-ci se connecte, et lance le message d’accueil initial seulement lorsque la transcription en temps réel est prête.
|
||||
- Si `streaming.provider` pointe vers un fournisseur non enregistré, ou si aucun fournisseur n’est enregistré, Appels vocaux journalise un avertissement et ignore le streaming média au lieu de faire échouer tout le plugin.
|
||||
- `streaming.provider` est facultatif. S’il n’est pas défini, Voice Call utilise le premier fournisseur de transcription en temps réel enregistré.
|
||||
- Fournisseurs de transcription en temps réel intégrés : Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) et xAI (`xai`), enregistrés par leurs plugins fournisseurs.
|
||||
- La configuration brute propre au fournisseur se trouve sous `streaming.providers.<providerId>`.
|
||||
- Après que Twilio a envoyé un message `start` de flux accepté, Voice Call enregistre immédiatement le flux, met en file d’attente les médias entrants via le fournisseur de transcription pendant que celui-ci se connecte, et ne lance le message d’accueil initial qu’une fois la transcription en temps réel prête.
|
||||
- Si `streaming.provider` pointe vers un fournisseur non enregistré, ou si aucun fournisseur n’est enregistré, Voice Call consigne un avertissement et ignore le streaming multimédia au lieu de faire échouer tout le plugin.
|
||||
|
||||
### Exemples de fournisseurs de streaming
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenAI">
|
||||
Valeurs par défaut : clé d’API `streaming.providers.openai.apiKey` ou
|
||||
Valeurs par défaut : clé API `streaming.providers.openai.apiKey` ou
|
||||
`OPENAI_API_KEY` ; modèle `gpt-4o-transcribe` ; `silenceDurationMs: 800` ;
|
||||
`vadThreshold: 0.5`.
|
||||
|
||||
@ -363,8 +368,8 @@ Comportement runtime actuel :
|
||||
|
||||
</Tab>
|
||||
<Tab title="xAI">
|
||||
Valeurs par défaut : clé d’API `streaming.providers.xai.apiKey` ou `XAI_API_KEY` ;
|
||||
endpoint `wss://api.x.ai/v1/stt` ; encodage `mulaw` ; fréquence d’échantillonnage `8000` ;
|
||||
Valeurs par défaut : clé API `streaming.providers.xai.apiKey` ou `XAI_API_KEY` ;
|
||||
point de terminaison `wss://api.x.ai/v1/stt` ; encodage `mulaw` ; fréquence d’échantillonnage `8000` ;
|
||||
`endpointingMs: 800` ; `interimResults: true`.
|
||||
|
||||
```json5
|
||||
@ -397,8 +402,8 @@ Comportement runtime actuel :
|
||||
|
||||
## TTS pour les appels
|
||||
|
||||
Appels vocaux utilise la configuration principale `messages.tts` pour le streaming
|
||||
vocal sur les appels. Vous pouvez la remplacer dans la configuration du plugin avec la
|
||||
Voice Call utilise la configuration principale `messages.tts` pour la parole en streaming
|
||||
lors des appels. Vous pouvez la remplacer dans la configuration du plugin avec la
|
||||
**même forme** — elle est fusionnée en profondeur avec `messages.tts`.
|
||||
|
||||
```json5
|
||||
@ -416,22 +421,22 @@ vocal sur les appels. Vous pouvez la remplacer dans la configuration du plugin a
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech est ignoré pour les appels vocaux.** L’audio de téléphonie nécessite du PCM ;
|
||||
le transport Microsoft actuel n’expose pas de sortie PCM de téléphonie.
|
||||
**Microsoft speech est ignoré pour les appels vocaux.** L’audio téléphonique nécessite du PCM ;
|
||||
le transport Microsoft actuel n’expose pas de sortie PCM téléphonique.
|
||||
</Warning>
|
||||
|
||||
Notes de comportement :
|
||||
|
||||
- Les anciennes clés `tts.<provider>` dans la configuration du plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) sont réparées par `openclaw doctor --fix` ; la configuration validée doit utiliser `tts.providers.<provider>`.
|
||||
- Le TTS principal est utilisé lorsque le streaming média Twilio est activé ; sinon, les appels reviennent aux voix natives du fournisseur.
|
||||
- Si un flux média Twilio est déjà actif, Appels vocaux ne revient pas à TwiML `<Say>`. Si le TTS de téléphonie n’est pas disponible dans cet état, la demande de lecture échoue au lieu de mélanger deux chemins de lecture.
|
||||
- Lorsque le TTS de téléphonie bascule vers un fournisseur secondaire, Appels vocaux journalise un avertissement avec la chaîne de fournisseurs (`from`, `to`, `attempts`) pour le débogage.
|
||||
- Lorsque l’interruption vocale Twilio ou le démontage du flux vide la file TTS en attente, les demandes de lecture mises en file se résolvent au lieu de laisser les appelants attendre indéfiniment la fin de la lecture.
|
||||
- Les anciennes clés `tts.<provider>` dans la configuration du plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) sont réparées par `openclaw doctor --fix` ; la configuration validée devrait utiliser `tts.providers.<provider>`.
|
||||
- Le TTS principal est utilisé lorsque le streaming multimédia Twilio est activé ; sinon les appels reviennent aux voix natives du fournisseur.
|
||||
- Si un flux multimédia Twilio est déjà actif, Voice Call ne revient pas à TwiML `<Say>`. Si le TTS téléphonique n’est pas disponible dans cet état, la requête de lecture échoue au lieu de mélanger deux chemins de lecture.
|
||||
- Lorsque le TTS téléphonique revient à un fournisseur secondaire, Voice Call consigne un avertissement avec la chaîne de fournisseurs (`from`, `to`, `attempts`) pour le débogage.
|
||||
- Lorsque l’interruption Twilio ou le démontage du flux vide la file TTS en attente, les requêtes de lecture en file se règlent au lieu de laisser les appelants attendre indéfiniment la fin de la lecture.
|
||||
|
||||
### Exemples de TTS
|
||||
### Exemples TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="TTS principal uniquement">
|
||||
<Tab title="Core TTS only">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -445,7 +450,7 @@ Notes de comportement :
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Remplacer par ElevenLabs (appels uniquement)">
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -469,7 +474,7 @@ Notes de comportement :
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Remplacement du modèle OpenAI (fusion en profondeur)">
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -495,7 +500,7 @@ Notes de comportement :
|
||||
|
||||
## Appels entrants
|
||||
|
||||
La stratégie entrante vaut `disabled` par défaut. Pour activer les appels entrants, définissez :
|
||||
La politique d’entrée est définie par défaut sur `disabled`. Pour activer les appels entrants, définissez :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -506,31 +511,31 @@ La stratégie entrante vaut `disabled` par défaut. Pour activer les appels entr
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` est un filtrage de l’identification de l’appelant à faible assurance. Le
|
||||
`inboundPolicy: "allowlist"` est un filtrage de l’identifiant d’appelant à faible assurance. Le
|
||||
plugin normalise la valeur `From` fournie par le fournisseur et la compare à
|
||||
`allowFrom`. La vérification du Webhook authentifie la livraison par le fournisseur et
|
||||
`allowFrom`. La vérification Webhook authentifie la livraison par le fournisseur et
|
||||
l’intégrité de la charge utile, mais elle ne prouve **pas** la propriété du numéro
|
||||
d’appelant PSTN/VoIP. Traitez `allowFrom` comme un filtrage d’identification de l’appelant, et non comme une identité
|
||||
forte de l’appelant.
|
||||
d’appelant PSTN/VoIP. Traitez `allowFrom` comme un filtrage de l’identifiant d’appelant, et non comme une identité
|
||||
d’appelant forte.
|
||||
</Warning>
|
||||
|
||||
Les réponses automatiques utilisent le système d’agents. Ajustez avec `responseModel`,
|
||||
Les réponses automatiques utilisent le système d’agents. Ajustez-les avec `responseModel`,
|
||||
`responseSystemPrompt` et `responseTimeoutMs`.
|
||||
|
||||
### Routage par numéro
|
||||
|
||||
Utilisez `numbers` lorsqu’un plugin Appels vocaux reçoit des appels pour plusieurs numéros de téléphone
|
||||
Utilisez `numbers` lorsqu’un même plugin Voice Call reçoit des appels pour plusieurs numéros de téléphone
|
||||
et que chaque numéro doit se comporter comme une ligne différente. Par exemple, un
|
||||
numéro peut utiliser un assistant personnel décontracté tandis qu’un autre utilise une persona
|
||||
professionnelle, un agent de réponse différent et une voix TTS différente.
|
||||
numéro peut utiliser un assistant personnel décontracté tandis qu’un autre utilise une personnalité professionnelle,
|
||||
un agent de réponse différent et une voix TTS différente.
|
||||
|
||||
Les routes sont sélectionnées à partir du numéro `To` composé fourni par le fournisseur. Les clés doivent être des
|
||||
numéros E.164. Lorsqu’un appel arrive, Appels vocaux résout une seule fois la route correspondante,
|
||||
stocke la route correspondante sur l’enregistrement d’appel et réutilise cette configuration effective
|
||||
pour le message d’accueil, le chemin de réponse automatique classique, le chemin de consultation en temps réel et la lecture
|
||||
TTS. Si aucune route ne correspond, la configuration globale d’Appels vocaux est utilisée.
|
||||
Les appels sortants n’utilisent pas `numbers` ; transmettez explicitement la cible sortante, le message et
|
||||
la session lors du lancement de l’appel.
|
||||
Les routes sont sélectionnées à partir du numéro composé `To` fourni par le fournisseur. Les clés doivent être
|
||||
des numéros E.164. Lorsqu’un appel arrive, Voice Call résout une fois la route correspondante,
|
||||
stocke la route correspondante dans l’enregistrement d’appel et réutilise cette configuration effective
|
||||
pour le message d’accueil, le chemin classique de réponse automatique, le chemin de consultation en temps réel et la lecture
|
||||
TTS. Si aucune route ne correspond, la configuration globale de Voice Call est utilisée.
|
||||
Les appels sortants n’utilisent pas `numbers` ; transmettez explicitement la cible sortante, le message et la
|
||||
session lors de l’initiation de l’appel.
|
||||
|
||||
Les remplacements de route prennent actuellement en charge :
|
||||
|
||||
@ -541,8 +546,7 @@ Les remplacements de route prennent actuellement en charge :
|
||||
- `responseSystemPrompt`
|
||||
- `responseTimeoutMs`
|
||||
|
||||
La valeur de route `tts` est fusionnée en profondeur par-dessus la configuration `tts` globale d’Appels vocaux, vous pouvez donc
|
||||
généralement remplacer uniquement la voix du fournisseur :
|
||||
La valeur de route `tts` est fusionnée en profondeur avec la configuration `tts` globale de Voice Call, ce qui vous permet généralement de remplacer uniquement la voix du fournisseur :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -570,51 +574,45 @@ généralement remplacer uniquement la voix du fournisseur :
|
||||
|
||||
### Contrat de sortie vocale
|
||||
|
||||
Pour les réponses automatiques, Appels vocaux ajoute un contrat strict de sortie vocale à
|
||||
l’invite système :
|
||||
Pour les réponses automatiques, Voice Call ajoute un contrat strict de sortie vocale à l’invite système :
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
```
|
||||
|
||||
Appels vocaux extrait le texte à prononcer de manière défensive :
|
||||
Voice Call extrait le texte à prononcer de manière défensive :
|
||||
|
||||
- Ignore les charges utiles marquées comme contenu de raisonnement/erreur.
|
||||
- Analyse le JSON direct, le JSON clôturé ou les clés `"spoken"` en ligne.
|
||||
- Revient au texte brut et supprime les paragraphes d’introduction probablement liés à la planification ou aux métadonnées.
|
||||
- Ignore les charges utiles marquées comme contenu de raisonnement ou d’erreur.
|
||||
- Analyse le JSON direct, le JSON balisé ou les clés `"spoken"` en ligne.
|
||||
- Se rabat sur du texte brut et supprime les paragraphes d’introduction qui ressemblent à de la planification ou à des métadonnées.
|
||||
|
||||
Cela maintient la lecture vocale centrée sur le texte destiné à l’appelant et évite
|
||||
la fuite de texte de planification dans l’audio.
|
||||
Cela maintient la lecture vocale centrée sur le texte destiné à l’appelant et évite de divulguer du texte de planification dans l’audio.
|
||||
|
||||
### Comportement au démarrage de la conversation
|
||||
|
||||
Pour les appels `conversation` sortants, la gestion du premier message est liée à l’état de lecture
|
||||
en direct :
|
||||
Pour les appels `conversation` sortants, la gestion du premier message est liée à l’état de lecture en direct :
|
||||
|
||||
- Le vidage de la file d’interruption vocale et la réponse automatique ne sont supprimés que pendant que le message d’accueil initial est activement prononcé.
|
||||
- Si la lecture initiale échoue, l’appel repasse à `listening` et le message initial reste en file d’attente pour une nouvelle tentative.
|
||||
- L’effacement de la file d’attente lors d’une interruption et la réponse automatique ne sont supprimés que pendant que le message d’accueil initial est en cours de lecture.
|
||||
- Si la lecture initiale échoue, l’appel revient à l’état `listening` et le message initial reste en file d’attente pour une nouvelle tentative.
|
||||
- La lecture initiale pour le streaming Twilio démarre à la connexion du flux, sans délai supplémentaire.
|
||||
- L’interruption vocale abandonne la lecture active et vide les entrées TTS Twilio mises en file mais pas encore en lecture. Les entrées vidées sont résolues comme ignorées, afin que la logique de réponse de suivi puisse continuer sans attendre un audio qui ne sera jamais lu.
|
||||
- Les conversations vocales en temps réel utilisent le premier tour propre au flux en temps réel. Appels vocaux ne publie **pas** de mise à jour TwiML `<Say>` héritée pour ce message initial, afin que les sessions `<Connect><Stream>` sortantes restent attachées.
|
||||
- L’interruption annule la lecture active et efface les entrées TTS Twilio en file d’attente mais pas encore en cours de lecture. Les entrées effacées sont résolues comme ignorées, afin que la logique de réponse de suivi puisse continuer sans attendre un audio qui ne sera jamais lu.
|
||||
- Les conversations vocales en temps réel utilisent le premier tour propre au flux temps réel. Voice Call ne publie **pas** de mise à jour TwiML `<Say>` héritée pour ce message initial, de sorte que les sessions `<Connect><Stream>` sortantes restent attachées.
|
||||
|
||||
### Délai de grâce de déconnexion du flux Twilio
|
||||
### Délai de grâce lors de la déconnexion d’un flux Twilio
|
||||
|
||||
Lorsqu’un flux média Twilio se déconnecte, Appels vocaux attend **2000 ms** avant
|
||||
de terminer automatiquement l’appel :
|
||||
Lorsqu’un flux média Twilio se déconnecte, Voice Call attend **2000 ms** avant de mettre automatiquement fin à l’appel :
|
||||
|
||||
- Si le flux se reconnecte pendant cette fenêtre, la fin automatique est annulée.
|
||||
- Si aucun flux ne se réenregistre après la période de grâce, l’appel est terminé pour éviter les appels actifs bloqués.
|
||||
- Si aucun flux ne se réenregistre après le délai de grâce, l’appel est terminé afin d’éviter les appels actifs bloqués.
|
||||
|
||||
## Nettoyeur d’appels obsolètes
|
||||
|
||||
Utilisez `staleCallReaperSeconds` pour terminer les appels qui ne reçoivent jamais de Webhook
|
||||
terminal (par exemple, les appels en mode notification qui ne se terminent jamais). La valeur par défaut
|
||||
est `0` (désactivé).
|
||||
Utilisez `staleCallReaperSeconds` pour terminer les appels qui ne reçoivent jamais de Webhook terminal (par exemple, les appels en mode notification qui ne se terminent jamais). La valeur par défaut est `0` (désactivé).
|
||||
|
||||
Plages recommandées :
|
||||
|
||||
- **Production :** `120` à `300` secondes pour les flux de type notification.
|
||||
- Gardez cette valeur **supérieure à `maxDurationSeconds`** afin que les appels normaux puissent se terminer. Un bon point de départ est `maxDurationSeconds + 30–60` secondes.
|
||||
- Conservez cette valeur **supérieure à `maxDurationSeconds`** afin que les appels normaux puissent se terminer. Un bon point de départ est `maxDurationSeconds + 30–60` secondes.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -633,26 +631,24 @@ Plages recommandées :
|
||||
|
||||
## Sécurité des Webhooks
|
||||
|
||||
Lorsqu’un proxy ou un tunnel se trouve devant le Gateway, le plugin
|
||||
reconstruit l’URL publique pour la vérification de signature. Ces options
|
||||
contrôlent quels en-têtes transférés sont approuvés :
|
||||
Lorsqu’un proxy ou un tunnel se trouve devant le Gateway, le plugin reconstruit l’URL publique pour la vérification de signature. Ces options contrôlent les en-têtes transférés qui sont approuvés :
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Liste d’autorisation des hôtes provenant des en-têtes de transfert.
|
||||
Autorisez les hôtes issus des en-têtes de transfert.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Approuver les en-têtes transférés sans liste d’autorisation.
|
||||
Approuvez les en-têtes transférés sans liste d’autorisation.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
N’approuver les en-têtes transférés que lorsque l’IP distante de la requête correspond à la liste.
|
||||
N’approuvez les en-têtes transférés que lorsque l’IP distante de la requête correspond à la liste.
|
||||
</ParamField>
|
||||
|
||||
Protections supplémentaires :
|
||||
|
||||
- La **protection contre la relecture** des Webhooks est activée pour Twilio et Plivo. Les requêtes Webhook valides rejouées sont accusées réception, mais ignorées pour les effets de bord.
|
||||
- Les tours de conversation Twilio incluent un jeton par tour dans les rappels `<Gather>`, afin que les rappels vocaux obsolètes/rejoués ne puissent pas satisfaire un tour de transcription en attente plus récent.
|
||||
- Les requêtes Webhook non authentifiées sont rejetées avant la lecture du corps lorsque les en-têtes de signature requis par le fournisseur sont absents.
|
||||
- Le Webhook voice-call utilise le profil de corps partagé avant authentification (64 Ko / 5 secondes) plus une limite par IP des requêtes en cours avant la vérification de signature.
|
||||
- La **protection contre la relecture** des Webhooks est activée pour Twilio et Plivo. Les requêtes Webhook valides rejouées sont acquittées mais ignorées pour les effets de bord.
|
||||
- Les tours de conversation Twilio incluent un jeton par tour dans les callbacks `<Gather>`, afin que les callbacks vocaux obsolètes ou rejoués ne puissent pas satisfaire un tour de transcription en attente plus récent.
|
||||
- Les requêtes Webhook non authentifiées sont rejetées avant la lecture du corps lorsque les en-têtes de signature requis du fournisseur sont absents.
|
||||
- Le Webhook voice-call utilise le profil de corps pré-authentification partagé (64 Ko / 5 secondes) ainsi qu’un plafond par IP sur les requêtes en cours avant la vérification de signature.
|
||||
|
||||
Exemple avec un hôte public stable :
|
||||
|
||||
@ -689,14 +685,14 @@ openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Lorsque le Gateway est déjà en cours d’exécution, les commandes opérationnelles `voicecall` délèguent
|
||||
au runtime voice-call détenu par le Gateway afin que la CLI ne lie pas un second
|
||||
serveur Webhook. Si aucun Gateway n’est joignable, les commandes reviennent à un
|
||||
au runtime d’appels vocaux détenu par le Gateway afin que la CLI ne lie pas un second
|
||||
serveur Webhook. Si aucun Gateway n’est joignable, les commandes se rabattent sur un
|
||||
runtime CLI autonome.
|
||||
|
||||
`latency` lit `calls.jsonl` depuis le chemin de stockage par défaut des appels vocaux.
|
||||
Utilisez `--file <path>` pour pointer vers un journal différent et `--last <n>` pour limiter
|
||||
`latency` lit `calls.jsonl` depuis le chemin de stockage d’appels vocaux par défaut.
|
||||
Utilisez `--file <path>` pour pointer vers un autre journal et `--last <n>` pour limiter
|
||||
l’analyse aux N derniers enregistrements (200 par défaut). La sortie inclut p50/p90/p99
|
||||
pour la latence des tours et les temps d’attente d’écoute.
|
||||
pour la latence de tour et les temps d’attente d’écoute.
|
||||
|
||||
## Outil d’agent
|
||||
|
||||
@ -711,7 +707,7 @@ Nom de l’outil : `voice_call`.
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
Ce dépôt inclut une documentation Skill correspondante à `skills/voice-call/SKILL.md`.
|
||||
Ce dépôt fournit une documentation de skill correspondante dans `skills/voice-call/SKILL.md`.
|
||||
|
||||
## RPC Gateway
|
||||
|
||||
@ -725,12 +721,12 @@ Ce dépôt inclut une documentation Skill correspondante à `skills/voice-call/S
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` n’est valide qu’avec `mode: "conversation"`. Les appels en mode notification
|
||||
doivent utiliser `voicecall.dtmf` après l’existence de l’appel s’ils ont besoin de chiffres
|
||||
après la connexion.
|
||||
doivent utiliser `voicecall.dtmf` après la création de l’appel s’ils ont besoin de chiffres
|
||||
après connexion.
|
||||
|
||||
## Dépannage
|
||||
|
||||
### La configuration échoue lors de l’exposition du webhook
|
||||
### L’exposition du Webhook échoue pendant la configuration
|
||||
|
||||
Exécutez la configuration depuis le même environnement que celui qui exécute le Gateway :
|
||||
|
||||
@ -739,19 +735,19 @@ openclaw voicecall setup
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Pour `twilio`, `telnyx` et `plivo`, `webhook-exposure` doit être au vert. Une
|
||||
configuration de `publicUrl` échoue toujours lorsqu’elle pointe vers un espace réseau local
|
||||
ou privé, car l’opérateur ne peut pas rappeler ces adresses. N’utilisez pas
|
||||
Pour `twilio`, `telnyx` et `plivo`, `webhook-exposure` doit être au vert. Un
|
||||
`publicUrl` configuré échoue quand même s’il pointe vers un espace réseau local ou privé,
|
||||
car l’opérateur ne peut pas rappeler ces adresses. N’utilisez pas
|
||||
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
|
||||
`192.168.x`, `169.254.x`, `fc00::/7` ou `fd00::/8` comme `publicUrl`.
|
||||
|
||||
Les appels sortants Twilio en mode notification envoient leur TwiML `<Say>` initial directement dans
|
||||
la requête de création d’appel ; le premier message prononcé ne dépend donc pas de Twilio
|
||||
récupérant le TwiML du webhook. Un webhook public reste requis pour les rappels d’état,
|
||||
les appels conversationnels, le DTMF avant connexion, les flux en temps réel et le contrôle d’appel
|
||||
après connexion.
|
||||
la requête de création d’appel ; le premier message parlé ne dépend donc pas de la récupération
|
||||
du TwiML de Webhook par Twilio. Un Webhook public reste requis pour les rappels de statut,
|
||||
les appels conversationnels, le DTMF avant connexion, les flux temps réel et le contrôle
|
||||
d’appel après connexion.
|
||||
|
||||
Utilisez une méthode d’exposition publique :
|
||||
Utilisez un chemin d’exposition public :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -778,7 +774,7 @@ openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` est une simulation, sauf si vous passez `--yes`.
|
||||
`voicecall smoke` est une exécution à blanc sauf si vous passez `--yes`.
|
||||
|
||||
### Les identifiants du fournisseur échouent
|
||||
|
||||
@ -791,18 +787,18 @@ Vérifiez le fournisseur sélectionné et les champs d’identifiants requis :
|
||||
- Plivo : `plivo.authId`, `plivo.authToken` et `fromNumber`.
|
||||
|
||||
Les identifiants doivent exister sur l’hôte du Gateway. Modifier un profil shell local
|
||||
n’affecte pas un Gateway déjà en cours d’exécution tant qu’il n’a pas redémarré ou rechargé son
|
||||
environnement.
|
||||
n’affecte pas un Gateway déjà en cours d’exécution tant qu’il ne redémarre pas ou ne recharge pas
|
||||
son environnement.
|
||||
|
||||
### Les appels démarrent mais les webhooks du fournisseur n’arrivent pas
|
||||
### Les appels démarrent mais les Webhooks du fournisseur n’arrivent pas
|
||||
|
||||
Confirmez que la console du fournisseur pointe vers l’URL exacte du webhook public :
|
||||
Confirmez que la console du fournisseur pointe vers l’URL exacte du Webhook public :
|
||||
|
||||
```text
|
||||
https://voice.example.com/voice/webhook
|
||||
```
|
||||
|
||||
Inspectez ensuite l’état à l’exécution :
|
||||
Puis inspectez l’état du runtime :
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
@ -815,13 +811,13 @@ Causes courantes :
|
||||
- `publicUrl` pointe vers un chemin différent de `serve.path`.
|
||||
- L’URL du tunnel a changé après le démarrage du Gateway.
|
||||
- Un proxy transfère la requête mais supprime ou réécrit les en-têtes d’hôte/protocole.
|
||||
- Le pare-feu ou le DNS achemine le nom d’hôte public ailleurs que vers le Gateway.
|
||||
- Le pare-feu ou le DNS route le nom d’hôte public ailleurs que vers le Gateway.
|
||||
- Le Gateway a été redémarré sans que le Plugin Voice Call soit activé.
|
||||
|
||||
Lorsqu’un proxy inverse ou un tunnel se trouve devant le Gateway, définissez
|
||||
`webhookSecurity.allowedHosts` sur le nom d’hôte public, ou utilisez
|
||||
`webhookSecurity.trustedProxyIPs` pour une adresse de proxy connue. Utilisez
|
||||
`webhookSecurity.trustForwardingHeaders` uniquement lorsque la limite du proxy est sous
|
||||
`webhookSecurity.trustForwardingHeaders` uniquement lorsque la frontière du proxy est sous
|
||||
votre contrôle.
|
||||
|
||||
### La vérification de signature échoue
|
||||
@ -829,14 +825,14 @@ votre contrôle.
|
||||
Les signatures du fournisseur sont vérifiées par rapport à l’URL publique qu’OpenClaw reconstruit
|
||||
à partir de la requête entrante. Si les signatures échouent :
|
||||
|
||||
- Confirmez que l’URL du webhook du fournisseur correspond exactement à `publicUrl`, y compris
|
||||
- Confirmez que l’URL du Webhook du fournisseur correspond exactement à `publicUrl`, y compris
|
||||
le schéma, l’hôte et le chemin.
|
||||
- Pour les URL ngrok de l’offre gratuite, mettez à jour `publicUrl` lorsque le nom d’hôte du tunnel change.
|
||||
- Pour les URL ngrok en offre gratuite, mettez à jour `publicUrl` lorsque le nom d’hôte du tunnel change.
|
||||
- Assurez-vous que le proxy préserve les en-têtes d’hôte et de protocole d’origine, ou configurez
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- N’activez pas `skipSignatureVerification` en dehors des tests locaux.
|
||||
|
||||
### Les connexions Google Meet Twilio échouent
|
||||
### Les connexions Google Meet via Twilio échouent
|
||||
|
||||
Google Meet utilise ce Plugin pour les connexions par appel Twilio. Vérifiez d’abord Voice Call :
|
||||
|
||||
@ -845,19 +841,19 @@ openclaw voicecall setup
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Vérifiez ensuite explicitement le transport Google Meet :
|
||||
Puis vérifiez explicitement le transport Google Meet :
|
||||
|
||||
```bash
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Si Voice Call est au vert mais que le participant Meet ne rejoint jamais la réunion, vérifiez le
|
||||
numéro d’appel Meet, le PIN et `--dtmf-sequence`. L’appel téléphonique peut être sain alors que
|
||||
la réunion rejette ou ignore une séquence DTMF incorrecte.
|
||||
Si Voice Call est au vert mais que le participant Meet ne rejoint jamais, vérifiez le numéro
|
||||
d’appel entrant Meet, le code PIN et `--dtmf-sequence`. L’appel téléphonique peut être sain tandis
|
||||
que la réunion rejette ou ignore une séquence DTMF incorrecte.
|
||||
|
||||
Google Meet transmet la séquence DTMF Meet et le texte d’introduction à `voicecall.start`.
|
||||
Pour les appels Twilio, Voice Call sert d’abord le TwiML DTMF, redirige vers le
|
||||
webhook, puis ouvre le flux multimédia en temps réel afin que l’introduction enregistrée soit générée
|
||||
Webhook, puis ouvre le flux média temps réel afin que l’introduction enregistrée soit générée
|
||||
après que le participant téléphonique a rejoint la réunion.
|
||||
|
||||
Utilisez `openclaw logs --follow` pour la trace en direct de la phase. Une connexion Twilio Meet
|
||||
@ -865,28 +861,28 @@ saine journalise cet ordre :
|
||||
|
||||
- Google Meet délègue la connexion Twilio à Voice Call.
|
||||
- Voice Call stocke le TwiML DTMF avant connexion.
|
||||
- Le TwiML initial de Twilio est consommé et servi avant le traitement en temps réel.
|
||||
- Voice Call sert le TwiML en temps réel pour l’appel Twilio.
|
||||
- Le pont en temps réel démarre avec le message d’accueil initial en file d’attente.
|
||||
- Le TwiML initial Twilio est consommé et servi avant la gestion temps réel.
|
||||
- Voice Call sert le TwiML temps réel pour l’appel Twilio.
|
||||
- Le pont temps réel démarre avec le message d’accueil initial en file d’attente.
|
||||
|
||||
`openclaw voicecall tail` affiche toujours les enregistrements d’appel persistés ; il est utile pour
|
||||
l’état des appels et les transcriptions, mais toutes les transitions webhook/en temps réel n’y
|
||||
l’état des appels et les transcriptions, mais toutes les transitions Webhook/temps réel n’y
|
||||
apparaissent pas.
|
||||
|
||||
### L’appel en temps réel n’a pas de parole
|
||||
### L’appel temps réel n’a pas de parole
|
||||
|
||||
Confirmez qu’un seul mode audio est activé. `realtime.enabled` et
|
||||
`streaming.enabled` ne peuvent pas tous deux être vrais.
|
||||
`streaming.enabled` ne peuvent pas tous les deux être `true`.
|
||||
|
||||
Pour les appels Twilio en temps réel, vérifiez également :
|
||||
Pour les appels Twilio temps réel, vérifiez aussi :
|
||||
|
||||
- Un Plugin fournisseur en temps réel est chargé et enregistré.
|
||||
- Un Plugin fournisseur temps réel est chargé et enregistré.
|
||||
- `realtime.provider` n’est pas défini ou nomme un fournisseur enregistré.
|
||||
- La clé API du fournisseur est disponible pour le processus Gateway.
|
||||
- `openclaw logs --follow` affiche le TwiML en temps réel servi, le pont en temps réel
|
||||
démarré et le message d’accueil initial mis en file d’attente.
|
||||
- `openclaw logs --follow` montre que le TwiML temps réel a été servi, que le pont temps réel
|
||||
a démarré et que le message d’accueil initial a été mis en file d’attente.
|
||||
|
||||
## Liens associés
|
||||
## Associé
|
||||
|
||||
- [Mode conversation](/fr/nodes/talk)
|
||||
- [Synthèse vocale](/fr/tools/tts)
|
||||
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez utiliser la synthèse vocale ElevenLabs dans OpenClaw
|
||||
- Vous souhaitez utiliser la reconnaissance vocale ElevenLabs Scribe pour les pièces jointes audio
|
||||
- Vous souhaitez utiliser la transcription en temps réel ElevenLabs pour les appels vocaux
|
||||
summary: Utilisez la parole ElevenLabs, Scribe STT et la transcription en temps réel avec OpenClaw
|
||||
- Vous voulez la synthèse vocale ElevenLabs dans OpenClaw
|
||||
- Vous souhaitez utiliser la transcription vocale ElevenLabs Scribe pour les pièces jointes audio
|
||||
- Vous souhaitez la transcription en temps réel d’ElevenLabs pour Appel vocal ou Google Meet
|
||||
summary: Utiliser la synthèse vocale ElevenLabs, Scribe STT et la transcription en temps réel avec OpenClaw
|
||||
title: ElevenLabs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T13:55:38Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T07:05:38Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
|
||||
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
|
||||
source_path: providers/elevenlabs.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw utilise ElevenLabs pour la synthèse vocale, la reconnaissance vocale par lot avec Scribe
|
||||
v2, et la reconnaissance vocale en streaming Voice Call avec Scribe v2 Realtime.
|
||||
OpenClaw utilise ElevenLabs pour la synthèse vocale, la transcription vocale par lots avec Scribe
|
||||
v2 et la STT en streaming avec Scribe v2 Realtime.
|
||||
|
||||
| Fonctionnalité | Surface OpenClaw | Valeur par défaut |
|
||||
| ------------------------- | ---------------------------------------------- | ------------------------- |
|
||||
| Synthèse vocale | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Reconnaissance vocale par lot | `tools.media.audio` | `scribe_v2` |
|
||||
| Reconnaissance vocale en streaming | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
|
||||
| Capacité | Surface OpenClaw | Par défaut |
|
||||
| ----------------------- | ---------------------------------------------------------------------- | ------------------------ |
|
||||
| Synthèse vocale | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Transcription vocale par lots | `tools.media.audio` | `scribe_v2` |
|
||||
| Transcription vocale en streaming | streaming d’appel vocal ou Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` |
|
||||
|
||||
## Authentification
|
||||
|
||||
Définissez `ELEVENLABS_API_KEY` dans l’environnement. `XI_API_KEY` est également accepté pour
|
||||
la compatibilité avec les outils ElevenLabs existants.
|
||||
assurer la compatibilité avec les outils ElevenLabs existants.
|
||||
|
||||
```bash
|
||||
export ELEVENLABS_API_KEY="..."
|
||||
@ -50,10 +50,10 @@ export ELEVENLABS_API_KEY="..."
|
||||
}
|
||||
```
|
||||
|
||||
Définissez `modelId` sur `eleven_v3` pour utiliser la synthèse vocale ElevenLabs v3. OpenClaw conserve
|
||||
Définissez `modelId` sur `eleven_v3` pour utiliser la TTS ElevenLabs v3. OpenClaw conserve
|
||||
`eleven_multilingual_v2` comme valeur par défaut pour les installations existantes.
|
||||
|
||||
## Reconnaissance vocale
|
||||
## Transcription vocale
|
||||
|
||||
Utilisez Scribe v2 pour les pièces jointes audio entrantes et les courts segments vocaux enregistrés :
|
||||
|
||||
@ -73,19 +73,19 @@ Utilisez Scribe v2 pour les pièces jointes audio entrantes et les courts segmen
|
||||
OpenClaw envoie l’audio multipart à ElevenLabs `/v1/speech-to-text` avec
|
||||
`model_id: "scribe_v2"`. Les indications de langue sont mappées vers `language_code` lorsqu’elles sont présentes.
|
||||
|
||||
## Reconnaissance vocale en streaming Voice Call
|
||||
## STT en streaming
|
||||
|
||||
Le Plugin `elevenlabs` intégré enregistre Scribe v2 Realtime pour la transcription
|
||||
en streaming Voice Call.
|
||||
Le Plugin `elevenlabs` fourni enregistre Scribe v2 Realtime pour l’appel vocal et
|
||||
la transcription en streaming en mode agent Google Meet.
|
||||
|
||||
| Paramètre | Chemin de config | Valeur par défaut |
|
||||
| --------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| Clé API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Revient à `ELEVENLABS_API_KEY` / `XI_API_KEY` |
|
||||
| Modèle | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Format audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Fréquence d’échantillonnage | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Stratégie de validation | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Langue | `...elevenlabs.languageCode` | (non défini) |
|
||||
| Paramètre | Chemin de configuration | Par défaut |
|
||||
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Clé API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Se rabat sur `ELEVENLABS_API_KEY` / `XI_API_KEY` |
|
||||
| Modèle | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Format audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Fréquence d’échantillonnage | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Stratégie de commit | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Langue | `...elevenlabs.languageCode` | (non défini) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,12 +113,18 @@ en streaming Voice Call.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Voice Call reçoit les médias Twilio en G.711 u-law à 8 kHz. Le fournisseur temps réel ElevenLabs
|
||||
utilise par défaut `ulaw_8000`, ce qui permet de transférer les trames de téléphonie sans
|
||||
L’appel vocal reçoit les médias Twilio en u-law G.711 à 8 kHz. Le fournisseur temps réel ElevenLabs
|
||||
utilise `ulaw_8000` par défaut, ce qui permet de transférer les trames téléphoniques sans
|
||||
transcodage.
|
||||
</Note>
|
||||
|
||||
## Liens connexes
|
||||
Pour le mode agent Google Meet, définissez
|
||||
`plugins.entries.google-meet.config.realtime.transcriptionProvider` sur
|
||||
`"elevenlabs"` et configurez le même bloc de fournisseur sous
|
||||
`plugins.entries.google-meet.config.realtime.providers.elevenlabs`.
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Synthèse vocale](/fr/tools/tts)
|
||||
- [Google Meet](/fr/plugins/google-meet)
|
||||
- [Sélection de modèle](/fr/concepts/model-providers)
|
||||
|
||||
@ -5,25 +5,25 @@ read_when:
|
||||
summary: Configuration de Google Gemini (clé API + OAuth, génération d’images, compréhension des médias, TTS, recherche web)
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T07:16:26Z"
|
||||
generated_at: "2026-05-04T07:05:35Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 14605b88f0d1d7e01796d429113a73b2b52a48fde6443565dcb3db47653be5e7
|
||||
source_hash: 3e45627f5d5cd57e858c7590a90435b7fc0e9381509f3312a16fc9e9a4cbd908
|
||||
source_path: providers/google.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Le Plugin Google donne accès aux modèles Gemini via Google AI Studio, ainsi qu’à
|
||||
la génération d’images, à la compréhension des médias (image/audio/vidéo), à la synthèse vocale et à la recherche web via
|
||||
Le Plugin Google fournit l’accès aux modèles Gemini via Google AI Studio, ainsi que
|
||||
la génération d’images, la compréhension des médias (image/audio/vidéo), la synthèse vocale et la recherche web via
|
||||
Gemini Grounding.
|
||||
|
||||
- Fournisseur : `google`
|
||||
- Authentification : `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
|
||||
- API : API Google Gemini
|
||||
- Option d’exécution : `agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
réutilise l’OAuth Gemini CLI tout en conservant les références de modèle canoniques sous la forme `google/*`.
|
||||
réutilise l’OAuth de Gemini CLI tout en conservant les références de modèles canoniques sous la forme `google/*`.
|
||||
|
||||
## Premiers pas
|
||||
## Bien démarrer
|
||||
|
||||
Choisissez votre méthode d’authentification préférée et suivez les étapes de configuration.
|
||||
|
||||
@ -32,7 +32,7 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
**Idéal pour :** l’accès standard à l’API Gemini via Google AI Studio.
|
||||
|
||||
<Steps>
|
||||
<Step title="Exécuter l’intégration">
|
||||
<Step title="Lancer l’intégration">
|
||||
```bash
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
@ -75,7 +75,7 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
|
||||
<Warning>
|
||||
Le fournisseur `google-gemini-cli` est une intégration non officielle. Certains utilisateurs
|
||||
signalent des restrictions de compte lorsqu’ils utilisent OAuth de cette façon. Utilisez-le à vos propres risques.
|
||||
signalent des restrictions de compte lors de l’utilisation d’OAuth de cette manière. Utilisez-le à vos propres risques.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
@ -90,7 +90,7 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
OpenClaw prend en charge les installations Homebrew et les installations npm globales, y compris
|
||||
OpenClaw prend en charge les installations Homebrew ainsi que les installations npm globales, y compris
|
||||
les dispositions Windows/npm courantes.
|
||||
</Step>
|
||||
<Step title="Se connecter via OAuth">
|
||||
@ -109,7 +109,7 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
- Runtime : `google-gemini-cli`
|
||||
- Alias : `gemini-cli`
|
||||
|
||||
L’identifiant de modèle Gemini API de Gemini 3.1 Pro est `gemini-3.1-pro-preview`. OpenClaw accepte le plus court `google/gemini-3.1-pro` comme alias pratique et le normalise avant les appels au fournisseur.
|
||||
L’identifiant de modèle de Gemini 3.1 Pro dans l’API Gemini est `gemini-3.1-pro-preview`. OpenClaw accepte la forme plus courte `google/gemini-3.1-pro` comme alias pratique et la normalise avant les appels au fournisseur.
|
||||
|
||||
**Variables d’environnement :**
|
||||
|
||||
@ -119,8 +119,8 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
(Ou les variantes `GEMINI_CLI_*`.)
|
||||
|
||||
<Note>
|
||||
Si les requêtes OAuth Gemini CLI échouent après la connexion, définissez `GOOGLE_CLOUD_PROJECT` ou
|
||||
`GOOGLE_CLOUD_PROJECT_ID` sur l’hôte Gateway puis réessayez.
|
||||
Si les requêtes OAuth de Gemini CLI échouent après la connexion, définissez `GOOGLE_CLOUD_PROJECT` ou
|
||||
`GOOGLE_CLOUD_PROJECT_ID` sur l’hôte du Gateway et réessayez.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
@ -128,32 +128,32 @@ Choisissez votre méthode d’authentification préférée et suivez les étapes
|
||||
est installée et présente dans `PATH`.
|
||||
</Note>
|
||||
|
||||
Les références de modèle `google-gemini-cli/*` sont des alias de compatibilité hérités. Les nouvelles
|
||||
configurations doivent utiliser des références de modèle `google/*` avec le runtime `google-gemini-cli`
|
||||
lorsqu’elles veulent une exécution locale avec Gemini CLI.
|
||||
Les références de modèles `google-gemini-cli/*` sont des alias de compatibilité hérités. Les nouvelles
|
||||
configurations doivent utiliser les références de modèles `google/*`, ainsi que le runtime `google-gemini-cli`
|
||||
lorsqu’elles souhaitent une exécution locale de Gemini CLI.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Fonctionnalités
|
||||
|
||||
| Fonctionnalité | Pris en charge |
|
||||
| ------------------------------ | ------------------------------ |
|
||||
| Complétions de chat | Oui |
|
||||
| Génération d’images | Oui |
|
||||
| Génération de musique | Oui |
|
||||
| Synthèse vocale | Oui |
|
||||
| Voix en temps réel | Oui (API Google Live) |
|
||||
| Compréhension d’images | Oui |
|
||||
| Transcription audio | Oui |
|
||||
| Compréhension de vidéos | Oui |
|
||||
| Recherche web (Grounding) | Oui |
|
||||
| Pensée/raisonnement | Oui (Gemini 2.5+ / Gemini 3+) |
|
||||
| Modèles Gemma 4 | Oui |
|
||||
| Fonctionnalité | Pris en charge |
|
||||
| ---------------------- | ----------------------------- |
|
||||
| Complétions de chat | Oui |
|
||||
| Génération d’images | Oui |
|
||||
| Génération de musique | Oui |
|
||||
| Synthèse vocale | Oui |
|
||||
| Voix en temps réel | Oui (Google Live API) |
|
||||
| Compréhension des images | Oui |
|
||||
| Transcription audio | Oui |
|
||||
| Compréhension vidéo | Oui |
|
||||
| Recherche web (Grounding) | Oui |
|
||||
| Réflexion/raisonnement | Oui (Gemini 2.5+ / Gemini 3+) |
|
||||
| Modèles Gemma 4 | Oui |
|
||||
|
||||
## Recherche web
|
||||
|
||||
Le fournisseur de recherche web `gemini` intégré utilise le grounding de Google Search de Gemini.
|
||||
Le fournisseur de recherche web `gemini` intégré utilise le grounding de Gemini Google Search.
|
||||
Configurez une clé de recherche dédiée sous `plugins.entries.google.config.webSearch`,
|
||||
ou laissez-le réutiliser `models.providers.google.apiKey` après `GEMINI_API_KEY` :
|
||||
|
||||
@ -177,24 +177,24 @@ ou laissez-le réutiliser `models.providers.google.apiKey` après `GEMINI_API_KE
|
||||
|
||||
L’ordre de priorité des identifiants est `webSearch.apiKey` dédié, puis `GEMINI_API_KEY`,
|
||||
puis `models.providers.google.apiKey`. `webSearch.baseUrl` est facultatif et
|
||||
existe pour les proxys d’opérateur ou les points de terminaison compatibles avec l’API Gemini ; lorsqu’il est omis,
|
||||
existe pour les proxys d’opérateurs ou les points de terminaison compatibles avec l’API Gemini ; lorsqu’il est omis,
|
||||
la recherche web Gemini réutilise `models.providers.google.baseUrl`. Consultez
|
||||
[Recherche Gemini](/fr/tools/gemini-search) pour le comportement d’outil propre à ce fournisseur.
|
||||
[Recherche Gemini](/fr/tools/gemini-search) pour le comportement de l’outil propre à ce fournisseur.
|
||||
|
||||
<Tip>
|
||||
Les modèles Gemini 3 utilisent `thinkingLevel` plutôt que `thinkingBudget`. OpenClaw mappe
|
||||
les contrôles de raisonnement des alias Gemini 3, Gemini 3.1 et `gemini-*-latest` vers
|
||||
`thinkingLevel`, afin que les exécutions par défaut/à faible latence n’envoient pas de valeurs
|
||||
`thinkingLevel` afin que les exécutions par défaut/à faible latence n’envoient pas de valeurs
|
||||
`thinkingBudget` désactivées.
|
||||
|
||||
`/think adaptive` conserve la sémantique de pensée dynamique de Google au lieu de choisir
|
||||
`/think adaptive` conserve la sémantique de réflexion dynamique de Google au lieu de choisir
|
||||
un niveau OpenClaw fixe. Gemini 3 et Gemini 3.1 omettent un `thinkingLevel` fixe afin que
|
||||
Google puisse choisir le niveau ; Gemini 2.5 envoie la sentinelle dynamique de Google
|
||||
`thinkingBudget: -1`.
|
||||
|
||||
Les modèles Gemma 4 (par exemple `gemma-4-26b-a4b-it`) prennent en charge le mode pensée. OpenClaw
|
||||
réécrit `thinkingBudget` vers un `thinkingLevel` Google pris en charge pour Gemma 4.
|
||||
Définir la pensée sur `off` conserve la pensée désactivée au lieu de la mapper vers
|
||||
Les modèles Gemma 4 (par exemple `gemma-4-26b-a4b-it`) prennent en charge le mode réflexion. OpenClaw
|
||||
réécrit `thinkingBudget` en un `thinkingLevel` Google pris en charge pour Gemma 4.
|
||||
Définir la réflexion sur `off` conserve la réflexion désactivée au lieu de la mapper vers
|
||||
`MINIMAL`.
|
||||
</Tip>
|
||||
|
||||
@ -206,7 +206,7 @@ Le fournisseur de génération d’images `google` intégré utilise par défaut
|
||||
- Prend également en charge `google/gemini-3-pro-image-preview`
|
||||
- Génération : jusqu’à 4 images par requête
|
||||
- Mode édition : activé, jusqu’à 5 images d’entrée
|
||||
- Contrôles de géométrie : `size`, `aspectRatio` et `resolution`
|
||||
- Contrôles géométriques : `size`, `aspectRatio` et `resolution`
|
||||
|
||||
Pour utiliser Google comme fournisseur d’images par défaut :
|
||||
|
||||
@ -223,16 +223,16 @@ Pour utiliser Google comme fournisseur d’images par défaut :
|
||||
```
|
||||
|
||||
<Note>
|
||||
Consultez [Génération d’images](/fr/tools/image-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
|
||||
Consultez [Génération d’images](/fr/tools/image-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
|
||||
</Note>
|
||||
|
||||
## Génération de vidéos
|
||||
## Génération vidéo
|
||||
|
||||
Le Plugin `google` intégré enregistre aussi la génération de vidéos via l’outil partagé
|
||||
Le Plugin `google` intégré enregistre également la génération vidéo via l’outil partagé
|
||||
`video_generate`.
|
||||
|
||||
- Modèle vidéo par défaut : `google/veo-3.1-fast-generate-preview`
|
||||
- Modes : texte-vers-vidéo, image-vers-vidéo et flux de référence à une seule vidéo
|
||||
- Modes : texte vers vidéo, image vers vidéo et flux de référence à vidéo unique
|
||||
- Prend en charge `aspectRatio`, `resolution` et `audio`
|
||||
- Limite de durée actuelle : **4 à 8 secondes**
|
||||
|
||||
@ -251,20 +251,20 @@ Pour utiliser Google comme fournisseur vidéo par défaut :
|
||||
```
|
||||
|
||||
<Note>
|
||||
Consultez [Génération de vidéos](/fr/tools/video-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
|
||||
Consultez [Génération vidéo](/fr/tools/video-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
|
||||
</Note>
|
||||
|
||||
## Génération de musique
|
||||
|
||||
Le Plugin `google` intégré enregistre aussi la génération de musique via l’outil partagé
|
||||
Le Plugin `google` intégré enregistre également la génération de musique via l’outil partagé
|
||||
`music_generate`.
|
||||
|
||||
- Modèle musical par défaut : `google/lyria-3-clip-preview`
|
||||
- Modèle de musique par défaut : `google/lyria-3-clip-preview`
|
||||
- Prend également en charge `google/lyria-3-pro-preview`
|
||||
- Contrôles de prompt : `lyrics` et `instrumental`
|
||||
- Format de sortie : `mp3` par défaut, plus `wav` sur `google/lyria-3-pro-preview`
|
||||
- Entrées de référence : jusqu’à 10 images
|
||||
- Les exécutions adossées à une session se détachent via le flux partagé tâche/statut, y compris `action: "status"`
|
||||
- Les exécutions appuyées par une session se détachent via le flux partagé de tâche/état, y compris `action: "status"`
|
||||
|
||||
Pour utiliser Google comme fournisseur de musique par défaut :
|
||||
|
||||
@ -281,18 +281,18 @@ Pour utiliser Google comme fournisseur de musique par défaut :
|
||||
```
|
||||
|
||||
<Note>
|
||||
Consultez [Génération de musique](/fr/tools/music-generation) pour les paramètres d’outil partagés, la sélection du fournisseur et le comportement de basculement.
|
||||
Consultez [Génération de musique](/fr/tools/music-generation) pour les paramètres partagés de l’outil, la sélection du fournisseur et le comportement de basculement.
|
||||
</Note>
|
||||
|
||||
## Synthèse vocale
|
||||
|
||||
Le fournisseur vocal `google` intégré utilise le chemin TTS de l’API Gemini avec
|
||||
Le fournisseur de parole `google` intégré utilise le chemin TTS de l’API Gemini avec
|
||||
`gemini-3.1-flash-tts-preview`.
|
||||
|
||||
- Voix par défaut : `Kore`
|
||||
- Authentification : `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY`
|
||||
- Sortie : WAV pour les pièces jointes TTS classiques, Opus pour les cibles de note vocale, PCM pour Talk/téléphonie
|
||||
- Sortie note vocale : le PCM Google est encapsulé en WAV et transcodé en Opus 48 kHz avec `ffmpeg`
|
||||
- Sortie : WAV pour les pièces jointes TTS classiques, Opus pour les cibles de notes vocales, PCM pour Talk/téléphonie
|
||||
- Sortie de note vocale : le PCM Google est encapsulé en WAV et transcodé en Opus 48 kHz avec `ffmpeg`
|
||||
|
||||
Pour utiliser Google comme fournisseur TTS par défaut :
|
||||
|
||||
@ -314,12 +314,12 @@ Pour utiliser Google comme fournisseur TTS par défaut :
|
||||
}
|
||||
```
|
||||
|
||||
Gemini API TTS utilise des prompts en langage naturel pour contrôler le style. Définissez
|
||||
`audioProfile` pour préfixer le texte à prononcer avec un prompt de style réutilisable. Définissez
|
||||
`speakerName` lorsque votre texte de prompt fait référence à un locuteur nommé.
|
||||
Le TTS de l’API Gemini utilise des prompts en langage naturel pour contrôler le style. Définissez
|
||||
`audioProfile` pour préfixer le texte prononcé avec un prompt de style réutilisable. Définissez
|
||||
`speakerName` lorsque le texte de votre prompt fait référence à un locuteur nommé.
|
||||
|
||||
Gemini API TTS accepte aussi des balises audio expressives entre crochets dans le texte,
|
||||
comme `[whispers]` ou `[laughs]`. Pour éviter que ces balises apparaissent dans la réponse de chat visible
|
||||
Le TTS de l’API Gemini accepte également des balises audio expressives entre crochets dans le texte,
|
||||
comme `[whispers]` ou `[laughs]`. Pour exclure les balises de la réponse de chat visible
|
||||
tout en les envoyant au TTS, placez-les dans un bloc `[[tts:text]]...[[/tts:text]]` :
|
||||
|
||||
```text
|
||||
@ -330,7 +330,7 @@ Here is the clean reply text.
|
||||
|
||||
<Note>
|
||||
Une clé API Google Cloud Console limitée à l’API Gemini est valide pour ce
|
||||
fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Speech.
|
||||
fournisseur. Il ne s’agit pas du chemin séparé de l’API Cloud Text-to-Speech.
|
||||
</Note>
|
||||
|
||||
## Voix en temps réel
|
||||
@ -338,20 +338,22 @@ fournisseur. Il ne s’agit pas du chemin distinct de l’API Cloud Text-to-Spee
|
||||
Le Plugin `google` intégré enregistre un fournisseur de voix en temps réel adossé à
|
||||
l’API Gemini Live pour les ponts audio backend tels que Voice Call et Google Meet.
|
||||
|
||||
| Paramètre | Chemin de configuration | Valeur par défaut |
|
||||
| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| Modèle | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Voix | `...google.voice` | `Kore` |
|
||||
| Température | `...google.temperature` | (non défini) |
|
||||
| Sensibilité de début VAD | `...google.startSensitivity` | (non défini) |
|
||||
| Sensibilité de fin VAD | `...google.endSensitivity` | (non défini) |
|
||||
| Durée de silence | `...google.silenceDurationMs` | (non défini) |
|
||||
| Gestion de l’activité | `...google.activityHandling` | Valeur par défaut de Google, `start-of-activity-interrupts` |
|
||||
| Couverture du tour | `...google.turnCoverage` | Valeur par défaut de Google, `only-activity` |
|
||||
| Désactiver VAD automatique | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Clé API | `...google.apiKey` | Se rabat sur `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` |
|
||||
| Paramètre | Chemin de configuration | Valeur par défaut |
|
||||
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Modèle | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| Voix | `...google.voice` | `Kore` |
|
||||
| Température | `...google.temperature` | (non défini) |
|
||||
| Sensibilité de début VAD | `...google.startSensitivity` | (non défini) |
|
||||
| Sensibilité de fin VAD | `...google.endSensitivity` | (non défini) |
|
||||
| Durée du silence | `...google.silenceDurationMs` | (non défini) |
|
||||
| Gestion de l’activité | `...google.activityHandling` | Valeur par défaut de Google, `start-of-activity-interrupts` |
|
||||
| Couverture du tour | `...google.turnCoverage` | Valeur par défaut de Google, `only-activity` |
|
||||
| Désactiver la VAD automatique | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| Reprise de session | `...google.sessionResumption` | `true` |
|
||||
| Compression du contexte | `...google.contextWindowCompression` | `true` |
|
||||
| Clé API | `...google.apiKey` | Se replie sur `models.providers.google.apiKey`, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` |
|
||||
|
||||
Exemple de configuration en temps réel de Voice Call :
|
||||
Exemple de configuration temps réel Voice Call :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -380,24 +382,25 @@ Exemple de configuration en temps réel de Voice Call :
|
||||
```
|
||||
|
||||
<Note>
|
||||
Google Live API utilise l’audio bidirectionnel et les appels de fonctions via un WebSocket.
|
||||
OpenClaw adapte l’audio du pont téléphonie/Meet au flux Gemini PCM Live API et
|
||||
Google Live API utilise l’audio bidirectionnel et l’appel de fonctions via un WebSocket.
|
||||
OpenClaw adapte l’audio de téléphonie/pont Meet au flux PCM Live API de Gemini et
|
||||
conserve les appels d’outils sur le contrat vocal temps réel partagé. Laissez `temperature`
|
||||
non défini sauf si vous devez modifier l’échantillonnage ; OpenClaw omet les valeurs non positives
|
||||
non défini, sauf si vous devez modifier l’échantillonnage ; OpenClaw omet les valeurs non positives,
|
||||
car Google Live peut renvoyer des transcriptions sans audio pour `temperature: 0`.
|
||||
La transcription Gemini API est activée sans `languageCodes` ; le SDK Google actuel
|
||||
rejette les indications de code de langue sur ce chemin d’API.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk prend en charge les sessions navigateur Google Live avec des jetons à usage unique contraints.
|
||||
Les fournisseurs de voix temps réel côté backend uniquement peuvent aussi passer par le transport relais générique
|
||||
du Gateway, qui conserve les identifiants du fournisseur sur le Gateway.
|
||||
Control UI Talk prend en charge les sessions Google Live dans le navigateur avec des
|
||||
jetons contraints à usage unique. Les fournisseurs vocaux temps réel côté backend uniquement
|
||||
peuvent aussi passer par le transport de relais générique du Gateway, qui conserve
|
||||
les identifiants du fournisseur sur le Gateway.
|
||||
</Note>
|
||||
|
||||
Pour la vérification en direct par les mainteneurs, exécutez
|
||||
Pour la vérification live par les mainteneurs, exécutez
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`.
|
||||
La partie Google émet la même forme de jeton Live API contraint que celle utilisée par Control
|
||||
Le segment Google émet la même forme de jeton contraint Live API que celle utilisée par Control
|
||||
UI Talk, ouvre le point de terminaison WebSocket du navigateur, envoie la charge utile de configuration initiale
|
||||
et attend `setupComplete`.
|
||||
|
||||
@ -412,8 +415,8 @@ et attend `setupComplete`.
|
||||
`cachedContent` ou l’ancien `cached_content`
|
||||
- Si les deux sont présents, `cachedContent` l’emporte
|
||||
- Exemple de valeur : `cachedContents/prebuilt-context`
|
||||
- L’utilisation d’un cache hit Gemini est normalisée dans OpenClaw `cacheRead` depuis
|
||||
le champ amont `cachedContentTokenCount`
|
||||
- L’utilisation des succès de cache Gemini est normalisée dans `cacheRead` OpenClaw à partir de
|
||||
`cachedContentTokenCount` en amont
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -438,33 +441,33 @@ et attend `setupComplete`.
|
||||
la sortie JSON de la CLI comme suit :
|
||||
|
||||
- Le texte de réponse provient du champ `response` du JSON de la CLI.
|
||||
- L’utilisation se rabat sur `stats` lorsque la CLI laisse `usage` vide.
|
||||
- `stats.cached` est normalisé dans OpenClaw `cacheRead`.
|
||||
- Si `stats.input` est absent, OpenClaw déduit les jetons d’entrée depuis
|
||||
- L’utilisation se replie sur `stats` lorsque la CLI laisse `usage` vide.
|
||||
- `stats.cached` est normalisé dans `cacheRead` OpenClaw.
|
||||
- Si `stats.input` est absent, OpenClaw déduit les jetons d’entrée de
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configuration de l’environnement et du démon">
|
||||
Si le Gateway s’exécute comme démon (launchd/systemd), assurez-vous que `GEMINI_API_KEY`
|
||||
est disponible pour ce processus (par exemple dans `~/.openclaw/.env` ou via
|
||||
<Accordion title="Configuration de l’environnement et du daemon">
|
||||
Si le Gateway s’exécute comme daemon (launchd/systemd), assurez-vous que `GEMINI_API_KEY`
|
||||
est disponible pour ce processus (par exemple, dans `~/.openclaw/.env` ou via
|
||||
`env.shellEnv`).
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Associé
|
||||
## Associés
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Sélection du modèle" href="/fr/concepts/model-providers" icon="layers">
|
||||
Choix des fournisseurs, des références de modèles et du comportement de bascule.
|
||||
Choix des fournisseurs, des références de modèle et du comportement de basculement.
|
||||
</Card>
|
||||
<Card title="Génération d’images" href="/fr/tools/image-generation" icon="image">
|
||||
Paramètres d’outil d’image partagés et sélection du fournisseur.
|
||||
<Card title="Génération d’image" href="/fr/tools/image-generation" icon="image">
|
||||
Paramètres partagés de l’outil image et sélection du fournisseur.
|
||||
</Card>
|
||||
<Card title="Génération de vidéos" href="/fr/tools/video-generation" icon="video">
|
||||
Paramètres d’outil vidéo partagés et sélection du fournisseur.
|
||||
<Card title="Génération de vidéo" href="/fr/tools/video-generation" icon="video">
|
||||
Paramètres partagés de l’outil vidéo et sélection du fournisseur.
|
||||
</Card>
|
||||
<Card title="Génération de musique" href="/fr/tools/music-generation" icon="music">
|
||||
Paramètres d’outil musical partagés et sélection du fournisseur.
|
||||
Paramètres partagés de l’outil musique et sélection du fournisseur.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,181 +1,283 @@
|
||||
---
|
||||
read_when:
|
||||
- Recherche des définitions des canaux de publication publics
|
||||
- Exécution de la validation de version ou de l’acceptation du package
|
||||
- Recherche de la nomenclature et de la cadence des versions
|
||||
summary: Voies de publication, liste de contrôle opérateur, boîtes de validation, nommage des versions et cadence
|
||||
- Exécuter la validation de version ou l’acceptation de package
|
||||
- Recherche de la nomenclature des versions et de la cadence
|
||||
summary: Voies de publication, liste de contrôle de l’opérateur, boîtes de validation, nommage des versions et cadence
|
||||
title: Politique de publication
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:37:55Z"
|
||||
generated_at: "2026-05-04T07:06:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
|
||||
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw comporte trois canaux de publication publics :
|
||||
OpenClaw propose trois canaux de publication publics :
|
||||
|
||||
- stable : versions balisées publiées sur npm `beta` par défaut, ou sur npm `latest` sur demande explicite
|
||||
- beta : balises de préversion publiées sur npm `beta`
|
||||
- dev : tête mouvante de `main`
|
||||
- stable : versions étiquetées qui publient vers npm `beta` par défaut, ou vers npm `latest` lorsque cela est explicitement demandé
|
||||
- beta : balises de préversion qui publient vers npm `beta`
|
||||
- dev : la tête mobile de `main`
|
||||
|
||||
## Nommage des versions
|
||||
|
||||
- Version de publication stable : `YYYY.M.D`
|
||||
- Balise Git : `vYYYY.M.D`
|
||||
- Version corrective stable : `YYYY.M.D-N`
|
||||
- Version de publication corrective stable : `YYYY.M.D-N`
|
||||
- Balise Git : `vYYYY.M.D-N`
|
||||
- Version de préversion bêta : `YYYY.M.D-beta.N`
|
||||
- Version de prépublication beta : `YYYY.M.D-beta.N`
|
||||
- Balise Git : `vYYYY.M.D-beta.N`
|
||||
- Ne pas ajouter de zéro initial au mois ni au jour
|
||||
- Ne pas compléter le mois ou le jour avec un zéro initial
|
||||
- `latest` désigne la version stable npm actuellement promue
|
||||
- `beta` désigne la cible d’installation bêta actuelle
|
||||
- Les publications stables et correctives stables sont publiées sur npm `beta` par défaut ; les opérateurs de publication peuvent cibler explicitement `latest`, ou promouvoir ultérieurement une build bêta validée
|
||||
- `beta` désigne la cible d’installation beta actuelle
|
||||
- Les publications stables et correctives stables publient vers npm `beta` par défaut ; les opérateurs de publication peuvent cibler explicitement `latest`, ou promouvoir ultérieurement une build beta validée
|
||||
- Chaque publication stable d’OpenClaw livre ensemble le paquet npm et l’application macOS ;
|
||||
les publications bêta valident et publient normalement d’abord le chemin npm/paquet, la
|
||||
build/signature/notarisation de l’application mac étant réservée aux versions stables sauf demande explicite
|
||||
les publications beta valident et publient normalement d’abord le chemin npm/paquet, la
|
||||
compilation/signature/notarisation de l’application Mac étant réservée aux versions stables sauf demande explicite
|
||||
|
||||
## Cadence de publication
|
||||
|
||||
- Les publications passent d’abord par la bêta
|
||||
- La stable ne suit qu’après validation de la dernière bêta
|
||||
- Les mainteneurs créent normalement les publications depuis une branche `release/YYYY.M.D` créée
|
||||
à partir de `main` courant, afin que la validation de publication et les correctifs ne bloquent pas le nouveau
|
||||
- Les publications passent d’abord par beta
|
||||
- Stable suit seulement après validation de la dernière beta
|
||||
- Les mainteneurs créent normalement les publications à partir d’une branche `release/YYYY.M.D` créée
|
||||
depuis le `main` actuel, afin que la validation et les correctifs de publication ne bloquent pas le nouveau
|
||||
développement sur `main`
|
||||
- Si une balise bêta a été poussée ou publiée et nécessite un correctif, les mainteneurs créent
|
||||
la balise `-beta.N` suivante au lieu de supprimer ou recréer l’ancienne balise bêta
|
||||
- Si une balise beta a été poussée ou publiée et nécessite un correctif, les mainteneurs créent
|
||||
la balise `-beta.N` suivante au lieu de supprimer ou recréer l’ancienne balise beta
|
||||
- La procédure de publication détaillée, les approbations, les identifiants et les notes de récupération sont
|
||||
réservés aux mainteneurs
|
||||
|
||||
## Liste de contrôle de l’opérateur de publication
|
||||
|
||||
Cette liste de contrôle décrit publiquement la structure du flux de publication. Les identifiants privés,
|
||||
la signature, la notarisation, la récupération des dist-tags et les détails de rollback d’urgence restent dans
|
||||
le runbook de publication réservé aux mainteneurs.
|
||||
Cette liste de contrôle présente la forme publique du flux de publication. Les identifiants privés,
|
||||
la signature, la notarisation, la récupération des dist-tags et les détails de restauration d’urgence restent dans
|
||||
le guide de publication réservé aux mainteneurs.
|
||||
|
||||
1. Partir de `main` courant : récupérer la dernière version, confirmer que le commit cible est poussé,
|
||||
et confirmer que la CI de `main` courant est suffisamment verte pour créer une branche depuis celui-ci.
|
||||
1. Partir du `main` actuel : récupérer la dernière version, confirmer que le commit cible est poussé,
|
||||
et confirmer que la CI du `main` actuel est suffisamment verte pour créer une branche depuis celui-ci.
|
||||
2. Réécrire la section supérieure de `CHANGELOG.md` à partir de l’historique réel des commits avec
|
||||
`/changelog`, garder des entrées destinées aux utilisateurs, la commiter, la pousser, puis rebaser/récupérer
|
||||
`/changelog`, garder les entrées orientées utilisateur, la commiter, la pousser, puis rebaser/récupérer
|
||||
une fois de plus avant de créer la branche.
|
||||
3. Examiner les enregistrements de compatibilité de publication dans
|
||||
`src/plugins/compat/registry.ts` et
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Supprimer la compatibilité expirée
|
||||
uniquement lorsque le chemin de mise à niveau reste couvert, ou consigner pourquoi elle est
|
||||
intentionnellement conservée.
|
||||
4. Créer `release/YYYY.M.D` depuis `main` courant ; ne pas effectuer le travail de publication normal
|
||||
4. Créer `release/YYYY.M.D` depuis le `main` actuel ; ne pas effectuer le travail de publication normal
|
||||
directement sur `main`.
|
||||
5. Mettre à jour chaque emplacement de version requis pour la balise prévue, exécuter
|
||||
`pnpm plugins:sync` afin que les paquets de Plugin publiables partagent la version de publication
|
||||
et les métadonnées de compatibilité, puis exécuter le prévol déterministe local :
|
||||
`pnpm plugins:sync` afin que les paquets Plugin publiables partagent la version de publication
|
||||
et les métadonnées de compatibilité, puis exécuter la prévalidation déterministe locale :
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` et
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, et
|
||||
`pnpm release:check`.
|
||||
6. Exécuter `OpenClaw NPM Release` avec `preflight_only=true`. Avant l’existence d’une balise,
|
||||
un SHA complet de 40 caractères de la branche de publication est autorisé pour le prévol
|
||||
de validation uniquement. Enregistrer le `preflight_run_id` réussi.
|
||||
6. Exécuter `OpenClaw NPM Release` avec `preflight_only=true`. Avant qu’une balise existe,
|
||||
un SHA complet de 40 caractères de la branche de publication est autorisé pour une prévalidation
|
||||
uniquement destinée à la validation. Enregistrer le `preflight_run_id` réussi.
|
||||
7. Lancer tous les tests de prépublication avec `Full Release Validation` pour la
|
||||
branche de publication, la balise ou le SHA complet du commit. C’est le point d’entrée manuel unique
|
||||
pour les quatre grandes boîtes de tests de publication : Vitest, Docker, QA Lab et Package.
|
||||
8. Si la validation échoue, corriger sur la branche de publication et réexécuter le plus petit
|
||||
fichier, canal, job de workflow, profil de paquet, fournisseur ou allowlist de modèles en échec qui
|
||||
prouve le correctif. Réexécuter l’enveloppe complète uniquement lorsque la surface modifiée rend
|
||||
pour les quatre grandes boîtes de test de publication : Vitest, Docker, QA Lab et Package.
|
||||
8. Si la validation échoue, corriger sur la branche de publication et relancer le plus petit
|
||||
fichier, canal, job de workflow, profil de paquet, fournisseur ou allowlist de modèle en échec qui
|
||||
prouve le correctif. Relancer l’umbrella complète uniquement lorsque la surface modifiée rend
|
||||
les preuves antérieures obsolètes.
|
||||
9. Pour la bêta, baliser `vYYYY.M.D-beta.N`, puis exécuter `OpenClaw Release Publish` depuis
|
||||
9. Pour beta, étiqueter `vYYYY.M.D-beta.N`, puis exécuter `OpenClaw Release Publish` depuis
|
||||
la branche `release/YYYY.M.D` correspondante. Il vérifie `pnpm plugins:sync:check`,
|
||||
publie d’abord tous les paquets de Plugin publiables sur npm, publie ensuite le même
|
||||
ensemble sur ClawHub sous forme de tarballs npm-pack ClawPack, puis promeut l’artefact
|
||||
de prévol npm OpenClaw préparé avec le dist-tag correspondant. Après publication, exécuter l’acceptation
|
||||
post-publication du paquet contre le paquet publié `openclaw@YYYY.M.D-beta.N` ou
|
||||
`openclaw@beta`. Si une préversion poussée ou publiée nécessite un correctif,
|
||||
créer le numéro de préversion correspondant suivant ; ne pas supprimer ni réécrire l’ancienne
|
||||
préversion.
|
||||
10. Pour la stable, continuer uniquement après que la bêta validée ou la release candidate dispose des
|
||||
publie d’abord tous les paquets Plugin publiables vers npm, publie ensuite le même
|
||||
ensemble vers ClawHub sous forme de tarballs npm-pack ClawPack, puis promeut
|
||||
l’artefact de prévalidation npm OpenClaw préparé avec le dist-tag correspondant. Après
|
||||
publication, exécuter l’acceptation du paquet post-publication
|
||||
contre le paquet publié `openclaw@YYYY.M.D-beta.N` ou
|
||||
`openclaw@beta`. Si une prépublication poussée ou publiée nécessite un correctif,
|
||||
créer le numéro de prépublication correspondant suivant ; ne pas supprimer ni réécrire l’ancienne
|
||||
prépublication.
|
||||
10. Pour stable, continuer uniquement après que la beta validée ou la version candidate dispose des
|
||||
preuves de validation requises. La publication npm stable passe aussi par
|
||||
`OpenClaw Release Publish`, en réutilisant l’artefact de prévol réussi via
|
||||
`preflight_run_id` ; la préparation de la publication macOS stable nécessite également les
|
||||
fichiers empaquetés `.zip`, `.dmg`, `.dSYM.zip`, ainsi que le fichier `appcast.xml` mis à jour sur `main`.
|
||||
11. Après publication, exécuter le vérificateur npm post-publication, l’E2E Telegram
|
||||
publié-npm autonome facultatif lorsque vous avez besoin d’une preuve de canal post-publication,
|
||||
la promotion de dist-tag si nécessaire, les notes de publication/préversion GitHub depuis la
|
||||
section `CHANGELOG.md` correspondante complète, ainsi que les étapes d’annonce de publication.
|
||||
`OpenClaw Release Publish`, en réutilisant l’artefact de prévalidation réussi via
|
||||
`preflight_run_id` ; l’état prêt pour la publication macOS stable exige également le
|
||||
`.zip`, le `.dmg`, le `.dSYM.zip` empaquetés, ainsi que le `appcast.xml` mis à jour sur `main`.
|
||||
11. Après publication, exécuter le vérificateur npm post-publication, l’E2E Telegram npm publié
|
||||
autonome facultatif lorsque vous avez besoin d’une preuve de canal post-publication,
|
||||
la promotion de dist-tag si nécessaire, les notes de publication/prépublication GitHub depuis la
|
||||
section complète correspondante de `CHANGELOG.md`, et les étapes d’annonce de publication.
|
||||
|
||||
## Prévol de publication
|
||||
## Prévalidation de publication
|
||||
|
||||
- Exécutez `pnpm check:test-types` avant la préparation de release afin que le TypeScript des tests reste couvert en dehors du gate local plus rapide `pnpm check`
|
||||
- Exécutez `pnpm check:architecture` avant la préparation de release afin que les vérifications plus larges des cycles d’import et des limites d’architecture soient vertes en dehors du gate local plus rapide
|
||||
- Exécutez `pnpm build && pnpm ui:build` avant `pnpm release:check` afin que les artefacts de release `dist/*` attendus et le bundle de Control UI existent pour l’étape de validation du pack
|
||||
- Exécutez `pnpm plugins:sync` après l’incrément de version racine et avant le tag. Il met à jour les versions des paquets Plugin publiables, les métadonnées de compatibilité peer/API d’OpenClaw, les métadonnées de build et les ébauches de journaux de modifications des plugins pour correspondre à la version de release du cœur. `pnpm plugins:sync:check` est le garde-fou de release non modifiant ; le workflow de publication échoue avant toute mutation du registre si cette étape a été oubliée.
|
||||
- Exécutez le workflow manuel `Full Release Validation` avant l’approbation de release pour lancer toutes les boîtes de test pré-release depuis un point d’entrée unique. Il accepte une branche, un tag ou un SHA de commit complet, déclenche le `CI` manuel et déclenche `OpenClaw Release Checks` pour les suites de smoke d’installation, d’acceptation de paquet, de chemins de release Docker, live/E2E, OpenWebUI, parité QA Lab, Matrix et Telegram. Avec `release_profile=full` et `rerun_group=all`, il exécute aussi l’E2E Telegram de paquet contre l’artefact `release-package-under-test` provenant des contrôles de release. Fournissez `npm_telegram_package_spec` après la publication lorsque le même E2E Telegram doit aussi valider le paquet npm publié. Fournissez `package_acceptance_package_spec` après la publication lorsque Package Acceptance doit exécuter sa matrice paquet/mise à jour contre le paquet npm livré au lieu de l’artefact construit depuis le SHA. Fournissez `evidence_package_spec` lorsque le rapport de preuve privé doit démontrer que la validation correspond à un paquet npm publié sans forcer l’E2E Telegram.
|
||||
- Exécutez `pnpm check:test-types` avant la prévalidation de release afin que le TypeScript des tests reste
|
||||
couvert en dehors de la gate locale plus rapide `pnpm check`
|
||||
- Exécutez `pnpm check:architecture` avant la prévalidation de release afin que les vérifications plus larges des
|
||||
cycles d’importation et des limites d’architecture soient vertes en dehors de la gate locale plus rapide
|
||||
- Exécutez `pnpm build && pnpm ui:build` avant `pnpm release:check` afin que les artefacts de release attendus
|
||||
`dist/*` et le bundle Control UI existent pour l’étape de validation du pack
|
||||
- Exécutez `pnpm plugins:sync` après l’incrément de version racine et avant le marquage. Cette commande
|
||||
met à jour les versions des packages Plugin publiables, les métadonnées de compatibilité pair/API OpenClaw,
|
||||
les métadonnées de build et les ébauches de changelog Plugin pour qu’elles correspondent à la version de
|
||||
release du cœur. `pnpm plugins:sync:check` est la garde de release non mutante ;
|
||||
le workflow de publication échoue avant toute mutation du registre si cette étape a été
|
||||
oubliée.
|
||||
- Exécutez le workflow manuel `Full Release Validation` avant l’approbation de release pour
|
||||
lancer toutes les boîtes de test de pré-release depuis un seul point d’entrée. Il accepte une branche,
|
||||
une balise ou un SHA de commit complet, déclenche manuellement `CI` et déclenche
|
||||
`OpenClaw Release Checks` pour la fumée d’installation, l’acceptation de package, les suites de chemin de release Docker,
|
||||
le live/E2E, OpenWebUI, la parité QA Lab, Matrix et les
|
||||
voies Telegram. Avec `release_profile=full` et `rerun_group=all`, il exécute aussi l’E2E Telegram de package
|
||||
contre l’artefact `release-package-under-test` issu des vérifications de release. Fournissez `npm_telegram_package_spec` après publication lorsque le même
|
||||
E2E Telegram doit aussi prouver le package npm publié. Fournissez
|
||||
`package_acceptance_package_spec` après publication lorsque Package Acceptance
|
||||
doit exécuter sa matrice package/mise à jour contre le package npm livré au lieu
|
||||
de l’artefact construit depuis le SHA. Fournissez
|
||||
`evidence_package_spec` lorsque le rapport privé de preuves doit démontrer que la
|
||||
validation correspond à un package npm publié sans forcer l’E2E Telegram.
|
||||
Exemple :
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- Exécutez le workflow manuel `Package Acceptance` lorsque vous voulez une preuve latérale pour un candidat de paquet pendant que le travail de release continue. Utilisez `source=npm` pour `openclaw@beta`, `openclaw@latest` ou une version de release exacte ; `source=ref` pour empaqueter une branche/un tag/un SHA `package_ref` fiable avec le harnais `workflow_ref` actuel ; `source=url` pour une archive tar HTTPS avec un SHA-256 requis ; ou `source=artifact` pour une archive tar téléversée par une autre exécution GitHub Actions. Le workflow résout le candidat en `package-under-test`, réutilise le planificateur de release Docker E2E contre cette archive tar, et peut exécuter la QA Telegram contre la même archive tar avec `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Lorsque les lanes Docker sélectionnées incluent `published-upgrade-survivor`, l’artefact de paquet est le candidat et `published_upgrade_survivor_baseline` sélectionne la base publiée.
|
||||
- Exécutez le workflow manuel `Package Acceptance` lorsque vous voulez une preuve par canal latéral
|
||||
pour un candidat package pendant que le travail de release continue. Utilisez `source=npm` pour
|
||||
`openclaw@beta`, `openclaw@latest` ou une version de release exacte ; `source=ref`
|
||||
pour empaqueter une branche/balise/SHA `package_ref` de confiance avec le harnais
|
||||
`workflow_ref` actuel ; `source=url` pour une archive tar HTTPS avec un
|
||||
SHA-256 requis ; ou `source=artifact` pour une archive tar téléversée par un autre run GitHub
|
||||
Actions. Le workflow résout le candidat en
|
||||
`package-under-test`, réutilise le planificateur de release Docker E2E contre cette
|
||||
archive tar, et peut exécuter la QA Telegram contre la même archive tar avec
|
||||
`telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Lorsque les
|
||||
voies Docker sélectionnées incluent `published-upgrade-survivor`, l’artefact package
|
||||
est le candidat et `published_upgrade_survivor_baseline` sélectionne
|
||||
la base publiée.
|
||||
Exemple : `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
Profils courants :
|
||||
- `smoke` : lanes d’installation/canal/agent, réseau Gateway et rechargement de configuration
|
||||
- `package` : lanes paquet/mise à jour/Plugin natives de l’artefact sans OpenWebUI ni ClawHub live
|
||||
- `product` : profil package plus canaux MCP, nettoyage cron/sous-agent, recherche web OpenAI et OpenWebUI
|
||||
- `full` : segments de chemin de release Docker avec OpenWebUI
|
||||
- `smoke` : voies installation/canal/agent, réseau Gateway et rechargement de config
|
||||
- `package` : voies package/mise à jour/Plugin natives de l’artefact, sans OpenWebUI ni ClawHub live
|
||||
- `product` : profil package plus canaux MCP, nettoyage cron/sous-agent,
|
||||
recherche web OpenAI et OpenWebUI
|
||||
- `full` : fragments de chemin de release Docker avec OpenWebUI
|
||||
- `custom` : sélection exacte de `docker_lanes` pour une réexécution ciblée
|
||||
- Exécutez directement le workflow manuel `CI` lorsque vous avez seulement besoin d’une couverture CI normale complète pour le candidat de release. Les déclenchements CI manuels contournent la portée basée sur les changements et forcent les shards Linux Node, les shards de plugins groupés, les contrats de canal, la compatibilité Node 22, `check`, `check-additional`, le smoke de build, les contrôles docs, les skills Python, Windows, macOS, Android et les lanes i18n Control UI.
|
||||
- Exécutez directement le workflow manuel `CI` lorsque vous avez seulement besoin de la couverture CI normale complète
|
||||
pour le candidat de release. Les déclenchements CI manuels contournent la portée par changements
|
||||
et forcent les shards Linux Node, les shards de Plugin groupé, les contrats de canal,
|
||||
la compatibilité Node 22, `check`, `check-additional`, la fumée de build,
|
||||
les vérifications docs, les Skills Python, Windows, macOS, Android et les voies i18n Control UI.
|
||||
Exemple : `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- Exécutez `pnpm qa:otel:smoke` lors de la validation de la télémétrie de release. Il exerce QA-lab via un récepteur OTLP/HTTP local et vérifie les noms des spans de trace exportés, les attributs bornés et la rédaction du contenu/des identifiants sans nécessiter Opik, Langfuse ni un autre collecteur externe.
|
||||
- Exécutez `pnpm release:check` avant chaque release taguée
|
||||
- Exécutez `OpenClaw Release Publish` pour la séquence de publication modifiante après l’existence du tag. Déclenchez-le depuis `release/YYYY.M.D` (ou `main` lors de la publication d’un tag atteignable depuis main), transmettez le tag de release et le `preflight_run_id` npm OpenClaw réussi, et conservez la portée de publication Plugin par défaut `all-publishable` sauf si vous exécutez délibérément une réparation ciblée. Le workflow sérialise la publication npm des plugins, la publication ClawHub des plugins et la publication npm d’OpenClaw afin que le paquet cœur ne soit pas publié avant ses plugins externalisés.
|
||||
- Les contrôles de release s’exécutent maintenant dans un workflow manuel séparé :
|
||||
- Exécutez `pnpm qa:otel:smoke` lors de la validation de la télémétrie de release. Cette commande exerce
|
||||
QA-lab via un récepteur OTLP/HTTP local et vérifie les noms de spans de trace exportés,
|
||||
les attributs bornés et la rédaction du contenu/des identifiants sans
|
||||
nécessiter Opik, Langfuse ou un autre collecteur externe.
|
||||
- Exécutez `pnpm release:check` avant chaque release balisée
|
||||
- Exécutez `OpenClaw Release Publish` pour la séquence de publication mutante après que la
|
||||
balise existe. Déclenchez-la depuis `release/YYYY.M.D` (ou `main` lors de la publication d’une
|
||||
balise accessible depuis main), transmettez la balise de release et le
|
||||
`preflight_run_id` npm OpenClaw réussi, et gardez la portée de publication Plugin par défaut
|
||||
`all-publishable` sauf si vous exécutez délibérément une réparation ciblée. Le
|
||||
workflow sérialise la publication npm Plugin, la publication ClawHub Plugin et la publication npm OpenClaw,
|
||||
afin que le package cœur ne soit pas publié avant ses
|
||||
plugins externalisés.
|
||||
- Les vérifications de release s’exécutent désormais dans un workflow manuel séparé :
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` exécute aussi la lane de parité mock QA Lab ainsi que le profil Matrix live rapide et la lane QA Telegram avant l’approbation de release. Les lanes live utilisent l’environnement `qa-live-shared` ; Telegram utilise aussi les baux d’identifiants Convex CI. Exécutez le workflow manuel `QA-Lab - All Lanes` avec `matrix_profile=all` et `matrix_shards=true` lorsque vous voulez l’inventaire complet du transport Matrix, des médias et de l’E2EE en parallèle.
|
||||
- La validation d’installation et de mise à niveau cross-OS fait partie des workflows publics `OpenClaw Release Checks` et `Full Release Validation`, qui appellent directement le workflow réutilisable `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Cette séparation est intentionnelle : garder le vrai chemin de release npm court, déterministe et centré sur les artefacts, tandis que les contrôles live plus lents restent dans leur propre lane pour ne pas retarder ni bloquer la publication
|
||||
- Les contrôles de release contenant des secrets doivent être déclenchés via `Full Release Validation` ou depuis la référence de workflow `main`/release afin que la logique du workflow et les secrets restent contrôlés
|
||||
- `OpenClaw Release Checks` accepte une branche, un tag ou un SHA de commit complet tant que le commit résolu est atteignable depuis une branche OpenClaw ou un tag de release
|
||||
- La préparation de validation seule `OpenClaw NPM Release` accepte aussi le SHA de commit complet de 40 caractères de la branche de workflow actuelle sans exiger de tag poussé
|
||||
- Ce chemin SHA est uniquement destiné à la validation et ne peut pas être promu en vraie publication
|
||||
- En mode SHA, le workflow synthétise `v<package.json version>` uniquement pour le contrôle des métadonnées de paquet ; la vraie publication exige toujours un vrai tag de release
|
||||
- Les deux workflows conservent le vrai chemin de publication et de promotion sur les runners hébergés par GitHub, tandis que le chemin de validation non modifiant peut utiliser les runners Linux Blacksmith plus grands
|
||||
- `OpenClaw Release Checks` exécute aussi la voie de parité mock QA Lab ainsi que le profil Matrix live rapide
|
||||
et la voie QA Telegram avant l’approbation de release. Les voies live
|
||||
utilisent l’environnement `qa-live-shared` ; Telegram utilise aussi les baux d’identifiants Convex CI.
|
||||
Exécutez le workflow manuel `QA-Lab - All Lanes` avec
|
||||
`matrix_profile=all` et `matrix_shards=true` lorsque vous voulez l’inventaire complet Matrix
|
||||
transport, média et E2EE en parallèle.
|
||||
- La validation runtime d’installation et de mise à niveau multi-OS fait partie des workflows publics
|
||||
`OpenClaw Release Checks` et `Full Release Validation`, qui appellent directement le
|
||||
workflow réutilisable
|
||||
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Cette séparation est intentionnelle : garder le vrai chemin de release npm court,
|
||||
déterministe et centré sur les artefacts, tandis que les vérifications live plus lentes restent dans leur
|
||||
propre voie afin de ne pas retarder ou bloquer la publication
|
||||
- Les vérifications de release portant des secrets doivent être déclenchées via `Full Release
|
||||
Validation` ou depuis la réf de workflow `main`/release afin que la logique de workflow et les
|
||||
secrets restent contrôlés
|
||||
- `OpenClaw Release Checks` accepte une branche, une balise ou un SHA de commit complet tant que
|
||||
le commit résolu est accessible depuis une branche OpenClaw ou une balise de release
|
||||
- La prévalidation en validation seule `OpenClaw NPM Release` accepte aussi le SHA complet actuel
|
||||
de 40 caractères du commit de branche de workflow sans exiger de balise poussée
|
||||
- Ce chemin SHA sert uniquement à la validation et ne peut pas être promu en vraie publication
|
||||
- En mode SHA, le workflow synthétise `v<package.json version>` uniquement pour la
|
||||
vérification des métadonnées de package ; la vraie publication exige toujours une vraie balise de release
|
||||
- Les deux workflows gardent le vrai chemin de publication et de promotion sur des runners hébergés par GitHub,
|
||||
tandis que le chemin de validation non mutant peut utiliser les runners Linux Blacksmith plus grands
|
||||
- Ce workflow exécute
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
en utilisant les secrets de workflow `OPENAI_API_KEY` et `ANTHROPIC_API_KEY`
|
||||
- La préparation de release npm n’attend plus la lane séparée des contrôles de release
|
||||
en utilisant les deux secrets de workflow `OPENAI_API_KEY` et `ANTHROPIC_API_KEY`
|
||||
- La prévalidation de release npm n’attend plus la voie séparée des vérifications de release
|
||||
- Exécutez `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(ou le tag beta/correction correspondant) avant l’approbation
|
||||
(ou la balise beta/correction correspondante) avant l’approbation
|
||||
- Après la publication npm, exécutez
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(ou la version beta/correction correspondante) pour vérifier le chemin d’installation du registre publié dans un nouveau préfixe temporaire
|
||||
(ou la version beta/correction correspondante) pour vérifier le chemin d’installation du registre publié
|
||||
dans un préfixe temporaire frais
|
||||
- Après une publication beta, exécutez `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
|
||||
pour vérifier l’onboarding du paquet installé, la configuration Telegram et le vrai E2E Telegram contre le paquet npm publié en utilisant le pool partagé d’identifiants Telegram loués. Les exécutions ponctuelles locales des mainteneurs peuvent omettre les variables Convex et transmettre directement les trois identifiants d’environnement `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Les mainteneurs peuvent exécuter le même contrôle post-publication depuis GitHub Actions via le workflow manuel `NPM Telegram Beta E2E`. Il est intentionnellement uniquement manuel et ne s’exécute pas à chaque merge.
|
||||
- L’automatisation de release des mainteneurs utilise maintenant préparation puis promotion :
|
||||
pour vérifier l’onboarding du package installé, la configuration Telegram et l’E2E Telegram réel
|
||||
contre le package npm publié en utilisant le pool partagé d’identifiants Telegram loués.
|
||||
Les exécutions ponctuelles locales par les mainteneurs peuvent omettre les vars Convex et transmettre directement les trois
|
||||
identifiants d’env `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Pour exécuter la fumée beta post-publication complète depuis une machine de mainteneur, utilisez `pnpm release:beta-smoke -- --beta betaN`. L’assistant exécute la validation Parallels de mise à jour npm/cible fraîche, déclenche `NPM Telegram Beta E2E`, interroge le run de workflow exact, télécharge l’artefact et imprime le rapport Telegram.
|
||||
- Les mainteneurs peuvent exécuter la même vérification post-publication depuis GitHub Actions via le
|
||||
workflow manuel `NPM Telegram Beta E2E`. Il est intentionnellement uniquement manuel et
|
||||
ne s’exécute pas à chaque merge.
|
||||
- L’automatisation de release des mainteneurs utilise désormais prévalidation puis promotion :
|
||||
- la vraie publication npm doit passer un `preflight_run_id` npm réussi
|
||||
- la vraie publication npm doit être déclenchée depuis la même branche `main` ou `release/YYYY.M.D` que l’exécution de préparation réussie
|
||||
- les releases npm stables ciblent par défaut `beta`
|
||||
- la vraie publication npm doit être déclenchée depuis la même branche `main` ou
|
||||
`release/YYYY.M.D` que le run de prévalidation réussi
|
||||
- les releases npm stables ciblent `beta` par défaut
|
||||
- la publication npm stable peut cibler explicitement `latest` via l’entrée de workflow
|
||||
- la mutation de dist-tag npm basée sur un token vit désormais dans `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` pour des raisons de sécurité, car `npm dist-tag add` nécessite toujours `NPM_TOKEN` tandis que le dépôt public conserve une publication uniquement OIDC
|
||||
- la release publique `macOS Release` est uniquement de validation ; lorsqu’un tag n’existe que sur une branche de release mais que le workflow est déclenché depuis `main`, définissez `public_release_branch=release/YYYY.M.D`
|
||||
- la vraie publication mac privée doit passer un `preflight_run_id` mac privé et un `validate_run_id` réussis
|
||||
- la mutation de dist-tag npm basée sur jeton vit désormais dans
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
pour la sécurité, car `npm dist-tag add` nécessite toujours `NPM_TOKEN` alors que le
|
||||
dépôt public garde une publication uniquement OIDC
|
||||
- le `macOS Release` public est uniquement de la validation ; lorsqu’une balise vit seulement sur une
|
||||
branche de release mais que le workflow est déclenché depuis `main`, définissez
|
||||
`public_release_branch=release/YYYY.M.D`
|
||||
- la vraie publication privée mac doit passer un
|
||||
`preflight_run_id` et un `validate_run_id` mac privés réussis
|
||||
- les vrais chemins de publication promeuvent les artefacts préparés au lieu de les reconstruire
|
||||
- Pour les releases de correction stables comme `YYYY.M.D-N`, le vérificateur post-publication contrôle aussi le même chemin de mise à niveau en préfixe temporaire de `YYYY.M.D` vers `YYYY.M.D-N`, afin que les corrections de release ne puissent pas laisser silencieusement d’anciennes installations globales sur la charge utile stable de base
|
||||
- La préparation de release npm échoue fermée sauf si l’archive tar contient à la fois `dist/control-ui/index.html` et une charge utile `dist/control-ui/assets/` non vide, afin d’éviter de livrer à nouveau un tableau de bord navigateur vide
|
||||
- La vérification post-publication contrôle aussi que les points d’entrée Plugin publiés et les métadonnées de paquet sont présents dans l’agencement du registre installé. Une release qui livre des charges utiles d’exécution Plugin manquantes échoue au vérificateur postpublish et ne peut pas être promue en `latest`.
|
||||
- `pnpm test:install:smoke` impose aussi le budget npm pack `unpackedSize` sur l’archive tar candidate de mise à jour, afin que l’e2e d’installation détecte les gonflements accidentels de pack avant le chemin de publication de release
|
||||
- Si le travail de release a touché la planification CI, les manifestes de timing des extensions ou les matrices de test des extensions, régénérez et relisez les sorties de matrice `plugin-prerelease-extension-shard` détenues par le planificateur depuis `.github/workflows/plugin-prerelease.yml` avant l’approbation, afin que les notes de release ne décrivent pas une disposition CI obsolète
|
||||
à nouveau
|
||||
- Pour les releases de correction stables comme `YYYY.M.D-N`, le vérificateur post-publication
|
||||
vérifie aussi le même chemin de mise à niveau avec préfixe temporaire de `YYYY.M.D` à `YYYY.M.D-N`
|
||||
afin que les corrections de release ne puissent pas laisser silencieusement d’anciennes installations globales sur le
|
||||
payload stable de base
|
||||
- La prévalidation de release npm échoue fermée sauf si l’archive tar inclut à la fois
|
||||
`dist/control-ui/index.html` et un payload `dist/control-ui/assets/` non vide
|
||||
afin de ne pas livrer à nouveau un tableau de bord navigateur vide
|
||||
- La vérification post-publication vérifie aussi que les points d’entrée Plugin publiés et
|
||||
les métadonnées de package sont présents dans l’agencement du registre installé. Une release qui
|
||||
livre des payloads runtime Plugin manquants échoue au vérificateur post-publication et
|
||||
ne peut pas être promue vers `latest`.
|
||||
- `pnpm test:install:smoke` impose aussi le budget `unpackedSize` du pack npm sur
|
||||
l’archive tar de mise à jour candidate, afin que l’e2e d’installation détecte le gonflement accidentel du pack
|
||||
avant le chemin de publication de release
|
||||
- Si le travail de release a touché la planification CI, les manifestes de timing d’extension ou
|
||||
les matrices de tests d’extension, régénérez et examinez les sorties de matrice
|
||||
`plugin-prerelease-extension-shard` détenues par le planificateur depuis
|
||||
`.github/workflows/plugin-prerelease.yml` avant l’approbation afin que les notes de release ne
|
||||
décrivent pas une disposition CI obsolète
|
||||
- La préparation d’une release macOS stable inclut aussi les surfaces de mise à jour :
|
||||
- la release GitHub doit finir avec les paquets `.zip`, `.dmg` et `.dSYM.zip`
|
||||
- la release GitHub doit finir avec les fichiers `.zip`, `.dmg` et `.dSYM.zip` empaquetés
|
||||
- `appcast.xml` sur `main` doit pointer vers le nouveau zip stable après publication
|
||||
- l’app empaquetée doit conserver un identifiant de bundle non debug, une URL de flux Sparkle non vide et un `CFBundleVersion` supérieur ou égal au plancher canonique de build Sparkle pour cette version de release
|
||||
- l’app empaquetée doit conserver un bundle id non debug, une URL de flux Sparkle
|
||||
non vide et une `CFBundleVersion` au moins égale au plancher de build Sparkle canonique
|
||||
pour cette version de release
|
||||
|
||||
## Boîtes de test de release
|
||||
|
||||
`Full Release Validation` est la manière dont les opérateurs lancent tous les tests pré-release depuis un point d’entrée unique. Pour une preuve de commit épinglé sur une branche qui évolue rapidement, utilisez l’assistant afin que chaque workflow enfant s’exécute depuis une branche temporaire fixée sur le SHA cible :
|
||||
`Full Release Validation` est la manière dont les opérateurs lancent tous les tests de pré-release depuis
|
||||
un seul point d’entrée. Pour une preuve de commit épinglé sur une branche qui avance vite, utilisez
|
||||
l’assistant afin que chaque workflow enfant s’exécute depuis une branche temporaire fixée au
|
||||
SHA cible :
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
L’assistant pousse `release-ci/<sha>-...`, déclenche `Full Release Validation` depuis cette branche avec `ref=<sha>`, vérifie que chaque `headSha` de workflow enfant correspond à la cible, puis supprime la branche temporaire. Cela évite de prouver par accident une exécution enfant plus récente de `main`.
|
||||
L’assistant pousse `release-ci/<sha>-...`, déclenche `Full Release Validation`
|
||||
depuis cette branche avec `ref=<sha>`, vérifie que chaque `headSha` de workflow enfant
|
||||
correspond à la cible, puis supprime la branche temporaire. Cela évite de prouver accidentellement un run enfant
|
||||
`main` plus récent.
|
||||
|
||||
Pour la validation d’une branche ou d’un tag de release, exécutez-la depuis la référence de workflow fiable `main` et transmettez la branche ou le tag de release comme `ref` :
|
||||
Pour la validation d’une branche ou d’une balise de release, exécutez-la depuis la réf de workflow
|
||||
`main` de confiance et transmettez la branche ou la balise de release comme `ref` :
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -187,54 +289,54 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
Le workflow résout la référence cible, déclenche manuellement `CI` avec
|
||||
Le workflow résout la ref cible, déclenche manuellement `CI` avec
|
||||
`target_ref=<release-ref>`, déclenche `OpenClaw Release Checks`, prépare un
|
||||
artefact parent `release-package-under-test` pour les vérifications côté package,
|
||||
et déclenche l’E2E Telegram autonome du package lorsque `release_profile=full`
|
||||
avec `rerun_group=all` ou lorsque `npm_telegram_package_spec` est défini.
|
||||
`OpenClaw Release Checks` lance ensuite en éventail le smoke test d’installation,
|
||||
les vérifications de version cross-OS, la couverture live/E2E Docker du chemin de
|
||||
version, Package Acceptance avec QA du package Telegram, la parité QA Lab, Matrix
|
||||
live et Telegram live. Une exécution complète n’est acceptable que lorsque le
|
||||
résumé `Full Release Validation` indique que `normal_ci` et `release_checks` ont
|
||||
réussi. En mode full/all, l’enfant `npm_telegram` doit également réussir ; hors
|
||||
artefact parent `release-package-under-test` pour les vérifications côté paquet,
|
||||
et déclenche l’E2E Telegram de paquet autonome lorsque `release_profile=full` avec
|
||||
`rerun_group=all` ou lorsque `npm_telegram_package_spec` est défini. `OpenClaw Release
|
||||
Checks` déploie ensuite en éventail le smoke test d’installation, les vérifications
|
||||
de release multiplateformes, la couverture live/E2E Docker du chemin de release,
|
||||
Package Acceptance avec la QA du paquet Telegram, la parité QA Lab, Matrix en
|
||||
direct et Telegram en direct. Une exécution complète n’est acceptable que lorsque
|
||||
le résumé `Full Release Validation` indique que `normal_ci` et `release_checks`
|
||||
ont réussi. En mode full/all, l’enfant `npm_telegram` doit aussi réussir ; hors
|
||||
full/all, il est ignoré sauf si un `npm_telegram_package_spec` publié a été
|
||||
fourni. Le résumé final du vérificateur inclut les tableaux des jobs les plus
|
||||
lents pour chaque exécution enfant, afin que le responsable de version puisse
|
||||
fourni. Le résumé final du vérificateur inclut les tableaux des tâches les plus
|
||||
lentes pour chaque exécution enfant, afin que le responsable de release puisse
|
||||
voir le chemin critique actuel sans télécharger les journaux.
|
||||
Consultez [Validation complète de version](/fr/reference/full-release-validation)
|
||||
pour la matrice complète des étapes, les noms exacts des jobs de workflow, les
|
||||
différences entre profils stable et full, les artefacts et les poignées de
|
||||
réexécution ciblée.
|
||||
Les workflows enfants sont déclenchés depuis la référence de confiance qui
|
||||
exécute `Full Release Validation`, normalement `--ref main`, même lorsque la
|
||||
référence cible `ref` pointe vers une branche ou une balise de version plus
|
||||
ancienne. Il n’existe pas d’entrée séparée de référence de workflow pour Full
|
||||
Release Validation ; choisissez le harnais de confiance en choisissant la
|
||||
référence d’exécution du workflow. N’utilisez pas `--ref main -f ref=<sha>` pour
|
||||
prouver un commit exact sur une branche `main` mouvante ; les SHA de commits
|
||||
bruts ne peuvent pas être des références de déclenchement de workflow, utilisez
|
||||
donc `pnpm ci:full-release --sha <sha>` pour créer la branche temporaire épinglée.
|
||||
Consultez [Validation complète de release](/fr/reference/full-release-validation) pour
|
||||
la matrice complète des étapes, les noms exacts des tâches de workflow, les
|
||||
différences entre les profils stable et full, les artefacts et les identifiants
|
||||
de relance ciblée.
|
||||
Les workflows enfants sont déclenchés depuis la ref approuvée qui exécute
|
||||
`Full Release Validation`, normalement `--ref main`, même lorsque la `ref` cible
|
||||
pointe vers une branche ou une balise de release plus ancienne. Il n’existe pas
|
||||
d’entrée workflow-ref séparée pour Full Release Validation ; choisissez le
|
||||
harnais approuvé en choisissant la ref d’exécution du workflow.
|
||||
N’utilisez pas `--ref main -f ref=<sha>` pour une preuve exacte de commit sur
|
||||
`main` mouvant ; les SHA de commit bruts ne peuvent pas être des refs de
|
||||
déclenchement de workflow, utilisez donc `pnpm ci:full-release --sha <sha>` pour
|
||||
créer la branche temporaire épinglée.
|
||||
|
||||
Utilisez `release_profile` pour sélectionner l’étendue live/fournisseur :
|
||||
Utilisez `release_profile` pour sélectionner l’étendue live/provider :
|
||||
|
||||
- `minimum` : chemin OpenAI/core live et Docker le plus rapide et critique pour la version
|
||||
- `stable` : minimum plus couverture stable des fournisseurs/backends pour l’approbation de version
|
||||
- `full` : stable plus couverture large des fournisseurs/médias consultatifs
|
||||
- `minimum` : chemin OpenAI/core live et Docker le plus rapide et critique pour la release
|
||||
- `stable` : minimum plus couverture stable provider/backend pour l’approbation de release
|
||||
- `full` : stable plus large couverture provider/médias consultative
|
||||
|
||||
`OpenClaw Release Checks` utilise la référence de workflow de confiance pour
|
||||
résoudre une seule fois la référence cible en tant que
|
||||
`release-package-under-test` et réutilise cet artefact dans les vérifications
|
||||
Docker du chemin de version comme dans Package Acceptance. Cela garde toutes les
|
||||
machines côté package sur les mêmes octets et évite les builds répétés de
|
||||
package. Le smoke test d’installation OpenAI cross-OS utilise
|
||||
`OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsque la variable de dépôt/organisation est
|
||||
définie, sinon `openai/gpt-5.4`, car cette voie prouve l’installation du
|
||||
package, l’onboarding, le démarrage du Gateway et un tour d’agent live, plutôt
|
||||
que de mesurer le modèle par défaut le plus lent. La matrice plus large des
|
||||
fournisseurs live reste l’endroit prévu pour la couverture propre aux modèles.
|
||||
`OpenClaw Release Checks` utilise la ref de workflow approuvée pour résoudre une
|
||||
seule fois la ref cible en tant que `release-package-under-test` et réutilise cet
|
||||
artefact dans les vérifications Docker du chemin de release et Package
|
||||
Acceptance. Cela maintient toutes les machines côté paquet sur les mêmes octets
|
||||
et évite les builds de paquet répétés.
|
||||
Le smoke test d’installation OpenAI multiplateforme utilise
|
||||
`OPENCLAW_CROSS_OS_OPENAI_MODEL` lorsque la variable repo/org est définie, sinon
|
||||
`openai/gpt-5.4`, car cette voie prouve l’installation du paquet, l’onboarding,
|
||||
le démarrage du Gateway et un tour d’agent live, plutôt que de mesurer le modèle
|
||||
par défaut le plus lent. La matrice plus large de providers live reste l’endroit
|
||||
pour la couverture propre aux modèles.
|
||||
|
||||
Utilisez ces variantes selon l’étape de version :
|
||||
Utilisez ces variantes selon l’étape de release :
|
||||
|
||||
```bash
|
||||
# Validate an unpublished release candidate branch.
|
||||
@ -264,46 +366,47 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
N’utilisez pas l’ombrelle complète comme première réexécution après un correctif
|
||||
ciblé. Si une machine échoue, utilisez le workflow enfant, le job, la voie Docker,
|
||||
le profil de package, le fournisseur de modèle ou la voie QA en échec pour la
|
||||
preuve suivante. Réexécutez l’ombrelle complète seulement lorsque le correctif a
|
||||
modifié l’orchestration partagée de la version ou a rendu obsolètes les preuves
|
||||
précédentes de toutes les machines. Le vérificateur final de l’ombrelle revérifie
|
||||
les identifiants enregistrés des exécutions de workflows enfants ; ainsi, après
|
||||
la réexécution réussie d’un workflow enfant, ne réexécutez que le job parent
|
||||
N’utilisez pas l’ombrelle complète comme première relance après un correctif
|
||||
ciblé. Si une machine échoue, utilisez le workflow enfant, la tâche, la voie
|
||||
Docker, le profil de paquet, le provider de modèle ou la voie QA en échec pour
|
||||
la preuve suivante. Relancez l’ombrelle complète uniquement lorsque le correctif
|
||||
a modifié l’orchestration partagée de release ou a rendu obsolètes les preuves
|
||||
toutes machines précédentes. Le vérificateur final de l’ombrelle revérifie les
|
||||
identifiants enregistrés des exécutions de workflows enfants ; après la relance
|
||||
réussie d’un workflow enfant, relancez uniquement la tâche parente
|
||||
`Verify full validation` en échec.
|
||||
|
||||
Pour une récupération bornée, passez `rerun_group` à l’ombrelle. `all` est la
|
||||
vraie exécution de candidat de version, `ci` exécute seulement l’enfant CI normal,
|
||||
`plugin-prerelease` exécute seulement l’enfant Plugin propre à la version,
|
||||
`release-checks` exécute toutes les machines de version, et les groupes de
|
||||
version plus étroits sont `install-smoke`, `cross-os`, `live-e2e`, `package`,
|
||||
`qa`, `qa-parity`, `qa-live` et `npm-telegram`. Les réexécutions ciblées
|
||||
`npm-telegram` nécessitent `npm_telegram_package_spec` ; les exécutions full/all
|
||||
avec `release_profile=full` utilisent l’artefact de package de release-checks.
|
||||
véritable exécution de release candidate, `ci` exécute uniquement l’enfant CI
|
||||
normal, `plugin-prerelease` exécute uniquement l’enfant Plugin réservé à la
|
||||
release, `release-checks` exécute toutes les machines de release, et les groupes
|
||||
de release plus étroits sont `install-smoke`, `cross-os`, `live-e2e`, `package`,
|
||||
`qa`, `qa-parity`, `qa-live` et `npm-telegram`.
|
||||
Les relances ciblées `npm-telegram` nécessitent `npm_telegram_package_spec` ; les
|
||||
exécutions full/all avec `release_profile=full` utilisent l’artefact de paquet
|
||||
release-checks.
|
||||
|
||||
### Vitest
|
||||
|
||||
La machine Vitest est le workflow enfant manuel `CI`. Le CI manuel contourne
|
||||
intentionnellement le périmètre des changements et force le graphe de tests
|
||||
normal pour le candidat de version : shards Linux Node, shards de plugins
|
||||
intégrés, contrats de canaux, compatibilité Node 22, `check`, `check-additional`,
|
||||
smoke test de build, vérifications de documentation, Skills Python, Windows,
|
||||
macOS, Android et i18n de Control UI.
|
||||
La machine Vitest est le workflow enfant manuel `CI`. La CI manuelle contourne
|
||||
intentionnellement le périmétrage des changements et force le graphe de tests
|
||||
normal pour la release candidate : shards Linux Node, shards de plugins groupés,
|
||||
contrats de canaux, compatibilité Node 22, `check`, `check-additional`, smoke
|
||||
test de build, vérifications de docs, Skills Python, Windows, macOS, Android et
|
||||
i18n Control UI.
|
||||
|
||||
Utilisez cette machine pour répondre à « l’arbre source a-t-il passé toute la
|
||||
suite de tests normale ? ». Ce n’est pas la même chose que la validation produit
|
||||
du chemin de version. Preuves à conserver :
|
||||
Utilisez cette machine pour répondre à « l’arborescence source a-t-elle réussi
|
||||
la suite de tests normale complète ? ». Ce n’est pas la même chose que la
|
||||
validation produit du chemin de release. Preuves à conserver :
|
||||
|
||||
- résumé `Full Release Validation` indiquant l’URL de l’exécution `CI` déclenchée
|
||||
- exécution `CI` verte sur le SHA cible exact
|
||||
- noms des shards échoués ou lents des jobs CI lors de l’investigation de régressions
|
||||
- noms des shards en échec ou lents des tâches CI lors de l’analyse de régressions
|
||||
- artefacts de chronométrage Vitest comme `.artifacts/vitest-shard-timings.json` lorsqu’une exécution nécessite une analyse de performance
|
||||
|
||||
Exécutez le CI manuel directement seulement lorsque la version nécessite un CI
|
||||
normal déterministe, mais pas les machines Docker, QA Lab, live, cross-OS ou
|
||||
package :
|
||||
Exécutez la CI manuelle directement uniquement lorsque la release a besoin d’une
|
||||
CI normale déterministe, mais pas des machines Docker, QA Lab, live,
|
||||
multiplateformes ou de paquet :
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -313,115 +416,114 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
La machine Docker se trouve dans `OpenClaw Release Checks` via
|
||||
`openclaw-live-and-e2e-checks-reusable.yml`, plus le workflow `install-smoke` en
|
||||
mode version. Elle valide le candidat de version au moyen d’environnements Docker
|
||||
packagés, et pas seulement de tests au niveau source.
|
||||
mode release. Elle valide la release candidate via des environnements Docker
|
||||
empaquetés au lieu de se limiter aux tests au niveau source.
|
||||
|
||||
La couverture Docker de version inclut :
|
||||
La couverture Docker de release inclut :
|
||||
|
||||
- smoke test d’installation complet avec le smoke test lent d’installation globale Bun activé
|
||||
- préparation/réutilisation de l’image de smoke test du Dockerfile racine par SHA cible, avec les jobs QR, racine/Gateway et smoke installer/Bun exécutés comme shards install-smoke séparés
|
||||
- préparation/réutilisation de l’image de smoke test du Dockerfile racine par SHA cible, avec les tâches de smoke test QR, root/gateway et installer/Bun exécutées comme shards install-smoke séparés
|
||||
- voies E2E du dépôt
|
||||
- morceaux Docker du chemin de version : `core`, `package-update-openai`,
|
||||
- fragments Docker du chemin de release : `core`, `package-update-openai`,
|
||||
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
|
||||
`plugins-runtime-services`,
|
||||
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
|
||||
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
|
||||
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
|
||||
`plugins-runtime-install-g` et `plugins-runtime-install-h`
|
||||
- couverture OpenWebUI dans le morceau `plugins-runtime-services` lorsqu’elle est demandée
|
||||
- voies séparées d’installation/désinstallation des plugins intégrés
|
||||
- couverture OpenWebUI dans le fragment `plugins-runtime-services` lorsque demandé
|
||||
- voies d’installation/désinstallation de plugins groupés séparées
|
||||
`bundled-plugin-install-uninstall-0` à
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- suites fournisseurs live/E2E et couverture des modèles live Docker lorsque les vérifications de version incluent les suites live
|
||||
- suites providers live/E2E et couverture de modèles live Docker lorsque les vérifications de release incluent les suites live
|
||||
|
||||
Utilisez les artefacts Docker avant de réexécuter. Le planificateur du chemin de
|
||||
version téléverse `.artifacts/docker-tests/` avec les journaux de voies,
|
||||
`summary.json`, `failures.json`, les chronométrages de phase, le JSON du plan du
|
||||
planificateur et les commandes de réexécution. Pour une récupération ciblée,
|
||||
Utilisez les artefacts Docker avant de relancer. Le planificateur du chemin de
|
||||
release téléverse `.artifacts/docker-tests/` avec les journaux de voies,
|
||||
`summary.json`, `failures.json`, les chronométrages de phases, le JSON du plan
|
||||
du planificateur et les commandes de relance. Pour une récupération ciblée,
|
||||
utilisez `docker_lanes=<lane[,lane]>` sur le workflow live/E2E réutilisable au
|
||||
lieu de réexécuter tous les morceaux de version. Les commandes de réexécution
|
||||
générées incluent le `package_artifact_run_id` précédent et les entrées d’image
|
||||
Docker préparée lorsqu’elles sont disponibles, afin qu’une voie en échec puisse
|
||||
lieu de relancer tous les fragments de release. Les commandes de relance
|
||||
générées incluent l’ancien `package_artifact_run_id` et les entrées d’image
|
||||
Docker préparées lorsqu’elles sont disponibles, afin qu’une voie en échec puisse
|
||||
réutiliser le même tarball et les mêmes images GHCR.
|
||||
|
||||
### QA Lab
|
||||
|
||||
La machine QA Lab fait également partie de `OpenClaw Release Checks`. C’est la
|
||||
barrière de version pour le comportement agentique et le niveau canal, séparée
|
||||
de Vitest et de la mécanique de package Docker.
|
||||
La machine QA Lab fait aussi partie de `OpenClaw Release Checks`. C’est la porte
|
||||
de release pour le comportement agentique et le niveau canal, séparée de Vitest
|
||||
et des mécaniques de paquet Docker.
|
||||
|
||||
La couverture QA Lab de version inclut :
|
||||
La couverture QA Lab de release inclut :
|
||||
|
||||
- voie de parité simulée comparant la voie candidate OpenAI à la référence Opus 4.6 avec le pack de parité agentique
|
||||
- voie de parité mock comparant la voie candidate OpenAI à la référence Opus 4.6 avec le pack de parité agentique
|
||||
- profil QA Matrix live rapide utilisant l’environnement `qa-live-shared`
|
||||
- voie QA Telegram live utilisant les locations d’identifiants Convex CI
|
||||
- `pnpm qa:otel:smoke` lorsque la télémétrie de version nécessite une preuve locale explicite
|
||||
- voie QA Telegram live utilisant des baux d’identifiants Convex CI
|
||||
- `pnpm qa:otel:smoke` lorsque la télémétrie de release nécessite une preuve locale explicite
|
||||
|
||||
Utilisez cette machine pour répondre à « la version se comporte-t-elle
|
||||
Utilisez cette machine pour répondre à « la release se comporte-t-elle
|
||||
correctement dans les scénarios QA et les flux de canaux live ? ». Conservez les
|
||||
URL d’artefacts des voies de parité, Matrix et Telegram lors de l’approbation de
|
||||
la version. La couverture Matrix complète reste disponible comme exécution QA-Lab
|
||||
manuelle shardée, plutôt que comme voie critique par défaut pour la version.
|
||||
URL d’artefacts pour les voies parité, Matrix et Telegram lors de l’approbation
|
||||
de la release. La couverture Matrix complète reste disponible comme exécution
|
||||
QA-Lab manuelle shardée, plutôt que comme voie critique par défaut pour la
|
||||
release.
|
||||
|
||||
### Package
|
||||
### Paquet
|
||||
|
||||
La machine Package est la barrière du produit installable. Elle s’appuie sur
|
||||
La machine Paquet est la porte du produit installable. Elle s’appuie sur
|
||||
`Package Acceptance` et le résolveur
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. Le résolveur normalise un
|
||||
candidat en tarball `package-under-test` consommé par Docker E2E, valide
|
||||
l’inventaire du package, enregistre la version du package et son SHA-256, et
|
||||
garde la référence du harnais de workflow séparée de la référence source du
|
||||
package.
|
||||
candidat dans le tarball `package-under-test` consommé par Docker E2E, valide
|
||||
l’inventaire du paquet, enregistre la version du paquet et le SHA-256, et garde
|
||||
la ref du harnais de workflow séparée de la ref source du paquet.
|
||||
|
||||
Sources de candidats prises en charge :
|
||||
Sources candidates prises en charge :
|
||||
|
||||
- `source=npm` : `openclaw@beta`, `openclaw@latest` ou une version exacte de release OpenClaw
|
||||
- `source=ref` : empaqueter une branche, une balise ou un SHA de commit complet `package_ref` de confiance avec le harnais `workflow_ref` sélectionné
|
||||
- `source=url` : télécharger un `.tgz` HTTPS avec `package_sha256` obligatoire
|
||||
- `source=ref` : empaqueter une branche, balise ou SHA de commit complet `package_ref` approuvé avec le harnais `workflow_ref` sélectionné
|
||||
- `source=url` : télécharger un `.tgz` HTTPS avec `package_sha256` requis
|
||||
- `source=artifact` : réutiliser un `.tgz` téléversé par une autre exécution GitHub Actions
|
||||
|
||||
`OpenClaw Release Checks` exécute Package Acceptance avec `source=artifact`,
|
||||
l’artefact de package de version préparé, `suite_profile=custom`,
|
||||
l’artefact de paquet de release préparé, `suite_profile=custom`,
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
|
||||
`published_upgrade_survivor_scenarios=reported-issues` et
|
||||
`telegram_mode=mock-openai`. Package Acceptance garde la migration, la mise à
|
||||
jour, le nettoyage des dépendances obsolètes de Plugin, les fixtures de Plugin
|
||||
hors ligne, la mise à jour de Plugin et la QA du package Telegram contre le même
|
||||
jour, le nettoyage des dépendances de Plugin obsolètes, les fixtures de Plugin
|
||||
hors ligne, la mise à jour de Plugin et la QA du paquet Telegram sur le même
|
||||
tarball résolu. La matrice de mise à niveau couvre chaque référence stable
|
||||
publiée sur npm de `2026.4.23` à `latest` ; utilisez Package Acceptance avec
|
||||
`source=npm` pour un candidat déjà livré, ou `source=ref`/`source=artifact` pour
|
||||
un tarball npm local adossé à un SHA avant publication. C’est le remplacement
|
||||
natif GitHub de la majeure partie de la couverture package/mise à jour qui
|
||||
nécessitait auparavant Parallels. Les vérifications de version cross-OS restent
|
||||
importantes pour l’onboarding, l’installateur et le comportement de plateforme
|
||||
propres à l’OS, mais la validation produit package/mise à jour devrait préférer
|
||||
natif GitHub de la majeure partie de la couverture paquet/mise à jour qui
|
||||
nécessitait auparavant Parallels. Les vérifications de release multiplateformes
|
||||
restent importantes pour l’onboarding, l’installateur et le comportement propres
|
||||
aux OS, mais la validation produit de paquet/mise à jour devrait préférer
|
||||
Package Acceptance.
|
||||
|
||||
La checklist canonique pour la validation des mises à jour et des plugins est
|
||||
[Tester les mises à jour et les plugins](/fr/help/testing-updates-plugins).
|
||||
Utilisez-la pour décider quelle voie locale, Docker, Package Acceptance ou de
|
||||
vérification de version prouve une installation/mise à jour de Plugin, un
|
||||
nettoyage doctor ou un changement de migration de package publié. La migration
|
||||
exhaustive de mise à jour publiée depuis chaque package stable `2026.4.23+` est
|
||||
un workflow manuel `Update Migration` séparé, et ne fait pas partie du CI complet
|
||||
de version.
|
||||
Utilisez-la pour décider quelle voie locale, Docker, Package Acceptance ou
|
||||
release-check prouve un changement d’installation/mise à jour de Plugin, de
|
||||
nettoyage doctor ou de migration de paquet publié. La migration exhaustive de
|
||||
mise à jour publiée depuis chaque paquet stable `2026.4.23+` est un workflow
|
||||
manuel `Update Migration` séparé, qui ne fait pas partie de Full Release CI.
|
||||
|
||||
L’indulgence héritée de package-acceptance est intentionnellement limitée dans
|
||||
le temps. Les packages jusqu’à `2026.4.25` peuvent utiliser le chemin de
|
||||
La tolérance historique de package-acceptance est intentionnellement limitée
|
||||
dans le temps. Les paquets jusqu’à `2026.4.25` peuvent utiliser le chemin de
|
||||
compatibilité pour les lacunes de métadonnées déjà publiées sur npm : entrées
|
||||
privées d’inventaire QA absentes du tarball, `gateway install --wrapper`
|
||||
manquant, fichiers de patch manquants dans la fixture git dérivée du tarball,
|
||||
`update.channel` persistant manquant, anciens emplacements d’enregistrements
|
||||
d’installation de Plugin, persistance manquante des enregistrements
|
||||
d’installation de marketplace, et migration des métadonnées de configuration
|
||||
pendant `plugins update`. Le package `2026.4.26` publié peut émettre des
|
||||
avertissements pour les fichiers d’empreinte de métadonnées de build local déjà
|
||||
livrés. Les packages ultérieurs doivent satisfaire les contrats de package
|
||||
modernes ; ces mêmes lacunes font échouer la validation de version.
|
||||
d’inventaire QA privées absentes du tarball, `gateway install --wrapper` absent,
|
||||
fichiers de correctif absents de la fixture git dérivée du tarball,
|
||||
`update.channel` persisté absent, anciens emplacements d’enregistrement
|
||||
d’installation de Plugin, persistance d’enregistrement d’installation de
|
||||
marketplace absente, et migration de métadonnées de configuration pendant
|
||||
`plugins update`. Le paquet publié `2026.4.26` peut avertir pour les fichiers
|
||||
d’horodatage de métadonnées de build local qui ont déjà été livrés. Les paquets
|
||||
ultérieurs doivent satisfaire les contrats modernes de paquet ; ces mêmes
|
||||
lacunes font échouer la validation de release.
|
||||
|
||||
Utilisez des profils Package Acceptance plus larges lorsque la question de
|
||||
version porte sur un package réellement installable :
|
||||
release porte sur un véritable paquet installable :
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -433,26 +535,35 @@ gh workflow run package-acceptance.yml \
|
||||
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
|
||||
```
|
||||
|
||||
Profils de package courants :
|
||||
Profils de paquet courants :
|
||||
|
||||
- `smoke` : voies rapides d’installation de package/canal/agent, de réseau Gateway et de rechargement de configuration
|
||||
- `package` : contrats d’installation/mise à jour/package Plugin sans ClawHub en direct ; c’est la valeur par défaut du contrôle de version
|
||||
- `product` : `package` plus les canaux MCP, le nettoyage cron/sous-agent, la recherche web OpenAI et OpenWebUI
|
||||
- `full` : fragments de chemin de publication Docker avec OpenWebUI
|
||||
- `custom` : liste exacte `docker_lanes` pour des réexécutions ciblées
|
||||
- `smoke` : installation rapide du package/canal/agent, réseau Gateway et voies de
|
||||
rechargement de configuration
|
||||
- `package` : contrats d’installation/mise à jour/package de plugin sans ClawHub en direct ; c’est la valeur par défaut
|
||||
de la vérification de release
|
||||
- `product` : `package` plus canaux MCP, nettoyage cron/sous-agent, recherche web
|
||||
OpenAI et OpenWebUI
|
||||
- `full` : segments du chemin de release Docker avec OpenWebUI
|
||||
- `custom` : liste `docker_lanes` exacte pour des relances ciblées
|
||||
|
||||
Pour la preuve Telegram du package candidat, activez `telegram_mode=mock-openai` ou `telegram_mode=live-frontier` dans Package Acceptance. Le workflow transmet l’archive tarball `package-under-test` résolue à la voie Telegram ; le workflow Telegram autonome accepte toujours une spécification npm publiée pour les contrôles après publication.
|
||||
Pour la preuve Telegram d’un package candidat, activez `telegram_mode=mock-openai` ou
|
||||
`telegram_mode=live-frontier` sur Package Acceptance. Le workflow transmet le tarball
|
||||
`package-under-test` résolu à la voie Telegram ; le workflow Telegram autonome
|
||||
accepte toujours une spécification npm publiée pour les vérifications post-publication.
|
||||
|
||||
## Automatisation de publication de version
|
||||
## Automatisation de publication de release
|
||||
|
||||
`OpenClaw Release Publish` est le point d’entrée normal de publication avec mutation. Il orchestre les workflows de publication fiable dans l’ordre requis par la version :
|
||||
`OpenClaw Release Publish` est le point d’entrée normal de publication mutante. Il
|
||||
orchestre les workflows d’éditeur approuvé dans l’ordre requis par la release :
|
||||
|
||||
1. Extraire le tag de version et résoudre son SHA de commit.
|
||||
2. Vérifier que le tag est accessible depuis `main` ou `release/*`.
|
||||
1. Extraire le tag de release et résoudre son SHA de commit.
|
||||
2. Vérifier que le tag est atteignable depuis `main` ou `release/*`.
|
||||
3. Exécuter `pnpm plugins:sync:check`.
|
||||
4. Déclencher `Plugin NPM Release` avec `publish_scope=all-publishable` et `ref=<release-sha>`.
|
||||
5. Déclencher `Plugin ClawHub Release` avec la même portée et le même SHA.
|
||||
6. Déclencher `OpenClaw NPM Release` avec le tag de version, le dist-tag npm et le `preflight_run_id` enregistré.
|
||||
4. Déclencher `Plugin NPM Release` avec `publish_scope=all-publishable` et
|
||||
`ref=<release-sha>`.
|
||||
5. Déclencher `Plugin ClawHub Release` avec le même périmètre et le même SHA.
|
||||
6. Déclencher `OpenClaw NPM Release` avec le tag de release, le dist-tag npm et
|
||||
le `preflight_run_id` enregistré.
|
||||
|
||||
Exemple de publication bêta :
|
||||
|
||||
@ -484,57 +595,92 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=latest
|
||||
```
|
||||
|
||||
Utilisez les workflows de plus bas niveau `Plugin NPM Release` et `Plugin ClawHub Release` uniquement pour une réparation ciblée ou un travail de republication. Pour une réparation de Plugin sélectionné, transmettez `plugin_publish_scope=selected` et `plugins=@openclaw/name` à `OpenClaw Release Publish`, ou déclenchez directement le workflow enfant lorsque le package OpenClaw ne doit pas être publié.
|
||||
Utilisez les workflows de plus bas niveau `Plugin NPM Release` et `Plugin ClawHub Release`
|
||||
uniquement pour une réparation ciblée ou une republication. Pour une réparation de plugin
|
||||
sélectionné, transmettez `plugin_publish_scope=selected` et `plugins=@openclaw/name` à
|
||||
`OpenClaw Release Publish`, ou déclenchez directement le workflow enfant lorsque le
|
||||
package OpenClaw ne doit pas être publié.
|
||||
|
||||
## Entrées du workflow NPM
|
||||
|
||||
`OpenClaw NPM Release` accepte ces entrées contrôlées par l’opérateur :
|
||||
|
||||
- `tag` : tag de version requis tel que `v2026.4.2`, `v2026.4.2-1` ou `v2026.4.2-beta.1` ; lorsque `preflight_only=true`, il peut aussi s’agir du SHA de commit complet à 40 caractères de la branche de workflow actuelle pour un précontrôle uniquement de validation
|
||||
- `preflight_only` : `true` pour la validation/construction/package uniquement, `false` pour le vrai chemin de publication
|
||||
- `preflight_run_id` : requis sur le vrai chemin de publication afin que le workflow réutilise l’archive tarball préparée depuis l’exécution de précontrôle réussie
|
||||
- `npm_dist_tag` : tag npm cible pour le chemin de publication ; valeur par défaut `beta`
|
||||
- `tag` : tag de release requis, comme `v2026.4.2`, `v2026.4.2-1` ou
|
||||
`v2026.4.2-beta.1` ; lorsque `preflight_only=true`, il peut aussi s’agir du SHA de commit complet
|
||||
de 40 caractères de la branche de workflow actuelle pour un preflight uniquement
|
||||
de validation
|
||||
- `preflight_only` : `true` pour validation/build/package uniquement, `false` pour le
|
||||
véritable chemin de publication
|
||||
- `preflight_run_id` : requis sur le véritable chemin de publication afin que le workflow réutilise
|
||||
le tarball préparé par l’exécution de preflight réussie
|
||||
- `npm_dist_tag` : tag npm cible pour le chemin de publication ; vaut `beta` par défaut
|
||||
|
||||
`OpenClaw Release Publish` accepte ces entrées contrôlées par l’opérateur :
|
||||
|
||||
- `tag` : tag de version requis ; il doit déjà exister
|
||||
- `preflight_run_id` : identifiant d’exécution de précontrôle `OpenClaw NPM Release` réussi ; requis lorsque `publish_openclaw_npm=true`
|
||||
- `tag` : tag de release requis ; doit déjà exister
|
||||
- `preflight_run_id` : identifiant d’exécution de preflight `OpenClaw NPM Release` réussi ;
|
||||
requis lorsque `publish_openclaw_npm=true`
|
||||
- `npm_dist_tag` : tag npm cible pour le package OpenClaw
|
||||
- `plugin_publish_scope` : valeur par défaut `all-publishable` ; utilisez `selected` uniquement pour un travail de réparation ciblé
|
||||
- `plugins` : noms de packages `@openclaw/*` séparés par des virgules lorsque `plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm` : valeur par défaut `true` ; définissez `false` uniquement lorsque vous utilisez le workflow comme orchestrateur de réparation limité aux Plugins
|
||||
- `plugin_publish_scope` : vaut `all-publishable` par défaut ; utilisez `selected` uniquement
|
||||
pour une réparation ciblée
|
||||
- `plugins` : noms de packages `@openclaw/*` séparés par des virgules lorsque
|
||||
`plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm` : vaut `true` par défaut ; définissez `false` uniquement lorsque vous utilisez le
|
||||
workflow comme orchestrateur de réparation limitée aux plugins
|
||||
|
||||
`OpenClaw Release Checks` accepte ces entrées contrôlées par l’opérateur :
|
||||
|
||||
- `ref` : branche, tag ou SHA de commit complet à valider. Les contrôles contenant des secrets exigent que le commit résolu soit accessible depuis une branche OpenClaw ou un tag de version.
|
||||
- `ref` : branche, tag ou SHA de commit complet à valider. Les vérifications portant des secrets
|
||||
exigent que le commit résolu soit atteignable depuis une branche OpenClaw ou un
|
||||
tag de release.
|
||||
|
||||
Règles :
|
||||
|
||||
- Les tags stables et de correction peuvent publier vers `beta` ou `latest`
|
||||
- Les tags de préversion bêta peuvent publier uniquement vers `beta`
|
||||
- Pour `OpenClaw NPM Release`, l’entrée SHA de commit complet est autorisée uniquement lorsque `preflight_only=true`
|
||||
- `OpenClaw Release Checks` et `Full Release Validation` sont toujours uniquement de validation
|
||||
- Le vrai chemin de publication doit utiliser le même `npm_dist_tag` que celui utilisé pendant le précontrôle ; le workflow vérifie ces métadonnées avant de poursuivre la publication
|
||||
- Les tags de prérelease bêta ne peuvent publier que vers `beta`
|
||||
- Pour `OpenClaw NPM Release`, l’entrée SHA de commit complet n’est autorisée que lorsque
|
||||
`preflight_only=true`
|
||||
- `OpenClaw Release Checks` et `Full Release Validation` sont toujours
|
||||
uniquement de validation
|
||||
- Le véritable chemin de publication doit utiliser le même `npm_dist_tag` que celui utilisé pendant le preflight ;
|
||||
le workflow vérifie ces métadonnées avant de poursuivre la publication
|
||||
|
||||
## Séquence de version npm stable
|
||||
## Séquence de release npm stable
|
||||
|
||||
Lors de la préparation d’une version npm stable :
|
||||
Lors de la préparation d’une release npm stable :
|
||||
|
||||
1. Exécutez `OpenClaw NPM Release` avec `preflight_only=true`
|
||||
- Avant qu’un tag n’existe, vous pouvez utiliser le SHA de commit complet de la branche de workflow actuelle pour une répétition à blanc du workflow de précontrôle, uniquement de validation
|
||||
2. Choisissez `npm_dist_tag=beta` pour le flux normal bêta d’abord, ou `latest` uniquement lorsque vous souhaitez intentionnellement une publication stable directe
|
||||
3. Exécutez `Full Release Validation` sur la branche de version, le tag de version ou le SHA de commit complet lorsque vous voulez la CI normale plus la couverture du cache d’invites en direct, de Docker, de QA Lab, de Matrix et de Telegram depuis un seul workflow manuel
|
||||
4. Si vous n’avez intentionnellement besoin que du graphe de tests normal déterministe, exécutez plutôt le workflow manuel `CI` sur la ref de version
|
||||
- Avant qu’un tag existe, vous pouvez utiliser le SHA de commit complet de la branche de workflow
|
||||
actuelle pour un essai à blanc uniquement de validation du workflow de preflight
|
||||
2. Choisissez `npm_dist_tag=beta` pour le flux normal bêta d’abord, ou `latest` uniquement
|
||||
lorsque vous voulez intentionnellement une publication stable directe
|
||||
3. Exécutez `Full Release Validation` sur la branche de release, le tag de release ou le SHA de
|
||||
commit complet lorsque vous voulez la CI normale plus la couverture cache de prompt en direct,
|
||||
Docker, QA Lab, Matrix et Telegram depuis un seul workflow manuel
|
||||
4. Si vous n’avez intentionnellement besoin que du graphe de tests normal déterministe, exécutez plutôt le
|
||||
workflow manuel `CI` sur la référence de release
|
||||
5. Enregistrez le `preflight_run_id` réussi
|
||||
6. Exécutez `OpenClaw Release Publish` avec le même `tag`, le même `npm_dist_tag` et le `preflight_run_id` enregistré ; il publie les Plugins externalisés vers npm et ClawHub avant de promouvoir le package npm OpenClaw
|
||||
7. Si la version a atterri sur `beta`, utilisez le workflow privé `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` pour promouvoir cette version stable de `beta` vers `latest`
|
||||
8. Si la version a été intentionnellement publiée directement vers `latest` et que `beta` doit suivre immédiatement la même construction stable, utilisez ce même workflow privé pour faire pointer les deux dist-tags vers la version stable, ou laissez sa synchronisation planifiée d’auto-réparation déplacer `beta` plus tard
|
||||
6. Exécutez `OpenClaw Release Publish` avec le même `tag`, le même `npm_dist_tag`,
|
||||
et le `preflight_run_id` enregistré ; il publie les plugins externalisés vers npm
|
||||
et ClawHub avant de promouvoir le package npm OpenClaw
|
||||
7. Si la release a atterri sur `beta`, utilisez le workflow privé
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
pour promouvoir cette version stable de `beta` vers `latest`
|
||||
8. Si la release a intentionnellement été publiée directement vers `latest` et que `beta`
|
||||
doit suivre immédiatement le même build stable, utilisez ce même workflow privé
|
||||
pour faire pointer les deux dist-tags vers la version stable, ou laissez sa synchronisation
|
||||
auto-réparatrice planifiée déplacer `beta` plus tard
|
||||
|
||||
La mutation du dist-tag réside dans le dépôt privé pour des raisons de sécurité, car elle nécessite toujours `NPM_TOKEN`, tandis que le dépôt public conserve une publication uniquement OIDC.
|
||||
La mutation du dist-tag réside dans le dépôt privé pour des raisons de sécurité, car elle
|
||||
requiert toujours `NPM_TOKEN`, tandis que le dépôt public conserve une publication uniquement OIDC.
|
||||
|
||||
Cela permet de garder le chemin de publication directe et le chemin de promotion bêta d’abord tous deux documentés et visibles pour l’opérateur.
|
||||
Cela garde le chemin de publication directe et le chemin de promotion bêta d’abord tous deux
|
||||
documentés et visibles par l’opérateur.
|
||||
|
||||
Si un mainteneur doit revenir à l’authentification npm locale, exécutez les commandes de la CLI 1Password (`op`) uniquement dans une session tmux dédiée. N’appelez pas `op` directement depuis le shell principal de l’agent ; le garder dans tmux rend les invites, alertes et traitements OTP observables et évite les alertes hôte répétées.
|
||||
Si un mainteneur doit revenir à l’authentification npm locale, exécutez toute commande CLI
|
||||
1Password (`op`) uniquement dans une session tmux dédiée. N’appelez pas `op`
|
||||
directement depuis le shell principal de l’agent ; le conserver dans tmux rend les invites,
|
||||
alertes et la gestion OTP observables et évite les alertes hôte répétées.
|
||||
|
||||
## Références publiques
|
||||
|
||||
@ -548,8 +694,10 @@ Si un mainteneur doit revenir à l’authentification npm locale, exécutez les
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
Les mainteneurs utilisent la documentation de version privée dans [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) pour le runbook réel.
|
||||
Les mainteneurs utilisent la documentation de release privée dans
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
pour le runbook réel.
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Canaux de publication](/fr/install/development-channels)
|
||||
- [Canaux de release](/fr/install/development-channels)
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez une défense en profondeur contre les attaques SSRF et de réassociation DNS
|
||||
- Configuration d’un proxy direct externe pour le trafic d’exécution d’OpenClaw
|
||||
summary: Comment acheminer le trafic HTTP et WebSocket de l’environnement d’exécution OpenClaw via un proxy de filtrage géré par l’opérateur
|
||||
- Configuration d'un proxy direct externe pour le trafic d'exécution d'OpenClaw
|
||||
summary: Comment acheminer le trafic HTTP et WebSocket d’exécution d’OpenClaw via un proxy de filtrage géré par l’opérateur
|
||||
title: Proxy réseau
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:25:50Z"
|
||||
generated_at: "2026-05-04T07:06:16Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: cd5594324e8c6b7da51d903e98fda0feacb8970e0b15d980f7a249d6641461c9
|
||||
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Proxy réseau
|
||||
|
||||
OpenClaw peut acheminer le trafic HTTP et WebSocket d’exécution via un proxy direct géré par l’opérateur. Il s’agit d’une défense en profondeur facultative pour les déploiements qui veulent un contrôle central de la sortie réseau, une protection SSRF plus forte et une meilleure auditabilité réseau.
|
||||
OpenClaw peut router le trafic HTTP et WebSocket d’exécution via un proxy direct géré par l’opérateur. Il s’agit d’une défense en profondeur facultative pour les déploiements qui veulent un contrôle centralisé de la sortie réseau, une protection SSRF renforcée et une meilleure auditabilité réseau.
|
||||
|
||||
OpenClaw ne fournit pas, ne télécharge pas, ne démarre pas, ne configure pas et ne certifie pas de proxy. Vous exécutez la technologie de proxy adaptée à votre environnement, et OpenClaw y achemine les clients HTTP et WebSocket normaux locaux au processus.
|
||||
OpenClaw ne fournit pas, ne télécharge pas, ne démarre pas, ne configure pas et ne certifie pas de proxy. Vous exécutez la technologie de proxy adaptée à votre environnement, et OpenClaw y route les clients HTTP et WebSocket locaux au processus.
|
||||
|
||||
## Pourquoi utiliser un proxy ?
|
||||
|
||||
Un proxy donne aux opérateurs un point de contrôle réseau unique pour le trafic HTTP et WebSocket sortant. Cela peut être utile même en dehors du renforcement contre les SSRF :
|
||||
Un proxy donne aux opérateurs un point de contrôle réseau unique pour le trafic HTTP et WebSocket sortant. Cela peut être utile même en dehors du durcissement SSRF :
|
||||
|
||||
- Politique centrale : maintenir une seule politique de sortie au lieu de compter sur chaque point d’appel HTTP de l’application pour appliquer correctement les règles réseau.
|
||||
- Vérifications au moment de la connexion : évaluer la destination après la résolution DNS et juste avant que le proxy ouvre la connexion en amont.
|
||||
- Défense contre le rebinding DNS : réduire l’écart entre une vérification DNS au niveau de l’application et la connexion sortante réelle.
|
||||
- Couverture JavaScript plus large : acheminer les clients ordinaires `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch et similaires via le même chemin.
|
||||
- Politique centrale : maintenir une seule politique de sortie au lieu de compter sur chaque point d’appel HTTP applicatif pour appliquer correctement les règles réseau.
|
||||
- Vérifications à la connexion : évaluer la destination après la résolution DNS et juste avant que le proxy n’ouvre la connexion amont.
|
||||
- Défense contre le rebinding DNS : réduire l’écart entre une vérification DNS au niveau applicatif et la connexion sortante réelle.
|
||||
- Couverture JavaScript plus large : router les clients ordinaires `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch et clients similaires via le même chemin.
|
||||
- Auditabilité : journaliser les destinations autorisées et refusées à la frontière de sortie.
|
||||
- Contrôle opérationnel : appliquer des règles de destination, une segmentation réseau, des limites de débit ou des listes d’autorisation sortantes sans reconstruire OpenClaw.
|
||||
|
||||
L’acheminement par proxy est un garde-fou au niveau du processus pour la sortie HTTP et WebSocket normale. Il donne aux opérateurs un chemin fermé en cas d’échec pour acheminer les clients HTTP JavaScript pris en charge via leur propre proxy de filtrage, mais ce n’est pas un bac à sable réseau au niveau de l’OS et cela ne fait pas certifier par OpenClaw la politique de destination du proxy.
|
||||
Le routage par proxy est un garde-fou au niveau du processus pour la sortie HTTP et WebSocket normale. Il donne aux opérateurs un chemin à échec fermé pour router les clients HTTP JavaScript pris en charge via leur propre proxy de filtrage, mais ce n’est pas un bac à sable réseau au niveau du système d’exploitation et il ne fait pas certifier par OpenClaw la politique de destination du proxy.
|
||||
|
||||
## Comment OpenClaw achemine le trafic
|
||||
## Comment OpenClaw route le trafic
|
||||
|
||||
Quand `proxy.enabled=true` et qu’une URL de proxy est configurée, les processus d’exécution protégés comme `openclaw gateway run`, `openclaw node run` et `openclaw agent --local` acheminent la sortie HTTP et WebSocket normale via le proxy configuré :
|
||||
Lorsque `proxy.enabled=true` et qu’une URL de proxy est configurée, les processus d’exécution protégés tels que `openclaw gateway run`, `openclaw node run` et `openclaw agent --local` routent la sortie HTTP et WebSocket normale via le proxy configuré :
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
@ -43,27 +43,27 @@ OpenClaw process
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
Le contrat public est le comportement d’acheminement, pas les hooks Node internes utilisés pour l’implémenter. Les clients WebSocket du plan de contrôle d’OpenClaw Gateway utilisent un chemin direct étroit pour le trafic RPC Gateway en local loopback lorsque l’URL du Gateway utilise `localhost` ou une IP de loopback littérale comme `127.0.0.1` ou `[::1]`. Ce chemin du plan de contrôle doit pouvoir atteindre les Gateway en loopback même lorsque le proxy de l’opérateur bloque les destinations de loopback. Les requêtes HTTP et WebSocket d’exécution normales utilisent toujours le proxy configuré.
|
||||
Le contrat public est le comportement de routage, pas les hooks Node internes utilisés pour l’implémenter. Les clients WebSocket du plan de contrôle OpenClaw Gateway utilisent un chemin direct étroit pour le trafic RPC Gateway en local loopback lorsque l’URL du Gateway utilise `localhost` ou une adresse IP de bouclage littérale telle que `127.0.0.1` ou `[::1]`. Ce chemin du plan de contrôle doit pouvoir atteindre les Gateways de bouclage même lorsque le proxy de l’opérateur bloque les destinations de bouclage. Les requêtes HTTP et WebSocket d’exécution normales utilisent toujours le proxy configuré.
|
||||
|
||||
En interne, OpenClaw utilise deux hooks d’acheminement au niveau du processus pour cette fonctionnalité :
|
||||
En interne, OpenClaw utilise deux hooks de routage au niveau du processus pour cette fonctionnalité :
|
||||
|
||||
- L’acheminement par répartiteur Undici couvre `fetch`, les clients basés sur undici et les transports qui fournissent leur propre répartiteur undici.
|
||||
- L’acheminement `global-agent` couvre les appelants Node core `node:http` et `node:https`, y compris de nombreuses bibliothèques construites sur `http.request`, `https.request`, `http.get` et `https.get`. Le mode proxy géré force cet agent global afin que des agents HTTP Node explicites ne contournent pas accidentellement le proxy de l’opérateur.
|
||||
- Le routage du répartiteur Undici couvre `fetch`, les clients basés sur undici et les transports qui fournissent leur propre répartiteur undici.
|
||||
- Le routage `global-agent` couvre les appelants Node core `node:http` et `node:https`, y compris de nombreuses bibliothèques construites sur `http.request`, `https.request`, `http.get` et `https.get`. Le mode proxy géré force cet agent global afin que les agents HTTP Node explicites ne contournent pas accidentellement le proxy de l’opérateur.
|
||||
|
||||
Certains plugins possèdent des transports personnalisés qui nécessitent un câblage explicite du proxy même lorsqu’un acheminement au niveau du processus existe. Par exemple, le transport de l’API Bot de Telegram utilise son propre répartiteur HTTP/1 undici et respecte donc l’environnement de proxy du processus ainsi que le repli géré `OPENCLAW_PROXY_URL` dans ce chemin de transport propre au propriétaire.
|
||||
Certains plugins possèdent des transports personnalisés qui nécessitent un câblage de proxy explicite même lorsqu’un routage au niveau du processus existe. Par exemple, le transport Bot API de Telegram utilise son propre répartiteur undici HTTP/1 et respecte donc l’environnement de proxy du processus ainsi que le repli géré `OPENCLAW_PROXY_URL` dans ce chemin de transport propre à ce propriétaire.
|
||||
|
||||
L’URL du proxy elle-même doit utiliser `http://`. Les destinations HTTPS restent prises en charge via le proxy avec HTTP `CONNECT` ; cela signifie seulement qu’OpenClaw attend un écouteur de proxy direct HTTP simple comme `http://127.0.0.1:3128`.
|
||||
L’URL du proxy elle-même doit utiliser `http://`. Les destinations HTTPS restent prises en charge via le proxy avec HTTP `CONNECT` ; cela signifie seulement qu’OpenClaw attend un écouteur de proxy direct HTTP en clair tel que `http://127.0.0.1:3128`.
|
||||
|
||||
Tant que le proxy est actif, OpenClaw efface `no_proxy`, `NO_PROXY` et `GLOBAL_AGENT_NO_PROXY`. Ces listes de contournement sont basées sur la destination ; laisser `localhost` ou `127.0.0.1` à cet endroit permettrait donc à des cibles SSRF à haut risque d’éviter le proxy de filtrage.
|
||||
Pendant que le proxy est actif, OpenClaw efface `no_proxy`, `NO_PROXY` et `GLOBAL_AGENT_NO_PROXY`. Ces listes de contournement étant basées sur la destination, y laisser `localhost` ou `127.0.0.1` permettrait à des cibles SSRF à haut risque d’éviter le proxy de filtrage.
|
||||
|
||||
À l’arrêt, OpenClaw restaure l’environnement de proxy précédent et réinitialise l’état d’acheminement de processus mis en cache.
|
||||
À l’arrêt, OpenClaw restaure l’environnement de proxy précédent et réinitialise l’état de routage de processus mis en cache.
|
||||
|
||||
## Termes de proxy associés
|
||||
## Termes de proxy connexes
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl` : acheminement par proxy direct sortant pour la sortie d’exécution OpenClaw. Cette page documente cette fonctionnalité.
|
||||
- `gateway.auth.mode: "trusted-proxy"` : authentification par proxy inverse sensible à l’identité pour l’accès au Gateway. Consultez [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy` : proxy de débogage local et inspecteur de capture pour le développement et le support. Consultez [openclaw proxy](/fr/cli/proxy).
|
||||
- Paramètres de proxy propres à un canal ou à un fournisseur : remplacements propres au propriétaire pour un transport particulier. Préférez le proxy réseau géré lorsque l’objectif est un contrôle central de la sortie sur toute l’exécution.
|
||||
- `proxy.enabled` / `proxy.proxyUrl` : routage par proxy direct sortant pour la sortie d’exécution OpenClaw. Cette page documente cette fonctionnalité.
|
||||
- `gateway.auth.mode: "trusted-proxy"` : authentification par proxy inverse entrant tenant compte de l’identité pour l’accès au Gateway. Voir [Authentification par proxy approuvé](/fr/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy` : proxy de débogage local et inspecteur de capture pour le développement et le support. Voir [openclaw proxy](/fr/cli/proxy).
|
||||
- Paramètres de proxy propres à un canal ou à un fournisseur : remplacements propres au propriétaire pour un transport particulier. Préférez le proxy réseau géré lorsque l’objectif est un contrôle centralisé de la sortie sur l’ensemble de l’exécution.
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -73,13 +73,13 @@ proxy:
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Vous pouvez également fournir l’URL via l’environnement, tout en gardant `proxy.enabled=true` dans la configuration :
|
||||
Vous pouvez aussi fournir l’URL via l’environnement, tout en conservant `proxy.enabled=true` dans la configuration :
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
```
|
||||
|
||||
`proxy.proxyUrl` est prioritaire sur `OPENCLAW_PROXY_URL`.
|
||||
`proxy.proxyUrl` a priorité sur `OPENCLAW_PROXY_URL`.
|
||||
|
||||
Si `enabled=true` mais qu’aucune URL de proxy valide n’est configurée, les commandes protégées échouent au démarrage au lieu de revenir à un accès réseau direct.
|
||||
|
||||
@ -92,41 +92,41 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
Le repli d’environnement convient surtout aux exécutions au premier plan. Si vous l’utilisez avec un service installé, placez `OPENCLAW_PROXY_URL` dans l’environnement durable du service, par exemple `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, puis réinstallez le service afin que launchd, systemd ou Scheduled Tasks démarre le Gateway avec cette valeur.
|
||||
Le repli par l’environnement convient surtout aux exécutions au premier plan. Si vous l’utilisez avec un service installé, placez `OPENCLAW_PROXY_URL` dans l’environnement durable du service, par exemple `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, puis réinstallez le service afin que launchd, systemd ou Scheduled Tasks démarre le gateway avec cette valeur.
|
||||
|
||||
Pour les commandes `openclaw --container ...`, OpenClaw transmet `OPENCLAW_PROXY_URL` à la CLI enfant ciblée conteneur lorsqu’elle est définie. L’URL doit être accessible depuis l’intérieur du conteneur ; `127.0.0.1` désigne le conteneur lui-même, pas l’hôte. OpenClaw rejette les URL de proxy en loopback pour les commandes ciblées conteneur, sauf si vous remplacez explicitement cette vérification de sécurité.
|
||||
Pour les commandes `openclaw --container ...`, OpenClaw transmet `OPENCLAW_PROXY_URL` à la CLI enfant ciblant le conteneur lorsqu’elle est définie. L’URL doit être accessible depuis l’intérieur du conteneur ; `127.0.0.1` désigne le conteneur lui-même, pas l’hôte. OpenClaw rejette les URL de proxy en bouclage pour les commandes ciblant un conteneur, sauf si vous remplacez explicitement cette vérification de sécurité.
|
||||
|
||||
## Exigences du proxy
|
||||
|
||||
La politique du proxy constitue la frontière de sécurité. OpenClaw ne peut pas vérifier que le proxy bloque les bonnes cibles.
|
||||
La politique du proxy est la frontière de sécurité. OpenClaw ne peut pas vérifier que le proxy bloque les bonnes cibles.
|
||||
|
||||
Configurez le proxy pour :
|
||||
|
||||
- Se lier uniquement au loopback ou à une interface privée de confiance.
|
||||
- Restreindre l’accès afin que seul le processus, l’hôte, le conteneur ou le compte de service OpenClaw puisse l’utiliser.
|
||||
- Se lier uniquement au bouclage ou à une interface privée de confiance.
|
||||
- Restreindre l’accès afin que seuls le processus, l’hôte, le conteneur ou le compte de service OpenClaw puissent l’utiliser.
|
||||
- Résoudre lui-même les destinations et bloquer les IP de destination après la résolution DNS.
|
||||
- Appliquer la politique au moment de la connexion pour les requêtes HTTP simples comme pour les tunnels HTTPS `CONNECT`.
|
||||
- Rejeter les contournements basés sur la destination pour les plages de loopback, privées, link-local, de métadonnées, multicast, réservées ou de documentation.
|
||||
- Éviter les listes d’autorisation de noms d’hôte, sauf si vous faites pleinement confiance au chemin de résolution DNS.
|
||||
- Journaliser la destination, la décision, le statut et la raison sans journaliser les corps de requête, les en-têtes d’autorisation, les cookies ni d’autres secrets.
|
||||
- Garder la politique du proxy sous contrôle de version et examiner les changements comme une configuration sensible pour la sécurité.
|
||||
- Appliquer la politique au moment de la connexion pour les requêtes HTTP en clair comme pour les tunnels HTTPS `CONNECT`.
|
||||
- Rejeter les contournements basés sur la destination pour les plages de bouclage, privées, link-local, de métadonnées, multicast, réservées ou de documentation.
|
||||
- Éviter les listes d’autorisation de noms d’hôte sauf si vous faites entièrement confiance au chemin de résolution DNS.
|
||||
- Journaliser la destination, la décision, l’état et le motif sans journaliser les corps de requête, les en-têtes d’autorisation, les cookies ou d’autres secrets.
|
||||
- Conserver la politique du proxy sous contrôle de version et examiner les changements comme une configuration sensible pour la sécurité.
|
||||
|
||||
## Destinations bloquées recommandées
|
||||
|
||||
Utilisez cette liste de refus comme point de départ pour tout proxy direct, pare-feu ou politique de sortie.
|
||||
|
||||
La logique de classification au niveau de l’application OpenClaw se trouve dans `src/infra/net/ssrf.ts` et `src/shared/net/ip.ts`. Les hooks de parité pertinents sont `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` et la gestion intégrée de la sentinelle IPv4 pour les formes NAT64, 6to4, Teredo, ISATAP et IPv4-mapped. Ces fichiers sont des références utiles pour maintenir une politique de proxy externe, mais OpenClaw n’exporte ni n’applique automatiquement ces règles dans votre proxy.
|
||||
La logique de classification au niveau applicatif d’OpenClaw se trouve dans `src/infra/net/ssrf.ts` et `src/shared/net/ip.ts`. Les hooks de parité pertinents sont `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` et la gestion intégrée des sentinelles IPv4 pour NAT64, 6to4, Teredo, ISATAP et les formes IPv4-mapped. Ces fichiers sont des références utiles lors de la maintenance d’une politique de proxy externe, mais OpenClaw n’exporte ni n’applique automatiquement ces règles dans votre proxy.
|
||||
|
||||
| Plage ou hôte | Pourquoi bloquer |
|
||||
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
|
||||
| `::1/128` | Loopback IPv6 |
|
||||
| `0.0.0.0/8`, `::/128` | Adresses non spécifiées et de ce réseau |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Bouclage IPv4 |
|
||||
| `::1/128` | Bouclage IPv6 |
|
||||
| `0.0.0.0/8`, `::/128` | Adresses non spécifiées et du réseau courant |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Réseaux privés RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Adresses link-local et chemins courants de métadonnées cloud |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Adresses link-local et chemins de métadonnées cloud courants |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Services de métadonnées cloud |
|
||||
| `100.64.0.0/10` | Espace d’adresses partagé NAT de grade opérateur |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Plages de benchmarking |
|
||||
| `100.64.0.0/10` | Espace d’adressage partagé NAT de classe opérateur |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Plages de benchmark |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Plages à usage spécial et de documentation |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | IPv4 réservé |
|
||||
@ -136,7 +136,7 @@ La logique de classification au niveau de l’application OpenClaw se trouve dan
|
||||
| `2002::/16`, `2001::/32` | 6to4 et Teredo avec IPv4 intégrée |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv6 compatible IPv4 et IPv6 IPv4-mapped |
|
||||
|
||||
Si votre fournisseur cloud ou votre plateforme réseau documente d’autres hôtes de métadonnées ou plages réservées, ajoutez-les également.
|
||||
Si votre fournisseur cloud ou votre plateforme réseau documente des hôtes de métadonnées ou des plages réservées supplémentaires, ajoutez-les également.
|
||||
|
||||
## Validation
|
||||
|
||||
@ -146,9 +146,9 @@ Validez le proxy depuis le même hôte, conteneur ou compte de service qui exéc
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Par défaut, lorsqu’aucune destination personnalisée n’est fournie, la commande vérifie que `https://example.com/` réussit et démarre un canari temporaire en loopback que le proxy ne doit pas atteindre. La vérification refusée par défaut réussit lorsque le proxy renvoie une réponse de refus non-2xx ou bloque le canari avec un échec de transport ; elle échoue si une réponse réussie atteint le canari. Si aucun proxy n’est activé et configuré, la validation signale un problème de configuration ; utilisez `--proxy-url` pour une prévalidation ponctuelle avant de changer la configuration. Utilisez `--allowed-url` et `--denied-url` pour tester les attentes propres au déploiement. Les destinations refusées personnalisées sont fermées en cas d’échec : toute réponse HTTP signifie que la destination était accessible via le proxy, et toute erreur de transport est signalée comme non concluante, car OpenClaw ne peut pas prouver que le proxy a bloqué une origine accessible. En cas d’échec de validation, la commande se termine avec le code 1.
|
||||
Par défaut, lorsqu’aucune destination personnalisée n’est fournie, la commande vérifie que `https://example.com/` réussit et démarre un canari de bouclage temporaire que le proxy ne doit pas atteindre. La vérification refusée par défaut réussit lorsque le proxy renvoie une réponse de refus non 2xx ou bloque le canari avec une défaillance de transport ; elle échoue si une réponse réussie atteint le canari. Si aucun proxy n’est activé et configuré, la validation signale un problème de configuration ; utilisez `--proxy-url` pour une pré-vérification ponctuelle avant de modifier la configuration. Utilisez `--allowed-url` et `--denied-url` pour tester les attentes propres au déploiement. Les destinations refusées personnalisées sont à échec fermé : toute réponse HTTP signifie que la destination était accessible via le proxy, et toute erreur de transport est signalée comme non concluante, car OpenClaw ne peut pas prouver que le proxy a bloqué une origine accessible. En cas d’échec de validation, la commande se termine avec le code 1.
|
||||
|
||||
Utilisez `--json` pour l’automatisation. La sortie JSON contient le résultat global, la source effective de la configuration du proxy, les éventuelles erreurs de configuration et chaque vérification de destination. Les identifiants de l’URL du proxy sont expurgés dans la sortie texte et JSON :
|
||||
Utilisez `--json` pour l’automatisation. La sortie JSON contient le résultat global, la source effective de la configuration du proxy, toute erreur de configuration et chaque vérification de destination. Les identifiants de l’URL de proxy sont expurgés dans la sortie texte et JSON :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -178,7 +178,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
La requête publique devrait réussir. Les requêtes de bouclage et de métadonnées devraient être bloquées par le proxy. Pour `openclaw proxy validate`, le canari de bouclage intégré peut distinguer un refus du proxy d’une origine joignable. Les vérifications personnalisées `--denied-url` n’ont pas ce canari ; considérez donc les réponses HTTP comme les échecs de transport ambigus comme des échecs de validation, sauf si votre proxy expose un signal de refus propre au déploiement que vous pouvez vérifier séparément.
|
||||
La requête publique doit réussir. Les requêtes de bouclage et de métadonnées doivent être bloquées par le proxy. Pour `openclaw proxy validate`, le canari de bouclage intégré peut distinguer un refus du proxy d’une origine accessible. Les vérifications `--denied-url` personnalisées ne disposent pas de ce canari ; traitez donc les réponses HTTP comme les échecs de transport ambigus comme des échecs de validation, sauf si votre proxy expose un signal de refus propre au déploiement que vous pouvez vérifier séparément.
|
||||
|
||||
Activez ensuite le routage proxy d’OpenClaw :
|
||||
|
||||
@ -198,10 +198,11 @@ proxy:
|
||||
|
||||
## Limites
|
||||
|
||||
- Le proxy améliore la couverture pour les clients HTTP et WebSocket JavaScript locaux au processus, mais ce n’est pas un bac à sable réseau au niveau du système d’exploitation.
|
||||
- Les sockets `net`, `tls` et `http2` bruts, les addons natifs et les processus enfants peuvent contourner le routage proxy au niveau Node, sauf s’ils héritent des variables d’environnement proxy et les respectent.
|
||||
- IRC est un canal TCP/TLS brut en dehors du routage via proxy direct géré par l’opérateur. Dans les déploiements qui exigent que tout le trafic sortant passe par ce proxy direct, définissez `channels.irc.enabled=false`, sauf si le trafic IRC direct sortant est explicitement approuvé.
|
||||
- Les interfaces Web locales des utilisateurs et les serveurs de modèles locaux doivent être ajoutés à la liste d’autorisation dans la stratégie de proxy de l’opérateur lorsque nécessaire ; OpenClaw n’expose pas de contournement général du réseau local pour eux.
|
||||
- Le contournement du proxy du plan de contrôle du Gateway est volontairement limité à `localhost` et aux URL IP de bouclage littérales. Utilisez `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` pour les connexions locales directes au plan de contrôle du Gateway ; les autres noms d’hôte sont routés comme du trafic ordinaire basé sur le nom d’hôte.
|
||||
- OpenClaw n’inspecte, ne teste ni ne certifie votre stratégie de proxy.
|
||||
- Traitez les modifications de stratégie de proxy comme des changements opérationnels sensibles en matière de sécurité.
|
||||
- Le proxy améliore la couverture pour les clients HTTP JavaScript locaux au processus et WebSocket, mais ce n’est pas un bac à sable réseau au niveau du système d’exploitation.
|
||||
- Les sockets `net`, `tls` et `http2` brutes, les extensions natives et les processus enfants peuvent contourner le routage proxy au niveau de Node, sauf s’ils héritent des variables d’environnement de proxy et les respectent.
|
||||
- IRC est un canal TCP/TLS brut en dehors du routage par proxy direct géré par l’opérateur. Dans les déploiements qui exigent que toutes les sorties passent par ce proxy direct, définissez `channels.irc.enabled=false`, sauf si la sortie IRC directe est explicitement approuvée.
|
||||
- Le proxy de débogage local est un outil de diagnostic, et son transfert direct en amont pour les requêtes proxy et les tunnels CONNECT est désactivé par défaut lorsque le mode proxy géré est actif ; n’activez le transfert direct que pour des diagnostics locaux approuvés.
|
||||
- Les WebUIs locales des utilisateurs et les serveurs de modèles locaux doivent être ajoutés à la liste d’autorisation dans la politique de proxy de l’opérateur lorsque nécessaire ; OpenClaw n’expose pas de contournement général du réseau local pour eux.
|
||||
- Le contournement du proxy du plan de contrôle Gateway est volontairement limité à `localhost` et aux URL avec adresses IP de bouclage littérales. Utilisez `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` pour les connexions locales directes au plan de contrôle Gateway ; les autres noms d’hôte sont routés comme du trafic ordinaire basé sur un nom d’hôte.
|
||||
- OpenClaw n’inspecte, ne teste ni ne certifie votre politique de proxy.
|
||||
- Traitez les modifications de politique de proxy comme des changements opérationnels sensibles à la sécurité.
|
||||
|
||||
@ -1,42 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez effectuer du travail en arrière-plan ou en parallèle via l’agent
|
||||
- Vous modifiez la politique des outils sessions_spawn ou de sous-agent
|
||||
- Vous implémentez ou dépannez des sessions de sous-agent liées au fil
|
||||
- Vous souhaitez lancer un travail en arrière-plan ou en parallèle via l’agent
|
||||
- Vous modifiez sessions_spawn ou la politique de l’outil de sous-agent
|
||||
- Vous implémentez ou dépannez des sessions de sous-agents liées à un fil de discussion
|
||||
sidebarTitle: Sub-agents
|
||||
summary: Lancer des exécutions isolées d’agent en arrière-plan qui annoncent les résultats dans la conversation du demandeur
|
||||
summary: Lancer des exécutions d’agents isolées en arrière-plan qui annoncent les résultats dans la conversation du demandeur
|
||||
title: Sous-agents
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:27:12Z"
|
||||
generated_at: "2026-05-04T07:06:32Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
|
||||
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
|
||||
source_path: tools/subagents.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Les sous-agents sont des exécutions d’agent en arrière-plan lancées depuis une exécution d’agent existante.
|
||||
Ils s’exécutent dans leur propre session (`agent:<agentId>:subagent:<uuid>`) et,
|
||||
une fois terminés, **annoncent** leur résultat au canal de chat du demandeur.
|
||||
Chaque exécution de sous-agent est suivie comme une
|
||||
une fois terminés, **annoncent** leur résultat au canal de discussion du
|
||||
demandeur. Chaque exécution de sous-agent est suivie comme une
|
||||
[tâche en arrière-plan](/fr/automation/tasks).
|
||||
|
||||
Objectifs principaux :
|
||||
|
||||
- Paralléliser les travaux de « recherche / tâche longue / outil lent » sans bloquer l’exécution principale.
|
||||
- Garder les sous-agents isolés par défaut (séparation des sessions + sandboxing facultatif).
|
||||
- Garder la surface des outils difficile à mal utiliser : les sous-agents n’obtiennent **pas** les outils de session par défaut.
|
||||
- Prendre en charge une profondeur d’imbrication configurable pour les motifs d’orchestration.
|
||||
- Paralléliser le travail de « recherche / tâche longue / outil lent » sans bloquer l’exécution principale.
|
||||
- Garder les sous-agents isolés par défaut (séparation de session + sandboxing facultatif).
|
||||
- Garder la surface d’outils difficile à mal utiliser : les sous-agents n’obtiennent **pas** les outils de session par défaut.
|
||||
- Prendre en charge une profondeur d’imbrication configurable pour les schémas d’orchestration.
|
||||
|
||||
<Note>
|
||||
**Note sur les coûts :** chaque sous-agent possède par défaut son propre contexte
|
||||
et sa propre consommation de tokens. Pour les tâches lourdes ou répétitives,
|
||||
définissez un modèle moins coûteux pour les sous-agents et gardez votre agent
|
||||
principal sur un modèle de meilleure qualité. Configurez cela via
|
||||
`agents.defaults.subagents.model` ou avec des remplacements par agent. Lorsqu’un enfant
|
||||
a réellement besoin de la transcription courante du demandeur, l’agent peut demander
|
||||
`context: "fork"` pour ce lancement précis. Les sessions de sous-agent liées à un fil utilisent par défaut
|
||||
`context: "fork"` parce qu’elles dérivent la conversation courante dans un
|
||||
**Note sur les coûts :** chaque sous-agent a son propre contexte et sa propre utilisation de tokens par
|
||||
défaut. Pour les tâches lourdes ou répétitives, définissez un modèle moins coûteux pour les sous-agents
|
||||
et gardez votre agent principal sur un modèle de meilleure qualité. Configurez via
|
||||
`agents.defaults.subagents.model` ou des remplacements par agent. Lorsqu’un enfant
|
||||
a réellement besoin de la transcription actuelle du demandeur, l’agent peut demander
|
||||
`context: "fork"` sur ce lancement précis. Les sessions de sous-agent liées à un fil utilisent par défaut
|
||||
`context: "fork"` parce qu’elles dérivent la conversation actuelle dans un
|
||||
fil de suivi.
|
||||
</Note>
|
||||
|
||||
@ -55,17 +54,17 @@ actuelle** :
|
||||
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
|
||||
```
|
||||
|
||||
Utilisez la commande de niveau supérieur [`/steer <message>`](/fr/tools/steer) pour orienter l’exécution active de la session demanderesse actuelle. Utilisez `/subagents steer <id|#> <message>` lorsque la cible est une exécution enfant.
|
||||
Utilisez [`/steer <message>`](/fr/tools/steer) au niveau supérieur pour guider l’exécution active de la session actuelle du demandeur. Utilisez `/subagents steer <id|#> <message>` lorsque la cible est une exécution enfant.
|
||||
|
||||
`/subagents info` affiche les métadonnées de l’exécution (état, horodatages, identifiant de session,
|
||||
chemin de transcription, nettoyage). Utilisez `sessions_history` pour une vue de rappel bornée
|
||||
et filtrée pour la sécurité ; inspectez le chemin de transcription sur disque lorsque vous
|
||||
`/subagents info` affiche les métadonnées d’exécution (statut, horodatages, identifiant de session,
|
||||
chemin de transcription, nettoyage). Utilisez `sessions_history` pour une vue de rappel bornée et
|
||||
filtrée pour la sécurité ; inspectez le chemin de transcription sur le disque lorsque vous
|
||||
avez besoin de la transcription brute complète.
|
||||
|
||||
### Contrôles de liaison aux fils
|
||||
### Contrôles de liaison de fil
|
||||
|
||||
Ces commandes fonctionnent sur les canaux qui prennent en charge les liaisons de fil persistantes.
|
||||
Consultez [Canaux prenant en charge les fils](#thread-supporting-channels) ci-dessous.
|
||||
Voir [Canaux prenant en charge les fils](#thread-supporting-channels) ci-dessous.
|
||||
|
||||
```text
|
||||
/focus <subagent-label|session-key|session-id|session-label>
|
||||
@ -75,79 +74,80 @@ Consultez [Canaux prenant en charge les fils](#thread-supporting-channels) ci-de
|
||||
/session max-age <duration|off>
|
||||
```
|
||||
|
||||
### Comportement du lancement
|
||||
### Comportement de lancement
|
||||
|
||||
`/subagents spawn` démarre un sous-agent en arrière-plan comme commande utilisateur (et non comme
|
||||
relais interne) et renvoie une seule mise à jour finale d’achèvement au
|
||||
chat du demandeur lorsque l’exécution se termine.
|
||||
relais interne) et renvoie une dernière mise à jour d’achèvement au canal de discussion du
|
||||
demandeur lorsque l’exécution se termine.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Non-blocking, push-based completion">
|
||||
- La commande de lancement est non bloquante ; elle renvoie immédiatement un identifiant d’exécution.
|
||||
- À l’achèvement, le sous-agent annonce un message de résumé/résultat au canal de chat du demandeur.
|
||||
- L’achèvement fonctionne par envoi actif. Une fois lancé, ne consultez **pas** `/subagents list`, `sessions_list` ou `sessions_history` en boucle simplement pour attendre la fin ; inspectez l’état uniquement à la demande pour le débogage ou l’intervention.
|
||||
- À l’achèvement, OpenClaw ferme au mieux les onglets/processus de navigateur suivis ouverts par cette session de sous-agent avant la poursuite du flux de nettoyage de l’annonce.
|
||||
- À l’achèvement, le sous-agent annonce un message de résumé/résultat au canal de discussion du demandeur.
|
||||
- L’achèvement est basé sur le push. Une fois lancé, ne sondez **pas** `/subagents list`, `sessions_list` ou `sessions_history` en boucle uniquement pour attendre qu’il se termine ; inspectez le statut seulement à la demande pour le débogage ou l’intervention.
|
||||
- À l’achèvement, OpenClaw ferme au mieux les onglets/processus de navigateur suivis ouverts par cette session de sous-agent avant que le flux de nettoyage de l’annonce continue.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Manual-spawn delivery resilience">
|
||||
- OpenClaw tente d’abord une remise directe `agent` avec une clé d’idempotence stable.
|
||||
- Si la remise directe échoue, il se rabat sur le routage par file.
|
||||
- OpenClaw tente d’abord une livraison directe `agent` avec une clé d’idempotence stable.
|
||||
- Si le tour d’achèvement de l’agent demandeur échoue, ne produit aucune sortie visible ou renvoie un préfixe manifestement incomplet du résultat enfant capturé, OpenClaw se rabat sur une livraison directe de l’achèvement à partir du résultat enfant capturé.
|
||||
- Si la livraison directe ne peut pas être utilisée, il se rabat sur le routage par file.
|
||||
- Si le routage par file n’est toujours pas disponible, l’annonce est retentée avec un court backoff exponentiel avant l’abandon final.
|
||||
- La remise d’achèvement conserve la route résolue du demandeur : les routes d’achèvement liées à un fil ou à une conversation l’emportent lorsqu’elles sont disponibles ; si l’origine de l’achèvement ne fournit qu’un canal, OpenClaw complète la cible/le compte manquant à partir de la route résolue de la session du demandeur (`lastChannel` / `lastTo` / `lastAccountId`) afin que la remise directe fonctionne quand même.
|
||||
- La livraison de l’achèvement conserve la route résolue du demandeur : les routes d’achèvement liées au fil ou liées à la conversation l’emportent lorsqu’elles sont disponibles ; si l’origine de l’achèvement ne fournit qu’un canal, OpenClaw renseigne la cible/le compte manquant depuis la route résolue de la session du demandeur (`lastChannel` / `lastTo` / `lastAccountId`) afin que la livraison directe fonctionne encore.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Completion handoff metadata">
|
||||
Le transfert d’achèvement vers la session demanderesse est un contexte interne
|
||||
généré à l’exécution (et non un texte rédigé par l’utilisateur) et inclut :
|
||||
Le transfert d’achèvement vers la session du demandeur est un contexte interne généré à l’exécution
|
||||
(pas un texte rédigé par l’utilisateur) et inclut :
|
||||
|
||||
- `Result` — dernier texte visible de réponse `assistant`, sinon dernier texte assaini d’outil/toolResult. Les exécutions terminales en échec ne réutilisent pas le texte de réponse capturé.
|
||||
- `Result` — dernier texte de réponse `assistant` visible, sinon dernier texte tool/toolResult nettoyé. Les exécutions terminales échouées ne réutilisent pas le texte de réponse capturé.
|
||||
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
|
||||
- Statistiques compactes d’exécution/tokens.
|
||||
- Une instruction de remise demandant à l’agent demandeur de reformuler avec une voix d’assistant normale (sans transférer les métadonnées internes brutes).
|
||||
- Une instruction de livraison indiquant à l’agent demandeur de reformuler avec une voix d’assistant normale (et non de transférer des métadonnées internes brutes).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Modes and ACP runtime">
|
||||
- `--model` et `--thinking` remplacent les valeurs par défaut pour cette exécution précise.
|
||||
- Utilisez `info`/`log` pour inspecter les détails et la sortie après l’achèvement.
|
||||
- `/subagents spawn` est un mode ponctuel (`mode: "run"`). Pour les sessions persistantes liées à un fil, utilisez `sessions_spawn` avec `thread: true` et `mode: "session"`.
|
||||
- Pour les sessions de harnais ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explicite), utilisez `sessions_spawn` avec `runtime: "acp"` lorsque l’outil annonce cet environnement d’exécution. Consultez le [modèle de remise ACP](/fr/tools/acp-agents#delivery-model) lors du débogage des achèvements ou des boucles agent-à-agent. Lorsque le Plugin `codex` est activé, le contrôle de chat/fil Codex doit préférer `/codex ...` à ACP, sauf si l’utilisateur demande explicitement ACP/acpx.
|
||||
- OpenClaw masque `runtime: "acp"` tant qu’ACP n’est pas activé, que le demandeur est sandboxé ou qu’un Plugin de backend tel que `acpx` n’est pas chargé. `runtime: "acp"` attend un identifiant de harnais ACP externe, ou une entrée `agents.list[]` avec `runtime.type="acp"` ; utilisez l’environnement d’exécution de sous-agent par défaut pour les agents de configuration OpenClaw normaux provenant de `agents_list`.
|
||||
- `/subagents spawn` est un mode à exécution unique (`mode: "run"`). Pour les sessions persistantes liées à un fil, utilisez `sessions_spawn` avec `thread: true` et `mode: "session"`.
|
||||
- Pour les sessions de harnais ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explicite), utilisez `sessions_spawn` avec `runtime: "acp"` lorsque l’outil annonce ce runtime. Voir [Modèle de livraison ACP](/fr/tools/acp-agents#delivery-model) lors du débogage des achèvements ou des boucles agent-à-agent. Lorsque le Plugin `codex` est activé, le contrôle de discussion/fil Codex doit préférer `/codex ...` à ACP, sauf si l’utilisateur demande explicitement ACP/acpx.
|
||||
- OpenClaw masque `runtime: "acp"` jusqu’à ce qu’ACP soit activé, que le demandeur ne soit pas sandboxé et qu’un Plugin backend tel que `acpx` soit chargé. `runtime: "acp"` attend un identifiant de harnais ACP externe, ou une entrée `agents.list[]` avec `runtime.type="acp"` ; utilisez le runtime de sous-agent par défaut pour les agents de configuration OpenClaw normaux issus de `agents_list`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Modes de contexte
|
||||
|
||||
Les sous-agents natifs démarrent isolés, sauf si l’appelant demande explicitement de dupliquer
|
||||
la transcription courante.
|
||||
Les sous-agents natifs démarrent isolés sauf si l’appelant demande explicitement de dupliquer
|
||||
la transcription actuelle.
|
||||
|
||||
| Mode | Quand l’utiliser | Comportement |
|
||||
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | Recherche nouvelle, implémentation indépendante, travail avec outil lent, ou tout ce qui peut être résumé dans le texte de la tâche | Crée une transcription enfant propre. C’est la valeur par défaut et elle réduit l’utilisation des tokens. |
|
||||
| `fork` | Travail qui dépend de la conversation courante, de résultats d’outils précédents ou d’instructions nuancées déjà présentes dans la transcription du demandeur | Dérive la transcription du demandeur dans la session enfant avant le démarrage de l’enfant. |
|
||||
| Mode | Quand l’utiliser | Comportement |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | Recherche nouvelle, implémentation indépendante, travail d’outil lent, ou tout ce qui peut être résumé dans le texte de la tâche | Crée une transcription enfant propre. C’est la valeur par défaut et cela réduit l’utilisation de tokens. |
|
||||
| `fork` | Travail qui dépend de la conversation actuelle, de résultats d’outils antérieurs ou d’instructions nuancées déjà présentes dans la transcription du demandeur | Dérive la transcription du demandeur dans la session enfant avant le démarrage de l’enfant. |
|
||||
|
||||
Utilisez `fork` avec parcimonie. Il est destiné à la délégation sensible au contexte, pas à
|
||||
remplacer la rédaction d’une invite de tâche claire.
|
||||
Utilisez `fork` avec parcimonie. Il est destiné à la délégation sensible au contexte, et non à
|
||||
remplacer une invite de tâche claire.
|
||||
|
||||
## Outil : `sessions_spawn`
|
||||
|
||||
Démarre une exécution de sous-agent avec `deliver: false` sur la voie globale `subagent`,
|
||||
puis exécute une étape d’annonce et publie la réponse d’annonce dans le canal de
|
||||
chat du demandeur.
|
||||
puis exécute une étape d’annonce et publie la réponse d’annonce dans le canal de discussion
|
||||
du demandeur.
|
||||
|
||||
La disponibilité dépend de la politique d’outils effective de l’appelant. Les profils `coding` et
|
||||
`full` exposent `sessions_spawn` par défaut. Le profil `messaging`
|
||||
ne le fait pas ; ajoutez `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
|
||||
"subagents"]` ou utilisez `tools.profile: "coding"` pour les agents qui doivent déléguer
|
||||
du travail. Les politiques de canal/groupe, fournisseur, sandbox et autoriser/refuser par agent peuvent
|
||||
du travail. Les politiques de canal/groupe, de fournisseur, de sandbox et les politiques allow/deny par agent peuvent
|
||||
encore retirer l’outil après l’étape de profil. Utilisez `/tools` depuis la même
|
||||
session pour confirmer la liste effective des outils.
|
||||
session pour confirmer la liste d’outils effective.
|
||||
|
||||
**Valeurs par défaut :**
|
||||
|
||||
- **Modèle :** hérite de l’appelant, sauf si vous définissez `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` par agent) ; un `sessions_spawn.model` explicite l’emporte toujours.
|
||||
- **Thinking :** hérite de l’appelant, sauf si vous définissez `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` par agent) ; un `sessions_spawn.thinking` explicite l’emporte toujours.
|
||||
- **Délai d’exécution :** si `sessions_spawn.runTimeoutSeconds` est omis, OpenClaw utilise `agents.defaults.subagents.runTimeoutSeconds` lorsqu’il est défini ; sinon, il se rabat sur `0` (aucun délai).
|
||||
- **Modèle :** hérite de l’appelant sauf si vous définissez `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` par agent) ; un `sessions_spawn.model` explicite l’emporte toujours.
|
||||
- **Thinking :** hérite de l’appelant sauf si vous définissez `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` par agent) ; un `sessions_spawn.thinking` explicite l’emporte toujours.
|
||||
- **Délai d’exécution :** si `sessions_spawn.runTimeoutSeconds` est omis, OpenClaw utilise `agents.defaults.subagents.runTimeoutSeconds` lorsqu’il est défini ; sinon, il se rabat sur `0` (pas de délai).
|
||||
|
||||
### Paramètres de l’outil
|
||||
|
||||
@ -155,31 +155,31 @@ session pour confirmer la liste effective des outils.
|
||||
La description de la tâche pour le sous-agent.
|
||||
</ParamField>
|
||||
<ParamField path="label" type="string">
|
||||
Libellé lisible par l’humain facultatif.
|
||||
Libellé facultatif lisible par l’humain.
|
||||
</ParamField>
|
||||
<ParamField path="agentId" type="string">
|
||||
Lancer sous un autre identifiant d’agent lorsque `subagents.allowAgents` l’autorise.
|
||||
</ParamField>
|
||||
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
|
||||
`acp` est uniquement destiné aux harnais ACP externes (`claude`, `droid`, `gemini`, `opencode` ou Codex ACP/acpx explicitement demandé) et aux entrées `agents.list[]` dont `runtime.type` vaut `acp`.
|
||||
`acp` est réservé aux harnais ACP externes (`claude`, `droid`, `gemini`, `opencode`, ou Codex ACP/acpx explicitement demandé) et aux entrées `agents.list[]` dont `runtime.type` vaut `acp`.
|
||||
</ParamField>
|
||||
<ParamField path="resumeSessionId" type="string">
|
||||
ACP uniquement. Reprend une session de harnais ACP existante lorsque `runtime: "acp"` ; ignoré pour les lancements de sous-agents natifs.
|
||||
ACP uniquement. Reprend une session de harnais ACP existante lorsque `runtime: "acp"` ; ignoré pour les lancements de sous-agent natifs.
|
||||
</ParamField>
|
||||
<ParamField path="streamTo" type='"parent"'>
|
||||
ACP uniquement. Diffuse la sortie d’exécution ACP vers la session parente lorsque `runtime: "acp"` ; à omettre pour les lancements de sous-agents natifs.
|
||||
ACP uniquement. Diffuse la sortie d’exécution ACP vers la session parente lorsque `runtime: "acp"` ; omettez pour les lancements de sous-agent natifs.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
Remplace le modèle du sous-agent. Les valeurs invalides sont ignorées et le sous-agent s’exécute sur le modèle par défaut, avec un avertissement dans le résultat de l’outil.
|
||||
Remplace le modèle du sous-agent. Les valeurs non valides sont ignorées et le sous-agent s’exécute sur le modèle par défaut avec un avertissement dans le résultat de l’outil.
|
||||
</ParamField>
|
||||
<ParamField path="thinking" type="string">
|
||||
Remplace le niveau de réflexion pour l’exécution du sous-agent.
|
||||
</ParamField>
|
||||
<ParamField path="runTimeoutSeconds" type="number">
|
||||
Par défaut, utilise `agents.defaults.subagents.runTimeoutSeconds` lorsqu’il est défini, sinon `0`. Lorsqu’il est défini, l’exécution du sous-agent est interrompue après N secondes.
|
||||
Vaut par défaut `agents.defaults.subagents.runTimeoutSeconds` lorsqu’il est défini, sinon `0`. Lorsqu’il est défini, l’exécution du sous-agent est interrompue après N secondes.
|
||||
</ParamField>
|
||||
<ParamField path="thread" type="boolean" default="false">
|
||||
Lorsque `true`, demande une liaison de fil de canal pour cette session de sous-agent.
|
||||
Lorsque `true`, demande la liaison de fil de canal pour cette session de sous-agent.
|
||||
</ParamField>
|
||||
<ParamField path="mode" type='"run" | "session"' default="run">
|
||||
Si `thread: true` et que `mode` est omis, la valeur par défaut devient `session`. `mode: "session"` nécessite `thread: true`.
|
||||
@ -188,15 +188,15 @@ session pour confirmer la liste effective des outils.
|
||||
`"delete"` archive immédiatement après l’annonce (conserve tout de même la transcription via renommage).
|
||||
</ParamField>
|
||||
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
|
||||
`require` rejette le lancement sauf si l’environnement d’exécution enfant cible est sandboxé.
|
||||
`require` rejette le lancement sauf si le runtime enfant cible est sandboxé.
|
||||
</ParamField>
|
||||
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
|
||||
`fork` dérive la transcription courante du demandeur dans la session enfant. Sous-agents natifs uniquement. Les lancements liés à un fil utilisent par défaut `fork` ; les lancements non liés à un fil utilisent par défaut `isolated`.
|
||||
`fork` dérive la transcription actuelle du demandeur dans la session enfant. Sous-agents natifs uniquement. Les lancements liés à un fil utilisent par défaut `fork` ; les lancements non liés à un fil utilisent par défaut `isolated`.
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
`sessions_spawn` n’accepte **pas** les paramètres de remise par canal (`target`,
|
||||
`channel`, `to`, `threadId`, `replyTo`, `transport`). Pour la remise, utilisez
|
||||
`sessions_spawn` n’accepte **pas** les paramètres de livraison par canal (`target`,
|
||||
`channel`, `to`, `threadId`, `replyTo`, `transport`). Pour la livraison, utilisez
|
||||
`message`/`sessions_send` depuis l’exécution lancée.
|
||||
</Warning>
|
||||
|
||||
@ -220,20 +220,20 @@ les sessions de sous-agent persistantes liées à un fil (`sessions_spawn` avec
|
||||
### Flux rapide
|
||||
|
||||
<Steps>
|
||||
<Step title="Spawn">
|
||||
`sessions_spawn` avec `thread: true` (et facultativement `mode: "session"`).
|
||||
<Step title="Créer">
|
||||
`sessions_spawn` avec `thread: true` (et éventuellement `mode: "session"`).
|
||||
</Step>
|
||||
<Step title="Bind">
|
||||
<Step title="Lier">
|
||||
OpenClaw crée ou lie un fil à cette cible de session dans le canal actif.
|
||||
</Step>
|
||||
<Step title="Route follow-ups">
|
||||
Les réponses et messages de suivi dans ce fil sont routés vers la session liée.
|
||||
<Step title="Acheminer les suivis">
|
||||
Les réponses et messages de suivi dans ce fil sont acheminés vers la session liée.
|
||||
</Step>
|
||||
<Step title="Inspect timeouts">
|
||||
Utilisez `/session idle` pour inspecter/mettre à jour le défocus automatique en cas d’inactivité et
|
||||
<Step title="Inspecter les délais d’expiration">
|
||||
Utilisez `/session idle` pour inspecter/mettre à jour le désancrage automatique après inactivité et
|
||||
`/session max-age` pour contrôler la limite stricte.
|
||||
</Step>
|
||||
<Step title="Detach">
|
||||
<Step title="Détacher">
|
||||
Utilisez `/unfocus` pour détacher manuellement.
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -242,68 +242,68 @@ les sessions de sous-agent persistantes liées à un fil (`sessions_spawn` avec
|
||||
|
||||
| Commande | Effet |
|
||||
| ------------------ | --------------------------------------------------------------------- |
|
||||
| `/focus <target>` | Associe le fil actuel (ou en crée un) à une cible de sous-agent/session |
|
||||
| `/unfocus` | Supprime l’association pour le fil actuellement associé |
|
||||
| `/agents` | Liste les exécutions actives et l’état d’association (`thread:<id>` ou `unbound`) |
|
||||
| `/session idle` | Inspecte/met à jour la désactivation automatique de focus en cas d’inactivité (fils associés avec focus uniquement) |
|
||||
| `/session max-age` | Inspecte/met à jour la limite stricte (fils associés avec focus uniquement) |
|
||||
| `/focus <target>` | Lie le fil actuel (ou en crée un) à une cible de sous-agent/session |
|
||||
| `/unfocus` | Supprime la liaison du fil lié actuel |
|
||||
| `/agents` | Liste les exécutions actives et l’état de liaison (`thread:<id>` ou `unbound`) |
|
||||
| `/session idle` | Inspecte/met à jour le désancrage automatique après inactivité (fils liés focalisés uniquement) |
|
||||
| `/session max-age` | Inspecte/met à jour la limite stricte (fils liés focalisés uniquement) |
|
||||
|
||||
### Commutateurs de configuration
|
||||
### Options de configuration
|
||||
|
||||
- **Valeur globale par défaut :** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- Les **clés de remplacement par canal et d’association automatique au spawn** sont propres à chaque adaptateur. Voir [Canaux prenant en charge les fils](#thread-supporting-channels) ci-dessus.
|
||||
- **Valeur par défaut globale :** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- **Les clés de remplacement par canal et de liaison automatique au spawn** sont propres à chaque adaptateur. Consultez [Canaux prenant en charge les fils](#thread-supporting-channels) ci-dessus.
|
||||
|
||||
Voir [Référence de configuration](/fr/gateway/configuration-reference) et
|
||||
[Commandes slash](/fr/tools/slash-commands) pour les détails actuels des adaptateurs.
|
||||
Consultez la [Référence de configuration](/fr/gateway/configuration-reference) et
|
||||
les [commandes slash](/fr/tools/slash-commands) pour les détails actuels des adaptateurs.
|
||||
|
||||
### Liste d’autorisation
|
||||
|
||||
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
|
||||
Liste des ids d’agents qui peuvent être ciblés via `agentId` explicite (`["*"]` autorise n’importe lequel). Par défaut : uniquement l’agent demandeur. Si vous définissez une liste et souhaitez quand même que le demandeur puisse se lancer lui-même avec `agentId`, incluez l’id du demandeur dans la liste.
|
||||
Liste des ids d’agents pouvant être ciblés via un `agentId` explicite (`["*"]` autorise n’importe lequel). Par défaut : uniquement l’agent demandeur. Si vous définissez une liste et voulez toujours que le demandeur puisse se créer lui-même avec `agentId`, incluez l’id du demandeur dans la liste.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
|
||||
Liste d’autorisation d’agents cibles par défaut utilisée lorsque l’agent demandeur ne définit pas son propre `subagents.allowAgents`.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
|
||||
Bloque les appels `sessions_spawn` qui omettent `agentId` (force la sélection explicite d’un profil). Remplacement par agent : `agents.list[].subagents.requireAgentId`.
|
||||
Bloque les appels `sessions_spawn` qui omettent `agentId` (force une sélection explicite de profil). Remplacement par agent : `agents.list[].subagents.requireAgentId`.
|
||||
</ParamField>
|
||||
|
||||
Si la session demandeuse est sandboxée, `sessions_spawn` rejette les cibles
|
||||
qui s’exécuteraient sans sandbox.
|
||||
qui s’exécuteraient hors sandbox.
|
||||
|
||||
### Découverte
|
||||
|
||||
Utilisez `agents_list` pour voir quels ids d’agents sont actuellement autorisés pour
|
||||
`sessions_spawn`. La réponse inclut le modèle effectif de chaque agent listé
|
||||
et les métadonnées de runtime intégrées afin que les appelants puissent distinguer PI, le serveur d’application Codex
|
||||
et les métadonnées d’exécution intégrées afin que les appelants puissent distinguer PI, le serveur d’application Codex
|
||||
et les autres runtimes natifs configurés.
|
||||
|
||||
### Archivage automatique
|
||||
|
||||
- Les sessions de sous-agent sont automatiquement archivées après `agents.defaults.subagents.archiveAfterMinutes` (par défaut `60`).
|
||||
- Les sessions de sous-agents sont automatiquement archivées après `agents.defaults.subagents.archiveAfterMinutes` (`60` par défaut).
|
||||
- L’archivage utilise `sessions.delete` et renomme la transcription en `*.deleted.<timestamp>` (même dossier).
|
||||
- `cleanup: "delete"` archive immédiatement après l’annonce (conserve quand même la transcription via renommage).
|
||||
- L’archivage automatique est fait au mieux ; les minuteurs en attente sont perdus si le Gateway redémarre.
|
||||
- `cleanup: "delete"` archive immédiatement après l’annonce (la transcription est tout de même conservée via renommage).
|
||||
- L’archivage automatique est au mieux ; les minuteurs en attente sont perdus si le gateway redémarre.
|
||||
- `runTimeoutSeconds` n’archive **pas** automatiquement ; il arrête seulement l’exécution. La session reste jusqu’à l’archivage automatique.
|
||||
- L’archivage automatique s’applique de la même façon aux sessions de profondeur 1 et de profondeur 2.
|
||||
- Le nettoyage du navigateur est séparé du nettoyage d’archivage : les onglets/processus de navigateur suivis sont fermés au mieux lorsque l’exécution se termine, même si l’enregistrement de transcription/session est conservé.
|
||||
- L’archivage automatique s’applique de la même manière aux sessions de profondeur 1 et de profondeur 2.
|
||||
- Le nettoyage du navigateur est distinct du nettoyage d’archive : les onglets/processus de navigateur suivis sont fermés au mieux lorsque l’exécution se termine, même si la transcription/l’enregistrement de session est conservé.
|
||||
|
||||
## Sous-agents imbriqués
|
||||
|
||||
Par défaut, les sous-agents ne peuvent pas lancer leurs propres sous-agents
|
||||
Par défaut, les sous-agents ne peuvent pas créer leurs propres sous-agents
|
||||
(`maxSpawnDepth: 1`). Définissez `maxSpawnDepth: 2` pour activer un niveau
|
||||
d’imbrication — le **modèle orchestrateur** : principal → sous-agent orchestrateur →
|
||||
sous-sous-agents workers.
|
||||
sous-sous-agents travailleurs.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
subagents: {
|
||||
maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
|
||||
maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
|
||||
maxConcurrent: 8, // global concurrency lane cap (default: 8)
|
||||
runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
|
||||
maxSpawnDepth: 2, // autorise les sous-agents à créer des enfants (par défaut : 1)
|
||||
maxChildrenPerAgent: 5, // nombre max d’enfants actifs par session d’agent (par défaut : 5)
|
||||
maxConcurrent: 8, // limite globale de voies de concurrence (par défaut : 8)
|
||||
runTimeoutSeconds: 900, // délai d’expiration par défaut pour sessions_spawn quand il est omis (0 = aucun délai)
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -312,31 +312,31 @@ sous-sous-agents workers.
|
||||
|
||||
### Niveaux de profondeur
|
||||
|
||||
| Profondeur | Forme de la clé de session | Rôle | Peut lancer ? |
|
||||
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | Agent principal | Toujours |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Sous-agent (orchestrateur lorsque la profondeur 2 est autorisée) | Seulement si `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sous-sous-agent (worker feuille) | Jamais |
|
||||
| Profondeur | Forme de la clé de session | Rôle | Peut créer ? |
|
||||
| ---------- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | Agent principal | Toujours |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Sous-agent (orchestrateur quand la profondeur 2 est autorisée) | Uniquement si `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sous-sous-agent (travailleur feuille) | Jamais |
|
||||
|
||||
### Chaîne d’annonce
|
||||
|
||||
Les résultats remontent la chaîne :
|
||||
|
||||
1. Le worker de profondeur 2 termine → annonce à son parent (orchestrateur de profondeur 1).
|
||||
1. Le travailleur de profondeur 2 termine → annonce à son parent (orchestrateur de profondeur 1).
|
||||
2. L’orchestrateur de profondeur 1 reçoit l’annonce, synthétise les résultats, termine → annonce au principal.
|
||||
3. L’agent principal reçoit l’annonce et la livre à l’utilisateur.
|
||||
|
||||
Chaque niveau ne voit que les annonces de ses enfants directs.
|
||||
|
||||
<Note>
|
||||
**Conseil opérationnel :** démarrez le travail enfant une seule fois et attendez les événements
|
||||
de fin au lieu de construire des boucles de sondage autour de `sessions_list`,
|
||||
`sessions_history`, `/subagents list` ou des commandes de sommeil `exec`.
|
||||
`sessions_list` et `/subagents list` maintiennent les relations de sessions enfant
|
||||
centrées sur le travail actif — les enfants actifs restent attachés, les enfants terminés restent
|
||||
visibles pendant une courte fenêtre récente, et les liens enfant périmés présents seulement dans le stockage sont
|
||||
ignorés après leur fenêtre de fraîcheur. Cela empêche les anciennes métadonnées `spawnedBy` /
|
||||
`parentSessionKey` de ressusciter des enfants fantômes après
|
||||
**Consignes opérationnelles :** démarrez le travail enfant une seule fois et attendez les événements
|
||||
de fin plutôt que de construire des boucles d’interrogation autour de `sessions_list`,
|
||||
`sessions_history`, `/subagents list` ou de commandes `exec` avec sleep.
|
||||
`sessions_list` et `/subagents list` gardent les relations de sessions enfants
|
||||
centrées sur le travail en cours — les enfants actifs restent attachés, les enfants terminés restent
|
||||
visibles pendant une courte fenêtre récente, et les liens enfants obsolètes uniquement stockés sont
|
||||
ignorés après leur fenêtre de fraîcheur. Cela empêche d’anciennes métadonnées `spawnedBy` /
|
||||
`parentSessionKey` de ressusciter des enfants fantômes après un
|
||||
redémarrage. Si un événement de fin d’enfant arrive après que vous avez déjà envoyé la
|
||||
réponse finale, le suivi correct est le jeton silencieux exact
|
||||
`NO_REPLY` / `no_reply`.
|
||||
@ -344,76 +344,77 @@ réponse finale, le suivi correct est le jeton silencieux exact
|
||||
|
||||
### Politique d’outils par profondeur
|
||||
|
||||
- Le rôle et la portée de contrôle sont écrits dans les métadonnées de session au moment du spawn. Cela empêche les clés de session plates ou restaurées de récupérer accidentellement des privilèges d’orchestrateur.
|
||||
- **Profondeur 1 (orchestrateur, lorsque `maxSpawnDepth >= 2`) :** reçoit `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` afin de pouvoir gérer ses enfants. Les autres outils de session/système restent refusés.
|
||||
- **Profondeur 1 (feuille, lorsque `maxSpawnDepth == 1`) :** aucun outil de session (comportement actuel par défaut).
|
||||
- **Profondeur 2 (worker feuille) :** aucun outil de session — `sessions_spawn` est toujours refusé à la profondeur 2. Ne peut pas lancer d’autres enfants.
|
||||
- Le rôle et la portée de contrôle sont écrits dans les métadonnées de session au moment de la création. Cela empêche les clés de session plates ou restaurées de récupérer accidentellement des privilèges d’orchestrateur.
|
||||
- **Profondeur 1 (orchestrateur, quand `maxSpawnDepth >= 2`) :** reçoit `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` afin de pouvoir gérer ses enfants. Les autres outils de session/système restent refusés.
|
||||
- **Profondeur 1 (feuille, quand `maxSpawnDepth == 1`) :** aucun outil de session (comportement actuel par défaut).
|
||||
- **Profondeur 2 (travailleur feuille) :** aucun outil de session — `sessions_spawn` est toujours refusé à la profondeur 2. Ne peut pas créer d’autres enfants.
|
||||
|
||||
### Limite de spawn par agent
|
||||
### Limite de création par agent
|
||||
|
||||
Chaque session d’agent (à n’importe quelle profondeur) peut avoir au plus `maxChildrenPerAgent`
|
||||
(par défaut `5`) enfants actifs à la fois. Cela évite une démultiplication incontrôlée
|
||||
(`5` par défaut) enfants actifs à la fois. Cela empêche un déploiement incontrôlé
|
||||
depuis un seul orchestrateur.
|
||||
|
||||
### Arrêt en cascade
|
||||
|
||||
Arrêter un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants de profondeur 2 :
|
||||
Arrêter un orchestrateur de profondeur 1 arrête automatiquement tous ses enfants
|
||||
de profondeur 2 :
|
||||
|
||||
- `/stop` dans le chat principal arrête tous les agents de profondeur 1 et cascade vers leurs enfants de profondeur 2.
|
||||
- `/subagents kill <id>` arrête un sous-agent précis et cascade vers ses enfants.
|
||||
- `/subagents kill all` arrête tous les sous-agents du demandeur et cascade.
|
||||
- `/stop` dans le chat principal arrête tous les agents de profondeur 1 et se propage à leurs enfants de profondeur 2.
|
||||
- `/subagents kill <id>` arrête un sous-agent précis et se propage à ses enfants.
|
||||
- `/subagents kill all` arrête tous les sous-agents du demandeur et se propage.
|
||||
|
||||
## Authentification
|
||||
|
||||
L’authentification des sous-agents est résolue par **id d’agent**, pas par type de session :
|
||||
L’authentification des sous-agents est résolue par **id d’agent**, et non par type de session :
|
||||
|
||||
- La clé de session du sous-agent est `agent:<agentId>:subagent:<uuid>`.
|
||||
- Le magasin d’authentification est chargé depuis le `agentDir` de cet agent.
|
||||
- Les profils d’authentification de l’agent principal sont fusionnés comme **fallback** ; les profils d’agent remplacent les profils principaux en cas de conflit.
|
||||
- Le magasin d’authentification est chargé depuis l’`agentDir` de cet agent.
|
||||
- Les profils d’authentification de l’agent principal sont fusionnés comme **repli** ; les profils d’agent remplacent les profils principaux en cas de conflit.
|
||||
|
||||
La fusion est additive, donc les profils principaux sont toujours disponibles comme
|
||||
fallbacks. L’authentification entièrement isolée par agent n’est pas encore prise en charge.
|
||||
solutions de repli. L’authentification entièrement isolée par agent n’est pas encore prise en charge.
|
||||
|
||||
## Annonce
|
||||
|
||||
Les sous-agents rendent compte via une étape d’annonce :
|
||||
|
||||
- L’étape d’annonce s’exécute dans la session du sous-agent (pas dans la session du demandeur).
|
||||
- L’étape d’annonce s’exécute dans la session du sous-agent (pas dans la session demandeuse).
|
||||
- Si le sous-agent répond exactement `ANNOUNCE_SKIP`, rien n’est publié.
|
||||
- Si le dernier texte assistant est le jeton silencieux exact `NO_REPLY` / `no_reply`, la sortie d’annonce est supprimée même si une progression visible existait auparavant.
|
||||
- Si le dernier texte assistant est le jeton silencieux exact `NO_REPLY` / `no_reply`, la sortie d’annonce est supprimée même si une progression visible antérieure existait.
|
||||
|
||||
La livraison dépend de la profondeur du demandeur :
|
||||
|
||||
- Les sessions demandeuses de premier niveau utilisent un appel de suivi `agent` avec livraison externe (`deliver=true`).
|
||||
- Les sessions de sous-agent demandeuses imbriquées reçoivent une injection de suivi interne (`deliver=false`) afin que l’orchestrateur puisse synthétiser les résultats des enfants dans la session.
|
||||
- Si une session de sous-agent demandeuse imbriquée a disparu, OpenClaw se rabat sur le demandeur de cette session lorsqu’il est disponible.
|
||||
- Les sessions demandeuses de premier niveau utilisent un appel `agent` de suivi avec livraison externe (`deliver=true`).
|
||||
- Les sessions de sous-agent demandeur imbriquées reçoivent une injection de suivi interne (`deliver=false`) afin que l’orchestrateur puisse synthétiser les résultats enfants dans la session.
|
||||
- Si une session de sous-agent demandeur imbriquée a disparu, OpenClaw revient au demandeur de cette session lorsqu’il est disponible.
|
||||
|
||||
Pour les sessions demandeuses de premier niveau, la livraison directe en mode achèvement
|
||||
résout d’abord toute route de conversation/fil associée et tout remplacement de hook, puis remplit
|
||||
Pour les sessions demandeuses de premier niveau, la livraison directe en mode fin
|
||||
résout d’abord toute route de conversation/fil liée et tout remplacement de hook, puis remplit
|
||||
les champs de cible de canal manquants depuis la route stockée de la session demandeuse.
|
||||
Cela maintient les achèvements dans le bon chat/sujet même lorsque l’origine
|
||||
de l’achèvement identifie seulement le canal.
|
||||
Cela garde les fins sur le bon chat/sujet même lorsque l’origine de la fin
|
||||
n’identifie que le canal.
|
||||
|
||||
L’agrégation des achèvements d’enfants est limitée à l’exécution demandeuse actuelle lors de
|
||||
la construction des résultats d’achèvement imbriqués, empêchant les sorties d’enfants
|
||||
d’exécutions précédentes obsolètes de fuiter dans l’annonce actuelle. Les réponses d’annonce préservent
|
||||
L’agrégation des fins d’enfants est limitée à l’exécution demandeuse actuelle lors de
|
||||
la construction des résultats de fin imbriqués, empêchant les sorties d’enfants
|
||||
d’exécutions antérieures obsolètes de fuir dans l’annonce actuelle. Les réponses d’annonce préservent
|
||||
le routage de fil/sujet lorsqu’il est disponible sur les adaptateurs de canal.
|
||||
|
||||
### Contexte d’annonce
|
||||
|
||||
Le contexte d’annonce est normalisé en un bloc d’événement interne stable :
|
||||
|
||||
| Champ | Source |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Source | `subagent` ou `cron` |
|
||||
| Ids de session | Clé/id de session enfant |
|
||||
| Type | Type d’annonce + libellé de tâche |
|
||||
| Statut | Dérivé du résultat du runtime (`success`, `error`, `timeout` ou `unknown`) — **non** déduit du texte du modèle |
|
||||
| Contenu du résultat | Dernier texte assistant visible, sinon dernier texte d’outil/toolResult assaini |
|
||||
| Suivi | Instruction décrivant quand répondre ou rester silencieux |
|
||||
| Champ | Source |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Source | `subagent` ou `cron` |
|
||||
| Ids de session | Clé/id de session enfant |
|
||||
| Type | Type d’annonce + libellé de tâche |
|
||||
| Statut | Dérivé du résultat d’exécution (`success`, `error`, `timeout` ou `unknown`) — **pas** déduit du texte du modèle |
|
||||
| Contenu du résultat | Dernier texte assistant visible, sinon dernier texte tool/toolResult assaini |
|
||||
| Suivi | Instruction décrivant quand répondre ou rester silencieux |
|
||||
|
||||
Les exécutions terminales échouées signalent un statut d’échec sans rejouer le texte
|
||||
de réponse capturé. En cas de timeout, si l’enfant n’a atteint que des appels d’outils, l’annonce
|
||||
Les exécutions terminales échouées signalent un statut d’échec sans rejouer le
|
||||
texte de réponse capturé. En cas de délai expiré, si l’enfant n’a progressé que jusqu’aux appels d’outils, l’annonce
|
||||
peut condenser cet historique en un bref résumé de progression partielle au lieu
|
||||
de rejouer la sortie brute des outils.
|
||||
|
||||
@ -421,8 +422,8 @@ de rejouer la sortie brute des outils.
|
||||
|
||||
Les charges utiles d’annonce incluent une ligne de statistiques à la fin (même lorsqu’elles sont enveloppées) :
|
||||
|
||||
- Runtime (par exemple `runtime 5m12s`).
|
||||
- Utilisation de tokens (entrée/sortie/total).
|
||||
- Durée d’exécution (par ex. `runtime 5m12s`).
|
||||
- Utilisation des tokens (entrée/sortie/total).
|
||||
- Coût estimé lorsque la tarification du modèle est configurée (`models.providers.*.models[].cost`).
|
||||
- `sessionKey`, `sessionId` et chemin de transcription afin que l’agent principal puisse récupérer l’historique via `sessions_history` ou inspecter le fichier sur disque.
|
||||
|
||||
@ -433,34 +434,28 @@ doivent être réécrites avec une voix d’assistant normale.
|
||||
|
||||
`sessions_history` est le chemin d’orchestration le plus sûr :
|
||||
|
||||
- Le rappel assistant est d’abord normalisé : balises de réflexion supprimées ; échafaudage `<relevant-memories>` / `<relevant_memories>` supprimé ; blocs de charge utile XML d’appel d’outil en texte brut (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) supprimés, y compris les charges utiles tronquées qui ne se ferment jamais proprement ; échafaudage d’appel/résultat d’outil rétrogradé et marqueurs de contexte historique supprimés ; tokens de contrôle de modèle divulgués (`<|assistant|>`, autres `<|...|>` ASCII, `<｜...｜>` pleine chasse) supprimés ; XML d’appel d’outil MiniMax mal formé supprimé.
|
||||
- Le rappel assistant est d’abord normalisé : balises de pensée supprimées ; échafaudages `<relevant-memories>` / `<relevant_memories>` supprimés ; blocs de charge utile XML d’appels d’outils en texte brut (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) supprimés, y compris les charges utiles tronquées qui ne se ferment jamais proprement ; échafaudages d’appel/résultat d’outil rétrogradés et marqueurs de contexte historique supprimés ; tokens de contrôle du modèle divulgués (`<|assistant|>`, autres ASCII `<|...|>`, pleine chasse `<｜...｜>`) supprimés ; XML d’appel d’outil MiniMax mal formé supprimé.
|
||||
- Le texte ressemblant à des identifiants/tokens est expurgé.
|
||||
- Les longs blocs peuvent être tronqués.
|
||||
- Les très grands historiques peuvent supprimer les lignes plus anciennes ou remplacer une ligne surdimensionnée par `[sessions_history omitted: message too large]`.
|
||||
- L’inspection brute de la transcription sur disque est le fallback lorsque vous avez besoin de la transcription complète octet pour octet.
|
||||
- Les très grands historiques peuvent supprimer les lignes plus anciennes ou remplacer une ligne trop volumineuse par `[sessions_history omitted: message too large]`.
|
||||
- L’inspection de la transcription brute sur disque est le repli lorsque vous avez besoin de la transcription complète octet pour octet.
|
||||
|
||||
## Politique d’outils
|
||||
|
||||
Les sous-agents utilisent d’abord le même profil et le même pipeline de politique d’outils que le parent ou
|
||||
l’agent cible. Ensuite, OpenClaw applique la couche de restriction
|
||||
des sous-agents.
|
||||
Les sous-agents utilisent d’abord le même profil et le même pipeline de politique des outils que l’agent parent ou cible. Ensuite, OpenClaw applique la couche de restriction des sous-agents.
|
||||
|
||||
Sans `tools.profile` restrictif, les sous-agents reçoivent **tous les outils sauf
|
||||
les outils de session** et les outils système :
|
||||
Sans `tools.profile` restrictif, les sous-agents reçoivent **tous les outils sauf les outils de session** et les outils système :
|
||||
|
||||
- `sessions_list`
|
||||
- `sessions_history`
|
||||
- `sessions_send`
|
||||
- `sessions_spawn`
|
||||
|
||||
`sessions_history` reste ici aussi une vue de rappel bornée et assainie — ce
|
||||
n’est pas un dump brut de transcription.
|
||||
`sessions_history` reste ici aussi une vue de rappel bornée et assainie — ce n’est pas un vidage brut de transcription.
|
||||
|
||||
Lorsque `maxSpawnDepth >= 2`, les sous-agents orchestrateurs de profondeur 1
|
||||
reçoivent en plus `sessions_spawn`, `subagents`, `sessions_list` et
|
||||
`sessions_history` afin de pouvoir gérer leurs enfants.
|
||||
Quand `maxSpawnDepth >= 2`, les sous-agents orchestrateurs de profondeur 1 reçoivent en plus `sessions_spawn`, `subagents`, `sessions_list` et `sessions_history` afin de pouvoir gérer leurs enfants.
|
||||
|
||||
### Remplacement via la configuration
|
||||
### Remplacer via la configuration
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -484,12 +479,7 @@ reçoivent en plus `sessions_spawn`, `subagents`, `sessions_list` et
|
||||
}
|
||||
```
|
||||
|
||||
`tools.subagents.tools.allow` est un filtre final qui n’autorise que ce qui est explicitement permis. Il peut restreindre
|
||||
l’ensemble d’outils déjà résolu, mais il ne peut pas **rajouter** un outil supprimé
|
||||
par `tools.profile`. Par exemple, `tools.profile: "coding"` inclut
|
||||
`web_search`/`web_fetch`, mais pas l’outil `browser`. Pour permettre aux
|
||||
sous-agents de profil coding d’utiliser l’automatisation de navigateur, ajoutez browser à
|
||||
l’étape du profil :
|
||||
`tools.subagents.tools.allow` est un filtre final d’autorisation seule. Il peut restreindre l’ensemble d’outils déjà résolu, mais il ne peut pas **rajouter** un outil supprimé par `tools.profile`. Par exemple, `tools.profile: "coding"` inclut `web_search`/`web_fetch`, mais pas l’outil `browser`. Pour permettre aux sous-agents avec le profil coding d’utiliser l’automatisation de navigateur, ajoutez browser à l’étape du profil :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -500,65 +490,44 @@ l’étape du profil :
|
||||
}
|
||||
```
|
||||
|
||||
Utilisez `agents.list[].tools.alsoAllow: ["browser"]` par agent lorsque seul un
|
||||
agent doit obtenir l’automatisation de navigateur.
|
||||
Utilisez `agents.list[].tools.alsoAllow: ["browser"]` par agent lorsque seul un agent doit recevoir l’automatisation de navigateur.
|
||||
|
||||
## Concurrence
|
||||
|
||||
Les sous-agents utilisent une voie de file d’attente dédiée dans le processus :
|
||||
Les sous-agents utilisent une file dédiée en cours de processus :
|
||||
|
||||
- **Nom de la voie :** `subagent`
|
||||
- **Concurrence :** `agents.defaults.subagents.maxConcurrent` (par défaut `8`)
|
||||
|
||||
## Vivacité et récupération
|
||||
|
||||
OpenClaw ne considère pas l’absence de `endedAt` comme une preuve permanente qu’un
|
||||
sous-agent est encore actif. Les exécutions non terminées plus anciennes que la fenêtre d’exécution obsolète
|
||||
cessent d’être comptées comme actives/en attente dans `/subagents list`, les résumés de statut,
|
||||
les contrôles de fin des descendants et les vérifications de concurrence par session.
|
||||
OpenClaw ne considère pas l’absence de `endedAt` comme une preuve permanente qu’un sous-agent est encore actif. Les exécutions non terminées plus anciennes que la fenêtre d’exécution obsolète cessent d’être comptabilisées comme actives/en attente dans `/subagents list`, les résumés d’état, le contrôle de terminaison des descendants et les vérifications de concurrence par session.
|
||||
|
||||
Après un redémarrage du Gateway, les exécutions restaurées non terminées et obsolètes sont élaguées sauf si
|
||||
leur session enfant est marquée `abortedLastRun: true`. Ces
|
||||
sessions enfants interrompues par redémarrage restent récupérables via le flux de récupération d’orphelin
|
||||
de sous-agent, qui envoie un message synthétique de reprise avant
|
||||
d’effacer le marqueur d’interruption.
|
||||
Après un redémarrage du Gateway, les exécutions restaurées non terminées et obsolètes sont élaguées, sauf si leur session enfant est marquée `abortedLastRun: true`. Ces sessions enfants interrompues par le redémarrage restent récupérables via le flux de récupération des sous-agents orphelins, qui envoie un message synthétique de reprise avant d’effacer le marqueur d’interruption.
|
||||
|
||||
La récupération automatique après redémarrage est limitée par session enfant. Si le même
|
||||
enfant de sous-agent est accepté à plusieurs reprises pour une récupération d’orphelin dans la
|
||||
fenêtre de reblocage rapide, OpenClaw persiste une pierre tombale de récupération sur cette
|
||||
session et cesse de la reprendre automatiquement lors des redémarrages ultérieurs. Exécutez
|
||||
`openclaw tasks maintenance --apply` pour réconcilier l’enregistrement de tâche, ou
|
||||
`openclaw doctor --fix` pour effacer les indicateurs de récupération interrompue obsolètes sur les
|
||||
sessions avec pierre tombale.
|
||||
La récupération automatique au redémarrage est bornée par session enfant. Si le même enfant de sous-agent est accepté plusieurs fois pour une récupération d’orphelin dans la fenêtre de reblocage rapide, OpenClaw conserve une pierre tombale de récupération sur cette session et cesse de la reprendre automatiquement lors des redémarrages suivants. Exécutez `openclaw tasks maintenance --apply` pour réconcilier l’enregistrement de tâche, ou `openclaw doctor --fix` pour effacer les indicateurs de récupération interrompue obsolètes sur les sessions avec pierre tombale.
|
||||
|
||||
<Note>
|
||||
Si la création d’un sous-agent échoue avec Gateway `PAIRING_REQUIRED` /
|
||||
`scope-upgrade`, vérifiez l’appelant RPC avant de modifier l’état d’association.
|
||||
La coordination interne `sessions_spawn` doit se connecter en tant que
|
||||
`client.id: "gateway-client"` avec `client.mode: "backend"` via une authentification directe
|
||||
loopback par jeton partagé/mot de passe ; ce chemin ne dépend pas de la
|
||||
base de portée des appareils associés de la CLI. Les appelants distants, les
|
||||
`deviceIdentity` explicites, les chemins explicites par jeton d’appareil et les clients
|
||||
navigateur/node nécessitent toujours l’approbation normale de l’appareil pour les mises à niveau de portée.
|
||||
Si la création d’un sous-agent échoue avec Gateway `PAIRING_REQUIRED` / `scope-upgrade`, vérifiez l’appelant RPC avant de modifier l’état d’appairage. La coordination interne `sessions_spawn` doit se connecter comme `client.id: "gateway-client"` avec `client.mode: "backend"` sur une authentification directe par jeton partagé/mot de passe en local loopback ; ce chemin ne dépend pas de la base de portée d’appareil appairé de la CLI. Les appelants distants, `deviceIdentity` explicite, les chemins explicites par jeton d’appareil et les clients navigateur/node nécessitent toujours l’approbation normale de l’appareil pour les montées de portée.
|
||||
</Note>
|
||||
|
||||
## Arrêt
|
||||
|
||||
- L’envoi de `/stop` dans la discussion du demandeur interrompt la session du demandeur et arrête toutes les exécutions de sous-agent actives créées depuis celle-ci, avec propagation aux enfants imbriqués.
|
||||
- `/subagents kill <id>` arrête un sous-agent précis et propage l’arrêt à ses enfants.
|
||||
- Envoyer `/stop` dans la discussion du demandeur interrompt la session du demandeur et arrête toutes les exécutions de sous-agents actives lancées depuis celle-ci, en cascade vers les enfants imbriqués.
|
||||
- `/subagents kill <id>` arrête un sous-agent spécifique et se répercute en cascade sur ses enfants.
|
||||
|
||||
## Limites
|
||||
## Limitations
|
||||
|
||||
- L’annonce du sous-agent est fournie **au mieux**. Si le Gateway redémarre, le travail « announce back » en attente est perdu.
|
||||
- Les sous-agents partagent toujours les mêmes ressources du processus Gateway ; considérez `maxConcurrent` comme une soupape de sécurité.
|
||||
- L’annonce des sous-agents est **best-effort**. Si le gateway redémarre, le travail en attente de « retour d’annonce » est perdu.
|
||||
- Les sous-agents partagent toujours les mêmes ressources du processus gateway ; considérez `maxConcurrent` comme une soupape de sécurité.
|
||||
- `sessions_spawn` est toujours non bloquant : il renvoie `{ status: "accepted", runId, childSessionKey }` immédiatement.
|
||||
- Le contexte de sous-agent injecte uniquement `AGENTS.md` + `TOOLS.md` (pas de `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`).
|
||||
- Le contexte des sous-agents injecte uniquement `AGENTS.md` + `TOOLS.md` (pas de `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`).
|
||||
- La profondeur maximale d’imbrication est de 5 (plage de `maxSpawnDepth` : 1–5). La profondeur 2 est recommandée pour la plupart des cas d’utilisation.
|
||||
- `maxChildrenPerAgent` limite le nombre d’enfants actifs par session (par défaut `5`, plage `1–20`).
|
||||
- `maxChildrenPerAgent` plafonne les enfants actifs par session (par défaut `5`, plage `1–20`).
|
||||
|
||||
## Connexe
|
||||
|
||||
- [Agents ACP](/fr/tools/acp-agents)
|
||||
- [Envoi à l’agent](/fr/tools/agent-send)
|
||||
- [Tâches en arrière-plan](/fr/automation/tasks)
|
||||
- [Outils de bac à sable multi-agent](/fr/tools/multi-agent-sandbox-tools)
|
||||
- [Outils de sandbox multi-agent](/fr/tools/multi-agent-sandbox-tools)
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez gérer le Gateway depuis un navigateur
|
||||
- Vous souhaitez accéder au Tailnet sans tunnels SSH
|
||||
- Vous souhaitez utiliser le Gateway depuis un navigateur
|
||||
- Vous voulez accéder au Tailnet sans tunnels SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: Interface utilisateur de contrôle basée sur le navigateur pour le Gateway (chat, nœuds, configuration)
|
||||
summary: Interface de contrôle basée sur navigateur pour le Gateway (discussion, nœuds, configuration)
|
||||
title: Interface de contrôle
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:27:24Z"
|
||||
generated_at: "2026-05-04T07:06:32Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c890d83da2c296b600e4b5a00a538f37e6bd54da31fbe62113ecd6177b15626e
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
L’interface de contrôle est une petite application monopage **Vite + Lit** servie par le Gateway :
|
||||
La Control UI est une petite application monopage **Vite + Lit** servie par le Gateway :
|
||||
|
||||
- par défaut : `http://<host>:18789/`
|
||||
- préfixe facultatif : définissez `gateway.controlUi.basePath` (par ex. `/openclaw`)
|
||||
- préfixe facultatif : définissez `gateway.controlUi.basePath` (p. ex. `/openclaw`)
|
||||
|
||||
Elle communique **directement avec le WebSocket du Gateway** sur le même port.
|
||||
|
||||
@ -29,20 +29,20 @@ Si le Gateway s’exécute sur le même ordinateur, ouvrez :
|
||||
|
||||
Si la page ne se charge pas, démarrez d’abord le Gateway : `openclaw gateway`.
|
||||
|
||||
L’authentification est fournie pendant l’établissement de la connexion WebSocket via :
|
||||
L’authentification est fournie pendant la négociation WebSocket via :
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- les en-têtes d’identité Tailscale Serve lorsque `gateway.auth.allowTailscale: true`
|
||||
- les en-têtes d’identité de proxy de confiance lorsque `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Le panneau des paramètres du tableau de bord conserve un jeton pour la session de l’onglet de navigateur actuel et l’URL du Gateway sélectionnée ; les mots de passe ne sont pas persistés. L’onboarding génère généralement un jeton de Gateway pour l’authentification par secret partagé lors de la première connexion, mais l’authentification par mot de passe fonctionne aussi lorsque `gateway.auth.mode` vaut `"password"`.
|
||||
Le panneau de paramètres du tableau de bord conserve un jeton pour la session de l’onglet de navigateur actuel et l’URL de Gateway sélectionnée ; les mots de passe ne sont pas persistés. L’intégration génère généralement un jeton de Gateway pour l’authentification par secret partagé lors de la première connexion, mais l’authentification par mot de passe fonctionne aussi lorsque `gateway.auth.mode` vaut `"password"`.
|
||||
|
||||
## Appairage d’appareil (première connexion)
|
||||
|
||||
Lorsque vous vous connectez à l’interface de contrôle depuis un nouveau navigateur ou appareil, le Gateway exige généralement une **approbation d’appairage unique**. Il s’agit d’une mesure de sécurité destinée à empêcher tout accès non autorisé.
|
||||
Lorsque vous vous connectez à la Control UI depuis un nouveau navigateur ou appareil, le Gateway exige généralement une **approbation d’appairage unique**. Il s’agit d’une mesure de sécurité destinée à empêcher les accès non autorisés.
|
||||
|
||||
**Ce que vous verrez :** « déconnecté (1008) : appairage requis »
|
||||
**Ce que vous verrez :** « disconnected (1008): pairing required »
|
||||
|
||||
<Steps>
|
||||
<Step title="Lister les demandes en attente">
|
||||
@ -57,15 +57,15 @@ Lorsque vous vous connectez à l’interface de contrôle depuis un nouveau navi
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Si le navigateur réessaie l’appairage avec des détails d’authentification modifiés (rôle/portées/clé publique), la demande en attente précédente est remplacée et un nouveau `requestId` est créé. Relancez `openclaw devices list` avant l’approbation.
|
||||
Si le navigateur retente l’appairage avec des détails d’authentification modifiés (rôle/portées/clé publique), la demande en attente précédente est remplacée et un nouveau `requestId` est créé. Réexécutez `openclaw devices list` avant l’approbation.
|
||||
|
||||
Si le navigateur est déjà appairé et que vous le faites passer d’un accès en lecture à un accès en écriture/admin, cela est traité comme une mise à niveau d’approbation, et non comme une reconnexion silencieuse. OpenClaw conserve l’ancienne approbation active, bloque la reconnexion plus large et vous demande d’approuver explicitement le nouvel ensemble de portées.
|
||||
Si le navigateur est déjà appairé et que vous le faites passer d’un accès en lecture à un accès en écriture/administration, cela est traité comme une mise à niveau d’approbation, et non comme une reconnexion silencieuse. OpenClaw conserve l’ancienne approbation active, bloque la reconnexion plus étendue et vous demande d’approuver explicitement le nouvel ensemble de portées.
|
||||
|
||||
Une fois approuvé, l’appareil est mémorisé et ne nécessitera pas de nouvelle approbation, sauf si vous le révoquez avec `openclaw devices revoke --device <id> --role <role>`. Consultez [CLI des appareils](/fr/cli/devices) pour la rotation et la révocation des jetons.
|
||||
Une fois approuvé, l’appareil est mémorisé et ne demandera plus de nouvelle approbation, sauf si vous le révoquez avec `openclaw devices revoke --device <id> --role <role>`. Consultez [CLI des appareils](/fr/cli/devices) pour la rotation et la révocation des jetons.
|
||||
|
||||
<Note>
|
||||
- Les connexions de navigateur directes en local loopback (`127.0.0.1` / `localhost`) sont approuvées automatiquement.
|
||||
- Tailscale Serve peut éviter l’aller-retour d’appairage pour les sessions d’opérateur de l’interface de contrôle lorsque `gateway.auth.allowTailscale: true`, que l’identité Tailscale est vérifiée et que le navigateur présente son identité d’appareil.
|
||||
- Les connexions directes de navigateur en local loopback (`127.0.0.1` / `localhost`) sont approuvées automatiquement.
|
||||
- Tailscale Serve peut ignorer l’aller-retour d’appairage pour les sessions opérateur de la Control UI lorsque `gateway.auth.allowTailscale: true`, que l’identité Tailscale est vérifiée et que le navigateur présente son identité d’appareil.
|
||||
- Les liaisons Tailnet directes, les connexions de navigateur sur le LAN et les profils de navigateur sans identité d’appareil nécessitent toujours une approbation explicite.
|
||||
- Chaque profil de navigateur génère un ID d’appareil unique ; changer de navigateur ou effacer les données du navigateur nécessitera donc un nouvel appairage.
|
||||
|
||||
@ -73,144 +73,144 @@ Une fois approuvé, l’appareil est mémorisé et ne nécessitera pas de nouvel
|
||||
|
||||
## Identité personnelle (locale au navigateur)
|
||||
|
||||
L’interface de contrôle prend en charge une identité personnelle propre à chaque navigateur (nom d’affichage et avatar), attachée aux messages sortants pour l’attribution dans les sessions partagées. Elle réside dans le stockage du navigateur, est limitée au profil de navigateur actuel et n’est pas synchronisée avec d’autres appareils ni persistée côté serveur au-delà des métadonnées normales d’auteur de transcription sur les messages que vous envoyez réellement. Effacer les données du site ou changer de navigateur la réinitialise à vide.
|
||||
La Control UI prend en charge une identité personnelle par navigateur (nom d’affichage et avatar) attachée aux messages sortants pour l’attribution dans les sessions partagées. Elle réside dans le stockage du navigateur, est limitée au profil de navigateur actuel et n’est pas synchronisée avec d’autres appareils ni persistée côté serveur au-delà des métadonnées normales d’auteur de transcript sur les messages que vous envoyez réellement. Effacer les données du site ou changer de navigateur la réinitialise à une valeur vide.
|
||||
|
||||
Le même modèle local au navigateur s’applique au remplacement de l’avatar de l’assistant. Les avatars d’assistant téléversés superposent l’identité résolue par le Gateway uniquement dans le navigateur local et ne transitent jamais via `config.patch`. Le champ de configuration partagé `ui.assistant.avatar` reste disponible pour les clients non-UI qui écrivent directement dans ce champ (comme des gateways scriptés ou des tableaux de bord personnalisés).
|
||||
Le même modèle local au navigateur s’applique au remplacement de l’avatar de l’assistant. Les avatars d’assistant téléversés superposent l’identité résolue par le Gateway dans le navigateur local uniquement et ne font jamais d’aller-retour via `config.patch`. Le champ de configuration partagé `ui.assistant.avatar` reste disponible pour les clients non-UI qui écrivent directement dans ce champ (comme les gateways scriptés ou les tableaux de bord personnalisés).
|
||||
|
||||
## Point de terminaison de configuration d’exécution
|
||||
|
||||
L’interface de contrôle récupère ses paramètres d’exécution depuis `/__openclaw/control-ui-config.json`. Ce point de terminaison est protégé par la même authentification de Gateway que le reste de la surface HTTP : les navigateurs non authentifiés ne peuvent pas le récupérer, et une récupération réussie nécessite soit un jeton/mot de passe de Gateway déjà valide, soit une identité Tailscale Serve, soit une identité de proxy de confiance.
|
||||
La Control UI récupère ses paramètres d’exécution depuis `/__openclaw/control-ui-config.json`. Ce point de terminaison est protégé par la même authentification de Gateway que le reste de la surface HTTP : les navigateurs non authentifiés ne peuvent pas le récupérer, et une récupération réussie nécessite soit un jeton/mot de passe de Gateway déjà valide, soit une identité Tailscale Serve, soit une identité de proxy de confiance.
|
||||
|
||||
## Prise en charge des langues
|
||||
|
||||
L’interface de contrôle peut se localiser au premier chargement en fonction de la locale de votre navigateur. Pour la remplacer plus tard, ouvrez **Vue d’ensemble -> Accès au Gateway -> Langue**. Le sélecteur de locale se trouve dans la carte Accès au Gateway, pas sous Apparence.
|
||||
La Control UI peut se localiser au premier chargement selon la locale de votre navigateur. Pour la remplacer plus tard, ouvrez **Vue d’ensemble -> Accès au Gateway -> Langue**. Le sélecteur de locale se trouve dans la carte Accès au Gateway, pas sous Apparence.
|
||||
|
||||
- Locales prises en charge : `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Les traductions non anglaises sont chargées paresseusement dans le navigateur.
|
||||
- La locale sélectionnée est enregistrée dans le stockage du navigateur et réutilisée lors des visites futures.
|
||||
- Les clés de traduction manquantes se replient sur l’anglais.
|
||||
- Les clés de traduction manquantes se rabattent sur l’anglais.
|
||||
|
||||
Les traductions de la documentation sont générées pour le même ensemble de locales non anglaises, mais le sélecteur de langue Mintlify intégré au site de documentation est limité aux codes de locale acceptés par Mintlify. Les documentations thaïes (`th`) et persanes (`fa`) sont toujours générées dans le dépôt de publication ; elles peuvent ne pas apparaître dans ce sélecteur tant que Mintlify ne prend pas en charge ces codes.
|
||||
Les traductions de la documentation sont générées pour le même ensemble de locales non anglaises, mais le sélecteur de langue Mintlify intégré au site de documentation est limité aux codes de locale acceptés par Mintlify. Les docs en thaï (`th`) et en persan (`fa`) sont quand même générées dans le dépôt de publication ; elles peuvent ne pas apparaître dans ce sélecteur tant que Mintlify ne prend pas en charge ces codes.
|
||||
|
||||
## Thèmes d’apparence
|
||||
|
||||
Le panneau Apparence conserve les thèmes intégrés Claw, Knot et Dash, ainsi qu’un emplacement d’import tweakcn local au navigateur. Pour importer un thème, ouvrez [thèmes tweakcn](https://tweakcn.com/themes), choisissez ou créez un thème, cliquez sur **Partager**, puis collez le lien de thème copié dans Apparence. L’importateur accepte aussi les URL de registre `https://tweakcn.com/r/themes/<id>`, les URL d’éditeur comme `https://tweakcn.com/editor/theme?theme=amethyst-haze`, les chemins relatifs `/themes/<id>`, les ID de thème bruts et les noms de thème par défaut tels que `amethyst-haze`.
|
||||
Le panneau Apparence conserve les thèmes intégrés Claw, Knot et Dash, ainsi qu’un emplacement d’import tweakcn local au navigateur. Pour importer un thème, ouvrez [l’éditeur tweakcn](https://tweakcn.com/editor/theme), choisissez ou créez un thème, cliquez sur **Partager**, puis collez le lien de thème copié dans Apparence. L’importateur accepte aussi les URL de registre `https://tweakcn.com/r/themes/<id>`, les URL d’éditeur comme `https://tweakcn.com/editor/theme?theme=amethyst-haze`, les chemins relatifs `/themes/<id>`, les ID de thème bruts et les noms de thème par défaut comme `amethyst-haze`.
|
||||
|
||||
Les thèmes importés sont stockés uniquement dans le profil de navigateur actuel. Ils ne sont pas écrits dans la configuration du Gateway et ne se synchronisent pas entre appareils. Remplacer le thème importé met à jour l’unique emplacement local ; l’effacer fait revenir le thème actif à Claw si le thème importé était sélectionné.
|
||||
|
||||
## Ce qu’elle peut faire (aujourd’hui)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Discussion et parole">
|
||||
- Discutez avec le modèle via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Parlez via des sessions temps réel du navigateur. OpenAI utilise WebRTC direct, Google Live utilise un jeton de navigateur contraint à usage unique sur WebSocket, et les plugins vocaux temps réel uniquement côté backend utilisent le transport relais du Gateway. Le relais conserve les identifiants du fournisseur sur le Gateway pendant que le navigateur diffuse le PCM du microphone via les RPC `talk.realtime.relay*` et renvoie les appels d’outil `openclaw_agent_consult` via `chat.send` pour le modèle OpenClaw configuré plus grand.
|
||||
- Diffusez les appels d’outil + les cartes de sortie d’outil en direct dans la discussion (événements d’agent).
|
||||
<Accordion title="Chat et conversation vocale">
|
||||
- Discuter avec le modèle via le WS du Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Parler via des sessions temps réel dans le navigateur. OpenAI utilise WebRTC direct, Google Live utilise un jeton de navigateur contraint à usage unique sur WebSocket, et les plugins de voix temps réel côté backend uniquement utilisent le transport de relais du Gateway. Le relais conserve les identifiants de fournisseur sur le Gateway pendant que le navigateur diffuse le PCM du microphone via les RPC `talk.realtime.relay*` et renvoie les appels d’outil `openclaw_agent_consult` via `chat.send` pour le plus grand modèle OpenClaw configuré.
|
||||
- Diffuser les appels d’outil + les cartes de sortie d’outil en direct dans Chat (événements d’agent).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Canaux, instances, sessions, rêves">
|
||||
- Canaux : état des canaux intégrés ainsi que des canaux de plugins groupés/externes, connexion par QR et configuration par canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Canaux : statut des canaux intégrés et des canaux de plugins groupés/externes, connexion par QR code et configuration par canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Instances : liste de présence + actualisation (`system-presence`).
|
||||
- Sessions : liste + remplacements par session du modèle/de la réflexion/du mode rapide/du mode verbeux/de la trace/du raisonnement (`sessions.list`, `sessions.patch`).
|
||||
- Rêves : état du Dreaming, bascule d’activation/désactivation et lecteur du journal des rêves (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- Sessions : liste + remplacements par session pour le modèle/la réflexion/le mode rapide/le mode verbeux/la trace/le raisonnement (`sessions.list`, `sessions.patch`).
|
||||
- Rêves : statut de Dreaming, bascule d’activation/désactivation et lecteur du journal des rêves (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, skills, nœuds, approbations d’exécution">
|
||||
<Accordion title="Cron, Skills, Nodes, approbations exec">
|
||||
- Tâches Cron : lister/ajouter/modifier/exécuter/activer/désactiver + historique d’exécution (`cron.*`).
|
||||
- Skills : état, activer/désactiver, installer, mises à jour de clé API (`skills.*`).
|
||||
- Nœuds : liste + capacités (`node.list`).
|
||||
- Approbations d’exécution : modifiez les listes d’autorisation du Gateway ou des nœuds + la politique de demande pour `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Skills : statut, activation/désactivation, installation, mises à jour de clé API (`skills.*`).
|
||||
- Nodes : liste + capacités (`node.list`).
|
||||
- Approbations exec : modifier les listes d’autorisation du Gateway ou des Nodes + politique de demande pour `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configuration">
|
||||
- Affichez/modifiez `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Appliquez + redémarrez avec validation (`config.apply`) et réveillez la dernière session active.
|
||||
- Afficher/modifier `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Appliquer + redémarrer avec validation (`config.apply`) et réveiller la dernière session active.
|
||||
- Les écritures incluent une garde par hachage de base pour éviter d’écraser des modifications concurrentes.
|
||||
- Les écritures (`config.set`/`config.apply`/`config.patch`) effectuent une vérification préalable de résolution des SecretRef actifs pour les références présentes dans la charge utile de configuration soumise ; les références soumises actives non résolues sont rejetées avant écriture.
|
||||
- Schéma + rendu de formulaire (`config.schema` / `config.schema.lookup`, y compris les champs `title` / `description`, les indications d’interface correspondantes, les résumés des enfants immédiats, les métadonnées de documentation sur les nœuds imbriqués objet/joker/tableau/composition, ainsi que les schémas de Plugin + canal lorsqu’ils sont disponibles) ; l’éditeur JSON brut est disponible uniquement lorsque l’instantané dispose d’un aller-retour brut sûr.
|
||||
- Si un instantané ne peut pas effectuer en toute sécurité un aller-retour de texte brut, l’interface de contrôle force le mode Formulaire et désactive le mode Brut pour cet instantané.
|
||||
- Dans l’éditeur JSON brut, « Réinitialiser à la version enregistrée » préserve la forme rédigée en brut (formatage, commentaires, disposition `$include`) au lieu de restituer un instantané aplati, afin que les modifications externes survivent à une réinitialisation lorsque l’instantané peut effectuer un aller-retour sûr.
|
||||
- Les valeurs d’objet SecretRef structurées sont rendues en lecture seule dans les champs de texte du formulaire afin d’éviter toute corruption accidentelle d’objet en chaîne.
|
||||
- Les écritures (`config.set`/`config.apply`/`config.patch`) prévalident la résolution des SecretRef actifs pour les références dans la charge utile de configuration soumise ; les références actives soumises non résolues sont rejetées avant l’écriture.
|
||||
- Schéma + rendu de formulaire (`config.schema` / `config.schema.lookup`, y compris les champs `title` / `description`, les indices d’interface correspondants, les résumés d’enfants immédiats, les métadonnées de documentation sur les nœuds objet imbriqué/joker/tableau/composition, ainsi que les schémas de plugin + canal lorsqu’ils sont disponibles) ; l’éditeur JSON brut est disponible uniquement lorsque l’instantané dispose d’un aller-retour brut sûr.
|
||||
- Si un instantané ne peut pas effectuer en toute sécurité l’aller-retour du texte brut, la Control UI force le mode Formulaire et désactive le mode Brut pour cet instantané.
|
||||
- La commande « Réinitialiser à l’enregistré » de l’éditeur JSON brut préserve la forme rédigée en brut (mise en forme, commentaires, disposition `$include`) au lieu de rerendre un instantané aplati, afin que les modifications externes survivent à une réinitialisation lorsque l’instantané peut effectuer un aller-retour sûr.
|
||||
- Les valeurs d’objet SecretRef structurées sont rendues en lecture seule dans les entrées de texte du formulaire pour éviter une corruption accidentelle d’objet vers chaîne.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Débogage, journaux, mise à jour">
|
||||
- Débogage : instantanés d’état/de santé/des modèles + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`).
|
||||
- Journaux : suivi en direct des journaux de fichier du Gateway avec filtrage/export (`logs.tail`).
|
||||
- Mise à jour : exécutez une mise à jour de package/git + redémarrage (`update.run`) avec un rapport de redémarrage, puis interrogez `update.status` après la reconnexion pour vérifier la version du Gateway en cours d’exécution.
|
||||
- Débogage : instantanés de statut/santé/modèles + journal d’événements + appels RPC manuels (`status`, `health`, `models.list`).
|
||||
- Journaux : suivi en direct des journaux de fichier du Gateway avec filtre/export (`logs.tail`).
|
||||
- Mise à jour : exécuter une mise à jour de package/git + redémarrer (`update.run`) avec un rapport de redémarrage, puis interroger `update.status` après reconnexion pour vérifier la version du Gateway en cours d’exécution.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Notes du panneau des tâches Cron">
|
||||
- Pour les tâches isolées, la livraison utilise par défaut l’annonce d’un résumé. Vous pouvez passer à aucune si vous voulez des exécutions uniquement internes.
|
||||
- Pour les tâches isolées, la livraison annonce un résumé par défaut. Vous pouvez passer à aucune si vous voulez des exécutions internes uniquement.
|
||||
- Les champs canal/cible apparaissent lorsque l’annonce est sélectionnée.
|
||||
- Le mode Webhook utilise `delivery.mode = "webhook"` avec `delivery.to` défini sur une URL Webhook HTTP(S) valide.
|
||||
- Pour les tâches de session principale, les modes de livraison Webhook et aucune sont disponibles.
|
||||
- Les contrôles de modification avancés incluent supprimer après exécution, effacer le remplacement d’agent, les options cron exactes/échelonnées, les remplacements de modèle/réflexion de l’agent et les bascules de livraison au mieux.
|
||||
- La validation du formulaire est en ligne avec des erreurs au niveau des champs ; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
|
||||
- Définissez `cron.webhookToken` pour envoyer un jeton porteur dédié ; s’il est omis, le Webhook est envoyé sans en-tête d’authentification.
|
||||
- Repli obsolète : les anciennes tâches stockées avec `notify: true` peuvent encore utiliser `cron.webhook` jusqu’à leur migration.
|
||||
- Les contrôles d’édition avancée incluent supprimer après exécution, effacer le remplacement d’agent, options Cron exact/décalage, remplacements du modèle/de la réflexion de l’agent et bascules de livraison au mieux.
|
||||
- La validation du formulaire est intégrée avec des erreurs au niveau des champs ; les valeurs invalides désactivent le bouton d’enregistrement jusqu’à correction.
|
||||
- Définissez `cron.webhookToken` pour envoyer un jeton bearer dédié ; s’il est omis, le Webhook est envoyé sans en-tête d’authentification.
|
||||
- Solution de repli obsolète : les anciennes tâches stockées avec `notify: true` peuvent encore utiliser `cron.webhook` jusqu’à migration.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comportement de la discussion
|
||||
## Comportement du chat
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sémantique d’envoi et d’historique">
|
||||
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via les événements `chat`.
|
||||
- Les téléversements de chat acceptent les images ainsi que les fichiers non vidéo. Les images conservent le chemin d’image natif ; les autres fichiers sont stockés comme médias gérés et affichés dans l’historique sous forme de liens de pièce jointe.
|
||||
- Renvoyer avec la même `idempotencyKey` renvoie `{ status: "in_flight" }` pendant l’exécution, puis `{ status: "ok" }` après l’achèvement.
|
||||
- Les réponses `chat.history` sont limitées en taille pour la sécurité de l’UI. Quand les entrées de transcription sont trop volumineuses, le Gateway peut tronquer les longs champs de texte, omettre les blocs de métadonnées lourds et remplacer les messages trop volumineux par un espace réservé (`[chat.history omitted: message too large]`).
|
||||
- Les images de l’assistant/générées sont conservées comme références de médias gérés et renvoyées via des URL de médias Gateway authentifiées, afin que les rechargements ne dépendent pas du maintien des charges utiles d’image base64 brutes dans la réponse d’historique du chat.
|
||||
- `chat.history` supprime aussi du texte visible de l’assistant les balises de directive inline uniquement destinées à l’affichage (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), les charges utiles XML d’appel d’outil en texte brut (notamment `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` et les blocs d’appel d’outil tronqués), ainsi que les jetons de contrôle du modèle ASCII/pleine chasse divulgués, et omet les entrées d’assistant dont tout le texte visible est uniquement le jeton silencieux exact `NO_REPLY` / `no_reply`.
|
||||
- Pendant un envoi actif et le rafraîchissement final de l’historique, la vue de chat garde visibles les messages utilisateur/assistant optimistes locaux si `chat.history` renvoie brièvement un instantané plus ancien ; la transcription canonique remplace ces messages locaux une fois que l’historique du Gateway est à jour.
|
||||
- Les événements `chat` en direct représentent l’état de livraison, tandis que `chat.history` est reconstruit depuis la transcription de session durable. Après les événements finaux d’outil, l’UI de contrôle recharge l’historique et ne fusionne qu’une petite fin optimiste ; la frontière de transcription est documentée dans [WebChat](/fr/web/webchat).
|
||||
- `chat.inject` ajoute une note d’assistant à la transcription de session et diffuse un événement `chat` pour des mises à jour limitées à l’UI (pas d’exécution d’agent, pas de livraison de canal).
|
||||
- Les sélecteurs de modèle et de réflexion de l’en-tête de chat modifient immédiatement la session active via `sessions.patch` ; ce sont des remplacements persistants de session, pas des options d’envoi limitées à un seul tour.
|
||||
- Saisir `/new` dans l’UI de contrôle crée et bascule vers la même nouvelle session de tableau de bord que New Chat. Saisir `/reset` conserve la réinitialisation explicite sur place du Gateway pour la session actuelle.
|
||||
- Le sélecteur de modèle de chat demande la vue de modèle configurée du Gateway. Si `agents.defaults.models` est présent, cette liste d’autorisation alimente le sélecteur. Sinon, le sélecteur affiche les entrées explicites `models.providers.*.models` ainsi que les fournisseurs disposant d’une authentification utilisable. Le catalogue complet reste disponible via le RPC de débogage `models.list` avec `view: "all"`.
|
||||
- Quand de nouveaux rapports d’utilisation de session Gateway indiquent une forte pression de contexte, la zone de composition du chat affiche un avis de contexte et, aux niveaux de compaction recommandés, un bouton compact qui exécute le chemin normal de Compaction de session. Les instantanés de jetons obsolètes sont masqués jusqu’à ce que le Gateway signale de nouveau une utilisation récente.
|
||||
<Accordion title="Send and history semantics">
|
||||
- `chat.send` est **non bloquant** : il accuse réception immédiatement avec `{ runId, status: "started" }` et la réponse est diffusée via des événements `chat`.
|
||||
- Les téléversements de chat acceptent les images ainsi que les fichiers non vidéo. Les images conservent le chemin d’image natif ; les autres fichiers sont stockés comme médias gérés et affichés dans l’historique sous forme de liens de pièces jointes.
|
||||
- Un nouvel envoi avec le même `idempotencyKey` renvoie `{ status: "in_flight" }` pendant l’exécution, puis `{ status: "ok" }` après la fin.
|
||||
- Les réponses `chat.history` sont limitées en taille pour la sécurité de l’interface utilisateur. Lorsque les entrées de transcription sont trop volumineuses, le Gateway peut tronquer les champs de texte longs, omettre les blocs de métadonnées lourds et remplacer les messages surdimensionnés par un espace réservé (`[chat.history omitted: message too large]`).
|
||||
- Les images d’assistant/générées sont conservées comme références de médias gérés et resservies via des URL de médias authentifiées du Gateway, afin que les rechargements ne dépendent pas de la présence durable des charges utiles d’image base64 brutes dans la réponse d’historique du chat.
|
||||
- `chat.history` supprime également les balises de directives en ligne uniquement destinées à l’affichage du texte visible de l’assistant (par exemple `[[reply_to_*]]` et `[[audio_as_voice]]`), les charges utiles XML d’appels d’outils en texte brut (y compris `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` et les blocs d’appels d’outils tronqués), ainsi que les jetons de contrôle de modèle ASCII/pleine chasse divulgués, et omet les entrées d’assistant dont tout le texte visible est uniquement le jeton silencieux exact `NO_REPLY` / `no_reply`.
|
||||
- Pendant un envoi actif et l’actualisation finale de l’historique, la vue de chat garde visibles les messages utilisateur/assistant optimistes locaux si `chat.history` renvoie brièvement un instantané plus ancien ; la transcription canonique remplace ces messages locaux une fois que l’historique du Gateway a rattrapé son retard.
|
||||
- Les événements `chat` en direct représentent l’état de livraison, tandis que `chat.history` est reconstruit à partir de la transcription durable de la session. Après les événements finaux d’outils, l’interface Control recharge l’historique et ne fusionne qu’une petite fin optimiste ; la limite de transcription est documentée dans [WebChat](/fr/web/webchat).
|
||||
- `chat.inject` ajoute une note d’assistant à la transcription de session et diffuse un événement `chat` pour les mises à jour uniquement destinées à l’interface utilisateur (aucune exécution d’agent, aucune livraison de canal).
|
||||
- Le modèle d’en-tête du chat et les sélecteurs de réflexion modifient immédiatement la session active via `sessions.patch` ; ce sont des remplacements persistants de session, et non des options d’envoi limitées à un seul tour.
|
||||
- Saisir `/new` dans l’interface Control crée et bascule vers la même nouvelle session de tableau de bord que Nouveau chat. Saisir `/reset` conserve la réinitialisation explicite en place du Gateway pour la session actuelle.
|
||||
- Le sélecteur de modèle de chat demande la vue de modèle configurée du Gateway. Si `agents.defaults.models` est présent, cette liste d’autorisation pilote le sélecteur. Sinon, le sélecteur affiche les entrées explicites `models.providers.*.models` ainsi que les fournisseurs avec une authentification utilisable. Le catalogue complet reste disponible via le RPC de débogage `models.list` avec `view: "all"`.
|
||||
- Lorsque les rapports d’utilisation d’une session Gateway fraîche indiquent une forte pression de contexte, la zone de composition du chat affiche un avis de contexte et, aux niveaux de Compaction recommandés, un bouton compact qui exécute le chemin normal de Compaction de session. Les instantanés de jetons obsolètes sont masqués jusqu’à ce que le Gateway signale à nouveau une utilisation fraîche.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Mode conversation (temps réel du navigateur)">
|
||||
Le mode conversation utilise un fournisseur vocal temps réel enregistré. Configurez OpenAI avec `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, ou configurez Google avec `talk.provider: "google"` plus `talk.providers.google.apiKey` ; la configuration du fournisseur temps réel Voice Call peut toujours être réutilisée comme solution de repli. Le navigateur ne reçoit jamais de clé API de fournisseur standard. OpenAI reçoit un secret client Realtime éphémère pour WebRTC. Google Live reçoit un jeton d’authentification Live API à usage unique et contraint pour une session WebSocket de navigateur, avec les instructions et déclarations d’outils verrouillées dans le jeton par le Gateway. Les fournisseurs qui n’exposent qu’un pont temps réel backend passent par le transport relais du Gateway, afin que les identifiants et sockets fournisseur restent côté serveur pendant que l’audio du navigateur circule via des RPC Gateway authentifiés. L’invite de session Realtime est assemblée par le Gateway ; `talk.realtime.session` n’accepte pas de remplacements d’instructions fournis par l’appelant.
|
||||
<Accordion title="Talk mode (browser realtime)">
|
||||
Le mode Parler utilise un fournisseur vocal temps réel enregistré. Configurez OpenAI avec `talk.provider: "openai"` plus `talk.providers.openai.apiKey`, ou configurez Google avec `talk.provider: "google"` plus `talk.providers.google.apiKey` ; la configuration du fournisseur temps réel Voice Call peut encore être réutilisée comme solution de repli. Le navigateur ne reçoit jamais de clé API de fournisseur standard. OpenAI reçoit un secret client Realtime éphémère pour WebRTC. Google Live reçoit un jeton d’authentification Live API contraint à usage unique pour une session WebSocket de navigateur, avec les instructions et déclarations d’outils verrouillées dans le jeton par le Gateway. Les fournisseurs qui exposent uniquement un pont temps réel dorsal passent par le transport relais du Gateway, de sorte que les identifiants et les sockets fournisseur restent côté serveur tandis que l’audio du navigateur transite par des RPC Gateway authentifiés. L’invite de session Realtime est assemblée par le Gateway ; `talk.realtime.session` n’accepte pas les remplacements d’instructions fournis par l’appelant.
|
||||
|
||||
Dans le compositeur de chat, le contrôle Talk est le bouton à vagues à côté du bouton de dictée par microphone. Quand Talk démarre, la ligne d’état du compositeur affiche `Connecting Talk...`, puis `Talk live` pendant que l’audio est connecté, ou `Asking OpenClaw...` pendant qu’un appel d’outil temps réel consulte le modèle plus grand configuré via `chat.send`.
|
||||
Dans le compositeur de Chat, le contrôle Parler est le bouton à vagues à côté du bouton de dictée au microphone. Lorsque Parler démarre, la ligne d’état du compositeur affiche `Connecting Talk...`, puis `Talk live` pendant que l’audio est connecté, ou `Asking OpenClaw...` pendant qu’un appel d’outil temps réel consulte le modèle plus grand configuré via `chat.send`.
|
||||
|
||||
Smoke live mainteneur : `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` vérifie l’échange SDP WebRTC de navigateur OpenAI, la configuration WebSocket de navigateur avec jeton contraint Google Live, et l’adaptateur de navigateur relais du Gateway avec un média de microphone factice. La commande imprime uniquement l’état du fournisseur et ne journalise pas de secrets.
|
||||
Smoke en direct pour mainteneur : `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` vérifie l’échange SDP WebRTC navigateur d’OpenAI, la configuration WebSocket navigateur à jeton contraint de Google Live et l’adaptateur navigateur relais du Gateway avec un média de microphone simulé. La commande n’affiche que l’état du fournisseur et ne journalise pas les secrets.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Arrêter et interrompre">
|
||||
<Accordion title="Stop and abort">
|
||||
- Cliquez sur **Arrêter** (appelle `chat.abort`).
|
||||
- Pendant qu’une exécution est active, les suivis normaux sont mis en file d’attente. Cliquez sur **Orienter** sur un message en file d’attente pour injecter ce suivi dans le tour en cours.
|
||||
- Saisissez `/stop` (ou des phrases d’interruption autonomes comme `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) pour interrompre hors bande.
|
||||
- `chat.abort` prend en charge `{ sessionKey }` (sans `runId`) pour interrompre toutes les exécutions actives de cette session.
|
||||
- Saisissez `/stop` (ou des phrases d’abandon autonomes comme `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) pour abandonner hors bande.
|
||||
- `chat.abort` prend en charge `{ sessionKey }` (sans `runId`) pour abandonner toutes les exécutions actives de cette session.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Conservation partielle après interruption">
|
||||
- Quand une exécution est interrompue, le texte partiel de l’assistant peut toujours être affiché dans l’UI.
|
||||
- Le Gateway conserve le texte partiel de l’assistant interrompu dans l’historique de transcription quand une sortie mise en tampon existe.
|
||||
- Les entrées conservées incluent des métadonnées d’interruption afin que les consommateurs de transcription puissent distinguer les partiels interrompus de la sortie d’achèvement normale.
|
||||
<Accordion title="Abort partial retention">
|
||||
- Lorsqu’une exécution est abandonnée, le texte partiel de l’assistant peut tout de même être affiché dans l’interface utilisateur.
|
||||
- Le Gateway conserve le texte partiel d’assistant abandonné dans l’historique de transcription lorsqu’une sortie mise en mémoire tampon existe.
|
||||
- Les entrées conservées incluent des métadonnées d’abandon afin que les consommateurs de transcription puissent distinguer les fragments partiels abandonnés de la sortie d’achèvement normale.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Installation PWA et Web Push
|
||||
## Installation PWA et web push
|
||||
|
||||
L’UI de contrôle fournit un `manifest.webmanifest` et un service worker, afin que les navigateurs modernes puissent l’installer comme PWA autonome. Web Push permet au Gateway de réveiller la PWA installée avec des notifications même lorsque l’onglet ou la fenêtre du navigateur n’est pas ouvert.
|
||||
L’interface Control fournit un `manifest.webmanifest` et un service worker, ce qui permet aux navigateurs modernes de l’installer comme PWA autonome. Web Push permet au Gateway de réveiller la PWA installée avec des notifications même lorsque l’onglet ou la fenêtre du navigateur n’est pas ouvert.
|
||||
|
||||
| Surface | Ce que cela fait |
|
||||
| Surface | Ce qu’elle fait |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifeste PWA. Les navigateurs proposent « Installer l’application » dès qu’il est accessible. |
|
||||
| `ui/public/manifest.webmanifest` | Manifeste PWA. Les navigateurs proposent « Installer l’application » une fois qu’il est accessible. |
|
||||
| `ui/public/sw.js` | Service worker qui gère les événements `push` et les clics de notification. |
|
||||
| `push/vapid-keys.json` (sous le répertoire d’état OpenClaw) | Paire de clés VAPID générée automatiquement, utilisée pour signer les charges utiles Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Points de terminaison d’abonnement du navigateur conservés. |
|
||||
| `push/vapid-keys.json` (sous le répertoire d’état OpenClaw) | Paire de clés VAPID générée automatiquement utilisée pour signer les charges utiles Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Points de terminaison d’abonnement de navigateur conservés. |
|
||||
|
||||
Remplacez la paire de clés VAPID via des variables d’environnement sur le processus Gateway lorsque vous voulez figer les clés (pour des déploiements multi-hôtes, la rotation des secrets ou des tests) :
|
||||
Remplacez la paire de clés VAPID via des variables d’environnement sur le processus Gateway lorsque vous voulez épingler les clés (pour les déploiements multi-hôtes, la rotation des secrets ou les tests) :
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (par défaut `mailto:openclaw@localhost`)
|
||||
|
||||
L’UI de contrôle utilise ces méthodes Gateway limitées par portée pour enregistrer et tester les abonnements du navigateur :
|
||||
L’interface Control utilise ces méthodes Gateway limitées par portée pour enregistrer et tester les abonnements de navigateur :
|
||||
|
||||
- `push.web.vapidPublicKey` — récupère la clé publique VAPID active.
|
||||
- `push.web.subscribe` — enregistre un `endpoint` plus `keys.p256dh`/`keys.auth`.
|
||||
@ -218,18 +218,18 @@ L’UI de contrôle utilise ces méthodes Gateway limitées par portée pour enr
|
||||
- `push.web.test` — envoie une notification de test à l’abonnement de l’appelant.
|
||||
|
||||
<Note>
|
||||
Web Push est indépendant du chemin relais iOS APNS (voir [Configuration](/fr/gateway/configuration) pour le push adossé à un relais) et de la méthode existante `push.test`, qui ciblent l’appairage mobile natif.
|
||||
Web Push est indépendant du chemin relais APNS iOS (voir [Configuration](/fr/gateway/configuration) pour le push adossé à un relais) et de la méthode `push.test` existante, qui ciblent l’appairage mobile natif.
|
||||
</Note>
|
||||
|
||||
## Intégrations hébergées
|
||||
|
||||
Les messages de l’assistant peuvent afficher du contenu web hébergé inline avec le shortcode `[embed ...]`. La politique sandbox de l’iframe est contrôlée par `gateway.controlUi.embedSandbox` :
|
||||
Les messages d’assistant peuvent afficher du contenu web hébergé en ligne avec le shortcode `[embed ...]`. La politique de sandbox iframe est contrôlée par `gateway.controlUi.embedSandbox` :
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Désactive l’exécution de scripts dans les intégrations hébergées.
|
||||
</Tab>
|
||||
<Tab title="scripts (par défaut)">
|
||||
<Tab title="scripts (default)">
|
||||
Autorise les intégrations interactives tout en conservant l’isolation d’origine ; c’est la valeur par défaut et elle suffit généralement pour les jeux/widgets de navigateur autonomes.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
@ -250,14 +250,14 @@ Exemple :
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Utilisez `trusted` uniquement quand le document intégré a réellement besoin d’un comportement même origine. Pour la plupart des jeux et canevas interactifs générés par l’agent, `scripts` est le choix le plus sûr.
|
||||
Utilisez `trusted` uniquement lorsque le document intégré a réellement besoin du comportement même origine. Pour la plupart des jeux générés par agent et des canevas interactifs, `scripts` est le choix le plus sûr.
|
||||
</Warning>
|
||||
|
||||
Les URL d’intégration externes absolues `http(s)` restent bloquées par défaut. Si vous voulez intentionnellement que `[embed url="https://..."]` charge des pages tierces, définissez `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Largeur des messages de chat
|
||||
|
||||
Les messages de chat groupés utilisent une largeur maximale lisible par défaut. Les déploiements sur écrans larges peuvent la remplacer sans modifier le CSS groupé en définissant `gateway.controlUi.chatMessageMaxWidth` :
|
||||
Les messages de chat groupés utilisent une largeur maximale lisible par défaut. Les déploiements sur grands écrans peuvent la remplacer sans modifier le CSS fourni en définissant `gateway.controlUi.chatMessageMaxWidth` :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,8 +274,8 @@ La valeur est validée avant d’atteindre le navigateur. Les valeurs prises en
|
||||
## Accès tailnet (recommandé)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve intégré (préféré)">
|
||||
Gardez le Gateway sur local loopback et laissez Tailscale Serve le mandater avec HTTPS :
|
||||
<Tab title="Integrated Tailscale Serve (preferred)">
|
||||
Gardez le Gateway sur loopback et laissez Tailscale Serve le relayer avec HTTPS :
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,46 +285,46 @@ La valeur est validée avant d’atteindre le navigateur. Les valeurs prises en
|
||||
|
||||
- `https://<magicdns>/` (ou votre `gateway.controlUi.basePath` configuré)
|
||||
|
||||
Par défaut, les requêtes Control UI/WebSocket Serve peuvent s’authentifier via les en-têtes d’identité Tailscale (`tailscale-user-login`) quand `gateway.auth.allowTailscale` vaut `true`. OpenClaw vérifie l’identité en résolvant l’adresse `x-forwarded-for` avec `tailscale whois` et en la faisant correspondre à l’en-tête, et n’accepte ces requêtes que lorsqu’elles atteignent local loopback avec les en-têtes `x-forwarded-*` de Tailscale. Pour les sessions d’opérateur de l’UI de contrôle avec identité d’appareil du navigateur, ce chemin Serve vérifié saute aussi l’aller-retour d’appairage de l’appareil ; les navigateurs sans appareil et les connexions de rôle de nœud suivent toujours les vérifications d’appareil normales. Définissez `gateway.auth.allowTailscale: false` si vous voulez exiger des identifiants explicites à secret partagé même pour le trafic Serve. Utilisez ensuite `gateway.auth.mode: "token"` ou `"password"`.
|
||||
Par défaut, les requêtes Serve de l’interface Control/WebSocket peuvent s’authentifier via les en-têtes d’identité Tailscale (`tailscale-user-login`) lorsque `gateway.auth.allowTailscale` est `true`. OpenClaw vérifie l’identité en résolvant l’adresse `x-forwarded-for` avec `tailscale whois` et en la faisant correspondre à l’en-tête, et n’accepte ces requêtes que lorsqu’elles atteignent loopback avec les en-têtes `x-forwarded-*` de Tailscale. Pour les sessions opérateur de l’interface Control avec identité d’appareil de navigateur, ce chemin Serve vérifié saute également l’aller-retour d’appairage d’appareil ; les navigateurs sans appareil et les connexions de rôle de nœud suivent toujours les vérifications d’appareil normales. Définissez `gateway.auth.allowTailscale: false` si vous voulez exiger des identifiants explicites à secret partagé même pour le trafic Serve. Utilisez ensuite `gateway.auth.mode: "token"` ou `"password"`.
|
||||
|
||||
Pour ce chemin d’identité Serve asynchrone, les tentatives d’authentification échouées pour la même IP client et la même portée d’authentification sont sérialisées avant les écritures de limitation de débit. Les nouvelles tentatives erronées simultanées depuis le même navigateur peuvent donc afficher `retry later` à la deuxième requête au lieu de deux incompatibilités simples en concurrence parallèle.
|
||||
Pour ce chemin d’identité Serve asynchrone, les tentatives d’authentification échouées pour la même IP cliente et la même portée d’authentification sont sérialisées avant les écritures de limitation de débit. Des nouvelles tentatives incorrectes simultanées depuis le même navigateur peuvent donc afficher `retry later` sur la deuxième requête au lieu de deux non-correspondances simples en concurrence parallèle.
|
||||
|
||||
<Warning>
|
||||
L’authentification Serve sans jeton suppose que l’hôte gateway est fiable. Si du code local non fiable peut s’exécuter sur cet hôte, exigez une authentification par jeton/mot de passe.
|
||||
L’authentification Serve sans jeton suppose que l’hôte du Gateway est fiable. Si du code local non fiable peut s’exécuter sur cet hôte, exigez une authentification par jeton/mot de passe.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Lier au tailnet + jeton">
|
||||
<Tab title="Bind to tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
Ouvrez ensuite :
|
||||
Puis ouvrez :
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (ou votre `gateway.controlUi.basePath` configuré)
|
||||
|
||||
Collez le secret partagé correspondant dans les paramètres de l’UI (envoyé comme `connect.params.auth.token` ou `connect.params.auth.password`).
|
||||
Collez le secret partagé correspondant dans les paramètres de l’interface utilisateur (envoyé comme `connect.params.auth.token` ou `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## HTTP non sécurisé
|
||||
|
||||
Si vous ouvrez le tableau de bord via HTTP en clair (`http://<lan-ip>` ou `http://<tailscale-ip>`), le navigateur s’exécute dans un **contexte non sécurisé** et bloque WebCrypto. Par défaut, OpenClaw **bloque** les connexions de l’UI de contrôle sans identité d’appareil.
|
||||
Si vous ouvrez le tableau de bord via HTTP simple (`http://<lan-ip>` ou `http://<tailscale-ip>`), le navigateur s’exécute dans un **contexte non sécurisé** et bloque WebCrypto. Par défaut, OpenClaw **bloque** les connexions de l’interface Control sans identité d’appareil.
|
||||
|
||||
Exceptions documentées :
|
||||
|
||||
- compatibilité HTTP non sécurisée limitée à localhost avec `gateway.controlUi.allowInsecureAuth=true`
|
||||
- authentification réussie de l’UI de contrôle opérateur via `gateway.auth.mode: "trusted-proxy"`
|
||||
- option d’urgence `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- compatibilité HTTP non sécurisé limitée à localhost avec `gateway.controlUi.allowInsecureAuth=true`
|
||||
- authentification opérateur réussie de l’interface Control via `gateway.auth.mode: "trusted-proxy"`
|
||||
- option de dernier recours `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Correction recommandée :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’UI localement :
|
||||
**Correctif recommandé :** utilisez HTTPS (Tailscale Serve) ou ouvrez l’interface localement :
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (sur l’hôte du Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Comportement du basculement d’authentification non sécurisée">
|
||||
<Accordion title="Comportement du basculeur d’authentification non sécurisée">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -335,14 +335,14 @@ Exceptions documentées :
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` est uniquement un basculement de compatibilité locale :
|
||||
`allowInsecureAuth` est uniquement un basculeur de compatibilité locale :
|
||||
|
||||
- Il permet aux sessions Control UI localhost de continuer sans identité d’appareil dans les contextes HTTP non sécurisés.
|
||||
- Il permet aux sessions de l’interface de contrôle localhost de continuer sans identité d’appareil dans des contextes HTTP non sécurisés.
|
||||
- Il ne contourne pas les vérifications d’appairage.
|
||||
- Il n’assouplit pas les exigences d’identité d’appareil distant (non-localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Utilisation d’urgence uniquement">
|
||||
<Accordion title="Solution d’urgence uniquement">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,44 +354,54 @@ Exceptions documentées :
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` désactive les vérifications d’identité d’appareil de la Control UI et constitue une dégradation sévère de la sécurité. Rétablissez rapidement la configuration après une utilisation d’urgence.
|
||||
`dangerouslyDisableDeviceAuth` désactive les vérifications d’identité d’appareil de l’interface de contrôle et constitue une forte dégradation de la sécurité. Rétablissez rapidement le réglage après une utilisation d’urgence.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Note sur le proxy de confiance">
|
||||
- Une authentification par proxy de confiance réussie peut admettre des sessions Control UI **opérateur** sans identité d’appareil.
|
||||
- Cela ne s’étend **pas** aux sessions Control UI avec rôle de nœud.
|
||||
- Les proxys inverses loopback sur le même hôte ne satisfont toujours pas l’authentification par proxy de confiance ; consultez [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth).
|
||||
- Une authentification de proxy de confiance réussie peut autoriser des sessions d’interface de contrôle **opérateur** sans identité d’appareil.
|
||||
- Cela ne s’étend **pas** aux sessions d’interface de contrôle avec rôle de nœud.
|
||||
- Les proxys inverses local loopback sur le même hôte ne satisfont toujours pas l’authentification de proxy de confiance ; consultez [Authentification par proxy de confiance](/fr/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Consultez [Tailscale](/fr/gateway/tailscale) pour des conseils de configuration HTTPS.
|
||||
Consultez [Tailscale](/fr/gateway/tailscale) pour les instructions de configuration HTTPS.
|
||||
|
||||
## Politique de sécurité du contenu
|
||||
|
||||
La Control UI est fournie avec une politique `img-src` stricte : seuls les éléments **same-origin**, les URL `data:` et les URL `blob:` générées localement sont autorisés. Les URL d’images distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et ne déclenchent aucune requête réseau.
|
||||
L’interface de contrôle est livrée avec une politique `img-src` stricte : seuls les ressources de **même origine**, les URL `data:` et les URL `blob:` générées localement sont autorisées. Les URL d’images distantes `http(s)` et relatives au protocole sont rejetées par le navigateur et ne déclenchent aucune requête réseau.
|
||||
|
||||
Ce que cela signifie en pratique :
|
||||
|
||||
- Les avatars et images servis sous des chemins relatifs (par exemple `/avatars/<id>`) s’affichent toujours, y compris les routes d’avatars authentifiées que l’UI récupère et convertit en URL `blob:` locales.
|
||||
- Les URL inline `data:image/...` s’affichent toujours (utile pour les charges utiles intégrées au protocole).
|
||||
- Les URL `blob:` locales créées par la Control UI s’affichent toujours.
|
||||
- Les URL d’avatars distantes émises par les métadonnées de canal sont supprimées par les helpers d’avatar de la Control UI et remplacées par le logo/badge intégré, afin qu’un canal compromis ou malveillant ne puisse pas forcer des récupérations d’images distantes arbitraires depuis le navigateur d’un opérateur.
|
||||
- Les avatars et les images servis sous des chemins relatifs (par exemple `/avatars/<id>`) s’affichent toujours, y compris les routes d’avatars authentifiées que l’interface récupère et convertit en URL `blob:` locales.
|
||||
- Les URL inline `data:image/...` s’affichent toujours (utile pour les charges utiles dans le protocole).
|
||||
- Les URL `blob:` locales créées par l’interface de contrôle s’affichent toujours.
|
||||
- Les URL d’avatar distantes émises par les métadonnées de canal sont retirées par les assistants d’avatar de l’interface de contrôle et remplacées par le logo/badge intégré, de sorte qu’un canal compromis ou malveillant ne puisse pas forcer des récupérations d’images distantes arbitraires depuis le navigateur d’un opérateur.
|
||||
|
||||
Vous n’avez rien à changer pour obtenir ce comportement — il est toujours activé et n’est pas configurable.
|
||||
Vous n’avez rien à changer pour obtenir ce comportement : il est toujours activé et n’est pas configurable.
|
||||
|
||||
## Authentification de la route d’avatar
|
||||
|
||||
Lorsque l’authentification du Gateway est configurée, le point de terminaison d’avatar de la Control UI exige le même jeton de Gateway que le reste de l’API :
|
||||
Lorsque l’authentification du Gateway est configurée, le point de terminaison d’avatar de l’interface de contrôle exige le même jeton Gateway que le reste de l’API :
|
||||
|
||||
- `GET /avatar/<agentId>` renvoie l’image d’avatar uniquement aux appelants authentifiés. `GET /avatar/<agentId>?meta=1` renvoie les métadonnées de l’avatar selon la même règle.
|
||||
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme pour la route sœur assistant-media). Cela empêche la route d’avatar de divulguer l’identité de l’agent sur des hôtes autrement protégés.
|
||||
- La Control UI elle-même transmet le jeton du Gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URL blob authentifiées afin que l’image s’affiche toujours dans les tableaux de bord.
|
||||
- Les requêtes non authentifiées vers l’une ou l’autre route sont rejetées (comme la route sœur assistant-media). Cela empêche la route d’avatar de divulguer l’identité de l’agent sur des hôtes qui sont autrement protégés.
|
||||
- L’interface de contrôle transmet elle-même le jeton Gateway comme en-tête bearer lors de la récupération des avatars, et utilise des URL blob authentifiées afin que l’image s’affiche toujours dans les tableaux de bord.
|
||||
|
||||
Si vous désactivez l’authentification du Gateway (ce qui est déconseillé sur les hôtes partagés), la route d’avatar devient également non authentifiée, comme le reste du Gateway.
|
||||
Si vous désactivez l’authentification du Gateway (non recommandé sur les hôtes partagés), la route d’avatar devient également non authentifiée, conformément au reste du Gateway.
|
||||
|
||||
## Construction de l’UI
|
||||
## Authentification de la route des médias de l’assistant
|
||||
|
||||
Lorsque l’authentification du Gateway est configurée, les aperçus de médias locaux de l’assistant utilisent une route en deux étapes :
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` exige l’authentification opérateur normale de l’interface de contrôle. Le navigateur envoie le jeton Gateway comme en-tête bearer lors de la vérification de disponibilité.
|
||||
- Les réponses de métadonnées réussies incluent un `mediaTicket` de courte durée limité à ce chemin source exact.
|
||||
- Les URL d’image, d’audio, de vidéo et de document rendues par le navigateur utilisent `mediaTicket=<ticket>` au lieu du jeton Gateway actif ou du mot de passe. Le ticket expire rapidement et ne peut pas autoriser une source différente.
|
||||
|
||||
Cela rend le rendu normal des médias compatible avec les éléments multimédias natifs du navigateur sans placer d’identifiants Gateway réutilisables dans des URL de médias visibles.
|
||||
|
||||
## Construction de l’interface
|
||||
|
||||
Le Gateway sert les fichiers statiques depuis `dist/control-ui`. Construisez-les avec :
|
||||
|
||||
@ -399,7 +409,7 @@ Le Gateway sert les fichiers statiques depuis `dist/control-ui`. Construisez-les
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Base absolue facultative (lorsque vous voulez des URL d’assets fixes) :
|
||||
Base absolue facultative (lorsque vous voulez des URL de ressources fixes) :
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
@ -411,14 +421,14 @@ Pour le développement local (serveur de développement séparé) :
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Pointez ensuite l’UI vers l’URL WS de votre Gateway (par exemple `ws://127.0.0.1:18789`).
|
||||
Pointez ensuite l’interface vers votre URL WS du Gateway (par exemple `ws://127.0.0.1:18789`).
|
||||
|
||||
## Débogage/test : serveur de développement + Gateway distant
|
||||
## Débogage/tests : serveur de développement + Gateway distant
|
||||
|
||||
La Control UI est composée de fichiers statiques ; la cible WebSocket est configurable et peut être différente de l’origine HTTP. C’est pratique lorsque vous voulez utiliser le serveur de développement Vite localement, mais que le Gateway s’exécute ailleurs.
|
||||
L’interface de contrôle est constituée de fichiers statiques ; la cible WebSocket est configurable et peut être différente de l’origine HTTP. C’est pratique lorsque vous voulez le serveur de développement Vite localement, mais que le Gateway s’exécute ailleurs.
|
||||
|
||||
<Steps>
|
||||
<Step title="Démarrer le serveur de développement de l’UI">
|
||||
<Step title="Démarrer le serveur de développement de l’interface">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -439,17 +449,17 @@ La Control UI est composée de fichiers statiques ; la cible WebSocket est confi
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notes">
|
||||
- `gatewayUrl` est stocké dans localStorage après le chargement et retiré de l’URL.
|
||||
- Si vous transmettez un point de terminaison `ws://` ou `wss://` complet via `gatewayUrl`, encodez en URL la valeur de `gatewayUrl` afin que le navigateur analyse correctement la chaîne de requête.
|
||||
- `token` doit être transmis via le fragment d’URL (`#token=...`) chaque fois que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites dans les journaux de requêtes et le Referer. Les anciens paramètres de requête `?token=` sont encore importés une fois pour compatibilité, mais uniquement comme solution de repli, et sont supprimés immédiatement après l’amorçage.
|
||||
- `gatewayUrl` est stocké dans localStorage après le chargement et supprimé de l’URL.
|
||||
- Si vous transmettez un point de terminaison complet `ws://` ou `wss://` via `gatewayUrl`, encodez en URL la valeur `gatewayUrl` afin que le navigateur analyse correctement la chaîne de requête.
|
||||
- `token` doit être transmis via le fragment d’URL (`#token=...`) chaque fois que possible. Les fragments ne sont pas envoyés au serveur, ce qui évite les fuites dans les journaux de requêtes et le Referer. Les paramètres de requête hérités `?token=` sont encore importés une fois par compatibilité, mais uniquement comme solution de repli, et sont supprimés immédiatement après l’amorçage.
|
||||
- `password` est conservé uniquement en mémoire.
|
||||
- Lorsque `gatewayUrl` est défini, l’UI ne se rabat pas sur les identifiants de configuration ou d’environnement. Fournissez explicitement `token` (ou `password`). L’absence d’identifiants explicites est une erreur.
|
||||
- Lorsque `gatewayUrl` est défini, l’interface ne se rabat pas sur les identifiants de configuration ou d’environnement. Fournissez explicitement `token` (ou `password`). L’absence d’identifiants explicites est une erreur.
|
||||
- Utilisez `wss://` lorsque le Gateway est derrière TLS (Tailscale Serve, proxy HTTPS, etc.).
|
||||
- `gatewayUrl` n’est accepté que dans une fenêtre de premier niveau (non intégrée) afin d’empêcher le clickjacking.
|
||||
- Les déploiements Control UI non-loopback doivent définir explicitement `gateway.controlUi.allowedOrigins` (origines complètes). Cela inclut les configurations de développement distantes.
|
||||
- Le démarrage du Gateway peut initialiser des origines locales telles que `http://localhost:<port>` et `http://127.0.0.1:<port>` à partir du bind et du port effectifs à l’exécution, mais les origines de navigateurs distants nécessitent toujours des entrées explicites.
|
||||
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]` sauf pour des tests locaux strictement contrôlés. Cela signifie autoriser n’importe quelle origine de navigateur, pas « correspondre à l’hôte que j’utilise ».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` active le mode de repli d’origine basé sur l’en-tête Host, mais c’est un mode de sécurité dangereux.
|
||||
- Les déploiements non-loopback de l’interface de contrôle doivent définir explicitement `gateway.controlUi.allowedOrigins` (origines complètes). Cela inclut les configurations de développement distantes.
|
||||
- Le démarrage du Gateway peut initialiser des origines locales comme `http://localhost:<port>` et `http://127.0.0.1:<port>` à partir de l’adresse de liaison et du port d’exécution effectifs, mais les origines de navigateurs distants nécessitent toujours des entrées explicites.
|
||||
- N’utilisez pas `gateway.controlUi.allowedOrigins: ["*"]` sauf pour des tests locaux strictement contrôlés. Cela signifie autoriser n’importe quelle origine de navigateur, et non « correspondre à l’hôte que j’utilise ».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` active le mode de repli d’origine par en-tête Host, mais c’est un mode de sécurité dangereux.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -468,9 +478,9 @@ Exemple :
|
||||
|
||||
Détails de configuration de l’accès distant : [Accès distant](/fr/gateway/remote).
|
||||
|
||||
## Associés
|
||||
## Liens connexes
|
||||
|
||||
- [Tableau de bord](/fr/web/dashboard) — tableau de bord du Gateway
|
||||
- [Contrôles de santé](/fr/gateway/health) — surveillance de la santé du Gateway
|
||||
- [TUI](/fr/web/tui) — interface utilisateur de terminal
|
||||
- [WebChat](/fr/web/webchat) — interface de chat basée sur le navigateur
|
||||
- [Contrôles d’état](/fr/gateway/health) — surveillance de l’état du Gateway
|
||||
- [TUI](/fr/web/tui) — interface utilisateur en terminal
|
||||
- [WebChat](/fr/web/webchat) — interface de chat dans le navigateur
|
||||
|
||||
Loading…
Reference in New Issue
Block a user