Problem: OpenClaw Agent Won't Execute Shell Commands

Your OpenClaw agent refuses to run shell commands, returning "exec tool disabled" or permission errors even though you've granted system access during setup.

You'll learn:

Why OpenClaw blocks shell execution by default
How to enable exec tool with proper security boundaries
When to use sandbox vs elevated mode

Time: 12 min | Level: Intermediate

Why This Happens

OpenClaw's exec tool is disabled by default since January 2026 as a security measure. The agent can only run shell commands when explicitly enabled in your configuration, even if you accepted system access during initial setup.

Common symptoms:

Agent replies "I cannot execute shell commands" or "exec tool is not available"
Error in logs: tool "exec" denied by policy
Commands work in Terminal but fail when requested through chat
Process tool unavailable (depends on exec being enabled)

Solution

Step 1: Check Current Tool Policy

# View your OpenClaw configuration
openclaw status --all | grep -A 10 "tools:"

Expected: You should see your current tool allowlist. If exec or group:runtime isn't listed, the tool is blocked.

If you see no tools section: Your config is using the default restrictive policy.

Step 2: Enable Exec Tool

Choose one of three security levels:

Option A: Coding Profile (Recommended)

# Open config editor
openclaw configure

# Or edit directly
nano ~/.openclaw/openclaw.json

Add this to your config:

{
  "tools": {
    "profile": "coding",
    "deny": []
  }
}

Why this works: The coding profile enables group:fs (file operations), group:runtime (exec, bash, process), and group:sessions - everything you need for development tasks.

Option B: Selective Allowlist

If you want granular control:

{
  "tools": {
    "allow": ["exec", "process", "read", "write", "web_search"],
    "deny": []
  }
}

Why this works: Explicitly allows only the tools you specify. Use group:runtime as shorthand for exec, bash, and process.

Option C: Full Access (Use with Caution)

{
  "tools": {
    "profile": "full"
  }
}

Warning: This enables ALL tools including browser automation and gateway control. Only use on trusted private networks.

Step 3: Restart Gateway

# Apply configuration changes
openclaw gateway restart

Expected: Gateway restarts successfully without errors.

If it fails with config validation error:

# Validate and auto-repair config
openclaw doctor --fix
openclaw gateway restart

Step 4: Verify Exec Tool Works

Test with a simple command through your messaging interface (Telegram, WhatsApp, etc.):

You: Run this command: echo "Hello from OpenClaw"

Expected response:

Agent: Running command...
Output: Hello from OpenClaw

Alternative CLI test:

openclaw message send --target YOUR_NUMBER --message "Run: ls -la /tmp"

Advanced: Sandbox vs Elevated Mode

Sandbox Mode (Default)

Commands run inside Docker container - safer but limited access:

{
  "tools": {
    "profile": "coding"
  },
  "gateway": {
    "sandbox": {
      "enabled": true
    }
  }
}

Use when: You want isolation from your host system.

Elevated Mode (Host Access)

Commands run directly on your machine with full permissions:

{
  "tools": {
    "profile": "coding",
    "elevated": {
      "enabled": true,
      "ask": "on-miss"  // Prompts before first use
    }
  },
  "gateway": {
    "sandbox": {
      "enabled": false
    }
  }
}

Use when: You need access to host files, network services, or local development tools.

Security note: The agent can now modify your real filesystem. Set ask: "always" to approve each command.

Per-Command Elevated Access

Keep sandbox enabled but allow specific elevated commands:

{
  "tools": {
    "profile": "coding",
    "elevated": {
      "enabled": true,
      "ask": "on-miss",
      "allowlist": [
        "git *",
        "npm install",
        "docker ps"
      ]
    }
  }
}

When running a command:

You: Run this on the host: git status

Agent automatically uses elevated: true for allowlisted patterns.

Verification

Test All Three Modes

# 1. Sandbox mode (default)
You: "Create a file at /tmp/test.txt with content 'sandbox test'"
# Should work inside container

# 2. Elevated mode (if enabled)
You: "Show me the real /etc/hosts file"
# Should show your actual host file

# 3. Background processes
You: "Run a long task: sleep 30 && echo done"
# Should background after 10 seconds, use process tool to poll

You should see:

Successful file creation in sandbox
Host file access in elevated mode (if enabled)
Background process with sessionId for long commands

Common Errors

Error: "tool exec denied by policy"

Cause: Tool still disabled after config change.

Fix:

# Verify config applied
openclaw gateway status
# If running, restart is needed
openclaw gateway restart

Error: "sandbox: permission denied"

Cause: Docker container lacks permissions for host path.

Fix: Mount your workspace in docker-compose:

# docker-compose.yml or openclaw.json gateway.sandbox.volumes
volumes:
  - "${HOME}/workspace:/workspace"

Then restart:

docker-compose down
docker-compose up -d
openclaw gateway restart

Error: "process tool not available"

Cause: Process tool depends on exec being enabled.

Fix: Enable runtime group:

{
  "tools": {
    "allow": ["group:runtime"]  // Includes exec + process
  }
}

What You Learned

OpenClaw's exec tool requires explicit enablement in config
profile: "coding" is the recommended security baseline
Elevated mode grants host access but needs careful allowlisting
Background commands auto-yield after 10s and require process tool

Limitation: Config changes require gateway restart - active sessions may disconnect briefly.

Security tip: Use tools.elevated.ask: "always" in production to audit every command.

Quick Reference: Tool Groups

{
  "group:runtime": ["exec", "bash", "process"],
  "group:fs": ["read", "write", "edit", "apply_patch"],
  "group:web": ["web_search", "web_fetch"],
  "group:ui": ["browser", "canvas"],
  "group:automation": ["cron", "gateway"],
  "group:messaging": ["message"]
}

Use these shorthands in tools.allow or tools.deny to control multiple tools at once.

Tested on OpenClaw 1.2.x, Node.js 22.x, macOS 14+ & Ubuntu 24.04