Approbations d’exécution

Les approbations d’exécution sont le garde-fou de l’app compagnon / de l’hôte de nœud qui permet à un agent en bac à sable d’exécuter des commandes sur un hôte réel (gateway ou node). Un verrou de sécurité : les commandes ne sont autorisées que lorsque la politique + la liste d’autorisation + l’approbation utilisateur (facultative) concordent toutes. Les approbations d’exécution s’empilent par-dessus la politique d’outils et le contrôle d’élévation (sauf si l’élévation est définie sur full, ce qui ignore les approbations).

Pour une vue d’ensemble axée sur les modes de deny, allowlist, ask, auto, full, la correspondance Codex Guardian et les permissions du harnais ACPX, consultez Modes de permission.

Inspecter la politique effective

Quand une portée locale demande host=node, exec-policy show signale cette portée comme gérée par le nœud à l’exécution au lieu de prétendre que le fichier local d’approbations est la source de vérité.

Si l’interface de l’app compagnon n’est pas disponible, toute demande qui déclencherait normalement une invite est résolue par le repli ask (par défaut : deny).

Où cela s’applique

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).

Modèle de confiance

• Les appelants authentifiés auprès du Gateway sont des opérateurs approuvés pour ce Gateway.
• Les nœuds appairés étendent cette capacité d’opérateur approuvé à l’hôte de 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 ni une politique de système de fichiers en lecture seule.
• Une fois approuvée, une commande peut modifier des fichiers selon les permissions de système de fichiers de l’hôte ou du bac à sable sélectionné.
• 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 d’exécutable épinglé le cas échéant.
• Pour les scripts shell et les invocations directes de fichiers par interpréteur/environnement d’exécution, 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 qui a dérivé.
• La liaison de fichiers est volontairement au mieux, pas un modèle sémantique complet de chaque chemin de chargeur d’interpréteur/environnement d’exécution. Si le mode d’approbation ne peut pas identifier exactement un fichier local concret à lier, il refuse d’émettre 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 de nœud transmet system.run à l’app macOS via l’IPC local.
• L’app macOS applique les approbations et exécute la commande dans le contexte de l’interface utilisateur.

Paramètres et stockage

Les approbations résident dans un fichier JSON local sur l’hôte d’exécution. Quand OPENCLAW_STATE_DIR est défini, le fichier suit ce répertoire d’état ; sinon, il utilise le répertoire d’état OpenClaw par défaut :

$OPENCLAW_STATE_DIR/exec-approvals.json# otherwise~/.openclaw/exec-approvals.json

Le socket d’approbation par défaut suit la même racine : $OPENCLAW_STATE_DIR/exec-approvals.sock, ou ~/.openclaw/exec-approvals.sock lorsque la variable n’est pas définie.

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",          "source": "allow-always",          "commandText": "rg -n TODO",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Boutons de politique

tools.exec.mode

tools.exec.mode est la surface de politique normalisée privilégiée pour l’exécution hôte. Les valeurs sont :

• deny - bloque l’exécution hôte.
• allowlist - exécute uniquement les commandes figurant dans la liste d’autorisation sans demander.
• ask - utilise la politique de liste d’autorisation et demande en cas d’absence de correspondance.
• auto - utilise la politique de liste d’autorisation, exécute directement les correspondances déterministes et envoie les absences d’approbation au réviseur automatique natif d’OpenClaw avant de revenir à une voie d’approbation humaine.
• full - exécute l’hôte sans invites d’approbation.

Les anciens tools.exec.security / tools.exec.ask restent pris en charge et prévalent encore lorsqu’ils sont définis à une portée de session ou d’agent plus étroite.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Exemples interceptés par le mode strict :

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -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.

tools.exec.commandHighlighting

Ce paramètre ne modifie pas security, ask, la correspondance de liste d’autorisation, le comportement strict d’évaluation en ligne, la transmission des approbations ni l’exécution des commandes. Il peut être défini globalement sous tools.exec.commandHighlighting ou par agent sous agents.list[].tools.exec.commandHighlighting.

Mode YOLO (sans approbation)

Si vous voulez que l’exécution hôte s’exécute sans invites d’approbation, vous devez ouvrir les deux couches de politique : la politique d’exécution demandée dans la configuration OpenClaw (tools.exec.*) et la politique d’approbations locale à l’hôte dans le fichier d’approbations de l’hôte d’exécution.

OpenClaw définit par défaut les askFallback omis sur deny. Définissez explicitement askFallback de l’hôte sur full lorsqu’une invite d’approbation sans interface utilisateur doit se rabattre sur l’autorisation.

Les fournisseurs adossés à la CLI qui exposent leur propre mode de permission non interactif peuvent suivre cette politique. Claude CLI ajoute --permission-mode bypassPermissions lorsque la politique d’exécution effective d’OpenClaw est YOLO. Pour les sessions live Claude gérées par OpenClaw, la politique d’exécution effective d’OpenClaw fait autorité sur le mode de permission natif de Claude : YOLO normalise les lancements live en --permission-mode bypassPermissions, et une politique d’exécution effective restrictive normalise les lancements live en --permission-mode default, même si les arguments bruts du backend Claude spécifient un autre mode.

Si vous voulez une configuration plus conservatrice, resserrez la politique d’exécution OpenClaw à allowlist / on-miss ou deny.

Configuration persistante « ne jamais demander » de l’hôte Gateway

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

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 les deux éléments :

• tools.exec.host/security/ask local.
• Les valeurs par défaut du fichier local d’approbations, y compris askFallback: "full".

Il est volontairement uniquement local. Pour modifier à distance les approbations d’hôte Gateway ou d’hôte de nœud, utilisez openclaw approvals set --gateway ou openclaw approvals set --node <id|name|ip>.

Hôte de nœud

Pour un hôte de nœud, appliquez plutôt le même fichier d’approbations sur ce nœud :

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Raccourci limité à la session

• /exec security=full ask=off modifie uniquement la session actuelle.
• /elevated full est un raccourci de dernier recours qui ignore les approbations d’exécution uniquement lorsque la politique demandée et le fichier d’approbations de l’hôte se résolvent tous deux en security: "full" et ask: "off". Un fichier d’hôte plus strict, comme ask: "always", déclenche toujours une invite.

Si le fichier d’approbations de l’hôte reste plus strict que la configuration, la politique d’hôte plus stricte l’emporte toujours.

Liste d’autorisation (par agent)

Les listes d’autorisation sont par agent. S’il existe plusieurs agents, changez l’agent que vous modifiez dans l’app macOS. Les motifs sont des correspondances glob.

Les motifs peuvent être des globs de chemins binaires résolus ou des globs de noms de commande seuls. Les noms seuls 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 comme echo ok && pwd doivent toujours avoir chaque segment de premier niveau conforme aux règles de liste d’autorisation.

Exemples :

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Restreindre les arguments avec argPattern

Ajoutez argPattern lorsqu’une entrée de liste d’autorisation doit correspondre à un binaire et à une forme d’arguments spécifique. OpenClaw évalue l’expression régulière par rapport aux arguments de commande analysés, en excluant le jeton exécutable (argv[0]). Pour les entrées rédigées manuellement, les arguments sont joints avec un seul espace, donc ancrez le motif lorsque vous avez besoin d’une correspondance exacte.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

Cette entrée autorise python3 safe.py ; python3 other.py est un échec de correspondance de la liste d’autorisation. Si une entrée par chemin uniquement pour le même binaire est également présente, les arguments sans correspondance peuvent toujours se rabattre sur cette entrée par chemin uniquement. Omettez l’entrée par chemin uniquement lorsque l’objectif est de restreindre le binaire aux arguments déclarés.

Les entrées enregistrées par les flux d’approbation peuvent utiliser un format de séparateur interne pour la correspondance exacte de argv. Préférez l’interface utilisateur ou le flux d’approbation pour régénérer ces entrées au lieu de modifier manuellement la valeur encodée. Si OpenClaw ne peut pas analyser argv pour un segment de commande, les entrées avec argPattern ne correspondent pas.

Chaque entrée de liste d’autorisation prend en charge :

Autorisation automatique des CLI de Skills

Lorsque Autorisation automatique des CLI de Skills est activé, les exécutables référencés par des Skills connus sont traités comme autorisés 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.

Binaires sûrs et transfert d’approbation

Pour les binaires sûrs (le chemin rapide stdin uniquement), 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), consultez Approbations d’exécution - avancé.

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 (valeurs par défaut ou un agent), ajustez la politique, ajoutez/supprimez des motifs de liste d’autorisation, puis Enregistrer. L’interface utilisateur 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 nœud. Les nœuds 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 fichier d’approbations local.

CLI : openclaw approvals prend en charge la modification du gateway ou du nœud - voir CLI d’approbations.

Flux d’approbation

Lorsqu’une invite est requise, le gateway diffuse exec.approval.requested aux clients opérateurs. Control UI et l’app macOS la résolvent via exec.approval.resolve, puis le gateway transfère la requête approuvée à l’hôte de nœud.

Pour host=node, les requêtes d’approbation incluent une charge utile canonique systemRunPlan. Le gateway utilise ce plan comme contexte command/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 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é, l’appel final system.run transféré 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 sessionKey après la création de la demande d’approbation, le gateway rejette l’exécution transférée comme non-concordance d’approbation.

Événements système

Le cycle de vie d’exécution est exposé sous forme de messages système :

• Exec running (uniquement si la commande dépasse le seuil de notification d’exécution).
• Exec finished.

Ils sont publiés dans la session de l’agent après que le nœud a signalé l’événement. Les approbations d’exécution refusées sont terminales pour la commande hôte elle-même : la commande ne s’exécute pas. Pour les approbations asynchrones de l’agent principal avec une session d’origine, OpenClaw publie le refus dans cette session comme suivi interne afin que l’agent puisse cesser d’attendre la commande asynchrone et éviter une réparation de résultat manquant. S’il n’y a pas de session ou si la session ne peut pas être reprise, OpenClaw peut toujours signaler un refus concis à l’opérateur ou à la route de chat directe. Les refus pour les sessions de sous-agent ne sont pas renvoyés dans le sous-agent. Les approbations d’exécution hébergées par 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 en cas d’approbation refusée

Lorsqu’une approbation d’exécution asynchrone est refusée, OpenClaw traite la commande hôte comme terminale et fail-closed. Pour les sessions de l’agent principal, le refus est remis comme suivi de session interne qui indique à l’agent que la commande asynchrone ne s’est pas exécutée. Cela préserve la continuité de la transcription sans exposer de sortie de commande obsolète. Si la remise à la session est indisponible, OpenClaw se rabat sur un refus concis à l’opérateur ou au chat direct lorsqu’une route sûre existe.

Implications

• full est puissant ; préférez les listes d’autorisation lorsque c’est possible.
• ask vous 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 d’autres.
• Les approbations ne s’appliquent qu’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 les approbations par conception. 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.

Connexe