Docker: EACCES permission denied writing ~/.openclaw (openclaw.json.*.tmp)

Symptoms

• Docker logs show errors like:
  • EACCES: permission denied, open '/home/node/.openclaw/openclaw.json.<...>.tmp'
• The gateway starts but can’t save config, auth profiles, or sessions.

Cause

The official Docker image runs as a non-root node user (uid 1000) for safety. When you bind-mount your host ~/.openclaw into /home/node/.openclaw, the container user must have write permissions.

This fails most often on Linux when:

• your host user is not uid 1000, and the directory is only writable by your host uid, or
• the directory/file is owned by root from a previous run.

Fix

0) Confirm what you are actually mounting (docker-setup.sh always mounts something)

If you used ./docker-setup.sh, you are bind-mounting host directories into the container by default:

• ${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw} → /home/node/.openclaw
• ${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace} → /home/node/.openclaw/workspace

Quick sanity check on the host:

echo "OPENCLAW_CONFIG_DIR=${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
echo "OPENCLAW_WORKSPACE_DIR=${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}"
ls -ld "${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}" "${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}"
id

1) Confirm which host directories are mounted

If you used docker-setup.sh, it typically mounts:

• OPENCLAW_CONFIG_DIR → /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR → /home/node/.openclaw/workspace

2) Linux: make the mount writable by uid 1000 (quickest)

On the host:

sudo chown -R 1000:1000 "${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
sudo chown -R 1000:1000 "${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}"

Then restart the containers:

docker compose restart

2.5) NAS / NFS / “chmod 777 still fails”: prefer a named volume

On some NAS / NFS / ACL-heavy filesystems (or when root-squash is involved), the container may still fail to mkdir even if the directory looks writable on the host.

In that case, the fastest workaround is to persist OpenClaw state in a Docker named volume (no host bind mount):

services:
  openclaw-gateway:
    volumes:
      - openclaw:/home/node/.openclaw
  openclaw-cli:
    volumes:
      - openclaw:/home/node/.openclaw

volumes:
  openclaw:

Notes:

• You will need to copy any existing ~/.openclaw state into the volume if you already onboarded.
• If your config hard-codes workspace paths, update them to match the container path (/home/node/.openclaw/workspace).

3) Alternative: run the container as your host user (advanced)

If you prefer matching the host uid/gid instead of changing ownership, set the compose user: to your uid/gid (security trade-offs vary by host).

Example (docker-compose.override.yml):

services:
  openclaw-gateway:
    user: "${UID}:${GID}"
  openclaw-cli:
    user: "${UID}:${GID}"

Verify

• Restarted gateway can write config (no new EACCES lines in docker compose logs).
• Control UI can save settings and the gateway persists sessions under the mounted directory.

Related

• Configuration overview (paths, state dir, env vars): /guides/openclaw-configuration
• Docker deployment guide: /guides/docker-deployment