How OpenClaw’s Sandbox and Memory Architecture Powers Secure AI Agents

Sandbox System

OpenClaw isolates tool execution in Docker containers, preventing direct host access.

Purpose

Limit tool operations (exec, read, write, edit) to a secure boundary.

Reduce the "blast radius" of accidental model actions.

Provide configurable isolation levels.

Key File Structure

src/agents/sandbox/
├── types.ts          // Core type definitions
├── config.ts         // Configuration merging logic
├── context.ts        // Entry point – parse sandbox context
├── docker.ts         // Docker container management
├── browser.ts        // Isolated browser container
├── tool-policy.ts    // Tool allow/deny policy
├── validate-sandbox-security.ts // Security validation
├── fs-bridge.ts      // File system operation bridge
└── prune.ts          // Automatic container cleanup

Sandbox Modes

"off" : No isolation; tools run directly on the host.

"non-main" : Isolate all non‑main sessions (default).

"all" : Isolate every session.

Container Scope

"session" : One container per session (default).

"agent" : One container per agent.

"shared" : All sessions share a single container.

Workspace Access Permissions

"none" : No workspace mounted (isolated at ~/.openclaw/sandboxes).

"ro" : Read‑only mount of the agent workspace at /agent.

"rw" : Read‑write mount at /workspace.

Security Restrictions

Prohibited bind mounts: /etc, /proc, /sys, /dev, /root, /boot, /run.

Prohibited Docker socket: /var/run/docker.sock.

Root filesystem is read‑only.

Default security config drops all capabilities, disables network access, and sets the container as read‑only.

Tool Policy Hierarchy

Global tool policy.

Agent‑specific policy.

Sandbox tool policy (further restriction).

Sub‑agent policy.

Default allowed tools: exec, read, write, edit, apply_patch, image. Default disallowed tools: browser, canvas, nodes, cron, gateway and all message channels.

Sandbox Configuration Example

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none",
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "network": "none",
          "memory": "512m",
          "cpus": 1
        },
        "prune": {
          "idleHours": 24,
          "maxAgeDays": 7
        }
      }
    }
  }
}

CLI Commands for Sandbox

openclaw sandbox list

– List sandbox containers. openclaw sandbox recreate – Force rebuild a container. openclaw sandbox explain – Show the effective configuration for debugging.

Memory Management

OpenClaw stores long‑term memory in human‑readable Markdown files and uses a SQLite database with vector embeddings for fast semantic search.

File Layout

~/.openclaw/workspace/
├── MEMORY.md          # Persistent long‑term memory (selected, durable)
└── memory/
    └── YYYY-MM-DD.md  # Daily append‑only logs

Hybrid Search Process

User query
 ↓
Keyword extraction (FTS) + vector embedding
 ↓
Parallel search:
   • Vector similarity
   • BM25 keyword match
 ↓
Score weighting (vectorWeight=0.7, textWeight=0.3)
 ↓
Post‑processing:
   • Time decay (half‑life 30 days)
   • MMR deduplication (λ=0.7)
 ↓
Top‑K results

Embedding Providers

OpenAI – text-embedding-3-small (default).

Gemini – gemini-embedding-001.

Voyage – voyage-4-large.

Mistral – mistral-embed.

Local – custom model path.

Provider selection prefers a local model if present; otherwise it falls back to the first available API key.

Session Management

Sessions are identified by keys such as agent:main:telegram:direct:user123. Supported scopes include direct, group, channel, cron, sub‑agent, and thread. Keys are normalized to lower case.

Lifecycle

Parse agent ID.

Load session store (per‑agent JSON files).

Detect reset triggers ( /new, /reset).

Evaluate freshness based on configurable hours.

Fork child sessions when needed (e.g., thread isolation).

Persist session files.

Archive old transcripts on reset.

Reset Policy Example

{
  "direct": 24,
  "group": 4,
  "thread": 24
}

Routing

OpenClaw routes incoming messages using a prioritized binding list: peer → guild+roles → guild → team → account → channel → default. The routing table is deterministic and extensible.

Skills System

Skills are Markdown files with YAML front‑matter that describe additional capabilities. They are loaded from multiple locations with a clear priority order.

Directory Structure

src/agents/skills/
├── types.ts
├── config.ts
├── workspace.ts
├── frontmatter.ts
├── filter.ts
├── bundled-dir.ts
├── bundled-context.ts
├── plugin-skills.ts
├── refresh.ts
├── env-overrides.ts
├── serialize.ts
├── tools-dir.ts
└── skills-install.ts

Loading Order (low → high priority)

extra (user‑specified directories).

bundled (built‑in skills).

managed ( ~/.openclaw/skills).

agents‑skills‑personal ( ~/.agents/skills).

agents‑skills‑project (project‑specific).

workspace ( ./skills).

Node Architecture

Nodes are remote clients (mobile, desktop, or any device running openclaw node) that execute commands on behalf of the gateway. Pairing uses a token and node ID; optional APNS wake‑up is available for iOS devices.

Core Types

NodeListNode – Displays node capabilities (caps, commands, permissions).

NodeSession – WebSocket session state.

NodePairingPairedNode – Persisted pairing record (node ID, token, gateway).

Command Policy

Commands must be listed in a node’s allowlist and declared in its manifest. Sensitive commands (e.g., camera, screen, SMS) require extra approval.

Security Measures

Pairing authentication using node ID and token.

Platform‑specific command whitelist.

Environment sanitisation to avoid PATH poisoning.

Output size limited to 200 KB.

Configuration Management

OpenClaw loads a JSON5 configuration that supports comments, trailing commas, environment‑variable interpolation, and $include modularisation.

Loading Pipeline

Read the raw file.

Resolve $include directives (max depth 10, path‑inside checks).

Substitute ${VAR} using process.env.

Validate with a strict Zod schema (cross‑field checks).

Apply defaults for models, agents, and sessions.

Normalise all paths.

Security Features

Prototype‑pollution protection (blocks __proto__, constructor, prototype).

Sensitive values are marked and redacted in logs.

File permissions: directories 0o700, files 0o600.

Audit log records every write with hash, size change, and suspicious‑flag detection.

Overall Design Principles

Deterministic routing – the same input always yields the same agent.

Explicit priority hierarchy for policies and bindings.

Strong sandbox boundaries for tool execution.

Hybrid memory search combining semantic vectors and BM25.

Extensible plugin and skill system.

Local‑first data ownership (files are the source of truth).