Lesson 1. The OpenClaw Configuration File#

Why you need this#

When you first start working with OpenClaw, everything works “out of the box” — with default settings. But sooner or later you’ll want to change something: connect a messenger, choose a different AI model, set up a schedule. For all of this, there’s the configuration file — a single file that stores all the parameters of your assistant.

It’s like a remote control: one file — and you control all of OpenClaw’s behavior.

What is openclaw.json#

openclaw.json is a text file in JSON5 format (an improved JSON that allows comments and trailing commas). It describes all settings: which messengers are connected, which AI model is used, which tools are available, and much more.

Where it’s located#

The file is at:

~/.openclaw/openclaw.json

What does ~ mean? It’s shorthand for your user’s “home folder.” On Mac it’s /Users/your_name/, on Linux — /home/your_name/.

If the file doesn’t exist — that’s fine! OpenClaw will work with default settings.

How to edit settings#

You have four ways to change settings. Choose whichever is most convenient:

Method 1: Setup wizard (easiest)#

Run in the terminal:

openclaw onboard

This is an interactive helper that asks questions and creates the correct configuration file for you.

For quick configuration of a specific section:

openclaw configure

Method 2: Terminal commands (one-liners)#

If you need to change something specific:

# View a current value
openclaw config get agents.defaults.workspace

# Set a new value
openclaw config set agents.defaults.heartbeat.every "2h"

# Remove a setting
openclaw config unset tools.web.search.apiKey

Method 3: Web interface#

Open in your browser:

http://127.0.0.1:18789

Go to the Config tab — there’s a convenient form with fields, as well as an editor for “raw” JSON.

Method 4: Editing the file directly#

Open the file ~/.openclaw/openclaw.json in any text editor and change the parameters you need.

What the configuration file looks like#

Here’s an example of a minimal file:

// ~/.openclaw/openclaw.json
{
  // Agent settings
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },

  // Messenger connection
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

Comments (lines starting with //) are hints for you. OpenClaw ignores them.

Hot reload — what it is and how it works#

Hot reload is when OpenClaw automatically notices that you changed the configuration file and applies changes without restarting. You don’t need to stop and restart the program!

Reload modes#

What’s applied instantly (no restart needed)#

• Messenger settings (channels)
• Agent and model settings (agents, models)
• Automation (hooks, cron, heartbeat)
• Sessions and messages
• Tools and media

What requires a restart#

• Gateway server settings (gateway.* — port, address, authorization)
• Infrastructure (discovery, plugins)

Environment variables#

Instead of writing secret keys directly in the configuration file, you can use environment variables — special named values that are stored separately.

OpenClaw reads variables from:

• The .env file in the current folder
• The ~/.openclaw/.env file

Example usage in settings:

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

Here ${OPENCLAW_GATEWAY_TOKEN} will be replaced with the actual value from the environment variable.

Checking settings#

If you made an error in the configuration file, OpenClaw won’t start and will show what’s wrong. To find and fix problems:

# Show problems
openclaw doctor

# Automatically fix
openclaw doctor --fix

Lesson summary#

• openclaw.json is the main OpenClaw configuration file, located in ~/.openclaw/
• There are 4 editing methods: wizard, commands, web interface, direct editing
• Hot reload lets you change most settings without restarting
• Secret keys are better stored in environment variables (.env file)
• If something breaks — openclaw doctor will help find and fix errors

Next lesson: Choosing an AI Model