chore(i18n): refresh fr translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
e15305352a
commit
d21630456e
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Inspection du travail en arrière-plan en cours ou récemment terminé
|
||||
- Débogage des échecs de livraison pour les exécutions d'agent détachées
|
||||
- Compréhension de la relation entre les exécutions en arrière-plan, les sessions, cron et heartbeat
|
||||
- Débogage des échecs de livraison pour les exécutions d’agent détachées
|
||||
- Comprendre comment les exécutions en arrière-plan sont liées aux sessions, aux tâches cron et au signal de pulsation
|
||||
summary: Suivi des tâches en arrière-plan pour les exécutions ACP, les sous-agents, les tâches cron isolées et les opérations CLI
|
||||
title: Tâches en arrière-plan
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:38Z"
|
||||
generated_at: "2026-04-10T06:56:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
|
||||
source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
|
||||
source_path: automation/tasks.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,29 +18,25 @@ x-i18n:
|
||||
|
||||
> **Vous cherchez la planification ?** Consultez [Automatisation et tâches](/fr/automation) pour choisir le bon mécanisme. Cette page couvre le **suivi** du travail en arrière-plan, pas sa planification.
|
||||
|
||||
Les tâches en arrière-plan suivent le travail qui s'exécute **en dehors de votre session de conversation principale** :
|
||||
Les tâches en arrière-plan suivent le travail qui s’exécute **en dehors de votre session de conversation principale** :
|
||||
les exécutions ACP, les lancements de sous-agents, les exécutions de tâches cron isolées et les opérations initiées par la CLI.
|
||||
|
||||
Les tâches ne remplacent **pas** les sessions, les tâches cron ou les heartbeat — elles constituent le **journal d'activité** qui enregistre quel travail détaché a eu lieu, quand, et s'il a réussi.
|
||||
Les tâches ne **remplacent pas** les sessions, les tâches cron ou les signaux de pulsation — elles constituent le **journal d’activité** qui enregistre quel travail détaché a eu lieu, quand, et s’il a réussi.
|
||||
|
||||
<Note>
|
||||
Toutes les exécutions d'agent ne créent pas une tâche. Les tours de heartbeat et le chat interactif normal n'en créent pas. Toutes les exécutions cron, tous les lancements ACP, tous les lancements de sous-agents et toutes les commandes d'agent CLI en créent.
|
||||
Toutes les exécutions d’agent ne créent pas une tâche. Les tours de signal de pulsation et le chat interactif normal n’en créent pas. Toutes les exécutions cron, tous les lancements ACP, tous les lancements de sous-agents et toutes les commandes d’agent via la CLI en créent.
|
||||
</Note>
|
||||
|
||||
## En bref
|
||||
## TL;DR
|
||||
|
||||
- Les tâches sont des **enregistrements**, pas des planificateurs — cron et heartbeat décident _quand_ le travail s'exécute, les tâches suivent _ce qui s'est passé_.
|
||||
- ACP, les sous-agents, toutes les tâches cron et les opérations CLI créent des tâches. Les tours de heartbeat n'en créent pas.
|
||||
- Les tâches sont des **enregistrements**, pas des planificateurs — cron et le signal de pulsation décident _quand_ le travail s’exécute, les tâches suivent _ce qui s’est passé_.
|
||||
- ACP, les sous-agents, toutes les tâches cron et les opérations CLI créent des tâches. Les tours de signal de pulsation n’en créent pas.
|
||||
- Chaque tâche passe par `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` ou `lost`).
|
||||
- Les tâches cron restent actives tant que l'environnement d'exécution cron possède encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d'exécution propriétaire est encore actif.
|
||||
- L'achèvement est piloté par poussée : le travail détaché peut notifier directement ou réveiller
|
||||
la session demandeuse/le heartbeat lorsqu'il se termine, donc les boucles de
|
||||
sondage de statut ont généralement une mauvaise forme.
|
||||
- Les exécutions cron isolées et les achèvements de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant le nettoyage final de comptabilisation.
|
||||
- La livraison des exécutions cron isolées supprime les réponses intermédiaires parentes obsolètes pendant que le
|
||||
travail de sous-agents descendants continue de s'écouler, et elle préfère la sortie finale descendante
|
||||
lorsqu'elle arrive avant la livraison.
|
||||
- Les notifications d'achèvement sont envoyées directement à un canal ou mises en file d'attente pour le prochain heartbeat.
|
||||
- Les tâches cron restent actives tant que l’environnement d’exécution cron possède encore la tâche ; les tâches CLI adossées au chat restent actives uniquement tant que leur contexte d’exécution propriétaire est encore actif.
|
||||
- La fin d’exécution est pilotée par envoi : le travail détaché peut notifier directement ou réveiller la session/le signal de pulsation du demandeur lorsqu’il se termine, donc les boucles d’interrogation d’état sont généralement une mauvaise approche.
|
||||
- Les exécutions cron isolées et les fins d’exécution de sous-agents nettoient au mieux les onglets/processus de navigateur suivis pour leur session enfant avant le nettoyage final.
|
||||
- La livraison des exécutions cron isolées supprime les réponses intermédiaires parent obsolètes pendant que le travail des sous-agents descendants est encore en cours de vidage, et elle privilégie la sortie finale descendante lorsqu’elle arrive avant la livraison.
|
||||
- Les notifications de fin d’exécution sont livrées directement à un canal ou mises en file d’attente pour le prochain signal de pulsation.
|
||||
- `openclaw tasks list` affiche toutes les tâches ; `openclaw tasks audit` fait remonter les problèmes.
|
||||
- Les enregistrements terminaux sont conservés pendant 7 jours, puis automatiquement supprimés.
|
||||
|
||||
@ -50,17 +46,17 @@ Toutes les exécutions d'agent ne créent pas une tâche. Les tours de heartbeat
|
||||
# Lister toutes les tâches (de la plus récente à la plus ancienne)
|
||||
openclaw tasks list
|
||||
|
||||
# Filtrer par environnement d'exécution ou statut
|
||||
# Filtrer par environnement d’exécution ou statut
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
|
||||
# Afficher les détails d'une tâche spécifique (par ID, ID d'exécution ou clé de session)
|
||||
# Afficher les détails d’une tâche spécifique (par ID, ID d’exécution ou clé de session)
|
||||
openclaw tasks show <lookup>
|
||||
|
||||
# Annuler une tâche en cours (tue la session enfant)
|
||||
# Annuler une tâche en cours d’exécution (tue la session enfant)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# Modifier la politique de notification pour une tâche
|
||||
# Modifier la politique de notification d’une tâche
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
|
||||
# Exécuter un audit de santé
|
||||
@ -70,7 +66,7 @@ openclaw tasks audit
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# Inspecter l'état de TaskFlow
|
||||
# Inspecter l’état de TaskFlow
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
@ -78,86 +74,84 @@ openclaw tasks flow cancel <lookup>
|
||||
|
||||
## Ce qui crée une tâche
|
||||
|
||||
| Source | Type d'exécution | Moment de création d'un enregistrement de tâche | Politique de notification par défaut |
|
||||
| ------------------------ | ---------------- | ------------------------------------------------------ | ------------------------------------ |
|
||||
| Exécutions ACP en arrière-plan | `acp` | Lancement d'une session enfant ACP | `done_only` |
|
||||
| Orchestration de sous-agents | `subagent` | Lancement d'un sous-agent via `sessions_spawn` | `done_only` |
|
||||
| Tâches cron (tous types) | `cron` | Chaque exécution cron (session principale et isolée) | `silent` |
|
||||
| Opérations CLI | `cli` | Commandes `openclaw agent` qui passent par la gateway | `silent` |
|
||||
| Tâches média de l'agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
|
||||
| Source | Type d’environnement d’exécution | Moment où un enregistrement de tâche est créé | Politique de notification par défaut |
|
||||
| ---------------------- | -------------------------------- | ------------------------------------------------------ | ------------------------------------ |
|
||||
| Exécutions ACP en arrière-plan | `acp` | Lancement d’une session ACP enfant | `done_only` |
|
||||
| Orchestration de sous-agents | `subagent` | Lancement d’un sous-agent via `sessions_spawn` | `done_only` |
|
||||
| Tâches cron (tous types) | `cron` | Chaque exécution cron (session principale et isolée) | `silent` |
|
||||
| Opérations CLI | `cli` | Commandes `openclaw agent` exécutées via la passerelle | `silent` |
|
||||
| Tâches média d’agent | `cli` | Exécutions `video_generate` adossées à une session | `silent` |
|
||||
|
||||
Les tâches cron de session principale utilisent `silent` comme politique de notification par défaut — elles créent des enregistrements pour le suivi mais ne génèrent pas de notifications. Les tâches cron isolées utilisent aussi `silent` par défaut, mais elles sont plus visibles car elles s'exécutent dans leur propre session.
|
||||
Les tâches cron de session principale utilisent par défaut la politique de notification `silent` — elles créent des enregistrements pour le suivi mais ne génèrent pas de notifications. Les tâches cron isolées utilisent aussi `silent` par défaut, mais sont plus visibles parce qu’elles s’exécutent dans leur propre session.
|
||||
|
||||
Les exécutions `video_generate` adossées à une session utilisent également `silent` comme politique de notification. Elles créent tout de même des enregistrements de tâche, mais l'achèvement est renvoyé à la session d'agent d'origine sous forme de réveil interne afin que l'agent puisse écrire le message de suivi et joindre lui-même la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les achèvements asynchrones de `music_generate` et `video_generate` essaient d'abord la livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
|
||||
Les exécutions `video_generate` adossées à une session utilisent également la politique de notification `silent`. Elles créent tout de même des enregistrements de tâche, mais la fin d’exécution est renvoyée à la session d’agent d’origine sous forme de réveil interne afin que l’agent puisse lui-même écrire le message de suivi et joindre la vidéo terminée. Si vous activez `tools.media.asyncCompletion.directSend`, les fins d’exécution asynchrones de `music_generate` et `video_generate` tentent d’abord une livraison directe au canal avant de revenir au chemin de réveil de la session demandeuse.
|
||||
|
||||
Tant qu'une tâche `video_generate` adossée à une session est encore active, l'outil agit aussi comme garde-fou : les appels répétés à `video_generate` dans cette même session renvoient le statut de la tâche active au lieu de démarrer une deuxième génération concurrente. Utilisez `action: "status"` lorsque vous voulez une consultation explicite de progression/statut côté agent.
|
||||
Tant qu’une tâche `video_generate` adossée à une session est encore active, l’outil sert aussi de garde-fou : des appels `video_generate` répétés dans cette même session renvoient le statut de la tâche active au lieu de démarrer une deuxième génération concurrente. Utilisez `action: "status"` si vous voulez une consultation explicite de progression/statut côté agent.
|
||||
|
||||
**Ce qui ne crée pas de tâches :**
|
||||
|
||||
- Les tours de heartbeat — session principale ; voir [Heartbeat](/fr/gateway/heartbeat)
|
||||
- Les tours de signal de pulsation — session principale ; voir [Signal de pulsation](/fr/gateway/heartbeat)
|
||||
- Les tours de chat interactif normaux
|
||||
- Les réponses directes à `/command`
|
||||
- Les réponses directes `/command`
|
||||
|
||||
## Cycle de vie d'une tâche
|
||||
## Cycle de vie d’une tâche
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> queued
|
||||
queued --> running : l'agent démarre
|
||||
queued --> running : l’agent démarre
|
||||
running --> succeeded : se termine correctement
|
||||
running --> failed : erreur
|
||||
running --> timed_out : délai d'attente dépassé
|
||||
running --> cancelled : l'opérateur annule
|
||||
running --> timed_out : délai dépassé
|
||||
running --> cancelled : l’opérateur annule
|
||||
queued --> lost : session disparue > 5 min
|
||||
running --> lost : session disparue > 5 min
|
||||
```
|
||||
|
||||
| Statut | Ce qu'il signifie |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| `queued` | Créée, en attente du démarrage de l'agent |
|
||||
| `running` | Le tour de l'agent est en cours d'exécution |
|
||||
| `succeeded` | Terminée avec succès |
|
||||
| `failed` | Terminée avec une erreur |
|
||||
| `timed_out` | A dépassé le délai d'attente configuré |
|
||||
| `cancelled` | Arrêtée par l'opérateur via `openclaw tasks cancel` |
|
||||
| `lost` | L'environnement d'exécution a perdu l'état d'autorité de référence après un délai de grâce de 5 minutes |
|
||||
| Statut | Ce que cela signifie |
|
||||
| ----------- | ------------------------------------------------------------------------ |
|
||||
| `queued` | Créée, en attente du démarrage de l’agent |
|
||||
| `running` | Le tour de l’agent est en cours d’exécution |
|
||||
| `succeeded` | Terminée avec succès |
|
||||
| `failed` | Terminée avec une erreur |
|
||||
| `timed_out` | A dépassé le délai configuré |
|
||||
| `cancelled` | Arrêtée par l’opérateur via `openclaw tasks cancel` |
|
||||
| `lost` | L’environnement d’exécution a perdu l’état de support faisant autorité après une période de grâce de 5 minutes |
|
||||
|
||||
Les transitions se produisent automatiquement — lorsque l'exécution d'agent associée se termine, le statut de la tâche est mis à jour pour correspondre.
|
||||
Les transitions se produisent automatiquement — lorsque l’exécution d’agent associée se termine, le statut de la tâche est mis à jour pour correspondre.
|
||||
|
||||
`lost` dépend de l'environnement d'exécution :
|
||||
`lost` dépend de l’environnement d’exécution :
|
||||
|
||||
- Tâches ACP : les métadonnées de la session enfant ACP de référence ont disparu.
|
||||
- Tâches de sous-agent : la session enfant de référence a disparu du magasin de l'agent cible.
|
||||
- Tâches cron : l'environnement d'exécution cron ne suit plus la tâche comme active.
|
||||
- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent à la place le contexte d'exécution actif, donc des lignes persistantes de session canal/groupe/direct ne les maintiennent pas actives.
|
||||
- Tâches ACP : les métadonnées de la session ACP enfant de support ont disparu.
|
||||
- Tâches de sous-agents : la session enfant de support a disparu du stockage de l’agent cible.
|
||||
- Tâches cron : l’environnement d’exécution cron ne suit plus la tâche comme active.
|
||||
- Tâches CLI : les tâches de session enfant isolée utilisent la session enfant ; les tâches CLI adossées au chat utilisent à la place le contexte d’exécution actif, donc des lignes persistantes de session canal/groupe/direct ne les maintiennent pas actives.
|
||||
|
||||
## Livraison et notifications
|
||||
|
||||
Lorsqu'une tâche atteint un état terminal, OpenClaw vous notifie. Il existe deux chemins de livraison :
|
||||
Lorsqu’une tâche atteint un état terminal, OpenClaw vous en informe. Il existe deux chemins de livraison :
|
||||
|
||||
**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message d'achèvement est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les achèvements de sous-agents, OpenClaw préserve aussi le routage lié de fil/sujet quand il est disponible et peut renseigner un `to` / compte manquant à partir de la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d'abandonner la livraison directe.
|
||||
**Livraison directe** — si la tâche a une cible de canal (le `requesterOrigin`), le message de fin d’exécution est envoyé directement à ce canal (Telegram, Discord, Slack, etc.). Pour les fins d’exécution de sous-agents, OpenClaw préserve également le routage de fil/topic lié lorsqu’il est disponible et peut compléter un `to` / compte manquant à partir de la route stockée de la session demandeuse (`lastChannel` / `lastTo` / `lastAccountId`) avant d’abandonner la livraison directe.
|
||||
|
||||
**Livraison mise en file d'attente dans la session** — si la livraison directe échoue ou si aucune origine n'est définie, la mise à jour est mise en file d'attente comme événement système dans la session du demandeur et apparaît au prochain heartbeat.
|
||||
**Livraison mise en file dans la session** — si la livraison directe échoue ou si aucune origine n’est définie, la mise à jour est mise en file d’attente comme événement système dans la session du demandeur et apparaît au prochain signal de pulsation.
|
||||
|
||||
<Tip>
|
||||
L'achèvement d'une tâche déclenche un réveil immédiat du heartbeat afin que vous voyiez rapidement le résultat — vous n'avez pas besoin d'attendre le prochain tick planifié du heartbeat.
|
||||
La fin d’exécution d’une tâche déclenche un réveil immédiat du signal de pulsation afin que vous voyiez le résultat rapidement — vous n’avez pas à attendre le prochain tick planifié du signal de pulsation.
|
||||
</Tip>
|
||||
|
||||
Cela signifie que le flux de travail habituel est piloté par poussée : lancez le travail détaché une seule fois, puis laissez
|
||||
l'environnement d'exécution vous réveiller ou vous notifier à l'achèvement. Ne sondez l'état d'une tâche que lorsque vous
|
||||
avez besoin de débogage, d'intervention ou d'un audit explicite.
|
||||
Cela signifie que le flux habituel repose sur l’envoi : démarrez le travail détaché une seule fois, puis laissez l’environnement d’exécution vous réveiller ou vous notifier à la fin. Interrogez l’état des tâches seulement si vous avez besoin de débogage, d’intervention ou d’un audit explicite.
|
||||
|
||||
### Politiques de notification
|
||||
|
||||
Contrôlez la quantité d'informations que vous recevez pour chaque tâche :
|
||||
Contrôlez la quantité d’informations que vous recevez pour chaque tâche :
|
||||
|
||||
| Politique | Ce qui est livré |
|
||||
| --------------------- | ------------------------------------------------------------------------- |
|
||||
| `done_only` (par défaut) | Uniquement l'état terminal (`succeeded`, `failed`, etc.) — **c'est la valeur par défaut** |
|
||||
| `state_changes` | Chaque transition d'état et chaque mise à jour de progression |
|
||||
| `silent` | Rien du tout |
|
||||
| Politique | Ce qui est livré |
|
||||
| ---------------------- | ----------------------------------------------------------------------- |
|
||||
| `done_only` (par défaut) | Seulement l’état terminal (`succeeded`, `failed`, etc.) — **c’est la valeur par défaut** |
|
||||
| `state_changes` | Chaque transition d’état et chaque mise à jour de progression |
|
||||
| `silent` | Rien du tout |
|
||||
|
||||
Modifiez la politique pendant l'exécution d'une tâche :
|
||||
Modifiez la politique pendant qu’une tâche est en cours d’exécution :
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
@ -171,7 +165,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d'exécution, Session enfant, Résumé.
|
||||
Colonnes de sortie : ID de tâche, type, statut, livraison, ID d’exécution, session enfant, résumé.
|
||||
|
||||
### `tasks show`
|
||||
|
||||
@ -179,7 +173,7 @@ Colonnes de sortie : ID de tâche, Type, Statut, Livraison, ID d'exécution, Ses
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
Le jeton de recherche accepte un ID de tâche, un ID d'exécution ou une clé de session. Affiche l'enregistrement complet, y compris le minutage, l'état de livraison, l'erreur et le résumé terminal.
|
||||
Le jeton de recherche accepte un ID de tâche, un ID d’exécution ou une clé de session. Affiche l’enregistrement complet, y compris le minutage, l’état de livraison, l’erreur et le résumé terminal.
|
||||
|
||||
### `tasks cancel`
|
||||
|
||||
@ -187,7 +181,7 @@ Le jeton de recherche accepte un ID de tâche, un ID d'exécution ou une clé de
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
Pour les tâches ACP et de sous-agent, cela tue la session enfant. Le statut passe à `cancelled` et une notification de livraison est envoyée.
|
||||
Pour les tâches ACP et de sous-agents, cela tue la session enfant. Pour les tâches suivies par la CLI, l’annulation est enregistrée dans le registre des tâches (il n’existe pas de handle d’environnement d’exécution enfant distinct). Le statut passe à `cancelled` et une notification de livraison est envoyée le cas échéant.
|
||||
|
||||
### `tasks notify`
|
||||
|
||||
@ -201,16 +195,16 @@ openclaw tasks notify <lookup> <done_only|state_changes|silent>
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
|
||||
Fait remonter les problèmes opérationnels. Les résultats apparaissent aussi dans `openclaw status` lorsque des problèmes sont détectés.
|
||||
Fait remonter les problèmes opérationnels. Les constatations apparaissent également dans `openclaw status` lorsque des problèmes sont détectés.
|
||||
|
||||
| Résultat | Gravité | Déclencheur |
|
||||
| Constatation | Gravité | Déclencheur |
|
||||
| ------------------------- | ------- | ---------------------------------------------------- |
|
||||
| `stale_queued` | warn | En file d'attente depuis plus de 10 minutes |
|
||||
| `stale_running` | error | En cours depuis plus de 30 minutes |
|
||||
| `lost` | error | La propriété de tâche adossée à l'environnement d'exécution a disparu |
|
||||
| `delivery_failed` | warn | La livraison a échoué et la politique de notification n'est pas `silent` |
|
||||
| `stale_queued` | warn | En file d’attente depuis plus de 10 minutes |
|
||||
| `stale_running` | error | En cours d’exécution depuis plus de 30 minutes |
|
||||
| `lost` | error | La propriété de tâche adossée à l’environnement d’exécution a disparu |
|
||||
| `delivery_failed` | warn | La livraison a échoué et la politique de notification n’est pas `silent` |
|
||||
| `missing_cleanup` | warn | Tâche terminale sans horodatage de nettoyage |
|
||||
| `inconsistent_timestamps` | warn | Violation de la chronologie (par exemple terminée avant d'avoir commencé) |
|
||||
| `inconsistent_timestamps` | warn | Violation de chronologie (par exemple, fin avant démarrage) |
|
||||
|
||||
### `tasks maintenance`
|
||||
|
||||
@ -219,22 +213,20 @@ openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Utilisez cette commande pour prévisualiser ou appliquer la réconciliation, l'horodatage de nettoyage et la suppression
|
||||
pour les tâches et l'état de Task Flow.
|
||||
Utilisez cette commande pour prévisualiser ou appliquer la réconciliation, l’horodatage du nettoyage et l’élagage des tâches ainsi que de l’état de Task Flow.
|
||||
|
||||
La réconciliation dépend de l'environnement d'exécution :
|
||||
La réconciliation dépend de l’environnement d’exécution :
|
||||
|
||||
- Les tâches ACP/sous-agent vérifient leur session enfant de référence.
|
||||
- Les tâches cron vérifient si l'environnement d'exécution cron possède encore la tâche.
|
||||
- Les tâches CLI adossées au chat vérifient le contexte d'exécution actif propriétaire, pas seulement la ligne de session de chat.
|
||||
- Les tâches ACP/sous-agents vérifient leur session enfant de support.
|
||||
- Les tâches cron vérifient si l’environnement d’exécution cron possède encore la tâche.
|
||||
- Les tâches CLI adossées au chat vérifient le contexte d’exécution actif propriétaire, et pas seulement la ligne de session de chat.
|
||||
|
||||
Le nettoyage à l'achèvement dépend aussi de l'environnement d'exécution :
|
||||
Le nettoyage de fin d’exécution dépend aussi de l’environnement d’exécution :
|
||||
|
||||
- L'achèvement d'un sous-agent ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage d'annonce ne continue.
|
||||
- L'achèvement d'une exécution cron isolée ferme au mieux les onglets/processus de navigateur suivis pour la session cron avant que l'exécution ne soit complètement démontée.
|
||||
- La livraison des exécutions cron isolées attend, si nécessaire, le suivi descendant des sous-agents et
|
||||
supprime le texte d'accusé de réception parent obsolète au lieu de l'annoncer.
|
||||
- La livraison de l'achèvement d'un sous-agent privilégie le dernier texte visible de l'assistant ; s'il est vide, elle revient à un texte assaini de dernier `tool`/`toolResult`, et les exécutions composées uniquement d'appels d'outil avec expiration de délai peuvent être réduites à un court résumé de progression partielle.
|
||||
- La fin d’exécution d’un sous-agent ferme au mieux les onglets/processus de navigateur suivis pour la session enfant avant que le nettoyage de l’annonce se poursuive.
|
||||
- La fin d’exécution d’une tâche cron isolée ferme au mieux les onglets/processus de navigateur suivis pour la session cron avant que l’exécution ne soit complètement démontée.
|
||||
- La livraison d’une tâche cron isolée attend au besoin la fin du suivi des sous-agents descendants et supprime le texte d’accusé de réception parent obsolète au lieu de l’annoncer.
|
||||
- La livraison de fin d’exécution d’un sous-agent privilégie le dernier texte visible de l’assistant ; s’il est vide, elle se rabat sur le dernier texte `tool`/`toolResult` assaini, et les exécutions limitées à des appels d’outil ayant expiré peuvent être réduites à un court résumé de progression partielle.
|
||||
- Les échecs de nettoyage ne masquent pas le véritable résultat de la tâche.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
@ -245,91 +237,90 @@ openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Utilisez ces commandes lorsque l'élément qui vous intéresse est le Task Flow orchestrateur
|
||||
plutôt qu'un enregistrement individuel de tâche en arrière-plan.
|
||||
Utilisez ces commandes lorsque c’est le Task Flow orchestrateur qui vous intéresse plutôt qu’un enregistrement individuel de tâche en arrière-plan.
|
||||
|
||||
## Tableau des tâches de chat (`/tasks`)
|
||||
|
||||
Utilisez `/tasks` dans n'importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche
|
||||
les tâches actives et récemment terminées avec l'environnement d'exécution, le statut, le minutage et les détails de progression ou d'erreur.
|
||||
Utilisez `/tasks` dans n’importe quelle session de chat pour voir les tâches en arrière-plan liées à cette session. Le tableau affiche
|
||||
les tâches actives et récemment terminées avec l’environnement d’exécution, le statut, le minutage, ainsi que les détails de progression ou d’erreur.
|
||||
|
||||
Lorsque la session actuelle n'a aucune tâche liée visible, `/tasks` revient aux comptages de tâches locales à l'agent
|
||||
afin que vous obteniez tout de même une vue d'ensemble sans divulguer les détails des autres sessions.
|
||||
Lorsque la session actuelle n’a aucune tâche liée visible, `/tasks` se rabat sur les comptes de tâches locaux à l’agent
|
||||
afin que vous conserviez une vue d’ensemble sans divulguer les détails d’autres sessions.
|
||||
|
||||
Pour le journal opérateur complet, utilisez la CLI : `openclaw tasks list`.
|
||||
|
||||
## Intégration au statut (pression des tâches)
|
||||
|
||||
`openclaw status` inclut un résumé des tâches visible en un coup d'œil :
|
||||
`openclaw status` inclut un résumé des tâches visible en un coup d’œil :
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
```
|
||||
|
||||
Le résumé signale :
|
||||
Le résumé indique :
|
||||
|
||||
- **active** — nombre de `queued` + `running`
|
||||
- **failures** — nombre de `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — répartition par `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
`/status` comme l'outil `session_status` utilisent un instantané des tâches sensible au nettoyage :
|
||||
les tâches actives sont privilégiées, les lignes terminées obsolètes sont masquées, et les échecs récents n'apparaissent que lorsqu'aucun travail actif
|
||||
ne reste. Cela permet à la carte de statut de rester centrée sur ce qui compte maintenant.
|
||||
`/status` et l’outil `session_status` utilisent tous deux un instantané des tâches tenant compte du nettoyage : les tâches actives sont
|
||||
privilégiées, les lignes terminées obsolètes sont masquées, et les échecs récents ne remontent que lorsqu’il ne reste plus aucun travail actif.
|
||||
Cela permet à la carte de statut de rester centrée sur ce qui compte maintenant.
|
||||
|
||||
## Stockage et maintenance
|
||||
|
||||
### Emplacement des tâches
|
||||
### Où vivent les tâches
|
||||
|
||||
Les enregistrements de tâche persistent dans SQLite à l'emplacement suivant :
|
||||
Les enregistrements de tâches persistent dans SQLite à l’emplacement suivant :
|
||||
|
||||
```
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
Le registre est chargé en mémoire au démarrage de la gateway et synchronise les écritures vers SQLite pour garantir la durabilité entre les redémarrages.
|
||||
Le registre est chargé en mémoire au démarrage de la passerelle et synchronise les écritures vers SQLite pour garantir la durabilité entre les redémarrages.
|
||||
|
||||
### Maintenance automatique
|
||||
|
||||
Un nettoyeur s'exécute toutes les **60 secondes** et gère trois choses :
|
||||
Un balayage s’exécute toutes les **60 secondes** et gère trois éléments :
|
||||
|
||||
1. **Réconciliation** — vérifie si les tâches actives ont toujours un état de référence faisant autorité dans l'environnement d'exécution. Les tâches ACP/sous-agent utilisent l'état de la session enfant, les tâches cron utilisent la propriété de tâche active, et les tâches CLI adossées au chat utilisent le contexte d'exécution propriétaire. Si cet état de référence a disparu depuis plus de 5 minutes, la tâche est marquée `lost`.
|
||||
2. **Horodatage de nettoyage** — définit un horodatage `cleanupAfter` sur les tâches terminales (`endedAt` + 7 jours).
|
||||
3. **Suppression** — supprime les enregistrements au-delà de leur date `cleanupAfter`.
|
||||
1. **Réconciliation** — vérifie si les tâches actives ont encore un support d’exécution faisant autorité. Les tâches ACP/sous-agents utilisent l’état de la session enfant, les tâches cron utilisent la possession de tâche active, et les tâches CLI adossées au chat utilisent le contexte d’exécution propriétaire. Si cet état de support a disparu pendant plus de 5 minutes, la tâche est marquée `lost`.
|
||||
2. **Horodatage du nettoyage** — définit un horodatage `cleanupAfter` sur les tâches terminales (`endedAt + 7 days`).
|
||||
3. **Élagage** — supprime les enregistrements ayant dépassé leur date `cleanupAfter`.
|
||||
|
||||
**Rétention** : les enregistrements de tâche terminaux sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration nécessaire.
|
||||
**Rétention** : les enregistrements de tâches terminales sont conservés pendant **7 jours**, puis automatiquement supprimés. Aucune configuration nécessaire.
|
||||
|
||||
## Comment les tâches se rapportent aux autres systèmes
|
||||
## Comment les tâches sont liées aux autres systèmes
|
||||
|
||||
### Tâches et Task Flow
|
||||
|
||||
[Task Flow](/fr/automation/taskflow) est la couche d'orchestration de flux au-dessus des tâches en arrière-plan. Un seul flux peut coordonner plusieurs tâches au cours de sa durée de vie en utilisant des modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements individuels de tâche et `openclaw tasks flow` pour inspecter le flux orchestrateur.
|
||||
[Task Flow](/fr/automation/taskflow) est la couche d’orchestration de flux au-dessus des tâches en arrière-plan. Un même flux peut coordonner plusieurs tâches au cours de son cycle de vie à l’aide de modes de synchronisation gérés ou miroir. Utilisez `openclaw tasks` pour inspecter les enregistrements individuels de tâches et `openclaw tasks flow` pour inspecter le flux orchestrateur.
|
||||
|
||||
Consultez [Task Flow](/fr/automation/taskflow) pour plus de détails.
|
||||
Voir [Task Flow](/fr/automation/taskflow) pour plus de détails.
|
||||
|
||||
### Tâches et cron
|
||||
|
||||
Une **définition** de tâche cron se trouve dans `~/.openclaw/cron/jobs.json`. **Chaque** exécution cron crée un enregistrement de tâche — à la fois en session principale et en mode isolé. Les tâches cron de session principale utilisent par défaut la politique de notification `silent`, afin d'assurer le suivi sans générer de notifications.
|
||||
Une **définition** de tâche cron vit dans `~/.openclaw/cron/jobs.json`. **Chaque** exécution cron crée un enregistrement de tâche — à la fois pour la session principale et pour les exécutions isolées. Les tâches cron de session principale utilisent par défaut la politique de notification `silent`, de sorte qu’elles sont suivies sans générer de notifications.
|
||||
|
||||
Consultez [Tâches cron](/fr/automation/cron-jobs).
|
||||
Voir [Tâches cron](/fr/automation/cron-jobs).
|
||||
|
||||
### Tâches et heartbeat
|
||||
### Tâches et signal de pulsation
|
||||
|
||||
Les exécutions heartbeat sont des tours de session principale — elles ne créent pas d'enregistrements de tâche. Lorsqu'une tâche se termine, elle peut déclencher un réveil du heartbeat afin que vous voyiez rapidement le résultat.
|
||||
Les exécutions du signal de pulsation sont des tours de session principale — elles ne créent pas d’enregistrements de tâche. Lorsqu’une tâche se termine, elle peut déclencher un réveil du signal de pulsation afin que vous voyiez rapidement le résultat.
|
||||
|
||||
Consultez [Heartbeat](/fr/gateway/heartbeat).
|
||||
Voir [Signal de pulsation](/fr/gateway/heartbeat).
|
||||
|
||||
### Tâches et sessions
|
||||
|
||||
Une tâche peut référencer une `childSessionKey` (où le travail s'exécute) et une `requesterSessionKey` (qui l'a démarrée). Les sessions sont le contexte de conversation ; les tâches sont une couche de suivi d'activité au-dessus.
|
||||
Une tâche peut référencer une `childSessionKey` (où le travail s’exécute) et une `requesterSessionKey` (qui l’a démarré). Les sessions correspondent au contexte de conversation ; les tâches correspondent au suivi d’activité au-dessus de ce contexte.
|
||||
|
||||
### Tâches et exécutions d'agent
|
||||
### Tâches et exécutions d’agent
|
||||
|
||||
Le `runId` d'une tâche la relie à l'exécution d'agent qui effectue le travail. Les événements de cycle de vie de l'agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n'avez pas besoin de gérer manuellement le cycle de vie.
|
||||
Le `runId` d’une tâche renvoie à l’exécution d’agent qui effectue le travail. Les événements du cycle de vie de l’agent (démarrage, fin, erreur) mettent automatiquement à jour le statut de la tâche — vous n’avez pas besoin de gérer manuellement le cycle de vie.
|
||||
|
||||
## Liens associés
|
||||
|
||||
- [Automatisation et tâches](/fr/automation) — tous les mécanismes d'automatisation en un coup d'œil
|
||||
- [Automatisation et tâches](/fr/automation) — aperçu de tous les mécanismes d’automatisation
|
||||
- [Task Flow](/fr/automation/taskflow) — orchestration de flux au-dessus des tâches
|
||||
- [Tâches planifiées](/fr/automation/cron-jobs) — planification du travail en arrière-plan
|
||||
- [Heartbeat](/fr/gateway/heartbeat) — tours périodiques de la session principale
|
||||
- [Signal de pulsation](/fr/gateway/heartbeat) — tours périodiques de session principale
|
||||
- [CLI : tâches](/cli/index#tasks) — référence des commandes CLI
|
||||
|
||||
612
docs/fr/concepts/active-memory.md
Normal file
612
docs/fr/concepts/active-memory.md
Normal file
@ -0,0 +1,612 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous voulez comprendre à quoi sert la mémoire active
|
||||
- Vous voulez activer la mémoire active pour un agent conversationnel
|
||||
- Vous voulez ajuster le comportement de la mémoire active sans l’activer partout
|
||||
summary: Un sous-agent de mémoire bloquante appartenant au plugin qui injecte la mémoire pertinente dans les sessions de chat interactives
|
||||
title: Mémoire active
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T06:55:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Mémoire active
|
||||
|
||||
La mémoire active est un sous-agent de mémoire bloquant optionnel appartenant au plugin, qui s’exécute
|
||||
avant la réponse principale pour les sessions conversationnelles admissibles.
|
||||
|
||||
Elle existe parce que la plupart des systèmes de mémoire sont capables mais réactifs. Ils s’appuient sur
|
||||
l’agent principal pour décider quand rechercher dans la mémoire, ou sur l’utilisateur pour dire des choses
|
||||
comme « souviens-toi de ceci » ou « recherche dans la mémoire ». À ce moment-là, l’instant où la mémoire
|
||||
aurait rendu la réponse naturelle est déjà passé.
|
||||
|
||||
La mémoire active donne au système une occasion limitée de faire remonter une mémoire pertinente
|
||||
avant que la réponse principale ne soit générée.
|
||||
|
||||
## Collez ceci dans votre agent
|
||||
|
||||
Collez ceci dans votre agent si vous voulez activer la mémoire active avec une
|
||||
configuration autonome et sûre par défaut :
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Cela active le plugin pour l’agent `main`, le limite par défaut aux sessions de
|
||||
type message direct, lui permet d’hériter d’abord du modèle de la session en cours, et
|
||||
autorise toujours le repli distant intégré si aucun modèle explicite ou hérité n’est disponible.
|
||||
|
||||
Ensuite, redémarrez la passerelle :
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Pour l’inspecter en direct dans une conversation :
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## Activer la mémoire active
|
||||
|
||||
La configuration la plus sûre consiste à :
|
||||
|
||||
1. activer le plugin
|
||||
2. cibler un agent conversationnel
|
||||
3. garder la journalisation activée uniquement pendant l’ajustement
|
||||
|
||||
Commencez avec ceci dans `openclaw.json` :
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Puis redémarrez la passerelle :
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Ce que cela signifie :
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` active le plugin
|
||||
- `config.agents: ["main"]` active la mémoire active uniquement pour l’agent `main`
|
||||
- `config.allowedChatTypes: ["direct"]` limite par défaut la mémoire active aux sessions de type message direct
|
||||
- si `config.model` n’est pas défini, la mémoire active hérite d’abord du modèle de la session en cours
|
||||
- `config.modelFallbackPolicy: "default-remote"` conserve le repli distant intégré par défaut lorsqu’aucun modèle explicite ou hérité n’est disponible
|
||||
- `config.promptStyle: "balanced"` utilise le style d’invite généraliste par défaut pour le mode `recent`
|
||||
- la mémoire active ne s’exécute toujours que sur les sessions de chat persistantes interactives admissibles
|
||||
|
||||
## Comment l’afficher
|
||||
|
||||
La mémoire active injecte un contexte système caché pour le modèle. Elle n’expose pas
|
||||
les balises brutes `<active_memory_plugin>...</active_memory_plugin>` au client.
|
||||
|
||||
## Bascule de session
|
||||
|
||||
Utilisez la commande du plugin si vous souhaitez suspendre ou reprendre la mémoire active pour la
|
||||
session de chat en cours sans modifier la configuration :
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
Cela s’applique à la session. Cela ne modifie pas
|
||||
`plugins.entries.active-memory.enabled`, le ciblage des agents, ni les autres
|
||||
paramètres globaux.
|
||||
|
||||
Si vous voulez que la commande écrive dans la configuration et suspendre ou reprendre la mémoire active pour
|
||||
toutes les sessions, utilisez la forme globale explicite :
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
La forme globale écrit dans `plugins.entries.active-memory.config.enabled`. Elle laisse
|
||||
`plugins.entries.active-memory.enabled` activé afin que la commande reste disponible pour
|
||||
réactiver la mémoire active plus tard.
|
||||
|
||||
Si vous voulez voir ce que fait la mémoire active dans une session en direct, activez le mode verbeux
|
||||
pour cette session :
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
Avec le mode verbeux activé, OpenClaw peut afficher :
|
||||
|
||||
- une ligne d’état de la mémoire active telle que `Active Memory: ok 842ms recent 34 chars`
|
||||
- un résumé de débogage lisible tel que `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
Ces lignes proviennent du même passage de mémoire active qui alimente le contexte système
|
||||
caché, mais elles sont formatées pour les humains au lieu d’exposer un balisage brut de l’invite.
|
||||
|
||||
Par défaut, la transcription du sous-agent de mémoire bloquant est temporaire et supprimée
|
||||
une fois l’exécution terminée.
|
||||
|
||||
Exemple de déroulement :
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
Forme attendue de la réponse visible :
|
||||
|
||||
```text
|
||||
...normal assistant reply...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
|
||||
```
|
||||
|
||||
## Quand elle s’exécute
|
||||
|
||||
La mémoire active utilise deux portes de contrôle :
|
||||
|
||||
1. **Activation par configuration**
|
||||
Le plugin doit être activé, et l’identifiant de l’agent courant doit apparaître dans
|
||||
`plugins.entries.active-memory.config.agents`.
|
||||
2. **Admissibilité stricte à l’exécution**
|
||||
Même lorsqu’elle est activée et ciblée, la mémoire active ne s’exécute que pour les
|
||||
sessions de chat persistantes interactives admissibles.
|
||||
|
||||
La règle réelle est :
|
||||
|
||||
```text
|
||||
plugin enabled
|
||||
+
|
||||
agent id targeted
|
||||
+
|
||||
allowed chat type
|
||||
+
|
||||
eligible interactive persistent chat session
|
||||
=
|
||||
active memory runs
|
||||
```
|
||||
|
||||
Si l’un de ces éléments échoue, la mémoire active ne s’exécute pas.
|
||||
|
||||
## Types de session
|
||||
|
||||
`config.allowedChatTypes` contrôle quels types de conversations peuvent exécuter la mémoire active.
|
||||
|
||||
La valeur par défaut est :
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
Cela signifie que la mémoire active s’exécute par défaut dans les sessions de type message direct, mais
|
||||
pas dans les sessions de groupe ou de canal, sauf si vous les activez explicitement.
|
||||
|
||||
Exemples :
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## Où elle s’exécute
|
||||
|
||||
La mémoire active est une fonctionnalité d’enrichissement conversationnel, pas une
|
||||
fonctionnalité d’inférence à l’échelle de la plateforme.
|
||||
|
||||
| Surface | Exécute la mémoire active ? |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Sessions persistantes de chat dans l’interface de contrôle / chat web | Oui, si le plugin est activé et que l’agent est ciblé |
|
||||
| Autres sessions de canal interactives sur le même chemin de chat persistant | Oui, si le plugin est activé et que l’agent est ciblé |
|
||||
| Exécutions sans interface en une seule fois | Non |
|
||||
| Exécutions de pulsation / en arrière-plan | Non |
|
||||
| Chemins internes génériques `agent-command` | Non |
|
||||
| Exécution de sous-agents / d’assistants internes | Non |
|
||||
|
||||
## Pourquoi l’utiliser
|
||||
|
||||
Utilisez la mémoire active lorsque :
|
||||
|
||||
- la session est persistante et destinée à l’utilisateur
|
||||
- l’agent dispose d’une mémoire à long terme pertinente à interroger
|
||||
- la continuité et la personnalisation comptent plus que le déterminisme brut de l’invite
|
||||
|
||||
Elle fonctionne particulièrement bien pour :
|
||||
|
||||
- les préférences stables
|
||||
- les habitudes récurrentes
|
||||
- le contexte utilisateur à long terme qui devrait remonter naturellement
|
||||
|
||||
Elle convient mal à :
|
||||
|
||||
- l’automatisation
|
||||
- les workers internes
|
||||
- les tâches d’API en une seule fois
|
||||
- les endroits où une personnalisation cachée serait surprenante
|
||||
|
||||
## Comment cela fonctionne
|
||||
|
||||
La structure à l’exécution est la suivante :
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["User Message"] --> Q["Build Memory Query"]
|
||||
Q --> R["Active Memory Blocking Memory Sub-Agent"]
|
||||
R -->|NONE or empty| M["Main Reply"]
|
||||
R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
Le sous-agent de mémoire bloquant peut utiliser uniquement :
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
Si la connexion est faible, il doit renvoyer `NONE`.
|
||||
|
||||
## Modes de requête
|
||||
|
||||
`config.queryMode` contrôle la quantité de conversation que voit le sous-agent de mémoire bloquant.
|
||||
|
||||
## Styles d’invite
|
||||
|
||||
`config.promptStyle` contrôle à quel point le sous-agent de mémoire bloquant est
|
||||
prompt ou strict lorsqu’il décide de renvoyer de la mémoire.
|
||||
|
||||
Styles disponibles :
|
||||
|
||||
- `balanced` : valeur par défaut généraliste pour le mode `recent`
|
||||
- `strict` : le moins prompt ; idéal lorsque vous voulez très peu de contamination par le contexte proche
|
||||
- `contextual` : le plus favorable à la continuité ; idéal lorsque l’historique de la conversation doit davantage compter
|
||||
- `recall-heavy` : plus enclin à faire remonter de la mémoire sur des correspondances plus faibles mais encore plausibles
|
||||
- `precision-heavy` : privilégie fortement `NONE` sauf si la correspondance est évidente
|
||||
- `preference-only` : optimisé pour les favoris, les habitudes, les routines, les goûts et les faits personnels récurrents
|
||||
|
||||
Correspondance par défaut lorsque `config.promptStyle` n’est pas défini :
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
Si vous définissez `config.promptStyle` explicitement, cette valeur remplace la correspondance par défaut.
|
||||
|
||||
Exemple :
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## Politique de repli du modèle
|
||||
|
||||
Si `config.model` n’est pas défini, la mémoire active essaie de résoudre un modèle dans cet ordre :
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` contrôle la dernière étape.
|
||||
|
||||
Valeur par défaut :
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
Autre option :
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
Utilisez `resolved-only` si vous voulez que la mémoire active ignore le rappel plutôt que de
|
||||
revenir au comportement distant intégré par défaut lorsqu’aucun modèle explicite ou hérité n’est
|
||||
disponible.
|
||||
|
||||
## Mécanismes d’échappement avancés
|
||||
|
||||
Ces options ne font intentionnellement pas partie de la configuration recommandée.
|
||||
|
||||
`config.thinking` peut remplacer le niveau de réflexion du sous-agent de mémoire bloquant :
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
Valeur par défaut :
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
Ne l’activez pas par défaut. La mémoire active s’exécute dans le chemin de réponse, donc un temps de
|
||||
réflexion supplémentaire augmente directement la latence visible par l’utilisateur.
|
||||
|
||||
`config.promptAppend` ajoute des instructions opérateur supplémentaires après l’invite par défaut de la mémoire active
|
||||
et avant le contexte de conversation :
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` remplace l’invite par défaut de la mémoire active. OpenClaw
|
||||
ajoute toujours ensuite le contexte de conversation :
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
La personnalisation de l’invite n’est pas recommandée sauf si vous testez délibérément un
|
||||
contrat de rappel différent. L’invite par défaut est réglée pour renvoyer soit `NONE`,
|
||||
soit un contexte compact de faits utilisateur pour le modèle principal.
|
||||
|
||||
### `message`
|
||||
|
||||
Seul le dernier message utilisateur est envoyé.
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
À utiliser lorsque :
|
||||
|
||||
- vous voulez le comportement le plus rapide
|
||||
- vous voulez le biais le plus fort vers le rappel de préférences stables
|
||||
- les tours de suivi n’ont pas besoin de contexte conversationnel
|
||||
|
||||
Délai recommandé :
|
||||
|
||||
- commencez autour de `3000` à `5000` ms
|
||||
|
||||
### `recent`
|
||||
|
||||
Le dernier message utilisateur plus une petite portion récente de la conversation sont envoyés.
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
À utiliser lorsque :
|
||||
|
||||
- vous voulez un meilleur équilibre entre vitesse et ancrage conversationnel
|
||||
- les questions de suivi dépendent souvent des derniers tours
|
||||
|
||||
Délai recommandé :
|
||||
|
||||
- commencez autour de `15000` ms
|
||||
|
||||
### `full`
|
||||
|
||||
La conversation complète est envoyée au sous-agent de mémoire bloquant.
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
À utiliser lorsque :
|
||||
|
||||
- la meilleure qualité de rappel compte plus que la latence
|
||||
- la conversation contient une mise en contexte importante loin plus haut dans le fil
|
||||
|
||||
Délai recommandé :
|
||||
|
||||
- augmentez-le sensiblement par rapport à `message` ou `recent`
|
||||
- commencez autour de `15000` ms ou plus selon la taille du fil
|
||||
|
||||
En général, le délai d’attente doit augmenter avec la taille du contexte :
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## Persistance de la transcription
|
||||
|
||||
Les exécutions du sous-agent de mémoire bloquant de la mémoire active créent une véritable transcription `session.jsonl`
|
||||
pendant l’appel du sous-agent de mémoire bloquant.
|
||||
|
||||
Par défaut, cette transcription est temporaire :
|
||||
|
||||
- elle est écrite dans un répertoire temporaire
|
||||
- elle est utilisée uniquement pour l’exécution du sous-agent de mémoire bloquant
|
||||
- elle est supprimée immédiatement après la fin de l’exécution
|
||||
|
||||
Si vous voulez conserver sur disque ces transcriptions du sous-agent de mémoire bloquant pour le débogage ou
|
||||
l’inspection, activez explicitement la persistance :
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Lorsqu’elle est activée, la mémoire active stocke les transcriptions dans un répertoire distinct sous le
|
||||
dossier des sessions de l’agent cible, et non dans le chemin principal de transcription de la conversation
|
||||
utilisateur.
|
||||
|
||||
La structure par défaut est conceptuellement :
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
Vous pouvez modifier le sous-répertoire relatif avec `config.transcriptDir`.
|
||||
|
||||
À utiliser avec précaution :
|
||||
|
||||
- les transcriptions du sous-agent de mémoire bloquant peuvent s’accumuler rapidement sur les sessions très actives
|
||||
- le mode de requête `full` peut dupliquer une grande quantité de contexte de conversation
|
||||
- ces transcriptions contiennent un contexte d’invite caché et des mémoires rappelées
|
||||
|
||||
## Configuration
|
||||
|
||||
Toute la configuration de la mémoire active se trouve sous :
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
Les champs les plus importants sont :
|
||||
|
||||
| Key | Type | Meaning |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | Active le plugin lui-même |
|
||||
| `config.agents` | `string[]` | Identifiants d’agent pouvant utiliser la mémoire active |
|
||||
| `config.model` | `string` | Référence de modèle optionnelle pour le sous-agent de mémoire bloquant ; lorsqu’elle n’est pas définie, la mémoire active utilise le modèle de la session en cours |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | Contrôle la quantité de conversation que voit le sous-agent de mémoire bloquant |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Contrôle à quel point le sous-agent de mémoire bloquant est prompt ou strict lorsqu’il décide de renvoyer de la mémoire |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Remplacement avancé du niveau de réflexion pour le sous-agent de mémoire bloquant ; `off` par défaut pour la vitesse |
|
||||
| `config.promptOverride` | `string` | Remplacement avancé complet de l’invite ; non recommandé pour un usage normal |
|
||||
| `config.promptAppend` | `string` | Instructions supplémentaires avancées ajoutées à l’invite par défaut ou remplacée |
|
||||
| `config.timeoutMs` | `number` | Délai d’attente maximal strict pour le sous-agent de mémoire bloquant |
|
||||
| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé de la mémoire active |
|
||||
| `config.logging` | `boolean` | Émet des journaux de la mémoire active pendant l’ajustement |
|
||||
| `config.persistTranscripts` | `boolean` | Conserve sur disque les transcriptions du sous-agent de mémoire bloquant au lieu de supprimer les fichiers temporaires |
|
||||
| `config.transcriptDir` | `string` | Répertoire relatif des transcriptions du sous-agent de mémoire bloquant sous le dossier des sessions de l’agent |
|
||||
|
||||
Champs de réglage utiles :
|
||||
|
||||
| Key | Type | Meaning |
|
||||
| ----------------------------- | -------- | ------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Nombre maximal total de caractères autorisés dans le résumé de la mémoire active |
|
||||
| `config.recentUserTurns` | `number` | Tours utilisateur précédents à inclure lorsque `queryMode` vaut `recent` |
|
||||
| `config.recentAssistantTurns` | `number` | Tours d’assistant précédents à inclure lorsque `queryMode` vaut `recent` |
|
||||
| `config.recentUserChars` | `number` | Nombre maximal de caractères par tour utilisateur récent |
|
||||
| `config.recentAssistantChars` | `number` | Nombre maximal de caractères par tour d’assistant récent |
|
||||
| `config.cacheTtlMs` | `number` | Réutilisation du cache pour les requêtes identiques répétées |
|
||||
|
||||
## Configuration recommandée
|
||||
|
||||
Commencez avec `recent`.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Si vous voulez inspecter le comportement en direct pendant l’ajustement, utilisez `/verbose on` dans la
|
||||
session au lieu de chercher une commande de débogage active-memory distincte.
|
||||
|
||||
Passez ensuite à :
|
||||
|
||||
- `message` si vous voulez une latence plus faible
|
||||
- `full` si vous décidez qu’un contexte supplémentaire vaut un sous-agent de mémoire bloquant plus lent
|
||||
|
||||
## Débogage
|
||||
|
||||
Si la mémoire active n’apparaît pas là où vous l’attendez :
|
||||
|
||||
1. Vérifiez que le plugin est activé dans `plugins.entries.active-memory.enabled`.
|
||||
2. Vérifiez que l’identifiant de l’agent courant figure dans `config.agents`.
|
||||
3. Vérifiez que vous testez via une session de chat persistante interactive.
|
||||
4. Activez `config.logging: true` et observez les journaux de la passerelle.
|
||||
5. Vérifiez que la recherche de mémoire fonctionne elle-même avec `openclaw memory status --deep`.
|
||||
|
||||
Si les résultats mémoire sont bruyants, réduisez :
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
Si la mémoire active est trop lente :
|
||||
|
||||
- réduisez `queryMode`
|
||||
- réduisez `timeoutMs`
|
||||
- réduisez le nombre de tours récents
|
||||
- réduisez les plafonds de caractères par tour
|
||||
|
||||
## Pages associées
|
||||
|
||||
- [Recherche en mémoire](/fr/concepts/memory-search)
|
||||
- [Référence de configuration de la mémoire](/fr/reference/memory-config)
|
||||
- [Configuration du SDK de plugin](/fr/plugins/sdk-setup)
|
||||
@ -1,102 +1,91 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous voulez comprendre comment `memory_search` fonctionne
|
||||
- Vous voulez choisir un fournisseur d'embeddings
|
||||
- Vous voulez ajuster la qualité de la recherche
|
||||
summary: Comment memory search trouve des notes pertinentes à l'aide des embeddings et de la récupération hybride
|
||||
title: Memory Search
|
||||
- Vous voulez choisir un fournisseur d’embeddings
|
||||
- Vous voulez ajuster la qualité de recherche
|
||||
summary: Comment la recherche mémoire trouve des notes pertinentes à l’aide des embeddings et de la récupération hybride
|
||||
title: Recherche mémoire
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:26Z"
|
||||
generated_at: "2026-04-10T06:55:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memory Search
|
||||
# Recherche mémoire
|
||||
|
||||
`memory_search` trouve des notes pertinentes dans vos fichiers de mémoire, même lorsque
|
||||
la formulation diffère du texte d'origine. Il fonctionne en indexant la mémoire en petits
|
||||
fragments et en les recherchant à l'aide d'embeddings, de mots-clés, ou des deux.
|
||||
`memory_search` trouve des notes pertinentes dans vos fichiers de mémoire, même lorsque la formulation diffère du texte d’origine. Elle fonctionne en indexant la mémoire en petits fragments, puis en les recherchant à l’aide d’embeddings, de mots-clés, ou des deux.
|
||||
|
||||
## Démarrage rapide
|
||||
|
||||
Si vous avez une clé API OpenAI, Gemini, Voyage ou Mistral configurée, memory
|
||||
search fonctionne automatiquement. Pour définir explicitement un fournisseur :
|
||||
Si vous avez une clé API OpenAI, Gemini, Voyage ou Mistral configurée, la recherche mémoire fonctionne automatiquement. Pour définir explicitement un fournisseur :
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
memorySearch: {
|
||||
provider: "openai", // or "gemini", "local", "ollama", etc.
|
||||
provider: "openai", // ou "gemini", "local", "ollama", etc.
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Pour des embeddings locaux sans clé API, utilisez `provider: "local"` (nécessite
|
||||
node-llama-cpp).
|
||||
Pour des embeddings locaux sans clé API, utilisez `provider: "local"` (nécessite `node-llama-cpp`).
|
||||
|
||||
## Fournisseurs pris en charge
|
||||
|
||||
| Fournisseur | ID | Nécessite une clé API | Notes |
|
||||
| ----------- | --------- | --------------------- | ---------------------------------------------------- |
|
||||
| OpenAI | `openai` | Oui | Détection automatique, rapide |
|
||||
| Gemini | `gemini` | Oui | Prend en charge l'indexation d'images et d'audio |
|
||||
| Voyage | `voyage` | Oui | Détection automatique |
|
||||
| Mistral | `mistral` | Oui | Détection automatique |
|
||||
| Bedrock | `bedrock` | Non | Détection automatique lorsque la chaîne d'identifiants AWS est résolue |
|
||||
| Ollama | `ollama` | Non | Local, doit être défini explicitement |
|
||||
| Local | `local` | Non | Modèle GGUF, téléchargement d'environ 0,6 Go |
|
||||
| Fournisseur | ID | Nécessite une clé API | Notes |
|
||||
| ----------- | --------- | --------------------- | ------------------------------------------------------- |
|
||||
| OpenAI | `openai` | Oui | Détection automatique, rapide |
|
||||
| Gemini | `gemini` | Oui | Prend en charge l’indexation d’images et d’audio |
|
||||
| Voyage | `voyage` | Oui | Détection automatique |
|
||||
| Mistral | `mistral` | Oui | Détection automatique |
|
||||
| Bedrock | `bedrock` | Non | Détection automatique lorsque la chaîne d’identifiants AWS est résolue |
|
||||
| Ollama | `ollama` | Non | Local, doit être défini explicitement |
|
||||
| Local | `local` | Non | Modèle GGUF, téléchargement d’environ 0,6 Go |
|
||||
|
||||
## Fonctionnement de la recherche
|
||||
## Comment la recherche fonctionne
|
||||
|
||||
OpenClaw exécute deux parcours de récupération en parallèle et fusionne les résultats :
|
||||
OpenClaw exécute deux chemins de récupération en parallèle et fusionne les résultats :
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Q["Query"] --> E["Embedding"]
|
||||
Q --> T["Tokenize"]
|
||||
E --> VS["Vector Search"]
|
||||
T --> BM["BM25 Search"]
|
||||
VS --> M["Weighted Merge"]
|
||||
Q["Requête"] --> E["Embedding"]
|
||||
Q --> T["Tokenisation"]
|
||||
E --> VS["Recherche vectorielle"]
|
||||
T --> BM["Recherche BM25"]
|
||||
VS --> M["Fusion pondérée"]
|
||||
BM --> M
|
||||
M --> R["Top Results"]
|
||||
M --> R["Meilleurs résultats"]
|
||||
```
|
||||
|
||||
- **La recherche vectorielle** trouve des notes au sens similaire ("gateway host" correspond à
|
||||
"the machine running OpenClaw").
|
||||
- **La recherche par mots-clés BM25** trouve des correspondances exactes (ID, chaînes d'erreur, clés
|
||||
de configuration).
|
||||
- **Recherche vectorielle** trouve des notes au sens similaire (« gateway host » correspond à « la machine qui exécute OpenClaw »).
|
||||
- **Recherche par mots-clés BM25** trouve des correspondances exactes (ID, chaînes d’erreur, clés de configuration).
|
||||
|
||||
Si un seul parcours est disponible (pas d'embeddings ou pas de FTS), l'autre s'exécute seul.
|
||||
Si un seul chemin est disponible (pas d’embeddings ou pas de FTS), l’autre s’exécute seul.
|
||||
|
||||
## Améliorer la qualité de la recherche
|
||||
## Améliorer la qualité de recherche
|
||||
|
||||
Deux fonctionnalités facultatives aident lorsque vous avez un long historique de notes :
|
||||
|
||||
### Décroissance temporelle
|
||||
|
||||
Les anciennes notes perdent progressivement du poids dans le classement afin que les informations récentes remontent en premier.
|
||||
Avec la demi-vie par défaut de 30 jours, une note du mois dernier obtient un score égal à 50 % de
|
||||
son poids d'origine. Les fichiers permanents comme `MEMORY.md` ne subissent jamais de décroissance.
|
||||
Les anciennes notes perdent progressivement du poids dans le classement, afin que les informations récentes remontent en premier. Avec la demi-vie par défaut de 30 jours, une note du mois dernier obtient 50 % de son poids d’origine. Les fichiers pérennes comme `MEMORY.md` ne subissent jamais de décroissance.
|
||||
|
||||
<Tip>
|
||||
Activez la décroissance temporelle si votre agent a des mois de notes quotidiennes et que des informations obsolètes
|
||||
continuent de dépasser le contexte récent dans le classement.
|
||||
Activez la décroissance temporelle si votre agent a des mois de notes quotidiennes et que des informations obsolètes continuent de dépasser le contexte récent dans le classement.
|
||||
</Tip>
|
||||
|
||||
### MMR (diversité)
|
||||
|
||||
Réduit les résultats redondants. Si cinq notes mentionnent toutes la même configuration de routeur, MMR
|
||||
garantit que les meilleurs résultats couvrent différents sujets au lieu de se répéter.
|
||||
Réduit les résultats redondants. Si cinq notes mentionnent toutes la même configuration de routeur, MMR garantit que les meilleurs résultats couvrent différents sujets au lieu de se répéter.
|
||||
|
||||
<Tip>
|
||||
Activez MMR si `memory_search` continue de renvoyer des extraits quasi dupliqués provenant
|
||||
de différentes notes quotidiennes.
|
||||
Activez MMR si `memory_search` continue de renvoyer des extraits presque dupliqués provenant de différentes notes quotidiennes.
|
||||
</Tip>
|
||||
|
||||
### Activer les deux
|
||||
@ -120,30 +109,22 @@ de différentes notes quotidiennes.
|
||||
|
||||
## Mémoire multimodale
|
||||
|
||||
Avec Gemini Embedding 2, vous pouvez indexer des images et des fichiers audio aux côtés du
|
||||
Markdown. Les requêtes de recherche restent du texte, mais elles correspondent au contenu visuel et audio.
|
||||
Consultez la [référence de configuration de la mémoire](/fr/reference/memory-config) pour la
|
||||
configuration.
|
||||
Avec Gemini Embedding 2, vous pouvez indexer des images et des fichiers audio en plus du Markdown. Les requêtes de recherche restent textuelles, mais elles sont mises en correspondance avec le contenu visuel et audio. Consultez la [référence de configuration de la mémoire](/fr/reference/memory-config) pour la configuration.
|
||||
|
||||
## Recherche dans la mémoire de session
|
||||
|
||||
Vous pouvez éventuellement indexer les transcriptions de session afin que `memory_search` puisse rappeler
|
||||
des conversations antérieures. Cette fonctionnalité est optionnelle via
|
||||
`memorySearch.experimental.sessionMemory`. Consultez la
|
||||
[référence de configuration](/fr/reference/memory-config) pour plus de détails.
|
||||
Vous pouvez facultativement indexer les transcriptions de session afin que `memory_search` puisse rappeler des conversations antérieures. Cette fonctionnalité est activée sur opt-in via `memorySearch.experimental.sessionMemory`. Consultez la [référence de configuration](/fr/reference/memory-config) pour plus de détails.
|
||||
|
||||
## Dépannage
|
||||
|
||||
**Aucun résultat ?** Exécutez `openclaw memory status` pour vérifier l'index. S'il est vide, exécutez
|
||||
`openclaw memory index --force`.
|
||||
**Aucun résultat ?** Exécutez `openclaw memory status` pour vérifier l’index. S’il est vide, exécutez `openclaw memory index --force`.
|
||||
|
||||
**Seulement des correspondances par mots-clés ?** Il se peut que votre fournisseur d'embeddings ne soit pas configuré. Vérifiez
|
||||
`openclaw memory status --deep`.
|
||||
**Seulement des correspondances par mots-clés ?** Votre fournisseur d’embeddings n’est peut-être pas configuré. Vérifiez avec `openclaw memory status --deep`.
|
||||
|
||||
**Texte CJK introuvable ?** Reconstruisez l'index FTS avec
|
||||
`openclaw memory index --force`.
|
||||
**Texte CJK introuvable ?** Reconstruisez l’index FTS avec `openclaw memory index --force`.
|
||||
|
||||
## Pour aller plus loin
|
||||
|
||||
- [Memory](/fr/concepts/memory) -- disposition des fichiers, backends, outils
|
||||
- [Mémoire active](/fr/concepts/active-memory) -- mémoire de sous-agent pour les sessions de chat interactives
|
||||
- [Mémoire](/fr/concepts/memory) -- disposition des fichiers, backends, outils
|
||||
- [Référence de configuration de la mémoire](/fr/reference/memory-config) -- tous les paramètres de configuration
|
||||
|
||||
@ -1,50 +1,50 @@
|
||||
---
|
||||
read_when:
|
||||
- Étendre qa-lab ou qa-channel
|
||||
- Ajouter des scénarios QA adossés au dépôt
|
||||
- Créer une automatisation QA plus réaliste autour du tableau de bord Gateway
|
||||
summary: Structure de l’automatisation QA privée pour qa-lab, qa-channel, les scénarios de départ, et les rapports de protocole
|
||||
title: Automatisation QA E2E
|
||||
- Extension de qa-lab ou qa-channel
|
||||
- Ajout de scénarios QA adossés au dépôt
|
||||
- Création d’une automatisation QA plus réaliste autour du tableau de bord Gateway
|
||||
summary: Forme de l’automatisation QA privée pour qa-lab, qa-channel, scénarios préconfigurés et rapports de protocole
|
||||
title: Automatisation QA de bout en bout
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:44Z"
|
||||
generated_at: "2026-04-10T06:55:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
|
||||
source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automatisation QA E2E
|
||||
# Automatisation QA de bout en bout
|
||||
|
||||
La pile QA privée est conçue pour exercer OpenClaw d’une manière plus réaliste,
|
||||
avec une forme proche d’un canal, qu’un simple test unitaire ne peut le faire.
|
||||
façonnée comme un canal, qu’un simple test unitaire ne peut le faire.
|
||||
|
||||
Éléments actuels :
|
||||
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec surfaces de MP, de canal, de fil,
|
||||
- `extensions/qa-channel` : canal de messages synthétique avec des surfaces de MP, de canal, de fil,
|
||||
de réaction, de modification et de suppression.
|
||||
- `extensions/qa-lab` : interface de débogage et bus QA pour observer la transcription,
|
||||
injecter des messages entrants et exporter un rapport Markdown.
|
||||
- `qa/` : ressources de départ adossées au dépôt pour la tâche de lancement et les
|
||||
scénarios QA de base.
|
||||
- `qa/` : ressources d’amorçage adossées au dépôt pour la tâche de démarrage et les
|
||||
scénarios QA de référence.
|
||||
|
||||
Le flux opérateur QA actuel repose sur un site QA à deux volets :
|
||||
Le flux opérateur QA actuel est un site QA à deux volets :
|
||||
|
||||
- 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 de type Slack et le plan de scénario.
|
||||
|
||||
Lancez-le avec :
|
||||
Exécutez-le avec :
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Cela construit le site QA, démarre la voie Gateway adossée à Docker et expose la
|
||||
page QA Lab où un opérateur ou une boucle d’automatisation peut donner à l’agent une
|
||||
mission QA, observer le comportement réel du canal et consigner ce qui a
|
||||
fonctionné, échoué ou est resté bloqué.
|
||||
page QA Lab où un opérateur ou une boucle d’automatisation peut donner une
|
||||
mission QA à l’agent, observer le comportement réel du canal et consigner ce
|
||||
qui a fonctionné, échoué ou est resté bloqué.
|
||||
|
||||
Pour une itération plus rapide sur l’interface QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
Pour des itérations plus rapides sur l’interface de QA Lab sans reconstruire l’image Docker à chaque fois,
|
||||
démarrez la pile avec un bundle QA Lab monté par liaison :
|
||||
|
||||
```bash
|
||||
@ -54,40 +54,56 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` conserve les services Docker sur une image préconstruite et monte par liaison
|
||||
`qa:lab:up:fast` maintient les services Docker sur une image préconstruite et monte par liaison
|
||||
`extensions/qa-lab/web/dist` dans le conteneur `qa-lab`. `qa:lab:watch`
|
||||
reconstruit ce bundle à chaque modification, et le navigateur se recharge automatiquement lorsque le hachage des ressources QA Lab change.
|
||||
reconstruit ce bundle à chaque changement, et le navigateur se recharge automatiquement lorsque le hachage de ressource de QA Lab change.
|
||||
|
||||
## Ressources de départ adossées au dépôt
|
||||
Pour une voie VM Linux jetable sans faire intervenir Docker dans le parcours QA, exécutez :
|
||||
|
||||
Les ressources de départ se trouvent dans `qa/` :
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Cela démarre un invité Multipass vierge, installe les dépendances, construit OpenClaw
|
||||
dans l’invité, exécute `qa suite`, puis copie le rapport QA normal et le
|
||||
résumé vers `.artifacts/qa-e2e/...` sur l’hôte.
|
||||
Cela réutilise le même comportement de sélection de scénario que `qa suite` sur l’hôte.
|
||||
Les exécutions live transmettent les entrées d’authentification QA prises en charge qui sont pratiques pour
|
||||
l’invité : clés de fournisseur basées sur l’environnement, chemin de configuration du fournisseur live QA, et
|
||||
`CODEX_HOME` lorsqu’il est présent. Gardez `--output-dir` sous la racine du dépôt afin que l’invité
|
||||
puisse réécrire via l’espace de travail monté.
|
||||
|
||||
## Amorçages adossés au dépôt
|
||||
|
||||
Les ressources d’amorçage se trouvent dans `qa/` :
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
|
||||
Elles sont volontairement versionnées dans git afin que le plan QA soit visible à la fois pour les humains et pour l’agent. La liste de base doit rester suffisamment large pour couvrir :
|
||||
Elles sont volontairement conservées dans git afin que le plan QA soit visible à la fois pour les humains et pour
|
||||
l’agent. La liste de référence doit rester suffisamment large pour couvrir :
|
||||
|
||||
- chat en MP et en canal
|
||||
- comportement des fils
|
||||
- cycle de vie des actions de message
|
||||
- rappels cron
|
||||
- rappel en mémoire
|
||||
- changement de modèle
|
||||
- transfert à un sous-agent
|
||||
- lecture du dépôt et de la documentation
|
||||
- les MP et les discussions de canal
|
||||
- le comportement des fils
|
||||
- le cycle de vie des actions sur les messages
|
||||
- les rappels cron
|
||||
- le rappel mémoire
|
||||
- le changement de modèle
|
||||
- le transfert vers un sous-agent
|
||||
- la lecture du dépôt et de la documentation
|
||||
- une petite tâche de build comme Lobster Invaders
|
||||
|
||||
## Rapports
|
||||
|
||||
`qa-lab` exporte un rapport de protocole Markdown à partir de la chronologie observée du bus.
|
||||
Le rapport doit répondre aux questions suivantes :
|
||||
Le rapport doit répondre à :
|
||||
|
||||
- Ce qui a fonctionné
|
||||
- Ce qui a échoué
|
||||
- Ce qui est resté bloqué
|
||||
- Quels scénarios de suivi méritent d’être ajoutés
|
||||
- Quels scénarios de suivi valent la peine d’être ajoutés
|
||||
|
||||
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles réels
|
||||
Pour les vérifications de caractère et de style, exécutez le même scénario sur plusieurs références de modèles live
|
||||
et rédigez un rapport Markdown évalué :
|
||||
|
||||
```bash
|
||||
@ -109,29 +125,29 @@ pnpm openclaw qa character-eval \
|
||||
|
||||
La commande exécute des processus enfants locaux de passerelle QA, pas Docker. Les
|
||||
scénarios d’évaluation du caractère doivent définir la persona via `SOUL.md`, puis exécuter des tours utilisateur ordinaires
|
||||
comme du chat, de l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle candidat ne doit
|
||||
pas être informé qu’il est en cours d’évaluation. La commande préserve chaque
|
||||
transcription complète, enregistre des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
|
||||
un raisonnement `xhigh` de classer les exécutions selon leur naturel, leur ambiance et leur humour.
|
||||
comme le chat, l’aide sur l’espace de travail et de petites tâches sur des fichiers. Le modèle
|
||||
candidat ne doit pas être informé qu’il est en cours d’évaluation. La commande préserve chaque transcription complète,
|
||||
enregistre des statistiques d’exécution de base, puis demande aux modèles juges en mode rapide avec
|
||||
un raisonnement `xhigh` de classer les exécutions selon le naturel, l’ambiance et l’humour.
|
||||
Utilisez `--blind-judge-models` lors de la comparaison de fournisseurs : l’invite du juge reçoit toujours
|
||||
chaque transcription et le statut d’exécution, mais les références candidates sont remplacées par des
|
||||
étiquettes neutres comme `candidate-01` ; le rapport remappe les classements vers les références réelles après
|
||||
chaque transcription et statut d’exécution, mais les références candidates sont remplacées par des
|
||||
étiquettes neutres telles que `candidate-01` ; le rapport remappe les classements vers les références réelles après
|
||||
l’analyse.
|
||||
Les exécutions candidates utilisent par défaut le niveau de réflexion `high`, avec `xhigh` pour les modèles OpenAI qui
|
||||
le prennent en charge. Remplacez un candidat spécifique inline avec
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours un
|
||||
secours global, et l’ancien format `--model-thinking <provider/model=level>` est
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` définit toujours une
|
||||
valeur de repli globale, et l’ancien format `--model-thinking <provider/model=level>` est
|
||||
conservé pour compatibilité.
|
||||
Les références 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` inline lorsqu’un
|
||||
Les références candidates OpenAI utilisent par défaut le mode rapide afin que le traitement prioritaire soit utilisé là
|
||||
où le fournisseur le prend en charge. Ajoutez `,fast`, `,no-fast` ou `,fast=false` inline lorsqu’un
|
||||
candidat unique ou un juge a besoin d’une dérogation. Passez `--fast` uniquement si vous voulez
|
||||
forcer le 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 invites des juges précisent explicitement de
|
||||
ne pas classer selon la vitesse.
|
||||
enregistrées dans le rapport pour l’analyse comparative, mais les invites des juges indiquent explicitement
|
||||
de ne pas classer selon la vitesse.
|
||||
Les exécutions des modèles candidats et juges utilisent toutes deux par défaut une concurrence de 16. Réduisez
|
||||
`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression sur la passerelle locale
|
||||
rendent l’exécution trop bruyante.
|
||||
Lorsqu’aucun `--model` candidat n’est passé, l’évaluation du caractère utilise par défaut
|
||||
`--concurrency` ou `--judge-concurrency` lorsque les limites du fournisseur ou la pression locale sur la passerelle
|
||||
rendent une exécution trop bruyante.
|
||||
Lorsqu’aucun candidat `--model` n’est passé, l’évaluation du caractère utilise par défaut
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5`, et
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,34 +1,34 @@
|
||||
---
|
||||
read_when:
|
||||
- Implémentation ou mise à jour de clients WS de passerelle
|
||||
- Débogage des incompatibilités de protocole ou des échecs de connexion
|
||||
- Régénération du schéma/des modèles du protocole
|
||||
summary: 'Protocole WebSocket de la passerelle : handshake, trames, gestion des versions'
|
||||
title: Protocole de la passerelle
|
||||
- Implémenter ou mettre à jour des clients WS de gateway
|
||||
- Déboguer les incompatibilités de protocole ou les échecs de connexion
|
||||
- Régénérer le schéma/les modèles du protocole
|
||||
summary: 'Protocole WebSocket Gateway : handshake, trames, gestion des versions'
|
||||
title: Protocole Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:15:53Z"
|
||||
generated_at: "2026-04-10T06:55:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
|
||||
source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protocole de la passerelle (WebSocket)
|
||||
# Protocole Gateway (WebSocket)
|
||||
|
||||
Le protocole WS de la passerelle est le **plan de contrôle unique + transport de nœud** pour
|
||||
Le protocole WS Gateway est le **plan de contrôle unique + le transport de nœud** pour
|
||||
OpenClaw. Tous les clients (CLI, interface web, app macOS, nœuds iOS/Android,
|
||||
nœuds sans interface) se connectent via WebSocket et déclarent leur **rôle** + **portée** au
|
||||
moment du handshake.
|
||||
nœuds headless) se connectent via WebSocket et déclarent leur **rôle** + leur **portée**
|
||||
au moment du handshake.
|
||||
|
||||
## Transport
|
||||
|
||||
- WebSocket, trames texte avec charge utile JSON.
|
||||
- WebSocket, trames texte avec des payloads JSON.
|
||||
- La première trame **doit** être une requête `connect`.
|
||||
|
||||
## Handshake (`connect`)
|
||||
|
||||
Passerelle → Client (défi de pré-connexion) :
|
||||
Gateway → Client (défi pré-connexion) :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -38,7 +38,7 @@ Passerelle → Client (défi de pré-connexion) :
|
||||
}
|
||||
```
|
||||
|
||||
Client → Passerelle :
|
||||
Client → Gateway :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -73,7 +73,7 @@ Client → Passerelle :
|
||||
}
|
||||
```
|
||||
|
||||
Passerelle → Client :
|
||||
Gateway → Client :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -84,7 +84,7 @@ Passerelle → Client :
|
||||
}
|
||||
```
|
||||
|
||||
Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
|
||||
Lorsqu’un token d’appareil est émis, `hello-ok` inclut également :
|
||||
|
||||
```json
|
||||
{
|
||||
@ -96,7 +96,7 @@ Lorsqu’un jeton d’appareil est émis, `hello-ok` inclut également :
|
||||
}
|
||||
```
|
||||
|
||||
Pendant un transfert d’amorçage approuvé, `hello-ok.auth` peut aussi inclure des
|
||||
Pendant le transfert de bootstrap approuvé, `hello-ok.auth` peut aussi inclure des
|
||||
entrées de rôle supplémentaires bornées dans `deviceTokens` :
|
||||
|
||||
```json
|
||||
@ -116,12 +116,12 @@ entrées de rôle supplémentaires bornées dans `deviceTokens` :
|
||||
}
|
||||
```
|
||||
|
||||
Pour le flux d’amorçage intégré nœud/opérateur, le jeton principal du nœud reste sur
|
||||
`scopes: []` et tout jeton opérateur transmis reste borné à la liste d’autorisation
|
||||
de l’opérateur d’amorçage (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Les vérifications de portée d’amorçage restent
|
||||
préfixées par rôle : les entrées opérateur satisfont uniquement les requêtes opérateur, et les rôles non opérateur
|
||||
ont toujours besoin de portées sous leur propre préfixe de rôle.
|
||||
Pour le flux de bootstrap intégré nœud/opérateur, le token principal du nœud reste avec
|
||||
`scopes: []` et tout token opérateur transmis reste borné à la liste d’autorisation de
|
||||
l’opérateur de bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Les vérifications de portée de bootstrap restent
|
||||
préfixées par le rôle : les entrées opérateur ne satisfont que les requêtes opérateur, et les
|
||||
rôles non opérateur ont toujours besoin de portées sous leur propre préfixe de rôle.
|
||||
|
||||
### Exemple de nœud
|
||||
|
||||
@ -158,7 +158,7 @@ ont toujours besoin de portées sous leur propre préfixe de rôle.
|
||||
}
|
||||
```
|
||||
|
||||
## Format des trames
|
||||
## Encapsulation
|
||||
|
||||
- **Requête** : `{type:"req", id, method, params}`
|
||||
- **Réponse** : `{type:"res", id, ok, payload|error}`
|
||||
@ -170,10 +170,10 @@ Les méthodes avec effets de bord nécessitent des **clés d’idempotence** (vo
|
||||
|
||||
### Rôles
|
||||
|
||||
- `operator` = client du plan de contrôle (CLI/UI/automatisation).
|
||||
- `operator` = client de plan de contrôle (CLI/UI/automatisation).
|
||||
- `node` = hôte de capacités (camera/screen/canvas/system.run).
|
||||
|
||||
### Portées (opérateur)
|
||||
### Portées (`operator`)
|
||||
|
||||
Portées courantes :
|
||||
|
||||
@ -187,293 +187,308 @@ Portées courantes :
|
||||
`talk.config` avec `includeSecrets: true` nécessite `operator.talk.secrets`
|
||||
(ou `operator.admin`).
|
||||
|
||||
Les méthodes RPC de passerelle enregistrées par un plugin peuvent demander leur propre portée opérateur, mais
|
||||
Les méthodes RPC Gateway enregistrées par des plugins peuvent demander leur propre portée opérateur, mais
|
||||
les préfixes d’administration cœur réservés (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) sont toujours résolus vers `operator.admin`.
|
||||
|
||||
La portée de méthode n’est que le premier filtre. Certaines commandes slash atteintes via
|
||||
`chat.send` appliquent des vérifications plus strictes au niveau de la commande. Par exemple, les écritures persistantes
|
||||
`/config set` et `/config unset` nécessitent `operator.admin`.
|
||||
`chat.send` appliquent des vérifications plus strictes au niveau de la commande en plus. Par
|
||||
exemple, les écritures persistantes `/config set` et `/config unset` nécessitent `operator.admin`.
|
||||
|
||||
`node.pair.approve` a également une vérification de portée supplémentaire au moment de l’approbation en plus de la portée de méthode de base :
|
||||
`node.pair.approve` a également une vérification de portée supplémentaire au moment de l’approbation, en
|
||||
plus de la portée de méthode de base :
|
||||
|
||||
- requêtes sans commande : `operator.pairing`
|
||||
- requêtes avec des commandes de nœud autres que exec : `operator.pairing` + `operator.write`
|
||||
- requêtes avec des commandes de nœud hors exec : `operator.pairing` + `operator.write`
|
||||
- requêtes qui incluent `system.run`, `system.run.prepare` ou `system.which` :
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### `caps`/`commands`/`permissions` (nœud)
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
|
||||
Les nœuds déclarent des revendications de capacité au moment de la connexion :
|
||||
Les nœuds déclarent des revendications de capacités au moment de la connexion :
|
||||
|
||||
- `caps` : catégories de capacités de haut niveau.
|
||||
- `commands` : liste d’autorisation de commandes pour l’invocation.
|
||||
- `commands` : liste d’autorisation des commandes pour `invoke`.
|
||||
- `permissions` : bascules granulaires (par ex. `screen.record`, `camera.capture`).
|
||||
|
||||
La passerelle les traite comme des **revendications** et applique les listes d’autorisation côté serveur.
|
||||
La Gateway traite celles-ci comme des **revendications** et applique des listes d’autorisation côté serveur.
|
||||
|
||||
## Présence
|
||||
|
||||
- `system-presence` renvoie des entrées indexées par identité d’appareil.
|
||||
- Les entrées de présence incluent `deviceId`, `roles` et `scopes` afin que les interfaces puissent afficher une seule ligne par appareil
|
||||
même lorsqu’il se connecte à la fois comme **operator** et **node**.
|
||||
même lorsqu’il se connecte à la fois comme **operator** et comme **node**.
|
||||
|
||||
## Familles de méthodes RPC courantes
|
||||
## Familles courantes de méthodes RPC
|
||||
|
||||
Cette page n’est pas un dump complet généré, mais la surface WS publique est plus large
|
||||
que les exemples de handshake/auth ci-dessus. Voici les principales familles de méthodes que la
|
||||
passerelle expose aujourd’hui.
|
||||
Gateway expose aujourd’hui.
|
||||
|
||||
`hello-ok.features.methods` est une liste de découverte conservatrice construite à partir de
|
||||
`src/gateway/server-methods-list.ts` plus les exports de méthodes de plugin/canal chargés.
|
||||
Traitez-la comme une découverte de fonctionnalités, et non comme un dump généré de tous les helpers appelables
|
||||
`src/gateway/server-methods-list.ts` plus les exports de méthodes de plugins/canaux chargés.
|
||||
Traitez-la comme un mécanisme de découverte de fonctionnalités, pas comme un dump généré de tous les helpers appelables
|
||||
implémentés dans `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Système et identité
|
||||
|
||||
- `health` renvoie l’instantané de santé de la passerelle mis en cache ou sondé fraîchement.
|
||||
- `status` renvoie le résumé de la passerelle de style `/status` ; les champs sensibles sont
|
||||
- `health` renvoie le snapshot d’état de santé de la gateway, en cache ou fraîchement sondé.
|
||||
- `status` renvoie le résumé de gateway au format `/status` ; les champs sensibles sont
|
||||
inclus uniquement pour les clients opérateur avec portée admin.
|
||||
- `gateway.identity.get` renvoie l’identité d’appareil de la passerelle utilisée par les flux de relais et
|
||||
d’association.
|
||||
- `system-presence` renvoie l’instantané de présence actuel des appareils
|
||||
operator/node connectés.
|
||||
- `gateway.identity.get` renvoie l’identité d’appareil de la gateway utilisée par les flux de relais et
|
||||
de pairing.
|
||||
- `system-presence` renvoie le snapshot de présence actuel pour les appareils
|
||||
opérateur/nœud connectés.
|
||||
- `system-event` ajoute un événement système et peut mettre à jour/diffuser le contexte
|
||||
de présence.
|
||||
- `last-heartbeat` renvoie le dernier événement heartbeat persistant.
|
||||
- `set-heartbeats` active ou désactive le traitement des heartbeats sur la passerelle.
|
||||
- `last-heartbeat` renvoie le dernier événement heartbeat persisté.
|
||||
- `set-heartbeats` active ou désactive le traitement des heartbeats sur la gateway.
|
||||
|
||||
### Modèles et utilisation
|
||||
|
||||
- `models.list` renvoie le catalogue de modèles autorisé à l’exécution.
|
||||
- `usage.status` renvoie les fenêtres d’utilisation fournisseur / résumés du quota restant.
|
||||
- `usage.cost` renvoie des résumés agrégés de coût d’utilisation pour une plage de dates.
|
||||
- `models.list` renvoie le catalogue des modèles autorisés à l’exécution.
|
||||
- `usage.status` renvoie des résumés des fenêtres d’utilisation des fournisseurs et du quota restant.
|
||||
- `usage.cost` renvoie des résumés agrégés des coûts d’utilisation pour une plage de dates.
|
||||
- `doctor.memory.status` renvoie l’état de préparation de la mémoire vectorielle / des embeddings pour
|
||||
l’espace de travail de l’agent par défaut actif.
|
||||
- `sessions.usage` renvoie des résumés d’utilisation par session.
|
||||
- `sessions.usage.timeseries` renvoie des séries temporelles d’utilisation pour une session.
|
||||
- `sessions.usage.timeseries` renvoie une série temporelle d’utilisation pour une session.
|
||||
- `sessions.usage.logs` renvoie les entrées du journal d’utilisation pour une session.
|
||||
|
||||
### Canaux et helpers de connexion
|
||||
### Canaux et assistants de connexion
|
||||
|
||||
- `channels.status` renvoie les résumés d’état des canaux/plugins intégrés + groupés.
|
||||
- `channels.status` renvoie des résumés d’état des canaux/plugins intégrés + fournis.
|
||||
- `channels.logout` déconnecte un canal/compte spécifique là où le canal
|
||||
prend en charge la déconnexion.
|
||||
- `web.login.start` démarre un flux de connexion QR/web pour le fournisseur de canal web
|
||||
actuel compatible QR.
|
||||
- `web.login.wait` attend que ce flux de connexion QR/web se termine et démarre le
|
||||
- `web.login.wait` attend la fin de ce flux de connexion QR/web et démarre le
|
||||
canal en cas de succès.
|
||||
- `push.test` envoie une notification push APNs de test à un nœud iOS enregistré.
|
||||
- `voicewake.get` renvoie les déclencheurs de mot d’activation stockés.
|
||||
- `voicewake.set` met à jour les déclencheurs de mot d’activation et diffuse la modification.
|
||||
- `voicewake.set` met à jour les déclencheurs de mot d’activation et diffuse le changement.
|
||||
|
||||
### Messagerie et journaux
|
||||
|
||||
- `send` est la RPC de livraison sortante directe pour les envois ciblés par canal/compte/fil
|
||||
hors du moteur de chat.
|
||||
- `logs.tail` renvoie la fin du journal de fichiers configuré de la passerelle avec contrôles de curseur/limite et
|
||||
de nombre maximal d’octets.
|
||||
- `send` est la RPC de livraison sortante directe pour les envois
|
||||
ciblés par canal/compte/fil en dehors du moteur de chat.
|
||||
- `logs.tail` renvoie la fin du journal de fichiers configuré de la gateway avec des contrôles de curseur/limite et
|
||||
d’octets maximum.
|
||||
|
||||
### Talk et TTS
|
||||
|
||||
- `talk.config` renvoie la charge utile de configuration Talk effective ; `includeSecrets`
|
||||
- `talk.config` renvoie le payload de configuration Talk effectif ; `includeSecrets`
|
||||
nécessite `operator.talk.secrets` (ou `operator.admin`).
|
||||
- `talk.mode` définit/diffuse l’état actuel du mode Talk pour les clients WebChat/Control UI.
|
||||
- `talk.mode` définit/diffuse l’état actuel du mode Talk pour les clients
|
||||
WebChat/Control UI.
|
||||
- `talk.speak` synthétise la parole via le fournisseur de parole Talk actif.
|
||||
- `tts.status` renvoie l’état d’activation TTS, le fournisseur actif, les fournisseurs de secours,
|
||||
- `tts.status` renvoie l’état d’activation de TTS, le fournisseur actif, les fournisseurs de repli,
|
||||
et l’état de configuration du fournisseur.
|
||||
- `tts.providers` renvoie l’inventaire des fournisseurs TTS visibles.
|
||||
- `tts.enable` et `tts.disable` activent/désactivent l’état des préférences TTS.
|
||||
- `tts.providers` renvoie l’inventaire visible des fournisseurs TTS.
|
||||
- `tts.enable` et `tts.disable` activent ou désactivent l’état des préférences TTS.
|
||||
- `tts.setProvider` met à jour le fournisseur TTS préféré.
|
||||
- `tts.convert` exécute une conversion ponctuelle de texte en parole.
|
||||
- `tts.convert` exécute une conversion texte-parole ponctuelle.
|
||||
|
||||
### Secrets, configuration, mise à jour et assistant
|
||||
|
||||
- `secrets.reload` résout à nouveau les SecretRefs actifs et remplace l’état des secrets à l’exécution
|
||||
uniquement en cas de succès complet.
|
||||
- `secrets.resolve` résout les attributions de secrets ciblées par commande pour un ensemble commande/cible spécifique.
|
||||
- `config.get` renvoie l’instantané de configuration actuel et son hash.
|
||||
- `config.set` écrit une charge utile de configuration validée.
|
||||
- `secrets.resolve` résout les assignations de secrets ciblées par commande pour un ensemble spécifique
|
||||
de commandes/cibles.
|
||||
- `config.get` renvoie le snapshot de configuration actuel et son hash.
|
||||
- `config.set` écrit un payload de configuration validé.
|
||||
- `config.patch` fusionne une mise à jour partielle de configuration.
|
||||
- `config.apply` valide + remplace la charge utile complète de configuration.
|
||||
- `config.schema` renvoie la charge utile du schéma de configuration en direct utilisée par Control UI et
|
||||
- `config.apply` valide puis remplace le payload complet de configuration.
|
||||
- `config.schema` renvoie le payload du schéma de configuration live utilisé par Control UI et
|
||||
les outils CLI : schéma, `uiHints`, version et métadonnées de génération, y compris
|
||||
les métadonnées de schéma des plugins + canaux lorsque le runtime peut les charger. Le schéma
|
||||
les métadonnées de schéma de plugin + canal lorsque l’exécution peut les charger. Le schéma
|
||||
inclut les métadonnées de champ `title` / `description` dérivées des mêmes libellés
|
||||
et textes d’aide utilisés par l’interface, y compris pour les branches imbriquées objet, joker, élément de tableau
|
||||
et composition `anyOf` / `oneOf` / `allOf` lorsqu’une documentation de champ correspondante
|
||||
existe.
|
||||
- `config.schema.lookup` renvoie une charge utile de recherche limitée à un chemin pour un chemin de configuration :
|
||||
chemin normalisé, nœud de schéma superficiel, hint correspondant + `hintPath`, et
|
||||
et textes d’aide utilisés par l’UI, y compris pour les objets imbriqués, les jokers,
|
||||
les éléments de tableau et les branches de composition `anyOf` / `oneOf` / `allOf` lorsque la
|
||||
documentation de champ correspondante existe.
|
||||
- `config.schema.lookup` renvoie un payload de recherche limité à un chemin pour un chemin de configuration
|
||||
: chemin normalisé, nœud de schéma superficiel, indice correspondant + `hintPath`, et
|
||||
résumés immédiats des enfants pour l’exploration UI/CLI.
|
||||
- Les nœuds de schéma de recherche conservent la documentation destinée à l’utilisateur et les champs de validation courants :
|
||||
- Les nœuds de schéma de recherche conservent la documentation orientée utilisateur et les champs de validation courants :
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
bornes numériques/chaînes/tableaux/objets, et indicateurs booléens comme
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- Les résumés enfants exposent `key`, le `path` normalisé, `type`, `required`,
|
||||
`hasChildren`, plus le `hint` / `hintPath` correspondant.
|
||||
- `update.run` exécute le flux de mise à jour de la passerelle et planifie un redémarrage uniquement lorsque
|
||||
- Les résumés des enfants exposent `key`, le `path` normalisé, `type`, `required`,
|
||||
`hasChildren`, ainsi que le `hint` / `hintPath` correspondant.
|
||||
- `update.run` exécute le flux de mise à jour de la gateway et planifie un redémarrage uniquement lorsque
|
||||
la mise à jour elle-même a réussi.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` et `wizard.cancel` exposent l’assistant
|
||||
d’onboarding via WS RPC.
|
||||
d’onboarding via RPC WS.
|
||||
|
||||
### Grandes familles existantes
|
||||
### Familles majeures existantes
|
||||
|
||||
#### Helpers d’agent et d’espace de travail
|
||||
#### Assistants d’agent et d’espace de travail
|
||||
|
||||
- `agents.list` renvoie les entrées d’agent configurées.
|
||||
- `agents.create`, `agents.update` et `agents.delete` gèrent les enregistrements d’agent et
|
||||
le câblage de l’espace de travail.
|
||||
le raccordement de l’espace de travail.
|
||||
- `agents.files.list`, `agents.files.get` et `agents.files.set` gèrent les
|
||||
fichiers d’espace de travail d’amorçage exposés pour un agent.
|
||||
- `agent.identity.get` renvoie l’identité effective de l’assistant pour un agent ou une
|
||||
session.
|
||||
- `agent.wait` attend qu’une exécution se termine et renvoie l’instantané terminal lorsqu’il est
|
||||
fichiers de l’espace de travail de bootstrap exposés pour un agent.
|
||||
- `agent.identity.get` renvoie l’identité effective de l’assistant pour un agent ou
|
||||
une session.
|
||||
- `agent.wait` attend la fin d’une exécution et renvoie le snapshot terminal lorsqu’il est
|
||||
disponible.
|
||||
|
||||
#### Contrôle de session
|
||||
|
||||
- `sessions.list` renvoie l’index actuel des sessions.
|
||||
- `sessions.subscribe` et `sessions.unsubscribe` activent/désactivent les abonnements aux événements de changement de session
|
||||
pour le client WS actuel.
|
||||
- `sessions.messages.subscribe` et `sessions.messages.unsubscribe` activent/désactivent les
|
||||
abonnements aux événements de transcription/message pour une session.
|
||||
- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés de session spécifiques.
|
||||
- `sessions.subscribe` et `sessions.unsubscribe` activent ou désactivent les
|
||||
abonnements aux événements de changement de session pour le client WS actuel.
|
||||
- `sessions.messages.subscribe` et `sessions.messages.unsubscribe` activent ou désactivent
|
||||
les abonnements aux événements de transcription/message pour une session.
|
||||
- `sessions.preview` renvoie des aperçus bornés de transcription pour des clés
|
||||
de session spécifiques.
|
||||
- `sessions.resolve` résout ou canonicalise une cible de session.
|
||||
- `sessions.create` crée une nouvelle entrée de session.
|
||||
- `sessions.send` envoie un message dans une session existante.
|
||||
- `sessions.steer` est la variante interrompre-et-réorienter pour une session active.
|
||||
- `sessions.steer` est la variante interruption-et-réorientation pour une session active.
|
||||
- `sessions.abort` interrompt le travail actif pour une session.
|
||||
- `sessions.patch` met à jour les métadonnées/remplacements de session.
|
||||
- `sessions.reset`, `sessions.delete` et `sessions.compact` effectuent la
|
||||
maintenance de session.
|
||||
- `sessions.get` renvoie la ligne complète de session stockée.
|
||||
- l’exécution de chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
|
||||
- l’exécution du chat utilise toujours `chat.history`, `chat.send`, `chat.abort` et
|
||||
`chat.inject`.
|
||||
- `chat.history` est normalisé pour l’affichage pour les clients UI : les balises de directive en ligne sont
|
||||
supprimées du texte visible, les charges utiles XML d’appel d’outil en texte brut (y compris
|
||||
- `chat.history` est normalisé pour l’affichage pour les clients UI : les balises de directive inline sont
|
||||
supprimées du texte visible, les payloads XML d’appel d’outil en texte brut (y compris
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, et
|
||||
les blocs d’appel d’outil tronqués) ainsi que les jetons de contrôle du modèle ASCII/pleine largeur divulgués
|
||||
sont supprimés, les lignes assistant composées uniquement de jetons silencieux telles que `NO_REPLY` /
|
||||
`no_reply` exact sont omises, et les lignes surdimensionnées peuvent être remplacées par des espaces réservés.
|
||||
les blocs d’appel d’outil tronqués) ainsi que les jetons de contrôle de modèle ASCII/pleine largeur divulgués
|
||||
sont supprimés, les lignes d’assistant ne contenant que des jetons silencieux, telles que `NO_REPLY` /
|
||||
`no_reply` exacts, sont omises, et les lignes surdimensionnées peuvent être remplacées par des placeholders.
|
||||
|
||||
#### Association d’appareil et jetons d’appareil
|
||||
#### Pairing d’appareils et tokens d’appareil
|
||||
|
||||
- `device.pair.list` renvoie les appareils associés en attente et approuvés.
|
||||
- `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent
|
||||
les enregistrements d’association d’appareil.
|
||||
- `device.token.rotate` fait pivoter un jeton d’appareil associé dans les limites de rôle
|
||||
et de portée approuvées.
|
||||
- `device.token.revoke` révoque un jeton d’appareil associé.
|
||||
- `device.pair.list` renvoie les appareils pairés en attente et approuvés.
|
||||
- `device.pair.approve`, `device.pair.reject` et `device.pair.remove` gèrent les
|
||||
enregistrements de pairing d’appareil.
|
||||
- `device.token.rotate` fait tourner un token d’appareil pairé dans les limites de son rôle
|
||||
et de ses portées approuvés.
|
||||
- `device.token.revoke` révoque un token d’appareil pairé.
|
||||
|
||||
#### Association de nœud, invocation et travail en attente
|
||||
#### Pairing de nœud, `invoke` et travail en attente
|
||||
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
|
||||
`node.pair.reject` et `node.pair.verify` couvrent l’association de nœud et la
|
||||
vérification d’amorçage.
|
||||
`node.pair.reject` et `node.pair.verify` couvrent le pairing de nœud et la
|
||||
vérification du bootstrap.
|
||||
- `node.list` et `node.describe` renvoient l’état des nœuds connus/connectés.
|
||||
- `node.rename` met à jour un libellé de nœud associé.
|
||||
- `node.rename` met à jour un libellé de nœud pairé.
|
||||
- `node.invoke` transmet une commande à un nœud connecté.
|
||||
- `node.invoke.result` renvoie le résultat d’une requête d’invocation.
|
||||
- `node.event` transporte des événements provenant d’un nœud vers la passerelle.
|
||||
- `node.canvas.capability.refresh` rafraîchit les jetons de capacité canvas à portée limitée.
|
||||
- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente pour nœuds connectés.
|
||||
- `node.pending.enqueue` et `node.pending.drain` gèrent le travail en attente durable
|
||||
- `node.invoke.result` renvoie le résultat d’une requête `invoke`.
|
||||
- `node.event` transporte les événements d’origine nœud de retour vers la gateway.
|
||||
- `node.canvas.capability.refresh` rafraîchit les tokens de capacité canvas à portée limitée.
|
||||
- `node.pending.pull` et `node.pending.ack` sont les API de file d’attente des nœuds connectés.
|
||||
- `node.pending.enqueue` et `node.pending.drain` gèrent le travail durable en attente
|
||||
pour les nœuds hors ligne/déconnectés.
|
||||
|
||||
#### Familles d’approbation
|
||||
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` et
|
||||
`exec.approval.resolve` couvrent les demandes ponctuelles d’approbation exec ainsi que la
|
||||
`exec.approval.resolve` couvrent les requêtes d’approbation exec ponctuelles ainsi que la
|
||||
recherche/relecture des approbations en attente.
|
||||
- `exec.approval.waitDecision` attend une approbation exec en attente et renvoie
|
||||
la décision finale (ou `null` en cas de dépassement de délai).
|
||||
- `exec.approvals.get` et `exec.approvals.set` gèrent les instantanés de politique
|
||||
d’approbation exec de la passerelle.
|
||||
- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale exec
|
||||
du nœud via des commandes relais de nœud.
|
||||
la décision finale (ou `null` en cas de délai d’attente).
|
||||
- `exec.approvals.get` et `exec.approvals.set` gèrent les snapshots de politique
|
||||
d’approbation exec de la gateway.
|
||||
- `exec.approvals.node.get` et `exec.approvals.node.set` gèrent la politique locale de
|
||||
d’approbation exec du nœud via des commandes de relais de nœud.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` et `plugin.approval.resolve` couvrent
|
||||
les flux d’approbation définis par plugin.
|
||||
les flux d’approbation définis par les plugins.
|
||||
|
||||
#### Autres grandes familles
|
||||
#### Autres familles majeures
|
||||
|
||||
- automatisation :
|
||||
- `wake` planifie une injection immédiate ou au prochain heartbeat d’un texte de réveil
|
||||
- `wake` planifie une injection de texte de réveil immédiate ou au prochain heartbeat
|
||||
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
|
||||
`cron.run`, `cron.runs`
|
||||
- skills/outils : `skills.*`, `tools.catalog`, `tools.effective`
|
||||
- Skills/outils : `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
|
||||
|
||||
### Familles d’événements courantes
|
||||
|
||||
- `chat` : mises à jour de chat UI telles que `chat.inject` et autres événements
|
||||
de chat uniquement liés à la transcription.
|
||||
de chat limités à la transcription.
|
||||
- `session.message` et `session.tool` : mises à jour de transcription/flux d’événements pour une
|
||||
session abonnée.
|
||||
- `sessions.changed` : l’index de session ou les métadonnées ont changé.
|
||||
- `presence` : mises à jour de l’instantané de présence système.
|
||||
- `tick` : événement périodique de keepalive / vivacité.
|
||||
- `health` : mise à jour de l’instantané de santé de la passerelle.
|
||||
- `presence` : mises à jour du snapshot de présence du système.
|
||||
- `tick` : événement périodique de keepalive / vitalité.
|
||||
- `health` : mise à jour du snapshot de santé de la gateway.
|
||||
- `heartbeat` : mise à jour du flux d’événements heartbeat.
|
||||
- `cron` : événement de changement d’exécution/tâche cron.
|
||||
- `shutdown` : notification d’arrêt de la passerelle.
|
||||
- `node.pair.requested` / `node.pair.resolved` : cycle de vie de l’association de nœud.
|
||||
- `cron` : événement de changement d’exécution/de tâche cron.
|
||||
- `shutdown` : notification d’arrêt de la gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved` : cycle de vie du pairing de nœud.
|
||||
- `node.invoke.request` : diffusion de requête d’invocation de nœud.
|
||||
- `device.pair.requested` / `device.pair.resolved` : cycle de vie des appareils associés.
|
||||
- `voicewake.changed` : modification de la configuration des déclencheurs de mot d’activation.
|
||||
- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie
|
||||
d’approbation exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie d’approbation
|
||||
de plugin.
|
||||
- `device.pair.requested` / `device.pair.resolved` : cycle de vie des appareils pairés.
|
||||
- `voicewake.changed` : la configuration des déclencheurs de mot d’activation a changé.
|
||||
- `exec.approval.requested` / `exec.approval.resolved` : cycle de vie de
|
||||
l’approbation exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved` : cycle de vie de
|
||||
l’approbation de plugin.
|
||||
|
||||
### Méthodes helper pour les nœuds
|
||||
### Méthodes utilitaires de nœud
|
||||
|
||||
- Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables
|
||||
de skill pour les vérifications d’auto-autorisation.
|
||||
- Les nœuds peuvent appeler `skills.bins` pour récupérer la liste actuelle des exécutables de skill
|
||||
pour les vérifications d’auto-autorisation.
|
||||
|
||||
### Méthodes helper pour les opérateurs
|
||||
### Méthodes utilitaires d’opérateur
|
||||
|
||||
- Les opérateurs peuvent appeler `commands.list` (`operator.read`) pour récupérer l’inventaire des commandes à l’exécution pour un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
|
||||
- `scope` contrôle quelle surface la valeur `name` principale cible :
|
||||
- `text` renvoie le jeton principal de commande texte sans le `/` initial
|
||||
- `native` et le chemin par défaut `both` renvoient des noms natifs adaptés au fournisseur
|
||||
lorsqu’ils sont disponibles
|
||||
- `textAliases` contient des alias slash exacts tels que `/model` et `/m`.
|
||||
- `nativeName` contient le nom de commande natif adapté au fournisseur lorsqu’il existe.
|
||||
- `provider` est facultatif et n’affecte que le nommage natif ainsi que la disponibilité
|
||||
des commandes natives de plugin.
|
||||
- `includeArgs=false` omet les métadonnées d’arguments sérialisées de la réponse.
|
||||
- Les opérateurs peuvent appeler `tools.catalog` (`operator.read`) pour récupérer le catalogue d’outils à l’exécution pour un
|
||||
agent. La réponse inclut des outils groupés et des métadonnées de provenance :
|
||||
agent. La réponse inclut les outils groupés et les métadonnées de provenance :
|
||||
- `source` : `core` ou `plugin`
|
||||
- `pluginId` : propriétaire du plugin lorsque `source="plugin"`
|
||||
- `optional` : indique si un outil de plugin est optionnel
|
||||
- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire effectif des outils à l’exécution
|
||||
- `optional` : si un outil de plugin est facultatif
|
||||
- Les opérateurs peuvent appeler `tools.effective` (`operator.read`) pour récupérer l’inventaire d’outils effectivement actif à l’exécution
|
||||
pour une session.
|
||||
- `sessionKey` est requis.
|
||||
- La passerelle dérive le contexte d’exécution de confiance côté serveur à partir de la session au lieu d’accepter
|
||||
- La gateway dérive le contexte d’exécution fiable côté serveur à partir de la session au lieu d’accepter
|
||||
un contexte d’authentification ou de livraison fourni par l’appelant.
|
||||
- La réponse est limitée à la session et reflète ce que la conversation active peut utiliser immédiatement,
|
||||
y compris les outils cœur, plugin et canal.
|
||||
- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire
|
||||
visible des skills pour un agent.
|
||||
- `agentId` est optionnel ; omettez-le pour lire l’espace de travail de l’agent par défaut.
|
||||
- La réponse est limitée à la session et reflète ce que la conversation active peut utiliser maintenant,
|
||||
y compris les outils core, plugin et de canal.
|
||||
- Les opérateurs peuvent appeler `skills.status` (`operator.read`) pour récupérer l’inventaire visible des
|
||||
Skills pour un agent.
|
||||
- `agentId` est facultatif ; omettez-le pour lire l’espace de travail de l’agent par défaut.
|
||||
- La réponse inclut l’éligibilité, les exigences manquantes, les vérifications de configuration et
|
||||
les options d’installation nettoyées sans exposer les valeurs brutes des secrets.
|
||||
- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour
|
||||
les métadonnées de découverte ClawHub.
|
||||
les options d’installation nettoyées sans exposer les valeurs secrètes brutes.
|
||||
- Les opérateurs peuvent appeler `skills.search` et `skills.detail` (`operator.read`) pour les métadonnées
|
||||
de découverte ClawHub.
|
||||
- Les opérateurs peuvent appeler `skills.install` (`operator.admin`) dans deux modes :
|
||||
- mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
|
||||
- Mode ClawHub : `{ source: "clawhub", slug, version?, force? }` installe un
|
||||
dossier de skill dans le répertoire `skills/` de l’espace de travail de l’agent par défaut.
|
||||
- mode installateur de passerelle : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
exécute une action `metadata.openclaw.install` déclarée sur l’hôte de la passerelle.
|
||||
- Mode installateur Gateway : `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
exécute une action déclarée `metadata.openclaw.install` sur l’hôte gateway.
|
||||
- Les opérateurs peuvent appeler `skills.update` (`operator.admin`) dans deux modes :
|
||||
- le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
|
||||
- Le mode ClawHub met à jour un slug suivi ou toutes les installations ClawHub suivies dans
|
||||
l’espace de travail de l’agent par défaut.
|
||||
- le mode config modifie les valeurs `skills.entries.<skillKey>` telles que `enabled`,
|
||||
- Le mode configuration patche les valeurs `skills.entries.<skillKey>` telles que `enabled`,
|
||||
`apiKey` et `env`.
|
||||
|
||||
## Approbations exec
|
||||
|
||||
- Lorsqu’une requête exec nécessite une approbation, la passerelle diffuse `exec.approval.requested`.
|
||||
- Lorsqu’une requête exec nécessite une approbation, la gateway diffuse `exec.approval.requested`.
|
||||
- Les clients opérateur résolvent cela en appelant `exec.approval.resolve` (nécessite la portée `operator.approvals`).
|
||||
- Pour `host=node`, `exec.approval.request` doit inclure `systemRunPlan` (`argv`/`cwd`/`rawCommand`/métadonnées de session canoniques). Les requêtes sans `systemRunPlan` sont rejetées.
|
||||
- Après approbation, les appels transmis `node.invoke system.run` réutilisent ce
|
||||
`systemRunPlan` canonique comme contexte faisant autorité pour la commande/le cwd/la session.
|
||||
- Après l’approbation, les appels `node.invoke system.run` transmis réutilisent ce
|
||||
`systemRunPlan` canonique comme contexte autoritaire de commande/cwd/session.
|
||||
- Si un appelant modifie `command`, `rawCommand`, `cwd`, `agentId` ou
|
||||
`sessionKey` entre la préparation et le transfert final approuvé de `system.run`, la
|
||||
passerelle rejette l’exécution au lieu de faire confiance à la charge utile modifiée.
|
||||
`sessionKey` entre `prepare` et la transmission finale approuvée de `system.run`, la
|
||||
gateway rejette l’exécution au lieu de faire confiance au payload modifié.
|
||||
|
||||
## Repli de livraison d’agent
|
||||
|
||||
@ -485,108 +500,108 @@ implémentés dans `src/gateway/server-methods/*.ts`.
|
||||
|
||||
- `PROTOCOL_VERSION` se trouve dans `src/gateway/protocol/schema.ts`.
|
||||
- Les clients envoient `minProtocol` + `maxProtocol` ; le serveur rejette les incompatibilités.
|
||||
- Les schémas + modèles sont générés à partir des définitions TypeBox :
|
||||
- Les schémas + modèles sont générés à partir de définitions TypeBox :
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
## Auth
|
||||
## Authentification
|
||||
|
||||
- L’authentification de passerelle par secret partagé utilise `connect.params.auth.token` ou
|
||||
- L’authentification gateway par secret partagé utilise `connect.params.auth.token` ou
|
||||
`connect.params.auth.password`, selon le mode d’authentification configuré.
|
||||
- Les modes porteurs d’identité comme Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) ou le mode non-loopback
|
||||
`gateway.auth.mode: "trusted-proxy"` satisfont la vérification d’authentification de connexion à partir des
|
||||
en-têtes de requête au lieu de `connect.params.auth.*`.
|
||||
- Le mode d’entrée privée `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ; n’exposez pas ce mode sur une entrée publique/non fiable.
|
||||
- Après l’association, la passerelle émet un **jeton d’appareil** limité au
|
||||
rôle + portées de la connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
|
||||
- Les modes porteurs d’identité tels que Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) ou
|
||||
`gateway.auth.mode: "trusted-proxy"` hors loopback satisfont la vérification d’authentification de connexion à partir
|
||||
des en-têtes de requête au lieu de `connect.params.auth.*`.
|
||||
- Le mode d’entrée privée `gateway.auth.mode: "none"` ignore entièrement l’authentification de connexion par secret partagé ;
|
||||
n’exposez pas ce mode sur une entrée publique/non fiable.
|
||||
- Après le pairing, la Gateway émet un **token d’appareil** limité au rôle + aux portées
|
||||
de la connexion. Il est renvoyé dans `hello-ok.auth.deviceToken` et doit être
|
||||
persisté par le client pour les connexions futures.
|
||||
- Les clients doivent persister le `hello-ok.auth.deviceToken` principal après toute
|
||||
connexion réussie.
|
||||
- Une reconnexion avec ce jeton d’appareil **stocké** doit également réutiliser l’ensemble de portées approuvées stocké
|
||||
pour ce jeton. Cela préserve l’accès déjà accordé en lecture/sondage/état
|
||||
et évite que les reconnexions ne se réduisent silencieusement à une
|
||||
portée implicite plus étroite limitée à l’administration.
|
||||
- L’ordre de priorité normal de l’authentification de connexion est le suivant : jeton/mot de passe partagé explicite d’abord, puis
|
||||
`deviceToken` explicite, puis jeton stocké par appareil, puis jeton d’amorçage.
|
||||
- Les entrées supplémentaires `hello-ok.auth.deviceTokens` sont des jetons de transfert d’amorçage.
|
||||
Ne les persistez que lorsque la connexion a utilisé une authentification d’amorçage sur un transport de confiance
|
||||
tel que `wss://` ou loopback/association locale.
|
||||
- La reconnexion avec ce token d’appareil **stocké** doit également réutiliser l’ensemble de portées approuvées
|
||||
stocké pour ce token. Cela préserve l’accès lecture/sonde/statut qui avait déjà été
|
||||
accordé et évite de réduire silencieusement les reconnexions à une
|
||||
portée implicite plus étroite réservée à l’admin.
|
||||
- L’ordre de priorité normal de l’authentification de connexion est d’abord le token/mot de passe partagé explicite, puis
|
||||
le `deviceToken` explicite, puis le token par appareil stocké, puis le token de bootstrap.
|
||||
- Les entrées supplémentaires `hello-ok.auth.deviceTokens` sont des tokens de transfert de bootstrap.
|
||||
Persistez-les uniquement lorsque la connexion a utilisé l’authentification bootstrap sur un transport fiable
|
||||
tel que `wss://` ou loopback/pairing local.
|
||||
- Si un client fournit un `deviceToken` **explicite** ou des `scopes` explicites, cet
|
||||
ensemble de portées demandé par l’appelant reste prioritaire ; les portées mises en cache ne sont réutilisées que
|
||||
lorsque le client réutilise le jeton stocké par appareil.
|
||||
- Les jetons d’appareil peuvent être tournés/révoqués via `device.token.rotate` et
|
||||
ensemble de portées demandé par l’appelant reste autoritaire ; les portées en cache ne sont réutilisées que lorsque le client réutilise le token par appareil stocké.
|
||||
- Les tokens d’appareil peuvent être tournés/révoqués via `device.token.rotate` et
|
||||
`device.token.revoke` (nécessite la portée `operator.pairing`).
|
||||
- L’émission/la rotation de jeton reste bornée à l’ensemble des rôles approuvés enregistré dans
|
||||
l’entrée d’association de cet appareil ; faire pivoter un jeton ne peut pas élargir l’appareil à un
|
||||
rôle que l’approbation d’association n’a jamais accordé.
|
||||
- Pour les sessions de jeton d’appareil associé, la gestion des appareils est limitée à soi-même sauf si
|
||||
l’appelant possède également `operator.admin` : les appelants non admin peuvent supprimer/révoquer/faire pivoter uniquement
|
||||
leur **propre** entrée d’appareil.
|
||||
- L’émission/la rotation de token reste limitée à l’ensemble de rôles approuvés enregistré dans
|
||||
l’entrée de pairing de cet appareil ; la rotation d’un token ne peut pas étendre l’appareil à un
|
||||
rôle que l’approbation de pairing n’a jamais accordé.
|
||||
- Pour les sessions de token d’appareil pairé, la gestion des appareils est limitée à soi-même sauf si l’appelant
|
||||
possède aussi `operator.admin` : les appelants non admin ne peuvent supprimer/révoquer/faire tourner
|
||||
que leur **propre** entrée d’appareil.
|
||||
- `device.token.rotate` vérifie également l’ensemble de portées opérateur demandé par rapport aux
|
||||
portées de la session actuelle de l’appelant. Les appelants non admin ne peuvent pas faire pivoter un jeton vers
|
||||
un ensemble de portées opérateur plus large que celui qu’ils possèdent déjà.
|
||||
- Les échecs d’authentification incluent `error.details.code` ainsi que des indices de récupération :
|
||||
portées actuelles de session de l’appelant. Les appelants non admin ne peuvent pas faire tourner un token vers
|
||||
un ensemble de portées opérateur plus large que celui qu’ils détiennent déjà.
|
||||
- Les échecs d’authentification incluent `error.details.code` ainsi que des indications de récupération :
|
||||
- `error.details.canRetryWithDeviceToken` (booléen)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Comportement client pour `AUTH_TOKEN_MISMATCH` :
|
||||
- Les clients de confiance peuvent tenter une reprise bornée avec un jeton mis en cache par appareil.
|
||||
- Si cette reprise échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des indications d’action à l’opérateur.
|
||||
- Les clients de confiance peuvent tenter une unique nouvelle tentative bornée avec un token par appareil en cache.
|
||||
- Si cette nouvelle tentative échoue, les clients doivent arrêter les boucles de reconnexion automatiques et afficher des instructions d’action à l’opérateur.
|
||||
|
||||
## Identité d’appareil + association
|
||||
## Identité d’appareil + pairing
|
||||
|
||||
- Les nœuds doivent inclure une identité d’appareil stable (`device.id`) dérivée de l’empreinte d’une
|
||||
paire de clés.
|
||||
- Les passerelles émettent des jetons par appareil + rôle.
|
||||
- Des approbations d’association sont requises pour les nouveaux IDs d’appareil sauf si
|
||||
l’approbation automatique locale est activée.
|
||||
- L’approbation automatique d’association est centrée sur les connexions directes locales loopback.
|
||||
- OpenClaw dispose également d’un chemin restreint d’auto-connexion backend/conteneur-local pour
|
||||
des flux helper de secret partagé de confiance.
|
||||
- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour l’association et
|
||||
- Les gateways émettent des tokens par appareil + rôle.
|
||||
- Les approbations de pairing sont requises pour les nouveaux IDs d’appareil, sauf si
|
||||
l’auto-approbation locale est activée.
|
||||
- L’auto-approbation de pairing est centrée sur les connexions directes de local loopback.
|
||||
- OpenClaw dispose également d’un chemin étroit d’auto-connexion backend/local au conteneur pour
|
||||
des flux d’assistant de secret partagé approuvés.
|
||||
- Les connexions tailnet ou LAN sur le même hôte sont toujours traitées comme distantes pour le pairing et
|
||||
nécessitent une approbation.
|
||||
- Tous les clients WS doivent inclure l’identité `device` pendant `connect` (operator + node).
|
||||
Control UI peut l’omettre uniquement dans les modes suivants :
|
||||
- `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost uniquement.
|
||||
Control UI ne peut l’omettre que dans ces modes :
|
||||
- `gateway.controlUi.allowInsecureAuth=true` pour la compatibilité HTTP non sécurisée localhost-only.
|
||||
- authentification opérateur Control UI réussie avec `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (mode de dernier recours, forte dégradation de sécurité).
|
||||
- Toutes les connexions doivent signer le nonce fourni par le serveur dans `connect.challenge`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (bris de glace, grave dégradation de sécurité).
|
||||
- Toutes les connexions doivent signer le nonce `connect.challenge` fourni par le serveur.
|
||||
|
||||
### Diagnostics de migration de l’authentification d’appareil
|
||||
|
||||
Pour les clients hérités qui utilisent encore le comportement de signature antérieur au défi, `connect` renvoie désormais
|
||||
des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec une valeur stable `error.details.reason`.
|
||||
Pour les clients hérités qui utilisent encore le comportement de signature antérieur au challenge, `connect` renvoie désormais
|
||||
des codes de détail `DEVICE_AUTH_*` sous `error.details.code` avec une valeur stable dans `error.details.reason`.
|
||||
|
||||
Échecs de migration courants :
|
||||
Échecs courants de migration :
|
||||
|
||||
| Message | details.code | details.reason | Signification |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Le client a omis `device.nonce` (ou a envoyé une valeur vide). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Le client a signé avec un nonce obsolète/incorrect. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La charge utile de signature ne correspond pas à la charge utile v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est en dehors du décalage autorisé. |
|
||||
| Message | details.code | details.reason | Signification |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Le client a omis `device.nonce` (ou l’a envoyé vide). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Le client a signé avec un nonce périmé/incorrect. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Le payload de signature ne correspond pas au payload v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | L’horodatage signé est hors du décalage autorisé. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` ne correspond pas à l’empreinte de la clé publique. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Le format/canonicalisation de la clé publique a échoué. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Le format / la canonicalisation de la clé publique a échoué. |
|
||||
|
||||
Cible de migration :
|
||||
|
||||
- Toujours attendre `connect.challenge`.
|
||||
- Signer la charge utile v2 qui inclut le nonce du serveur.
|
||||
- Signer le payload v2 qui inclut le nonce du serveur.
|
||||
- Envoyer le même nonce dans `connect.params.device.nonce`.
|
||||
- La charge utile de signature préférée est `v3`, qui lie `platform` et `deviceFamily`
|
||||
en plus des champs device/client/role/scopes/token/nonce.
|
||||
- Le payload de signature préféré est `v3`, qui lie `platform` et `deviceFamily`
|
||||
en plus des champs appareil/client/rôle/portées/token/nonce.
|
||||
- Les signatures héritées `v2` restent acceptées pour compatibilité, mais l’épinglage des métadonnées
|
||||
des appareils associés continue de contrôler la politique de commande lors de la reconnexion.
|
||||
d’appareil pairé contrôle toujours la politique de commande lors de la reconnexion.
|
||||
|
||||
## TLS + épinglage
|
||||
|
||||
- TLS est pris en charge pour les connexions WS.
|
||||
- Les clients peuvent éventuellement épingler l’empreinte du certificat de la passerelle (voir la configuration `gateway.tls`
|
||||
ainsi que `gateway.remote.tlsFingerprint` ou le CLI `--tls-fingerprint`).
|
||||
- Les clients peuvent éventuellement épingler l’empreinte du certificat gateway (voir la configuration `gateway.tls`
|
||||
ainsi que `gateway.remote.tlsFingerprint` ou la CLI `--tls-fingerprint`).
|
||||
|
||||
## Portée
|
||||
|
||||
Ce protocole expose l’**API complète de la passerelle** (état, canaux, modèles, chat,
|
||||
Ce protocole expose l’**API gateway complète** (état, canaux, modèles, chat,
|
||||
agent, sessions, nœuds, approbations, etc.). La surface exacte est définie par les
|
||||
schémas TypeBox dans `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,41 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Vous souhaitez configurer les fournisseurs de recherche mémoire ou les modèles d’embeddings
|
||||
- Vous souhaitez configurer des fournisseurs de recherche en mémoire ou des modèles d’embeddings
|
||||
- Vous souhaitez configurer le backend QMD
|
||||
- Vous souhaitez ajuster la recherche hybride, le MMR ou la décroissance temporelle
|
||||
- Vous souhaitez activer l’indexation mémoire multimodale
|
||||
summary: Tous les paramètres de configuration pour la recherche mémoire, les fournisseurs d’embeddings, QMD, la recherche hybride et l’indexation multimodale
|
||||
- Vous souhaitez activer l’indexation de mémoire multimodale
|
||||
summary: Tous les paramètres de configuration pour la recherche en mémoire, les fournisseurs d’embeddings, QMD, la recherche hybride et l’indexation multimodale
|
||||
title: Référence de configuration de la mémoire
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:13:33Z"
|
||||
generated_at: "2026-04-10T06:56:10Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Référence de configuration de la mémoire
|
||||
|
||||
Cette page répertorie tous les paramètres de configuration de la recherche mémoire d’OpenClaw. Pour des aperçus conceptuels, voir :
|
||||
Cette page répertorie tous les paramètres de configuration pour la recherche en mémoire d’OpenClaw. Pour des aperçus conceptuels, voir :
|
||||
|
||||
- [Vue d’ensemble de la mémoire](/fr/concepts/memory) -- fonctionnement de la mémoire
|
||||
- [Moteur intégré](/fr/concepts/memory-builtin) -- backend SQLite par défaut
|
||||
- [Moteur QMD](/fr/concepts/memory-qmd) -- sidecar local-first
|
||||
- [Recherche mémoire](/fr/concepts/memory-search) -- pipeline de recherche et réglages
|
||||
- [Recherche en mémoire](/fr/concepts/memory-search) -- pipeline de recherche et ajustement
|
||||
- [Mémoire active](/fr/concepts/active-memory) -- activer le sous-agent de mémoire pour les sessions interactives
|
||||
|
||||
Tous les paramètres de recherche mémoire se trouvent sous `agents.defaults.memorySearch` dans `openclaw.json`, sauf indication contraire.
|
||||
Tous les paramètres de recherche en mémoire se trouvent sous `agents.defaults.memorySearch` dans `openclaw.json`, sauf indication contraire.
|
||||
|
||||
Si vous recherchez le bouton de fonctionnalité **mémoire active** et la configuration du sous-agent, ils se trouvent sous `plugins.entries.active-memory` au lieu de `memorySearch`.
|
||||
|
||||
La mémoire active utilise un modèle à deux conditions :
|
||||
|
||||
1. le plugin doit être activé et cibler l’ID de l’agent actuel
|
||||
2. la requête doit être une session de chat interactive persistante éligible
|
||||
|
||||
Voir [Mémoire active](/fr/concepts/active-memory) pour le modèle d’activation, la configuration gérée par le plugin, la persistance des transcriptions et le modèle de déploiement sûr.
|
||||
|
||||
---
|
||||
|
||||
## Sélection du fournisseur
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | détection automatique | ID de l’adaptateur d’embeddings : `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | défaut du fournisseur | Nom du modèle d’embeddings |
|
||||
| `fallback` | `string` | `"none"` | ID de l’adaptateur de secours lorsque le primaire échoue |
|
||||
| `enabled` | `boolean` | `true` | Activer ou désactiver la recherche mémoire |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | détecté automatiquement | ID de l’adaptateur d’embeddings : `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | valeur par défaut du fournisseur | Nom du modèle d’embeddings |
|
||||
| `fallback` | `string` | `"none"` | ID de l’adaptateur de secours en cas d’échec du principal |
|
||||
| `enabled` | `boolean` | `true` | Activer ou désactiver la recherche en mémoire |
|
||||
|
||||
### Ordre de détection automatique
|
||||
|
||||
@ -48,33 +58,33 @@ Lorsque `provider` n’est pas défini, OpenClaw sélectionne le premier disponi
|
||||
5. `mistral` -- si une clé Mistral peut être résolue.
|
||||
6. `bedrock` -- si la chaîne d’identifiants AWS SDK est résolue (rôle d’instance, clés d’accès, profil, SSO, identité web ou configuration partagée).
|
||||
|
||||
`ollama` est pris en charge, mais n’est pas détecté automatiquement (définissez-le explicitement).
|
||||
`ollama` est pris en charge mais n’est pas détecté automatiquement (définissez-le explicitement).
|
||||
|
||||
### Résolution de clé API
|
||||
### Résolution des clés API
|
||||
|
||||
Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut de l’AWS SDK (rôles d’instance, SSO, clés d’accès).
|
||||
Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut du SDK AWS (rôles d’instance, SSO, clés d’accès).
|
||||
|
||||
| Provider | Env var | Config key |
|
||||
| -------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | chaîne d’identifiants AWS | Aucune clé API nécessaire |
|
||||
| Ollama | `OLLAMA_API_KEY` (espace réservé) | -- |
|
||||
| Fournisseur | Variable d’environnement | Clé de configuration |
|
||||
| ----------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | chaîne d’identifiants AWS | Aucune clé API nécessaire |
|
||||
| Ollama | `OLLAMA_API_KEY` (espace réservé) | -- |
|
||||
|
||||
Codex OAuth couvre uniquement le chat/les complétions et ne satisfait pas les requêtes d’embeddings.
|
||||
L’authentification OAuth de Codex couvre uniquement le chat/les complétions et ne satisfait pas les requêtes d’embeddings.
|
||||
|
||||
---
|
||||
|
||||
## Configuration des endpoints distants
|
||||
## Configuration des points de terminaison distants
|
||||
|
||||
Pour des endpoints compatibles OpenAI personnalisés ou pour remplacer les valeurs par défaut du fournisseur :
|
||||
Pour des points de terminaison personnalisés compatibles OpenAI ou pour remplacer les valeurs par défaut du fournisseur :
|
||||
|
||||
| Key | Type | Description |
|
||||
| ---------------- | -------- | -------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | URL de base API personnalisée |
|
||||
| `remote.apiKey` | `string` | Remplacer la clé API |
|
||||
| Clé | Type | Description |
|
||||
| ---------------- | -------- | ------------------------------------------------ |
|
||||
| `remote.baseUrl` | `string` | URL de base de l’API personnalisée |
|
||||
| `remote.apiKey` | `string` | Remplacer la clé API |
|
||||
| `remote.headers` | `object` | En-têtes HTTP supplémentaires (fusionnés avec les valeurs par défaut du fournisseur) |
|
||||
|
||||
```json5
|
||||
@ -98,20 +108,20 @@ Pour des endpoints compatibles OpenAI personnalisés ou pour remplacer les valeu
|
||||
|
||||
## Configuration spécifique à Gemini
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Prend aussi en charge `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Pour Embedding 2 : 768, 1536 ou 3072 |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ---------------------- | -------- | --------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Prend également en charge `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Pour Embedding 2 : 768, 1536 ou 3072 |
|
||||
|
||||
<Warning>
|
||||
Modifier le modèle ou `outputDimensionality` déclenche une réindexation complète automatique.
|
||||
La modification du modèle ou de `outputDimensionality` déclenche automatiquement une réindexation complète.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Configuration des embeddings Bedrock
|
||||
|
||||
Bedrock utilise la chaîne d’identifiants par défaut de l’AWS SDK -- aucune clé API nécessaire.
|
||||
Bedrock utilise la chaîne d’identifiants par défaut du SDK AWS -- aucune clé API n’est nécessaire.
|
||||
Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock, définissez simplement le fournisseur et le modèle :
|
||||
|
||||
```json5
|
||||
@ -127,41 +137,41 @@ Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Tout ID de modèle d’embeddings Bedrock |
|
||||
| `outputDimensionality` | `number` | valeur par défaut du modèle | Pour Titan V2 : 256, 512 ou 1024 |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ---------------------- | -------- | ----------------------------- | ------------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Tout ID de modèle d’embeddings Bedrock |
|
||||
| `outputDimensionality` | `number` | valeur par défaut du modèle | Pour Titan V2 : 256, 512 ou 1024 |
|
||||
|
||||
### Modèles pris en charge
|
||||
|
||||
Les modèles suivants sont pris en charge (avec détection de famille et valeurs dimensionnelles par défaut) :
|
||||
Les modèles suivants sont pris en charge (avec détection de famille et dimensions par défaut) :
|
||||
|
||||
| Model ID | Provider | Default Dims | Configurable Dims |
|
||||
| ------------------------------------------ | ---------- | ------------ | -------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
| ID du modèle | Fournisseur | Dimensions par défaut | Dimensions configurables |
|
||||
| ------------------------------------------- | ----------- | --------------------- | ------------------------ |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
Les variantes suffixées par débit (par exemple `amazon.titan-embed-text-v1:2:8k`) héritent de la configuration du modèle de base.
|
||||
Les variantes avec suffixe de débit (par exemple, `amazon.titan-embed-text-v1:2:8k`) héritent de la configuration du modèle de base.
|
||||
|
||||
### Authentification
|
||||
|
||||
L’authentification Bedrock utilise l’ordre de résolution standard des identifiants de l’AWS SDK :
|
||||
L’authentification Bedrock utilise l’ordre standard de résolution des identifiants du SDK AWS :
|
||||
|
||||
1. Variables d’environnement (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. Cache de jetons SSO
|
||||
2. Cache des jetons SSO
|
||||
3. Identifiants de jeton d’identité web
|
||||
4. Fichiers partagés d’identifiants et de configuration
|
||||
5. Identifiants de métadonnées ECS ou EC2
|
||||
|
||||
La région est résolue à partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, du `baseUrl` du fournisseur `amazon-bedrock`, ou prend par défaut `us-east-1`.
|
||||
La région est résolue à partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, du `baseUrl` du fournisseur `amazon-bedrock`, ou utilise par défaut `us-east-1`.
|
||||
|
||||
### Autorisations IAM
|
||||
|
||||
@ -185,42 +195,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## Configuration des embeddings locaux
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------- |
|
||||
| `local.modelPath` | `string` | téléchargement automatique | Chemin vers le fichier modèle GGUF |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------------- |
|
||||
| `local.modelPath` | `string` | téléchargé automatiquement | Chemin vers le fichier de modèle GGUF |
|
||||
| `local.modelCacheDir` | `string` | valeur par défaut de node-llama-cpp | Répertoire de cache pour les modèles téléchargés |
|
||||
|
||||
Modèle par défaut : `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 Go, téléchargé automatiquement).
|
||||
Modèle par défaut : `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, téléchargé automatiquement).
|
||||
Nécessite une build native : `pnpm approve-builds` puis `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
## Configuration de la recherche hybride
|
||||
|
||||
Tous sous `memorySearch.query.hybrid` :
|
||||
Le tout sous `memorySearch.query.hybrid` :
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Activer la recherche hybride BM25 + vectorielle |
|
||||
| `vectorWeight` | `number` | `0.7` | Poids des scores vectoriels (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Poids des scores BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Multiplicateur de taille du pool de candidats |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| --------------------- | --------- | ---------- | ---------------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Activer la recherche hybride BM25 + vectorielle |
|
||||
| `vectorWeight` | `number` | `0.7` | Poids des scores vectoriels (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Poids des scores BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Multiplicateur de taille du pool de candidats |
|
||||
|
||||
### MMR (diversité)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------- | --------- | ------- | ------------------------------------ |
|
||||
| `mmr.enabled` | `boolean` | `false` | Activer le reclassement MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = diversité maximale, 1 = pertinence maximale |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------- | --------- | ---------- | ------------------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | Activer le reranking MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = diversité maximale, 1 = pertinence maximale |
|
||||
|
||||
### Décroissance temporelle (récence)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | ------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Activer le boost de récence |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Le score est divisé par deux tous les N jours |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ---------------------------- | --------- | ---------- | ----------------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Activer le boost de récence |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Le score est divisé par deux tous les N jours |
|
||||
|
||||
Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subissent jamais de décroissance.
|
||||
Les fichiers persistants (`MEMORY.md`, fichiers non datés dans `memory/`) ne subissent jamais de décroissance.
|
||||
|
||||
### Exemple complet
|
||||
|
||||
@ -245,10 +255,10 @@ Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subi
|
||||
|
||||
---
|
||||
|
||||
## Chemins mémoire supplémentaires
|
||||
## Chemins de mémoire supplémentaires
|
||||
|
||||
| Key | Type | Description |
|
||||
| ------------ | ---------- | ---------------------------------------- |
|
||||
| Clé | Type | Description |
|
||||
| ------------ | ---------- | -------------------------------------------- |
|
||||
| `extraPaths` | `string[]` | Répertoires ou fichiers supplémentaires à indexer |
|
||||
|
||||
```json5
|
||||
@ -266,13 +276,9 @@ Les fichiers pérennes (`MEMORY.md`, fichiers non datés dans `memory/`) ne subi
|
||||
Les chemins peuvent être absolus ou relatifs à l’espace de travail. Les répertoires sont analysés récursivement à la recherche de fichiers `.md`. La gestion des liens symboliques dépend du backend actif :
|
||||
le moteur intégré ignore les liens symboliques, tandis que QMD suit le comportement du scanner QMD sous-jacent.
|
||||
|
||||
Pour la recherche de transcriptions inter-agents à portée d’agent, utilisez
|
||||
`agents.list[].memorySearch.qmd.extraCollections` au lieu de `memory.qmd.paths`.
|
||||
Ces collections supplémentaires suivent la même forme `{ path, name, pattern? }`, mais
|
||||
elles sont fusionnées par agent et peuvent conserver des noms partagés explicites lorsque le chemin
|
||||
pointe en dehors de l’espace de travail actuel.
|
||||
Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et
|
||||
`memorySearch.qmd.extraCollections`, QMD conserve la première entrée et ignore le doublon.
|
||||
Pour la recherche de transcriptions inter-agents à portée d’agent, utilisez `agents.list[].memorySearch.qmd.extraCollections` au lieu de `memory.qmd.paths`.
|
||||
Ces collections supplémentaires suivent la même forme `{ path, name, pattern? }`, mais elles sont fusionnées par agent et peuvent conserver des noms partagés explicites lorsque le chemin pointe en dehors de l’espace de travail actuel.
|
||||
Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et dans `memorySearch.qmd.extraCollections`, QMD conserve la première entrée et ignore le doublon.
|
||||
|
||||
---
|
||||
|
||||
@ -280,13 +286,13 @@ Si le même chemin résolu apparaît à la fois dans `memory.qmd.paths` et
|
||||
|
||||
Indexez les images et l’audio en plus du Markdown à l’aide de Gemini Embedding 2 :
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Activer l’indexation multimodale |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Taille maximale de fichier pour l’indexation |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------------------- | ---------- | ---------- | ------------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Activer l’indexation multimodale |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Taille maximale des fichiers pour l’indexation |
|
||||
|
||||
S’applique uniquement aux fichiers dans `extraPaths`. Les racines mémoire par défaut restent limitées au Markdown.
|
||||
S’applique uniquement aux fichiers dans `extraPaths`. Les racines de mémoire par défaut restent limitées au Markdown.
|
||||
Nécessite `gemini-embedding-2-preview`. `fallback` doit être `"none"`.
|
||||
|
||||
Formats pris en charge : `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
@ -294,119 +300,109 @@ Formats pris en charge : `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.he
|
||||
|
||||
---
|
||||
|
||||
## Cache d’embeddings
|
||||
## Cache des embeddings
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------ | --------- | ------- | -------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Mettre en cache les embeddings de segments dans SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Nombre maximal d’embeddings en cache |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------------ | --------- | ---------- | ---------------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Mettre en cache les embeddings de fragments dans SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Nombre maximal d’embeddings mis en cache |
|
||||
|
||||
Empêche de réintégrer les textes inchangés lors de la réindexation ou des mises à jour de transcriptions.
|
||||
Empêche de recalculer les embeddings d’un texte inchangé lors d’une réindexation ou de mises à jour de transcriptions.
|
||||
|
||||
---
|
||||
|
||||
## Indexation par lots
|
||||
## Indexation par lot
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | --------- | ------- | -------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Activer l’API d’embeddings par lots |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Tâches par lots parallèles |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Attendre la fin du lot |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalle d’interrogation |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Délai d’expiration du lot |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ----------------------------- | --------- | ---------- | -------------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Activer l’API d’embeddings par lot |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Tâches par lot parallèles |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Attendre la fin du lot |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalle d’interrogation |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Délai d’expiration du lot |
|
||||
|
||||
Disponible pour `openai`, `gemini` et `voyage`. Les lots OpenAI sont généralement
|
||||
les plus rapides et les moins chers pour les remplissages initiaux volumineux.
|
||||
Disponible pour `openai`, `gemini` et `voyage`. Le traitement par lot OpenAI est généralement le plus rapide et le moins cher pour les gros remplissages rétroactifs.
|
||||
|
||||
---
|
||||
|
||||
## Recherche mémoire de session (expérimental)
|
||||
## Recherche en mémoire de session (expérimental)
|
||||
|
||||
Indexez les transcriptions de session et exposez-les via `memory_search` :
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | ---------- | ------------ | --------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Activer l’indexation des sessions |
|
||||
| `sources` | `string[]` | `["memory"]` | Ajoutez `"sessions"` pour inclure les transcriptions |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Seuil en octets pour la réindexation |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Seuil en messages pour la réindexation |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ----------------------------- | ---------- | ------------ | -------------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Activer l’indexation des sessions |
|
||||
| `sources` | `string[]` | `["memory"]` | Ajouter `"sessions"` pour inclure les transcriptions |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Seuil en octets pour la réindexation |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Seuil en messages pour la réindexation |
|
||||
|
||||
L’indexation des sessions est opt-in et s’exécute de façon asynchrone. Les résultats peuvent être légèrement
|
||||
obsolètes. Les journaux de session se trouvent sur le disque, traitez donc l’accès au système de fichiers comme frontière de confiance.
|
||||
L’indexation des sessions est optionnelle et s’exécute de façon asynchrone. Les résultats peuvent être légèrement obsolètes. Les journaux de session sont stockés sur le disque, considérez donc l’accès au système de fichiers comme la frontière de confiance.
|
||||
|
||||
---
|
||||
|
||||
## Accélération vectorielle SQLite (sqlite-vec)
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Utiliser sqlite-vec pour les requêtes vectorielles |
|
||||
| `store.vector.extensionPath` | `string` | intégré | Remplacer le chemin sqlite-vec |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ---------------------------- | --------- | ---------- | ------------------------------------------ |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Utiliser sqlite-vec pour les requêtes vectorielles |
|
||||
| `store.vector.extensionPath` | `string` | intégré | Remplacer le chemin de sqlite-vec |
|
||||
|
||||
Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la
|
||||
similarité cosinus en processus.
|
||||
Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la similarité cosinus en processus.
|
||||
|
||||
---
|
||||
|
||||
## Stockage de l’index
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------------------ |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Emplacement de l’index (prend en charge le jeton `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` ou `trigram`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokeniseur FTS5 (`unicode61` ou `trigram`) |
|
||||
|
||||
---
|
||||
|
||||
## Configuration du backend QMD
|
||||
|
||||
Définissez `memory.backend = "qmd"` pour l’activer. Tous les paramètres QMD se trouvent sous
|
||||
`memory.qmd` :
|
||||
Définissez `memory.backend = "qmd"` pour l’activer. Tous les paramètres QMD se trouvent sous `memory.qmd` :
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Chemin de l’exécutable QMD |
|
||||
| `searchMode` | `string` | `search` | Commande de recherche : `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Indexer automatiquement `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Chemins supplémentaires : `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indexer les transcriptions de session |
|
||||
| `sessions.retentionDays` | `number` | -- | Rétention des transcriptions |
|
||||
| `sessions.exportDir` | `string` | -- | Répertoire d’exportation |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------------------ | --------- | ---------- | ------------------------------------------------ |
|
||||
| `command` | `string` | `qmd` | Chemin de l’exécutable QMD |
|
||||
| `searchMode` | `string` | `search` | Commande de recherche : `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Indexer automatiquement `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Chemins supplémentaires : `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indexer les transcriptions de session |
|
||||
| `sessions.retentionDays` | `number` | -- | Rétention des transcriptions |
|
||||
| `sessions.exportDir` | `string` | -- | Répertoire d’exportation |
|
||||
|
||||
OpenClaw privilégie la collection QMD actuelle et les formes de requête MCP, mais conserve
|
||||
la compatibilité avec les anciennes versions de QMD en revenant si nécessaire aux indicateurs de collection hérités `--mask`
|
||||
et aux anciens noms d’outils MCP.
|
||||
OpenClaw privilégie les formes actuelles de collection QMD et de requête MCP, mais maintient les anciennes versions de QMD fonctionnelles en revenant si nécessaire aux indicateurs de collection hérités `--mask` et aux anciens noms d’outils MCP.
|
||||
|
||||
Les remplacements de modèle QMD restent du côté QMD, pas dans la configuration OpenClaw. Si vous devez
|
||||
remplacer globalement les modèles de QMD, définissez des variables d’environnement telles que
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` et `QMD_GENERATE_MODEL` dans l’environnement d’exécution
|
||||
de la passerelle.
|
||||
Les remplacements de modèle QMD restent du côté de QMD, pas dans la configuration d’OpenClaw. Si vous devez remplacer globalement les modèles de QMD, définissez des variables d’environnement telles que `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` et `QMD_GENERATE_MODEL` dans l’environnement d’exécution de la passerelle.
|
||||
|
||||
### Planning de mise à jour
|
||||
### Planification des mises à jour
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | --------- | ------- | ------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Intervalle de rafraîchissement |
|
||||
| `update.debounceMs` | `number` | `15000` | Anti-rebond des changements de fichiers |
|
||||
| `update.onBoot` | `boolean` | `true` | Rafraîchir au démarrage |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Bloquer le démarrage jusqu’à la fin du rafraîchissement |
|
||||
| `update.embedInterval` | `string` | -- | Cadence d’embedding distincte |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Délai d’expiration des commandes QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Délai d’expiration des opérations de mise à jour QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Délai d’expiration des opérations d’embedding QMD |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------------------- | --------- | ---------- | -------------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Intervalle d’actualisation |
|
||||
| `update.debounceMs` | `number` | `15000` | Antirebond des changements de fichiers |
|
||||
| `update.onBoot` | `boolean` | `true` | Actualiser au démarrage |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Bloquer le démarrage jusqu’à la fin de l’actualisation |
|
||||
| `update.embedInterval` | `string` | -- | Cadence d’embedding distincte |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Délai d’expiration pour les commandes QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Délai d’expiration pour les opérations de mise à jour QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Délai d’expiration pour les opérations d’embedding QMD |
|
||||
|
||||
### Limites
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | -------- | ------- | -------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | Nombre maximal de résultats de recherche |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Limiter la longueur des extraits |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Limiter le total des caractères injectés |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Délai d’expiration de la recherche |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ------------------------- | -------- | ---------- | ------------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | Nombre maximal de résultats de recherche |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Limiter la longueur des extraits |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Limiter le total de caractères injectés |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Délai d’expiration de la recherche |
|
||||
|
||||
### Portée
|
||||
|
||||
Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que
|
||||
[`session.sendPolicy`](/fr/gateway/configuration-reference#session) :
|
||||
Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que [`session.sendPolicy`](/fr/gateway/configuration-reference#session) :
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -421,20 +417,20 @@ Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Mê
|
||||
}
|
||||
```
|
||||
|
||||
Par défaut, DM uniquement. `match.keyPrefix` correspond à la clé de session normalisée ;
|
||||
La valeur par défaut est DM-only. `match.keyPrefix` correspond à la clé de session normalisée ;
|
||||
`match.rawKeyPrefix` correspond à la clé brute, y compris `agent:<id>:`.
|
||||
|
||||
### Citations
|
||||
|
||||
`memory.citations` s’applique à tous les backends :
|
||||
|
||||
| Value | Behavior |
|
||||
| Valeur | Comportement |
|
||||
| ---------------- | --------------------------------------------------- |
|
||||
| `auto` (par défaut) | Inclure un pied de page `Source: <path#line>` dans les extraits |
|
||||
| `on` | Toujours inclure le pied de page |
|
||||
| `off` | Omettre le pied de page (le chemin est tout de même transmis à l’agent en interne) |
|
||||
| `auto` (par défaut) | Inclure un pied de page `Source: <path#line>` dans les extraits |
|
||||
| `on` | Toujours inclure le pied de page |
|
||||
| `off` | Omettre le pied de page (le chemin est toujours transmis à l’agent en interne) |
|
||||
|
||||
### Exemple QMD complet
|
||||
### Exemple complet QMD
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -459,20 +455,18 @@ Par défaut, DM uniquement. `match.keyPrefix` correspond à la clé de session n
|
||||
|
||||
## Dreaming (expérimental)
|
||||
|
||||
Dreaming se configure sous `plugins.entries.memory-core.config.dreaming`,
|
||||
et non sous `agents.defaults.memorySearch`.
|
||||
Dreaming est configuré sous `plugins.entries.memory-core.config.dreaming`, et non sous `agents.defaults.memorySearch`.
|
||||
|
||||
Dreaming s’exécute comme un balayage planifié unique et utilise en interne des phases light/deep/REM comme
|
||||
détail d’implémentation.
|
||||
Dreaming s’exécute comme un balayage planifié unique et utilise des phases internes léger/profond/REM comme détail d’implémentation.
|
||||
|
||||
Pour le comportement conceptuel et les commandes slash, voir [Dreaming](/fr/concepts/dreaming).
|
||||
|
||||
### Paramètres utilisateur
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
| ----------- | --------- | ----------- | ------------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Activer ou désactiver entièrement Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadence cron facultative pour le balayage complet de Dreaming |
|
||||
| Clé | Type | Par défaut | Description |
|
||||
| ----------- | --------- | ----------- | ---------------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Activer ou désactiver complètement dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadence cron optionnelle pour le balayage complet de dreaming |
|
||||
|
||||
### Exemple
|
||||
|
||||
@ -496,5 +490,5 @@ Pour le comportement conceptuel et les commandes slash, voir [Dreaming](/fr/conc
|
||||
Remarques :
|
||||
|
||||
- Dreaming écrit l’état machine dans `memory/.dreams/`.
|
||||
- Dreaming écrit une sortie narrative lisible par l’humain dans `DREAMS.md` (ou le fichier existant `dreams.md`).
|
||||
- La stratégie des phases light/deep/REM et les seuils sont des comportements internes, pas une configuration destinée à l’utilisateur.
|
||||
- Dreaming écrit une sortie narrative lisible par un humain dans `DREAMS.md` (ou `dreams.md` existant).
|
||||
- La stratégie de phase léger/profond/REM et les seuils sont des comportements internes, pas une configuration destinée à l’utilisateur.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,70 +1,75 @@
|
||||
---
|
||||
read_when:
|
||||
- Configuration des approbations exec ou des listes d’autorisation
|
||||
- Implémentation de l’UX d’approbation exec dans l’app macOS
|
||||
- Examen des invites d’échappement du sandbox et de leurs implications
|
||||
summary: Approbations exec, listes d’autorisation et invites d’échappement du sandbox
|
||||
title: Approbations exec
|
||||
- Configuration des approbations d’exécution ou des listes d’autorisation
|
||||
- Implémentation de l’expérience utilisateur des approbations d’exécution dans l’app macOS
|
||||
- Examen des invites d’échappement au bac à sable et de leurs implications
|
||||
summary: Approbations d’exécution, listes d’autorisation et invites d’échappement au bac à sable
|
||||
title: Approbations d’exécution
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:19:49Z"
|
||||
generated_at: "2026-04-10T06:56:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
|
||||
source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Approbations exec
|
||||
# Approbations d’exécution
|
||||
|
||||
Les approbations exec sont la **barrière de sécurité de l’app compagnon / de l’hôte de nœud** permettant à un agent sandboxé d’exécuter
|
||||
des commandes sur un hôte réel (`gateway` ou `node`). Considérez cela comme un verrouillage de sécurité :
|
||||
les commandes sont autorisées uniquement lorsque la politique + la liste d’autorisation + l’approbation utilisateur (facultative) sont toutes d’accord.
|
||||
Les approbations exec s’ajoutent à la politique d’outils et au contrôle elevated (sauf si elevated est défini sur `full`, ce qui ignore les approbations).
|
||||
La politique effective est la **plus stricte** entre `tools.exec.*` et les valeurs par défaut des approbations ; si un champ d’approbation est omis, la valeur `tools.exec` est utilisée.
|
||||
L’exécution hôte utilise également l’état local des approbations sur cette machine. Un
|
||||
`ask: "always"` local à l’hôte dans `~/.openclaw/exec-approvals.json` continue d’afficher des invites même si
|
||||
les valeurs par défaut de la session ou de la configuration demandent `ask: "on-miss"`.
|
||||
Utilisez `openclaw approvals get`, `openclaw approvals get --gateway` ou
|
||||
Les approbations d’exécution sont le **garde-fou de l’app compagnon / de l’hôte de nœud** pour permettre à un agent sandboxé d’exécuter
|
||||
des commandes sur un hôte réel (`gateway` ou `node`). Considérez cela comme un interverrouillage de sécurité :
|
||||
les commandes ne sont autorisées que lorsque la politique + la liste d’autorisation + l’approbation utilisateur (facultative) sont toutes d’accord.
|
||||
Les approbations d’exécution s’ajoutent à la politique de l’outil et au contrôle elevated (sauf si elevated est défini sur `full`, ce qui ignore les approbations).
|
||||
La politique effective est la **plus stricte** entre `tools.exec.*` et les valeurs par défaut des approbations ; si un champ d’approbation est omis, la valeur de `tools.exec` est utilisée.
|
||||
L’exécution sur hôte utilise aussi l’état local des approbations sur cette machine. Un
|
||||
`ask: "always"` local dans `~/.openclaw/exec-approvals.json` continue à demander une approbation même si
|
||||
la session ou les valeurs par défaut de la configuration demandent `ask: "on-miss"`.
|
||||
Utilisez `openclaw approvals get`, `openclaw approvals get --gateway`, ou
|
||||
`openclaw approvals get --node <id|name|ip>` pour inspecter la politique demandée,
|
||||
les sources de politique de l’hôte et le résultat effectif.
|
||||
Pour la machine locale, `openclaw exec-policy show` expose la même vue fusionnée et
|
||||
`openclaw exec-policy set|preset` peut synchroniser en une seule étape la politique locale demandée avec le
|
||||
fichier local des approbations de l’hôte. Lorsqu’une portée locale demande `host=node`,
|
||||
`openclaw exec-policy show` signale cette portée comme gérée par le nœud au moment de l’exécution au lieu de
|
||||
faire semblant que le fichier local des approbations est la source de vérité effective.
|
||||
|
||||
Si l’interface de l’app compagnon n’est **pas disponible**, toute requête nécessitant une invite est
|
||||
résolue par le **repli ask** (par défaut : deny).
|
||||
Si l’interface de l’app compagnon **n’est pas disponible**, toute demande nécessitant une invite
|
||||
est résolue par la **solution de repli ask** (par défaut : deny).
|
||||
|
||||
Les clients natifs d’approbation dans les discussions peuvent également exposer des affordances spécifiques au canal sur le
|
||||
message d’approbation en attente. Par exemple, Matrix peut initialiser des raccourcis par réaction sur l’invite
|
||||
d’approbation (`✅` autoriser une fois, `❌` refuser et `♾️` toujours autoriser si disponible)
|
||||
Les clients d’approbation de chat natifs peuvent aussi exposer des affordances spécifiques au canal sur le
|
||||
message d’approbation en attente. Par exemple, Matrix peut préremplir des raccourcis de réaction sur
|
||||
l’invite d’approbation (`✅` autoriser une fois, `❌` refuser, et `♾️` toujours autoriser lorsque disponible)
|
||||
tout en laissant les commandes `/approve ...` dans le message comme solution de repli.
|
||||
|
||||
## Où cela s’applique
|
||||
|
||||
Les approbations exec sont appliquées localement sur l’hôte d’exécution :
|
||||
Les approbations d’exécution sont appliquées localement sur l’hôte d’exécution :
|
||||
|
||||
- **hôte gateway** → processus `openclaw` sur la machine gateway
|
||||
- **hôte node** → exécuteur de nœud (app compagnon macOS ou hôte de nœud sans interface)
|
||||
- **hôte node** → exécuteur de nœud (app compagnon macOS ou hôte de nœud headless)
|
||||
|
||||
Remarque sur le modèle de confiance :
|
||||
Note sur le modèle de confiance :
|
||||
|
||||
- Les appelants authentifiés auprès de la gateway sont des opérateurs de confiance pour cette Gateway.
|
||||
- Les nœuds appairés étendent cette capacité d’opérateur de confiance à l’hôte de nœud.
|
||||
- Les approbations exec réduisent le risque d’exécution accidentelle, mais ne constituent pas une limite d’authentification par utilisateur.
|
||||
- Les exécutions approuvées sur l’hôte de nœud lient le contexte d’exécution canonique : `cwd` canonique, `argv` exact, liaison de l’environnement
|
||||
lorsqu’il est présent, et chemin exécutable épinglé si applicable.
|
||||
- Pour les scripts shell et les invocations directes de fichiers d’interpréteur/runtime, OpenClaw essaie également de lier
|
||||
un seul opérande de fichier local concret. Si ce fichier lié change après l’approbation mais avant l’exécution,
|
||||
l’exécution est refusée au lieu d’exécuter un contenu qui a dérivé.
|
||||
- Cette liaison de fichier est volontairement réalisée au mieux, et ne constitue pas un modèle sémantique complet de chaque
|
||||
chemin de chargement d’interpréteur/runtime. Si le mode d’approbation ne peut pas identifier exactement un fichier local concret
|
||||
à lier, il refuse de créer une exécution appuyée par approbation au lieu de prétendre offrir une couverture complète.
|
||||
- Les appelants authentifiés par Gateway sont des opérateurs de confiance pour cette Gateway.
|
||||
- Les nœuds appairés étendent cette capacité d’opérateur de confiance à l’hôte du nœud.
|
||||
- Les approbations d’exécution réduisent le risque d’exécution accidentelle, mais ne constituent pas une frontière d’authentification par utilisateur.
|
||||
- Les exécutions approuvées sur hôte de nœud lient le contexte d’exécution canonique : `cwd` canonique, `argv` exact, liaison d’environnement
|
||||
lorsqu’elle est présente, et chemin de l’exécutable épinglé lorsque applicable.
|
||||
- Pour les scripts shell et les invocations directes de fichiers d’interpréteur/runtime, OpenClaw essaie aussi de lier
|
||||
un opérande de fichier local concret. Si ce fichier lié change après l’approbation mais avant l’exécution,
|
||||
l’exécution est refusée au lieu d’exécuter un contenu dérivé.
|
||||
- Cette liaison de fichier est volontairement fournie au mieux, et non comme un modèle sémantique complet de chaque
|
||||
chemin de chargement d’interpréteur/runtime. Si le mode d’approbation ne peut pas identifier exactement un fichier local concret à lier,
|
||||
il refuse de créer une exécution adossée à une approbation plutôt que de prétendre offrir une couverture complète.
|
||||
|
||||
Découpage macOS :
|
||||
Scission macOS :
|
||||
|
||||
- Le **service hôte de nœud** transmet `system.run` à l’**app macOS** via IPC local.
|
||||
- L’**app macOS** applique les approbations + exécute la commande dans le contexte de l’interface.
|
||||
- **service d’hôte de nœud** transfère `system.run` vers l’**app macOS** via IPC locale.
|
||||
- **app macOS** applique les approbations + exécute la commande dans le contexte de l’interface.
|
||||
|
||||
## Paramètres et stockage
|
||||
|
||||
Les approbations vivent dans un fichier JSON local sur l’hôte d’exécution :
|
||||
Les approbations sont stockées dans un fichier JSON local sur l’hôte d’exécution :
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
|
||||
@ -103,14 +108,14 @@ Exemple de schéma :
|
||||
}
|
||||
```
|
||||
|
||||
## Mode « YOLO » sans approbation
|
||||
## Mode "YOLO" sans approbation
|
||||
|
||||
Si vous voulez que l’exécution hôte se fasse sans invites d’approbation, vous devez ouvrir **les deux** couches de politique :
|
||||
Si vous voulez que l’exécution sur hôte s’exécute sans invites d’approbation, vous devez ouvrir **les deux** couches de politique :
|
||||
|
||||
- la politique exec demandée dans la configuration OpenClaw (`tools.exec.*`)
|
||||
- la politique locale des approbations sur l’hôte dans `~/.openclaw/exec-approvals.json`
|
||||
- la politique d’exécution demandée dans la configuration OpenClaw (`tools.exec.*`)
|
||||
- la politique locale d’approbation sur l’hôte dans `~/.openclaw/exec-approvals.json`
|
||||
|
||||
C’est désormais le comportement hôte par défaut sauf si vous le durcissez explicitement :
|
||||
C’est désormais le comportement par défaut sur l’hôte, sauf si vous le resserrez explicitement :
|
||||
|
||||
- `tools.exec.security`: `full` sur `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
@ -118,15 +123,15 @@ C’est désormais le comportement hôte par défaut sauf si vous le durcissez e
|
||||
|
||||
Distinction importante :
|
||||
|
||||
- `tools.exec.host=auto` choisit l’emplacement d’exécution d’exec : sandbox quand disponible, sinon gateway.
|
||||
- YOLO choisit la façon dont l’exécution hôte est approuvée : `security=full` plus `ask=off`.
|
||||
- En mode YOLO, OpenClaw n’ajoute pas de filtre distinct d’approbation heuristique sur l’obfuscation de commande en plus de la politique d’exécution hôte configurée.
|
||||
- `auto` ne transforme pas le routage vers gateway en remplacement gratuit depuis une session sandboxée. Une requête par appel `host=node` est autorisée depuis `auto`, et `host=gateway` n’est autorisé depuis `auto` que lorsqu’aucun runtime sandbox n’est actif. Si vous voulez une valeur par défaut stable non automatique, définissez `tools.exec.host` ou utilisez explicitement `/exec host=...`.
|
||||
- `tools.exec.host=auto` choisit où l’exécution a lieu : dans le bac à sable lorsqu’il est disponible, sinon sur la gateway.
|
||||
- YOLO choisit comment l’exécution sur hôte est approuvée : `security=full` plus `ask=off`.
|
||||
- En mode YOLO, OpenClaw n’ajoute pas de contrôle d’approbation heuristique séparé pour l’obfuscation de commande au-dessus de la politique d’exécution sur hôte configurée.
|
||||
- `auto` ne transforme pas le routage gateway en dérogation libre depuis une session sandboxée. Une demande par appel `host=node` est autorisée depuis `auto`, et `host=gateway` n’est autorisé depuis `auto` que lorsqu’aucun runtime sandbox n’est actif. Si vous voulez une valeur par défaut stable non `auto`, définissez `tools.exec.host` ou utilisez `/exec host=...` explicitement.
|
||||
|
||||
Si vous voulez une configuration plus prudente, resserrez l’une ou l’autre couche à `allowlist` / `on-miss`
|
||||
Si vous voulez une configuration plus prudente, resserrez l’une ou l’autre couche vers `allowlist` / `on-miss`
|
||||
ou `deny`.
|
||||
|
||||
Configuration persistante « ne jamais demander » sur l’hôte gateway :
|
||||
Configuration persistante "ne jamais demander" pour l’hôte gateway :
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
@ -135,7 +140,7 @@ openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Puis définissez le fichier d’approbations de l’hôte pour qu’il corresponde :
|
||||
Ensuite, définissez le fichier d’approbations de l’hôte de façon cohérente :
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
@ -150,7 +155,22 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Pour un hôte node, appliquez plutôt le même fichier d’approbations sur ce nœud :
|
||||
Raccourci local pour la même politique d’hôte gateway sur la machine actuelle :
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
```
|
||||
|
||||
Ce raccourci local met à jour les deux :
|
||||
|
||||
- `tools.exec.host/security/ask` local
|
||||
- valeurs par défaut locales de `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Il est volontairement limité au local. Si vous devez modifier à distance les approbations de l’hôte gateway ou de l’hôte node,
|
||||
continuez à utiliser `openclaw approvals set --gateway` ou
|
||||
`openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
Pour un hôte de nœud, appliquez plutôt le même fichier d’approbations sur ce nœud :
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -165,39 +185,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Limitation importante limitée au local :
|
||||
|
||||
- `openclaw exec-policy` ne synchronise pas les approbations du nœud
|
||||
- `openclaw exec-policy set --host node` est refusé
|
||||
- les approbations d’exécution du nœud sont récupérées depuis le nœud au moment de l’exécution, donc les mises à jour ciblant le nœud doivent utiliser `openclaw approvals --node ...`
|
||||
|
||||
Raccourci limité à la session :
|
||||
|
||||
- `/exec security=full ask=off` modifie uniquement la session en cours.
|
||||
- `/elevated full` est un raccourci de dernier recours qui ignore aussi les approbations exec pour cette session.
|
||||
- `/elevated full` est un raccourci brise-glace qui ignore aussi les approbations d’exécution pour cette session.
|
||||
|
||||
Si le fichier d’approbations de l’hôte reste plus strict que la configuration, la politique hôte la plus stricte continue de s’appliquer.
|
||||
Si le fichier d’approbations de l’hôte reste plus strict que la configuration, la politique d’hôte la plus stricte continue de prévaloir.
|
||||
|
||||
## Paramètres de politique
|
||||
|
||||
### Sécurité (`exec.security`)
|
||||
|
||||
- **deny** : bloque toutes les requêtes d’exécution hôte.
|
||||
- **allowlist** : autorise uniquement les commandes présentes dans la liste d’autorisation.
|
||||
- **deny** : bloque toutes les demandes d’exécution sur hôte.
|
||||
- **allowlist** : autorise uniquement les commandes figurant dans la liste d’autorisation.
|
||||
- **full** : autorise tout (équivalent à elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off** : ne jamais demander.
|
||||
- **on-miss** : demander uniquement lorsqu’aucune entrée de la liste d’autorisation ne correspond.
|
||||
- **on-miss** : demander uniquement quand la liste d’autorisation ne correspond pas.
|
||||
- **always** : demander pour chaque commande.
|
||||
- La confiance durable `allow-always` ne supprime pas les invites lorsque le mode ask effectif est `always`
|
||||
- une confiance durable `allow-always` ne supprime pas les invites lorsque le mode ask effectif est `always`
|
||||
|
||||
### Repli ask (`askFallback`)
|
||||
### Solution de repli Ask (`askFallback`)
|
||||
|
||||
Si une invite est requise mais qu’aucune interface n’est joignable, le repli décide :
|
||||
Si une invite est requise mais qu’aucune interface n’est accessible, la solution de repli décide :
|
||||
|
||||
- **deny** : bloquer.
|
||||
- **allowlist** : autoriser uniquement si la liste d’autorisation correspond.
|
||||
- **full** : autoriser.
|
||||
|
||||
### Durcissement de l’évaluation en ligne par interpréteur (`tools.exec.strictInlineEval`)
|
||||
### Renforcement de l’évaluation inline de l’interpréteur (`tools.exec.strictInlineEval`)
|
||||
|
||||
Lorsque `tools.exec.strictInlineEval=true`, OpenClaw traite les formes d’évaluation de code en ligne comme nécessitant une approbation uniquement, même si le binaire d’interpréteur lui-même figure dans la liste d’autorisation.
|
||||
Quand `tools.exec.strictInlineEval=true`, OpenClaw traite les formes d’évaluation inline du code comme nécessitant une approbation même si le binaire de l’interpréteur lui-même figure dans la liste d’autorisation.
|
||||
|
||||
Exemples :
|
||||
|
||||
@ -212,15 +238,15 @@ Exemples :
|
||||
Il s’agit d’une défense en profondeur pour les chargeurs d’interpréteur qui ne se mappent pas proprement à un seul opérande de fichier stable. En mode strict :
|
||||
|
||||
- ces commandes nécessitent toujours une approbation explicite ;
|
||||
- `allow-always` ne conserve pas automatiquement de nouvelles entrées de liste d’autorisation pour elles.
|
||||
- `allow-always` ne persiste pas automatiquement de nouvelles entrées de liste d’autorisation pour elles.
|
||||
|
||||
## Liste d’autorisation (par agent)
|
||||
|
||||
Les listes d’autorisation sont **par agent**. Si plusieurs agents existent, changez l’agent que vous
|
||||
modifiez dans l’app macOS. Les motifs sont des **correspondances glob insensibles à la casse**.
|
||||
Les motifs doivent se résoudre en **chemins binaires** (les entrées avec uniquement le nom de base sont ignorées).
|
||||
Les motifs doivent se résoudre en **chemins de binaire** (les entrées avec nom de base uniquement sont ignorées).
|
||||
Les anciennes entrées `agents.default` sont migrées vers `agents.main` au chargement.
|
||||
Les chaînages shell tels que `echo ok && pwd` exigent toujours que chaque segment de premier niveau respecte les règles de la liste d’autorisation.
|
||||
Les chaînes shell comme `echo ok && pwd` exigent toujours que chaque segment de premier niveau respecte les règles de liste d’autorisation.
|
||||
|
||||
Exemples :
|
||||
|
||||
@ -228,79 +254,81 @@ Exemples :
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
Chaque entrée de la liste d’autorisation suit :
|
||||
Chaque entrée de liste d’autorisation suit :
|
||||
|
||||
- **id** UUID stable utilisé pour l’identité dans l’interface (facultatif)
|
||||
- **dernière utilisation** horodatage
|
||||
- horodatage de **dernière utilisation**
|
||||
- **dernière commande utilisée**
|
||||
- **dernier chemin résolu**
|
||||
|
||||
## Auto-autoriser les CLI de Skills
|
||||
|
||||
Lorsque **Auto-allow skill CLIs** est activé, les exécutables référencés par des Skills connus
|
||||
sont traités comme étant dans la liste d’autorisation sur les nœuds (nœud macOS ou hôte de nœud sans interface). Cela utilise
|
||||
`skills.bins` via la RPC Gateway pour récupérer la liste des binaires de skill. Désactivez cette option si vous voulez des listes d’autorisation strictement manuelles.
|
||||
Lorsque **Auto-allow skill CLIs** est activé, les exécutables référencés par les Skills connus
|
||||
sont traités comme figurant dans la liste d’autorisation sur les nœuds (nœud macOS ou hôte de nœud headless). Cela utilise
|
||||
`skills.bins` via le RPC Gateway pour récupérer la liste des binaires de Skills. Désactivez cette option si vous voulez des listes d’autorisation manuelles strictes.
|
||||
|
||||
Remarques importantes sur la confiance :
|
||||
Notes de confiance importantes :
|
||||
|
||||
- Il s’agit d’une **liste d’autorisation implicite de commodité**, distincte des entrées de liste d’autorisation manuelle par chemin.
|
||||
- Elle est destinée aux environnements d’opérateur de confiance où la Gateway et le nœud sont dans la même limite de confiance.
|
||||
- Si vous exigez une confiance explicite stricte, gardez `autoAllowSkills: false` et utilisez uniquement des entrées manuelles de liste d’autorisation par chemin.
|
||||
- Il s’agit d’une **liste d’autorisation implicite pratique**, distincte des entrées manuelles de liste d’autorisation par chemin.
|
||||
- Elle est destinée à des environnements d’opérateurs de confiance où Gateway et le nœud sont dans la même frontière de confiance.
|
||||
- Si vous exigez une confiance explicite stricte, conservez `autoAllowSkills: false` et utilisez uniquement des entrées manuelles de liste d’autorisation par chemin.
|
||||
|
||||
## Safe bins (stdin-only)
|
||||
|
||||
`tools.exec.safeBins` définit une petite liste de binaires **stdin-only** (par exemple `cut`)
|
||||
pouvant s’exécuter en mode allowlist **sans** entrées explicites dans la liste d’autorisation. Les safe bins rejettent
|
||||
les arguments de fichier positionnels et les jetons ressemblant à des chemins, ils ne peuvent donc agir que sur le flux entrant.
|
||||
Considérez cela comme un chemin rapide étroit pour des filtres de flux, pas comme une liste de confiance générale.
|
||||
qui peuvent s’exécuter en mode liste d’autorisation **sans** entrées explicites dans la liste d’autorisation. Les safe bins refusent
|
||||
les arguments de fichier positionnels et les jetons ressemblant à des chemins, afin qu’ils ne puissent opérer que sur le flux entrant.
|
||||
Considérez cela comme un chemin rapide étroit pour les filtres de flux, et non comme une liste de confiance générale.
|
||||
N’ajoutez **pas** de binaires d’interpréteur ou de runtime (par exemple `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) à `safeBins`.
|
||||
Si une commande peut évaluer du code, exécuter des sous-commandes ou lire des fichiers par conception, préférez des entrées explicites dans la liste d’autorisation et conservez les invites d’approbation activées.
|
||||
Si une commande peut évaluer du code, exécuter des sous-commandes ou lire des fichiers par conception, préférez des entrées explicites dans la liste d’autorisation et laissez les invites d’approbation activées.
|
||||
Les safe bins personnalisés doivent définir un profil explicite dans `tools.exec.safeBinProfiles.<bin>`.
|
||||
La validation est déterministe à partir de la seule forme de `argv` (sans vérifications de présence de fichiers sur le système hôte), ce qui
|
||||
évite un comportement d’oracle d’existence de fichier via les différences entre allow et deny.
|
||||
Les options orientées fichier sont refusées pour les safe bins par défaut (par exemple `sort -o`, `sort --output`,
|
||||
La validation est déterministe à partir de la seule forme de `argv` (sans vérification d’existence sur le système de fichiers hôte), ce qui
|
||||
évite un comportement d’oracle d’existence de fichier via des différences d’autorisation/refus.
|
||||
Les options orientées fichiers sont refusées pour les safe bins par défaut (par exemple `sort -o`, `sort --output`,
|
||||
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
|
||||
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
|
||||
`grep -f/--file`).
|
||||
Les safe bins appliquent également une politique explicite de drapeaux par binaire pour les options qui cassent le comportement stdin-only
|
||||
(par exemple `sort -o/--output/--compress-program` et les drapeaux récursifs de grep).
|
||||
Les options longues sont validées en mode fermé en safe-bin : les drapeaux inconnus et les abréviations ambiguës sont rejetés.
|
||||
Drapeaux refusés par profil de safe-bin :
|
||||
Les safe bins appliquent aussi une politique explicite par binaire sur les drapeaux qui rompent le
|
||||
comportement stdin-only (par exemple `sort -o/--output/--compress-program` et les drapeaux récursifs de grep).
|
||||
Les options longues sont validées en refus par défaut en mode safe-bin : les drapeaux inconnus et les
|
||||
abréviations ambiguës sont rejetés.
|
||||
Drapeaux refusés par profil safe-bin :
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
|
||||
|
||||
- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
|
||||
- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
|
||||
- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
|
||||
- `wc`: `--files0-from`
|
||||
- `grep` : `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
|
||||
- `jq` : `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
|
||||
- `sort` : `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
|
||||
- `wc` : `--files0-from`
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
Les safe bins forcent également les jetons `argv` à être traités comme du **texte littéral** au moment de l’exécution (sans globbing
|
||||
et sans expansion `$VARS`) pour les segments stdin-only, de sorte que des motifs tels que `*` ou `$HOME/...` ne puissent pas être
|
||||
Les safe bins forcent aussi les jetons `argv` à être traités comme du **texte littéral** au moment de l’exécution (pas de globbing
|
||||
et pas d’expansion de `$VARS`) pour les segments stdin-only, afin que des motifs comme `*` ou `$HOME/...` ne puissent pas être
|
||||
utilisés pour dissimuler des lectures de fichiers.
|
||||
Les safe bins doivent également se résoudre à partir de répertoires binaires de confiance (valeurs système par défaut plus
|
||||
`tools.exec.safeBinTrustedDirs` facultatif). Les entrées `PATH` ne sont jamais automatiquement dignes de confiance.
|
||||
Les répertoires de confiance safe-bin par défaut sont volontairement minimaux : `/bin`, `/usr/bin`.
|
||||
Si votre exécutable safe-bin se trouve dans des chemins de gestionnaire de paquets/utilisateur (par exemple
|
||||
Les safe bins doivent aussi se résoudre depuis des répertoires de binaires de confiance (valeurs système par défaut plus
|
||||
`tools.exec.safeBinTrustedDirs` facultatif). Les entrées `PATH` ne sont jamais automatiquement considérées comme fiables.
|
||||
Les répertoires fiables par défaut pour les safe bins sont volontairement minimaux : `/bin`, `/usr/bin`.
|
||||
Si votre exécutable safe-bin se trouve dans des chemins utilisateur ou de gestionnaire de paquets (par exemple
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), ajoutez-les explicitement
|
||||
à `tools.exec.safeBinTrustedDirs`.
|
||||
Le chaînage shell et les redirections ne sont pas automatiquement autorisés en mode allowlist.
|
||||
L’enchaînement shell et les redirections ne sont pas automatiquement autorisés en mode allowlist.
|
||||
|
||||
Le chaînage shell (`&&`, `||`, `;`) est autorisé lorsque chaque segment de premier niveau satisfait la liste d’autorisation
|
||||
(y compris les safe bins ou l’auto-autorisation des skills). Les redirections restent non prises en charge en mode allowlist.
|
||||
La substitution de commande (`$()` / accents graves) est rejetée lors de l’analyse de la liste d’autorisation, y compris à l’intérieur
|
||||
des guillemets doubles ; utilisez des guillemets simples si vous avez besoin du texte littéral `$()`.
|
||||
L’enchaînement shell (`&&`, `||`, `;`) est autorisé lorsque chaque segment de premier niveau satisfait la liste d’autorisation
|
||||
(y compris les safe bins ou l’auto-autorisation de Skills). Les redirections restent non prises en charge en mode allowlist.
|
||||
La substitution de commande (`$()` / accents graves) est rejetée lors de l’analyse allowlist, y compris à l’intérieur des
|
||||
guillemets doubles ; utilisez des guillemets simples si vous avez besoin du texte littéral `$()`.
|
||||
Dans les approbations de l’app compagnon macOS, le texte shell brut contenant une syntaxe de contrôle ou d’expansion shell
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance dans la liste d’autorisation sauf
|
||||
si le binaire shell lui-même figure dans la liste d’autorisation.
|
||||
Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les remplacements d’environnement limités à la requête sont réduits à une
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) est traité comme une absence de correspondance dans la liste d’autorisation, sauf si
|
||||
le binaire shell lui-même figure dans la liste d’autorisation.
|
||||
Pour les wrappers shell (`bash|sh|zsh ... -c/-lc`), les substitutions d’environnement à portée de requête sont réduites à une
|
||||
petite liste d’autorisation explicite (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Pour les décisions allow-always en mode allowlist, les wrappers de distribution connus
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) conservent les chemins des exécutables internes plutôt que ceux des wrappers. Les multiplexeurs shell (`busybox`, `toybox`) sont également déballés pour les applets shell (`sh`, `ash`,
|
||||
etc.) afin que les exécutables internes soient conservés plutôt que les binaires du multiplexeur. Si un wrapper ou
|
||||
un multiplexeur ne peut pas être déballé en toute sécurité, aucune entrée de liste d’autorisation n’est automatiquement conservée.
|
||||
Si vous mettez dans la liste d’autorisation des interpréteurs comme `python3` ou `node`, préférez `tools.exec.strictInlineEval=true` afin que l’évaluation en ligne nécessite toujours une approbation explicite. En mode strict, `allow-always` peut toujours conserver des invocations bénignes d’interpréteur/script, mais les vecteurs d’évaluation en ligne ne sont pas conservés automatiquement.
|
||||
Pour les décisions allow-always en mode allowlist, les wrappers de répartition connus
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistent les chemins des exécutables internes au lieu des chemins
|
||||
des wrappers. Les multiplexeurs shell (`busybox`, `toybox`) sont aussi déballés pour les applets shell (`sh`, `ash`,
|
||||
etc.) afin que les exécutables internes soient persistés au lieu des binaires du multiplexeur. Si un wrapper ou un
|
||||
multiplexeur ne peut pas être déballé de manière sûre, aucune entrée de liste d’autorisation n’est persistée automatiquement.
|
||||
Si vous mettez des interpréteurs comme `python3` ou `node` dans la liste d’autorisation, préférez `tools.exec.strictInlineEval=true` afin que l’évaluation inline nécessite toujours une approbation explicite. En mode strict, `allow-always` peut toujours persister des invocations bénignes d’interpréteur/script, mais les supports d’évaluation inline ne sont pas persistés automatiquement.
|
||||
|
||||
Safe bins par défaut :
|
||||
|
||||
@ -311,105 +339,103 @@ Safe bins par défaut :
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` et `sort` ne font pas partie de la liste par défaut. Si vous les activez explicitement, conservez des entrées explicites dans la liste d’autorisation pour
|
||||
leurs workflows non stdin.
|
||||
Pour `grep` en mode safe-bin, fournissez le motif avec `-e`/`--regexp` ; la forme de motif positionnel est
|
||||
leurs flux de travail non stdin.
|
||||
Pour `grep` en mode safe-bin, fournissez le motif avec `-e`/`--regexp` ; la forme de motif positionnelle est
|
||||
rejetée afin que des opérandes de fichier ne puissent pas être dissimulés comme positionnels ambigus.
|
||||
|
||||
### Safe bins versus allowlist
|
||||
### Safe bins versus liste d’autorisation
|
||||
|
||||
| Sujet | `tools.exec.safeBins` | Liste d’autorisation (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Objectif | Autoriser automatiquement des filtres stdin étroits | Faire explicitement confiance à des exécutables spécifiques |
|
||||
| Type de correspondance | Nom d’exécutable + politique `argv` du profil safe-bin | Motif glob du chemin exécutable résolu |
|
||||
| Portée des arguments | Restreinte par le profil safe-bin et les règles de jetons littéraux | Correspondance sur le chemin uniquement ; les arguments restent sinon sous votre responsabilité |
|
||||
| Exemples typiques | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI personnalisées |
|
||||
| Meilleur usage | Transformations de texte à faible risque dans des pipelines | Tout outil avec un comportement plus large ou des effets de bord |
|
||||
| Objectif | Auto-autoriser des filtres stdin étroits | Faire explicitement confiance à des exécutables spécifiques |
|
||||
| Type de correspondance | Nom d’exécutable + politique `argv` du safe-bin | Motif glob du chemin résolu de l’exécutable |
|
||||
| Portée des arguments | Restreinte par le profil safe-bin et les règles de jetons littéraux | Correspondance de chemin uniquement ; les arguments relèvent sinon de votre responsabilité |
|
||||
| Exemples typiques | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI personnalisées |
|
||||
| Meilleure utilisation | Transformations de texte à faible risque dans des pipelines | Tout outil au comportement plus large ou avec effets de bord |
|
||||
|
||||
Emplacement de la configuration :
|
||||
|
||||
- `safeBins` provient de la configuration (`tools.exec.safeBins` ou par agent `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` provient de la configuration (`tools.exec.safeBinTrustedDirs` ou par agent `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` provient de la configuration (`tools.exec.safeBinProfiles` ou par agent `agents.list[].tools.exec.safeBinProfiles`). Les clés de profil par agent remplacent les clés globales.
|
||||
- les entrées de la liste d’autorisation vivent dans le fichier local à l’hôte `~/.openclaw/exec-approvals.json` sous `agents.<id>.allowlist` (ou via Control UI / `openclaw approvals allowlist ...`).
|
||||
- `safeBins` vient de la configuration (`tools.exec.safeBins` ou `agents.list[].tools.exec.safeBins` par agent).
|
||||
- `safeBinTrustedDirs` vient de la configuration (`tools.exec.safeBinTrustedDirs` ou `agents.list[].tools.exec.safeBinTrustedDirs` par agent).
|
||||
- `safeBinProfiles` vient de la configuration (`tools.exec.safeBinProfiles` ou `agents.list[].tools.exec.safeBinProfiles` par agent). Les clés de profil par agent remplacent les clés globales.
|
||||
- les entrées de liste d’autorisation vivent dans `~/.openclaw/exec-approvals.json` local à l’hôte sous `agents.<id>.allowlist` (ou via Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` avertit avec `tools.exec.safe_bins_interpreter_unprofiled` lorsque des binaires d’interpréteur/runtime apparaissent dans `safeBins` sans profils explicites.
|
||||
- `openclaw doctor --fix` peut générer des entrées `safeBinProfiles.<bin>` personnalisées manquantes sous forme de `{}` (relisez-les et resserrez-les ensuite). Les binaires d’interpréteur/runtime ne sont pas générés automatiquement.
|
||||
- `openclaw doctor --fix` peut générer les entrées personnalisées manquantes `safeBinProfiles.<bin>` sous la forme `{}` (vérifiez-les et resserrez-les ensuite). Les binaires d’interpréteur/runtime ne sont pas générés automatiquement.
|
||||
|
||||
Exemple de profil personnalisé :
|
||||
__OC_I18N_900004__
|
||||
Si vous ajoutez explicitement `jq` à `safeBins`, OpenClaw rejette toujours le builtin `env` en mode safe-bin
|
||||
__OC_I18N_900005__
|
||||
Si vous activez explicitement `jq` dans `safeBins`, OpenClaw rejette quand même le builtin `env` en mode safe-bin
|
||||
afin que `jq -n env` ne puisse pas vider l’environnement du processus hôte sans chemin explicite dans la liste d’autorisation
|
||||
ou invite d’approbation.
|
||||
|
||||
## Modification dans Control UI
|
||||
|
||||
Utilisez la carte **Control UI → Nodes → Exec approvals** pour modifier les valeurs par défaut, les remplacements
|
||||
par agent et les listes d’autorisation. Choisissez une portée (Defaults ou un agent), ajustez la politique,
|
||||
ajoutez/supprimez des motifs de liste d’autorisation, puis cliquez sur **Save**. L’interface affiche les métadonnées **last used**
|
||||
par motif pour vous aider à garder la liste propre.
|
||||
Utilisez la carte **Control UI → Nodes → Exec approvals** pour modifier les valeurs par défaut, les
|
||||
remplacements par agent et les listes d’autorisation. Choisissez une portée (valeurs par défaut ou agent), ajustez la politique,
|
||||
ajoutez/supprimez des motifs de liste d’autorisation, puis cliquez sur **Save**. L’interface affiche les métadonnées de **dernière utilisation**
|
||||
par motif afin que vous puissiez garder la liste propre.
|
||||
|
||||
Le sélecteur de cible choisit **Gateway** (approbations locales) ou un **Node**. Les nœuds
|
||||
doivent annoncer `system.execApprovals.get/set` (app macOS ou hôte de nœud sans interface).
|
||||
Si un nœud n’annonce pas encore les approbations exec, modifiez directement son
|
||||
doivent annoncer `system.execApprovals.get/set` (app macOS ou hôte de nœud headless).
|
||||
Si un nœud n’annonce pas encore les approbations d’exécution, modifiez directement son
|
||||
`~/.openclaw/exec-approvals.json` local.
|
||||
|
||||
CLI : `openclaw approvals` prend en charge la modification gateway ou node (voir [CLI des approbations](/cli/approvals)).
|
||||
CLI : `openclaw approvals` prend en charge la modification sur gateway ou sur nœud (voir [CLI d’approbations](/cli/approvals)).
|
||||
|
||||
## Flux d’approbation
|
||||
|
||||
Lorsqu’une invite est requise, la gateway diffuse `exec.approval.requested` aux clients opérateur.
|
||||
Lorsqu’une invite est requise, la gateway diffuse `exec.approval.requested` aux clients opérateurs.
|
||||
Control UI et l’app macOS la résolvent via `exec.approval.resolve`, puis la gateway transmet la
|
||||
requête approuvée à l’hôte de nœud.
|
||||
demande approuvée à l’hôte de nœud.
|
||||
|
||||
Pour `host=node`, les demandes d’approbation incluent une charge utile canonique `systemRunPlan`. La gateway utilise
|
||||
ce plan comme contexte faisant autorité pour la commande/le `cwd`/la session lors de la transmission des requêtes `system.run`
|
||||
approuvées.
|
||||
ce plan comme contexte de commande/cwd/session faisant autorité lors du transfert des demandes
|
||||
`system.run` approuvées.
|
||||
|
||||
C’est important pour la latence d’approbation asynchrone :
|
||||
|
||||
- le chemin d’exécution node prépare un plan canonique en amont
|
||||
- le chemin d’exécution du nœud prépare un plan canonique en amont
|
||||
- l’enregistrement d’approbation stocke ce plan et ses métadonnées de liaison
|
||||
- une fois approuvée, l’appel final transmis à `system.run` réutilise le plan stocké
|
||||
au lieu de faire confiance à des modifications ultérieures de l’appelant
|
||||
- si l’appelant modifie `command`, `rawCommand`, `cwd`, `agentId` ou
|
||||
- une fois approuvée, l’appel final `system.run` transmis réutilise le plan stocké
|
||||
au lieu de se fier à des modifications ultérieures de l’appelant
|
||||
- si l’appelant modifie `command`, `rawCommand`, `cwd`, `agentId`, ou
|
||||
`sessionKey` après la création de la demande d’approbation, la gateway rejette l’exécution
|
||||
transmise comme incompatibilité d’approbation
|
||||
transmise comme non conforme à l’approbation
|
||||
|
||||
## Commandes d’interpréteur/runtime
|
||||
|
||||
Les exécutions d’interpréteur/runtime appuyées par approbation sont volontairement prudentes :
|
||||
Les exécutions d’interpréteur/runtime adossées à une approbation sont volontairement prudentes :
|
||||
|
||||
- Le contexte exact `argv`/`cwd`/`env` est toujours lié.
|
||||
- Les formes de script shell direct et de fichier runtime direct sont liées au mieux à un instantané concret d’un seul
|
||||
fichier local.
|
||||
- Les formes courantes de wrapper de gestionnaire de paquets qui se résolvent toujours en un seul fichier local direct (par exemple
|
||||
- Les formes directes de script shell et de fichier runtime sont liées au mieux à un instantané d’un seul fichier local concret.
|
||||
- Les formes courantes de wrappers de gestionnaire de paquets qui se résolvent malgré tout vers un seul fichier local direct (par exemple
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`) sont déballées avant la liaison.
|
||||
- Si OpenClaw ne peut pas identifier exactement un fichier local concret pour une commande d’interpréteur/runtime
|
||||
(par exemple scripts de paquet, formes d’évaluation, chaînes de chargement propres au runtime ou formes ambiguës
|
||||
à plusieurs fichiers), l’exécution appuyée par approbation est refusée au lieu de prétendre à une couverture sémantique
|
||||
qu’elle n’a pas.
|
||||
- Pour ces workflows, préférez le sandboxing, une limite d’hôte séparée ou un workflow explicite de confiance
|
||||
via allowlist/full où l’opérateur accepte la sémantique plus large du runtime.
|
||||
(par exemple scripts de package, formes eval, chaînes de chargement propres au runtime, ou formes ambiguës multi-fichiers),
|
||||
l’exécution adossée à une approbation est refusée au lieu de prétendre couvrir une sémantique qu’elle n’a pas.
|
||||
- Pour ces flux de travail, préférez le sandboxing, une frontière d’hôte séparée, ou un flux explicite
|
||||
de liste d’autorisation/de `full` de confiance où l’opérateur accepte la sémantique runtime plus large.
|
||||
|
||||
Lorsque des approbations sont requises, l’outil exec renvoie immédiatement avec un id d’approbation. Utilisez cet id pour
|
||||
Lorsque des approbations sont requises, l’outil exec renvoie immédiatement avec un identifiant d’approbation. Utilisez cet identifiant pour
|
||||
corréler les événements système ultérieurs (`Exec finished` / `Exec denied`). Si aucune décision n’arrive avant le
|
||||
délai d’attente, la requête est traitée comme un timeout d’approbation et exposée comme motif de refus.
|
||||
délai d’expiration, la demande est traitée comme un délai d’approbation expiré et remontée comme motif de refus.
|
||||
|
||||
### Comportement de livraison du suivi
|
||||
### Comportement de remise de suivi
|
||||
|
||||
Après la fin d’une exécution asynchrone approuvée, OpenClaw envoie un tour `agent` de suivi à la même session.
|
||||
|
||||
- Si une cible de livraison externe valide existe (canal livrable plus cible `to`), la livraison du suivi utilise ce canal.
|
||||
- Dans les flux webchat uniquement ou les sessions internes sans cible externe, la livraison du suivi reste limitée à la session (`deliver: false`).
|
||||
- Si un appelant demande explicitement une livraison externe stricte sans canal externe résoluble, la requête échoue avec `INVALID_REQUEST`.
|
||||
- Si `bestEffortDeliver` est activé et qu’aucun canal externe ne peut être résolu, la livraison est rétrogradée vers une livraison limitée à la session au lieu d’échouer.
|
||||
- Si une cible de remise externe valide existe (canal livrable plus cible `to`), la remise de suivi utilise ce canal.
|
||||
- Dans les flux webchat uniquement ou de session interne sans cible externe, la remise de suivi reste limitée à la session (`deliver: false`).
|
||||
- Si un appelant demande explicitement une remise externe stricte sans canal externe résoluble, la demande échoue avec `INVALID_REQUEST`.
|
||||
- Si `bestEffortDeliver` est activé et qu’aucun canal externe ne peut être résolu, la remise est rétrogradée en mode session uniquement au lieu d’échouer.
|
||||
|
||||
La boîte de dialogue de confirmation inclut :
|
||||
|
||||
- commande + arguments
|
||||
- `cwd`
|
||||
- id d’agent
|
||||
- chemin exécutable résolu
|
||||
- métadonnées d’hôte + de politique
|
||||
- identifiant d’agent
|
||||
- chemin résolu de l’exécutable
|
||||
- hôte + métadonnées de politique
|
||||
|
||||
Actions :
|
||||
|
||||
@ -417,107 +443,106 @@ Actions :
|
||||
- **Always allow** → ajouter à la liste d’autorisation + exécuter
|
||||
- **Deny** → bloquer
|
||||
|
||||
## Transfert des approbations vers les canaux de discussion
|
||||
## Transfert des approbations vers les canaux de chat
|
||||
|
||||
Vous pouvez transférer les invites d’approbation exec vers n’importe quel canal de discussion (y compris les canaux de plugin) et les approuver
|
||||
avec `/approve`. Cela utilise le pipeline normal de livraison sortante.
|
||||
Vous pouvez transférer les invites d’approbation d’exécution vers n’importe quel canal de chat (y compris les canaux de plugin) et les approuver
|
||||
avec `/approve`. Cela utilise le pipeline de remise sortante normal.
|
||||
|
||||
Configuration :
|
||||
__OC_I18N_900005__
|
||||
Répondez dans la discussion :
|
||||
__OC_I18N_900006__
|
||||
La commande `/approve` gère à la fois les approbations exec et les approbations de plugin. Si l’ID ne correspond pas à une approbation exec en attente, elle vérifie automatiquement les approbations de plugin à la place.
|
||||
Répondez dans le chat :
|
||||
__OC_I18N_900007__
|
||||
La commande `/approve` gère à la fois les approbations d’exécution et les approbations de plugin. Si l’identifiant ne correspond à aucune approbation d’exécution en attente, elle vérifie automatiquement les approbations de plugin à la place.
|
||||
|
||||
### Transfert des approbations de plugin
|
||||
|
||||
Le transfert des approbations de plugin utilise le même pipeline de livraison que les approbations exec, mais dispose de sa
|
||||
Le transfert des approbations de plugin utilise le même pipeline de remise que les approbations d’exécution, mais possède sa
|
||||
propre configuration indépendante sous `approvals.plugin`. Activer ou désactiver l’un n’affecte pas l’autre.
|
||||
__OC_I18N_900007__
|
||||
La forme de configuration est identique à `approvals.exec` : `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter` et `targets` fonctionnent de la même manière.
|
||||
__OC_I18N_900008__
|
||||
La forme de la configuration est identique à `approvals.exec` : `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter`, et `targets` fonctionnent de la même manière.
|
||||
|
||||
Les canaux qui prennent en charge les réponses interactives partagées affichent les mêmes boutons d’approbation pour les approbations exec et
|
||||
Les canaux qui prennent en charge les réponses interactives partagées affichent les mêmes boutons d’approbation pour les approbations d’exécution et
|
||||
de plugin. Les canaux sans interface interactive partagée reviennent à du texte brut avec des instructions `/approve`.
|
||||
|
||||
### Approbations dans la même discussion sur n’importe quel canal
|
||||
### Approbations dans le même chat sur n’importe quel canal
|
||||
|
||||
Lorsqu’une demande d’approbation exec ou de plugin provient d’une surface de discussion livrable, cette même discussion
|
||||
Lorsqu’une demande d’approbation d’exécution ou de plugin provient d’une surface de chat livrable, ce même chat
|
||||
peut désormais l’approuver avec `/approve` par défaut. Cela s’applique à des canaux tels que Slack, Matrix et
|
||||
Microsoft Teams en plus des flux existants de l’interface Web et de l’interface terminal.
|
||||
Microsoft Teams, en plus des flux existants de l’interface Web et de l’interface terminal.
|
||||
|
||||
Ce chemin partagé par commande texte utilise le modèle d’authentification normal du canal pour cette conversation. Si la
|
||||
discussion d’origine peut déjà envoyer des commandes et recevoir des réponses, les demandes d’approbation n’ont plus besoin d’un
|
||||
adaptateur distinct de livraison native simplement pour rester en attente.
|
||||
Ce chemin partagé par commande texte utilise le modèle d’authentification normal du canal pour cette conversation. Si le
|
||||
chat d’origine peut déjà envoyer des commandes et recevoir des réponses, les demandes d’approbation n’ont plus besoin d’un
|
||||
adaptateur de remise natif séparé simplement pour rester en attente.
|
||||
|
||||
Discord et Telegram prennent également en charge `/approve` dans la même discussion, mais ces canaux utilisent toujours leur
|
||||
liste résolue d’approbateurs pour l’autorisation même lorsque la livraison native des approbations est désactivée.
|
||||
Discord et Telegram prennent aussi en charge `/approve` dans le même chat, mais ces canaux utilisent toujours leur
|
||||
liste d’approbateurs résolue pour l’autorisation, même lorsque la remise native des approbations est désactivée.
|
||||
|
||||
Pour Telegram et les autres clients d’approbation native qui appellent directement la Gateway,
|
||||
ce repli est volontairement limité aux échecs « approval not found ». Un vrai
|
||||
refus/une vraie erreur d’approbation exec ne fait pas silencieusement l’objet d’une nouvelle tentative comme approbation de plugin.
|
||||
Pour Telegram et les autres clients d’approbation natifs qui appellent directement la Gateway,
|
||||
cette solution de repli est volontairement limitée aux échecs de type « approbation introuvable ». Une véritable
|
||||
erreur/refus d’approbation d’exécution ne réessaie pas silencieusement comme approbation de plugin.
|
||||
|
||||
### Livraison native des approbations
|
||||
### Remise native des approbations
|
||||
|
||||
Certains canaux peuvent aussi agir comme clients natifs d’approbation. Les clients natifs ajoutent les DM des approbateurs, la
|
||||
diffusion vers la discussion d’origine et une UX interactive d’approbation spécifique au canal en plus du
|
||||
flux partagé `/approve` dans la même discussion.
|
||||
Certains canaux peuvent aussi agir comme clients d’approbation natifs. Les clients natifs ajoutent des MP d’approbateur, un fanout vers le chat d’origine
|
||||
et une expérience utilisateur d’approbation interactive propre au canal par-dessus le flux partagé `/approve` dans le même chat.
|
||||
|
||||
Lorsque des cartes/boutons d’approbation native sont disponibles, cette interface native est le
|
||||
chemin principal côté agent. L’agent ne doit pas également faire écho à une commande de discussion
|
||||
`/approve` en double sauf si le résultat de l’outil indique que les approbations par discussion ne sont pas disponibles ou que
|
||||
Lorsque des cartes/boutons d’approbation natifs sont disponibles, cette interface native constitue le chemin principal
|
||||
orienté agent. L’agent ne doit pas non plus répéter une commande de chat en clair
|
||||
`/approve`, sauf si le résultat de l’outil indique que les approbations par chat ne sont pas disponibles ou que
|
||||
l’approbation manuelle est le seul chemin restant.
|
||||
|
||||
Modèle générique :
|
||||
|
||||
- la politique d’exécution hôte décide toujours si une approbation exec est requise
|
||||
- `approvals.exec` contrôle le transfert des invites d’approbation vers d’autres destinations de discussion
|
||||
- `channels.<channel>.execApprovals` contrôle si ce canal agit comme client natif d’approbation
|
||||
- la politique d’exécution sur hôte décide toujours si une approbation d’exécution est requise
|
||||
- `approvals.exec` contrôle le transfert des invites d’approbation vers d’autres destinations de chat
|
||||
- `channels.<channel>.execApprovals` contrôle si ce canal agit comme client d’approbation natif
|
||||
|
||||
Les clients natifs d’approbation activent automatiquement la livraison DM-first lorsque toutes ces conditions sont vraies :
|
||||
Les clients d’approbation natifs activent automatiquement une remise d’abord par MP lorsque toutes les conditions suivantes sont réunies :
|
||||
|
||||
- le canal prend en charge la livraison native des approbations
|
||||
- les approbateurs peuvent être résolus à partir de `execApprovals.approvers` explicite ou des sources de repli documentées
|
||||
pour ce canal
|
||||
- le canal prend en charge la remise d’approbation native
|
||||
- les approbateurs peuvent être résolus à partir de `execApprovals.approvers` explicite ou des
|
||||
sources de repli documentées pour ce canal
|
||||
- `channels.<channel>.execApprovals.enabled` n’est pas défini ou vaut `"auto"`
|
||||
|
||||
Définissez `enabled: false` pour désactiver explicitement un client natif d’approbation. Définissez `enabled: true` pour
|
||||
le forcer lorsque les approbateurs sont résolus. La livraison publique vers la discussion d’origine reste explicite via
|
||||
Définissez `enabled: false` pour désactiver explicitement un client d’approbation natif. Définissez `enabled: true` pour le forcer
|
||||
lorsque les approbateurs se résolvent. La remise publique dans le chat d’origine reste explicite via
|
||||
`channels.<channel>.execApprovals.target`.
|
||||
|
||||
FAQ : [Pourquoi y a-t-il deux configurations d’approbation exec pour les approbations de discussion ?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
FAQ : [Pourquoi existe-t-il deux configurations d’approbation d’exécution pour les approbations par chat ?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
|
||||
- Discord : `channels.discord.execApprovals.*`
|
||||
- Slack : `channels.slack.execApprovals.*`
|
||||
- Telegram : `channels.telegram.execApprovals.*`
|
||||
|
||||
Ces clients natifs d’approbation ajoutent le routage DM et la diffusion facultative vers un canal au flux partagé
|
||||
`/approve` dans la même discussion et aux boutons d’approbation partagés.
|
||||
Ces clients d’approbation natifs ajoutent un routage par MP et un fanout de canal facultatif au-dessus du flux partagé
|
||||
`/approve` dans le même chat et des boutons d’approbation partagés.
|
||||
|
||||
Comportement partagé :
|
||||
|
||||
- Slack, Matrix, Microsoft Teams et autres discussions livrables similaires utilisent le modèle d’authentification normal du canal
|
||||
pour `/approve` dans la même discussion
|
||||
- lorsqu’un client natif d’approbation s’active automatiquement, la cible de livraison native par défaut est les DM des approbateurs
|
||||
- Slack, Matrix, Microsoft Teams et les chats livrables similaires utilisent le modèle d’authentification normal du canal
|
||||
pour `/approve` dans le même chat
|
||||
- lorsqu’un client d’approbation natif s’active automatiquement, la cible de remise native par défaut est les MP des approbateurs
|
||||
- pour Discord et Telegram, seuls les approbateurs résolus peuvent approuver ou refuser
|
||||
- les approbateurs Discord peuvent être explicites (`execApprovals.approvers`) ou déduits de `commands.ownerAllowFrom`
|
||||
- les approbateurs Telegram peuvent être explicites (`execApprovals.approvers`) ou déduits de la configuration propriétaire existante (`allowFrom`, plus `defaultTo` en message direct lorsque pris en charge)
|
||||
- les approbateurs Slack peuvent être explicites (`execApprovals.approvers`) ou déduits de `commands.ownerAllowFrom`
|
||||
- les boutons natifs Slack préservent le type d’id d’approbation, de sorte que les ids `plugin:` puissent résoudre les approbations de plugin
|
||||
sans seconde couche de repli locale à Slack
|
||||
- le routage DM/canal natif de Matrix et ses raccourcis par réaction gèrent à la fois les approbations exec et plugin ;
|
||||
l’autorisation de plugin continue cependant de provenir de `channels.matrix.dm.allowFrom`
|
||||
- les boutons natifs Slack préservent le type d’identifiant d’approbation, de sorte que les identifiants `plugin:` peuvent résoudre les approbations de plugin
|
||||
sans deuxième couche locale de repli propre à Slack
|
||||
- le routage natif par MP/canal Matrix et les raccourcis de réaction gèrent à la fois les approbations d’exécution et de plugin ;
|
||||
l’autorisation des plugins continue de provenir de `channels.matrix.dm.allowFrom`
|
||||
- le demandeur n’a pas besoin d’être un approbateur
|
||||
- la discussion d’origine peut approuver directement avec `/approve` lorsque cette discussion prend déjà en charge les commandes et les réponses
|
||||
- les boutons natifs d’approbation Discord routent selon le type d’id d’approbation : les ids `plugin:` vont
|
||||
directement vers les approbations de plugin, tout le reste va vers les approbations exec
|
||||
- les boutons natifs Telegram suivent le même repli borné d’exec vers plugin que `/approve`
|
||||
- lorsque `target` natif active la livraison vers la discussion d’origine, les invites d’approbation incluent le texte de la commande
|
||||
- les approbations exec en attente expirent après 30 minutes par défaut
|
||||
- si aucune interface opérateur ou aucun client d’approbation configuré ne peut accepter la requête, l’invite revient à `askFallback`
|
||||
- le chat d’origine peut approuver directement avec `/approve` lorsque ce chat prend déjà en charge les commandes et les réponses
|
||||
- les boutons d’approbation natifs Discord routent selon le type d’identifiant d’approbation : les identifiants `plugin:` vont
|
||||
directement vers les approbations de plugin, tout le reste va vers les approbations d’exécution
|
||||
- les boutons d’approbation natifs Telegram suivent le même repli borné des approbations d’exécution vers les approbations de plugin que `/approve`
|
||||
- lorsque `target` natif active la remise dans le chat d’origine, les invites d’approbation incluent le texte de la commande
|
||||
- les approbations d’exécution en attente expirent par défaut après 30 minutes
|
||||
- si aucune interface opérateur ou aucun client d’approbation configuré ne peut accepter la demande, l’invite retombe sur `askFallback`
|
||||
|
||||
Telegram utilise par défaut les DM des approbateurs (`target: "dm"`). Vous pouvez passer à `channel` ou `both` lorsque vous
|
||||
voulez que les invites d’approbation apparaissent aussi dans la discussion/le sujet Telegram d’origine. Pour les sujets de forum Telegram,
|
||||
OpenClaw préserve le sujet pour l’invite d’approbation et pour le suivi post-approbation.
|
||||
Telegram utilise par défaut les MP des approbateurs (`target: "dm"`). Vous pouvez passer à `channel` ou `both` lorsque vous
|
||||
voulez que les invites d’approbation apparaissent aussi dans le chat/sujet Telegram d’origine. Pour les sujets de forum Telegram,
|
||||
OpenClaw préserve le sujet pour l’invite d’approbation et le suivi après approbation.
|
||||
|
||||
Voir :
|
||||
|
||||
@ -525,51 +550,51 @@ Voir :
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Flux IPC macOS
|
||||
__OC_I18N_900008__
|
||||
Remarques de sécurité :
|
||||
__OC_I18N_900009__
|
||||
Notes de sécurité :
|
||||
|
||||
- Socket Unix en mode `0600`, jeton stocké dans `exec-approvals.json`.
|
||||
- Mode du socket Unix `0600`, jeton stocké dans `exec-approvals.json`.
|
||||
- Vérification du pair de même UID.
|
||||
- Challenge/response (nonce + jeton HMAC + hash de requête) + TTL court.
|
||||
- Challenge/réponse (nonce + jeton HMAC + hachage de requête) + TTL court.
|
||||
|
||||
## Événements système
|
||||
|
||||
Le cycle de vie exec est exposé sous forme de messages système :
|
||||
Le cycle de vie de l’exécution apparaît sous forme de messages système :
|
||||
|
||||
- `Exec running` (uniquement si la commande dépasse le seuil de notification d’exécution)
|
||||
- `Exec running` (uniquement si la commande dépasse le seuil de notification d’exécution en cours)
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Ils sont publiés dans la session de l’agent après que le nœud a signalé l’événement.
|
||||
Les approbations exec sur l’hôte gateway émettent les mêmes événements de cycle de vie lorsque la commande se termine (et éventuellement lorsqu’elle s’exécute plus longtemps que le seuil).
|
||||
Les execs contrôlés par approbation réutilisent l’id d’approbation comme `runId` dans ces messages pour faciliter la corrélation.
|
||||
Les approbations d’exécution sur l’hôte gateway émettent les mêmes événements de cycle de vie lorsque la commande se termine (et éventuellement lorsqu’elle s’exécute plus longtemps que le seuil).
|
||||
Les exécutions soumises à approbation réutilisent l’identifiant d’approbation comme `runId` dans ces messages pour faciliter la corrélation.
|
||||
|
||||
## Comportement lors d’une approbation refusée
|
||||
## Comportement en cas d’approbation refusée
|
||||
|
||||
Lorsqu’une approbation exec asynchrone est refusée, OpenClaw empêche l’agent de réutiliser
|
||||
Lorsqu’une approbation d’exécution asynchrone est refusée, OpenClaw empêche l’agent de réutiliser
|
||||
la sortie d’une exécution antérieure de la même commande dans la session. Le motif du refus
|
||||
est transmis avec des indications explicites disant qu’aucune sortie de commande n’est disponible, ce qui empêche
|
||||
l’agent d’affirmer qu’il y a une nouvelle sortie ou de répéter la commande refusée avec
|
||||
des résultats obsolètes issus d’une exécution antérieure réussie.
|
||||
est transmis avec une indication explicite qu’aucune sortie de commande n’est disponible, ce qui empêche
|
||||
l’agent d’affirmer qu’il existe une nouvelle sortie ou de répéter la commande refusée avec
|
||||
des résultats obsolètes issus d’une exécution réussie précédente.
|
||||
|
||||
## Implications
|
||||
|
||||
- **full** est puissant ; préférez les listes d’autorisation lorsque possible.
|
||||
- **ask** vous garde dans la boucle tout en permettant des approbations rapides.
|
||||
- Les listes d’autorisation par agent empêchent qu’une approbation d’un agent ne fuit vers d’autres.
|
||||
- Les approbations s’appliquent uniquement aux requêtes d’exécution hôte provenant d’**expéditeurs autorisés**. Les expéditeurs non autorisés ne peuvent pas émettre `/exec`.
|
||||
- `/exec security=full` est une commodité au niveau de la session pour les opérateurs autorisés et ignore volontairement les approbations.
|
||||
Pour bloquer strictement l’exécution hôte, définissez la sécurité des approbations sur `deny` ou refusez l’outil `exec` via la politique d’outils.
|
||||
- **full** est puissant ; préférez les listes d’autorisation lorsque c’est possible.
|
||||
- **ask** vous maintient dans la boucle tout en permettant des approbations rapides.
|
||||
- Les listes d’autorisation par agent empêchent les approbations d’un agent de fuir vers les autres.
|
||||
- Les approbations ne s’appliquent qu’aux demandes d’exécution sur hôte provenant **d’expéditeurs autorisés**. Les expéditeurs non autorisés ne peuvent pas émettre `/exec`.
|
||||
- `/exec security=full` est une commodité au niveau de la session pour les opérateurs autorisés et ignore les approbations par conception.
|
||||
Pour bloquer strictement l’exécution sur hôte, définissez la sécurité des approbations sur `deny` ou refusez l’outil `exec` via la politique d’outil.
|
||||
|
||||
Liens connexes :
|
||||
Associé :
|
||||
|
||||
- [Outil Exec](/fr/tools/exec)
|
||||
- [Mode Elevated](/fr/tools/elevated)
|
||||
- [Exec tool](/fr/tools/exec)
|
||||
- [Elevated mode](/fr/tools/elevated)
|
||||
- [Skills](/fr/tools/skills)
|
||||
|
||||
## Liens connexes
|
||||
## Associé
|
||||
|
||||
- [Exec](/fr/tools/exec) — outil d’exécution de commandes shell
|
||||
- [Sandboxing](/fr/gateway/sandboxing) — modes sandbox et accès à l’espace de travail
|
||||
- [Sécurité](/fr/gateway/security) — modèle de sécurité et durcissement
|
||||
- [Sandboxing](/fr/gateway/sandboxing) — modes de bac à sable et accès à l’espace de travail
|
||||
- [Security](/fr/gateway/security) — modèle de sécurité et durcissement
|
||||
- [Sandbox vs Tool Policy vs Elevated](/fr/gateway/sandbox-vs-tool-policy-vs-elevated) — quand utiliser chacun
|
||||
|
||||
Loading…
Reference in New Issue
Block a user