Sandboxing & Tool Policies

Introduction

Sandboxing and tool policies form the innermost security layer in OpenClaw, controlling exactly what an agent can do once a message passes authentication and scope checks. Even a legitimate user in an allowed channel should not have unrestricted access to every tool and file on the system. This lesson covers sandbox modes, scopes, workspace access levels, and the built-in tool profiles that make policy management practical.

Key Concepts

• Sandbox mode -- the top-level switch that determines whether sandboxing is active (off or all)
• Sandbox scope -- the isolation boundary: agent (per-agent), session (per-conversation), or shared (all agents share one sandbox)
• Workspace access -- the level of filesystem access granted inside the sandbox: none, ro (read-only), or rw (read-write)
• Tool profile -- a predefined set of allowed tools: minimal, messaging, coding, or full
• Deny list -- an explicit list of tools that are blocked regardless of the active profile
• Control-plane tools -- administrative tools (gateway configuration, agent lifecycle, runtime management) that should never be exposed to untrusted agents

Real World Context

Think of sandboxing like a laboratory cleanroom. The sandbox mode is whether the cleanroom is active. The scope determines whether each researcher gets their own room or they share one. Workspace access is like granting read-only access to reference binders versus letting researchers modify the master copies. Tool profiles are the approved equipment lists posted on the wall. You would never let a visiting intern use the same equipment as a senior researcher working on classified materials.

Deep Dive

Sandbox Modes

The sandbox mode is a binary switch at the top level:

yaml
sandbox:
  mode: all    # every agent runs inside a sandbox
  # mode: off  # no sandboxing (development only)

When mode is all, every agent process is confined to its sandbox boundary. When off, agents run with the same privileges as the OpenClaw process itself. You should never use off in production.

Sandbox Scope

Scope determines the isolation granularity:

yaml
sandbox:
  mode: all
  scope: session   # each conversation gets its own sandbox

Here is what each scope level means:

• agent -- one sandbox per agent definition. All conversations with that agent share the same sandbox. Use this when the agent needs persistent state across conversations.
• session -- one sandbox per conversation session. Each new DM thread or group interaction gets a fresh, isolated environment. This is the safest option for multi-user deployments.
• shared -- all agents share a single sandbox. Only appropriate when agents are cooperating on the same task and full trust exists between them.

The session scope pairs naturally with dmScope: per-channel-peer from the scope layer, creating complete isolation between users.

Workspace Access

Workspace access controls what the sandboxed agent can see and modify on the filesystem:

yaml
sandbox:
  mode: all
  scope: session
  workspaceAccess: ro   # agent can read project files but not modify them

The three levels are:

• none -- the agent has no access to the host filesystem. It can only use tools and in-memory data.
• ro -- read-only access. The agent can inspect files, read configuration, and analyze code, but cannot write or delete anything.
• rw -- full read-write access. The agent can create, modify, and delete files within the workspace.

For a code-review agent, ro is appropriate. For a coding assistant that writes files, rw is needed but should be combined with a restrictive tool profile.

Tool Profiles

Tool profiles are curated sets of allowed tools that match common agent roles:

yaml
agents:
  reviewer:
    toolProfile: messaging   # can read/send messages, no code execution
  coder:
    toolProfile: coding      # can read/write files, run builds
  admin:
    toolProfile: full        # unrestricted (trusted agents only)

The four profiles are ordered from least to most permissive:

Deny Lists

Even within a profile, you can explicitly block specific tools:

yaml
agents:
  coder:
    toolProfile: coding
    denyTools:
      - automation:schedule    # no cron-like scheduling
      - runtime:restart        # cannot restart services
      - fs:delete              # cannot delete files

Deny lists override the profile -- if a tool is in the deny list, it is blocked even if the profile would normally allow it. This is how you prevent untrusted agents from accessing control-plane tools. As a rule, any agent that receives input from external users should have automation, runtime, and fs:delete in its deny list.

Composing Sandbox and Tool Policies

The sandbox and tool policy work together:

yaml
sandbox:
  mode: all
  scope: session
  workspaceAccess: ro

agents:
  helper:
    toolProfile: messaging
    denyTools:
      - automation:schedule
      - runtime:restart

This configuration means the helper agent runs in a per-session sandbox, can read workspace files but not modify them, can send messages but not execute code, and is explicitly blocked from scheduling tasks or restarting services.

Common Pitfalls

• Using shared scope in multi-user environments -- all agents and sessions see each other's data, which defeats isolation and enables cross-user leakage
• Granting rw workspace access with the full tool profile -- this combination gives the agent nearly unrestricted power and should only be used for fully trusted internal agents
• Forgetting to deny control-plane tools for external-facing agents -- an attacker who can prompt-inject a message could reconfigure the gateway or restart services if these tools are available

Best Practices

• Default to session scope and ro workspace access -- start restrictive and open up only for agents that genuinely need more
• Always add explicit deny lists for control-plane tools -- even if the current profile does not include them, deny lists act as a safety net against profile changes
• Match the tool profile to the agent's actual role -- a Q&A bot does not need coding; giving it more tools than necessary only widens the attack surface

Summary

• Sandbox mode should be all in production; off is for development only
• Sandbox scope controls isolation granularity: agent, session, or shared, with session being the safest for multi-user deployments
• Workspace access levels (none, ro, rw) control filesystem visibility inside the sandbox
• Tool profiles (minimal, messaging, coding, full) provide predefined permission sets that match common agent roles
• Deny lists override profiles and should always block control-plane tools for agents that handle external input