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

Agent coordination

Bac à sable et outils multi-agents

Status: active

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.

Exemples de configuration

Exemple 1 : agent personnel et agent familial restreint
json
{  "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é
json
{  "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
json
{  "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
json
{  "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 :

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

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)

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

    Après (multi-agent)

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

    Exemples de restrictions d’outils

    Agent en lecture seule

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

    Exécution de commandes avec les outils de système de fichiers désactivés

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

    Communication uniquement

    json
    {  "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"

    Tests

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

  • Vérifier la résolution des agents

    bash
    openclaw agents list --bindings

  • Vérifier les conteneurs de bac à sable

    bash
    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

    bash
    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

    Was this useful?
    On this page

    On this page