OpenClaw EACCES: Permission Denied Opening openclaw.json

TL;DR: EACCES: permission denied, open '/home/<user>/.openclaw/openclaw.json' means the gateway process cannot read its own config file because a different user owns it, almost always root. Run ls -l on the .openclaw directory to see who owns the file, confirm which user the gateway actually runs as, then chown the file and its parent directory to that user. Do not re-run the installer with sudo, and if you already did, treat the whole .openclaw tree as suspect, not just this one file.

EACCES: permission denied, open '/home/<user>/.openclaw/openclaw.json' is one of the more common self-hosting failures an OpenClaw operator will hit, and one of the faster ones to fix once you know it is an ownership mismatch rather than a broken install.

Contents

• What EACCES: Permission Denied Actually Means
• Ownership or Mode: Two Different Causes, Two Different Fixes
• How to Check Which User Owns the Config, and Which User Needs It
• The Repair
• Why It Happens, and How to Not Do It Again

What EACCES: Permission Denied on openclaw.json Actually Means

EACCES is not an OpenClaw error in the sense the rest of the error series covers. It is the operating system’s own answer to an open() call, returned before OpenClaw’s code gets to do anything with the file. The kernel checked whether the calling process’s user has read permission on openclaw.json, found that it does not, and refused the call.

That distinction matters for where you look. A parsing error or a missing key is a property of the file’s contents, and the fix lives inside the file. EACCES is a property of the file’s ownership and the calling process’s identity, and the fix lives outside the file, in chown and in whichever user account starts the gateway.

The file usually exists, is usually complete, and is usually correct. The process asking to read it simply is not allowed to.

Ownership or Mode: Two Different Causes, Two Different Fixes

Two different failures produce two different complaints about the same config file, and they do not share a fix.

Ownership, which is this error: the file is owned by a user other than the one the gateway runs as. The gateway’s own user has no grant on the file at all, regardless of whether the file is otherwise writable by somebody. This is almost always the result of an install or a write that happened as root while the gateway itself runs unprivileged.

Mode, which is a separate problem: the right user owns the file, but its permission bits are set too restrictively, commonly locked to 444 (read-only for everyone, including the owner) when a write was expected. That failure looks similar on the surface and is covered separately in the OpenClaw production gotchas post, in the section on which files may be 444 and which must stay 644.

If you have already tried chmod on this file and the error persists, you are very likely looking at an ownership problem, not a mode problem, and chmod was never going to touch it. chmod changes what the owner allows. It cannot change who the owner is.

There is a third, unrelated failure that also touches this file: a config that exists, is readable, and is simply missing a required key. That one prints a different message entirely and is covered in the gateway start blocked post , which deals with a config OpenClaw can open but did not finish writing. If your error text says EACCES, you are not in that case. The gateway cannot open the file at all, so it has not had a chance to check what is inside it.

How to Check Which User Owns the Config, and Which User Needs It

Two facts settle this, and both are cheap to get.

Fact one: who owns the file right now. List the config directory rather than just the file, since a mismatched parent directory can produce the same error even on a correctly owned file:

ls -l ~/.openclaw/

The third and fourth columns of the output are the owning user and group. If that user is root and you are not running the gateway as root, you have found the cause.

Fact two: which user the gateway actually runs as. This is not always the user you are logged in as, and assuming it is is the most common way this diagnosis goes wrong.

• If the gateway starts under systemd, read the unit file for a User= line. That line, not your login shell, decides the identity.
• If the gateway runs in a container, check the image’s default user, a USER line in the Dockerfile, or run id inside the running container. Bind-mounted files keep the ownership they had on the host, and the container’s internal user is frequently a different numeric UID with no relationship to your host username.
• If the gateway runs as a plain foreground process from a terminal, the answer is whichever account is running that shell, which whoami will tell you directly.

Compare the two facts. If the file’s owner and the gateway’s user are not the same account, you have confirmed the cause and the repair is a single command.

The Repair

Once you know both users, the fix is a straightforward ownership change:

sudo chown <gateway-user>:<gateway-user> ~/.openclaw/openclaw.json
sudo chown <gateway-user>:<gateway-user> ~/.openclaw

Two details make or break this fix.

Target the user the gateway actually runs as, not the user typing the command. On a Docker host these are routinely different accounts, and chown-ing to your own login user will look like it worked, restart cleanly, and then fail again the moment the container’s internal user tries to read the file.

Fix the directory as well as the file. Directory permissions gate whether a process can even traverse into .openclaw to reach the file inside it. A correctly owned openclaw.json sitting inside a root-owned directory can still be unreachable.

If the ownership was set by a root install, check the rest of the tree at the same time rather than assuming this file was the only casualty. The next section covers why.

Why It Happens, and How to Not Do It Again

The root cause behind this error is almost always the same one: the installer, or a manual write to the config, ran with elevated privileges, while the process that later needs to read the result does not.

Running an installer with sudo out of habit, because some other step in the setup needed root and it was simpler to keep the prefix, is the single most common way a config directory ends up root-owned underneath a gateway that runs as an ordinary user. The install completes without complaint. The failure only shows up later, when the gateway itself tries to open the file it was just handed.

The fix at that point is not only the one file. If the installer ran as root once, everything else it touched in that pass may carry the same ownership, including other files under .openclaw that have not been opened yet and have not failed yet. chown the directory tree, not just the file named in the error, or expect this same message to reappear on a different filename next week.

The prevention is simpler than the diagnosis: do not run OpenClaw’s installer or setup commands with sudo. If a particular step genuinely requires root, such as installing a system package, isolate that step and let everything that writes into .openclaw run as the same unprivileged user the gateway will use afterward. For the full setup sequence, including where privilege is and is not required, see the OpenClaw tutorial . For the broader set of startup and runtime failures this one sits alongside, the OpenClaw errors reference is the index to work from.