OpenClaw Sandbox Isolation Environment Configuration

Overview

OpenClaw's sandbox isolation environment is a critical component for ensuring system security. When an AI agent executes tool operations, the sandbox ensures these operations don't compromise the host system's security or stability. This article covers the three core sandbox capabilities in detail: tool path constraints, container execution, and browser bridge configuration.

Sandbox Architecture

Since OpenClaw directly embeds the Pi coding agent SDK (rather than invoking it as a subprocess), the sandbox mechanism is deeply integrated into the tool execution layer. Every tool call goes through sandbox checks — after permission verification is completed during the policy filtering stage of the seven-stage tool pipeline, runtime constraints from the sandbox are still applied during actual execution.

Tool Path Constraints

Basic Concept

Path constraints limit the file system scope that tools can access. By declaring allowed path prefixes in the configuration file, you can precisely control the file operation boundaries of the AI agent.

Configuration

In the OpenClaw configuration file, use the sandbox.allowedPaths field to declare accessible paths:

sandbox:
  allowedPaths:
    - /home/openclaw/workspace
    - /tmp/openclaw
  deniedPaths:
    - /etc
    - /var/log
    - /home/openclaw/.ssh
  maxFileSize: 10MB
  maxDepth: 10

Path Resolution Rules

The sandbox normalizes paths during checks: resolving symbolic links, eliminating .. path traversals, and unifying path separators. This means attempts to bypass constraints via paths like ../../etc/passwd are ineffective.

Temporary File Handling

Temporary files generated during tool execution are stored by default in /tmp/openclaw/<session-id>/. Each session has its own temporary directory, which is automatically cleaned up by the sandbox when the session ends.

Container Execution

Container Isolation Mode

For scenarios that require executing arbitrary code (such as code execution skills), OpenClaw supports running tool operations inside containers. Container execution provides a stronger isolation level than path constraints alone.

Configuring the Container Runtime

sandbox:
  containerExec:
    enabled: true
    runtime: docker
    image: openclaw/sandbox:latest
    memoryLimit: 512m
    cpuLimit: 1.0
    networkMode: none
    timeout: 30s

Key Parameter Descriptions

• runtime: Container runtime, supports Docker and Podman
• image: Sandbox container image; official prebuilt images include common programming language runtimes
• memoryLimit: Memory cap to prevent resource exhaustion attacks
• cpuLimit: CPU usage limit
• networkMode: Network mode; none means completely isolated networking, restricted allows limited external access
• timeout: Execution timeout; the container is forcefully terminated if exceeded

File System Mounts

During container execution, the sandbox mounts necessary files into the container in read-only mode. Output files produced by tools are mapped back to the host system through a dedicated output directory.

sandbox:
  containerExec:
    mounts:
      - source: /home/openclaw/workspace
        target: /workspace
        readonly: true
      - source: /tmp/openclaw/output
        target: /output
        readonly: false

Browser Bridge

Bridge Mechanism

OpenClaw's browser tool needs to interact with a real browser instance. The sandbox establishes a controlled communication channel through the browser bridge URL, allowing the AI agent to operate the browser while preventing browser operations from escaping the sandbox boundaries.

Configuring the Browser Bridge

sandbox:
  browserBridge:
    enabled: true
    bridgeUrl: "ws://localhost:9222"
    allowedDomains:
      - "*.example.com"
      - "docs.openclaw.com"
    blockedDomains:
      - "*.internal.corp"
    maxTabs: 3
    maxPageLoadTime: 15s
    screenshotFormat: png
    screenshotQuality: 80

Domain Filtering

The browser bridge supports domain whitelists and blocklists. Only domains on the allow list can be accessed, preventing the AI agent from using the browser to reach internal network resources or sensitive services.

Bridge Security

The browser bridge communicates via WebSocket protocol. Token verification is required when establishing a connection, with each session having its own unique token. The bridge layer also intercepts dangerous operations such as downloading executables or accessing the file:// protocol.

Sandbox Monitoring

Resource Usage Monitoring

The sandbox continuously monitors resource usage at runtime:

• File system operation count and total data volume
• Container CPU and memory usage
• Browser bridge network traffic
• Tool call frequency

Alert Configuration

When resource usage approaches limits, the system triggers alerts. You can set alert thresholds and notification methods in the configuration.

Troubleshooting

Common sandbox-related issues:

1. Path access denied: Check whether allowedPaths includes the target path; pay attention to symbolic link resolution
2. Container startup failure: Confirm the container runtime is installed and the image has been pulled
3. Browser bridge timeout: Verify the browser instance is running normally and the bridge URL is correct
4. Resource limit exceeded: Adjust memoryLimit and cpuLimit parameters

Summary

OpenClaw's sandbox mechanism provides three layers of protection through path constraints, container execution, and browser bridging, ensuring system security while preserving the AI agent's capabilities. Properly configuring these three dimensions achieves the optimal balance between security and functionality.