Use this file to discover all available pages before exploring further.

Config

Config helpers for non-interactive edits in

text

openclaw.json

: get/set/patch/unset/file/schema/validate values by path and print the active config file. Run without a subcommand to open the configure wizard (same as

text

openclaw configure

Root options

Repeatable guided-setup section filter when you run `openclaw config` without a subcommand.

Supported guided sections:

text

workspace

text

model

text

web

text

gateway

text

daemon

text

channels

text

plugins

text

skills

text

health

Examples


bash
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

text
`config schema`

Print the generated JSON schema for

text

openclaw.json

to stdout as JSON.


bash
openclaw config schema

Pipe it into a file when you want to inspect or validate it with other tools:


bash
openclaw config schema > openclaw.schema.json

Paths

Paths use dot or bracket notation:


bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Use the agent list index to target a specific agent:


bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

Values

Values are parsed as JSON5 when possible; otherwise they are treated as strings. Use

text

--strict-json

to require JSON5 parsing.

text

--json

remains supported as a legacy alias.


bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

text

config get <path> --json

prints the raw value as JSON instead of terminal-formatted text.

note

Object assignment replaces the target path by default. Protected map/list paths that commonly hold user-added entries, such as `agents.defaults.models`, `models.providers`, `models.providers..models`, `plugins.entries`, and `auth.profiles`, refuse replacements that would remove existing entries unless you pass `--replace`.

Use

text

--merge

when adding entries to those maps:


bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Use

text

--replace

only when you intentionally want the provided value to become the complete target value.

text
`config set`
modes

text

openclaw config set

supports four assignment styles:

```bash} openclaw config set ``` ```bash} openclaw config set channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN ``` Provider builder mode targets `secrets.providers.` paths only:


text
```bash}
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-timeout-ms 5000
```

```bash} openclaw config set --batch-json '[ { "path": "secrets.providers.default", "provider": { "source": "env" } }, { "path": "channels.discord.token", "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" } } ]' ```


text
```bash}
openclaw config set --batch-file ./config-set.batch.json --dry-run
```

warning

SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface).

Batch parsing always uses the batch payload (

text

--batch-json

text

--batch-file

) as the source of truth.

text

--strict-json

text

--json

do not change batch parsing behavior.

text
`config patch`

Use

text

config patch

when you want to paste or pipe a config-shaped patch instead of running many path-based

text

config set

commands. The input is a JSON5 object. Objects merge recursively, arrays and scalar values replace the target value, and

text

null

deletes the target path.


bash
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5

You can also pipe a patch over stdin, which is useful for remote setup scripts:


bash
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Example patch:


json5
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}

Use

text

--replace-path <path>

when one object or array must become exactly the provided value instead of being recursively patched:


bash
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

text

--dry-run

runs schema and SecretRef resolvability checks without writing. Exec-backed SecretRefs are skipped by default during dry-run; add

text

--allow-exec

when you intentionally want dry-run to execute provider commands.

JSON path/value mode remains supported for both SecretRefs and providers:


bash
openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

Provider builder flags

Provider builder targets must use

text

secrets.providers.<alias>

as the path.

Hardened exec provider example:


bash
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

Dry run

Use

text

--dry-run

to validate changes without writing

text

openclaw.json


bash
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec

JSON output shape


json5
{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

```json} { "ok": true, "operations": 1, "configPath": "~/.openclaw/openclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0 } ``` ```json} { "ok": false, "operations": 1, "configPath": "~/.openclaw/openclaw.json", "inputModes": ["builder"], "checks": { "schema": false, "resolvability": true, "resolvabilityComplete": true }, "refsChecked": 1, "skippedExecRefs": 0, "errors": [ { "kind": "resolvability", "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.", "ref": "env:default:MISSING_TEST_SECRET" } ] } ```

Write safety

text

openclaw config set

and other OpenClaw-owned config writers validate the full post-change config before committing it to disk. If the new payload fails schema validation or looks like a destructive clobber, the active config is left alone and the rejected payload is saved beside it as

text

openclaw.json.rejected.*

warning

The active config path must be a regular file. Symlinked `openclaw.json` layouts are unsupported for writes; use `OPENCLAW_CONFIG_PATH` to point directly at the real file instead.

Prefer CLI writes for small edits:


bash
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

If a write is rejected, inspect the saved payload and fix the full config shape:


bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

Direct editor writes are still allowed, but the running Gateway treats them as untrusted until they validate. Invalid direct edits can be restored from the last-known-good backup during startup or hot reload. See Gateway troubleshooting.

Whole-file recovery is reserved for globally broken config, such as parse errors, root-level schema failures, legacy migration failures, or mixed plugin and root failures. If validation fails only under

text

plugins.entries.<id>...

, OpenClaw keeps the active

text

openclaw.json

in place and reports the plugin-local issue instead of restoring

text

.last-good

. This prevents plugin schema changes or

text

minHostVersion

skew from rolling back unrelated user settings such as models, providers, auth profiles, channels, gateway exposure, tools, memory, browser, or cron config.

Subcommands

text
config file
: Print the active config file path (resolved from
text
OPENCLAW_CONFIG_PATH
or default location). The path should name a regular file, not a symlink.

Restart the gateway after edits.

Validate

Validate the current config against the active schema without starting the gateway.


bash
openclaw config validate
openclaw config validate --json

After

text

openclaw config validate

is passing, you can use the local TUI to have an embedded agent compare the active config against the docs while you validate each change from the same terminal:

note

If validation is already failing, start with `openclaw configure` or `openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config guard.


bash
openclaw chat

Then inside the TUI:


text
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

Typical repair loop:

Compare with docs

Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.

Apply targeted edits

Apply targeted edits with `openclaw config set` or `openclaw configure`.

Re-validate

Rerun `openclaw config validate` after each change.

Doctor for runtime issues

If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.

OpenClaw Docs

Config

Root options

Examples

text
`config schema`

Paths

Values

note

text
`config set`
modes

warning

text
`config patch`

Provider builder flags

Dry run

JSON output shape

Write safety

warning

Subcommands

Validate

note

Compare with docs

Apply targeted edits

Re-validate

Doctor for runtime issues

Related

OpenClaw Docs

Config

Root options

Examples

textCopyconfig schema

Paths

Values

note

textCopyconfig set modes

warning

textCopyconfig patch

Provider builder flags

Dry run

JSON output shape

Write safety

warning

Subcommands

Validate

note

Compare with docs

Apply targeted edits

Re-validate

Doctor for runtime issues

Related

text
`config schema`

text
`config set`
modes

text
`config patch`