Sandbox vs tool policy vs elevated

OpenClaw has three related (but different) controls:

1. Sandbox (
   text

   Copy

   agents.defaults.sandbox.*
   /
   text

   Copy

   agents.list[].sandbox.*
   ) decides where tools run (sandbox backend vs host).
2. Tool policy (
   text

   Copy

   tools.*
   ,
   text

   Copy

   tools.sandbox.tools.*
   ,
   text

   Copy

   agents.list[].tools.*
   ) decides which tools are available/allowed.
3. Elevated (
   text

   Copy

   tools.elevated.*
   ,
   text

   Copy

   agents.list[].tools.elevated.*
   ) is an exec-only escape hatch to run outside the sandbox when you’re sandboxed (
   text

   Copy

   gateway
   by default, or
   text

   Copy

   node
   when the exec target is configured to
   text

   Copy

   node
   ).

Quick debug

Use the inspector to see what OpenClaw is actually doing:

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

It prints:

• effective sandbox mode/scope/workspace access
• whether the session is currently sandboxed (main vs non-main)
• effective sandbox tool allow/deny (and whether it came from agent/global/default)
• elevated gates and fix-it key paths

Sandbox: where tools run

Sandboxing is controlled by

:

• text

  Copy

  "off"
  : everything runs on the host.
• text

  Copy

  "non-main"
  : only non-main sessions are sandboxed (common “surprise” for groups/channels).
• text

  Copy

  "all"
  : everything is sandboxed.

See Sandboxing for the full matrix (scope, workspace mounts, images).

Bind mounts (security quick check)

• text

  Copy

  docker.binds
  pierces the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (
  text

  Copy

  :ro
  or
  text

  Copy

  :rw
  ).
• Default is read-write if you omit the mode; prefer
  text

  Copy

  :ro
  for source/secrets.
• text

  Copy

  scope: "shared"
  ignores per-agent binds (only global binds apply).
• OpenClaw validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
• Non-existent leaf paths are still checked safely. If
  text

  Copy

  /workspace/alias-out/new-file
  resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
• Binding
  text

  Copy

  /var/run/docker.sock
  effectively hands host control to the sandbox; only do this intentionally.
• Workspace access (
  text

  Copy

  workspaceAccess: "ro"
  /
  text

  Copy

  "rw"
  ) is independent of bind modes.

Tool policy: which tools exist/are callable

Two layers matter:

• Tool profile:
  text

  Copy

  tools.profile
  and
  text

  Copy

  agents.list[].tools.profile
  (base allowlist)
• Provider tool profile:
  text

  Copy

  tools.byProvider[provider].profile
  and
  text

  Copy

  agents.list[].tools.byProvider[provider].profile
• Global/per-agent tool policy:
  text

  Copy

  tools.allow
  /
  text

  Copy

  tools.deny
  and
  text

  Copy

  agents.list[].tools.allow
  /
  text

  Copy

  agents.list[].tools.deny
• Provider tool policy:
  text

  Copy

  tools.byProvider[provider].allow/deny
  and
  text

  Copy

  agents.list[].tools.byProvider[provider].allow/deny
• Sandbox tool policy (only applies when sandboxed):
  text

  Copy

  tools.sandbox.tools.allow
  /
  text

  Copy

  tools.sandbox.tools.deny
  and
  text

  Copy

  agents.list[].tools.sandbox.tools.*

Rules of thumb:

• text

  Copy

  deny
  always wins.
• If
  text

  Copy

  allow
  is non-empty, everything else is treated as blocked.
• Tool policy is the hard stop:
  text

  Copy

  /exec
  cannot override a denied
  text

  Copy

  exec
  tool.
• text

  Copy

  /exec
  only changes session defaults for authorized senders; it does not grant tool access. Provider tool keys accept either
  text

  Copy

  provider
  (e.g.
  text

  Copy

  google-antigravity
  ) or
  text

  Copy

  provider/model
  (e.g.
  text

  Copy

  openai/gpt-5.4
  ).

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support

entries that expand to multiple tools:

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

Available groups:

• text

  Copy

  group:runtime
  :
  text

  Copy

  exec
  ,
  text

  Copy

  process
  ,
  text

  Copy

  code_execution
  (
  text

  Copy

  bash
  is accepted as an alias for
  text

  Copy

  exec
  )
• text

  Copy

  group:fs
  :
  text

  Copy

  read
  ,
  text

  Copy

  write
  ,
  text

  Copy

  edit
  ,
  text

  Copy

  apply_patch
• text

  Copy

  group:sessions
  :
  text

  Copy

  sessions_list
  ,
  text

  Copy

  sessions_history
  ,
  text

  Copy

  sessions_send
  ,
  text

  Copy

  sessions_spawn
  ,
  text

  Copy

  sessions_yield
  ,
  text

  Copy

  subagents
  ,
  text

  Copy

  session_status
• text

  Copy

  group:memory
  :
  text

  Copy

  memory_search
  ,
  text

  Copy

  memory_get
• text

  Copy

  group:web
  :
  text

  Copy

  web_search
  ,
  text

  Copy

  x_search
  ,
  text

  Copy

  web_fetch
• text

  Copy

  group:ui
  :
  text

  Copy

  browser
  ,
  text

  Copy

  canvas
• text

  Copy

  group:automation
  :
  text

  Copy

  cron
  ,
  text

  Copy

  gateway
• text

  Copy

  group:messaging
  :
  text

  Copy

  message
• text

  Copy

  group:nodes
  :
  text

  Copy

  nodes
• text

  Copy

  group:agents
  :
  text

  Copy

  agents_list
• text

  Copy

  group:media
  :
  text

  Copy

  image
  ,
  text

  Copy

  image_generate
  ,
  text

  Copy

  video_generate
  ,
  text

  Copy

  tts
• text

  Copy

  group:openclaw
  : all built-in OpenClaw tools (excludes provider plugins)

Elevated: exec-only "run on host"

Elevated does not grant extra tools; it only affects

.

• If you’re sandboxed,
  text

  Copy

  /elevated on
  (or
  text

  Copy

  exec
  with
  text

  Copy

  elevated: true
  ) runs outside the sandbox (approvals may still apply).
• Use
  text

  Copy

  /elevated full
  to skip exec approvals for the session.
• If you’re already running direct, elevated is effectively a no-op (still gated).
• Elevated is not skill-scoped and does not override tool allow/deny.
• Elevated does not grant arbitrary cross-host overrides from
  text

  Copy

  host=auto
  ; it follows the normal exec target rules and only preserves
  text

  Copy

  node
  when the configured/session target is already
  text

  Copy

  node
  .
• text

  Copy

  /exec
  is separate from elevated. It only adjusts per-session exec defaults for authorized senders.

Gates:

• Enablement:
  text

  Copy

  tools.elevated.enabled
  (and optionally
  text

  Copy

  agents.list[].tools.elevated.enabled
  )
• Sender allowlists:
  text

  Copy

  tools.elevated.allowFrom.<provider>
  (and optionally
  text

  Copy

  agents.list[].tools.elevated.allowFrom.<provider>
  )

See Elevated Mode.

Common "sandbox jail" fixes

"Tool X blocked by sandbox tool policy"

Fix-it keys (pick one):

• Disable sandbox:
  text

  Copy

  agents.defaults.sandbox.mode=off
  (or per-agent
  text

  Copy

  agents.list[].sandbox.mode=off
  )
• Allow the tool inside sandbox:
  • remove it from
    text

    Copy

    tools.sandbox.tools.deny
    (or per-agent
    text

    Copy

    agents.list[].tools.sandbox.tools.deny
    )
  • or add it to
    text

    Copy

    tools.sandbox.tools.allow
    (or per-agent allow)

"I thought this was main, why is it sandboxed?"

In

mode, group/channel keys are not main. Use the main session key (shown by ) or switch mode to .

Related

• Sandboxing -- full sandbox reference (modes, scopes, backends, images)
• Multi-Agent Sandbox & Tools -- per-agent overrides and precedence
• Elevated Mode