Skip to content
BSWEN
Blog

What Is the Difference Between OpenClaw Exec Tool Modes: Sandbox, Gateway, and Full?

Cowrie
Cowrie
Dev @ Bswen

I deployed an AI agent to my production server last week. Gave it full shell access. Within an hour, it had deleted my nginx configs and was trying to install npm packages globally.

That’s when I learned about OpenClaw’s exec tool modes.

The Problem

The exec tool is OpenClaw’s most powerful feature. It lets your AI agent run shell commands. Install packages. Process files. Deploy code. It’s also the most dangerous.

+-------------------+     +------------------+
|   AI Agent        |---->|   Shell Access   |
+-------------------+     +------------------+
                                  |
                                  v
                    +---------------------------+
                    |  What could go wrong?     |
                    +---------------------------+
                    | - Delete wrong files      |
                    | - Install malware         |
                    | - Expose secrets          |
                    | - Break production        |
                    +---------------------------+

I needed to understand the three modes before I broke anything else.

Mode 1: Sandbox (The Safe Default)

Sandbox mode runs commands inside a Docker container. Isolated from your main system.

openclaw-config.yaml
exec:
  mode: sandbox
  sandbox_image: "openclaw/sandbox:latest"

I tried this first. The agent ran rm -rf /tmp/* and my actual tmp folder stayed intact.

Pros:

  • Complete isolation from host system
  • Can’t access your files or secrets
  • Can’t break your server
  • Agent can still install packages and run scripts

Cons:

  • Slight performance overhead
  • Can’t access files on your actual machine
  • Need to mount volumes if you want file access

When to use:

  • Production servers with real data
  • Testing new agent behaviors
  • Any environment where you can’t afford mistakes

Mode 2: Gateway (Controlled Flexibility)

Gateway mode runs directly on your server but with a whitelist. You control which commands are allowed.

exec-approvals.json
{
  "allowed_commands": [
    "ls",
    "cat",
    "grep",
    "find",
    "npm run build",
    "python3 scripts/*.py"
  ],
  "blocked_patterns": [
    "rm -rf /",
    "sudo",
    "chmod 777"
  ]
}

I switched to gateway mode when I needed the agent to access my project files. The whitelist took some tuning.

First attempt, I allowed npm. Agent tried npm install -g some-sketchy-package. Blocked. Good.

Then I got too permissive:

exec-approvals.json (TOO PERMISSIVE)
{
  "allowed_commands": [
    "*"
  ]
}

That’s basically full mode with extra steps. Don’t do this.

The right approach:

exec-approvals.json (CORRECT)
{
  "allowed_commands": [
    "ls -la",
    "cat *.md",
    "grep -r *.py",
    "npm run *",
    "git status",
    "git diff"
  ],
  "require_approval_for": [
    "npm install",
    "pip install",
    "git push"
  ]
}

When to use:

  • Development environments
  • When you need file system access
  • When you want to audit commands before execution
  • Teams where multiple people manage the agent

Mode 3: Full (The Dangerous One)

Full mode gives unrestricted shell access. No whitelist. No sandbox.

openclaw-config.yaml
exec:
  mode: full  # DANGER ZONE

I tested this on a throwaway VPS. The agent created files in /etc, installed packages globally, and had access to every environment variable.

When to use:

  • Local development only
  • Throwaway environments
  • Never on production

The OpenClaw docs are blunt about this: “Fine for experimenting, not for a live server with anything real on it.”

My Trial and Error Journey

Here’s how I approached it, mistakes included.

Attempt 1: Full mode on production

Terminal window
# What I did
exec:
  mode: full


# What happened
Agent ran: curl https://some-url | bash
Result: Installed unverified code on my server

Lesson learned: Never use full mode on production.

Attempt 2: Sandbox without volume mounts

Terminal window
# What I did
exec:
  mode: sandbox


# What happened
Agent ran: cat project/app.py
Result: File not found (it's inside the container, not on host)

Lesson learned: Sandbox needs volume mounts for file access.

openclaw-config.yaml
exec:
  mode: sandbox
  sandbox_volumes:
    - ./project:/app/project:ro  # read-only for safety

Attempt 3: Gateway with weak whitelist

Terminal window
# What I did
allowed_commands: ["*"]


# What happened
Same risk as full mode

Lesson learned: A weak whitelist defeats the purpose.

Final Configuration:

openclaw-config.yaml
exec:
  mode: sandbox
  sandbox_image: "openclaw/sandbox:latest"
  sandbox_volumes:
    - ./src:/app/src:ro
    - ./output:/app/output:rw
  timeout: 300

Decision Flow

+------------------------+
| Do you need exec tool? |
+------------------------+
           |
           v
    +-------------+
    | Production? |
    +-------------+
     |          |
    YES        NO
     |          |
     v          v
+----------+  +----------+
| Sandbox  |  | Gateway  |
+----------+  +----------+
              or Full
              (if local)

Key Takeaways

  1. Sandbox is your default - Use it for production, testing, anything that matters
  2. Gateway needs tuning - Start restrictive, add commands as needed
  3. Full mode is for experiments only - Never on servers with real data
  4. Whitelist granularity matters - npm allows npm install -g malware, use npm run * instead

The exec tool gives your AI agent real power. Choose the mode that matches your risk tolerance.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: