Tool d'exécution

Exécutez des commandes shell dans l’espace de travail. execOpenClaw est une surface shell mutante : les commandes peuvent créer, modifier ou supprimer des fichiers partout où le système de fichiers de l’hôte ou du bac à sable sélectionné le permet. La désactivation des outils de système de fichiers d’OpenClaw tels que write, edit ou apply_patch ne rend pas exec en lecture seule.

Prend en charge l’exécution en premier plan et en arrière-plan via process. Si process n’est pas autorisé, exec s’exécute de manière synchrone et ignore yieldMs/background. Les sessions d’arrière-plan sont délimitées par agent ; process ne voit que les sessions du même agent.

Paramètres

Commande shell à exécuter. Répertoire de travail pour la commande. Remplacements d'environnement clé/valeur fusionnés par-dessus l'environnement hérité. Mettre automatiquement la commande en arrière-plan après ce délai (ms). Mettre la commande en arrière-plan immédiatement au lieu d'attendre `yieldMs`. Remplacer le délai d'attente exec configuré pour cet appel. Définissez `timeout: 0` uniquement lorsque la commande doit s'exécuter sans le délai d'attente du processus exec. Exécuter dans un pseudo-terminal lorsque disponible. À utiliser pour les interfaces de ligne de commande (CLI) TTY uniquement, les agents de codage et les interfaces utilisateur de terminal. Où exécuter. `auto` correspond à `sandbox` lorsqu'un runtime de bac à sable est actif et `gateway` sinon. Ignoré pour les appels de tool normaux. La sécurité `gateway` / `node` est contrôlée par `tools.exec.security` et `~/.openclaw/exec-approvals.json` ; le mode élevé peut forcer `security=full` uniquement lorsque l'opérateur accorde explicitement un accès élevé. Comportement de l'invite d'approbation pour l'exécution `gateway` / `node`. ID/nom du nœud lors de `host=node`. Demander le mode élevé — échapper du bac à sable vers le chemin d'hôte configuré. `security=full` est forcé uniquement lorsque la résolution élevée donne `full`.

Notes :

host par défaut est auto : bac à sable si le runtime du bac à sable est actif pour la session, sinon passerelle.
host n’accepte que auto, sandbox, gateway ou node. Ce n’est pas un sélecteur de nom d’hôte ; les valeurs ressemblant à des noms d’hôte sont rejetées avant l’exécution de la commande.
auto est la stratégie de routage par défaut, pas un caractère générique. host=node par appel est autorisé depuis auto ; host=gateway par appel n’est autorisé que lorsqu’aucun runtime de bac à sable n’est actif.
tools.exec.mode est le paramètre de stratégie normalisé. Les valeurs sont deny, allowlist, ask, auto et full. auto exécute directement les correspondances déterministes de liste blanche/binaire sécurisé et achemine chaque cas restant d’approbation d’exécution via l’auto-réviseur natif d’OpenClaw avant de demander à un humain. ask / ask=always demande encore à un humain à chaque fois.
Sans configuration supplémentaire, host=auto fonctionne toujours “tel quel” : l’absence de bac à sable (sandbox) signifie qu’il est résolu en gateway ; un bac à sable actif signifie qu’il reste dans le bac à sable.
elevated s’échappe du bac à sable vers le chemin d’hôte configuré : gateway par défaut, ou node lorsque tools.exec.host=node (ou que la session par défaut est host=node). Il n’est disponible que lorsque l’accès élevé est activé pour la session/provider actuelle.
Les approbations gateway/node sont contrôlées par ~/.openclaw/exec-approvals.json.
node nécessite un nœud jumelé (application compagnon ou hôte de nœud sans interface).
Si plusieurs nœuds sont disponibles, définissez exec.node ou tools.exec.node pour en sélectionner un.
exec host=node est le seul chemin d’exécution de shell pour les nœuds ; le wrapper obsolète nodes.run a été supprimé.
timeout s’applique à l’exécution system.run au premier plan, en arrière-plan, yieldMs, via la passerelle, dans le bac à sable et sur le nœud. Si omis, OpenClaw utilise tools.exec.timeoutSec ; timeout: 0 explicite désactive le délai d’expiration du processus d’exécution pour cet appel.
Sur les hôtes non-Windows, exec utilise SHELL lorsqu’il est défini ; si SHELL est fish, il préfère bash (ou sh) depuis PATH pour éviter les scripts incompatibles avec fish, puis revient à SHELL si aucun n’existe.
Sur les hôtes Windows, exec privilégie la découverte de PowerShell 7 (pwsh) (Program Files, ProgramW6432, puis PATH), puis revient à Windows PowerShell 5.1.
Sur les hôtes de passerelle non-Windows, les commandes exec bash et zsh utilisent un instantané de démarrage. OpenClaw capture les alias/fonctions sourçables et un petit ensemble d’environnement sécurisé à partir des fichiers de démarrage du shell dans $OPENCLAW_STATE_DIR/cache/shell-snapshots/, puis source cet instantané avant chaque commande exec. Les variables ressemblant à des secrets sont exclues ; l’exécution dans le bac à sable et le nœud n’utilise pas cet instantané. Définissez OPENCLAW_EXEC_SHELL_SNAPSHOT=0 dans l’environnement de processus du Gateway pour désactiver ce chemin d’instantané.
L’exécution sur l’hôte (gateway/node) rejette env.PATH et les remplacements du chargeur (LD_*/DYLD_*) pour empêcher le détournement de binaire ou l’injection de code.
OpenClaw définit OPENCLAW_SHELL=exec dans l’environnement de la commande générée (y compris l’exécution PTY et bac à sable) afin que les règles de shell/profil puissent détecter le contexte de l’outil exec.
openclaw channels login est bloqué depuis exec car il s’agit d’un flux d’authentification de canal interactif ; exécutez-le dans un terminal sur l’hôte de passerelle, ou utilisez l’outil de connexion natif du canal depuis le chat lorsqu’il en existe un.
Important : la mise en bac à sable est désactivée par défaut. Si la mise en bac à sable est désactivée, host=auto implicite est résolu en gateway. host=sandbox explicite échoue toujours de manière fermée au lieu de s’exécuter silencieusement sur l’hôte de passerelle. Activez la mise en bac à sable ou utilisez host=gateway avec des approbations.
Les vérifications préalables de script (pour les erreurs courantes de syntaxe de shell Python/Node) n’inspectent que les fichiers à l’intérieur de la limite effective workdir. Si un chemin de script est résolu à l’extérieur de workdir, la vérification préalable est ignorée pour ce fichier.
Pour les travaux de longue durée qui commencent maintenant, lancez-les une seule fois et comptez sur le réveil automatique à l’achèvement lorsqu’il est activé et que la commande émet une sortie ou échoue. Utilisez process pour les journaux, le statut, la saisie ou l’intervention ; n’émulez pas la planification avec des boucles de sleep, des boucles de timeout ou des sondages répétés.
Pour le travail qui doit se produire plus tard ou selon une planification, utilisez cron au lieu des modèles de sleep/délai exec.

Config

tools.exec.notifyOnExit (par défaut : true) : lorsque true, les sessions d’exécution en arrière-plan mettent en file d’attente un événement système et demandent un signal de présence à la sortie.
tools.exec.approvalRunningNoticeMs (par défaut : 10000) : émet une seule notification « running » lorsqu’une exécution soumise à approbation dure plus longtemps que cette durée (0 désactive).
tools.exec.timeoutSec (par défaut : 1800) : délai d’expiration d’exécution par commande en secondes. timeout par appel le remplace ; timeout: 0 par appel désactive le délai d’expiration du processus d’exécution.
tools.exec.host (par défaut : auto ; résout en sandbox lorsque le runtime sandbox est actif, gateway sinon)
tools.exec.security (par défaut : deny pour sandbox, full pour passerelle + nœud si non défini)
tools.exec.ask (par défaut : off)
L’exécution hôte sans approbation est le paramètre par défaut pour la passerelle et le nœud. Si vous souhaitez le comportement d’approbations/liste blanche, serrez à la fois tools.exec.* et ~/.openclaw/exec-approvals.json de l’hôte ; voir Exec approvals.
YOLO provient des paramètres par défaut de la stratégie hôte (security=full, ask=off), et non de host=auto. Si vous souhaitez forcer le routage via la passerelle ou le nœud, définissez tools.exec.host ou utilisez /exec host=....
En mode security=full plus ask=off, l’exécution hôte suit directement la stratégie configurée ; il n’y a pas de couche supplémentaire de préfiltrage heuristique d’obfuscation de commande ou de rejet préalable de script.
tools.exec.node (par défaut : non défini)
tools.exec.strictInlineEval (par défaut : false) : lorsque true, les formulaires d’évaluation de l’interpréteur en ligne tels que python -c, node -e, ruby -e, perl -e, php -r, lua -e et osascript -e nécessitent une approbation du réviseur ou explicite. Dans mode=auto, le chemin d’approbation exec normal peut laisser l’auto-réviseur natif autoriser une commande ponctuelle à faible risque évident ; les appels directs system.run du nœud hôte nécessitent toujours une approbation explicite car ils ne peuvent pas transmettre la commande à un circuit d’approbation humaine. Si le réviseur le demande, la demande est transmise à un humain. allow-always peut toujours rendre persistantes les invocations bénignes d’interpréteur/de script, mais les formulaires d’évaluation en ligne ne deviennent pas des règles d’autorisation durables.
tools.exec.commandHighlighting (par défaut : false) : lorsque true, les invites d’approbation peuvent mettre en surbrillance les étendues de commande dérivées de l’analyseur dans le texte de commande. Définissez sur true globalement ou par agent pour activer la mise en surbrillance du texte de commande sans modifier la politique d’approbation exec.
tools.exec.pathPrepend : liste des répertoires à ajouter au début de PATH pour les exécutions exec (passerelle + sandbox uniquement).
tools.exec.safeBins : fichiers binaires sécurisés stdin uniquement qui peuvent s’exécuter sans entrées de liste d’autorisation explicites. Pour plus de détails sur le comportement, consultez Safe bins.
tools.exec.safeBinTrustedDirs : répertoires explicites supplémentaires approuvés pour les vérifications de chemin safeBins. Les entrées PATH ne sont jamais automatiquement approuvées. Les valeurs par défaut intégrées sont /bin et /usr/bin.
tools.exec.safeBinProfiles : stratégie argv personnalisée optionnelle par fichier binaire sécurisé (minPositional, maxPositional, allowedValueFlags, deniedFlags).

Exemple :

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

Gestion du PATH

host=gateway : fusionne votre PATH de shell de connexion dans l’environnement exec. Les remplacements de env.PATH sont rejetés pour l’exécution sur l’hôte. Le démon lui-même s’exécute toujours avec un PATH minimal :
- macOS : macOS/opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- Linux : Linux/usr/local/bin, /usr/bin, /bin
  - Pour empêcher la configuration du shell utilisateur (comme ~/.zshenv ou /etc/zshenv) de remplacer les chemins prioritaires lors du démarrage, les entrées tools.exec.pathPrepend sont ajoutées de manière sécurisée au PATH final à l’intérieur de la commande shell juste avant l’exécution.
host=sandbox : exécute sh -lc (shell de connexion) à l’intérieur du conteneur, donc /etc/profile peut réinitialiser PATHOpenClaw. OpenClaw préfixe env.PATH après le chargement du profil via une variable d’environnement interne (pas d’interpolation de shell) ; tools.exec.pathPrepend s’applique ici aussi.
host=node : seuls les remplacements d’environnement non bloqués que vous envoyez sont transmis au nœud. Les remplacements de env.PATH sont rejetés pour l’exécution sur l’hôte et ignorés par les hôtes de nœud. Si vous avez besoin d’entrées PATH supplémentaires sur un nœud, configurez l’environnement du service hôte de nœud (systemd/launchd) ou installez les outils dans des emplacements standard.

Liaison de nœud par agent (utilisez l’index de la liste des agents dans la configuration) :

openclaw config get agents.list
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

Interface de contrôle : l’onglet Nœuds inclut un petit panneau “Liaison de nœud Exec” pour les mêmes paramètres.

Remplacements de session (`/exec`)

Utilisez /exec pour définir des valeurs par défaut par session pour host, security, ask et node. Envoyez /exec sans arguments pour afficher les valeurs actuelles.

Exemple :

/exec host=auto security=allowlist ask=on-miss node=mac-1

Modèle d’autorisation

/exec n’est honoré que pour les expéditeurs autorisés (listes d’autorisation/appariement de channel plus commands.useAccessGroups). Il met à jour uniquement l’état de session et n’écrit pas la configuration. Les expéditeurs de channel externes autorisés peuvent définir ces valeurs par défaut de session. Les clients internes de la gateway/webchat ont besoin de operator.admin pour les rendre persistantes. Pour désactiver définitivement exec, refusez-le via la stratégie de tool (tools.deny: ["exec"] ou par agent). Les approbations de l’hôte s’appliquent toujours, sauf si vous définissez explicitement security=full et ask=off.

Approbations Exec (application compagnon / hôte de nœud)

Les agents en bac à sable (Sandboxed) peuvent exiger une approbation par requête avant que exec ne s’exécute sur la passerelle ou l’hôte de nœud. Voir Exec approvals pour la stratégie, la liste d’autorisation et le flux de l’interface utilisateur.

Lorsque des approbations sont requises, l’outil exec renvoie immédiatement status: "approval-pending" et un identifiant d’approbation. Une fois approuvée (ou refusée / expirée), le Gateway émet des événements système de progression et d’exécution de commande uniquement pour les exécutions approuvées (Exec running / Exec finished). Les approbations refusées ou expirées sont finales et ne réveillent pas la session de l’agent avec un événement système de refus. Sur les canaux avec des cartes/boutons d’approbation natifs, l’agent doit s’appuyer d’abord sur cette interface utilisateur native et inclure uniquement une commande manuelle /approve lorsque le résultat de l’outil indique explicitement que les approbations par chat sont indisponibles ou que l’approbation manuelle est le seul chemin possible.

Liste d’autorisation + bins sûrs

L’application manuelle de la liste d’autorisation correspond aux globs de chemins binaires résolus et aux globs de noms de commande nus. 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 ou /tmp/rg. Lorsque security=allowlist, les commandes shell sont automatiquement autorisées uniquement si chaque segment de pipeline est sur la liste d’autorisation ou un binaire sécurisé. Les chaînes (;, &&, ||) et les redirections sont rejetées en mode liste d’autorisation, sauf si chaque segment de niveau supérieur satisfait à la liste d’autorisation (y compris les bins sûrs). Les redirections restent non prises en charge. La confiance durable allow-always ne contourne pas cette règle : une commande chaînée exige toujours que chaque segment de niveau supérieur corresponde.

autoAllowSkills est un chemin de commodité distinct dans les approbations d’exécution. Ce n’est pas la même chose que les entrées manuelles de la liste d’autorisation de chemins. Pour une confiance explicite stricte, gardez autoAllowSkills désactivé.

Utilisez les deux contrôles pour des tâches différentes :

tools.exec.safeBins : petits filtres de flux stdin uniquement.
tools.exec.safeBinTrustedDirs : rép supplémentaires de confiance explicite pour les chemins d’exécutables de bins sûrs.
tools.exec.safeBinProfiles : stratégie argv explicite pour les bins sûrs personnalisés.
allowlist : confiance explicite pour les chemins d’exécutables.

Ne traitez pas safeBins comme une liste d’autorisation générique, et n’ajoutez pas de binaires d’interpréteur/d’exécution (par exemple python3, node, ruby, bash). Si vous en avez besoin, utilisez des entrées de liste d’autorisation explicites et gardez les invites d’approbation activées. openclaw security audit avertit lorsque les entrées safeBins d’interpréteur/d’exécution manquent de profils explicites, et openclaw doctor --fix peut générer des entrées safeBinProfiles personnalisées manquantes. openclaw security audit et openclaw doctor avertissent également lorsque vous ajoutez explicitement des binaires à comportement étendu tels que jq à safeBins. Si vous autorisez explicitement les interpréteurs, activez tools.exec.strictInlineEval afin que les formulaires d’évaluation de code en ligne nécessitent toujours un examen ou une approbation explicite.

Pour les détails complets de la politique et des exemples, consultez Approbations Exec et Bins sûrs versus liste d’autorisation.

Exemples

Premier plan :

{ "tool": "exec", "command": "ls -la" }

Arrière-plan + interrogation :

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

L’interrogation est destinée au statut à la demande, et non aux boucles d’attente. Si le réveil automatique à l’achèvement est activé, la commande peut réveiller la session lorsqu’elle émet une sortie ou échoue.

Envoyer des touches (style tmux) :

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

Soumettre (envoyer CR uniquement) :

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

Coller (entre crochets par défaut) :

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch

apply_patch est un sous-outil de exec pour les modifications multi-fichiers structurées. Il est activé par défaut pour les modèles OpenAI et OpenAI Codex. Utilisez la configuration uniquement lorsque vous souhaitez le désactiver ou le restreindre à des modèles spécifiques :

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}