Gateway

Sandbox versus toolbeleid versus verhoogde bevoegdheden

Status: active

OpenClaw heeft drie verwante maar verschillende besturingselementen:

Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) bepaalt waar tools worden uitgevoerd (sandboxbackend of host).
Toolbeleid (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) bepaalt welke tools beschikbaar/toegestaan zijn.
Elevated (tools.elevated.*, agents.list[].tools.elevated.*) is een uitsluitend voor exec bedoelde uitweg om buiten de sandbox uit te voeren wanneer je in een sandbox werkt (standaard gateway, of node wanneer het exec-doel is ingesteld op node).

Snel debuggen

Gebruik de inspectietool om te zien wat OpenClaw daadwerkelijk doet:

bash

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Deze toont:

de effectieve sandboxmodus, het bereik en de werkruimtetoegang
of de sessie momenteel in een sandbox wordt uitgevoerd (hoofd- of niet-hoofdsessie)
de effectieve toestemmings- en weigeringsregels voor sandboxtools (en of deze afkomstig zijn van de agent, globale configuratie of standaardinstellingen)
Elevated-controles en configuratiepaden voor oplossingen

Sandbox: waar tools worden uitgevoerd

Sandboxing wordt bestuurd door agents.defaults.sandbox.mode:

"off": alles wordt op de host uitgevoerd.
"non-main": alleen niet-hoofdsessies worden in een sandbox uitgevoerd (een veelvoorkomende „verrassing” voor groepen/kanalen).
"all": alles wordt in een sandbox uitgevoerd.

agents.defaults.sandbox.workspaceAccess bepaalt wat de sandbox kan zien: "none", "ro" of "rw".

Zie Sandboxing voor de volledige matrix (bereik, werkruimtekoppelingen en images).

Bind-mounts (snelle beveiligingscontrole)

docker.binds doorbreekt het bestandssysteem van de sandbox: alles wat je koppelt, is in de container zichtbaar met de ingestelde modus (:ro of :rw).
Als je de modus weglaat, is de standaard lezen en schrijven; geef voor broncode/geheimen de voorkeur aan :ro.
scope: "shared" negeert bind-mounts per agent (alleen globale bind-mounts zijn van toepassing).
OpenClaw valideert bind-bronnen tweemaal: eerst op het genormaliseerde bronpad en daarna opnieuw nadat het pad via de diepste bestaande bovenliggende map is herleid. Ontsnappingen via bovenliggende symlinks omzeilen controles op geblokkeerde paden of toegestane hoofdmappen niet.
Niet-bestaande eindpaden worden nog steeds veilig gecontroleerd. Als /workspace/alias-out/new-file via een bovenliggende symlink wordt herleid naar een geblokkeerd pad of buiten de geconfigureerde toegestane hoofdmappen, wordt de bind-mount geweigerd.
Het koppelen van /var/run/docker.sock geeft de sandbox feitelijk controle over de host; doe dit alleen bewust.
Werkruimtetoegang (workspaceAccess) staat los van de modi van bind-mounts.

Toolbeleid: welke tools bestaan/aanroepbaar zijn

De volgende lagen zijn van belang:

Toolprofiel: tools.profile en agents.list[].tools.profile (basislijst met toegestane tools)
Toolprofiel per provider: tools.byProvider[provider].profile en agents.list[].tools.byProvider[provider].profile
Globaal toolbeleid/toolbeleid per agent: tools.allow/tools.deny en agents.list[].tools.allow/agents.list[].tools.deny
Toolbeleid per provider: tools.byProvider[provider].allow/deny en agents.list[].tools.byProvider[provider].allow/deny
Toolbeleid voor de sandbox (alleen van toepassing binnen een sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny en agents.list[].tools.sandbox.tools.*

Vuistregels:

deny heeft altijd voorrang.
Als allow niet leeg is, wordt al het overige als geblokkeerd beschouwd.
Het toolbeleid is de harde grens: /exec kan een geweigerde exec-tool niet alsnog toestaan.
Het toolbeleid filtert de beschikbaarheid van tools op naam; het inspecteert geen neveneffecten binnen exec. Als exec is toegestaan, maakt het weigeren van write, edit of apply_patch shellopdrachten niet alleen-lezen.
/exec wijzigt alleen de sessiestandaarden voor geautoriseerde afzenders; het verleent geen toegang tot tools.
Tool-sleutels voor providers accepteren zowel provider (bijvoorbeeld google-antigravity) als provider/model (bijvoorbeeld openai/gpt-5.4).
Gateway-logboeken bevatten agents/tool-policy-auditvermeldingen wanneer een stap in het toolbeleid tools verwijdert of wanneer sandboxbeleid voor tools een aanroep blokkeert. Gebruik openclaw logs om het regellabel, de configuratiesleutel en de betrokken toolnamen te bekijken.

Toolgroepen (verkorte notaties)

Toolbeleid (globaal, per agent en voor de sandbox) ondersteunt group:*-vermeldingen die naar meerdere tools worden uitgebreid:

json5

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Beschikbare groepen:

Groep	Tools
`group:runtime`	`exec`, `process`, `code_execution` (`bash` wordt geaccepteerd als alias voor `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `canvas`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	de meeste ingebouwde OpenClaw-tools (met uitzondering van de bestandssysteem- en runtimeprimitieven `read`/`write`/`edit`/`apply_patch`/`exec`/`process`, `canvas` en providerplugins)
`group:plugins`	alle geladen tools die eigendom zijn van plugins, inclusief geconfigureerde MCP-servers die via `bundle-mcp` beschikbaar worden gesteld

Weiger voor alleen-lezen-agents zowel group:runtime als tools die het bestandssysteem wijzigen, tenzij het sandboxbeleid voor het bestandssysteem of een afzonderlijke hostgrens de alleen-lezenbeperking afdwingt.

Voor MCP-servers in een sandbox vormt het sandboxbeleid voor tools een tweede toelatingscontrole. Als mcp.servers is geconfigureerd maar sandboxbewerkingen alleen ingebouwde tools tonen, voeg dan bundle-mcp, group:plugins of een MCP-toolnaam/-patroon met servervoorvoegsel, zoals outlook__send_mail of outlook__*, toe aan tools.sandbox.tools.alsoAllow. Start of laad vervolgens de Gateway opnieuw en leg de toollijst opnieuw vast. Serverpatronen gebruiken het providerveilige MCP-servervoorvoegsel: tekens die niet tot [A-Za-z0-9_-] behoren, worden -, namen die niet met een letter beginnen krijgen het voorvoegsel mcp-, en lange of dubbele voorvoegsels kunnen worden ingekort of van een achtervoegsel worden voorzien.

openclaw doctor controleert deze vorm momenteel voor door OpenClaw beheerde servers in mcp.servers. MCP-servers die vanuit gebundelde pluginmanifesten of Claude .mcp.json worden geladen, gebruiken dezelfde sandboxcontrole, maar deze diagnose somt die bronnen nog niet op; gebruik dezelfde vermeldingen in de lijst met toegestane tools als hun tools uit sandboxbewerkingen verdwijnen.

Elevated: uitsluitend voor exec „uitvoeren op host”

Elevated verleent geen extra tools; het is alleen van invloed op exec.

Als je in een sandbox werkt, wordt met /elevated on (of exec met elevated: true) buiten de sandbox uitgevoerd (goedkeuringen kunnen nog steeds van toepassing zijn).
Gebruik /elevated full om exec-goedkeuringen voor de sessie over te slaan.
Als je al rechtstreeks uitvoert, heeft Elevated feitelijk geen effect (de controles blijven van toepassing).
Elevated is niet beperkt tot een Skill en omzeilt geen toestemmings- of weigeringsregels voor tools.
Elevated verleent vanuit host=auto geen willekeurige mogelijkheid om een andere host te kiezen; het volgt de normale regels voor exec-doelen en behoudt node alleen wanneer het geconfigureerde doel of sessiedoel al node is.
/exec staat los van Elevated. Het past alleen de exec-standaarden per sessie aan voor geautoriseerde afzenders.

Controles:

Inschakeling: tools.elevated.enabled (en optioneel agents.list[].tools.elevated.enabled)
Lijsten met toegestane afzenders: tools.elevated.allowFrom.<provider> (en optioneel agents.list[].tools.elevated.allowFrom.<provider>)

Zie Elevated-modus.

Veelvoorkomende oplossingen voor „opgesloten in de sandbox”

„Tool X geblokkeerd door het sandboxbeleid voor tools”

Configuratiesleutels voor oplossingen (kies er één):

Schakel de sandbox uit: agents.defaults.sandbox.mode=off (of per agent agents.list[].sandbox.mode=off)
Sta de tool binnen de sandbox toe:
- verwijder deze uit tools.sandbox.tools.deny (of per agent uit agents.list[].tools.sandbox.tools.deny)
- of voeg deze toe aan tools.sandbox.tools.allow (of aan de lijst met toegestane tools per agent)
Controleer openclaw logs op de agents/tool-policy-vermelding. Deze registreert de sandboxmodus en of de toestemmings- of weigeringsregel de tool heeft geblokkeerd.

„Ik dacht dat dit de hoofdsessie was; waarom wordt deze in een sandbox uitgevoerd?”

In de modus "non-main" zijn groeps-/kanaalsleutels geen hoofdsessie. Gebruik de sleutel van de hoofdsessie (weergegeven door sandbox explain) of wijzig de modus in "off".

Gerelateerd

Sandboxing -- volledige sandboxreferentie (modi, bereiken, backends en images)
Sandbox en tools voor meerdere agents -- overschrijvingen per agent en voorrangsregels
Elevated-modus

Was this useful?