Configuration and operations

Configuration

OpenClaw reads an optional JSON5 config from ~/.openclaw/openclaw.json. If the file is missing, OpenClaw uses safe defaults. Common reasons to add a config:

Connect channels and control who can message the bot
Set models, tools, sandboxing, or automation (cron, hooks)
Tune sessions, media, networking, or UI

See the full reference for every available field.

💡 New to configuration? Start with openclaw onboard for interactive setup, or check out the Configuration Examples guide for complete copy-paste configs.

Minimal config

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

Editing config

openclaw onboard       # full setup wizard
openclaw configure     # config wizard

Strict validation

⚠️ OpenClaw only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to refuse to start. The only root-level exception is $schema (string), so editors can attach JSON Schema metadata.

When validation fails:

The Gateway does not boot
Only diagnostic commands work (openclaw doctor, openclaw logs, openclaw health, openclaw status)
Run openclaw doctor to see exact issues
Run openclaw doctor --fix (or --yes) to apply repairs

Common tasks

Set up a channel (WhatsApp, Telegram, Discord, etc.)

Choose and configure models

Control who can message the bot

Set up group chat mention gating

Configure sessions and resets

Enable sandboxing

Set up heartbeat (periodic check-ins)

Configure cron jobs

Set up webhooks (hooks)

Configure multi-agent routing

Split config into multiple files ($include)

Config hot reload

The Gateway watches ~/.openclaw/openclaw.json and applies changes automatically — no manual restart needed for most settings.

Reload modes

Mode	Behavior
`hybrid` (default)	Hot-applies safe changes instantly. Automatically restarts for critical ones.
`hot`	Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it.
`restart`	Restarts the Gateway on any config change, safe or not.
`off`	Disables file watching. Changes take effect on the next manual restart.

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

What hot-applies vs what needs a restart

Most fields hot-apply without downtime. In hybrid mode, restart-required changes are handled automatically.

Category	Fields	Restart needed?
Channels	`channels.*`, `web` (WhatsApp) — all built-in and extension channels	No
Agent & models	`agent`, `agents`, `models`, `routing`	No
Automation	`hooks`, `cron`, `agent.heartbeat`	No
Sessions & messages	`session`, `messages`	No
Tools & media	`tools`, `browser`, `skills`, `audio`, `talk`	No
UI & misc	`ui`, `logging`, `identity`, `bindings`	No
Gateway server	`gateway.*` (port, bind, auth, tailscale, TLS, HTTP)	Yes
Infrastructure	`discovery`, `canvasHost`, `plugins`	Yes

ℹ️ gateway.reload and gateway.remote are exceptions — changing them does not trigger a restart.

Config RPC (programmatic updates)

ℹ️ Control-plane write RPCs (config.apply, config.patch, update.run) are rate-limited to 3 requests per 60 seconds per deviceId+clientIp. When limited, the RPC returns UNAVAILABLE with retryAfterMs.

config.apply (full replace)

config.patch (partial update)

Environment variables

OpenClaw reads env vars from the parent process plus:

.env from the current working directory (if present)
~/.openclaw/.env (global fallback)

Neither file overrides existing env vars. You can also set inline env vars in config:

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Shell env import (optional)

Env var substitution in config values

Secret refs (env, file, exec)

See Environment for full precedence and sources.

Full reference

For the complete field-by-field reference, see Configuration Reference.

Gateway Runbook Configuration Reference