CLI commands

Config

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.

Externally managed config

Set OPENCLAW_CONFIG_READONLY=1 in the environment of both the Gateway and any OpenClaw CLI processes when a deployment system manages your config:

bash

export OPENCLAW_CONFIG_READONLY=1openclaw config validateopenclaw gateway run

For a service or container, set the variable in its service environment or container definition. This is a host-environment switch, not an openclaw.json field. Do not set OPENCLAW_CONFIG_READONLY in config env or env.vars. Entries in env.vars are ignored, including differently cased spellings; flat env keys are not valid configuration. Config reload cannot enable, disable, or change the host-selected read-only mode. Only the host value 1 enables this switch. Existing OPENCLAW_NIX_MODE behavior is unchanged.

Config writes are blocked, including setup, onboarding, doctor repairs, plugin install/update/uninstall/enable/disable, and mutating openclaw update flows. Startup-derived defaults stay runtime-only. Change the config through your external deployment system, then let the Gateway reload it or restart the Gateway as needed. Runtime state still needs a writable OPENCLAW_STATE_DIR.

OPENCLAW_CONFIG_READONLY=1 uses generic externally managed config messages and does not enable Nix-specific installation or service behavior. OPENCLAW_NIX_MODE=1 continues to imply immutable config, even if OPENCLAW_CONFIG_READONLY is unset or 0. For Nix installs, edit the Nix source instead; see Nix.

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

bash

openclaw config fileopenclaw config file --jsonopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config schema --jsonopenclaw config get browser.executablePathopenclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work '{"cdpPort":18801,"executablePath":"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"}' --strict-json --mergeopenclaw config set agents.defaults.heartbeat.every "2h"openclaw config set logging.audit.executionIdentity trueopenclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw config validate --json

Paths

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

bash

openclaw config get agents.defaults.workspaceopenclaw config get agents.entries.mainopenclaw config get agents.entriesopenclaw config set 'agents.entries.work.tools.exec.node' "node-id-or-name"

Prefer agents.entries.<id> paths for agent edits. The legacy agents.list[0] syntax and whole-list inputs still work with set, patch, and unset; writes persist the canonical keyed roster. Indexed edits use the current roster order. Within a batch, a submitted list keeps its order across subsequent keyed edits, including when agent IDs are numeric strings. Existing roster-deletion and $include ownership protections still apply.

When a legacy roster expands a single-agent installation in the root config file, writes retire its default marker and preserve the existing agent's responsibilities with explicit owners. An explicitly authored ownership: "explicit" cannot be combined with a legacy default: true marker.

For root-file writes, changing session.store clears a copied agents.defaults.sessionStore.agentId because that owner belongs to the previous store. To assign the destination store's owner, set that owner path explicitly in the same batch.

`config get`

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

A schema-valid but unset path explains that the runtime default applies; an unknown path suggests openclaw config schema. With --json, both use the standard CLI JSON failure envelope on stdout and exit with status 1. Without --json, diagnostics remain on stderr.

bash

openclaw config get browser.executablePathopenclaw 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.

With --json, stdout contains an object with the resolved path under path.

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

bash

openclaw config schemaopenclaw config schema --jsonopenclaw config schema > openclaw.schema.json

The schema is JSON in both modes. --json is accepted as the explicit machine-output spelling and keeps stdout reserved for the schema document.

`config validate`

Validates the current config against the active schema without starting the gateway. It also checks provider/source compatibility for every registry-declared SecretRef, including disabled plugin or channel configuration. This strict command can report an inactive mismatch that does not block normal Gateway startup, where SecretRef resolution remains limited to effectively active surfaces.

After schema validation, it checks every configured manual exec provider's command path using the same non-executing trust checks as startup: file presence, symlinks, trusted directories, permissions, ownership, and Windows ACL availability. config set, config patch, and config unset apply these checks only to providers changed or referenced by the operation, including during dry runs. Replacing the secrets or secrets.providers collection checks every remaining provider. An unrelated inactive provider does not block targeted repairs or removal of that provider.

Path validation does not execute providers or verify their output. Passing it does not guarantee successful secret resolution; exec dry runs require --allow-exec to test that separately.

bash

openclaw config validateopenclaw config validate --json

Provider and runtime params bags are intentionally typed as Record<string, unknown> because their owners define the supported keys and values. openclaw config validate can validate the container and overall config shape, but it cannot type-check provider-specific parameter names or values. Passing validation does not prove that a param is supported; consult the provider docs and verify behavior on the selected runtime and provider.

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.

bash

openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw config set channels.whatsapp.groups '{"*":{"requireMention":true}}' --strict-json

For structured values that are awkward to quote in your shell, put a config-shaped JSON5 object in a file and use config patch --file <path> --dry-run. The file contains config keys and their values, not a bare array.

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

When a write changes agents.defaults.model or a per-agent agents.entries.*.model, OpenClaw resolves each changed primary or fallback through the configured catalogs and the selected provider's model resolver before writing. Provider-supported exact provider/model pins are accepted even when absent from the curated picker; validation does not replace the selected model. Unknown model references are rejected without changing the active config. Run openclaw models list to browse the picker, or check the provider's documentation for an exact model ID. Successful validation does not prove that your account can call the model. openclaw models set is deliberately more permissive for the same setting: it saves a model the local catalog cannot confirm and prints a warning instead of rejecting the write.

Use --merge when adding entries to those maps:

bash

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw 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.

Conditional writes

Use a conditional expectation when automation must update one authored path only if it has not changed since the caller last observed it:

bash

openclaw config set gateway.port 19001 --strict-json --expect-current-json 18789openclaw config set gateway.port 19001 --strict-json --expect-current-absent

--expect-current-json <json> uses strict JSON and compares the value by JSON type and structure. null is an authored value, so it does not satisfy --expect-current-absent. The comparison uses the effective authored config after includes and environment substitution, before runtime defaults are applied.

The two expectation flags are mutually exclusive. They apply only to a single config set operation, require a direct non-redirected config path, and cannot be combined with batch mode or --dry-run. If input or roster resolution would write a different path than the caller requested, such as a sibling *Ref path, the command exits with status 1 instead of retargeting the expectation. A mismatch exits with status 1, writes nothing, and does not print either the expected or current value. OpenClaw's config snapshot guard still rejects a later race between the expectation check and the final file replacement.

`config set` modes

Value mode

bash

openclaw config set <path> <value>

SecretRef builder mode

bash

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

Provider builder mode

Targets secrets.providers.<alias> paths only:

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

Batch mode

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

bash

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

Batch files are limited to 8 MiB.

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.

Batch assignments apply in order, then validation checks the final config. A SecretRef replaced by a later assignment is not resolved or counted in dry-run output, even with --allow-exec. Providers that remain in a changed provider collection still receive command-path trust checks.

JSON path/value mode also works for SecretRefs and providers directly:

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

Common flags

--provider-source <env|file|exec|store>
--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>

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)

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

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

bash

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

Patch files are limited to 8 MiB. Piped --stdin patches are limited to 1 MiB.

Pipe a patch over stdin for remote setup scripts:

bash

ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-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.6-sol" },      models: {        "openai/gpt-5.6-sol": {          agentRuntime: { id: "openclaw" },          params: { fastMode: true },        },      },    },  },}

The runtime pin makes this an embedded OpenClaw recipe. A valid fastMode value is a portable typed runtime control and does not choose OpenClaw by itself.

Use --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'

--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 simulates a change without writing openclaw.json. Available on config set, config patch, and config unset. Which checks run depends on the input mode. Value mode (config set <path> <value> without --strict-json) skips the full schema pass and the ordinary SecretRef resolvability scan. Policy, provider, and model-reference checks can still run. When no checks apply, value mode reports Dry run successful even for a value the real write rejects. Use --strict-json (or config patch --file --dry-run) when you need schema validation.

bash

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

Value mode (a plain <value> without --strict-json): skips the full schema pass and ordinary SecretRef resolvability scan. Policy, provider, and model-reference checks can still run. When no checks apply, the CLI prints Dry run note: value mode does not run schema/resolvability checks and can succeed even when the real write would fail schema validation.
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 command-path trust checks run without executing providers. Exec SecretRef resolvability 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 failures when ok=false; each carries a kind of missing-path, schema, resolvability, model, or conflict (conflict means the config file changed while the command was writing, so nothing was changed — re-run to pick up the new file)

JSON output shape

json5

{  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" | "model" | "conflict",      message: string,      ref?: string, // present for resolvability errors    },  ],}

Success example

json

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

Failure example

json

{  "ok": false,  "operations": 1,  "configPath": "/home/user/.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/store name, invalid file pointer, exec provider failure, or provider/source mismatch).
model reference validation failed: a changed text-model primary or fallback is unknown; run openclaw models list and choose an available model.
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.

Effective changes to plugins.entries (or any subpath) require a restart, since the CLI cannot prove every plugin's reload metadata is loaded. Successful config set or config unset operations that produce no effective config diff print No change and leave the JSON5 file byte-for-byte untouched. A config unset target that is absent from the authored config exits with status 1 and also leaves the file untouched. Setting an absent key to a value equal to its runtime default is still an authored change and persists the explicit value.

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

OpenClaw-owned writes that change config reserialize JSON5 as standard JSON. When the source contains comments, the writer warns immediately before removing them; use a direct editor when preserving comments matters.

Prefer CLI writes for small edits:

bash

openclaw config set gateway.reload.mode '"hybrid"' --strict-json --dry-runopenclaw config set gateway.reload.mode '"hybrid"' --strict-jsonopenclaw 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 | headopenclaw config validate

Direct editor writes are still allowed, but the running Gateway treats them as untrusted until they validate. At startup, eligible single-file configs can receive deterministic legacy-key migrations if the complete result validates, with the previous config kept in the .bak ring. Other invalid direct edits fail startup; hot reload skips invalid edits without rewriting 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:

bash

openclaw chat

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

text

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

CLI reference
Configuration
openclaw configure — guided editor for the same settings

Was this useful?

Config

Externally managed config

Root options

Examples

Paths

`config get`

`config file`

`config schema`

`config validate`

Values

Conditional writes

`config set` modes

Value mode

SecretRef builder mode

Provider builder mode

Batch mode

Provider builder flags

`config patch`

Dry run

JSON output shape

Success example

Failure example

Applying changes

Write safety

Repair loop

Compare with docs

Apply targeted edits

Re-validate

Doctor for runtime issues

On this page

Molty

Externally managed config

Root options

Examples

Paths

config get

config file

config schema

config validate

Values

Conditional writes

config set modes

Value mode

SecretRef builder mode

Provider builder mode

Batch mode

Provider builder flags

config patch

Dry run

JSON output shape

Success example

Failure example

Applying changes

Write safety

Repair loop

Compare with docs

Apply targeted edits

Re-validate

Doctor for runtime issues

Related

On this page

`config get`

`config file`

`config schema`

`config validate`

`config set` modes

`config patch`