Permissions, Sandbox & Security Settings

## 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:

{  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: `` Error: web_search failed: getaddrinfo ENOTFOUND api.search.brave.com

Common error when sandbox tools not configured: `` 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:

// 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:

{  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)

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

Option 3: Use a command allowlist in config

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

## Fix iMessage Permission Denied Errors Error message: `` 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

# 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:

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:

{  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:

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

## Debug Permission Issues Run the status command to see effective permissions:

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:

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