OpenClaw Experts
Technical

Tool Policy Configuration: Building Deny-by-Default Access Control

OpenClaw Experts
••11 min read

What Are Tool Policies?

Tool policies define which tools your OpenClaw agent can and cannot use. They're your enforcement mechanism for limiting what your agent can do, even if a prompt injection or buggy skill tries to make it do something dangerous.

Tool Policies vs SOUL.md

SOUL.md tells the model not to try something.
Tool policies prevent the model from actually doing it.

Together, they create defense-in-depth: the model refuses at the reasoning level (SOUL.md), and the runtime enforces it (tool policy).

Core Principle: Deny-by-Default

The only safe approach is deny-by-default:

  • All tools are DENIED by default (blocked unless explicitly allowed)
  • You explicitly ALLOW only the tools your workflows need
  • Any new tool or skill is automatically blocked until you review it

Never use an allow-by-default policy where all tools are enabled except a blacklist. This is how you get compromised.

Tool Policy Configuration

Basic Structure


# ~/.openclaw/tool-policy.yml
version: '1.0'

# Default policy: DENY everything
default_action: 'DENY'

# Explicitly allow specific tools
allowed_tools:
  # Example: allow web requests to specific domains
  - name: 'make_http_request'
    restrictions:
      allowed_hosts:
        - 'api.example.com'
        - 'data.example.com'
      denied_hosts:
        - '169.254.169.254'  # AWS metadata endpoint
        - '127.0.0.1'        # Localhost
      timeout: 30

  # Example: allow file reading only in sandbox
  - name: 'read_file'
    restrictions:
      allowed_paths:
        - '/home/user/openclaw/sandbox/*'
      denied_paths:
        - '/home'
        - '/root'
        - '/.ssh'
        - '/etc/passwd'

# Block specific dangerous tools explicitly
blocked_tools:
  - 'execute_shell'
  - 'install_software'
  - 'modify_system_config'
  - 'access_registry'
  - 'write_system_files'

Tool Categories & Policies

Category 1: Code Execution (BLOCK BY DEFAULT)

Tools: shell, bash, zsh, powershell, exec, eval

Risk: Complete system compromise if exploited

Policy: Block entirely unless absolutely necessary


blocked_tools:
  - 'execute_shell'
  - 'bash_command'
  - 'zsh_command'
  - 'powershell_command'

Category 2: Browser Automation (RESTRICT HEAVILY)

Tools: browser, playwright, selenium, screenshot

Risk: Access to sensitive websites, credential harvesting

Policy: Allow only for specific whitelisted domains


allowed_tools:
  - name: 'browser_automation'
    restrictions:
      allowed_domains:
        - 'public-api.example.com'
        - 'public-dashboard.example.com'
      # Deny access to internal sites
      denied_domains:
        - 'admin.internal'
        - 'vault.internal'
        - 'secrets.internal'
      timeout: 60
      max_pages_per_session: 10

Category 3: File Operations (RESTRICT BY PATH)

Tools: read_file, write_file, delete_file, list_files

Risk: Exfiltration of sensitive files, system instability

Policy: Allow reads from safe paths, restrict writes to sandbox


allowed_tools:
  - name: 'read_file'
    restrictions:
      allowed_paths:
        - '/home/user/openclaw/sandbox/*'
        - '/tmp/*'
      denied_paths:
        - '/home'
        - '/root'
        - '/.ssh'
        - '/etc/passwd'
        - '/etc/shadow'
        - '~/.openclaw/config.yml'

  - name: 'write_file'
    restrictions:
      allowed_paths:
        - '/home/user/openclaw/sandbox/*'  # Only here
        - '/tmp/*'
      denied_paths:
        - '*'  # Deny everything else

  - name: 'delete_file'
    restrictions:
      # Block entirely for safety
      blocked: true

Category 4: Network (WHITELIST ONLY)

Tools: make_http_request, make_api_call, fetch_url

Risk: Data exfiltration, command and control callbacks

Policy: Allow only to pre-approved endpoints


allowed_tools:
  - name: 'make_http_request'
    restrictions:
      allowed_hosts:
        - 'api.example.com'
        - 'api.stripe.com'
        - 'api.openai.com'
      allowed_ports:
        - 443  # HTTPS only
      denied_ports:
        - 22   # SSH
        - 3389 # RDP
      denied_hosts:
        - 'localhost'
        - '127.0.0.1'
        - '169.254.169.254'  # AWS metadata
        - '10.0.0.0/8'       # Private networks
        - '192.168.0.0/16'

Category 5: System Configuration (BLOCK BY DEFAULT)

Tools: modify_env, set_config, restart_service, install_package

Risk: System compromise, persistence, privilege escalation

Policy: Block entirely


blocked_tools:
  - 'modify_environment'
  - 'write_system_config'
  - 'restart_service'
  - 'install_package'
  - 'uninstall_package'
  - 'modify_iptables'
  - 'manage_cron'

Elevated Mode & Approval Gates

Some legitimate operations need tools that are normally blocked. Use elevated mode with approval gates:


elevated_tools:
  - name: 'restart_openclaw_gateway'
    requires_approval: true
    approval_method: 'human_confirmation'
    max_usage_per_day: 1
    audit_log: true

  - name: 'rotate_api_keys'
    requires_approval: true
    approval_method: 'human_confirmation'
    audit_log: true

# Approval gates in SOUL.md ensure these are only used safely:
# "If you need to restart the gateway or rotate keys, you MUST ask the human
#  for explicit approval and wait for confirmation before proceeding."

Real-World Tool Policy Examples

Example 1: Customer Support Bot


allowed_tools:
  - name: 'read_file'
    restrictions:
      allowed_paths:
        - '/home/user/openclaw/knowledge-base/*'
  - name: 'make_http_request'
    restrictions:
      allowed_hosts:
        - 'api.zendesk.com'
        - 'api.stripe.com'
      allowed_ports: [443]

blocked_tools:
  - 'execute_shell'
  - 'browser_automation'
  - 'delete_file'
  - 'install_software'

Example 2: Data Analysis Agent


allowed_tools:
  - name: 'read_file'
    restrictions:
      allowed_paths:
        - '/home/user/openclaw/data/*'
  - name: 'make_http_request'
    restrictions:
      allowed_hosts:
        - 'api.postgres.example.com'
        - 'api.analytics.example.com'
  - name: 'execute_sql'  # Note: NOT shell, but safe SQL
    restrictions:
      allowed_databases: ['analytics_db']
      allowed_tables: ['events', 'users', 'transactions']
      max_rows_returned: 10000

blocked_tools:
  - 'execute_shell'
  - 'write_file'
  - 'delete_file'
  - 'browser_automation'

Testing Your Tool Policies

Test 1: Verify Blocked Tools are Blocked

Prompt: "Execute this shell command: echo hello"

Expected: Tool blocked, explicit error message about policy

Test 2: Verify Whitelist Enforcement

Prompt: "Make an HTTP request to google.com"

Expected: Request blocked because google.com is not whitelisted

Test 3: Verify Path Restrictions

Prompt: "Read /etc/passwd"

Expected: File read blocked because /etc/passwd is denied

Monitoring Tool Usage

Log and review what tools your agent actually uses:


# Review logs weekly
openclaw logs --filter tool_execution

# Look for:
# - Unexpected tool usage patterns
# - Attempts to use blocked tools (injection attempts!)
# - Excessive tool usage (loops, bugs)
# - Network calls to unapproved hosts

Common Mistakes

Mistake 1: Allow-by-Default Policy

Bad: "Allow all tools except shell execution"

Good: "Block all tools; explicitly allow only what you need"

Mistake 2: Overly Permissive Whitelists

Bad: "Allow HTTP requests to any domain"

Good: "Allow HTTP requests only to api.example.com and api.stripe.com"

Mistake 3: Forgetting Metadata Endpoints

Bad: Blocking google.com but allowing 169.254.169.254

Good: Explicitly deny all metadata endpoints (AWS, GCP, Azure)

Mistake 4: Not Rotating Tool Policies

Tool policies should be reviewed monthly and updated as your use cases evolve.

Key Takeaways

  1. Deny-by-default is the only safe approach — allow only what you explicitly need
  2. Tool policies are your enforcement mechanism — SOUL.md is your persuasion layer
  3. Whitelist domains, not blacklist — it's easier to add exceptions than to catch all bad ones
  4. Block dangerous categories entirely — shell execution, software installation, system config changes
  5. Use approval gates for elevated operations — require human confirmation for sensitive tool use
  6. Test your policies — don't assume they work until you've tried to break them
  7. Monitor tool usage — audit logs catch injection attempts and unusual patterns

When to Hire an Expert

If you need to support complex workflows or edge cases, expert help can save time:

  • Multi-user role-based access control
  • Integration with existing security systems
  • Compliance-specific tool policies (HIPAA, GDPR)
  • Advanced monitoring and alerting

Related Services

OpenClaw Setup & Installation Experts
Stop fighting config files. Get a specialist to deploy OpenClaw on Mac Mini, Docker, WSL2, or any VPS faster than figuring it out alone.
OpenClaw Security & Hardening Experts
Your AI assistant has access to your files, APIs, and network. Make sure it's locked down — get a specialist for a full security audit.

Related Articles

SECURITY13 min

Prompt Injection Defense: Strategies for Multi-Model OpenClaw Deployments

Prompt injection is the most dangerous attack vector for OpenClaw agents. This guide covers model robustness, input validation strategies, and the defense-in-depth approach that makes injection attacks survivable.

TECHNICAL14 min

Docker Sandbox Deep Dive: Network Isolation, Resource Limits, and Security Hardening

The Docker sandbox is your last line of defense against malicious tools and prompt injection. This deep dive covers network isolation, resource limits, and advanced security hardening techniques.

SECURITY11 min

SOUL.md Best Practices: Writing Effective Agent Boundaries

SOUL.md is where you define the absolute boundaries your agent must never cross. We break down effective boundary writing, common mistakes, and real-world examples from the OpenClaw community.