openclaw - 💡(How to fix) Fix Doctor cannot recover from invalid third-party plugin config; gateway hard-fails to start [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#62976Fetched 2026-04-09 07:59:55
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Participants

Error Message

  • Plugin manifest/schema/runtime has incompatibility (e.g. missing required fields, schema format mismatch, runtime init error)

Root Cause

A single incompatible plugin should not be able to brick the control plane.

RAW_BUFFERClick to expand / collapse

Problem

A bad third-party plugin config can put OpenClaw into a hard startup failure where openclaw doctor --fix does not recover the system.

In practice this becomes a P0 outage: gateway won't start until users manually edit/remove plugin config entries.

Repro (real environment)

  • OpenClaw: 2026.3.24
  • Add a third-party plugin via plugins.load.paths + plugins.entries.*
  • Plugin manifest/schema/runtime has incompatibility (e.g. missing required fields, schema format mismatch, runtime init error)
  • Restart gateway

Observed

  • Gateway startup aborts with plugin/config validation errors
  • openclaw doctor --fix is insufficient in this state
  • Manual deletion of plugin-related config is required to recover

Expected

  1. Startup should degrade gracefully for third-party plugin failures:
    • quarantine/disable bad plugin entry automatically
    • keep gateway bootable
  2. openclaw doctor --fix should detect and remove/disable broken plugin references (plugins.allow, plugins.entries, plugins.load.paths) with clear report.
  3. Provide a --safe-mode startup or doctor plugin quarantine path for outage recovery.

Why this matters

A single incompatible plugin should not be able to brick the control plane.

Suggestion

  • Add plugin preflight stage with non-fatal isolation for non-core plugins
  • Persist a quarantine list and boot with warning
  • Enhance doctor with deterministic plugin cleanup actions

extent analysis

TL;DR

Implement a plugin preflight stage to quarantine incompatible plugins and enhance the openclaw doctor command to detect and remove broken plugin references.

Guidance

  • Introduce a non-fatal isolation mechanism for non-core plugins to prevent startup failures due to incompatible plugins.
  • Develop a quarantine list to store incompatible plugins and boot the gateway with warnings instead of failures.
  • Enhance the openclaw doctor --fix command to detect and remove broken plugin references, including plugins.allow, plugins.entries, and plugins.load.paths.
  • Consider adding a --safe-mode startup option or a doctor plugin quarantine command to facilitate outage recovery.

Example

No code snippet is provided as the issue does not contain specific code references.

Notes

The proposed solution focuses on improving the robustness of the OpenClaw startup process and the openclaw doctor command. However, the implementation details may vary depending on the specific requirements and constraints of the OpenClaw system.

Recommendation

Apply workaround by implementing a plugin preflight stage and enhancing the openclaw doctor command, as this approach addresses the root cause of the issue and provides a more robust solution for handling incompatible plugins.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING