OpenClaw Permission Denied Error: Docker and File System Fix Guide

Why Do Permission Denied Errors Happen?

The "permission denied" error is the single most common issue new OpenClaw operators encounter. It shows up in your terminal or Docker logs as something like EACCES: permission denied, Got permission denied while trying to connect to the Docker daemon socket, or Error: EACCES: permission denied, open '/data/config.json'.

There are three root causes that account for over 95% of these errors:

• Docker socket permissions: Your user cannot access /var/run/docker.sock because they are not in the docker group.
• File ownership mismatch: The files on your host are owned by one user (often root), but the OpenClaw process inside Docker runs as a different user (often UID 1000).
• Incorrect directory permissions: The data directory or config files have restrictive permissions that prevent the OpenClaw process from reading or writing.

Let us walk through each fix in order from most common to least common.

Fix 1: Docker Socket Permissions

OpenClaw uses Docker for sandbox mode — isolating code execution in containers so your host system stays safe. To do this, OpenClaw needs access to the Docker daemon through its Unix socket at /var/run/docker.sock.

If your user is not in the docker group, you will see this error:

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

The fix is straightforward. Add your user to the docker group:

sudo usermod -aG docker $USER

Then log out and log back in for the group change to take effect. You can verify it worked by running:

docker ps

If this returns a list of containers (even an empty one) without a permission error, the fix worked.

If you are running OpenClaw inside Docker and need Docker-in-Docker access (for sandbox mode), you need to mount the Docker socket into the container. In your docker-compose.yml:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Additionally, ensure the user inside the container has permission to access the socket. The Docker socket on the host is typically owned by root:docker with permissions srw-rw----. The container user needs to have a matching GID. You can set this with:

environment:
  - PGID=999  # Match the docker group GID on your host

To find the docker group GID on your host, run:

getent group docker | cut -d: -f3

Fix 2: File Ownership Issues

The second most common permission error involves file ownership. This happens when you create the OpenClaw data directory as root but the OpenClaw process runs as a non-root user inside Docker.

Symptoms include errors like:

Error: EACCES: permission denied, open '/data/config.json'
Error: EACCES: permission denied, mkdir '/data/memory'

OpenClaw's Docker image runs as UID 1000 by default. If your data directory on the host was created by root (UID 0), the container process cannot read or write to it.

Fix it by changing ownership of the data directory to match the container user:

sudo chown -R 1000:1000 /opt/openclaw/data

The -R flag makes the change recursive, applying to all files and subdirectories. Replace /opt/openclaw/data with your actual data path.

To check what user your container is running as:

docker exec -it openclaw id

This will output something like uid=1000(node) gid=1000(node) groups=1000(node). Match the chown values to these numbers.

Fix 3: Running as Non-Root

Some operators try to fix permission errors by running OpenClaw as root. This is a mistake. Running any application as root gives it unrestricted access to your entire system, which is especially dangerous for an AI agent that executes code and interacts with external services.

Instead of running as root, always fix the underlying permission issue. Here is the decision tree:

1. If the error mentions the Docker socket, add your user to the docker group (Fix 1 above).
2. If the error mentions a file or directory, fix ownership with chown (Fix 2 above).
3. If the error persists, check directory permissions with ls -la and fix with chmod (Fix 4 below).

If you are using a Docker Compose setup, never set user: root in your service definition. Instead, use the PUID and PGID environment variables that OpenClaw supports:

environment:
  - PUID=1000
  - PGID=1000

These tell OpenClaw to run its internal processes as the specified user and group ID, matching the ownership of your data directory.

Fix 4: chmod and chown Basics

chmod changes file permissions (who can read, write, execute). chown changes file ownership (which user and group owns the file). For OpenClaw, you need both to be correct.

The OpenClaw data directory needs these minimum permissions:

# Set ownership to match your container user
sudo chown -R 1000:1000 /opt/openclaw/data

# Set directory permissions (rwx for owner, rx for group)
sudo find /opt/openclaw/data -type d -exec chmod 755 {} \;

# Set file permissions (rw for owner, r for group)
sudo find /opt/openclaw/data -type f -exec chmod 644 {} \;

Breaking down the permission numbers:

• 755 on directories = owner can read/write/enter, group and others can read/enter
• 644 on files = owner can read/write, group and others can read only

For the config files that contain API keys and sensitive data, you may want more restrictive permissions:

chmod 600 /opt/openclaw/data/.env
chmod 600 /opt/openclaw/data/config.json

600 means only the owner can read and write. No one else can access these files.

Fix 5: Docker Group Configuration

The Docker daemon runs as root and creates the Unix socket with root:docker ownership. Any user in the docker group can communicate with the daemon. This is by design, but it has security implications — any user in the docker group can effectively get root-level access through Docker.

To add a user to the docker group:

# Add your current user
sudo usermod -aG docker $USER

# Add a specific user
sudo usermod -aG docker openclaw-user

# Verify the group was added (after logging out and back in)
groups

If the docker group does not exist on your system, create it:

sudo groupadd docker

On some Linux distributions (particularly older Ubuntu versions), you may need to restart the Docker service after creating the group:

sudo systemctl restart docker

Security note: Adding a user to the docker group is equivalent to giving them root access. Only add users that you trust. For production deployments, consider running OpenClaw with rootless Docker or Podman, which provide container management without requiring root-level daemon access.

Fix 6: Docker Compose Permission Settings

A well-configured docker-compose.yml prevents most permission issues from occurring in the first place. Here is a template that handles permissions correctly:

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    environment:
      - PUID=1000
      - PGID=1000
      - PGID_DOCKER=999  # Docker group GID on host
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

Before starting the container, create the data directory with correct ownership:

mkdir -p ./data
sudo chown -R 1000:1000 ./data

This ensures the container user can read and write to the data directory from the moment it starts, eliminating the most common permission errors.

Troubleshooting Checklist

If you are still seeing permission errors after trying the fixes above, work through this checklist:

1. Check the exact error message. Is it about the Docker socket, a file path, or a directory? The error tells you which fix to apply.
2. Check container user: docker exec -it openclaw id
3. Check host file ownership: ls -la /opt/openclaw/data/
4. Compare UIDs: The UID from step 2 must match the owner from step 3.
5. Check Docker socket: ls -la /var/run/docker.sock — note the group owner.
6. Check groups: docker exec -it openclaw groups — the docker socket group must be listed.
7. Check SELinux or AppArmor: On RHEL/CentOS/Fedora, SELinux may block access even when Unix permissions are correct. Check with getenforce and review /var/log/audit/audit.log.
8. Check volume mount syntax: Ensure your Docker Compose volume mount uses the correct path and does not have a trailing slash mismatch.

If you have worked through every item on this list and still have issues, the Remote OpenClaw community is the fastest way to get help. Post your exact error message, the output of docker exec -it openclaw id, and ls -la of your data directory.