Section 8: openclaw.json — Handle With Care

Your ~/.openclaw/openclaw.json file is a critical system config. It controls plugins, channels, behavior, and guardrails.

::: warning ⚠️ Do not hand-edit this file Editing openclaw.json manually is the most common way to accidentally break your setup. A single misplaced comma, a "smart quote" instead of a plain one, or a deleted field can prevent OpenClaw from starting at all.

If you need to change settings, use the wizard or dashboard instead:

• Run openclaw setup to change configuration with built-in validation
• Open openclaw dashboard to adjust settings through the web interface

These tools validate your changes before saving, so mistakes are caught before they cause problems. :::

The safe path for configuration changes

For most changes, you should never need to open openclaw.json directly. Here's what to use instead:

For initial setup or reconfiguration: Run the setup wizard.

🖥️ Type this in your terminal:

openclaw setup

For ongoing management: Open the dashboard in your browser.

🖥️ Type this in your terminal:

openclaw dashboard

For auth/credential issues: Re-run the onboarding flow.

🖥️ Type this in your terminal:

openclaw onboard

Before any config change: always back up first

If you are about to make any configuration change — whether through the wizard or otherwise — back up your config first. This takes five seconds and can save you an hour of recovery work.

🖥️ Type this in your terminal:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

If something breaks, restore from that backup:

🖥️ Type this in your terminal:

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

Common reasons config breaks:

• Missing comma between fields
• Wrong quotes (word processors use "curly" quotes; JSON requires straight " ones)
• Deleting a required field

Recovery options:

1. Restore from backup (fastest)
2. If no backup exists, re-run onboarding to regenerate a clean config:

🖥️ Type this in your terminal:

openclaw onboard

Advanced users only: JSON structure reference

If you are an experienced user who needs to understand the raw file structure — for example, to write automation scripts or troubleshoot at a deep level — the format looks like this:

⚙️ Reference only — do not paste this into any file:

{
  "env": {
    "ANTHROPIC_API_KEY": "your-key-here"
  },
  "plugins": {
    "entries": {}
  }
}

Do not copy this. It is incomplete and illustrative only. Always use openclaw setup or openclaw dashboard for real changes.

::: power-user Treat openclaw.json like infrastructure code: back it up before changes, validate every patch, and avoid ad-hoc edits under pressure. :::