mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 16:50:43 +00:00
docs(cli-config): rewrite with Tabs for set modes, AccordionGroup for builder flags and dry-run details, Steps for the repair loop
This commit is contained in:
Vincent Koc
@@ -3,29 +3,18 @@ summary: "CLI reference for `openclaw config` (get/set/unset/file/schema/validat
|
|||||||
read_when:
|
read_when:
|
||||||
- You want to read or edit config non-interactively
|
- You want to read or edit config non-interactively
|
||||||
title: "Config"
|
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
|
## Root options
|
||||||
values by path and print the active config file. Run without a subcommand to
|
|
||||||
open the configure wizard (same as `openclaw configure`).
|
|
||||||
|
|
||||||
Root options:
|
<ParamField path="--section <section>" type="string">
|
||||||
|
Repeatable guided-setup section filter when you run `openclaw config` without a subcommand.
|
||||||
|
</ParamField>
|
||||||
|
|
||||||
- `--section <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
|
## Examples
|
||||||
|
|
||||||
@@ -52,21 +41,19 @@ openclaw config validate --json
|
|||||||
|
|
||||||
Print the generated JSON schema for `openclaw.json` to stdout as JSON.
|
Print the generated JSON schema for `openclaw.json` to stdout as JSON.
|
||||||
|
|
||||||
What it includes:
|
<AccordionGroup>
|
||||||
|
<Accordion title="What it includes">
|
||||||
- The current root config schema, plus a root `$schema` string field for editor tooling
|
- 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
|
- 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
|
- 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
|
- `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
|
- Best-effort live plugin + channel schema metadata when runtime manifests can be loaded.
|
||||||
- A clean fallback schema even when the current config is invalid
|
- A clean fallback schema even when the current config is invalid.
|
||||||
|
</Accordion>
|
||||||
Related runtime RPC:
|
<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.
|
||||||
- `config.schema.lookup` returns one normalized config path with a shallow
|
</Accordion>
|
||||||
schema node (`title`, `description`, `type`, `enum`, `const`, common bounds),
|
</AccordionGroup>
|
||||||
matched UI hint metadata, and immediate child summaries. Use it for
|
|
||||||
path-scoped drill-down in Control UI or custom clients.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw config schema
|
openclaw config schema
|
||||||
@@ -96,8 +83,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
|
|||||||
|
|
||||||
## Values
|
## Values
|
||||||
|
|
||||||
Values are parsed as JSON5 when possible; otherwise they are treated as strings.
|
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.
|
||||||
Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw config set agents.defaults.heartbeat.every "0m"
|
openclaw config set agents.defaults.heartbeat.every "0m"
|
||||||
@@ -107,11 +93,9 @@ openclaw config set channels.whatsapp.groups '["*"]' --strict-json
|
|||||||
|
|
||||||
`config get <path> --json` prints the raw value as JSON instead of terminal-formatted text.
|
`config get <path> --json` prints the raw value as JSON instead of terminal-formatted text.
|
||||||
|
|
||||||
Object assignment replaces the target path by default. Protected map/list paths
|
<Note>
|
||||||
that commonly hold user-added entries, such as `agents.defaults.models`,
|
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.<id>.models`, `plugins.entries`, and `auth.profiles`, refuse replacements that would remove existing entries unless you pass `--replace`.
|
||||||
`models.providers`, `models.providers.<id>.models`, `plugins.entries`, and
|
</Note>
|
||||||
`auth.profiles`, refuse replacements that would remove existing entries unless
|
|
||||||
you pass `--replace`.
|
|
||||||
|
|
||||||
Use `--merge` when adding entries to those maps:
|
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
|
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
|
Use `--replace` only when you intentionally want the provided value to become the complete target value.
|
||||||
the complete target value.
|
|
||||||
|
|
||||||
## `config set` modes
|
## `config set` modes
|
||||||
|
|
||||||
`openclaw config set` supports four assignment styles:
|
`openclaw config set` supports four assignment styles:
|
||||||
|
|
||||||
1. Value mode: `openclaw config set <path> <value>`
|
<Tabs>
|
||||||
2. SecretRef builder mode:
|
<Tab title="Value mode">
|
||||||
|
```bash
|
||||||
|
openclaw config set <path> <value>
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
<Tab title="SecretRef builder mode">
|
||||||
|
```bash
|
||||||
|
openclaw config set channels.discord.token \
|
||||||
|
--ref-provider default \
|
||||||
|
--ref-source env \
|
||||||
|
--ref-id DISCORD_BOT_TOKEN
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
<Tab title="Provider builder mode">
|
||||||
|
Provider builder mode targets `secrets.providers.<alias>` paths only:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw config set channels.discord.token \
|
openclaw config set secrets.providers.vault \
|
||||||
--ref-provider default \
|
--provider-source exec \
|
||||||
--ref-source env \
|
--provider-command /usr/local/bin/openclaw-vault \
|
||||||
--ref-id DISCORD_BOT_TOKEN
|
--provider-arg read \
|
||||||
```
|
--provider-arg openai/api-key \
|
||||||
|
--provider-timeout-ms 5000
|
||||||
|
```
|
||||||
|
|
||||||
3. Provider builder mode (`secrets.providers.<alias>` path only):
|
</Tab>
|
||||||
|
<Tab title="Batch mode">
|
||||||
|
```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
|
```bash
|
||||||
openclaw config set secrets.providers.vault \
|
openclaw config set --batch-file ./config-set.batch.json --dry-run
|
||||||
--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`):
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
```bash
|
<Warning>
|
||||||
openclaw config set --batch-json '[
|
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>
|
||||||
"path": "secrets.providers.default",
|
|
||||||
"provider": { "source": "env" }
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"path": "channels.discord.token",
|
|
||||||
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
|
|
||||||
}
|
|
||||||
]'
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
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.
|
||||||
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:
|
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.<alias>` as the path.
|
Provider builder targets must use `secrets.providers.<alias>` as the path.
|
||||||
|
|
||||||
Common flags:
|
<AccordionGroup>
|
||||||
|
<Accordion title="Common flags">
|
||||||
- `--provider-source <env|file|exec>`
|
- `--provider-source <env|file|exec>`
|
||||||
- `--provider-timeout-ms <ms>` (`file`, `exec`)
|
- `--provider-timeout-ms <ms>` (`file`, `exec`)
|
||||||
|
</Accordion>
|
||||||
Env provider (`--provider-source env`):
|
<Accordion title="Env provider (--provider-source env)">
|
||||||
|
- `--provider-allowlist <ENV_VAR>` (repeatable)
|
||||||
- `--provider-allowlist <ENV_VAR>` (repeatable)
|
</Accordion>
|
||||||
|
<Accordion title="File provider (--provider-source file)">
|
||||||
File provider (`--provider-source file`):
|
- `--provider-path <path>` (required)
|
||||||
|
- `--provider-mode <singleValue|json>`
|
||||||
- `--provider-path <path>` (required)
|
- `--provider-max-bytes <bytes>`
|
||||||
- `--provider-mode <singleValue|json>`
|
- `--provider-allow-insecure-path`
|
||||||
- `--provider-max-bytes <bytes>`
|
</Accordion>
|
||||||
- `--provider-allow-insecure-path`
|
<Accordion title="Exec provider (--provider-source exec)">
|
||||||
|
- `--provider-command <path>` (required)
|
||||||
Exec provider (`--provider-source exec`):
|
- `--provider-arg <arg>` (repeatable)
|
||||||
|
- `--provider-no-output-timeout-ms <ms>`
|
||||||
- `--provider-command <path>` (required)
|
- `--provider-max-output-bytes <bytes>`
|
||||||
- `--provider-arg <arg>` (repeatable)
|
- `--provider-json-only`
|
||||||
- `--provider-no-output-timeout-ms <ms>`
|
- `--provider-env <KEY=VALUE>` (repeatable)
|
||||||
- `--provider-max-output-bytes <bytes>`
|
- `--provider-pass-env <ENV_VAR>` (repeatable)
|
||||||
- `--provider-json-only`
|
- `--provider-trusted-dir <path>` (repeatable)
|
||||||
- `--provider-env <KEY=VALUE>` (repeatable)
|
- `--provider-allow-insecure-path`
|
||||||
- `--provider-pass-env <ENV_VAR>` (repeatable)
|
- `--provider-allow-symlink-command`
|
||||||
- `--provider-trusted-dir <path>` (repeatable)
|
</Accordion>
|
||||||
- `--provider-allow-insecure-path`
|
</AccordionGroup>
|
||||||
- `--provider-allow-symlink-command`
|
|
||||||
|
|
||||||
Hardened exec provider example:
|
Hardened exec provider example:
|
||||||
|
|
||||||
@@ -259,25 +248,29 @@ openclaw config set channels.discord.token \
|
|||||||
--allow-exec
|
--allow-exec
|
||||||
```
|
```
|
||||||
|
|
||||||
Dry-run behavior:
|
<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 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`.
|
||||||
|
</Accordion>
|
||||||
|
<Accordion title="--dry-run --json fields">
|
||||||
|
`--dry-run --json` prints a machine-readable report:
|
||||||
|
|
||||||
- Builder mode: runs SecretRef resolvability checks for changed refs/providers.
|
- `ok`: whether dry-run passed
|
||||||
- JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks.
|
- `operations`: number of assignments evaluated
|
||||||
- Policy validation also runs for known unsupported SecretRef target surfaces.
|
- `checks`: whether schema/resolvability checks ran
|
||||||
- Policy checks evaluate the full post-change config, so parent-object writes (for example setting `hooks` as an object) cannot bypass unsupported-surface validation.
|
- `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
|
||||||
- Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
|
- `refsChecked`: number of refs actually resolved during dry-run
|
||||||
- Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
|
- `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
|
||||||
- `--allow-exec` is dry-run only and errors if used without `--dry-run`.
|
- `errors`: structured schema/resolvability failures when `ok=false`
|
||||||
|
|
||||||
`--dry-run --json` prints a machine-readable report:
|
</Accordion>
|
||||||
|
</AccordionGroup>
|
||||||
- `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
|
### JSON output shape
|
||||||
|
|
||||||
@@ -304,66 +297,67 @@ Dry-run behavior:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Success example:
|
<Tabs>
|
||||||
|
<Tab title="Success example">
|
||||||
```json
|
```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",
|
"ok": true,
|
||||||
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
|
"operations": 1,
|
||||||
"ref": "env:default:MISSING_TEST_SECRET"
|
"configPath": "~/.openclaw/openclaw.json",
|
||||||
|
"inputModes": ["builder"],
|
||||||
|
"checks": {
|
||||||
|
"schema": false,
|
||||||
|
"resolvability": true,
|
||||||
|
"resolvabilityComplete": true
|
||||||
|
},
|
||||||
|
"refsChecked": 1,
|
||||||
|
"skippedExecRefs": 0
|
||||||
}
|
}
|
||||||
]
|
```
|
||||||
}
|
</Tab>
|
||||||
```
|
<Tab title="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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
</Tab>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
If dry-run fails:
|
<AccordionGroup>
|
||||||
|
<Accordion title="If dry-run fails">
|
||||||
- `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
|
- `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.
|
- `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).
|
- `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 <n> exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
|
- `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.
|
||||||
- For batch mode, fix failing entries and rerun `--dry-run` before writing.
|
- For batch mode, fix failing entries and rerun `--dry-run` before writing.
|
||||||
|
</Accordion>
|
||||||
|
</AccordionGroup>
|
||||||
|
|
||||||
## Write safety
|
## Write safety
|
||||||
|
|
||||||
`openclaw config set` and other OpenClaw-owned config writers validate the full
|
`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.*`.
|
||||||
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
|
<Warning>
|
||||||
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.
|
||||||
The active config path must be a regular file. Symlinked `openclaw.json`
|
</Warning>
|
||||||
layouts are unsupported for writes; use `OPENCLAW_CONFIG_PATH` to point directly
|
|
||||||
at the real file instead.
|
|
||||||
|
|
||||||
Prefer CLI writes for small edits:
|
Prefer CLI writes for small edits:
|
||||||
|
|
||||||
@@ -381,19 +375,9 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
|
|||||||
openclaw config validate
|
openclaw config validate
|
||||||
```
|
```
|
||||||
|
|
||||||
Direct editor writes are still allowed, but the running Gateway treats them as
|
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).
|
||||||
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
|
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.<id>...`, 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.
|
||||||
errors, root-level schema failures, legacy migration failures, or mixed plugin
|
|
||||||
and root failures. If validation fails only under `plugins.entries.<id>...`,
|
|
||||||
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
|
## Subcommands
|
||||||
|
|
||||||
@@ -403,21 +387,18 @@ Restart the gateway after edits.
|
|||||||
|
|
||||||
## Validate
|
## Validate
|
||||||
|
|
||||||
Validate the current config against the active schema without starting the
|
Validate the current config against the active schema without starting the gateway.
|
||||||
gateway.
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw config validate
|
openclaw config validate
|
||||||
openclaw config validate --json
|
openclaw config validate --json
|
||||||
```
|
```
|
||||||
|
|
||||||
After `openclaw config validate` is passing, you can use the local TUI to have
|
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:
|
||||||
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
|
<Note>
|
||||||
`openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config
|
If validation is already failing, start with `openclaw configure` or `openclaw doctor --fix`. `openclaw chat` does not bypass the invalid-config guard.
|
||||||
guard.
|
</Note>
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw chat
|
openclaw chat
|
||||||
@@ -434,10 +415,20 @@ Then inside the TUI:
|
|||||||
|
|
||||||
Typical repair loop:
|
Typical repair loop:
|
||||||
|
|
||||||
- Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
|
<Steps>
|
||||||
- Apply targeted edits with `openclaw config set` or `openclaw configure`.
|
<Step title="Compare with docs">
|
||||||
- Rerun `openclaw config validate` after each change.
|
Ask the agent to compare your current config with the relevant docs page and suggest the smallest fix.
|
||||||
- If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.
|
</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
|
## Related
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user