OpenClaw Sandbox vs Approvals vs Tool Policy: Three Different Safety Layers

When an OpenClaw command gets blocked, the tempting reaction is to look for one magic switch. Turn off the sandbox. Enable elevated mode. Change approvals. Add the tool to an allowlist. I get why that happens, but it is usually the wrong debugging model.

OpenClaw has three separate safety layers that can all affect the same moment: sandboxing, tool policy, and exec approvals. They sound related because they are all safety controls. They are not interchangeable.

The shortest version is this: sandboxing decides where tools run, tool policy decides which tools exist, and approvals decide whether a host exec command is allowed to proceed. If you understand that split, most “why did OpenClaw block this?” incidents become much less mysterious.

This post is docs-grounded and deliberately practical. If you want the deeper single-topic guide for approvals afterward, read OpenClaw Exec Approvals. This one is the operator map that keeps the three layers from blurring together.

The three-layer mental model

The OpenClaw docs define the split cleanly:

• Sandbox configuration under agents.defaults.sandbox.* or agents.list[].sandbox.* decides where tool execution happens: host or sandbox backend.
• Tool policy under keys like tools.*, tools.sandbox.tools.*, and agents.list[].tools.* decides which tools are available or blocked.
• Elevated / exec approvals apply to exec. Elevated is the escape hatch for running outside the sandbox, and exec approvals are the host-side guardrail that can still require policy, allowlist, and approval to agree.

That means the fix depends on the layer that said no. A denied browser tool is not fixed by approving an exec command. A sandboxed shell that cannot see a host path is not fixed by adding read to a tool allowlist. An approval prompt that falls back to deny is not fixed by changing the sandbox mode.

So before changing config, inspect the actual effective state:

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

The docs say this inspector reports the effective sandbox mode, scope, workspace access, whether the session is currently sandboxed, effective sandbox tool allow/deny, elevated gates, and fix-it key paths. Start there. It is much cheaper than guessing.

Layer 1: sandboxing decides where tools run

OpenClaw sandboxing is optional. When it is enabled, tool execution can happen inside a sandbox backend instead of directly on the host. The Gateway process itself stays on the host; the tools are what move into the isolated environment.

The core mode key is agents.defaults.sandbox.mode, with three documented values:

• off: no sandboxing; tools run on the host.
• non-main: non-main sessions are sandboxed. The docs call out a common surprise here: group or channel sessions are not the main session key, so they can count as non-main.
• all: every session runs in a sandbox.

The docs also describe sandbox scope values: agent, session, and shared. Scope is about how many sandbox runtimes are created and shared. That matters when you are debugging state that appears in one session but not another.

Backends are a separate choice. The docs cover Docker, SSH, and OpenShell backends. Docker is local container-backed. SSH can run the sandbox workspace on an SSH-accessible machine. OpenShell is an OpenShell-managed remote environment with mirror and remote workspace modes. You do not need all of that on day one, but you should know that “sandboxed” does not always mean “a local Docker container with my current files mounted exactly how I imagine.”

Workspace access is its own setting

The sandbox docs define workspaceAccess separately from sandbox mode:

• none: tools see a sandbox workspace.
• ro: the agent workspace is mounted read-only.
• rw: the agent workspace is mounted read-write.

This is where a lot of operator confusion comes from. “The tool exists” does not imply “the tool can write the host workspace.” You can allow edit as a tool and still be in a read-only workspace posture. The place where the tool runs and the files it can touch are different questions.

Bind mounts pierce the filesystem boundary

The Docker sandbox docs are blunt about bind mounts: docker.binds pierce the sandbox filesystem. Whatever you bind is visible inside the container with the mode you set, :ro or :rw. If you omit the mode, the documented default is read-write, so prefer :ro for source or secrets unless you intentionally need writes.

There is also an important scope note: with scope: "shared", per-agent binds are ignored and only global binds apply. If you are wondering why one agent-specific bind is not showing up, check scope before inventing a more exotic explanation.

Layer 2: tool policy decides what can be called

Tool policy is the hard stop for tool availability. The docs list several layers: tool profiles, provider tool profiles, global and per-agent allow/deny, provider-specific allow/deny, and sandbox-only tool policy. The details matter in larger deployments, but two rules carry most of the day-to-day weight:

• deny always wins.
• If an allow list is non-empty, everything else is treated as blocked.

That second rule is the one that bites people. An allowlist is not a friendly suggestion. It flips the default from “available unless denied” to “blocked unless explicitly allowed.”

Tool policy also cannot be bypassed by /exec. The docs say this directly: /exec only changes session defaults for authorized senders; it does not grant tool access. If the exec tool is denied by policy, an /exec directive is not a skeleton key.

A small example of the shape, not a universal recommendation:

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

The docs support group:* shorthands for tool policy. I like them for readability, but I would still inspect the effective policy after changing them. In production, “I think this expands to what I meant” is weaker than openclaw sandbox explain --json.

Want the full operator setup instead of learning each safety layer by breaking it in production? Get ClawKit here.

Layer 3: elevated and exec approvals control host commands

Elevated mode only affects exec. It does not grant extra tools, it does not override a denied tool policy, and it is not skill-scoped. Its job is narrower: when a session is sandboxed, elevated mode lets exec run outside the sandbox through the configured escape path.

The documented directives are:

• /elevated on or /elevated ask: run on the host and keep exec approvals.
• /elevated full: run on the host and skip exec approvals for the session.
• /elevated off: return to sandbox-confined execution.

There are gates before elevated is available: tools.elevated.enabled, sender allowlists under tools.elevated.allowFrom, and optional per-agent restrictions. If those gates fail, elevated is unavailable.

Exec approvals are a related but separate guardrail. The docs describe them as the companion app or node host interlock for letting a sandboxed agent run commands on a real host, either the gateway host or a node host. Approvals stack on top of tool policy and elevated gating unless elevated is set to full.

Approvals live on the execution host at:

~/.openclaw/exec-approvals.json

The key policy knobs are documented as:

• security: deny, allowlist, or full.
• ask: off, on-miss, or always.
• askFallback: what happens when a prompt is required but no UI is reachable: deny, allowlist, or full.

The effective policy is the stricter of OpenClaw's requested tools.exec.* policy and the host-local approvals state. So if a local host file is stricter than your config, the stricter host policy wins. That is a feature, not a bug.

Useful inspection commands from the docs:

openclaw approvals get
openclaw approvals get --gateway
openclaw approvals get --node <id|name|ip>
openclaw exec-policy show

A practical debugging flow

When something is blocked, I would debug in this order:

1. Ask: is the session sandboxed? Run openclaw sandbox explain. Confirm mode, scope, backend, and workspace access.
2. Ask: does the tool exist for this session? Check effective tool allow/deny. If the tool is denied, fix tool policy first. Do not touch approvals yet.
3. Ask: is this specifically host exec? If yes, then elevated and approvals matter. If no, they probably are not the layer you need.
4. Ask: is a host approval prompt failing? Inspect approvals with openclaw approvals get or openclaw exec-policy show. Remember that prompt fallback can deny when no UI is reachable.
5. Make the smallest config change. Do not disable sandboxing globally because one tool needs a narrower allowlist adjustment.

This order matters because it prevents over-correcting. The docs make it clear that OpenClaw has multiple safety layers by design. Treating every block as a reason to go permissive throws away the useful separation.

Common wrong fixes

“I enabled elevated but the tool is still blocked.”

Likely explanation: tool policy denied the tool. Elevated only affects exec; it does not grant access to arbitrary tools and does not override tool allow/deny.

“I changed /exec settings but exec is unavailable.”

/exec changes exec defaults for authorized senders. It does not grant a denied tool. If policy removed exec, fix policy.

“My group channel behaves differently than my direct main chat.”

In non-main sandbox mode, the docs say group and channel sessions use their own keys, so they count as non-main. That difference is expected.

“I mounted a folder and now the sandbox can see secrets.”

That is exactly what a bind mount can do. Bind mounts pierce the sandbox filesystem, and omitted modes default to read-write. Use :ro when you only need reads, and be intentional about every mounted path.

The operator takeaway

OpenClaw's safety model is easier to operate when you stop looking for one universal permission switch. Sandboxing answers “where does this run?” Tool policy answers “is this tool callable?” Exec approvals answer “may this host command proceed?” Elevated answers “should sandboxed exec escape to the host, and with which approval posture?”

Keep those questions separate and you will fix the right thing faster. Better, you will avoid the worst production habit: weakening every safety layer because one layer was misunderstood.

Originally published at https://www.openclawplaybook.ai/blog/openclaw-sandbox-approvals-tool-policy/

Get The OpenClaw Playbook → https://www.openclawplaybook.ai?utm_source=devto&utm_medium=article&utm_campaign=parasite-seo