Permissions & Access Control

Permission Model Overview

Permissions in OpenClaw operate on four dimensions:

• Tool permissions — which tools can be called
• Filesystem permissions — which paths can be read/written
• Network permissions — which domains can be contacted
• API budget — how much cost/usage is allowed

All permissions follow a default-deny philosophy in secure mode: if a permission is not explicitly granted, it is denied.

# Enable secure mode (default-deny for all permissions)
openclaw config set security.mode strict

Tool-Level Permissions

Control exactly which tools are available to each agent:

security:
  tools:
    # Option 1: Allowlist (recommended)
    allowed:
      - read_file
      - search_web
      - fetch_url
      - write_file

    # Option 2: Blocklist
    blocked:
      - run_command
      - execute_code
      - send_email
      - delete_file

Tool Permission Matrix

Override permissions per-run for specific tasks:

# Allow code execution only for this specific run
openclaw run "Run the test suite and report results" \
  --allow-tool execute_code \
  --allow-tool run_command

Filesystem Permissions

security:
  filesystem:
    read_paths:
      - "/workspace"        # allow read anywhere in workspace
      - "/data/shared"      # allow read from shared data
    write_paths:
      - "/workspace/output" # allow write only to output dir
    blocked_paths:
      - "/etc"
      - "/sys"
      - "/proc"
      - "/root"
      - "/home"
    block_hidden_files: true   # block reading .env, .ssh, etc.
    max_file_size_mb: 100      # refuse files larger than 100MB

Network Permissions

security:
  network:
    allowlist:
      - "api.openai.com"
      - "api.anthropic.com"
      - "*.github.com"          # wildcard domain
    block_private_ranges: true   # block 10.x, 172.16.x, 192.168.x
    block_localhost: true        # block 127.0.0.1 and ::1
    max_request_size_mb: 10     # limit upload payload size
    force_https: true            # reject http:// requests

API Rate Limiting per Agent

budget:
  hard_limit: 10.00          # hard stop at $10
  soft_limit: 7.50           # alert at $7.50
  per_task_limit: 1.00       # max $1 per task
  daily_limit: 25.00         # max $25/day

  # Token rate limits
  requests_per_minute: 20
  tokens_per_minute: 40000
  tokens_per_day: 1000000

Multi-User RBAC Setup

For shared deployments, define roles with different permission levels:

# rbac.yaml
roles:
  admin:
    tools: ["*"]          # all tools
    filesystem: full
    budget_limit: 100.00

  operator:
    tools: ["read_file", "write_file", "search_web", "fetch_url"]
    filesystem:
      read_paths: ["/workspace"]
      write_paths: ["/workspace/output"]
    budget_limit: 10.00

  viewer:
    tools: ["read_file"]
    filesystem:
      read_paths: ["/data/reports"]
    budget_limit: 1.00

users:
  alice: admin
  bob: operator
  ci-bot: operator
  readonly-user: viewer

# Run as a specific user role
openclaw run "task" --user bob --config rbac.yaml

Audit Trail for Permission Violations

audit:
  enabled: true
  log_violations: true
  violation_alert_webhook: "https://hooks.slack.com/..."

What's Next

• Audit Logging — Log every agent action for compliance
• Sandboxing — Container-level isolation
• Secrets Management — Vault integration

Implementing Permissions in Practice

When defining permissions for a new agent, start with zero permissions and add only what the agent actually needs to perform its documented function. This "least privilege by default" approach forces you to consciously justify each permission grant. It's far safer than starting with broad permissions and trying to restrict them after the fact — the latter almost always leaves more access than intended because it's hard to enumerate all the ways a permission could be used.

Group permissions logically by function. File access permissions should list exactly which directories the agent needs with which access levels (read vs read-write). Network permissions should list which domains or IP ranges the agent may contact. Command execution permissions should list the exact executables and whether argument sanitization is enforced. When these lists are well-defined, security reviews become straightforward — a reviewer can quickly assess whether the listed permissions are appropriate for the stated agent purpose.

Review and prune permissions regularly. Agents evolve — tools get added and removed, workflows change. A permission granted for a tool that was later removed should be revoked. Schedule quarterly permission audits as part of your security hygiene routine. Treat unused permissions the same as unused code — they add surface area with no benefit and should be removed.

Preventing Permission Escalation

Agent permission escalation occurs when an agent uses a permitted tool to gain access to resources or capabilities outside its intended scope. For example, an agent with read access to a configuration directory might use that access to read a credential file it was not intended to see. Prevent this by combining directory-level file permissions with explicit exclude lists for sensitive file patterns — block access to *.key, *.pem, *.env, and similar patterns even within permitted directories.

Treat permissions as contracts, not just configuration. When you define an agent's permissions, document what the agent is expected to do with them. If an agent has web access to fetch documentation pages, document that it should only access documentation URLs. If its actual behavior deviates from the documented contract — fetching URLs outside the expected domain — treat it as a security event worth investigating, not just an operational quirk. Maintaining clear behavioral expectations makes permission violations easier to detect and classify.

Permission Review Checklist

Use a standard checklist when reviewing permissions for any new agent before production deployment. Confirm that file paths are explicit and minimal; network access lists only the domains actually needed for the documented task; command execution, if enabled, uses an allowlist rather than a denylist; sensitive file patterns are excluded even within permitted directories; and that all permissions are documented with a rationale. A consistent review process ensures permissions receive appropriate scrutiny every time, not just when a reviewer happens to think of the right questions.