Managing OpenClaw Configuration via CLI

Managing configuration files manually is often a recipe for syntax errors and broken deployments. We have all been there—one missing comma in a JSON file and the whole system refuses to start.

The OpenClaw config command provides a suite of helpers for non-interactive edits in your openclaw.json file. Whether you need to get, set, or validate values by path, this CLI tool ensures your OpenClaw configuration remains consistent and error-free.

Root options:

1. --section <section>: repeatable guided-setup section filter when you run openclaw config without a subcommand

Supported guided sections:

1. workspace
2. model
3. web
4. gateway
5. daemon
6. channels
7. plugins
8. skills
9. health

Use OpenClaw config for quick edits

You can perform a wide range of tasks from printing the schema to setting complex nested values. Here are the most common ways to use the command.

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 agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
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:

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

Related runtime RPC:

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

openclaw config schema

Pipe it into a file when you want to inspect or validate it with other tools:

openclaw config schema > openclaw.schema.json

Paths

Paths use dot or bracket notation:

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Use the agent list index to target a specific agent:

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

Handle JSON and string values

The tool intelligently parses your inputs to ensure they match the expected format. It uses JSON5 parsing by default to give you more flexibility with your configuration data.

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.

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.

Choose your config set assignment style

There are four distinct ways to assign values depending on whether you are dealing with simple strings or complex secret providers. This flexibility allows you to automate setup across different environments easily.

1. Value mode: openclaw config set <path> <value>
2. SecretRef builder mode:

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

3. Provider builder mode (secrets.providers.<alias> path 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

4. Batch mode (--batch-json or --batch-file):

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

Policy note:

1. 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 remains supported for both SecretRefs and providers:

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

Configure secret providers with flags

When you need to set up a secret provider, specific flags help you define the source and behavior. These targets must always use the secrets.providers.<alias> path to function correctly.

Common flags:

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

Env provider (--provider-source env):

1. --provider-allowlist <ENV_VAR> (repeatable)

File provider (--provider-source file):

1. --provider-path <path> (required)
2. --provider-mode <singleValue|json>
3. --provider-max-bytes <bytes>

Exec provider (--provider-source exec):

1. --provider-command <path> (required)
2. --provider-arg <arg> (repeatable)
3. --provider-no-output-timeout-ms <ms>
4. --provider-max-output-bytes <bytes>
5. --provider-json-only
6. --provider-env <KEY=VALUE> (repeatable)
7. --provider-pass-env <ENV_VAR> (repeatable)
8. --provider-trusted-dir <path> (repeatable)
9. --provider-allow-insecure-path
10. --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

Test changes with Dry run

Before committing any changes to your production openclaw.json, you should verify them using the --dry-run flag. This process checks for schema validity and ensures your secret references are actually resolvable.

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:

1. Builder mode: runs SecretRef resolvability checks for changed refs/providers.
2. JSON mode (--strict-json, --json, or batch mode): runs schema validation plus SecretRef resolvability checks.
3. Policy validation also runs for known unsupported SecretRef target surfaces.
4. Policy checks evaluate the full post-change config, so parent-object writes (for example setting hooks as an object) cannot bypass unsupported-surface validation.
5. Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
6. Use --allow-exec with --dry-run to opt in to exec SecretRef checks (this may execute provider commands).
7. --allow-exec is dry-run only and errors if used without --dry-run.

--dry-run --json prints a machine-readable report:

1. ok: whether dry-run passed
2. operations: number of assignments evaluated
3. checks: whether schema/resolvability checks ran
4. checks.resolvabilityComplete: whether resolvability checks ran to completion (false when exec refs are skipped)
5. refsChecked: number of refs actually resolved during dry-run
6. skippedExecRefs: number of exec refs skipped because --allow-exec was not set
7. errors: structured schema/resolvability failures when ok=false

JSON Output Shape

{
  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:

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

Failure example:

{
  "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:

1. config schema validation failed: your post-change config shape is invalid; fix path/value or provider/ref object shape.
2. Config policy validation failed: unsupported SecretRef usage: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
3. 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).
4. Dry run note: skipped <n> exec SecretRef resolvability check(s): dry-run skipped exec refs; rerun with --allow-exec if you need exec resolvability validation.
5. For batch mode, fix failing entries and rerun --dry-run before writing.

Ensure Write safety for your configuration

OpenClaw protects your setup by validating the entire configuration before writing it to the disk. If a change is deemed unsafe or invalid, the tool preserves your original file and saves the rejected version separately.

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 can be restored from the last-known-good backup during startup or hot reload. See Gateway troubleshooting.

Explore OpenClaw config subcommands

Beyond setting values, there are utility subcommands to help you locate your active configuration. Remember to restart your Gateway after making any manual or CLI edits to apply the changes.

1. config file: Print the active config file path (resolved from OPENCLAW_CONFIG_PATH or default location).

Restart the Gateway after edits.

Run OpenClaw config validate

It is a good habit to check your current configuration against the active schema. This command lets you catch errors early without needing to start the full Gateway service.

openclaw config validate
openclaw config validate --json

Need more help? Chat with our AI Setup Assistant.

Next Steps

1. SecretRef Credential Surface
2. Gateway troubleshooting