Bac à sable et outils multi-agents

Chaque agent d’une configuration multi-agent peut remplacer les politiques globales de bac à sable et d’outils. Cette page présente la configuration par agent, les règles de priorité et des exemples.

Mise en bac à sable

Moteurs et modes — référence complète sur le bac à sable.

Bac à sable, politique d’outils et mode privilégié

Diagnostiquer « pourquoi ceci est-il bloqué ? »

Mode privilégié

Exécution privilégiée pour les expéditeurs de confiance.

L’authentification est limitée à chaque agent : chaque agent possède son propre stockage d’authentification agentDir dans ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Ne réutilisez jamais un même agentDir pour plusieurs agents. Les agents peuvent consulter les profils d’authentification de l’agent principal/par défaut lorsqu’ils ne disposent pas d’un profil local, mais les jetons d’actualisation OAuth ne sont pas clonés dans les stockages des agents secondaires. Si vous copiez manuellement des identifiants, copiez uniquement les profils statiques portables api_key ou token.

Exemples de configuration

Exemple 1 : agent personnel et agent familial restreint

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}

Résultat :

Agent main : s’exécute sur l’hôte avec un accès complet aux outils.
Agent family : s’exécute dans Docker (un conteneur par agent), avec uniquement read et l’envoi de messages dans la conversation actuelle.

Exemple 2 : agent professionnel avec bac à sable partagé

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}

Exemple 2b : profil global de programmation et agent limité à la messagerie

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Résultat :

Les agents par défaut disposent des outils de programmation.
L’agent support est limité à la messagerie, avec en plus l’outil Slack.

Exemple 3 : différents modes de bac à sable selon l’agent

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

Priorité de la configuration

Lorsque des configurations globales (agents.defaults.*) et propres à un agent (agents.list[].*) coexistent :

Configuration du bac à sable

Les paramètres propres à l’agent remplacent les paramètres globaux :

agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.list[].sandbox.{docker,browser,prune}.* remplace agents.defaults.sandbox.{docker,browser,prune}.* pour cet agent (ces paramètres sont ignorés lorsque la portée du bac à sable est résolue en "shared").

Restrictions des outils

L’ordre de filtrage est le suivant :

Profil d’outils

tools.profile ou agents.list[].tools.profile.

Profil d’outils du fournisseur

tools.byProvider[provider].profile ou agents.list[].tools.byProvider[provider].profile.

Politique globale d’outils

tools.allow / tools.deny.

Politique d’outils du fournisseur

tools.byProvider[provider].allow/deny.

Politique d’outils propre à l’agent

agents.list[].tools.allow/deny.

Politique de fournisseur de l’agent

agents.list[].tools.byProvider[provider].allow/deny.

Politique d’outils du bac à sable

tools.sandbox.tools ou agents.list[].tools.sandbox.tools.

Politique d’outils des sous-agents

tools.subagents.tools, le cas échéant.

Règles de priorité

Chaque niveau peut restreindre davantage les outils, mais ne peut pas réautoriser des outils refusés à un niveau antérieur.
Si agents.list[].tools.sandbox.tools est défini, il remplace tools.sandbox.tools pour cet agent.
Si agents.list[].tools.profile est défini, il remplace tools.profile pour cet agent.
Les clés d’outils de fournisseur acceptent soit provider (par exemple google-antigravity), soit provider/model (par exemple openai/gpt-5.4).

Comportement d’une liste d’autorisation vide

Si une liste d’autorisation explicite de cette chaîne ne laisse aucun outil appelable pour l’exécution, OpenClaw s’arrête avant de soumettre l’invite au modèle. Ce comportement est intentionnel : un agent configuré avec un outil manquant, comme agents.list[].tools.allow: ["query_db"], doit échouer de manière explicite jusqu’à l’activation du Plugin qui enregistre query_db, et non continuer comme un agent limité au texte.

Les politiques d’outils prennent en charge les raccourcis group:*, qui sont développés en plusieurs outils. Consultez les groupes d’outils pour obtenir la liste complète. Les remplacements du mode privilégié par agent (agents.list[].tools.elevated) peuvent restreindre davantage l’exécution privilégiée pour certains agents. Consultez la section Mode privilégié pour plus de détails.

Migration depuis un agent unique

Avant (agent unique)
Après (multi-agent)

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}

Les anciennes clés de configuration agents.defaults.*/agents.list[].* (comme sandbox.perSession, agentRuntime, embeddedPi) sont migrées par openclaw doctor ; utilisez désormais de préférence agents.defaults avec agents.list.

Exemples de restrictions d’outils

Agent en lecture seule
Exécution de commandes avec les outils de système de fichiers désactivés
Communication uniquement

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}

Cette politique désactive les outils de système de fichiers d’OpenClaw, mais exec reste un interpréteur de commandes et peut écrire des fichiers partout où le système de fichiers de l’hôte ou du bac à sable sélectionné l’autorise. Pour un agent en lecture seule, refusez exec et process, ou associez l’accès à l’interpréteur de commandes à des contrôles du système de fichiers du bac à sable, comme agents.defaults.sandbox.workspaceAccess: "ro" ou "none".

{
  "tools": {
    "sessions": { "visibility": "tree" },
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}

Dans ce profil, sessions_history renvoie toujours une vue de rappel limitée et assainie plutôt qu’une exportation brute de la transcription. Le rappel de l’assistant supprime les balises de raisonnement, la structure <relevant-memories>, les charges utiles XML en texte brut des appels d’outils (notamment <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> et les blocs d’appels d’outils tronqués), les structures d’appels d’outils dégradées, les jetons de contrôle du modèle ASCII ou pleine chasse divulgués, ainsi que le XML d’appels d’outils MiniMax mal formé, avant la rédaction et la troncature.

Piège courant : `"non-main"`

agents.defaults.sandbox.mode: "non-main" compare la clé de session à celle de la session principale (toujours "main" ; session.mainKey n’est pas configurable par l’utilisateur, et OpenClaw avertit puis ignore toute autre valeur), et non à l’identifiant de l’agent. Les sessions de groupe ou de canal obtiennent toujours leurs propres clés ; elles sont donc considérées comme non principales et placées dans un bac à sable. Si vous souhaitez qu’un agent ne soit jamais placé dans un bac à sable, définissez agents.list[].sandbox.mode: "off".

Tests

Après avoir configuré le bac à sable et les outils pour plusieurs agents :

Vérifier la résolution des agents

openclaw agents list --bindings

Vérifier les conteneurs de bac à sable

docker ps --filter "name=openclaw-sbx-"

Tester les restrictions d’outils

Envoyez un message nécessitant des outils restreints.
Vérifiez que l’agent ne peut pas utiliser les outils refusés.

Surveiller les journaux

openclaw logs --follow | grep -E "routing|sandbox|tools"

Résolution des problèmes

L’agent n’est pas placé dans un bac à sable malgré `mode: 'all'`

Vérifiez si un paramètre global agents.defaults.sandbox.mode le remplace.
La configuration propre à l’agent est prioritaire ; définissez donc agents.list[].sandbox.mode: "all".

Outils toujours disponibles malgré la liste de refus

Consultez l’ordre de filtrage complet : profil → profil du fournisseur → politique globale → politique du fournisseur → politique de l’agent → politique du fournisseur de l’agent → bac à sable → sous-agent.
Chaque niveau peut uniquement appliquer des restrictions supplémentaires, sans réaccorder d’autorisations.
Consultez Bac à sable, politique des outils et mode élevé pour un débogage étape par étape.

Conteneur non isolé pour chaque agent

La valeur par défaut de scope est "agent" (un conteneur par identifiant d’agent).
Définissez scope: "session" pour utiliser un conteneur par session, ou scope: "shared" pour réutiliser un même conteneur entre plusieurs agents.

Rubriques connexes

Mode élevé
Routage multi-agent
Configuration du bac à sable
Bac à sable, politique des outils et mode élevé — débogage de « pourquoi ceci est-il bloqué ? »
Mise en bac à sable — référence complète du bac à sable (modes, portées, backends, images)
Gestion des sessions

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Bac à sable et outils multi-agents

Mise en bac à sable

Bac à sable, politique d’outils et mode privilégié

Mode privilégié

Exemples de configuration

Priorité de la configuration

Configuration du bac à sable

Restrictions des outils

Migration depuis un agent unique

Exemples de restrictions d’outils

Piège courant : `"non-main"`

Tests

Résolution des problèmes

Rubriques connexes

Mise en bac à sable

Bac à sable, politique d’outils et mode privilégié

Mode privilégié

​Exemples de configuration

​Priorité de la configuration

​Configuration du bac à sable

​Restrictions des outils

​Migration depuis un agent unique

​Exemples de restrictions d’outils

​Piège courant : "non-main"

​Tests

​Résolution des problèmes

​Rubriques connexes

Exemples de configuration

Priorité de la configuration

Configuration du bac à sable

Restrictions des outils

Migration depuis un agent unique

Exemples de restrictions d’outils

Piège courant : `"non-main"`

Tests

Résolution des problèmes

Rubriques connexes