Fix OpenClaw Permission Denied Errors in 12 Minutes

Problem: OpenClaw Crashes with Permission Denied

You installed OpenClaw but get Error: EACCES: permission denied when trying to save configs, complete OAuth, or create agent directories.

You'll learn:

• Why Docker containers and Linux systems block OpenClaw file access
• How to fix permissions permanently without breaking security
• When to use non-root users vs. directory ownership changes

Time: 12 min | Level: Intermediate

Why This Happens

OpenClaw needs to write to ~/.openclaw/ for configuration files, agent data, and OAuth tokens. Permission errors occur when:

Common symptoms:

• EACCES: permission denied, mkdir '/home/node/.openclaw' during setup
• OAuth completes but fails to save credentials
• Config changes don't persist after restart
• Works as root but fails as regular user

Root cause: Docker containers run as node user by default, but mounted volumes are owned by your host user (UID mismatch). On Linux, the config directory either doesn't exist or has restrictive permissions.

Solution

Step 1: Identify Your Environment

Determine if you're running Docker or local installation:

# Check if OpenClaw is running in Docker
docker ps | grep openclaw

# Check local installation
which openclaw

Expected: Either see a Docker container or /usr/local/bin/openclaw (local)

Step 2A: Fix Docker Permissions (Docker Users)

The container's node user (UID 1000) can't write to host-mounted directories.

Option 1: Fix ownership (recommended for single-user systems)

# Create directory with correct ownership
mkdir -p ~/.openclaw
sudo chown -R 1000:1000 ~/.openclaw

# Verify permissions
ls -la ~/.openclaw

Why this works: Matches container's node user UID to the directory owner, allowing writes.

Option 2: Run as your host user (advanced)

Modify your docker-compose.yml:

services:
  openclaw:
    image: openclaw/openclaw:latest
    user: "${UID}:${GID}"  # Use host user ID
    volumes:
      - ~/.openclaw:/home/node/.openclaw
    environment:
      - HOME=/home/node

Then restart:

# Set your user ID as environment variable
export UID=$(id -u)
export GID=$(id -g)

# Restart container
docker compose down
docker compose up -d

If it fails:

• Error: "mkdir: cannot create directory": Directory still owned by wrong user - run sudo rm -rf ~/.openclaw and recreate with correct ownership
• OAuth still fails: Check logs with docker logs openclaw-gateway -n 50 to see if path is different

Step 2B: Fix Local Installation Permissions (Non-Docker)

For local installs, the config directory needs proper Linux permissions.

# Create directory if missing
mkdir -p ~/.openclaw

# Set restrictive permissions (security best practice)
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/*.json 2>/dev/null || true

# Fix nested agent directories
find ~/.openclaw -type d -exec chmod 700 {} \;
find ~/.openclaw -type f -name "*.json" -exec chmod 600 {} \;

Why these permissions:

• 700 = Only your user can read/write/execute directories
• 600 = Only your user can read/write config files
• OpenClaw's security model requires these restrictive permissions

If it fails:

• Error: "Permission denied" persists: Check if running in sandboxed Terminal (Flatpak/Snap) - use native terminal instead
• Directory appears empty: You may have multiple config locations - run openclaw config show to see active path

Step 3: Verify Directory Structure

OpenClaw expects this layout:

~/.openclaw/
├── openclaw.json           # Main config
├── agents/
│   └── main/
│       └── agent/
│           └── auth-profiles.json  # OAuth tokens
└── logs/

Create missing directories:

# Ensure complete structure exists
mkdir -p ~/.openclaw/agents/main/agent
mkdir -p ~/.openclaw/logs

# Set permissions (Docker)
sudo chown -R 1000:1000 ~/.openclaw

# Set permissions (Local)
chmod -R 700 ~/.openclaw

Step 4: Use Built-in Diagnostic Tool

OpenClaw v2026.1.30+ includes an auto-repair command:

# Automatically detect and fix common issues
openclaw doctor --fix

Expected output:

✓ Checking config directory permissions...
✓ Creating missing directories...
✓ Fixing file ownership...
✓ Verifying agent structure...
All issues resolved.

If doctor fails:

• Still shows permission errors: Run with sudo for Docker setups: sudo openclaw doctor --fix
• Command not found: Update to latest version: curl -fsSL https://openclaw.ai/install.sh | bash

Verification

Test configuration write:

# Try updating a config value
openclaw config set gateway.mode local

# Check if it persisted
openclaw config show | grep gateway.mode

You should see: "mode": "local" in the output

Test OAuth flow:

# Attempt OAuth (example with Anthropic)
openclaw models login --provider anthropic

Expected: OAuth completes without permission errors, credentials saved to ~/.openclaw/agents/main/agent/auth-profiles.json

What You Learned

• Docker UID mismatches cause permission denied errors in mounted volumes
• OpenClaw requires 700 directory and 600 file permissions for security
• The openclaw doctor --fix command automates common permission fixes

Limitations:

• Shared systems: Multiple users can't share the same ~/.openclaw - use separate home directories
• Sandboxed terminals: Flatpak/Snap terminals may still fail - use system terminal

Security note: Never use chmod 777 - this exposes API keys and OAuth tokens to all users.