diff --git a/docs/cli/config.md b/docs/cli/config.md
index 705975f1972..3a3620998c3 100644
--- a/docs/cli/config.md
+++ b/docs/cli/config.md
@@ -3,29 +3,18 @@ summary: "CLI reference for `openclaw config` (get/set/unset/file/schema/validat
read_when:
- You want to read or edit config non-interactively
title: "Config"
+sidebarTitle: "Config"
---
-# `openclaw config`
+Config helpers for non-interactive edits in `openclaw.json`: get/set/unset/file/schema/validate values by path and print the active config file. Run without a subcommand to open the configure wizard (same as `openclaw configure`).
-Config helpers for non-interactive edits in `openclaw.json`: get/set/unset/file/schema/validate
-values by path and print the active config file. Run without a subcommand to
-open the configure wizard (same as `openclaw configure`).
+## Root options
-Root options:
+
+ Repeatable guided-setup section filter when you run `openclaw config` without a subcommand.
+
-- `--section `: repeatable guided-setup section filter when you run `openclaw config` without a subcommand
-
-Supported guided sections:
-
-- `workspace`
-- `model`
-- `web`
-- `gateway`
-- `daemon`
-- `channels`
-- `plugins`
-- `skills`
-- `health`
+Supported guided sections: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`.
## Examples
@@ -52,21 +41,19 @@ openclaw config validate --json
Print the generated JSON schema for `openclaw.json` to stdout as JSON.
-What it includes:
-
-- The current root config schema, plus a root `$schema` string field for editor tooling
-- Field `title` and `description` docs metadata used by the Control UI
-- Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists
-- `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists
-- Best-effort live plugin + channel schema metadata when runtime manifests can be loaded
-- A clean fallback schema even when the current config is invalid
-
-Related runtime RPC:
-
-- `config.schema.lookup` returns one normalized config path with a shallow
- schema node (`title`, `description`, `type`, `enum`, `const`, common bounds),
- matched UI hint metadata, and immediate child summaries. Use it for
- path-scoped drill-down in Control UI or custom clients.
+
+
+ - The current root config schema, plus a root `$schema` string field for editor tooling.
+ - Field `title` and `description` docs metadata used by the Control UI.
+ - Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists.
+ - `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists.
+ - Best-effort live plugin + channel schema metadata when runtime manifests can be loaded.
+ - A clean fallback schema even when the current config is invalid.
+
+
+ `config.schema.lookup` returns one normalized config path with a shallow schema node (`title`, `description`, `type`, `enum`, `const`, common bounds), matched UI hint metadata, and immediate child summaries. Use it for path-scoped drill-down in Control UI or custom clients.
+
+
```bash
openclaw config schema
@@ -96,8 +83,7 @@ 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 `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
+Values are parsed as JSON5 when possible; otherwise they are treated as strings. Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
@@ -107,11 +93,9 @@ openclaw config set channels.whatsapp.groups '["*"]' --strict-json
`config get --json` prints the raw value as JSON instead of terminal-formatted text.
-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`.
+
+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 `--merge` when adding entries to those maps:
@@ -120,59 +104,65 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
```
-Use `--replace` only when you intentionally want the provided value to become
-the complete target value.
+Use `--replace` only when you intentionally want the provided value to become the complete target value.
## `config set` modes
`openclaw config set` supports four assignment styles:
-1. Value mode: `openclaw config set `
-2. SecretRef builder mode:
+
+
+ ```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:
-```bash
-openclaw config set channels.discord.token \
- --ref-provider default \
- --ref-source env \
- --ref-id DISCORD_BOT_TOKEN
-```
+ ```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
+ ```
-3. Provider builder mode (`secrets.providers.` path only):
+
+
+ ```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 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-file ./config-set.batch.json --dry-run
+ ```
-4. Batch mode (`--batch-json` or `--batch-file`):
+
+
-```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" }
- }
-]'
-```
+
+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).
+
-```bash
-openclaw config set --batch-file ./config-set.batch.json --dry-run
-```
-
-Policy note:
-
-- 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 (`--batch-json`/`--batch-file`) as the source of truth.
-`--strict-json` / `--json` do not change batch parsing behavior.
+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 remains supported for both SecretRefs and providers:
@@ -190,34 +180,33 @@ openclaw config set secrets.providers.vaultfile \
Provider builder targets must use `secrets.providers.` as the path.
-Common flags:
-
-- `--provider-source `
-- `--provider-timeout-ms ` (`file`, `exec`)
-
-Env provider (`--provider-source env`):
-
-- `--provider-allowlist ` (repeatable)
-
-File provider (`--provider-source file`):
-
-- `--provider-path ` (required)
-- `--provider-mode `
-- `--provider-max-bytes `
-- `--provider-allow-insecure-path`
-
-Exec provider (`--provider-source exec`):
-
-- `--provider-command ` (required)
-- `--provider-arg ` (repeatable)
-- `--provider-no-output-timeout-ms `
-- `--provider-max-output-bytes `
-- `--provider-json-only`
-- `--provider-env ` (repeatable)
-- `--provider-pass-env ` (repeatable)
-- `--provider-trusted-dir ` (repeatable)
-- `--provider-allow-insecure-path`
-- `--provider-allow-symlink-command`
+
+
+ - `--provider-source `
+ - `--provider-timeout-ms ` (`file`, `exec`)
+
+
+ - `--provider-allowlist ` (repeatable)
+
+
+ - `--provider-path ` (required)
+ - `--provider-mode `
+ - `--provider-max-bytes `
+ - `--provider-allow-insecure-path`
+
+
+ - `--provider-command ` (required)
+ - `--provider-arg ` (repeatable)
+ - `--provider-no-output-timeout-ms `
+ - `--provider-max-output-bytes `
+ - `--provider-json-only`
+ - `--provider-env ` (repeatable)
+ - `--provider-pass-env ` (repeatable)
+ - `--provider-trusted-dir ` (repeatable)
+ - `--provider-allow-insecure-path`
+ - `--provider-allow-symlink-command`
+
+
Hardened exec provider example:
@@ -259,25 +248,29 @@ openclaw config set channels.discord.token \
--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 also runs for known unsupported SecretRef target surfaces.
+ - Policy checks evaluate 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 during dry-run to avoid command side effects.
+ - Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
+ - `--allow-exec` is dry-run only and errors if used without `--dry-run`.
+
+
+ `--dry-run --json` prints a machine-readable report:
-- 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 also runs for known unsupported SecretRef target surfaces.
-- Policy checks evaluate 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 during dry-run to avoid command side effects.
-- Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
-- `--allow-exec` is dry-run only and errors if used without `--dry-run`.
+ - `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 schema/resolvability failures when `ok=false`
-`--dry-run --json` prints a machine-readable report:
-
-- `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 schema/resolvability failures when `ok=false`
+
+
### JSON output shape
@@ -304,66 +297,67 @@ Dry-run behavior:
}
```
-Success example:
-
-```json
-{
- "ok": true,
- "operations": 1,
- "configPath": "~/.openclaw/openclaw.json",
- "inputModes": ["builder"],
- "checks": {
- "schema": false,
- "resolvability": true,
- "resolvabilityComplete": true
- },
- "refsChecked": 1,
- "skippedExecRefs": 0
-}
-```
-
-Failure example:
-
-```json
-{
- "ok": false,
- "operations": 1,
- "configPath": "~/.openclaw/openclaw.json",
- "inputModes": ["builder"],
- "checks": {
- "schema": false,
- "resolvability": true,
- "resolvabilityComplete": true
- },
- "refsChecked": 1,
- "skippedExecRefs": 0,
- "errors": [
+
+
+ ```json
{
- "kind": "resolvability",
- "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
- "ref": "env:default:MISSING_TEST_SECRET"
+ "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"
+ }
+ ]
+ }
+ ```
+
+
-If dry-run fails:
-
-- `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
-- `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
-- `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
-- `Dry run note: skipped exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
-- For batch mode, fix failing entries and rerun `--dry-run` before writing.
+
+
+ - `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
+ - `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
+ - `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
+ - `Dry run note: skipped exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
+ - For batch mode, fix failing entries and rerun `--dry-run` before writing.
+
+
## 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.
+`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:
@@ -381,19 +375,9 @@ 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](/gateway/troubleshooting#gateway-restored-last-known-good-config).
+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](/gateway/troubleshooting#gateway-restored-last-known-good-config).
-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 `plugins.entries....`,
-OpenClaw keeps the active `openclaw.json` in place and reports the plugin-local
-issue instead of restoring `.last-good`. This prevents plugin schema changes or
-`minHostVersion` skew from rolling back unrelated user settings such as models,
-providers, auth profiles, channels, gateway exposure, tools, memory, browser, or
-cron config.
+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 `plugins.entries....`, OpenClaw keeps the active `openclaw.json` in place and reports the plugin-local issue instead of restoring `.last-good`. This prevents plugin schema changes or `minHostVersion` skew from rolling back unrelated user settings such as models, providers, auth profiles, channels, gateway exposure, tools, memory, browser, or cron config.
## Subcommands
@@ -403,21 +387,18 @@ Restart the gateway after edits.
## Validate
-Validate the current config against the active schema without starting the
-gateway.
+Validate the current config against the active schema without starting the gateway.
```bash
openclaw config validate
openclaw config validate --json
```
-After `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:
+After `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:
-If validation is already failing, start with `openclaw configure` or
-`openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config
-guard.
+
+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
@@ -434,10 +415,20 @@ Then inside the TUI:
Typical repair loop:
-- Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
-- Apply targeted edits with `openclaw config set` or `openclaw configure`.
-- Rerun `openclaw config validate` after each change.
-- If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.
+
+
+ Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
+
+
+ Apply targeted edits with `openclaw config set` or `openclaw configure`.
+
+
+ Rerun `openclaw config validate` after each change.
+
+
+ If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.
+
+
## Related