Sandbox vs Tool Policy vs Elevated

+15 Mana ✨
OpenClaw Security(DOCUMENTATION)

Introduction

OpenClaw provides three distinct security mechanisms that work together: sandbox modes, tool policies, and elevated mode. Each operates at a different level, and understanding how they compose is essential for building a secure multi-agent system.

Key Concepts

  • Sandbox Mode: Controls the execution environment for commands (off, basic, strict). Operates at the system level.
  • Tool Policy: Controls which tools an agent can use (allow/deny lists). Operates at the agent level.
  • Elevated Mode: Temporarily grants higher privileges for specific operations. Operates at the operation level.
  • Defense in Depth: Using all three mechanisms together creates multiple layers of security.

Real World Context

A bank's compliance team runs an OpenClaw agent for code auditing. The sandbox is set to strict (isolated execution), the tool policy only allows file_read and grep (no file writing or shell access), and elevated mode is available for authorized personnel to temporarily grant write access when a fix is needed. This three-layer approach ensures that even if one mechanism is bypassed, the others still provide protection.

Deep Dive

The three mechanisms operate at different levels:

┌─────────────────────────────────────┐
│  Elevated Mode (operation level)    │  ← Temporary privilege escalation
├─────────────────────────────────────┤
│  Tool Policy (agent level)          │  ← Which tools are available
├─────────────────────────────────────┤
│  Sandbox Mode (system level)        │  ← How commands execute
└─────────────────────────────────────┘

Sandbox mode is the foundation. It controls the execution environment:

json
{
  "sandbox": {
    "mode": "strict",
    "scope": "tree"
  }
}

With strict sandboxing, even if an agent has the bash tool, commands run in an isolated environment with no network access and limited filesystem visibility.

Tool policy sits above the sandbox and controls what tools are available:

json
{
  "tools": {
    "allow": ["file_read", "grep", "lint"],
    "deny": ["bash", "file_write", "deploy"]
  }
}

Even with sandbox mode off, a tool policy that denies bash prevents the agent from executing arbitrary commands.

Elevated mode is a temporary override that grants higher privileges for a specific operation:

json
{
  "elevated": {
    "enabled": true,
    "requiresApproval": true,
    "timeout": 300
  }
}

When elevated mode is enabled, an authorized user can temporarily grant an agent access to denied tools. The requiresApproval flag means a human must approve each elevation. The timeout (in seconds) automatically revokes elevated privileges after 5 minutes.

Common Pitfalls

  1. Relying on only one mechanism — Sandbox alone does not prevent tool misuse. Tool policy alone does not restrict how commands execute. Use all three.
  2. Leaving elevated mode without a timeout — An elevated session without a timeout remains privileged indefinitely, defeating its purpose.

Best Practices

  1. Apply defense in depth — Use strict sandbox + restrictive tool policy + gated elevated mode for maximum security.
  2. Audit elevated mode usage — Log every elevation event for security review.

Summary

  • Sandbox mode controls the execution environment at the system level
  • Tool policy controls which tools are available at the agent level
  • Elevated mode provides temporary privilege escalation at the operation level
  • All three mechanisms compose for defense-in-depth security
  • Always use timeouts and approval gates for elevated mode
✓ Completed