OpenClaw Configuration Guide: How to Edit openclaw.json Safely

If you want the short answer, OpenClaw reads its configuration from ~/.openclaw/openclaw.json, and the safest way to change it is to start with onboarding or the config CLI, then make small edits you can verify quickly.

That is the sane path.

Configuration is where OpenClaw becomes your setup instead of a generic default install. It is where you choose models, channels, permissions, workspaces, skills, and other runtime behavior.

It is also where people break perfectly good installs by editing too much at once.

This guide explains how OpenClaw configuration works, where the config file lives, which editing methods are safest, and how to avoid the most common mistakes.

Where OpenClaw configuration lives

The official docs say OpenClaw reads an optional JSON5 config file from:

~/.openclaw/openclaw.json

If that file is missing, OpenClaw uses safe defaults.

That detail matters because it changes how you should think about setup. Configuration is not mandatory on day one. It is how you move from the default baseline to the version of OpenClaw that matches your actual workflow.

Why configuration matters

The configuration docs list the common reasons people add a config file:

• connect channels and control who can message the bot
• set models, tools, sandboxing, or automation
• tune sessions, media, networking, or UI

That is a useful way to frame it.

In other words, configuration is not paperwork. It is the layer that controls how the assistant behaves in the real world.

The four safest ways to configure OpenClaw

1. Onboarding

The docs explicitly recommend starting with openclaw onboard if you are new.

That is good advice.

Onboarding is the least error-prone way to get the basics right because it asks for the important information in order instead of expecting you to know the whole schema up front.

2. The config CLI

For targeted changes, the CLI is often the cleanest option.

The docs show examples like:

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

This is a good method when you know exactly what you want to change and do not want to hand-edit the whole file.

3. The Control UI

The configuration docs note that the Control UI can render config fields and provide a raw JSON editor when needed. That can be more comfortable than editing a file directly if you want some structure around the process.

4. Direct file editing

You can still edit ~/.openclaw/openclaw.json directly. Just do it with restraint.

OpenClaw uses JSON5, which means comments and trailing commas are allowed. That is nice. It also uses strict validation, which means bad config changes are not silently ignored.

A simple minimal config

The docs show a minimal example like this:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

That is a good reminder that you do not need a massive config to get value. A few clear settings usually beat a giant file copied from somewhere else.

The safest workflow for editing config

Here is the pattern I recommend for most people.

Step 1: make one change at a time

Do not modify models, skills, channels, and group rules all at once.

Step 2: prefer the CLI for narrow edits

If you only need to change one field, use openclaw config get and openclaw config set instead of editing a long file by hand.

Step 3: verify the Gateway after changes

Use status and sanity checks right away.

openclaw gateway status

Step 4: use the dashboard to confirm the assistant still behaves normally

openclaw dashboard

Step 5: keep the docs open when touching unfamiliar sections

This sounds obvious, but it saves a lot of pain.

What strict validation means in practice

The configuration docs are very clear on this: OpenClaw only accepts configurations that fully match the schema. Unknown keys, invalid values, or malformed types can cause the Gateway to refuse to start.

That sounds harsh until you have lived through the alternative.

Silent misconfiguration is worse.

At least with strict validation, you know something is wrong immediately.

When validation fails, the docs recommend using openclaw doctor to see the exact issue, and openclaw doctor --fix when appropriate.

That is the kind of diagnostic muscle memory worth building early.

Common configuration sections worth learning first

Workspace and agent defaults

This is one of the most important settings because it controls where the agent reads and writes by default.

Models

The docs show a model configuration shape where you set a primary model and optional fallbacks. If you care about reliability, fallbacks are worth thinking about earlier than most people do.

Channel access rules

The configuration docs explain dmPolicy options like pairing, allowlist, open, and disabled. This matters because it is the difference between “people can message the bot safely” and “I accidentally opened the door too wide.”

Skills

You can define a shared baseline with agents.defaults.skills and override specific agents later. That is a strong pattern because it keeps the default setup sane while still allowing specialist agents.

Practical examples

Read one value

openclaw config get agents.defaults.workspace

Set one value

openclaw config set agents.defaults.heartbeat.every "2h"

Remove one value

openclaw config unset plugins.entries.brave.config.webSearch.apiKey

These are small commands, but they represent a good habit: targeted changes, quick verification, minimal drama.

Common mistakes people make with OpenClaw config

Copying a giant config they do not understand

This is how small mistakes become long debugging sessions.

Treating config as a one-time chore

Good OpenClaw setups evolve. Configuration is not finished once. It gets tuned over time.

Editing direct messages and group rules casually

Access policies deserve attention. A sloppy allowFrom or policy decision can create a security problem, not just a usability problem.

Forgetting that defaults can be enough

If the current setup works, you do not need to touch every setting just because the schema exists.

Where to go next after basic configuration

Once the basics make sense, these are the most useful follow-up resources:

• Setup guide
• Workspace files
• Skills guide
• Memory guide
• OpenClaw heartbeat setup
• OpenClaw cron setup

Official references:

• OpenClaw configuration docs
• OpenClaw getting started docs
• OpenClaw dashboard docs
• OpenClaw on GitHub

Final take

The best way to handle OpenClaw configuration is not to memorize the whole schema. It is to make small, deliberate changes with a clear reason for each one.

That keeps the system understandable.

And with agent systems, understandable is underrated.

FAQ

Where is the OpenClaw config file?

By default it lives at ~/.openclaw/openclaw.json.

What format does OpenClaw use for configuration?

It uses JSON5, which supports helpful things like comments and trailing commas.

Should I edit the config file directly?

You can, but for small changes the config CLI is often safer and faster.

What happens if my config is invalid?

OpenClaw uses strict validation, so the Gateway can refuse to start. Use openclaw doctor to diagnose the issue.

What should I configure first?

Start with the basics: workspace, model provider, access rules, and only the skills or channels you actually need.

How do I verify a config change worked?

Check Gateway status, then open the dashboard and make sure the assistant behaves normally.

A realistic way to grow your config over time

The best OpenClaw configs usually grow in stages.

Stage one is basic runtime setup. Stage two is one channel and one or two practical rules. Stage three is where you start caring about things like skills, routing, automations, and more opinionated guardrails.

That progression matters because configuration quality comes from clarity, not from file length.

A good mental model for config changes

Ask three questions before changing anything:

1. What behavior do I want to change?
2. What exact setting controls that behavior?
3. How will I verify the change worked?

If you cannot answer those, you are probably about to make a messy edit.

Why smaller config edits win

Small edits are easier to review, easier to test, and easier to roll back mentally.

That sounds basic, but it is one of the biggest differences between clean OpenClaw setups and chaotic ones. The clean setups have a reason for each setting. The chaotic ones look like someone copied a whole reference page into one file and hoped for the best.

That sounds almost too simple, but it is the habit that keeps configuration work from turning into self-inflicted chaos.