OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Bac à sable, politique des outils et mode privilégié

Status: active

OpenClaw dispose de trois contrôles liés mais distincts :

  1. Bac à sable (agents.defaults.sandbox.* / agents.list[].sandbox.*) détermine où les outils s’exécutent (backend du bac à sable ou hôte).
  2. Politique des outils (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) détermine quels outils sont disponibles/autorisés.
  3. Mode privilégié (tools.elevated.*, agents.list[].tools.elevated.*) est une porte de sortie réservée à exec permettant une exécution hors du bac à sable lorsque vous êtes dans un bac à sable (gateway par défaut, ou node lorsque la cible d’exécution est configurée sur node).

Débogage rapide

Utilisez l’inspecteur pour voir ce qu’OpenClaw fait réellement :

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Il affiche :

  • le mode, la portée et l’accès à l’espace de travail effectifs du bac à sable
  • si la session est actuellement dans un bac à sable (principale ou non principale)
  • les autorisations/interdictions effectives des outils du bac à sable (et si elles proviennent de l’agent, de la configuration globale ou des valeurs par défaut)
  • les contrôles du mode privilégié et les chemins des clés à corriger

Bac à sable : où les outils s’exécutent

La mise en bac à sable est contrôlée par agents.defaults.sandbox.mode :

  • "off" : tout s’exécute sur l’hôte.
  • "non-main" : seules les sessions non principales sont placées dans un bac à sable (« surprise » fréquente pour les groupes/canaux).
  • "all" : tout est placé dans un bac à sable.

agents.defaults.sandbox.workspaceAccess contrôle ce que le bac à sable peut voir : "none", "ro" ou "rw".

Consultez Mise en bac à sable pour connaître la matrice complète (portée, montages de l’espace de travail, images).

Montages liés (vérification rapide de sécurité)

  • docker.binds perce le système de fichiers du bac à sable : tout ce que vous montez est visible dans le conteneur avec le mode défini (:ro ou :rw).
  • Le mode par défaut est lecture-écriture si vous l’omettez ; privilégiez :ro pour le code source et les secrets.
  • scope: "shared" ignore les montages propres à chaque agent (seuls les montages globaux s’appliquent).
  • OpenClaw valide deux fois les sources des montages liés : d’abord sur le chemin source normalisé, puis à nouveau après résolution via l’ancêtre existant le plus profond. Les échappements par un parent symbolique ne contournent pas les contrôles des chemins bloqués ou des racines autorisées.
  • Les chemins feuilles inexistants sont tout de même vérifiés de manière sûre. Si /workspace/alias-out/new-file est résolu, via un parent symbolique, vers un chemin bloqué ou hors des racines autorisées configurées, le montage lié est rejeté.
  • Lier /var/run/docker.sock donne de fait le contrôle de l’hôte au bac à sable ; ne le faites qu’intentionnellement.
  • L’accès à l’espace de travail (workspaceAccess) est indépendant des modes des montages liés.

Politique des outils : quels outils existent/peuvent être appelés

Plusieurs couches sont importantes :

  • Profil d’outils : tools.profile et agents.list[].tools.profile (liste d’autorisation de base)
  • Profil d’outils du fournisseur : tools.byProvider[provider].profile et agents.list[].tools.byProvider[provider].profile
  • Politique globale/par agent des outils : tools.allow/tools.deny et agents.list[].tools.allow/agents.list[].tools.deny
  • Politique des outils du fournisseur : tools.byProvider[provider].allow/deny et agents.list[].tools.byProvider[provider].allow/deny
  • Politique des outils du bac à sable (s’applique uniquement dans un bac à sable) : tools.sandbox.tools.allow/tools.sandbox.tools.deny et agents.list[].tools.sandbox.tools.*

Règles générales :

  • deny l’emporte toujours.
  • Si allow n’est pas vide, tout le reste est considéré comme bloqué.
  • La politique des outils constitue un blocage absolu : /exec ne peut pas contourner l’interdiction de l’outil exec.
  • La politique des outils filtre leur disponibilité par nom ; elle n’examine pas les effets secondaires dans exec. Si exec est autorisé, interdire write, edit ou apply_patch ne rend pas les commandes shell accessibles en lecture seule.
  • /exec ne modifie que les valeurs par défaut de la session pour les expéditeurs autorisés ; il n’accorde aucun accès aux outils.
  • Les clés d’outils du fournisseur acceptent soit provider (par exemple google-antigravity), soit provider/model (par exemple openai/gpt-5.4).
  • Les journaux du Gateway incluent des entrées d’audit agents/tool-policy lorsqu’une étape de la politique des outils supprime des outils ou qu’une politique des outils du bac à sable bloque un appel. Utilisez openclaw logs pour voir l’étiquette de la règle, la clé de configuration et les noms des outils concernés.

Groupes d’outils (raccourcis)

Les politiques des outils (globales, propres à l’agent ou au bac à sable) prennent en charge les entrées group:*, qui se développent en plusieurs outils :

json5
{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Groupes disponibles :

Groupe Outils
group:runtime exec, process, code_execution (bash est accepté comme alias de exec)
group:fs read, write, edit, apply_patch
group:sessions sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory memory_search, memory_get
group:web web_search, x_search, web_fetch
group:ui browser, canvas
group:automation heartbeat_respond, cron, gateway
group:messaging message
group:nodes nodes, computer
group:agents agents_list, get_goal, create_goal, update_goal, update_plan, skill_workshop
group:media image, image_generate, music_generate, video_generate, tts
group:openclaw la plupart des outils intégrés d’OpenClaw (à l’exception des primitives de système de fichiers et d’exécution read/write/edit/apply_patch/exec/process, de canvas et des plugins de fournisseur)
group:plugins tous les outils chargés appartenant aux plugins, y compris les serveurs MCP configurés exposés via bundle-mcp

Pour les agents en lecture seule, interdisez group:runtime ainsi que les outils qui modifient le système de fichiers, sauf si la politique du système de fichiers du bac à sable ou une limite d’hôte distincte impose la contrainte de lecture seule.

Pour les serveurs MCP placés dans un bac à sable, la politique des outils du bac à sable constitue un second contrôle d’autorisation. Si mcp.servers est configuré mais que les tours placés dans un bac à sable n’affichent que les outils intégrés, ajoutez bundle-mcp, group:plugins ou un nom/motif global d’outil MCP préfixé par le serveur, tel que outlook__send_mail ou outlook__*, à tools.sandbox.tools.alsoAllow, puis redémarrez/rechargez le Gateway et capturez de nouveau la liste des outils. Les motifs globaux de serveurs utilisent le préfixe de serveur MCP compatible avec les fournisseurs : les caractères autres que [A-Za-z0-9_-] deviennent -, les noms qui ne commencent pas par une lettre reçoivent le préfixe mcp-, et les préfixes longs ou en double peuvent être tronqués ou recevoir un suffixe.

openclaw doctor vérifie actuellement cette structure pour les serveurs gérés par OpenClaw dans mcp.servers. Les serveurs MCP chargés à partir des manifestes de plugins intégrés ou du fichier .mcp.json de Claude utilisent le même contrôle du bac à sable, mais ce diagnostic ne répertorie pas encore ces sources ; utilisez les mêmes entrées de liste d’autorisation si leurs outils disparaissent dans les tours placés dans un bac à sable.

Mode privilégié : « exécuter sur l’hôte » réservé à exec

Le mode privilégié n’accorde pas d’outils supplémentaires ; il affecte uniquement exec.

  • Si vous êtes dans un bac à sable, /elevated on (ou exec avec elevated: true) s’exécute hors du bac à sable (des approbations peuvent toujours s’appliquer).
  • Utilisez /elevated full pour ignorer les approbations d’exécution pendant la session.
  • Si vous exécutez déjà directement sur l’hôte, le mode privilégié est de fait sans effet (les contrôles continuent de s’appliquer).
  • Le mode privilégié n’est pas limité à un Skill et ne contourne pas les autorisations/interdictions d’outils.
  • Le mode privilégié n’accorde pas de contournements arbitraires entre hôtes à partir de host=auto ; il suit les règles normales de cible d’exécution et ne conserve node que lorsque la cible configurée/de session est déjà node.
  • /exec est distinct du mode privilégié. Il ajuste uniquement les valeurs par défaut d’exécution propres à la session pour les expéditeurs autorisés.

Contrôles :

  • Activation : tools.elevated.enabled (et éventuellement agents.list[].tools.elevated.enabled)
  • Listes d’expéditeurs autorisés : tools.elevated.allowFrom.<provider> (et éventuellement agents.list[].tools.elevated.allowFrom.<provider>)

Consultez Mode privilégié.

Correctifs courants en cas d’« enfermement dans le bac à sable »

« Outil X bloqué par la politique des outils du bac à sable »

Clés à corriger (choisissez une option) :

  • Désactivez le bac à sable : agents.defaults.sandbox.mode=off (ou, par agent, agents.list[].sandbox.mode=off)
  • Autorisez l’outil dans le bac à sable :
    • retirez-le de tools.sandbox.tools.deny (ou, par agent, de agents.list[].tools.sandbox.tools.deny)
    • ou ajoutez-le à tools.sandbox.tools.allow (ou à la liste d’autorisation par agent)
  • Consultez openclaw logs pour trouver l’entrée agents/tool-policy. Elle enregistre le mode du bac à sable et indique si la règle d’autorisation ou d’interdiction a bloqué l’outil.

« Je pensais qu’il s’agissait de la session principale ; pourquoi est-elle dans un bac à sable ? »

En mode "non-main", les clés de groupe/canal ne sont pas principales. Utilisez la clé de la session principale (affichée par sandbox explain) ou passez au mode "off".

Voir aussi

Was this useful?
On this page

On this page