OpenClaw Agent File Permissions: Complete Guide

How OpenClaw File Permissions Work

OpenClaw uses a permission model inspired by the principle of least privilege. By default, agents can only access files within their own workspace directory. Everything outside that boundary is blocked unless you explicitly allow it.

The permission system has three layers. The first layer is the workspace root, which is the directory where the agent lives. The second layer is the openclaw.json configuration file, which overrides defaults with custom rules. The third layer is runtime enforcement, where OpenClaw checks every file operation against the permission rules before allowing it to proceed.

When an agent tries to read, write, or delete a file, OpenClaw intercepts the operation and checks it against the permission rules defined in openclaw.json. If the operation is allowed, it proceeds. If not, the agent receives a permission denied error and the operation is blocked. This happens transparently. The agent does not need to know about the permission system. It simply gets an error when it tries something it is not allowed to do.

The openclaw.json File: Structure and Syntax

The openclaw.json file lives in the root of your agent's workspace directory. It is the single source of truth for all permission rules. Here is the complete structure:

{
  "agent": "radar",
  "workspace": {
    "root": "./",
    "allowPaths": [
      "./data/**",
      "./reports/**",
      "./config/*.yaml"
    ],
    "denyPaths": [
      "./.env",
      "./.env.*",
      "./secrets/**",
      "./node_modules/**"
    ],
    "permissions": {
      "read": true,
      "write": true,
      "delete": false,
      "execute": false
    }
  },
  "shared": {
    "paths": [
      "/shared/datasets/**"
    ],
    "readOnly": true
  },
  "env": {
    "allowEnv": [
      "OPENAI_API_KEY",
      "DATABASE_URL",
      "NODE_ENV"
    ]
  },
  "network": {
    "allowNetwork": true,
    "allowDomains": [
      "api.openai.com",
      "api.anthropic.com"
    ]
  }
}

Let us break down each section.

Default Permissions vs Custom Permissions

When you deploy an agent without an openclaw.json file, OpenClaw applies a set of default permissions. Understanding these defaults helps you decide when you need a custom configuration and when the defaults are sufficient.

The defaults are conservative. Delete and execute are disabled. Env files are blocked. This means a freshly deployed agent cannot accidentally delete your project files or run arbitrary scripts. But the defaults also give the agent full read and write access to its workspace directory, which might be too broad for production deployments.

For production, always create an explicit openclaw.json with the minimum permissions your agent needs. A monitoring agent that only reads log files should not have write access. A report generator that writes to a specific output folder should not have access to your entire project tree.

Common Errors and How to Fix Them

Permission errors are the most common issue when deploying OpenClaw agents. Here are the errors you will encounter and exactly how to fix each one.

// Add the path to allowPaths in openclaw.json
"allowPaths": [
  "./data/**",
  "./path/to/file"  // Add the specific file or directory
]

// Then restart the agent session
// openclaw agent restart --agent [name]

// Check workspace.permissions.write is true
"permissions": {
  "read": true,
  "write": true  // Must be true for write operations
}

// If accessing a shared path, check readOnly
"shared": {
  "paths": ["/shared/data/**"],
  "readOnly": false  // Set to false if this agent needs to write
}

// Verify the root directory exists
// ls -la /path/to/workspace

// Use relative path from openclaw.json location
"workspace": {
  "root": "./"  // Relative to where openclaw.json lives
}

// Or use absolute path
"workspace": {
  "root": "/home/deploy/agents/radar"
}

// Add the variable to allowEnv
"env": {
  "allowEnv": [
    "OPENAI_API_KEY",
    "DATABASE_URL",
    "MY_NEW_VARIABLE"  // Add the missing variable
  ]
}

// Remove the file from denyPaths if the agent truly needs access
"denyPaths": [
  "./.env",
  // "./config/secrets.yaml"  // Remove this if agent needs it
]

// Or restructure your files so sensitive data is separate
// from files the agent needs to access

// OpenClaw caches permissions at session start
// You must restart the agent session

// Option 1: Restart the agent
// openclaw agent restart --agent radar

// Option 2: Clear the session and start fresh
// rm ~/.openclaw/agents/radar/sessions/sessions.json
// openclaw agent --agent radar --message "test"

Best Practices for Multi-Agent Setups

Running multiple agents on the same machine introduces coordination challenges. File permissions become critical when two or more agents interact with overlapping directories. Here are the practices that prevent problems.

Real-World Example: Three-Agent Setup

Here is a production-ready multi-agent configuration with Orion (project manager), Echo (content writer), and Radar (SEO analyst) running on the same server. Each agent has its own openclaw.json with properly scoped permissions.

Directory structure:

/agents/
  orion/
    SOUL.md
    openclaw.json
    tasks/
    reports/
  echo/
    SOUL.md
    openclaw.json
    drafts/
    published/
  radar/
    SOUL.md
    openclaw.json
    data/
    seo-reports/
  shared/
    briefs/          # Orion writes, Echo reads
    seo-reports/     # Radar writes, Echo reads
    keywords/        # Radar writes, Orion reads

Orion (PM) - openclaw.json:

{
  "agent": "orion",
  "workspace": {
    "root": "./",
    "allowPaths": [
      "./tasks/**",
      "./reports/**"
    ],
    "denyPaths": ["./.env", "./.env.*"],
    "permissions": {
      "read": true,
      "write": true,
      "delete": false,
      "execute": false
    }
  },
  "shared": {
    "paths": [
      "/agents/shared/briefs/**",
      "/agents/shared/keywords/**"
    ],
    "readOnly": false
  },
  "env": {
    "allowEnv": ["TELEGRAM_BOT_TOKEN", "CONVEX_URL"]
  }
}

Echo (Writer) - openclaw.json:

{
  "agent": "echo",
  "workspace": {
    "root": "./",
    "allowPaths": [
      "./drafts/**",
      "./published/**"
    ],
    "denyPaths": ["./.env", "./.env.*"],
    "permissions": {
      "read": true,
      "write": true,
      "delete": false,
      "execute": false
    }
  },
  "shared": {
    "paths": [
      "/agents/shared/briefs/**",
      "/agents/shared/seo-reports/**"
    ],
    "readOnly": true
  },
  "env": {
    "allowEnv": ["OPENAI_API_KEY"]
  }
}

Radar (SEO) - openclaw.json:

{
  "agent": "radar",
  "workspace": {
    "root": "./",
    "allowPaths": [
      "./data/**",
      "./seo-reports/**"
    ],
    "denyPaths": ["./.env", "./.env.*"],
    "permissions": {
      "read": true,
      "write": true,
      "delete": false,
      "execute": false
    }
  },
  "shared": {
    "paths": [
      "/agents/shared/seo-reports/**",
      "/agents/shared/keywords/**"
    ],
    "readOnly": false
  },
  "env": {
    "allowEnv": ["GSC_SERVICE_ACCOUNT", "GA4_PROPERTY_ID"]
  },
  "network": {
    "allowNetwork": true,
    "allowDomains": [
      "www.googleapis.com",
      "searchconsole.googleapis.com",
      "analyticsdata.googleapis.com"
    ]
  }
}

Notice the pattern. Orion writes briefs to the shared directory and reads keywords. Echo reads briefs and SEO reports but cannot modify them. Radar writes SEO reports and keywords but only connects to Google APIs. No agent can delete files. No agent can access another agent's private workspace. Each agent sees only the environment variables it needs.

Advanced: Glob Pattern Reference

The allowPaths and denyPaths arrays in openclaw.json use glob patterns. Here is a quick reference for the patterns you will use most often.

A common mistake is using ** when you mean *. The pattern ./data/* only matches files directly inside ./data/. If your agent needs to access nested subdirectories, you need ./data/**. Conversely, if you want to restrict access to only the top level of a directory, use * to prevent recursive access.

Security Checklist

Before deploying any agent to production, run through this checklist to make sure your permissions are locked down.

Frequently Asked Questions