Permission Denied Errors in OpenClaw: Full Guide

Look, if you've been messing around with OpenClaw for more than about forty-five minutes, you've probably already seen it. That angry little line in your terminal that makes you want to close your laptop and go outside:

PermissionError: [Errno 13] Permission denied

Or maybe it was EACCES. Or maybe it was the slightly more cryptic Permission denied (publickey) when your agent tried to touch a Git repo. Or maybe — and this one is truly fun — your agent just entered an infinite loop trying to sudo its way out of a problem it was never going to solve on its own.

Whatever flavor you got, the message is the same: your agent wants to do something, and your system is telling it to sit down.

This is, by a wide margin, the most common roadblock people hit when they start building with OpenClaw. It's not a bug in the platform. It's not a skill issue on your part. It's the entirely predictable collision between an AI agent that needs to interact with your filesystem, shell, and operating system — and an operating system that was specifically designed to prevent unauthorized things from interacting with it.

The good news: every single one of these errors is fixable, and once you understand the underlying pattern, you'll stop Googling the same stack trace every three days. Let's walk through all of it.

Why OpenClaw Agents Hit Permission Errors in the First Place

Before we fix anything, it helps to understand what's actually happening.

OpenClaw agents aren't just generating text. They're executing actions — writing files, running shell commands, installing packages, sometimes controlling your mouse and keyboard. They're doing real things on a real machine (or inside a real container). That means they're subject to the exact same permission rules as any other process running on that system.

Your operating system doesn't care that an AI is the one asking. It checks: does this user have write access to this directory? Does this process have permission to bind to this port? Is this application authorized to monitor keyboard input?

If the answer is no, you get a permission denied error. Simple as that.

The three big categories where this shows up:

1. Docker and container volume permissions (the #1 source of pain)
2. macOS privacy and accessibility permissions (for desktop/computer-use agents)
3. Filesystem and tool execution permissions (everything else)

Let's tackle them one at a time.

Category 1: Docker Volume Permission Hell

This is where roughly 70% of all OpenClaw permission errors come from, so we're spending the most time here.

The Core Problem

When you run an OpenClaw agent inside a Docker container (which is the recommended way to do it — you don't want an autonomous agent running unsandboxed on your host machine), you typically mount a local directory as a volume so the agent can read and write files in your project.

Something like:

docker run -v $(pwd)/workspace:/workspace openclaw-agent

Here's where the trouble starts. Inside the container, the agent process usually runs as root (UID 0) by default. Outside the container, on your host machine, you're running as your normal user (let's say UID 1000). When the agent creates a file inside /workspace, that file is owned by UID 0 — root. Now you, back on your host machine, can't edit or delete the files your own agent just created.

And it works the other way too. If your host files are owned by UID 1000, and the container process runs as a different UID, the agent can't read or write to the mounted volume. Permission denied.

The Fix

You need to make sure the UID and GID inside the container match yours on the host. Here's the cleanest way to do this.

Option A: Pass your UID/GID at runtime

docker run \
  --user "$(id -u):$(id -g)" \
  -v $(pwd)/workspace:/workspace \
  openclaw-agent

This tells Docker to run the container process as your host user. Files created by the agent will be owned by you. Files you created will be readable by the agent. Everyone's happy.

Option B: Set it in your Dockerfile

If you're building a custom OpenClaw image (which you probably will be eventually), add a non-root user that matches your host UID:

FROM openclaw/base:latest

ARG USER_UID=1000
ARG USER_GID=1000

RUN groupadd --gid $USER_GID agentuser \
    && useradd --uid $USER_UID --gid $USER_GID -m agentuser

USER agentuser
WORKDIR /workspace

Build it with your actual UID:

docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t my-openclaw .

Option C: Use docker-compose (recommended for ongoing projects)

version: '3.8'
services:
  openclaw-agent:
    image: openclaw/base:latest
    user: "${UID}:${GID}"
    volumes:
      - ./workspace:/workspace
    environment:
      - OPENCLAW_WORKSPACE=/workspace

Then create a .env file:

UID=1000
GID=1000

Or set it dynamically:

UID=$(id -u) GID=$(id -g) docker-compose up

The "I Just Want It to Work Right Now" Hack

If you're just prototyping and don't care about security yet (please don't do this in production):

docker run --user root -v $(pwd)/workspace:/workspace openclaw-agent

And then on your host after the agent runs:

sudo chown -R $(whoami):$(whoami) ./workspace

It's ugly. It works. Move to a real solution before you ship anything.

Category 2: macOS Privacy Permissions

If you're running OpenClaw agents that interact with your desktop — screen capture, mouse control, keyboard input, the full computer-use experience — macOS is going to fight you every step of the way.

The Core Problem

macOS requires explicit user approval for any application that wants to:

• Monitor keyboard input (Input Monitoring)
• Control the mouse or other applications (Accessibility)
• Record the screen (Screen Recording)

Your OpenClaw agent, whether it's running through Terminal, an Electron app, or a Python process, needs these permissions. And macOS won't grant them silently. You have to manually go into System Settings and flip the switch.

Worse: if the binary changes (you update Python, you rebuild the app, you switch terminal emulators), macOS sometimes revokes the permission. You'll see the agent suddenly fail with a permission error on operations that worked yesterday.

The Fix

Step 1: Identify which application needs the permission.

It's not always obvious. If you're running OpenClaw from Terminal.app, then Terminal.app needs the permission. If you're using iTerm2, iTerm2 needs it. If you're running a Python script directly, sometimes the Python binary itself needs it.

Step 2: Go to System Settings → Privacy & Security.

Grant the following to your terminal/application:

• Accessibility (required for mouse/keyboard control)
• Input Monitoring (required for keyboard capture)
• Screen Recording (required for screenshots/screen reading)

Step 3: Restart the application after granting permissions.

This one catches everyone. The permissions don't take effect until you quit and reopen the app.

Step 4: If permissions disappear after an update:

# Reset the permission database for a specific app (nuclear option)
tccutil reset Accessibility com.apple.Terminal
tccutil reset ScreenCapture com.apple.Terminal

Then re-grant manually. Yes, it's annoying. Blame Apple, not OpenClaw.

Pro Tip for macOS Users

Create a small test script to verify your permissions are working before you let your agent loose:

# test_permissions.py
import subprocess
result = subprocess.run(['osascript', '-e', 'tell application "System Events" to get name of first process'], 
                       capture_output=True, text=True)
if result.returncode == 0:
    print("✅ Accessibility permission is working")
else:
    print("❌ Accessibility permission denied - check System Settings")
    print(result.stderr)

Run it. If it fails, fix your permissions before running your actual agent.

Category 3: Filesystem and Tool Execution Errors

This is the catch-all category for everything that isn't Docker volumes or macOS privacy.

Agent Can't Install Packages

Your agent tries to run pip install or apt-get install and gets permission denied.

Fix: Inside a container, either run as root (for system packages) or use --user flag for pip:

pip install --user some-package

Better yet, configure your OpenClaw workspace to use a virtual environment:

python -m venv /workspace/.venv
source /workspace/.venv/bin/activate
pip install some-package  # no permission issues

Agent Can't Write to Expected Directories

The agent tries to write to /tmp, /app, ~, or some other directory and fails.

Fix: Set the OPENCLAW_WORKSPACE environment variable (or whatever your configuration uses) to a directory the agent actually has write access to. Don't let it guess.

export OPENCLAW_WORKSPACE=/workspace

And make sure that directory exists and is writable:

mkdir -p /workspace && chmod 755 /workspace

Agent Loops on sudo Commands

This one is darkly funny. The agent encounters a permission error, decides it needs sudo, runs sudo some-command, gets prompted for a password it can't provide, and then tries again. And again. And again.

Fix: Configure your OpenClaw agent's system prompt or tool constraints to explicitly prevent sudo usage. Most OpenClaw configurations let you set allowed and disallowed commands:

# openclaw-config.yaml
tools:
  shell:
    blocked_commands:
      - sudo
      - su
      - chmod 777
      - chown
    allowed_directories:
      - /workspace

If the agent needs elevated permissions for something, handle it in your container setup, not at runtime.

SSH/Git Permission Denied (Publickey)

Your agent tries to clone a repo or push code and gets Permission denied (publickey).

Fix: Mount your SSH keys into the container (read-only):

docker run \
  -v ~/.ssh:/home/agentuser/.ssh:ro \
  -v $(pwd)/workspace:/workspace \
  openclaw-agent

Or use HTTPS with a personal access token instead:

git clone https://${GITHUB_TOKEN}@github.com/your/repo.git

Pass the token as an environment variable:

docker run \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -v $(pwd)/workspace:/workspace \
  openclaw-agent

The Permissions Checklist

Before you start any new OpenClaw project, run through this:

• Container runs with matching UID/GID (--user "$(id -u):$(id -g)")
• Workspace volume is mounted and writable
• No sudo in the agent's tool repertoire
• macOS privacy permissions granted (if using desktop mode)
• SSH keys or access tokens available (if using Git)
• Virtual environment set up for Python packages
• Agent's allowed directories explicitly configured
• Test script confirms basic read/write works before running the full agent

Skip the Setup Headaches Entirely

Here's the thing I wish someone had told me before I spent a weekend debugging UID mapping: most of this permission configuration is boilerplate that someone else has already figured out. You can absolutely set it all up yourself — I just walked you through how — but if you'd rather start with a working foundation instead of debugging Docker volume permissions at 11pm on a Tuesday, Felix's OpenClaw Starter Pack is genuinely the fastest way to get going.

It comes pre-configured with sane Docker defaults, proper user mapping, a workspace structure that doesn't fight your OS, and the kind of guardrails (blocked commands, scoped directories) that prevent the most common permission disasters. I've seen people in the OpenClaw community go from "permission denied on literally everything" to a running agent in under an hour with that starter pack. It's not magic — it's just the right defaults, already set.

Whether you use it or build your own config from scratch, the principles are the same. Match your UIDs. Scope your directories. Don't let the agent use sudo. Grant macOS permissions proactively. Test before you trust.

A Quick Note on Security

I want to be direct about this because the temptation is real: do not solve permission errors by giving your agent unrestricted access to everything.

Running containers as root, mounting your entire home directory, disabling macOS security features, using chmod 777 — these all "fix" permission errors in the same way that removing your front door "fixes" the problem of losing your keys. It works, technically, until it very much doesn't.

OpenClaw agents execute real commands on real systems. A misconfigured agent with broad permissions can delete files, overwrite configs, leak credentials, or worse. The goal is to give the agent exactly the permissions it needs and nothing more. That's why scoped workspaces, non-root users, and blocked command lists exist.

Take the extra ten minutes to set it up correctly. Future you will be grateful.

Next Steps

If you just fixed your permission error and your agent is finally running, here's what to do next:

1. Lock down your configuration. Now that things work, go back and make sure you're not running as root or giving broader access than necessary.

2. Version your Docker setup. Put your Dockerfile, docker-compose.yaml, and .env in version control. Permission configs are the kind of thing that breaks silently when someone changes one line three months from now.

3. Set up a test script. Write a small script that verifies all permissions are correct before launching your agent. Run it in CI if you have it. Run it manually if you don't.

4. Join the OpenClaw community. Permission issues evolve as the platform evolves. The people who ship working agents are the ones who stay plugged into what's changing.

Permission denied errors are annoying, but they're solvable. Every single one of them. And once you've fixed them once, you basically never have to think about them again — which means you can get back to the actually interesting part: building agents that do useful things.

Now go make something.