docs/cli/config.md
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.
Guided sections: workspace, model, web, gateway, daemon, channels, plugins, skills, health.
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
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 getReads 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 filePrints 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 schemaPrints the generated JSON schema for openclaw.json to stdout.
openclaw config schema
openclaw config schema > openclaw.schema.json
config validateValidates the current config against the active schema without starting the gateway.
openclaw config validate
openclaw config validate --json
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.
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```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
```
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 targets must use secrets.providers.<alias> as the path.
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 patchPaste 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 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
{
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
},
],
}
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.
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.*.
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.
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