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.

</Warning>

Schema tooling notes:

- `openclaw config schema` prints the same JSON Schema family used by Control UI

and config validation.

- Treat that schema output as the canonical machine-readable contract for

`openclaw.json`; this overview and the configuration reference summarize it.

- Field `title` and `description` values are carried into the schema output for

editor and form tooling.

- Nested object, wildcard (`*`), and array-item (`[]`) entries inherit the same

docs metadata where matching field documentation exists.

- `anyOf` / `oneOf` / `allOf` composition branches inherit the same docs

metadata too, so union/intersection variants keep the same field help.

- `config.schema.lookup` returns one normalized config path with a shallow

schema node (`title`, `description`, `type`, `enum`, `const`, common bounds,

and similar validation fields), matched UI hint metadata, and immediate child

summaries for drill-down tooling.

- Runtime plugin/channel schemas are merged in when the gateway can load the

current manifest registry.

- `pnpm config:docs:check` detects drift between docs-facing config baseline

artifacts and the current schema surface.

`openclaw config schema` prints the canonical JSON Schema used by Control UI

and validation. `config.schema.lookup` fetches a single path-scoped node plus

child summaries for drill-down tooling. Field `title`/`description` docs metadata

carries through nested objects, wildcard (`*`), array-item (`[]`), and `anyOf`/

`oneOf`/`allOf` branches. Runtime plugin and channel schemas merge in when the

manifest registry is loaded.

When validation fails:

- Run `openclaw doctor` to see exact issues

- Run `openclaw doctor --fix` (or `--yes`) to apply repairs

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

`openclaw.json` is later changed outside OpenClaw and no longer validates, startup

and hot reload preserve the broken file as a timestamped `.clobbered.*` snapshot,

restore the last-known-good copy, and log a loud warning with the recovery reason.

Startup read recovery also treats sharp size drops, missing config metadata, and a

missing `gateway.mode` as critical clobber signatures when the last-known-good

copy had those fields.

If a status/log line is accidentally prepended before an otherwise valid JSON

config, gateway startup and `openclaw doctor --fix` can strip the prefix,

preserve the polluted file as `.clobbered.*`, and continue with the recovered

JSON.

The next main-agent turn also receives a system-event warning telling it that the

config was restored and must not be blindly rewritten. Last-known-good promotion

is updated after validated startup and after accepted hot reloads, including

OpenClaw-owned config writes whose persisted file hash still matches the accepted

write. Promotion is skipped when the candidate contains redacted secret

placeholders such as `***` or shortened token values.

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

If `openclaw.json` later fails validation (or drops `gateway.mode`, shrinks

sharply, or has a stray log line prepended), OpenClaw preserves the broken file

as `.clobbered.*`, 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 `***`.

## Common tasks

## Config RPC (programmatic updates)

<Note>

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`.

</Note>

Safe/default flow:

- `config.schema.lookup`: inspect one path-scoped config subtree with a shallow

schema node, matched hint metadata, and immediate child summaries

- `config.get`: fetch the current snapshot + hash

- `config.patch`: preferred partial update path

- `config.apply`: full-config replacement only

- `update.run`: explicit self-update + restart

When you are not replacing the entire config, prefer `config.schema.lookup`

then `config.patch`.

<AccordionGroup>

<Accordion title="config.apply (full replace)">

Validates + writes the full config and restarts the Gateway in one step.

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

<Warning>

`config.apply` replaces the **entire config**. Use `config.patch` for partial updates, or `openclaw config set` for single keys.

</Warning>

Params:

- `raw` (string) — JSON5 payload for the entire config

- `baseHash` (optional) — config hash from `config.get` (required when config exists)

- `sessionKey` (optional) — session key for the post-restart wake-up ping

- `note` (optional) — note for the restart sentinel

- `restartDelayMs` (optional) — delay before restart (default 2000)

Restart requests are coalesced while one is already pending/in-flight, and a 30-second cooldown applies between restart cycles.

```bash

openclaw gateway call config.get --params '{}' # capture payload.hash

openclaw gateway call config.apply --params '{

"raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",

"baseHash": "<hash>",

"sessionKey": "agent:main:whatsapp:direct:+15555550123"

}'

```

- `config.schema.lookup` to inspect one subtree (shallow schema node + child

summaries)

- `config.get` to fetch the current snapshot plus `hash`

- `config.patch` for partial updates (JSON merge patch: objects merge, `null`

deletes, arrays replace)

- `config.apply` only when you intend to replace the entire config

- `update.run` for explicit self-update plus restart

</Accordion>

<Accordion title="config.patch (partial update)">

Merges a partial update into the existing config (JSON merge patch semantics):

- Objects merge recursively

- `null` deletes a key

- Arrays replace

Params:

- `raw` (string) — JSON5 with just the keys to change

- `baseHash` (required) — config hash from `config.get`

- `sessionKey`, `note`, `restartDelayMs` — same as `config.apply`

<Note>

Control-plane writes (`config.apply`, `config.patch`, `update.run`) are

rate-limited to 3 requests per 60 seconds per `deviceId+clientIp`. Restart

requests coalesce and then enforce a 30-second cooldown between restart cycles.

</Note>

Restart behavior matches `config.apply`: coalesced pending restarts plus a 30-second cooldown between restart cycles.

Example partial patch:

```bash

openclaw gateway call config.patch --params '{

"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",

"baseHash": "<hash>"

}'

```

```bash

openclaw gateway call config.get --params '{}' # capture payload.hash

openclaw gateway call config.patch --params '{

"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",

"baseHash": "<hash>"

}'

```

</Accordion>

</AccordionGroup>

Both `config.apply` and `config.patch` accept `raw`, `baseHash`, `sessionKey`,

`note`, and `restartDelayMs`. `baseHash` is required for `config.patch` and

recommended for `config.apply` when a config already exists.

## Environment variables