Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Elke agent in een multi-agentconfiguratie kan de globale sandbox- en tool-policy overschrijven. Deze pagina behandelt configuratie per agent, prioriteitsregels en voorbeelden.

Sandboxing

Backends en modi — volledige sandboxreferentie.

Sandbox vs tool-policy vs verhoogd

Debuggen: “waarom wordt dit geblokkeerd?”

Verhoogde modus

Verhoogde exec voor vertrouwde afzenders.
Auth is per agent afgebakend: elke agent heeft zijn eigen agentDir-authopslag op ~/.openclaw/agents/<agentId>/agent/auth-profiles.json. Hergebruik agentDir nooit tussen agents. Agents kunnen de authprofielen van de standaard-/hoofdagent uitlezen wanneer ze geen lokaal profiel hebben, maar OAuth-refresh tokens worden niet gekloond naar secundaire agentopslag. Als je handmatig referenties kopieert, kopieer dan alleen draagbare statische api_key- of token-profielen.

​
Configuratievoorbeelden

{
  "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"
        }
      }
    }
  ]
}
Resultaat:
  • main-agent: draait op de host, volledige tooltoegang.
  • family-agent: draait in Docker (één container per agent), alleen read en berichten verzenden in het huidige gesprek.
{
  "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"]
        }
      }
    ]
  }
}

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
Resultaat:
  • standaardagents krijgen codeertools.
  • support-agent is alleen voor berichten (+ Slack-tool).
{
  "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"]
        }
      }
    ]
  }
}

​
Configuratieprioriteit

Wanneer zowel globale (agents.defaults.*) als agentspecifieke (agents.list[].*) configuraties bestaan:

​
Sandboxconfiguratie

Agentspecifieke instellingen overschrijven globale instellingen: 
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}.* overschrijft agents.defaults.sandbox.{docker,browser,prune}.* voor die agent (genegeerd wanneer de sandboxscope wordt herleid tot "shared").

​
Toolbeperkingen

De filtervolgorde is:
1

Toolprofiel

tools.profile of agents.list[].tools.profile.
2

Provider-toolprofiel

tools.byProvider[provider].profile of agents.list[].tools.byProvider[provider].profile.
3

Globale tool-policy

tools.allow / tools.deny.
4

Provider-tool-policy

tools.byProvider[provider].allow/deny.
5

Agentspecifieke tool-policy

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

Agent-provider-policy

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

Sandbox-tool-policy

tools.sandbox.tools of agents.list[].tools.sandbox.tools.
8

Subagent-tool-policy

tools.subagents.tools, indien van toepassing.
  • Elk niveau kan tools verder beperken, maar kan eerder geweigerde tools niet opnieuw toestaan.
  • Als agents.list[].tools.sandbox.tools is ingesteld, vervangt dit tools.sandbox.tools voor die agent.
  • Als agents.list[].tools.profile is ingesteld, overschrijft dit tools.profile voor die agent.
  • Provider-toolsleutels accepteren provider (bijv. google-antigravity) of provider/model (bijv. openai/gpt-5.4).
Als een expliciete allowlist in die keten ervoor zorgt dat de run geen aanroepbare tools meer heeft, stopt OpenClaw voordat de prompt naar het model wordt gestuurd. Dit is opzettelijk: een agent die is geconfigureerd met een ontbrekende tool zoals agents.list[].tools.allow: ["query_db"] moet duidelijk falen totdat de Plugin die query_db registreert is ingeschakeld, en niet doorgaan als tekst-only agent.
Tool-policies ondersteunen group:*-verkortingen die worden uitgebreid naar meerdere tools. Zie Toolgroepen voor de volledige lijst. Verhoogde overschrijvingen per agent (agents.list[].tools.elevated) kunnen verhoogde exec voor specifieke agents verder beperken. Zie Verhoogde modus voor details.

​
Migratie van één agent

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}
Verouderde agent.*-configuraties worden gemigreerd door openclaw doctor; geef voortaan de voorkeur aan agents.defaults + agents.list.

​
Voorbeelden van toolbeperkingen

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

​
Veelvoorkomende valkuil: “non-main”

agents.defaults.sandbox.mode: "non-main" is gebaseerd op session.mainKey (standaard "main"), niet op de agent-id. Groeps-/kanaalsessies krijgen altijd hun eigen sleutels, dus ze worden behandeld als niet-main en worden gesandboxed. Als je wilt dat een agent nooit wordt gesandboxed, stel dan agents.list[].sandbox.mode: "off" in.

​
Testen

Na het configureren van multi-agent-sandbox en tools:
1

Agentresolutie controleren

openclaw agents list --bindings
2

Sandboxcontainers verifiëren

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

Toolbeperkingen testen

  • Stuur een bericht waarvoor beperkte tools nodig zijn.
  • Controleer of de agent geweigerde tools niet kan gebruiken.
4

Logs monitoren

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

​
Problemen oplossen

  • Controleer of er een globale agents.defaults.sandbox.mode is die dit overschrijft.
  • Agentspecifieke configuratie heeft voorrang, dus stel agents.list[].sandbox.mode: "all" in.
  • Controleer de volgorde van toolfiltering: globaal → agent → sandbox → subagent.
  • Elk niveau kan alleen verder beperken, niet opnieuw toestaan.
  • Verifieer met logs: [tools] filtering tools for agent:${agentId}.
  • Stel scope: "agent" in in agentspecifieke sandboxconfiguratie.
  • De standaard is "session", waarmee één container per sessie wordt gemaakt.

​
Gerelateerd