English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Agent coordination

Bac à sable et outils multi-agents

Status: active

Chaque agent dans une configuration multi-agent peut remplacer la politique globale de sandbox et d’outils. Cette page couvre la configuration par agent, les règles de précédence et des exemples.

Isolation en sandbox

Backends et modes — référence complète du sandbox.
Sandbox vs politique d’outils vs mode élevé

Déboguer « pourquoi est-ce bloqué ? »
Mode élevé

Exécution élevée pour les expéditeurs approuvés.

Exemples de configuration

Exemple 1 : agent personnel + 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": "[email protected]"        }      }    }  ]}

Résultat :

  • agent main : s’exécute sur l’hôte, accès complet aux outils.
  • agent family : s’exécute dans Docker (un conteneur par agent), uniquement read et les envois de messages dans la conversation actuelle.
Exemple 2 : agent de travail avec sandbox 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 de codage global + agent de messagerie uniquement
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

Résultat :

  • les agents par défaut obtiennent les outils de codage.
  • l’agent support est limité à la messagerie (+ outil Slack).
Exemple 3 : différents modes de sandbox par 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"]        }      }    ]  }}

Précédence de la configuration

Lorsque des configurations globales (agents.defaults.*) et propres à l’agent (agents.list[].*) existent toutes deux :

Configuration du sandbox

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

Code
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 d’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 sandbox

    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 précédence
    • Chaque niveau peut restreindre davantage les outils, mais ne peut pas réautoriser des outils refusés par des niveaux précédents.
    • 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 dans cette chaîne laisse l’exécution sans aucun outil appelable, OpenClaw s’arrête avant de soumettre l’invite au modèle. C’est intentionnel : un agent configuré avec un outil manquant comme agents.list[].tools.allow: ["query_db"] doit échouer clairement jusqu’à ce que le Plugin qui enregistre query_db soit activé, au lieu de continuer comme agent texte uniquement.

    Les politiques d’outils prennent en charge les raccourcis group:*, qui s’étendent à plusieurs outils. Consultez Groupes d’outils pour la liste complète.

    Les remplacements élevés par agent (agents.list[].tools.elevated) peuvent restreindre davantage l’exécution élevée pour des agents spécifiques. Consultez Mode élevé pour plus de détails.

    Migration depuis un agent unique

    Before (single agent)

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

    After (multi-agent)

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

    Exemples de restriction des outils

    Read-only agent

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

    Shell execution with filesystem tools disabled

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

    Communication-only

    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 bornée et assainie plutôt qu’un vidage brut de la transcription. Le rappel de l’assistant supprime les balises de raisonnement, l’échafaudage <relevant-memories>, les charges utiles XML d’appels d’outils en texte brut (y compris <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), l’échafaudage d’appels d’outils déclassé, les jetons de contrôle du modèle ASCII/pleine largeur divulgués, ainsi que le XML d’appels d’outils MiniMax mal formé avant la caviardisation/troncature.

    Piège courant : "non-main"

    Tests

    Après avoir configuré le sandbox et les outils multi-agents :

  • Check agent resolution

    bash
    openclaw agents list --bindings

  • Verify sandbox containers

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

  • Test tool restrictions

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

  • Monitor logs

    bash
    tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

    • Dépannage

    Agent not sandboxed despite `mode: 'all'`
    • Vérifiez s’il existe un agents.defaults.sandbox.mode global qui le remplace.
    • La configuration propre à l’agent est prioritaire ; définissez donc agents.list[].sandbox.mode: "all".
    Tools still available despite deny list
    • Vérifiez l’ordre de filtrage des outils : global → agent → sandbox → sous-agent.
    • Chaque niveau ne peut que restreindre davantage, pas réaccorder.
    • Vérifiez avec les logs : [tools] filtering tools for agent:${agentId}.
    Container not isolated per agent
    • Définissez scope: "agent" dans la configuration de sandbox propre à l’agent.
    • La valeur par défaut est "session", ce qui crée un conteneur par session.

    Articles connexes

    Was this useful?