Config - OpenClaw

Non-interactive helpers for openclaw.json: get/set/patch/unset a value by path, print the schema, validate, or print the active file path. Run openclaw config with no subcommand to open the same guided wizard as openclaw configure.

When OPENCLAW_NIX_MODE=1, OpenClaw treats openclaw.json as immutable. Read-only commands (config get, config file, config schema, config validate) still work; config writers refuse. Edit the Nix source for the install instead; for the first-party nix-openclaw distribution, use the nix-openclaw Quick Start and set values under programs.openclaw.config or instances.<name>.config.

Root options

--section <section>

string

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

Guided sections: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Examples

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

Paths

Dot or bracket notation. Quote bracket paths in shell examples so zsh does not glob-expand [0]:

openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

`config get`

Reads a value from the redacted config snapshot (secrets never print). --json prints the raw value as JSON; otherwise strings/numbers/booleans print bare and objects/arrays print as formatted JSON.

openclaw config get browser.executablePath
openclaw config get agents.defaults.model --json

`config file`

Prints the active config file path, resolved from OPENCLAW_CONFIG_PATH or the default location. The path names a regular file, not a symlink; see Write safety.

`config schema`

Prints the generated JSON schema for openclaw.json to stdout.

What it includes

The current root config schema, plus a root $schema string field for editor tooling.
Field title / description docs metadata used by the Control UI.
Nested object, wildcard (*), and array-item ([]) nodes inherit the same title / description metadata when matching field docs exist.
anyOf / oneOf / allOf branches inherit the same docs metadata too.
Best-effort live plugin + channel schema metadata when runtime manifests can be loaded.
A clean fallback schema even when the current config is invalid.

openclaw config schema
openclaw config schema > openclaw.schema.json

`config validate`

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

openclaw config validate
openclaw config validate --json

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

Values

Values parse as JSON5 when possible; otherwise they are treated as raw strings. Use --strict-json to require standard JSON with no string fallback (JSON5-only syntax such as comments, trailing commas, or unquoted keys is then rejected). --json is a legacy alias for --strict-json on config set.

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

config get <path> --json prints the raw value as JSON instead of terminal-formatted text.

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

Use --merge when adding entries to those maps:

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 --replace only when the provided value should intentionally become the complete target value.

`config set` modes

Value mode
SecretRef builder mode
Provider builder mode
Batch mode

openclaw config set <path> <value>

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

Targets secrets.providers.<alias> paths only:

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

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" }
  }
]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

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.

Batch parsing always uses the batch payload (--batch-json/--batch-file) as the source of truth; --strict-json / --json do not change batch parsing behavior. JSON path/value mode also works for SecretRefs and providers directly:

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 secrets.providers.<alias> as the path.

Common flags

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Env provider (--provider-source env)

--provider-allowlist <ENV_VAR> (repeatable)

File provider (--provider-source file)

--provider-path <path> (required)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>
--provider-allow-insecure-path

Exec provider (--provider-source exec)

--provider-command <path> (required)
--provider-arg <arg> (repeatable)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (repeatable)
--provider-pass-env <ENV_VAR> (repeatable)
--provider-trusted-dir <path> (repeatable)
--provider-allow-insecure-path
--provider-allow-symlink-command

Hardened exec provider example:

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

`config patch`

Paste or pipe a config-shaped JSON5 patch instead of running many path-based config set commands. Objects merge recursively; arrays and scalar values replace the target; null deletes the target path.

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

Pipe a patch over stdin for remote setup scripts:

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Example patch:

{
  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 --replace-path <path> when one object or array must become exactly the provided value instead of being recursively patched:

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

--dry-run runs schema and SecretRef resolvability checks without writing. Exec-backed SecretRefs are skipped by default during dry-run; add --allow-exec when you intentionally want dry-run to execute provider commands.

Dry run

--dry-run validates changes without writing openclaw.json. Available on config set, config patch, and config unset.

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

Dry-run behavior

Builder mode: runs SecretRef resolvability checks for changed refs/providers.
JSON mode (--strict-json, --json, or batch mode): runs schema validation plus SecretRef resolvability checks.
Policy validation runs against the full post-change config, so parent-object writes (for example setting hooks as an object) cannot bypass unsupported-surface validation.
Exec SecretRef checks are skipped by default to avoid command side effects; pass --allow-exec to opt in (this may execute provider commands). --allow-exec is dry-run only and errors without --dry-run.

--dry-run --json fields

ok: whether dry-run passed
operations: number of assignments evaluated
checks: whether schema/resolvability checks ran
checks.resolvabilityComplete: whether resolvability checks ran to completion (false when exec refs are skipped)
refsChecked: number of refs actually resolved during dry-run
skippedExecRefs: number of exec refs skipped because --allow-exec was not set
errors: structured missing-path, schema, or resolvability failures when ok=false

JSON output shape

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

Success example
Failure example

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}

{
  "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"
    }
  ]
}

If dry-run fails

config schema validation failed: your post-change config shape is invalid; fix the path/value or provider/ref object shape.
Config policy validation failed: unsupported SecretRef usage: move that credential back to plaintext/string input; keep SecretRefs on supported surfaces only.
SecretRef assignment(s) could not be resolved: the referenced provider/ref cannot currently resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
Dry run note: skipped <n> exec SecretRef resolvability check(s): rerun with --allow-exec if you need exec resolvability validation.
For batch mode, fix failing entries and rerun --dry-run before writing.

Applying changes

After every successful config set / config patch / config unset, the CLI prints one of three hints so you know whether the gateway needs a restart:

Hint	Meaning
`Restart the gateway to apply.`	The changed path needs a full restart.
`Change will apply without restarting the gateway.`	Hot reload picks it up automatically.
`No gateway restart needed.`	Nothing runtime-relevant changed.

Writes to plugins.entries (or any subpath) always require a restart, since the CLI cannot prove every plugin’s reload metadata is loaded.

Write safety

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 openclaw.json.rejected.*.

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:

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:

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 fail startup or are skipped by hot reload; Gateway does not rewrite openclaw.json. Run openclaw doctor --fix to repair prefixed/clobbered config or restore the last-known-good copy. See Gateway troubleshooting. Whole-file recovery is reserved for doctor repair. Plugin schema changes or minHostVersion skew stay loud instead of rolling back unrelated user settings such as models, providers, auth profiles, channels, gateway exposure, tools, memory, browser, or cron config.

Repair loop

After openclaw config validate passes, 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:

openclaw chat

Inside the TUI, a leading ! runs a literal local shell command (after a one-time per-session confirmation prompt):

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

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.

​Root options

​Examples

​Paths

​config get

​config file

​config schema

​config validate

​Values

​config set modes

​Provider builder flags

​config patch

​Dry run

​JSON output shape

​Applying changes

​Write safety

​Repair loop

​Related

Root options

Examples

Paths

`config get`

`config file`

`config schema`

`config validate`

Values

`config set` modes

Provider builder flags

`config patch`

Dry run

JSON output shape

Applying changes

Write safety

Repair loop

Related