Lesson 2. Security#

Why you need this#

An AI assistant can run commands on your computer: read files, launch programs, access the internet. This is powerful but also dangerous — the model can make mistakes or do something undesirable. OpenClaw offers three levels of protection so you stay in control.

Three levels of protection#

OpenClaw has three different (but related) security mechanisms:

1. Sandbox — WHERE commands are executed#

A sandbox is an isolated environment, like a room with no windows or doors. The assistant can do anything inside, but can’t reach the rest of the system.

Technically, it’s a Docker container — a special “virtual box” on your computer.

Operating modes (setting agents.defaults.sandbox.mode):

Scope — how many containers are created:

• "session" — a separate container for each conversation
• "agent" — one container per assistant (default)

Example of enabling the sandbox:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent"
      }
    }
  }
}

2. Tool Policy — WHICH tools are available#

Even if the assistant works in a sandbox, you can restrict which tools it uses.

Two lists:

• allow — if specified, ONLY the listed tools are available
• deny — these tools are always blocked

Rule: deny always beats allow. If a tool is in both lists — it’s blocked.

Example — allow only file reading:

{
  tools: {
    sandbox: {
      tools: {
        allow: ["read", "exec", "process"],
        deny: ["browser", "canvas", "nodes", "cron"]
      }
    }
  }
}

Tool groups (shortcuts):

Instead of listing each tool, you can use groups:

3. Elevated — escaping the sandbox#

Elevated is an “emergency exit” from the sandbox, only for the exec command.

If the assistant works in a sandbox but needs to do something on the main computer, you can temporarily allow it:

• /elevated on — allow execution on the host (with confirmation)
• /elevated full — allow without confirmations (for experienced users)

Elevated does not grant access to new tools — it only lets exec work outside the sandbox.

Configuration setting:

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        telegram: ["tg:123456789"]  // who can use it
      }
    }
  }
}

Bind mount security#

If you mount host folders into the sandbox (via docker.binds), remember:

• By default, folders are mounted with full access (read and write)
• Add :ro for read-only: "/home/user/docs:/docs:ro"
• Never mount /var/run/docker.sock — this gives full control over the system

How to check current settings#

OpenClaw has a built-in security inspector:

openclaw sandbox explain
openclaw sandbox explain --agent work
openclaw sandbox explain --json

It will show:

• Current sandbox mode
• Which tools are allowed/blocked
• Elevated settings

What to do if a tool is blocked#

If you see “Tool X blocked by sandbox tool policy”:

1. Disable the sandbox: agents.defaults.sandbox.mode = "off"
2. Allow the tool: add to tools.sandbox.tools.allow
3. Remove from deny: remove from tools.sandbox.tools.deny

Practical recommendations#

Lesson summary#

• Sandbox isolates execution in a Docker container — protection from AI mistakes
• Tool policy restricts which tools are available at all
• Elevated is an emergency exit from the sandbox, only for exec
• Use openclaw sandbox explain to check current settings
• Deny always beats allow
• Use different sandbox modes for different trust levels