--- summary: "CLI reference for `openclaw config` (get/set/unset/file/schema/validate)" read_when: - You want to read or edit config non-interactively title: "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`). Root options: - `--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` ## 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 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 ``` ### `config schema` 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. ```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 `--strict-json` to require JSON5 parsing. `--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 ``` `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`. Use `--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 `--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 channels.discord.token \ --ref-provider default \ --ref-source env \ --ref-id DISCORD_BOT_TOKEN ``` 3. Provider builder mode (`secrets.providers.` path 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 ``` 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" } } ]' ``` ```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. 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 `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` 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 `--dry-run` to validate changes without writing `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 ``` 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: - `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 ```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 }, ], } ``` 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": [ { "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. ## 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: ```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](/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. ## Subcommands - `config file`: Print the active config file path (resolved from `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 `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. ```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: - 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 - [CLI reference](/cli) - [Configuration](/gateway/configuration)