Bug Evidence Report

openclaw migrate → Gateway Crash-Loop

plugins.entries for uninstalled plugins written without pre-flight check

OpenClaw v2026.4.26 · Ubuntu 24.04 LTS · Filed: 2026-05-06

Bug Type

Crash (process/app exits or hangs)

Beta Release Blocker

No

Summary

When running openclaw migrate apply (a brand-new command introduced April 28, 2026), OpenClaw copies Claude Code or Hermes plugin configuration blocks directly into ~/.openclaw/openclaw.json.

The issue occurs when those plugins are not installed on the target system.

OpenClaw Gateway validates plugins.entries during startup. If referenced plugins do not exist locally, the entire config is rejected and the Gateway crash-loops.

The migration command reports success even though it creates an invalid configuration.

Result:

• Gateway fails to start
• systemd enters restart loop
• User receives no meaningful migration warning
• Recovery requires manual config editing or repair tooling

Steps to Reproduce

1. Fresh Ubuntu 24.04 LTS
2. Install Node.js v24 via nvm
3. Install OpenClaw:

npm install -g openclaw@latest

1. Run onboarding:

openclaw onboard

1. Create Claude config:

~/.claude/settings.json

Containing MCP/plugin references such as:

• brave-search
• github
• fs

1. Run migration:

openclaw migrate apply

1. Start Gateway:

openclaw gateway start

Expected Behavior

Migration should either:

Option A

Skip unresolved plugins.entries and emit post-migration install hints.

Example:

{
  "_migrationHints": {
    "pluginsToInstall": [
      "openclaw plugins install brave",
      "openclaw plugins install github"
    ]
  }
}

Option B

Automatically install referenced plugins before writing config.

Actual Behavior

Gateway startup immediately fails.

Example log output:

plugin schema config invalid: plugins.entries.brave
plugin schema config invalid: plugins.entries.github
Gateway failed to start: plugin registration rejected missing hook names

systemd repeatedly attempts restart until failure threshold is reached.

Migration still reports success.

Impact & Severity

Root Cause

openclaw migrate apply copies:

plugins.entries.<plugin-id>

directly into:

~/.openclaw/openclaw.json

without validating whether referenced plugins exist locally.

Gateway validation later rejects the config.

Evidence From Repository

Official Documentation

Plugin documentation states:

"Missing: config references a plugin id that discovery did not find"

Gateway currently treats this as fatal during startup.

Issue #52992

Confirms that invalid:

• plugins.allow
• plugins.entries

references can block all CLI commands, including:

openclaw doctor --fix

This can create a deadlock scenario.

Issue #25595

Shows identical crash-loop behavior:

• plugin config becomes invalid
• Gateway repeatedly restarts
• systemd eventually gives up

Reported restart count:

3320 restarts

Release v2026.5.4

Release notes added:

emit catalog-backed install hints when plugins.entries references an uninstalled plugin

This confirms maintainers already recognize the issue category.

However:

• fix only applies to existing configs
• migration importer still writes invalid entries

Migration Output Evidence

openclaw migrate plan

openclaw migrate plan

Output:

✓ Plugin config entries (brave, github, fs) [will write]

No warning is emitted.

openclaw migrate apply

openclaw migrate apply

Output:

✓ Wrote plugin config entries: brave, github, fs
Migration complete.

Again:

• no validation
• no install check
• no warning

Gateway Failure Evidence

Gateway Start

openclaw gateway start

Result:

Config invalid:
- plugins.entries.brave: plugin not found
- plugins.entries.github: plugin not found
- plugins.entries.fs: plugin not found

Gateway aborts startup.

Broken Config Example

Generated invalid config:

{
  "plugins": {
    "entries": {
      "brave": {},
      "github": {},
      "fs": {}
    }
  }
}

None of these plugins exist locally.

Correct Safe Migration Behavior

Expected safer output:

{
  "plugins": {
    "entries": {}
  },
  "_migrationHints": {
    "pluginsToInstall": [
      "openclaw plugins install brave",
      "openclaw plugins install github",
      "openclaw plugins install fs"
    ]
  }
}

Doctor Output Comparison

Before Migration

Config ✓ valid
Gateway ✓ reachable
Plugins ✓ 0 external plugins installed

After Migration

Config ✗ INVALID
plugins.entries.brave: plugin not found
plugins.entries.github: plugin not found
plugins.entries.fs: plugin not found

The only change was:

openclaw migrate apply

systemd Crash Loop

Example journal output:

openclaw-gateway.service: Main process exited
Scheduled restart job
Scheduled restart job
Scheduled restart job
Start request repeated too quickly
Failed to start OpenClaw Gateway

Crash-loop behavior confirmed.

Why This Is Dangerous

The migration feature:

• appears successful
• silently writes invalid state
• creates broken backups
• can potentially block repair tooling
• bricks fresh installations

This affects first-time onboarding users most severely.

Workaround

Option 1

Run:

openclaw doctor --fix

This quarantines invalid plugin entries.

Option 2

Manually edit:

~/.openclaw/openclaw.json

Remove invalid:

plugins.entries.*

blocks.

Option 3

Install missing plugins manually:

openclaw plugins install <plugin-id>

Then restart Gateway:

openclaw gateway restart

Recommended Fix

1. Pre-flight Validation

Before writing config:

plugins.entries.<id>

must be resolved against installed plugin catalog.

2. Skip Unresolved Plugins

Migration should either:

• skip invalid entries
• emit install hints
• or block migration entirely

3. Backup Timing

Backups must occur:

BEFORE config modification

not after.

Current implementation backs up already-broken state.

Proof This Is a New Regression

Feature introduced in:

v2026.4.26
Released April 28, 2026

Migration command is approximately:

~8 days old

at time of report.

No Existing Issue Matches This Vector

Existing issues involve:

• manual config edits
• upgrades
• stale manifests
• schema mismatches

No existing issue documents:

openclaw migrate apply

creating invalid plugins.entries.

Environment Information

OpenClaw

openclaw --version

2026.4.26

Node.js

node --version

v24.0.0

npm

npm --version

10.9.2

OS

Ubuntu 24.04.2 LTS

Failure Chain Summary

openclaw migrate apply
        │
        ▼
Writes plugins.entries.* into config
        │
        ▼
No validation occurs
        │
        ▼
Gateway startup validation fails
        │
        ▼
Gateway exits with code 1
        │
        ▼
systemd restart loop begins
        │
        ▼
Fresh installation becomes unusable

Final Assessment

Severity: HIGH

This is a migration-time configuration corruption bug that:

• silently produces invalid state
• breaks Gateway startup
• affects fresh onboarding users
• lacks adequate warnings
• bypasses degraded-mode protections
• may deadlock repair tooling

The issue originates specifically from:

openclaw migrate apply

writing unresolved plugin entries without pre-flight validation.