Agent coordination

Bac à sable et outils multi-agents

Chaque agent dans une configuration multi-agent peut remplacer la politique globale de bac à sable et d’outils. Cette page couvre la configuration par agent, les règles de priorité et des exemples.

Bac à sable

Backends et modes — référence complète du bac à sable.

Bac à sable vs politique des outils vs mode élevé

Déboguer « pourquoi ceci est-il bloqué ? »

Mode élevé

Exécution élevée pour les expéditeurs de confiance.

Exemples de configuration

Exemple 1 : agent personnel + 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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "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 l’outil read.

Exemple 2 : agent de travail 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 de codage global + agent limité à la messagerie

{
  "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 : modes de bac à sable différents par 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 configuration

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

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.*

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 bac à sable

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

Politique d’outils de sous-agent

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 à 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 ne laisse aucun outil appelable à l’exécution, OpenClaw s’arrête avant de soumettre le prompt au modèle. C’est intentionnel : un agent configuré avec un outil manquant tel que 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 uniquement textuel.

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

Les remplacements de mode élevé 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

Avant (agent unique)

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

Après (multi-agent)

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

Exemples de restrictions d’outils

Agent en lecture seule

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

Exécution sûre (aucune modification de fichiers)

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

Communication uniquement

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

sessions_history dans ce profil renvoie toujours une vue de rappel limitée et assainie plutôt qu’un vidage brut de transcription. Le rappel de l’assistant retire les balises de réflexion, 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 rétrogradé, les jetons de contrôle de modèle ASCII/pleine chasse divulgués et le XML d’appels d’outils MiniMax mal formé avant la rédaction/troncature.

Piège courant : "non-main"

Tests

Après avoir configuré le bac à sable et les outils multi-agent :

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

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

Dépannage

Agent non placé en bac à sable malgré `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".

Outils toujours disponibles malgré la liste de refus

Vérifiez l’ordre de filtrage des outils : global → agent → bac à sable → sous-agent.
Chaque niveau peut seulement restreindre davantage, pas réautoriser.
Vérifiez avec les journaux : [tools] filtering tools for agent:${agentId}.

Conteneur non isolé par agent

Définissez scope: "agent" dans la configuration de bac à sable propre à l’agent.
La valeur par défaut est "session", qui crée un conteneur par session.

Connexe

Mode élevé
Routage multi-agent
Configuration du bac à sable
Bac à sable vs politique des outils vs 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

# Exemples de configuration

# Priorité de configuration

# Configuration du bac à sable

# Restrictions d’outils

Profil d’outils

Profil d’outils du fournisseur

Politique globale d’outils

Politique d’outils du fournisseur

Politique d’outils propre à l’agent

Politique de fournisseur de l’agent

Politique d’outils du bac à sable

Politique d’outils de sous-agent

# Migration depuis un agent unique

Avant (agent unique)

Après (multi-agent)

# Exemples de restrictions d’outils

Agent en lecture seule

Exécution sûre (aucune modification de fichiers)

Communication uniquement

# Piège courant : "non-main"

# Tests

Vérifier la résolution des agents

Vérifier les conteneurs de bac à sable

Tester les restrictions d’outils

Surveiller les journaux

# Dépannage

# Connexe

Exemples de configuration

Priorité de configuration

Configuration du bac à sable

Restrictions d’outils

Migration depuis un agent unique

Exemples de restrictions d’outils

Piège courant : "non-main"

Tests

Dépannage

Connexe