Fix 'Error: EACCES: permission denied' in OpenClaw Docker (openclaw.json)

TL;DR: The Instant Fix

The Problem: OpenClaw running in Docker can't write to openclaw.json or volumes due to UID mismatch. The container runs as node (UID 1000) but files are owned by root (UID 0).

The Error: EACCES: permission denied when accessing /home/node/.openclaw

The Solution:

1. Quick Fix: chown the directory to fix permissions
2. Real Fix: Run container as your user (no root needed)

Deploy on Vultr (H100/A100 Ready) (High Availability & Limited Time Promotion for new accounts)

---

The Log: What You're Seeing

The Error:

[INFO] Starting OpenClaw...
[ERROR] Failed to write config
Error: EACCES: permission denied, mkdir '/home/node/.openclaw'
    at Object.mkdirSync (node:fs:639:3)
    at saveConfig (/app/dist/index.js:42:11)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

[System] Config save failed
[Agent] Unable to initialize

Context: This error occurs when OpenClaw running in Docker tries to write configuration files or create directories but lacks permission.

Observed Behavior: Container starts but crashes when trying to save state or configuration.

---

Why This Happens (It's a UID Mismatch)

This is a Docker Permission Mismatch.

OpenClaw's Docker container assumes:

• Files are writable by the container user
• Volume mounts have correct ownership
• UID/GID matches between host and container

But your setup has:

• Container runs as node (UID 1000) by default
• Files owned by root (UID 0) from docker exec or previous runs
• Volume mount with root permissions from host

The error EACCES means: "Error ACcessES denied" — the filesystem rejected the write operation due to insufficient permissions.

Why Docker Containers Run as Root

Most Docker images run as root by default because:

• Root can do anything inside the container
• Simplifies installation (no permission issues during build)
• Traditional assumption: containers are isolated anyway

The Problem: When you docker exec into a container as root, any files created become root-owned. When OpenClaw (running as node) tries to access them later — permission denied.

The UID Mismatch Explained

Container User: node (UID 1000)
Config File Owner: root (UID 0)

node tries to write → File is owned by root → EACCES: permission denied

---

Solution A: Fix Ownership with chown (Quick Fix)

If you've already created files with wrong ownership, fix them manually.

Step 1: Check Current Ownership

# Enter the container
docker exec -it openclaw-container sh

# Check file ownership
ls -la /home/node/.openclaw

# Output might show:
# -rw-r--r-- 1 root root  4096 Feb  4 10:23 openclaw.json
#              ^^^^ ^^^^
#              owned by root

Step 2: Fix Ownership

# Option 1: chown the specific file
chown node:node /home/node/.openclaw/openclaw.json

# Option 2: chown the entire directory
chown -R node:node /home/node/.openclaw

# Option 3: chown everything in home
chown -R node:node /home/node

Step 3: Fix Volume Mount Permissions

If using volume mounts, ensure correct ownership on the host:

# On your host machine
# Find the volume path
docker inspect openclaw-container | grep -A 10 Mounts

# Navigate to the volume location on host
cd /var/lib/docker/volumes/openclaw-data/_data

# Fix ownership
sudo chown -R 1000:1000 .

# Or use your exact UID/GID
id node
# uid=1000(node) gid=1000(node) groups=1000(node)
sudo chown -R 1000:1000 .

---

Solution B: Fix Dockerfile (Permanent Fix)

The best solution is to ensure OpenClaw runs as a non-root user from the start.

Step 1: Update Dockerfile

FROM node:18-alpine

# Install OpenClaw
RUN npm install -g openclaw

# Create non-root user
RUN addgroup -g 1000 node && \
    adduser -D -u 1000 -G node -h /home/node node

# Set working directory
WORKDIR /home/node

# Create .openclaw directory with correct ownership
RUN mkdir -p /home/node/.openclaw && \
    chown -R node:node /home/node/.openclaw

# Switch to non-root user
USER node

# OpenClaw config goes here
ENV OPENCLAW_CONFIG=/home/node/.openclaw/openclaw.json

CMD ["openclaw"]

Step 2: Rebuild Container

# Build new image
docker build -t openclaw:fixed .

# Stop old container
docker stop openclaw-container
docker rm openclaw-container

# Run with correct user
docker run -d \
  --name openclaw-container \
  -v openclaw-data:/home/node/.openclaw \
  openclaw:fixed

---

Solution C: Run as Your Host User (Best for VPS)

On a VPS or your Linux machine, run the container with your UID/GID to avoid permission issues entirely.

Step 1: Find Your UID/GID

# Check your user ID
id
# Output: uid=1000(youruser) gid=1000(youruser) groups=1000(youruser)

Step 2: Run Container with Your User

# Run container with your UID/GID
docker run -d \
  --name openclaw-container \
  --user $(id -u):$(id -g) \
  -v $(pwd)/openclaw-data:/home/node/.openclaw \
  node:18-alpine \
  npx openclaw start

This ensures all files created inside the container are owned by your user, not root.

---

Solution D: Rootless Docker (Most Secure)

For maximum security, use rootless Docker. This runs containers without root privileges at all.

Install Rootless Docker

# Ubuntu/Debian - Install docker-ce-rootless-extras package
sudo apt-get install -y docker-ce-rootless-extras

# Or use dockerd-rootless-setuptool.sh (included with modern Docker)
dockerd-rootless-setuptool.sh install

Run Rootless

# Rootless docker is just `dockerd` instead of `docker`
dockerd-rootless.sh install

# Run containers without root
docker run -d \
  --name openclaw-container \
  -v openclaw-data:/data \
  openclaw:latest

Benefit: No root required, ever. All files are owned by your user automatically.

---

The "Survival" Recommendation

Stop debugging Docker permissions on your local machine.

Docker permissions on local Linux/Mac can be a nightmare. UIDs don't match, volume mounts are root-owned, chown feels hacky.

The smart choice: Deploy on a fresh VPS where you control the environment from the start.

Local Docker vs Cloud VPS Comparison

Issue	Local Docker	Cloud VPS (Vultr)
Permissions	UID mismatch, chown needed	Clean slate, your user only
Volume mounts	Root ownership issues	Properly configured
Debug time	1-2 hours (chown, rebuild)	0 minutes (works immediately)
Security	Need root for fixes	Isolated, no root needed
Setup Time	Hours of debugging	2 minutes

Deploy on Vultr (H100/A100 Ready) (High Availability & Limited Time Promotion for new accounts)

---

Complete Working Example

Verified Docker Configuration

FROM node:18-alpine

# Install OpenClaw
RUN npm install -g openclaw

# Create non-root user with specific UID/GID
RUN addgroup -g 1000 node && \
    adduser -D -u 1000 -G node -h /home/node node

# Set up directory structure
WORKDIR /home/node
RUN mkdir -p /home/node/.openclaw && \
    chown -R node:node /home/node/.openclaw

# Switch to non-root user early
USER node

# Set environment
ENV OPENCLAW_CONFIG=/home/node/.openclaw/openclaw.json

CMD ["openclaw"]

docker-compose.yml

version: '3.8'

services:
  openclaw:
    build: .
    user: "1000:1000"  # Run as UID 1000
    volumes:
      - ./data:/home/node/.openclaw
    environment:
      - OPENCLAW_CONFIG=/home/node/.openclaw/openclaw.json
    restart: unless-stopped

Verify Permissions Work

# Start container
docker-compose up -d

# Enter container
docker-compose exec openclaw sh

# Check user
id
# Should show: uid=1000(node) gid=1000(node)

# Check directory
ls -la /home/node/.openclaw
# Should show: drwxr-xr-x node node ...

# Try writing
echo "test" > /home/node/.openclaw/test.txt
# Should work without EACCES

---

FAQ

---