OneClickClaw.io

Where is the OpenClaw config file, and how do you change its location?

The short answer is ~/.openclaw/openclaw.json, written in JSON5. The longer answer matters when your edits appear to be ignored, which is almost always a second config file or an environment variable winning over the one you edited.

The OneClickClaw crab mascot holding up a config card

By default OpenClaw reads a single file:

~/.openclaw/openclaw.json

It is JSON5, not strict JSON, which means comments and trailing commas are allowed. That is deliberate, because the file is meant to be edited by hand.

The exact path per platform

PlatformPath
Linux/home/<user>/.openclaw/openclaw.json
macOS/Users/<user>/.openclaw/openclaw.json
WindowsC:\Users\<user>\.openclaw\openclaw.json
DockerInside the container, at the home of the user the process runs as

On a managed server the file belongs to the user the gateway runs as, which is often not the user you logged in with. If ls ~/.openclaw comes back empty on a machine where OpenClaw is clearly running, that is usually why.

The three environment variables that move it

VariableDefaultWhat it changes
OPENCLAW_HOME~/.openclaw/The root of everything, config included
OPENCLAW_CONFIG_PATH$OPENCLAW_HOME/openclaw.jsonThe config file alone
OPENCLAW_STATE_DIR$OPENCLAW_HOME/state/Mutable state, not config

OPENCLAW_CONFIG_PATH is the specific one. Set it and the default is ignored entirely, which is exactly what you want when running more than one instance on the same machine.

Why your edit did not take effect

This is the real reason most people search for the config path. Settings resolve in a fixed order, and the first source that defines a value wins:

  1. Process environment variables
  2. .env in the current working directory
  3. ~/.openclaw/.env
  4. The env block inside openclaw.json
  5. Shell import, meaning files you sourced

Read that list twice if you are debugging. An ANTHROPIC_API_KEY exported in your shell beats the one written in the config file, every time. The config is not being ignored, it is being outranked.

The same trap catches services. A variable exported in .bashrc does not exist for a systemd unit, so the config file wins there and loses in your terminal, and the same install behaves differently depending on how it was started.

Running more than one instance

Each instance needs its own values for all four of these, or they will fight over the same files:

  • OPENCLAW_CONFIG_PATH
  • OPENCLAW_STATE_DIR
  • The workspace path
  • The gateway port, default 18789

Permissions, because the file holds secrets

openclaw.json stores API keys in plaintext. So do several of its neighbours. All of these should be chmod 600:

  • ~/.openclaw/openclaw.json
  • ~/.openclaw/credentials/
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/exec-approvals.json
  • ~/.openclaw/agents/<id>/agent/auth-profiles.json

If you would rather keep keys out of the file altogether, reference them instead of writing them: "apiKey": "env:ANTHROPIC_API_KEY". Note the env: prefix. Writing process.env.ANTHROPIC_API_KEY does not work, that is JavaScript syntax and the config is data.

One more warning worth having

The setup wizard overwrites config sections rather than merging into them. Back up openclaw.json before running it on an install you have customised.

Frequently asked questions

Why are my edits ignored?
Almost always because an environment variable outranks the config file, or because OPENCLAW_CONFIG_PATH points at a different file than the one you opened. Check the precedence table on this page.
Can I put comments in the config?
Yes. The file is JSON5, not strict JSON, so line comments and trailing commas are both legal.
Is it safe to keep API keys in there?
They are stored in plaintext, so the file must be chmod 600. If you would rather not have keys on disk at all, reference them as env:VAR_NAME and set the variable elsewhere.

Related guides

← All troubleshooting
Where is the OpenClaw config file?