Sandbox en tools voor meerdere agents

Elke agent in een multi-agentconfiguratie kan het algemene sandbox- en toolbeleid overschrijven. Deze pagina behandelt configuratie per agent, voorrangsregels en voorbeelden.

Sandboxing

Backends en modi — volledige sandboxreferentie.

Sandbox versus toolbeleid versus verhoogd

Problemen oplossen met “waarom wordt dit geblokkeerd?”

Verhoogde modus

Verhoogde uitvoering voor vertrouwde afzenders.

Authenticatie is per agent afgebakend: elke agent heeft een eigen agentDir-authenticatieopslag in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Gebruik agentDir nooit opnieuw voor meerdere agents. Agents kunnen terugvallen op de authenticatieprofielen van de standaard-/hoofdagent wanneer ze geen lokaal profiel hebben, maar OAuth-vernieuwingstokens worden niet naar de opslag van secundaire agents gekloond. Als je aanmeldgegevens handmatig kopieert, kopieer dan alleen overdraagbare statische api_key- of token-profielen.

Configuratievoorbeelden

Voorbeeld 1: Persoonlijke agent + beperkte gezinsagent

{
  "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 toegang tot tools.
family-agent: draait in Docker (één container per agent), alleen read en berichten verzenden binnen het huidige gesprek.

Voorbeeld 2: Werkagent met gedeelde sandbox

{
  "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"]
        }
      }
    ]
  }
}

Voorbeeld 2b: Algemeen programmeerprofiel + agent die alleen berichten verwerkt

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

Resultaat:

standaardagents krijgen programmeertools.
support-agent kan alleen berichten verwerken (+ Slack-tool).

Voorbeeld 3: Verschillende sandboxmodi per 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"]
        }
      }
    ]
  }
}

Configuratievoorrang

Wanneer zowel algemene (agents.defaults.*) als agentspecifieke (agents.entries.*.*) configuraties bestaan:

Sandboxconfiguratie

Agentspecifieke instellingen overschrijven de algemene instellingen:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.* overschrijft agents.defaults.sandbox.{docker,browser,prune}.* voor die agent (wordt genegeerd wanneer het sandboxbereik wordt herleid tot "shared").

Toolbeperkingen

De filtervolgorde is:

Toolprofiel

tools.profile of agents.entries.*.tools.profile.

Toolprofiel van provider

tools.byProvider[provider].profile of agents.entries.*.tools.byProvider[provider].profile.

Algemeen toolbeleid

tools.allow / tools.deny.

Toolbeleid van provider

tools.byProvider[provider].allow/deny.

Agentspecifiek toolbeleid

agents.entries.*.tools.allow/deny.

Providerbeleid van agent

agents.entries.*.tools.byProvider[provider].allow/deny.

Toolbeleid van sandbox

tools.sandbox.tools of agents.entries.*.tools.sandbox.tools.

Toolbeleid van subagent

tools.subagents.tools, indien van toepassing.

Voorrangsregels

Elk niveau kan tools verder beperken, maar kan op eerdere niveaus geweigerde tools niet opnieuw toestaan.
Als agents.entries.*.tools.sandbox.tools is ingesteld, vervangt dit tools.sandbox.tools voor die agent.
Als agents.entries.*.tools.profile is ingesteld, overschrijft dit tools.profile voor die agent.
Providertoolsleutels accepteren zowel provider (bijvoorbeeld google-antigravity) als provider/model (bijvoorbeeld openai/gpt-5.4).

Gedrag bij een lege toelatingslijst

Als een expliciete toelatingslijst in die keten ervoor zorgt dat er geen aanroepbare tools overblijven, stopt OpenClaw voordat de prompt naar het model wordt verzonden. Dit is opzettelijk: een agent die is geconfigureerd met een ontbrekende tool zoals agents.entries.*.tools.allow: ["query_db"], moet duidelijk mislukken totdat de Plugin die query_db registreert is ingeschakeld, en niet doorgaan als een agent die alleen tekst verwerkt.

Toolbeleid ondersteunt group:*-verkortingen die naar meerdere tools worden uitgebreid. Zie Toolgroepen voor de volledige lijst. Verhoogde overschrijvingen per agent (agents.entries.*.tools.elevated) kunnen verhoogde uitvoering voor specifieke agents verder beperken. Zie Verhoogde modus voor details.

Migratie vanuit één agent

Voorheen (één agent)
Nadien (meerdere agents)

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

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

Verouderde configuratiesleutels agents.defaults.*/agents.entries.*.* (zoals sandbox.perSession, agentRuntime, embeddedPi) worden door openclaw doctor gemigreerd; geef voortaan de voorkeur aan agents.defaults + agents.entries.

Voorbeelden van toolbeperkingen

Alleen-lezenagent
Shelluitvoering met uitgeschakelde bestandssysteemtools
Alleen communicatie

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

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

Dit beleid schakelt de bestandssysteemtools van OpenClaw uit, maar exec blijft een shell en kan bestanden schrijven waar het geselecteerde host- of sandboxbestandssysteem dit toestaat. Weiger voor een alleen-lezenagent exec en process, of combineer shelltoegang met bestandssysteembesturing voor de sandbox, zoals agents.defaults.sandbox.workspaceAccess: "ro" of "none".

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

sessions_history in dit profiel retourneert nog steeds een begrensde, opgeschoonde herinneringsweergave in plaats van een onbewerkte transcriptdump. Bij het ophalen van assistentgegevens worden denktags, <relevant-memories>-scaffolding, XML-payloads voor toolaanroepen in platte tekst (waaronder <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> en afgekorte toolaanroepblokken), afgewaardeerde scaffolding voor toolaanroepen, gelekte ASCII-/volledige-breedte-modelbesturingstokens en ongeldige MiniMax-XML voor toolaanroepen verwijderd vóór redactie/afkapping.

Veelvoorkomende valkuil: “non-main”

agents.defaults.sandbox.mode: "non-main" vergelijkt de sessiesleutel met de hoofdsessiesleutel (altijd "main"; session.mainKey kan niet door de gebruiker worden geconfigureerd en OpenClaw waarschuwt voor elke andere waarde en negeert deze), niet met de agent-id. Groeps-/kanaalsessies krijgen altijd hun eigen sleutels, waardoor ze als niet-hoofd worden behandeld en in een sandbox worden uitgevoerd. Als je wilt dat een agent nooit in een sandbox wordt uitgevoerd, stel dan agents.entries.*.sandbox.mode: "off" in.

Testen

Na het configureren van de sandbox en tools voor meerdere agents:

Agentselectie controleren

openclaw agents list --bindings

Sandboxcontainers verifiëren

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

Toolbeperkingen testen

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

Logboeken bewaken

openclaw logs --follow | grep -E "routing|sandbox|tools"

Problemen oplossen

Agent wordt ondanks `mode: 'all'` niet in een sandbox uitgevoerd

Controleer of er een algemene agents.defaults.sandbox.mode bestaat die dit overschrijft.
Agentspecifieke configuratie heeft voorrang, dus stel agents.entries.*.sandbox.mode: "all" in.

Tools die ondanks de weigerlijst nog steeds beschikbaar zijn

Bekijk de volledige filtervolgorde: profiel → providerprofiel → globaal beleid → providerbeleid → agentbeleid → providerbeleid van de agent → sandbox → subagent.
Elk niveau kan alleen verdere beperkingen opleggen, niet opnieuw toegang verlenen.
Zie Sandbox versus toolbeleid versus verhoogde modus voor stapsgewijze foutopsporing.

Container niet per agent geïsoleerd

De standaardwaarde van scope is "agent" (één container per agent-id).
Stel scope: "session" in voor één container per sessie, of scope: "shared" om één container opnieuw te gebruiken voor meerdere agents.

Gerelateerd

Verhoogde modus
Routering met meerdere agents
Sandboxconfiguratie
Sandbox versus toolbeleid versus verhoogde modus — foutopsporing voor “waarom wordt dit geblokkeerd?”
Sandboxing — volledige sandboxreferentie (modi, bereiken, backends, images)
Sessiebeheer

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Sandbox en tools voor meerdere agents

Sandboxing

Sandbox versus toolbeleid versus verhoogd

Verhoogde modus

Configuratievoorbeelden

Configuratievoorrang

Sandboxconfiguratie

Toolbeperkingen

Migratie vanuit één agent

Voorbeelden van toolbeperkingen

Veelvoorkomende valkuil: “non-main”

Testen

Problemen oplossen

Gerelateerd

Sandboxing

Sandbox versus toolbeleid versus verhoogd

Verhoogde modus

​Configuratievoorbeelden

​Configuratievoorrang

​Sandboxconfiguratie

​Toolbeperkingen

​Migratie vanuit één agent

​Voorbeelden van toolbeperkingen

​Veelvoorkomende valkuil: “non-main”

​Testen

​Problemen oplossen

​Gerelateerd

Configuratievoorbeelden

Configuratievoorrang

Sandboxconfiguratie

Toolbeperkingen

Migratie vanuit één agent

Voorbeelden van toolbeperkingen

Veelvoorkomende valkuil: “non-main”

Testen

Problemen oplossen

Gerelateerd