Secure OpenClaw Agents: Sandbox and Tool Policy Guide

Ever felt like your agent is trapped in a box, or worse, running wild on your host machine when it shouldn’t? Managing permissions and execution environments can be a headache when you are trying to balance security with functionality.

Understanding how OpenClaw handles Sandbox environments, Tool Policy configurations, and Elevated permissions is crucial for building secure and capable agents. These three layers work together to ensure your tools run exactly where and how you want them to.

OpenClaw has three related (but different) controls:

1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) decides where tools run (sandbox backend vs host).
2. Tool policy (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) decides which tools are available/allowed.
3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) is an exec-only escape hatch to run outside the sandbox when you’re sandboxed (Gateway by default, or Node.js when the exec target is configured to Node.js).

Debug OpenClaw Sandbox settings with the CLI

When your configuration gets complex, you need a fast way to verify what settings are actually in effect. The OpenClaw CLI provides a powerful inspection tool to clear up any confusion about your current environment.

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

It prints:

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

Configure where tools run with OpenClaw Sandbox

The Sandbox environment is the foundation of your agent’s security, isolating execution to prevent unauthorized host access. Sandboxing is controlled by agents.defaults.sandbox.mode and determines which sessions are restricted.

1. "off": everything runs on the host.
2. "non-main": only non-main sessions are sandboxed (common “surprise” for groups/channels).
3. "all": everything is sandboxed.

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

Bind mounts (security quick check)

1. docker.binds pierces the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (:ro or :rw).
2. Default is read-write if you omit the mode; prefer :ro for source/secrets.
3. scope: "shared" ignores per-agent binds (only global binds apply).
4. 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.
5. Non-existent leaf paths are still checked safely. If /workspace/alias-out/new-file resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
6. Binding /var/run/docker.sock effectively hands host control to the sandbox; only do this intentionally.
7. Workspace access (workspaceAccess: "ro"/"rw") is independent of bind modes.

Manage tool access using OpenClaw Tool Policy

Defining which tools an agent can use is just as important as where those tools are executed. The Tool Policy system in OpenClaw allows you to create strict allowlists or denylists to manage your API surface area.

Two layers matter:

1. Tool profile: tools.profile and agents.list[].tools.profile (base allowlist)
2. Provider tool profile: tools.byProvider[provider].profile and agents.list[].tools.byProvider[provider].profile
3. Global/per-agent tool policy: tools.allow/tools.deny and agents.list[].tools.allow/agents.list[].tools.deny
4. Provider tool policy: tools.byProvider[provider].allow/deny and agents.list[].tools.byProvider[provider].allow/deny
5. Sandbox tool policy (only applies when sandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny and agents.list[].tools.sandbox.tools.*

Rules of thumb:

1. deny always wins.
2. If allow is non-empty, everything else is treated as blocked.
3. Tool policy is the hard stop: /exec cannot override a denied exec tool.
4. /exec only changes session defaults for authorized senders; it does not grant tool access.
5. Provider tool keys accept either provider (e.g. google-antigravity) or provider/model (e.g. openai/gpt-5.4).

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support group:* entries that expand to multiple tools:

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

Available groups:

1. group:runtime: exec, process, code_execution (bash is accepted as an alias for exec)
2. group:fs: read, write, edit, apply_patch
3. group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
4. group:memory: memory_search, memory_get
5. group:web: web_search, x_search, web_fetch
6. group:ui: browser, canvas
7. group:automation: cron, Gateway
8. group:messaging: message
9. group:nodes: nodes
10. group:agents: agents_list
11. group:media: image, image_generate, video_generate, tts
12. group:openclaw: all built-in OpenClaw tools (excludes provider plugins)

Run host commands using OpenClaw Elevated mode

Sometimes a sandboxed tool needs to perform an action that requires host-level access without compromising your entire security setup. Elevated mode provides a controlled way to run specific commands outside the container.

Elevated does not grant extra tools; it only affects exec.

1. If you’re sandboxed, /elevated on (or exec with elevated: true) runs outside the sandbox (approvals may still apply).
2. Use /elevated full to skip exec approvals for the session.
3. If you’re already running direct, Elevated is effectively a no-op (still gated).
4. Elevated is not skill-scoped and does not override tool allow/deny.
5. Elevated does not grant arbitrary cross-host overrides from host=auto; it follows the normal exec target rules and only preserves Node.js when the configured/session target is already Node.js.
6. /exec is separate from Elevated. It only adjusts per-session exec defaults for authorized senders.

Gates:

1. Enablement: tools.elevated.enabled (and optionally agents.list[].tools.elevated.enabled)
2. Sender allowlists: tools.elevated.allowFrom.<provider> (and optionally agents.list[].tools.elevated.allowFrom.<provider>)

See Elevated Mode.

Fix common OpenClaw sandbox jail issues

Running into permission errors or unexpected blocks can be frustrating when you are testing new tools. These common solutions will help you break out of a sandbox jail and get your agent back on track.

”Tool X blocked by sandbox tool policy”

Fix-it keys (pick one):

1. Disable sandbox: agents.defaults.sandbox.mode=off (or per-agent agents.list[].sandbox.mode=off)
2. Allow the tool inside sandbox:

• remove it from tools.sandbox.tools.deny (or per-agent agents.list[].tools.sandbox.tools.deny)
• or add it to tools.sandbox.tools.allow (or per-agent allow)

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

In "non-main" mode, group/channel keys are not main. Use the main session key (shown by sandbox explain) or switch mode to "off".

Explore related OpenClaw documentation

If you need more details on specific configurations or advanced setups, these resources will help you expand your knowledge. You can find deep dives into the technical matrix and per-agent overrides here.

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

AI Setup Assistant