You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,7 @@ Docs: https://docs.openclaw.ai
12
12
13
13
- Agents/tools: skip optional media and PDF tool factories when the effective tool denylist already blocks them, avoiding unnecessary hot-path setup for tools that will be filtered out before model use. (#76773) Thanks @dorukardahan.
14
14
- Discord/status: let explicit reaction tool calls opt into tracking subsequent tool progress on the reacted message with `trackToolCalls: true`, and use the shared tool display emoji table for status reactions.
15
+
- Gateway/config: stop Gateway startup and hot reload from auto-restoring invalid config; invalid config now fails closed and `openclaw doctor --fix` owns last-known-good repair.
15
16
- Gateway/performance: lazy-load early runtime discovery and shutdown-hook helpers, defer maintenance timers until after readiness, and trim duplicate plugin auto-enable work during Gateway startup.
16
17
- QA/Mantis: add a `pnpm openclaw qa mantis discord-smoke` runner and manual GitHub workflow that verify the Mantis Discord bot can see the configured guild/channel, post a smoke message, add a reaction, and upload artifacts.
17
18
- Gateway/performance: lazy-load the heavy cron runtime after the rest of Gateway startup, defer restart-sentinel refresh after readiness, and let the Gateway startup benchmark write per-run V8 CPU profiles with `--cpu-prof-dir`.
Copy file name to clipboardExpand all lines: docs/cli/config.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -439,9 +439,9 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
439
439
openclaw config validate
440
440
```
441
441
442
-
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).
442
+
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).
443
443
444
-
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.
444
+
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.
Copy file name to clipboardExpand all lines: docs/cli/plugins.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,10 +104,10 @@ is available, then fall back to `latest`.
104
104
</Note>
105
105
106
106
<AccordionGroup>
107
-
<Accordiontitle="Config includes and invalid-config recovery">
107
+
<Accordiontitle="Config includes and invalid-config repair">
108
108
If your `plugins` section is backed by a single-file `$include`, `plugins install/update/enable/disable/uninstall` write through to that included file and leave `openclaw.json` untouched. Root includes, include arrays, and includes with sibling overrides fail closed instead of flattening. See [Config includes](/gateway/configuration) for the supported shapes.
109
109
110
-
If config is invalid during install, `plugins install` normally fails closed and tells you to run `openclaw doctor --fix` first. During Gateway startup, invalid config for one plugin is isolated to that plugin so other channels and plugins can keep running; `openclaw doctor --fix` can quarantine the invalid plugin entry. The only documented install-time exception is a narrow bundled-plugin recovery path for plugins that explicitly opt into `openclaw.install.allowInvalidConfigRecovery`.
110
+
If config is invalid during install, `plugins install` normally fails closed and tells you to run `openclaw doctor --fix` first. During Gateway startup and hot reload, invalid plugin config fails closed like any other invalid config; `openclaw doctor --fix` can quarantine the invalid plugin entry. The only documented install-time exception is a narrow bundled-plugin recovery path for plugins that explicitly opt into `openclaw.install.allowInvalidConfigRecovery`.
111
111
112
112
</Accordion>
113
113
<Accordiontitle="--force and reinstall vs update">
Copy file name to clipboardExpand all lines: docs/gateway/troubleshooting.md
+18-16Lines changed: 18 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -300,9 +300,10 @@ Related:
300
300
-[Configuration](/gateway/configuration)
301
301
-[Doctor](/gateway/doctor)
302
302
303
-
## Gateway restored last-known-good config
303
+
## Gateway rejected invalid config
304
304
305
-
Use this when the Gateway starts, but logs say it restored `openclaw.json`.
305
+
Use this when Gateway startup fails with `Invalid config` or hot reload logs say
306
+
it skipped an invalid edit.
306
307
307
308
```bash
308
309
openclaw logs --follow
@@ -313,19 +314,19 @@ openclaw doctor
313
314
314
315
Look for:
315
316
316
-
-`Config auto-restored from last-known-good`
317
-
-`gateway: invalid config was restored from last-known-good backup`
318
-
-`config reload restored last-known-good config after invalid-config`
319
-
- A timestamped `openclaw.json.clobbered.*` file beside the active config
320
-
- A main-agent system event that starts with `Config recovery warning`
317
+
-`Invalid config at ...`
318
+
-`config reload skipped (invalid config): ...`
319
+
-`Config write rejected: ...`
320
+
- A timestamped `openclaw.json.rejected.*` file beside the active config
321
+
- A timestamped `openclaw.json.clobbered.*` file if `doctor --fix` repaired a broken direct edit
321
322
322
323
<AccordionGroup>
323
324
<Accordiontitle="What happened">
324
-
- The rejected config did not validate during startup or hot reload.
325
-
- OpenClaw preserved the rejected payload as `.clobbered.*`.
326
-
- The active config was restored from the last validated last-known-good copy.
327
-
- The next main-agent turn is warned not to blindly rewrite the rejected config.
328
-
- If all validation issues were under `plugins.entries.<id>...`, OpenClaw would not restore the whole file. Plugin-local failures stay loud while unrelated user settings remain in the active config.
325
+
- The config did not validate during startup, hot reload, or an OpenClaw-owned write.
326
+
- Gateway startup fails closed instead of rewriting `openclaw.json`.
327
+
- Hot reload skips invalid external edits and keeps the current runtime config active.
328
+
- OpenClaw-owned writes reject invalid/destructive payloads before commit and save `.rejected.*`.
329
+
- `openclaw doctor --fix` owns repair. It can remove non-JSON prefixes or restore the last-known-good copy while preserving the rejected payload as `.clobbered.*`.
329
330
330
331
</Accordion>
331
332
<Accordiontitle="Inspect and repair">
@@ -338,16 +339,17 @@ Look for:
338
339
```
339
340
</Accordion>
340
341
<Accordiontitle="Common signatures">
341
-
- `.clobbered.*` exists → an external direct edit or startup read was restored.
342
+
- `.clobbered.*` exists → doctor preserved a broken external edit while repairing the active config.
342
343
- `.rejected.*` exists → an OpenClaw-owned config write failed schema or clobber checks before commit.
343
344
- `Config write rejected:` → the write tried to drop required shape, shrink the file sharply, or persist invalid config.
344
-
- `Rejected validation details:` → the recovery log or main-agent notice includes the schema path that caused the restore, such as `agents.defaults.execution` or `gateway.auth.password.source`.
345
-
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, or `size-drop-vs-last-good:*` → startup treated the current file as clobbered because it lost fields or size compared with the last-known-good backup.
345
+
- `config reload skipped (invalid config):` → a direct edit failed validation and was ignored by the running Gateway.
346
+
- `Invalid config at ...` → startup failed before Gateway services booted.
347
+
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good`, or `size-drop-vs-last-good:*` → an OpenClaw-owned write was rejected because it lost fields or size compared with the last-known-good backup.
346
348
- `Config last-known-good promotion skipped` → the candidate contained redacted secret placeholders such as `***`.
347
349
348
350
</Accordion>
349
351
<Accordiontitle="Fix options">
350
-
1. Keep the restored active config if it is correct.
352
+
1. Run `openclaw doctor --fix` to let doctor repair prefixed/clobbered config or restore last-known-good.
351
353
2. Copy only the intended keys from `.clobbered.*` or `.rejected.*`, then apply them with `openclaw config set` or `config.patch`.
352
354
3. Run `openclaw config validate` before restarting.
353
355
4. If you edit by hand, keep the full JSON5 config, not just the partial object you wanted to change.
Copy file name to clipboardExpand all lines: docs/help/faq.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -804,15 +804,15 @@ lives on the [First-run FAQ](/help/faq-first-run).
804
804
805
805
- OpenClaw-owned config writes validate the full post-change config before writing.
806
806
- Invalid or destructive OpenClaw-owned writes are rejected and saved as `openclaw.json.rejected.*`.
807
-
- If a direct edit breaks startup or hot reload, the Gateway restores the last-known-good config and saves the rejected file as `openclaw.json.clobbered.*`.
808
-
- The main agent receives a boot warning after recovery so it does not blindly write the bad config again.
807
+
- If a direct edit breaks startup or hot reload, Gateway fails closed or skips the reload; it does not rewrite `openclaw.json`.
808
+
- `openclaw doctor --fix` owns repair and can restore last-known-good while saving the rejected file as `openclaw.json.clobbered.*`.
809
809
810
810
Recover:
811
811
812
-
- Check `openclaw logs --follow` for `Config auto-restored from last-known-good`, `Config write rejected:`, or `config reload restored last-known-good config`.
812
+
- Check `openclaw logs --follow` for `Invalid config at`, `Config write rejected:`, or `config reload skipped (invalid config)`.
813
813
- Inspect the newest `openclaw.json.clobbered.*` or `openclaw.json.rejected.*` beside the active config.
814
-
- Keep the active restored config if it works, then copy only the intended keys back with `openclaw config set` or `config.patch`.
815
-
- Run `openclaw config validate` and `openclaw doctor`.
814
+
- Run `openclaw config validate` and `openclaw doctor --fix`.
815
+
- Copy only the intended keys back with `openclaw config set` or `config.patch`.
816
816
- If you have no last-known-good or rejected payload, restore from backup, or re-run `openclaw doctor` and reconfigure channels/models.
817
817
- If this was unexpected, file a bug and include your last known config or any backup.
818
818
- A local coding agent can often reconstruct a working config from logs or history.
@@ -825,7 +825,7 @@ lives on the [First-run FAQ](/help/faq-first-run).
825
825
- Use `config.patch` for partial RPC edits; keep `config.apply` for full-config replacement only.
826
826
- If you are using the owner-only `gateway` tool from an agent run, it will still reject writes to `tools.exec.ask` / `tools.exec.security` (including legacy `tools.bash.*` aliases that normalize to the same protected exec paths).
0 commit comments