Sandbox versus toolbeleid versus verhoogde rechten

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.

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) bepaalt waar tools worden uitgevoerd (sandbox-backend versus host).
2. Toolbeleid (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) bepaalt welke tools beschikbaar/toegestaan zijn.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) is een alleen-voor-exec nooduitgang om buiten de sandbox te draaien wanneer je in een sandbox zit (gateway standaard, of node wanneer het exec-doel is geconfigureerd als node).

​

Snel debuggen

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• effectieve sandboxmodus/scope/workspacetoegang
• of de sessie momenteel in een sandbox zit (main versus niet-main)
• effectieve allow/deny voor sandbox-tools (en of die afkomstig is van agent/globaal/standaard)
• Elevated-gates en fix-it-sleutelpaden

​

Sandbox: waar tools draaien

• "off": alles draait op de host.
• "non-main": alleen niet-main-sessies zitten in een sandbox (veelvoorkomende “verrassing” voor groepen/kanalen).
• "all": alles zit in een sandbox.

​

Bind-mounts (snelle beveiligingscontrole)

• docker.binds doorboort het sandboxbestandssysteem: alles wat je mount is zichtbaar binnen de container met de modus die je instelt (:ro of :rw).
• De standaard is read-write als je de modus weglaat; geef de voorkeur aan :ro voor broncode/geheimen.
• scope: "shared" negeert binds per agent (alleen globale binds gelden).
• OpenClaw valideert bind-bronnen tweemaal: eerst op het genormaliseerde bronpad, daarna opnieuw na resolutie via de diepste bestaande ancestor. Ontsnappingen via symlink-parents omzeilen geen controles op geblokkeerde paden of toegestane roots.
• Niet-bestaande leaf-paden worden nog steeds veilig gecontroleerd. Als /workspace/alias-out/new-file via een gesymlinkte parent resolveert naar een geblokkeerd pad of buiten de geconfigureerde toegestane roots, wordt de bind geweigerd.
• Het binden van /var/run/docker.sock geeft de sandbox effectief controle over de host; doe dit alleen bewust.
• Workspacetoegang (workspaceAccess: "ro"/"rw") staat los van bind-modi.

​

Toolbeleid: welke tools bestaan/aanroepbaar zijn

• Toolprofiel: tools.profile en agents.list[].tools.profile (basis-allowlist)
• Provider-toolprofiel: tools.byProvider[provider].profile en agents.list[].tools.byProvider[provider].profile
• Globaal/per-agent toolbeleid: tools.allow/tools.deny en agents.list[].tools.allow/agents.list[].tools.deny
• Provider-toolbeleid: tools.byProvider[provider].allow/deny en agents.list[].tools.byProvider[provider].allow/deny
• Sandbox-toolbeleid (geldt alleen wanneer gesandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny en agents.list[].tools.sandbox.tools.*

• deny wint altijd.
• Als allow niet leeg is, wordt al het andere als geblokkeerd behandeld.
• Toolbeleid is de harde stop: /exec kan een geweigerde exec-tool niet overriden.
• Toolbeleid filtert toolbeschikbaarheid op naam; het inspecteert geen bijwerkingen binnen exec. Als exec is toegestaan, maakt het weigeren van write, edit of apply_patch shellcommando’s niet read-only.
• /exec wijzigt alleen sessiestandaarden voor geautoriseerde afzenders; het verleent geen tooltoegang. Provider-toolsleutels accepteren ofwel provider (bijv. google-antigravity) of provider/model (bijv. openai/gpt-5.4).

​

Toolgroepen (shorthands)

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

• group:runtime: exec, process, code_execution (bash wordt geaccepteerd als alias voor exec)
• group:fs: read, write, edit, apply_patch Voor read-only agents moet je group:runtime weigeren, evenals muterende bestandssysteemtools, tenzij sandbox-bestandssysteembeleid of een aparte host-grens de read-only-beperking afdwingt.
• 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
• group:agents: agents_list, update_plan
• group:media: image, image_generate, music_generate, video_generate, tts
• group:openclaw: alle ingebouwde OpenClaw-tools (exclusief provider-plugins)

​

Elevated: alleen-voor-exec “op host draaien”

• Als je gesandboxed bent, draait /elevated on (of exec met elevated: true) buiten de sandbox (goedkeuringen kunnen nog steeds gelden).
• Gebruik /elevated full om exec-goedkeuringen voor de sessie over te slaan.
• Als je al direct draait, is Elevated effectief een no-op (nog steeds gated).
• Elevated is niet skill-scoped en overridet niet tool-allow/deny.
• Elevated verleent geen willekeurige cross-host overrides vanuit host=auto; het volgt de normale regels voor exec-doelen en behoudt alleen node wanneer het geconfigureerde/sessie-doel al node is.
• /exec staat los van Elevated. Het past alleen exec-standaarden per sessie aan voor geautoriseerde afzenders.

• Inschakeling: tools.elevated.enabled (en optioneel agents.list[].tools.elevated.enabled)
• Allowlists voor afzenders: tools.elevated.allowFrom.<provider> (en optioneel agents.list[].tools.elevated.allowFrom.<provider>)

​

Veelvoorkomende oplossingen voor “sandbox jail"

​

"Tool X blocked by sandbox tool policy”

• Sandbox uitschakelen: agents.defaults.sandbox.mode=off (of per agent agents.list[].sandbox.mode=off)
• De tool binnen de sandbox toestaan:
  • verwijder deze uit tools.sandbox.tools.deny (of per agent agents.list[].tools.sandbox.tools.deny)
  • of voeg deze toe aan tools.sandbox.tools.allow (of allow per agent)

​

“I thought this was main, why is it sandboxed?”

​

Gerelateerd

• Sandboxing — volledige sandboxreferentie (modi, scopes, backends, images)
• Multi-Agent Sandbox & Tools — overrides en prioriteit per agent
• Elevated Mode