🦞OpenClaw Guide
Security

Permissions, Sandbox & Security Settings

Configure sandbox isolation, tool permissions, exec security policies, and macOS permission grants for secure OpenClaw operation.

⚠️ The Problem

Users encounter various permission and security issues when running OpenClaw agents: sandboxed agents can't access web_search or web_fetch tools, exec commands fail silently or require constant approval dialogs, iMessage integration returns 'authorization denied' errors, and agents are either too restricted or have concerning levels of access to host systems.

🔍 Why This Happens

OpenClaw has a multi-layered security model that can be confusing:

  1. Sandbox tool policy is separate from agent tool allow/deny - Even if you add web_search to agents.list[].tools.allow, the sandbox has its OWN tool filter at tools.sandbox.tools that must also permit the tool.

  2. Sandbox network is disabled by default - Docker containers run with network: 'none' unless explicitly configured, so even allowed web tools will fail.

  3. Environment variables don't inherit into sandbox - API keys like BRAVE_API_KEY set on the host are invisible inside the sandboxed container.

  4. Exec security defaults to 'allowlist' mode - Commands require explicit approval unless security policy is changed.

  5. macOS Full Disk Access required for iMessage - The chat.db file is protected by macOS security and requires Terminal/IDE to have Full Disk Access.

  6. Exec approvals UI prompts on every command - The Allow Once / Always Allow / Don't Allow dialog appears for each new command pattern until allowlisted.

✅ The Fix

Understanding the Security Layers

OpenClaw has THREE permission gates for sandboxed agents:

  1. agents.list[].tools.allow/deny - Agent-level tool permissions
  2. tools.sandbox.tools.allow - Sandbox-level tool filter
  3. sandbox.docker.network - Network access for the container

Enable Web Search in Sandboxed Agents

You need to configure ALL layers. Here's a complete working config:

json5
{  agents: {    list: [      {        id: "research",        sandbox: {          mode: "all",          scope: "agent",          workspaceAccess: "rw",          docker: {            network: "bridge"  // REQUIRED - 'none' blocks all network          }        },        tools: {          allow: ["read", "write", "web_search", "web_fetch"],          deny: ["exec", "edit", "apply_patch", "process"]        }      }    ]  },  tools: {    sandbox: {      tools: {        // Add web tools here - default only includes fs/sessions        allow: ["group:fs", "group:sessions", "group:web"]      }    },    web: {      search: {        enabled: true,        apiKey: "YOUR_BRAVE_API_KEY"  // Must be in config, not env var!      },      fetch: { enabled: true }    }  }}

Common error when sandbox network is disabled:

bash
Error: web_search failed: getaddrinfo ENOTFOUND api.search.brave.com

Common error when sandbox tools not configured:

bash
I don't have access to the web_search tool.

Fix Exec Permission Issues

If exec commands fail silently or aren't working, check your security mode:

json5
// In your clawdbot.json or config:{  tools: {    exec: {      host: "sandbox",      // or "node" for host execution      security: "allowlist"  // Options: "deny", "allowlist", "full"    }  }}

Security modes explained:

  • deny - No exec allowed at all
  • allowlist - Only pre-approved commands work (requires approval UI)
  • full - All commands allowed (USE WITH CAUTION)

For development/trusted environments where you want exec to just work:

json5
{  tools: {    exec: {      host: "sandbox",      security: "full"    }  }}

⚠️ Warning: Only use security: "full" if you understand the risks. The agent can run ANY shell command.

Stop Exec Approval Dialogs

The 'Allow Once / Always Allow / Don't Allow' popup appears when exec security is set to allowlist mode.

Option 1: Pre-approve commands in the UI

  1. Open OpenClaw Control UI (or macOS menu bar app)
  2. Navigate to Nodes → Exec approvals
  3. Add command patterns to the allowlist
  4. Use wildcards: git *, npm *, brew *

Option 2: Switch to full security (trusted environments only)

json5
{  tools: {    exec: {      security: "full"    }  }}

Option 3: Use a command allowlist in config

json5
{  tools: {    exec: {      security: "allowlist",      allowlist: [        "git *",        "npm *",        "ls *",        "cat *",        "echo *"      ]    }  }}

Fix iMessage Permission Denied Errors

Error message:

bash
imsg rpc: failed to parse permissionDenied(path: "/Users/username/Library/Messages/chat.db", underlying: authorization denied (code: 23))

This is a macOS security issue. The process running OpenClaw needs Full Disk Access:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the + button
  3. Add the application running OpenClaw:
    • If running from Terminal: Add Terminal.app
    • If running from VS Code: Add Visual Studio Code
    • If running from iTerm: Add iTerm.app
  4. Restart the application after granting access
  5. Restart OpenClaw gateway
bash
# After granting Full Disk Access:openclaw gateway restart

Secure Setup for Trading/Sensitive Environments

If you have sensitive data on your machine (trading software, credentials, financial data):

1. Run OpenClaw in Docker with minimal mounts:

bash
docker run -d --name openclaw \  -v ~/openclaw/data:/data \  -v ~/openclaw/config:/config:ro \  --network bridge \  openclaw/openclaw:latest

2. Never mount your home directory or sensitive paths

3. Use read-only filesystem where possible:

json5
{  sandbox: {    workspaceAccess: "ro"  // Read-only workspace  }}

4. Block local network access:

Use firewall rules to prevent the container from accessing local IPs (192.168.x.x, 10.x.x.x).

5. Create a dedicated user with minimal permissions:

bash
sudo useradd -r -s /bin/false openclawsudo chown -R openclaw:openclaw /opt/openclaw

Debug Permission Issues

Run the status command to see effective permissions:

bash
openclaw status --all

This shows:

  • Effective tool policy
  • Sandbox configuration
  • Which config keys are blocking access

Disable Write Tool While Keeping Web Search

You CAN use web search without write access:

json5
{  agents: {    list: [{      id: "readonly-researcher",      tools: {        allow: ["read", "web_search", "web_fetch"],        deny: ["write", "edit", "exec"]      }    }]  }}

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
openclaw status --allShow effective tool policy, sandbox config, and permission status
openclaw gateway restartRestart gateway after changing permissions or config
openclaw logs --followWatch logs to debug permission errors in real-time
openclaw config validateValidate your configuration file for errors

Related Issues

    📚 You Might Also Like

    Blog

    OpenClaw Self-Audit: The Prompt That Checks Your Own Security Setup

    Most people set up OpenClaw, lock things down as best they can, and never check again. Meanwhile, configs drift, updates change settings, and new integration...

    Guide

    How to Configure OpenClaw: Complete Settings Guide (2026)

    Configure OpenClaw in ~/.openclaw/openclaw.json: API keys, model providers, channels (WhatsApp/Telegram/Discord), security, and multi-agent routing. Copy-paste examples included.

    Integration

    SharePoint & OneDrive

    Enterprise document management through conversation. Search across SharePoint sites and OneDrive, share files via chat, and work with enterprise content — all with proper permissions and compliance.

    Use Case

    AI Assistant for Realtors

    Never miss a lead again

    🐙 Your AI should run your business.

    Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

    Join Vibe Combinator →