Every decision OpenClaw makes (which model answers your messages, which channels it listens on, how it authenticates) traces back to one file. Most people who run OpenClaw never open it directly; they click through onboarding once and never come back. A smaller group opens it, gets nervous about a stray comma breaking something, and closes it again. Neither reaction is wrong, but if you're running OpenClaw as real infrastructure rather than a weekend experiment, you need to know what's in there and how to change it without holding your breath.
This isn't a full reference of every key OpenClaw supports. It's a practical map: where the file lives, how to edit it without wrecking your setup, what the models section controls, and the handful of settings worth touching on a fresh install. If you haven't installed OpenClaw yet, our OpenClaw Setup: The Complete 2026 Guide covers that ground first.
Where the config file actually lives
The default location is `~/.openclaw/openclaw.json`. That's the file most installs write to and the one most documentation assumes you're looking at.
It isn't the only place it can be, though, and this trips people up more often than you'd expect. Some setups, particularly ones that lean on JSON5 for comments and trailing commas, use `~/.config/openclaw/openclaw.json5` instead, following the XDG config convention a lot of Linux tooling defaults to. If you're troubleshooting on a machine you didn't set up yourself, check both paths before assuming the config is missing.
There's a third wrinkle if you're managing an older install. OpenClaw wasn't always called OpenClaw, and instances that predate the rename may still have a `~/.openclaw/clawdbot.json` sitting around from that earlier era. If you inherited a server or you're migrating a legacy install, that file is worth checking. It's easy to spend twenty minutes editing a config the running process isn't actually reading because the real one lives somewhere else.
The practical takeaway: before you change anything, confirm which file your instance is actually loading. A quick way to sanity-check is to make a small, reversible change through the CLI (covered next) and confirm it takes effect, rather than assuming the path.
Editing it safely: CLI first, hand-editing second
You have two real ways to change OpenClaw's configuration, and they're not equally forgiving.
The first is to edit the JSON file directly in a text editor. This works, and for developers who live in JSON all day it's often the fastest path once you know exactly which key you want. The catch is that `openclaw.json` is, unsurprisingly, JSON, and JSON is unforgiving about syntax. A missing closing brace, a trailing comma, a quote you forgot to close, and the file can fail to parse. Depending on how OpenClaw handles that failure, you're looking at anything from a silently ignored setting to an agent that won't start at all.
The second, and the one we'd point most people at, is the CLI. Two commands cover almost everything:
- `openclaw config wizard` walks you through settings interactively, the same guided flow you got during initial onboarding, without having to remember every key name or worry about syntax.
- `openclaw config set <path> <value>` changes one specific setting from the command line in a single, targeted move. You tell it what to change, and it writes valid JSON back to disk without an editor and without the risk of a stray character breaking the file.
If you're not fully comfortable reading and writing raw JSON, or you're making a change on a production box where downtime actually costs you something, use the CLI. It stays the safer, more repeatable way to manage config even once you're fully comfortable with JSON, and it's what we default to on setups we've been running for months. It's also the approach behind our own OpenClaw Setup work, where a broken config on a client's server simply isn't an option. Save hand-editing for when you need to review the whole file at once or make several related changes the CLI would take a dozen commands to express.
The models section, explained
This is the part of the config most people eventually need to touch, because it's where OpenClaw decides which AI provider and model answers your messages.
Model and provider settings live under a `models` section in the config. Within it, `models.providers` is a map you define yourself, keyed by provider id. That's the mechanism that lets you register more than one AI provider on the same OpenClaw instance and configure each independently, an entry per provider, each with its own settings. You're not locked into a single vendor baked in at install time; the config is built to hold several side by side.
Separately, `agents.defaults.model.primary` decides which model gets used by default. It takes a "provider/model" reference, something like `zai/glm-5.2` (that's just an example of the format, not a model we're recommending). The value points at one of the providers you've defined in `models.providers` and tells OpenClaw which model within it to default to.
In practice, most people don't hand-edit either of these directly. There are dedicated CLI shortcuts built for model changes: `openclaw models set <provider/model>` switches your default model in one command, and `openclaw models auth login --provider <id> --set-default` authenticates a new provider and makes it the default in a single step. Both write to the same `models` structure, just without you needing to know the exact JSON shape.
If you're actively juggling multiple models, say, a fast model for routine replies and a stronger one for anything that needs real reasoning, and you want to switch between them without taking your agent offline, we cover that workflow in more depth in Switching LLM Models on OpenClaw Without Downtime. This section is the "what the config holds," that post is the "how to change it live."
Settings worth customizing first on a new install
Onboarding gets you a working agent, not necessarily a well-tuned one. Once the basics are running, a few areas are worth a deliberate look before you consider the setup finished.
Start with your default model. The provider OpenClaw defaults to out of the box isn't necessarily the one that fits your workload or budget, so decide deliberately, using `openclaw models set` or the wizard to make the change explicit.
If you plan to use more than one model, add the extra providers now rather than later. When your workflow benefits from routing different tasks to different models, get a second or third entry into `models.providers` while the config is still simple. Retrofitting a multi-provider setup onto a year of accumulated settings is harder than starting with room for it.
Also go back over anything you configured in a hurry during onboarding. Most people move fast through it just to see the agent work, and those quick decisions are worth a second look once you know how you're actually using it day to day. Treat your first-week config as a draft, not a final answer.
Whatever you touch, change it through the CLI where a dedicated command exists. It's less to remember, and it removes an entire category of self-inflicted outage.
Back it up before you touch it
This is the boring advice nobody follows until the day they wish they had. Before any hand-edit, or before a batch of CLI changes you're not fully certain about, copy the file:
```
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
```
It costs five seconds. If a hand-edit breaks the JSON, or a wizard run takes a setting somewhere you didn't intend, you restore the backup and you're back to a known-good state immediately, instead of reconstructing settings from memory while your agent sits offline.
If you do end up with a config that won't parse, the JSON error message is usually your fastest way back. Most editors, or a plain `node -e "JSON.parse(require('fs').readFileSync('path'))"` check, will point you straight at the line with the broken bracket or comma. Fix that one character, or restore the `.bak` copy if the damage is bigger than one typo, and you're running again. Either way, this is exactly the situation the CLI approach is designed to prevent in the first place: it never writes a file that doesn't parse.
Frequently asked questions
Can I just delete openclaw.json and start over?
You can, and OpenClaw will regenerate a fresh default config the next time you run onboarding, but you'll lose every setting you've customized: provider credentials, channel connections, workspace scoping, all of it. Restoring a backup or fixing the specific broken key is almost always faster than starting from zero, so treat a full reset as a last resort rather than a first move.
Why does my config live somewhere other than ~/.openclaw/openclaw.json?
Most likely your install uses the XDG-style path at `~/.config/openclaw/openclaw.json5` instead, or you're on an older instance still running off a `~/.openclaw/clawdbot.json` file from before the project's rename. Check all three locations before assuming the config is missing or corrupted.
Is it safe to edit openclaw.json while OpenClaw is running?
It depends on whether OpenClaw reloads config live or only reads it at startup, and that behavior isn't something to guess about on a production box. The safer pattern, regardless, is to make your change, verify the file still parses, and then restart the process so you know exactly what state it's running with, rather than hoping a live edit picked up cleanly.
I don't want to mess with JSON at all. What are my options?
Stick to the CLI entirely. `openclaw config wizard` handles general settings interactively, and `openclaw models set` or `openclaw models auth login --set-default` handle model changes without you ever opening the file. If you'd rather have someone configure the whole thing properly the first time, including model routing, channel setup, and the security settings that matter once this is running your business, our OpenClaw Setup team in Dubai handles it end to end. Email team@ins.ae or WhatsApp us at +971 58 995 4553 and we'll take it from there.
