> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  When `OPENCLAW_NIX_MODE=1`, OpenClaw treats `openclaw.json` as immutable. Read-only commands (`config get`, `config file`, `config schema`, `config validate`) still work; config writers refuse. Edit the Nix source for the install instead; for the first-party nix-openclaw distribution, use the [nix-openclaw Quick Start](https://github.com/openclaw/nix-openclaw#quick-start) and set values under `programs.openclaw.config` or `instances.<name>.config`.
</Note>

## Root options

<ParamField path="--section <section>" type="string">
  Repeatable guided-setup section filter when you run `openclaw config` without a subcommand.
</ParamField>

Guided sections: `workspace`, `model`, `web`, `gateway`, `daemon`, `channels`, `plugins`, `skills`, `health`.

## Examples

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

### Paths

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 get`

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config get browser.executablePath
openclaw 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](#write-safety).

### `config schema`

Prints the generated JSON schema for `openclaw.json` to stdout.

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config schema
openclaw config schema > openclaw.schema.json
```

### `config validate`

Validates the current config against the active schema without starting the gateway.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config validate
openclaw config validate --json
```

<Note>
  If validation is already failing, start with `openclaw configure` or `openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config guard.
</Note>

## 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.

<Note>
  Object assignment replaces the target path by default. Protected paths that commonly hold user-added entries refuse replacements that would remove existing entries unless you pass `--replace`: `agents.defaults.models`, `agents.list`, `models.providers`, `models.providers.<id>`, `models.providers.<id>.models`, `plugins.entries`, and `auth.profiles`.
</Note>

Use `--merge` when adding entries to those maps:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

<Tabs>
  <Tab title="Value mode">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw config set <path> <value>
    ```
  </Tab>

  <Tab title="SecretRef builder mode">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw config set channels.discord.token \
      --ref-provider default \
      --ref-source env \
      --ref-id DISCORD_BOT_TOKEN
    ```
  </Tab>

  <Tab title="Provider builder mode">
    Targets `secrets.providers.<alias>` paths only:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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
    ```
  </Tab>

  <Tab title="Batch mode">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw config set --batch-file ./config-set.batch.json --dry-run
    ```
  </Tab>
</Tabs>

<Warning>
  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).
</Warning>

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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.

<AccordionGroup>
  <Accordion title="Common flags">
    * `--provider-source <env|file|exec>`
    * `--provider-timeout-ms <ms>` (`file`, `exec`)
  </Accordion>

  <Accordion title="Env provider (--provider-source env)">
    * `--provider-allowlist <ENV_VAR>` (repeatable)
  </Accordion>

  <Accordion title="File provider (--provider-source file)">
    * `--provider-path <path>` (required)
    * `--provider-mode <singleValue|json>`
    * `--provider-max-bytes <bytes>`
    * `--provider-allow-insecure-path`
  </Accordion>

  <Accordion title="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)
    * `--provider-allow-insecure-path`
    * `--provider-allow-symlink-command`
  </Accordion>
</AccordionGroup>

Hardened exec provider example:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` validates changes without writing `openclaw.json`. Available on `config set`, `config patch`, and `config unset`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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
```

<AccordionGroup>
  <Accordion title="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 runs against 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 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`.
  </Accordion>

  <Accordion title="--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 missing-path, schema, or resolvability failures when `ok=false`
  </Accordion>
</AccordionGroup>

### JSON output shape

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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
    },
  ],
}
```

<Tabs>
  <Tab title="Success example">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "ok": true,
      "operations": 1,
      "configPath": "~/.openclaw/openclaw.json",
      "inputModes": ["builder"],
      "checks": {
        "schema": false,
        "resolvability": true,
        "resolvabilityComplete": true
      },
      "refsChecked": 1,
      "skippedExecRefs": 0
    }
    ```
  </Tab>

  <Tab title="Failure example">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="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 var, invalid file pointer, exec provider failure, or provider/source mismatch).
    * `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.
  </Accordion>
</AccordionGroup>

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

Writes to `plugins.entries` (or any subpath) always require a restart, since the CLI cannot prove every plugin's reload metadata is loaded.

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

<Warning>
  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.
</Warning>

Prefer CLI writes for small edits:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/gateway/troubleshooting#gateway-rejected-invalid-config).

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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw chat
```

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

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
```

<Steps>
  <Step title="Compare with docs">
    Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
  </Step>

  <Step title="Apply targeted edits">
    Apply targeted edits with `openclaw config set` or `openclaw configure`.
  </Step>

  <Step title="Re-validate">
    Rerun `openclaw config validate` after each change.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Related

* [CLI reference](/cli)
* [Configuration](/gateway/configuration)