Naar hoofdinhoud gaan

Documentation Index

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

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

Elke agent in een multi-agent-configuratie kan de globale sandbox- en toolpolicy overschrijven. Deze pagina behandelt configuratie per agent, voorrangsregels en voorbeelden.

Sandboxing

Backends en modi — volledige sandboxreferentie.

Sandbox vs tool policy vs elevated

Debuggen: “waarom is dit geblokkeerd?”

Elevated mode

Elevated 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 auth-profielen van de standaard-/hoofd-agent lezen wanneer ze geen lokaal profiel hebben, maar OAuth-vernieuwingstokens worden niet gekloond naar opslag voor secundaire agents. Als je inloggegevens handmatig 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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}
Resultaat:
  • main-agent: draait op host, volledige tooltoegang.
  • family-agent: draait in Docker (één container per agent), alleen de read-tool.
{
  "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"]
        }
      }
    ]
  }
}

​
Configuratievoorrang

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 sandboxbereik oplost naar "shared").

​
Toolbeperkingen

De filtervolgorde is:
1

Toolprofiel

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

Providertoolprofiel

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

Globale toolpolicy

tools.allow / tools.deny.
4

Providertoolpolicy

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

Agentspecifieke toolpolicy

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

Agentproviderpolicy

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

Sandboxtoolpolicy

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

Subagent-toolpolicy

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.
  • Providertool-sleutels accepteren zowel provider (bijv. google-antigravity) als 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 agent met alleen tekst.
Toolpolicy’s ondersteunen group:*-verkortingen die uitvouwen naar meerdere tools. Zie Toolgroepen voor de volledige lijst. Per-agent elevated-overschrijvingen (agents.list[].tools.elevated) kunnen elevated exec voor specifieke agents verder beperken. Zie Elevated mode voor details.

​
Migratie vanaf éé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 non-main en in een sandbox geplaatst. Als je wilt dat een agent nooit in een sandbox wordt geplaatst, 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 bewaken

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

​
Probleemoplossing

  • 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 toolfiltervolgorde: 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 de agentspecifieke sandboxconfiguratie in.
  • Standaard is "session", wat één container per sessie maakt.

​
Gerelateerd