OpenClaw Permissions Explained: What Each Setting Does

OpenClaw permissions control what your AI agent can and cannot do on your system. They are the boundary between a helpful assistant and an uncontrolled process with access to your files, network, and tools. Understanding permissions is not optional — it is the single most important thing you need to know before using OpenClaw in any serious capacity. This guide explains every permission level, what each setting does, which ones are safe for beginners, and how to configure recommended defaults.

Why Permissions Exist

An AI agent without permissions is either useless or dangerous. If it cannot access any files, it cannot help you with your project. If it can access everything without restriction, a poorly written skill or a misunderstood instruction could modify files you did not intend to change, make network requests you did not authorize, or execute commands that affect your system.

Permissions solve this problem by letting you define exactly what the agent is allowed to do. You stay in control, and the agent operates within the boundaries you set.

The Permission Model Overview

OpenClaw uses a layered permission model. Each layer adds capabilities, and you can configure them independently. Here are the core permission categories.

File System Read

What it does: Allows the agent to read files on your system.

Scope options:

• Project directory only: The agent can only read files within your current project folder. This is the safest option and sufficient for most workflows.
• Specified directories: You define a list of directories the agent can access. Useful when your project depends on configuration files stored elsewhere.
• Full read access: The agent can read any file on your system. This is rarely necessary and not recommended for beginners.

Risk level: Low. Reading files does not change anything on your system. The main concern is privacy — if the agent can read sensitive files like ~/.ssh/ or ~/.aws/credentials, that information enters the agent's context.

Recommended default: Project directory only.

File System Write

What it does: Allows the agent to create, modify, and delete files.

Scope options:

• Project directory only: The agent can only write to files within your current project folder. This is the safest option for write access.
• Specified directories: You define which directories the agent can modify.
• Full write access: The agent can write to any location on your system. This is strongly discouraged for any user.

Risk level: Medium to high. Write access means the agent can change your code, overwrite files, and create new files. Within a project directory, this is usually what you want — the agent needs to write code to help you. Outside the project directory, unintended writes can cause real problems.

Recommended default: Project directory only, with confirmation prompts enabled for deletions.

Command Execution

What it does: Allows the agent to run terminal commands on your system.

Scope options:

• Disabled: The agent cannot run any commands. It can only read and write files.
• Allowlisted commands: You define a specific list of commands the agent is permitted to run. For example, you might allow git status, npm test, and python script.py but nothing else.
• All commands with confirmation: The agent can run any command, but you must approve each one before it executes.
• All commands without confirmation: The agent runs commands freely. This is the most productive setting but carries the highest risk.

Risk level: High. Terminal commands can do anything your user account can do — install software, delete files, make network requests, modify system settings. Even seemingly innocent commands can have side effects.

Recommended default: Allowlisted commands for beginners. All commands with confirmation for intermediate users who understand what they are approving.

Network Access

What it does: Allows the agent to make HTTP requests, access APIs, and communicate over the network.

Scope options:

• Disabled: The agent cannot make any network requests. All work happens locally.
• Specified domains: You define which domains the agent can reach. For example, you might allow api.github.com and registry.npmjs.org but block everything else.
• All network access: The agent can reach any URL. Necessary for some workflows but should be used with awareness.

Risk level: Medium. Network requests can send data from your local environment to external services. If the agent has read access to sensitive files and network access, it could theoretically exfiltrate data. In practice, this risk is low with reputable skills, but the permission exists so you can control it.

Recommended default: Disabled or specified domains for beginners. Enable specific domains as needed when a skill requires external API access.

Tool and Integration Access

What it does: Allows the agent to interact with external tools and services like databases, cloud providers, or third-party APIs.

Scope options:

• Disabled: No external tool access.
• Specified tools: You define which integrations the agent can use.
• All tools: The agent can use any configured integration.

Risk level: Varies by tool. A read-only database connection is low risk. Write access to a production database is extremely high risk. Evaluate each tool integration individually.

Recommended default: Disabled. Enable specific tools only when a workflow requires them, and prefer read-only access wherever possible.

Permission Combinations and Their Implications

Permissions interact with each other. Understanding the combinations helps you make better decisions.

Read-only setup (file read + no write + no commands + no network): The safest configuration. The agent can analyze your code and answer questions but cannot change anything. Good for code review and learning.

Standard development setup (file read/write within project + allowlisted commands + no network): Covers most development workflows. The agent can edit your code and run tests but cannot access external services or run arbitrary commands.

Full development setup (file read/write within project + all commands with confirmation + specified network domains): For experienced users who need the agent to install packages, run build tools, and interact with APIs. The confirmation step on commands keeps you in the loop.

Unrestricted setup (full access to everything): Only appropriate for isolated environments like disposable containers or virtual machines. Never use this configuration on a machine with sensitive data or production access.

What Each Confirmation Prompt Means

When you enable confirmation prompts, the agent will ask for your approval before certain actions. Here is what each prompt type looks like and what you should check before approving.

File write confirmation: The agent shows you the file path and a preview of the changes. Check that the file path is correct and the changes look reasonable. Pay special attention to deletions and modifications to configuration files.

Command execution confirmation: The agent shows you the exact command it wants to run. Read the full command, including any flags and arguments. Be cautious with commands that include rm, sudo, curl | sh, or any piped commands where the output of one command feeds into another.

Network request confirmation: The agent shows you the URL and the request method (GET, POST, etc.). Check that the domain is one you trust and that POST requests are not sending sensitive data.

Configuring Your Permissions

Global vs. Project-Level Permissions

OpenClaw supports two levels of permission configuration.

Global permissions apply to every project you work on. Set these conservatively — they are your safety net.

Project-level permissions override global permissions for a specific project. You might have strict global defaults but allow more permissive settings for a trusted project where you need the agent to run build commands and access specific APIs.

The Configuration File

Permissions are defined in your OpenClaw configuration file. Here is an example of a balanced setup:

[permissions]
file_read = "project"
file_write = "project"
command_execution = "allowlist"
network_access = "disabled"

[permissions.command_allowlist]
commands = ["git", "npm test", "npm run build", "python -m pytest"]

[permissions.write_protection]
confirm_deletions = true
protected_patterns = ["*.env", "*.key", "*.pem"]

This configuration lets the agent read and write project files, run a specific set of commands, and blocks network access entirely. Deletions require confirmation, and files matching sensitive patterns cannot be modified.

Protected File Patterns

Even within your project directory, some files should be off-limits. Environment files (.env), encryption keys, certificates, and credential files should be added to your protected patterns list. The agent will not be able to read or modify files matching these patterns, regardless of other permission settings.

Common Permission Mistakes

Granting full write access because a skill asked for it: Always question why a skill needs broad permissions. A writing assistance skill should not need file system access at all. A code generation skill needs project-level write access but not full system access.

Forgetting to restrict command execution: This is the most dangerous permission to leave open. An agent that can run arbitrary commands can do anything your user account can do. Always start with an allowlist.

Ignoring network permissions: Network access is often overlooked because it seems harmless. But network access combined with file read access means the agent can potentially send your file contents to external servers. Control it.

Using the same permissions for every project: A personal side project and a production codebase have very different risk profiles. Configure permissions per project based on what that project actually needs.

Recommended Defaults for Beginners

If you are just getting started with OpenClaw, use these settings:

1. File read: Project directory only
2. File write: Project directory only with deletion confirmation
3. Command execution: Allowlisted commands only
4. Network access: Disabled
5. Tool access: Disabled
6. Protected patterns: *.env, *.key, *.pem, *.credential*

Start here, and relax permissions only when a specific workflow requires it. You can always grant more access later. Taking back access after something goes wrong is much harder.

Permissions are not obstacles to productivity. They are guardrails that let you use OpenClaw confidently, knowing that the agent operates within boundaries you defined. Take ten minutes to configure them properly, and you will never have to worry about unintended side effects.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Want a Pre-Built Setup?

If you would rather skip the browsing, OpenClaw personas come with curated skill sets already configured. Pick a persona that matches your role and start working immediately. Compare personas →