19 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Exec approvals | Approbations exec de l’hôte : réglages de politique, listes d’autorisation, et workflow YOLO/strict | Approbations Exec |
|
Les approbations exec sont le garde-fou de l’app compagnon / de l’hôte Node pour laisser
un agent sandboxé exécuter des commandes sur un hôte réel (gateway ou node). C’est
un verrou 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 exec se superposent par-dessus
la politique d’outils et le filtrage elevated (sauf si elevated est défini sur full, ce qui
ignore les approbations).
Inspection de la politique effective
| Commande | Ce qu’elle affiche |
|---|---|
openclaw approvals get / --gateway / --node <id|name|ip> |
Politique demandée, sources de politique de l’hôte, et résultat effectif. |
openclaw exec-policy show |
Vue fusionnée de la machine locale. |
openclaw exec-policy set / preset |
Synchroniser la politique locale demandée avec le fichier d’approbations de l’hôte local en une seule étape. |
Lorsqu’une portée locale demande host=node, exec-policy show rapporte cette
portée comme gérée par le Node à l’exécution au lieu de prétendre que le fichier local
d’approbations est la source de vérité.
Si l’UI de l’app compagnon n’est pas disponible, toute requête qui devrait
normalement afficher une invite est résolue par le fallback ask (par défaut : deny).
Où cela s’applique
Les approbations exec sont appliquées localement sur l’hôte d’exécution :
- Hôte Gateway → processus
openclawsur la machine Gateway. - Hôte Node → runner Node (app compagnon macOS ou hôte Node headless).
Modèle de confiance
- Les appelants authentifiés par la Gateway sont des opérateurs de confiance pour cette Gateway.
- Les Node appairés étendent cette capacité d’opérateur de confiance jusqu’à l’hôte Node.
- Les approbations exec réduisent le risque d’exécution accidentelle, mais ne constituent pas une frontière d’authentification par utilisateur.
- Les exécutions sur hôte Node approuvées lient le contexte d’exécution canonique : cwd canonique, argv exact, liaison env lorsqu’elle est présente, et chemin d’exécutable épinglé lorsque cela s’applique.
- 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érivant.
- La liaison de fichier est intentionnellement best-effort, 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 adossée à une approbation au lieu de prétendre offrir une couverture complète.
Séparation macOS
- Le service d’hôte Node transmet
system.runà l’app macOS via IPC local. - L’app macOS applique les approbations et exécute la commande dans le contexte UI.
Réglages et stockage
Les approbations vivent dans un fichier JSON local sur l’hôte d’exécution :
~/.openclaw/exec-approvals.json
Exemple de schéma :
{
"version": 1,
"socket": {
"path": "~/.openclaw/exec-approvals.sock",
"token": "base64url-token"
},
"defaults": {
"security": "deny",
"ask": "on-miss",
"askFallback": "deny",
"autoAllowSkills": false
},
"agents": {
"main": {
"security": "allowlist",
"ask": "on-miss",
"askFallback": "deny",
"autoAllowSkills": true,
"allowlist": [
{
"id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
"pattern": "~/Projects/**/bin/rg",
"lastUsedAt": 1737150000000,
"lastUsedCommand": "rg -n TODO",
"lastResolvedPath": "/Users/user/Projects/.../bin/rg"
}
]
}
}
}
Réglages de politique
exec.security
- `deny` — bloquer toutes les requêtes d’exec sur hôte.
- `allowlist` — autoriser uniquement les commandes présentes dans la liste d’autorisation.
- `full` — tout autoriser (équivalent à elevated).
exec.ask
- `off` — ne jamais afficher d’invite.
- `on-miss` — afficher une invite uniquement lorsqu’il n’y a pas de correspondance dans la liste d’autorisation.
- `always` — afficher une invite pour chaque commande. La confiance durable `allow-always` **ne** supprime **pas** les invites lorsque le mode ask effectif est `always`.
askFallback
Résolution lorsqu’une invite est requise mais qu’aucune UI n’est joignable.
deny— bloquer.allowlist— autoriser uniquement si la liste d’autorisation correspond.full— autoriser.
tools.exec.strictInlineEval
Lorsque `true`, OpenClaw traite les formes d’évaluation de code en ligne comme nécessitant une approbation
même si le binaire de l’interpréteur lui-même est dans la liste d’autorisation. Défense en profondeur
pour les chargeurs d’interpréteur qui ne correspondent pas proprement à un opérande
de fichier stable unique.
Exemples détectés par le mode strict :
python -cnode -e,node --eval,node -pruby -eperl -e,perl -Ephp -rlua -eosascript -e
En mode strict, ces commandes nécessitent toujours une approbation explicite, et
allow-always ne persiste pas automatiquement de nouvelles entrées de liste d’autorisation pour elles.
Mode YOLO (sans approbation)
Si vous voulez qu’exec 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.*) et la politique locale d’approbation de l’hôte dans
~/.openclaw/exec-approvals.json.
YOLO est le comportement hôte par défaut sauf si vous le resserrez explicitement :
| Couche | Réglage YOLO |
|---|---|
tools.exec.security |
full sur gateway/node |
tools.exec.ask |
off |
Hôte askFallback |
full |
tools.exec.host=autochoisit où exec s’exécute : sandbox lorsqu’il est disponible, sinon gateway.- YOLO choisit comment l’exec hôte est approuvé :
security=fullplusask=off. - En mode YOLO, OpenClaw n’ajoute pas de gate d’approbation heuristique séparée contre l’obfuscation de commande ni de couche de rejet preflight de script par-dessus la politique configurée d’exec hôte.
autone fait pas du routage gateway une dérogation gratuite depuis une session sandboxée. Une requêtehost=nodepar appel est autorisée depuisauto;host=gatewayn’est autorisé depuisautoque lorsqu’aucun runtime sandbox n’est actif. Pour une valeur par défaut stable non-auto, définisseztools.exec.hostou utilisez explicitement/exec host=....
Les fournisseurs soutenus par CLI qui exposent leur propre mode de permission non interactif
peuvent suivre cette politique. Claude CLI ajoute
--permission-mode bypassPermissions lorsque la politique exec demandée par OpenClaw
est YOLO. Remplacez ce comportement backend avec des arguments Claude explicites
sous agents.defaults.cliBackends.claude-cli.args / resumeArgs —
par exemple --permission-mode default, acceptEdits, ou
bypassPermissions.
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
```bash openclaw config set tools.exec.host gateway openclaw config set tools.exec.security full openclaw config set tools.exec.ask off openclaw gateway restart ``` ```bash openclaw approvals set --stdin <<'EOF' { version: 1, defaults: { security: "full", ask: "off", askFallback: "full" } } EOF ```Raccourci local
openclaw exec-policy preset yolo
Ce raccourci local met à jour à la fois :
- Le
tools.exec.host/security/asklocal. - Les valeurs par défaut locales de
~/.openclaw/exec-approvals.json.
Il est intentionnellement réservé au local. Pour modifier à distance les
approbations de l’hôte Gateway ou de l’hôte Node, utilisez openclaw approvals set --gateway ou
openclaw approvals set --node <id|name|ip>.
Hôte Node
Pour un hôte Node, appliquez à la place le même fichier d’approbations sur ce Node :
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
openclaw exec-policyne synchronise pas les approbations du Node.openclaw exec-policy set --host nodeest rejeté.- Les approbations exec du Node sont récupérées depuis le Node à l’exécution, donc les mises à jour ciblant le Node doivent utiliser
openclaw approvals --node ....
Raccourci session uniquement
/exec security=full ask=offne modifie que la session actuelle./elevated fullest un raccourci break-glass qui ignore aussi les approbations exec pour cette session.
Si le fichier d’approbations de l’hôte reste plus strict que la configuration, la politique de l’hôte la plus stricte l’emporte quand même.
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.
Les motifs peuvent être des globs de chemin binaire résolu ou des globs de nom de commande nu.
Les noms nus ne correspondent qu’aux commandes invoquées via PATH, donc rg peut correspondre à
/opt/homebrew/bin/rg lorsque la commande est rg, mais pas à ./rg ni
/tmp/rg. Utilisez un glob de chemin lorsque vous voulez faire confiance à un emplacement
binaire spécifique.
Les anciennes entrées agents.default sont migrées vers agents.main au chargement.
Les chaînes shell telles que echo ok && pwd exigent toujours que chaque segment de niveau supérieur
respecte les règles de la liste d’autorisation.
Exemples :
rg~/Projects/**/bin/peekaboo~/.local/bin/*/opt/homebrew/bin/rg
Chaque entrée de liste d’autorisation suit :
| Champ | Signification |
|---|---|
id |
UUID stable utilisé pour l’identité UI |
lastUsedAt |
Horodatage de la dernière utilisation |
lastUsedCommand |
Dernière commande ayant correspondu |
lastResolvedPath |
Dernier chemin binaire 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 autorisés sur les Node (Node macOS ou hôte
Node headless). Cela utilise skills.bins via la RPC Gateway pour récupérer la
liste des binaires de Skills. Désactivez cela si vous voulez des listes d’autorisation strictement manuelles.
Bins sûrs et transfert d’approbation
Pour les bins sûrs (chemin rapide stdin-only), les détails de liaison des interpréteurs, et la manière de transférer les invites d’approbation vers Slack/Discord/Telegram (ou de les exécuter comme clients d’approbation natifs), voir Exec approvals — avancé.
Édition dans la 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’UI 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 Node doivent annoncer system.execApprovals.get/set (app macOS ou
hôte Node headless). Si un Node n’annonce pas encore les approbations exec,
modifiez directement son ~/.openclaw/exec-approvals.json local.
CLI : openclaw approvals prend en charge l’édition côté gateway ou côté node — voir
CLI des approbations.
Flux d’approbation
Lorsqu’une invite est requise, la gateway diffuse
exec.approval.requested aux clients opérateur. La 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 Node.
Pour host=node, les requêtes d’approbation incluent un payload canonique
systemRunPlan. La gateway utilise ce plan comme contexte de
commande/cwd/session faisant autorité lors du transfert des requêtes
system.run approuvées.
C’est important pour la latence d’approbation asynchrone :
- Le chemin exec du Node prépare un plan canonique unique dès le départ.
- L’enregistrement d’approbation stocke ce plan et ses métadonnées de liaison.
- Une fois approuvé, l’appel
system.runfinal transmis 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, ousessionKeyaprès la création de la requête d’approbation, la gateway rejette l’exécution transmise comme incohérence d’approbation.
Événements système
Le cycle de vie exec apparaît comme des messages système :
Exec running(uniquement si la commande dépasse le seuil d’avis d’exécution).Exec finished.Exec denied.
Ils sont publiés dans la session de l’agent après que le Node a signalé l’événement.
Les approbations exec sur hôte Gateway émettent les mêmes événements de cycle de vie lorsque la
commande se termine (et éventuellement lorsqu’elle dure plus longtemps que le seuil).
Les exec contrôlés par approbation réutilisent l’id d’approbation comme runId dans ces
messages pour une corrélation facile.
Comportement lors d’un refus d’approbation
Lorsqu’une approbation exec 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. La raison du refus est transmise 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 d’une exécution réussie antérieure.
Implications
fullest puissant ; préférez les listes d’autorisation lorsque c’est possible.askvous garde dans la boucle tout en permettant des approbations rapides.- Les listes d’autorisation par agent empêchent les approbations d’un agent de fuiter vers les autres.
- Les approbations ne s’appliquent qu’aux requêtes exec sur hôte provenant d’expéditeurs autorisés. Les expéditeurs non autorisés ne peuvent pas émettre
/exec. /exec security=fullest une commodité au niveau session pour les opérateurs autorisés et ignore les approbations par conception. Pour bloquer strictement l’exec sur hôte, définissez la sécurité des approbations surdenyou refusez l’outilexecvia la politique d’outils.