OpenClaw Sandbox: Test Agent Workflows Without Breaking Anything

Every agent workflow has at least one path you haven't thought of. Sandbox mode lets you find it before your users do. Three hours in sandbox mode consistently catches more issues than a week of code review — because you're testing behavior, not reading logic.

How OpenClaw Sandbox Mode Works

Sandbox mode inserts an interception layer between the agent and every outbound action. When your agent decides to call a tool that writes data, sends a message, or executes a command, the sandbox layer catches the call, logs the full intended action, and returns a simulated success response to the agent.

The agent doesn't know it's sandboxed. It receives normal-looking responses and continues reasoning as if the action succeeded. This means you see the complete decision tree — including what the agent does after a successful write, which is often where the interesting bugs live.

Here's what gets intercepted:

• All file write and delete operations
• Shell command execution
• External API POST/PUT/DELETE calls made through tool integrations
• Message sends to Telegram, WhatsApp, email, and other channels
• Database write operations
• Any MCP tool operation classified as a write or action

Read operations are not intercepted. Search queries execute. File reads execute. API GET calls execute. This is intentional — you want real data flowing through the agent's reasoning so your test reflects actual conditions, not fabricated responses.

Enabling Sandbox Mode

There are three ways to enable sandbox mode, each appropriate for different situations.

Global gateway-level sandbox

Set sandbox: true in your gateway.yaml to sandbox every agent connected to this gateway. Use this when building a new agent system from scratch and nothing is production-ready yet.

# gateway.yaml
gateway:
  host: localhost
  port: 8080
  token: your-gateway-token
  sandbox: true          # All agents sandboxed
  sandbox_log: logs/sandbox.log

Per-agent sandbox flag

Pass --sandbox when starting a specific agent. The global setting in gateway.yaml stays as-is. This is the pattern for testing a new agent alongside existing production agents.

openclaw agent start \
  --name new-researcher \
  --bootstrap bootstrap-researcher.md \
  --sandbox

Environment variable

Set OPENCLAW_SANDBOX=true in your environment before starting an agent. Useful in CI pipelines where you can't modify gateway.yaml but need automated sandbox testing.

OPENCLAW_SANDBOX=true openclaw agent start --name test-agent

Reading Sandbox Logs

Every intercepted action writes a structured log entry to the sandbox log file. The default path is logs/sandbox.log relative to your working directory. Override it with sandbox_log in gateway.yaml.

# Stream sandbox log in real time
openclaw sandbox log --follow

# Filter to a specific tool
openclaw sandbox log --tool shell

# Show last 50 entries
openclaw sandbox log --tail 50

Each log entry includes the timestamp, agent name, tool name, action type, and the complete payload. Here's what a typical entry looks like:

[2025-02-27T14:23:11Z] SANDBOX INTERCEPT
  agent:   researcher-001
  tool:    shell
  action:  exec
  command: "rm -rf /data/old-reports/*.json"
  status:  intercepted (would have executed)
  sim_response: {"exit_code": 0, "stdout": "", "stderr": ""}

That rm -rf line is exactly the kind of thing you want to catch before production. And you will — because sandbox mode shows you every action the agent attempts, including the ones that happen three reasoning steps after the thing you were actually watching.

Selective Tool Sandboxing

Global sandbox mode is all-or-nothing. Sometimes you need something more surgical — real search results, real memory reads, but sandboxed writes. Configure this in tools.yaml by setting sandbox mode per tool.

# tools.yaml
tools:
  tavily-search:
    type: mcp
    server: tavily
    sandbox: false     # Search executes for real

  shell:
    type: builtin
    sandbox: true      # Shell commands are intercepted

  file-writer:
    type: mcp
    server: filesystem
    sandbox: true      # File writes are intercepted

  context7:
    type: mcp
    server: context7
    sandbox: false     # Doc lookups execute for real

This configuration gives you an agent that fetches real search results and real documentation, but logs rather than executes any shell commands or file writes. It's the right setup for validating that your agent is choosing the correct actions without actually taking them.

Graduating From Sandbox to Production

The graduation process should be deliberate, not just "remove the sandbox flag and hope." Here's a structured checklist we use before taking any agent live.

1. Run the agent in full sandbox mode against realistic test inputs for at least 20 turns
2. Review every intercepted action in the sandbox log — confirm each one is intentional
3. Identify any action the agent took that surprised you — add explicit prompt guidance to prevent it
4. Switch to selective tool sandboxing — sandbox writes, allow reads — and run another 20 turns
5. Enable exec approvals for any remaining write-capable tools before going fully live
6. Remove sandbox flags and monitor the first 50 live turns closely

Step 5 deserves emphasis. Exec approvals are a separate mechanism from sandbox mode — they require human confirmation before an action executes rather than silently intercepting it. Using both together during the graduation phase gives you a safety net even after sandbox mode is off.

Common Sandbox Mistakes

• Testing with fake data — agents behave differently with edge-case real data than with tidy test inputs. Always use realistic data sources for the read side of sandbox tests.
• Only testing the happy path — deliberately send your agent inputs that should trigger error handling, refusals, or fallback behaviors. Sandbox mode is the right time to stress-test these paths.
• Ignoring intercepted actions you don't recognize — if the sandbox log shows an action you didn't expect, investigate before graduating to production. Unexpected actions in sandbox always have a cause.
• Forgetting to disable sandbox before going live — it sounds obvious until the third time you wonder why your agent "works" but nothing is actually happening. Always confirm sandbox status with openclaw agent status.
• Not reviewing the full sandbox log before graduation — reading the last 10 entries isn't enough. Read the whole session log for any agent before you promote it to production.

Frequently Asked Questions

What does sandbox mode do in OpenClaw?

Sandbox mode intercepts all outbound actions — API calls, file writes, shell commands, message sends — and logs what would have happened instead of executing. Your agent runs its full reasoning loop, but nothing reaches the real world. This lets you validate logic without risk.

How do I enable OpenClaw sandbox mode?

Add sandbox: true to gateway.yaml under the gateway block, or pass --sandbox on the command line when starting an agent. The sandbox flag overrides per-tool settings, so every tool runs in intercepted mode regardless of individual configuration.

Does sandbox mode cost API tokens?

Yes. The agent's LLM calls still execute — you pay for reasoning, not for actions. Only the output actions are intercepted. Minimize token costs during testing by using shorter conversation turns and narrower task scopes rather than disabling LLM calls entirely.

Can I test MCP tools in sandbox mode?

Yes. MCP tools run normally in sandbox mode — read operations execute, but write and action operations are intercepted and logged. Search tools return real results; write tools log their intended actions without making changes. This split is what makes sandbox genuinely useful.

How do I see what actions were intercepted in sandbox mode?

Check the sandbox log at logs/sandbox.log or run openclaw sandbox log to stream it. Every intercepted action is recorded with timestamp, tool name, action type, and the full payload that would have been sent — detailed enough to diagnose any unexpected behavior.

Is there a way to selectively sandbox only certain tools?

Yes. In tools.yaml, set sandbox: true on individual tool entries rather than globally. This lets you sandbox destructive tools like shell while keeping read-only tools like search fully active — ideal for partial production testing where you want real data but safe writes.