Configuration

OpenClaw reads an optional JSON5 config from

. The active config path must be a regular file. Symlinked layouts are unsupported for OpenClaw-owned writes; an atomic write may replace the path instead of preserving the symlink. If you keep config outside the default state directory, point directly at the real file.

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.

Agents and automation should use

for exact field-level docs before editing config. Use this page for task-oriented guidance and Configuration reference for the broader field map and defaults.

Minimal config

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

Editing config

```bash} openclaw onboard # full onboarding flow openclaw configure # config wizard ``` ```bash} openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab. The Control UI renders a form from the live config schema, including field `title` / `description` docs metadata plus plugin and channel schemas when available, with a **Raw JSON** editor as an escape hatch. For drill-down UIs and other tooling, the gateway also exposes `config.schema.lookup` to fetch one path-scoped schema node plus immediate child summaries. Edit `~/.openclaw/openclaw.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)).

Strict validation

prints the canonical JSON Schema used by Control UI and validation. fetches a single path-scoped node plus child summaries for drill-down tooling. Field / docs metadata carries through nested objects, wildcard (), array-item (), and / / branches. Runtime plugin and channel schemas merge in when the manifest registry is loaded.

When validation fails:

• The Gateway does not boot
• Only diagnostic commands work (
  text

  Copy

  openclaw doctor
  ,
  text

  Copy

  openclaw logs
  ,
  text

  Copy

  openclaw health
  ,
  text

  Copy

  openclaw status
  )
• Run
  text

  Copy

  openclaw doctor
  to see exact issues
• Run
  text

  Copy

  openclaw doctor --fix
  (or
  text

  Copy

  --yes
  ) to apply repairs

The Gateway keeps a trusted last-known-good copy after each successful startup. If

later fails validation (or drops , shrinks sharply, or has a stray log line prepended), OpenClaw preserves the broken file as , restores the last-known-good copy, and logs the recovery reason. The next agent turn also receives a system-event warning so the main agent does not blindly rewrite the restored config. Promotion to last-known-good is skipped when a candidate contains redacted secret placeholders such as . When every validation issue is scoped to , OpenClaw does not perform whole-file recovery. It keeps the current config active and surfaces the plugin-local failure so a plugin schema or host-version mismatch cannot roll back unrelated user settings.

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

Restrict skills per agent

Tune gateway channel health monitoring

Tune gateway WebSocket handshake timeout

Configure sessions and resets

Enable sandboxing

Enable relay-backed push for official iOS builds

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

and applies changes automatically — no manual restart needed for most settings.

Direct file edits are treated as untrusted until they validate. The watcher waits for editor temp-write/rename churn to settle, reads the final file, and rejects invalid external edits by restoring the last-known-good config. OpenClaw-owned config writes use the same schema gate before writing; destructive clobbers such as dropping

or shrinking the file by more than half are rejected and saved as for inspection.

Plugin-local validation failures are the exception: if all issues are under

, reload keeps the current config and reports the plugin issue instead of restoring .

If you see

or in logs, inspect the matching file next to , fix the rejected payload, then run . See Gateway troubleshooting for the recovery checklist.

Reload modes

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

What hot-applies vs what needs a restart

Most fields hot-apply without downtime. In

mode, restart-required changes are handled automatically.

Reload planning

When you edit a source file that is referenced through

, OpenClaw plans the reload from the source-authored layout, not the flattened in-memory view. That keeps hot-reload decisions (hot-apply vs restart) predictable even when a single top-level section lives in its own included file such as . Reload planning fails closed if the source layout is ambiguous.

Config RPC (programmatic updates)

For tooling that writes config over the gateway API, prefer this flow:

• text

  Copy

  config.schema.lookup
  to inspect one subtree (shallow schema node + child summaries)
• text

  Copy

  config.get
  to fetch the current snapshot plus
  text

  Copy

  hash
• text

  Copy

  config.patch
  for partial updates (JSON merge patch: objects merge,
  text

  Copy

  null
  deletes, arrays replace)
• text

  Copy

  config.apply
  only when you intend to replace the entire config
• text

  Copy

  update.run
  for explicit self-update plus restart
• text

  Copy

  update.status
  to inspect the latest update restart sentinel and verify the running version after a restart

Agents should treat

as the first stop for exact field-level docs and constraints. Use Configuration reference when they need the broader config map, defaults, or links to dedicated subsystem references.

Example partial patch:

bash
Copy
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

Both

and accept , , , , and . is required for both methods when a config already exists.

Environment variables

OpenClaw reads env vars from the parent process plus:

• text

  Copy

  .env
  from the current working directory (if present)
• text

  Copy

  ~/.openclaw/.env
  (global fallback)

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

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