openclaw - 💡(How to fix) Fix Downgrading from 2026.4.29 to 2026.4.27 fails due to stale file-transfer entry in ~/.openclaw/plugins/installs.json [3 comments, 3 participants]

Summary

After upgrading OpenClaw from 2026.4.27 to 2026.4.29, message handling became extremely slow. I attempted to downgrade back to 2026.4.27 using npm. The downgrade appeared to succeed, but the gateway and CLI could no longer start because OpenClaw kept trying to load a file-transfer bundled plugin that does not exist in the 2026.4.27 package.

The confusing part is that the error message pointed to ~/.openclaw/openclaw.json, but openclaw.json did not contain any file-transfer entry. The actual stale reference was in:

~/.openclaw/plugins/installs.json

Removing only the stale pluginId == "file-transfer" entry from installs.json fixed the downgrade.

Environment

• OS: WSL Ubuntu
• Install method: npm global install
• npm global prefix: /home/lysme/.npm-global
• OpenClaw package path: /home/lysme/.npm-global/lib/node_modules/openclaw
• Gateway service: systemd user service
  • ~/.config/systemd/user/openclaw-gateway.service
• Previous working version: 2026.4.27
• Upgraded version: 2026.4.29
• Downgraded target version: 2026.4.27

Upgrade path

The upgrade from 2026.4.27 to 2026.4.29 completed successfully according to the updater:

Update Result: OK
Root: /home/lysme/.npm-global/lib/node_modules/openclaw
Before: 2026.4.27
After: 2026.4.29

However, after the upgrade, the gateway did not become healthy immediately and reported port/service issues:

Gateway did not become healthy after restart.
Port 18789 is already in use.
Gateway already running locally.

Performance regression after upgrade

After upgrading to 2026.4.29, message processing became very slow. Some logs showed very large embedded-run startup/prep times and event-loop saturation, for example:

[agent/embedded] [trace:embedded-run] startup stages ... totalMs=22183
[agent/embedded] [trace:embedded-run] prep stages ... totalMs=118449
system-prompt:61154ms
stream-setup:19943ms
[diagnostic] liveness warning: reasons=event_loop_delay,event_loop_utilization,cpu
eventLoopUtilization=1

This was the reason I attempted to downgrade back to 2026.4.27.

Downgrade command

I downgraded with:

npm install -g [email protected]

The package downgrade completed:

added 2 packages, and changed 443 packages

openclaw --version then reported:

OpenClaw 2026.4.27 (cbc2ba0)

Actual result after downgrade

After downgrading, openclaw gateway restart, openclaw status, and openclaw doctor --fix failed with:

Invalid config at /home/lysme/.openclaw/openclaw.json:
- plugins: plugin: plugin manifest not found:
/home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer/openclaw.plugin.json

The gateway error was:

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
 - plugins: plugin: plugin manifest not found:
 /home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer/openclaw.plugin.json

Run: openclaw doctor --fix
Gateway aborted: config is invalid.

But openclaw doctor --fix also failed before it could repair anything:

[openclaw] Failed to start CLI: Error: Invalid config at /home/lysme/.openclaw/openclaw.json:
- plugins: plugin: plugin manifest not found:
 /home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer/openclaw.plugin.json

Investigation

I checked the main config file:

grep -R -n "file-transfer" ~/.openclaw/openclaw.json

No result.

I also checked:

grep -R -n "file-transfer" ~/.openclaw ~/.config/systemd/user

Initially this did not make it obvious from openclaw.json, and the error message strongly suggested that ~/.openclaw/openclaw.json itself was the source.

Later, a more targeted diagnosis found the actual stale reference in:

~/.openclaw/plugins/installs.json

It contained a stale entry similar to:

{
  "pluginId": "file-transfer",
  "manifestPath": "/home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer/openclaw.plugin.json",
  "source": "/home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer/index.js",
  "rootDir": "/home/lysme/.npm-global/lib/node_modules/openclaw/dist/extensions/file-transfer",
  "enabled": false,
  "packageVersion": "2026.4.27"
}

The important point is that enabled was false, but OpenClaw still treated this stale install registry entry as something that needed to resolve a manifest. Since 2026.4.27 does not contain:

dist/extensions/file-transfer/openclaw.plugin.json

startup failed.

Workaround

The workaround was:

1. Stop the gateway.
2. Back up ~/.openclaw/plugins/installs.json.
3. Remove only the stale pluginId == "file-transfer" entry from ~/.openclaw/plugins/installs.json.
4. Reload/restart the systemd user service.

Example workaround:

systemctl --user stop openclaw-gateway.service || true
pkill -f '[o]penclaw.*gateway' || true
pkill -f '[n]ode.*openclaw' || true

cp ~/.openclaw/plugins/installs.json ~/.openclaw/plugins/installs.json.bak.$(date +%F-%H%M%S)

python3 <<'PY'
import json
import os

p = os.path.expanduser("~/.openclaw/plugins/installs.json")

with open(p, "r", encoding="utf-8") as f:
    data = json.load(f)


def clean(obj):
    if isinstance(obj, list):
        return [
            clean(item)
            for item in obj
            if not (isinstance(item, dict) and item.get("pluginId") == "file-transfer")
        ]

    if isinstance(obj, dict):
        out = {}
        for k, v in obj.items():
            if k == "file-transfer":
                continue
            if isinstance(v, dict) and v.get("pluginId") == "file-transfer":
                continue
            out[k] = clean(v)
        return out

    return obj


data = clean(data)

with open(p, "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
PY

python3 -m json.tool ~/.openclaw/plugins/installs.json >/dev/null

systemctl --user daemon-reload || true
systemctl --user reset-failed openclaw-gateway.service || true
systemctl --user start openclaw-gateway.service

After removing that stale entry, 2026.4.27 started normally again.

Expected behavior

When downgrading to an older version:

• A stale bundled plugin entry in ~/.openclaw/plugins/installs.json should not prevent startup if the plugin is disabled.
• If the plugin manifest no longer exists in the downgraded package, OpenClaw should either:
  • ignore disabled stale plugin registry entries;
  • automatically prune stale bundled plugin records; or
  • provide a repair command that can run even when config validation fails.
• The error should point to the real state file causing the problem. In this case the error reported ~/.openclaw/openclaw.json, but the actual stale reference was in ~/.openclaw/plugins/installs.json.

Suggested fix

Possible fixes:

1. During startup, tolerate missing manifests for disabled plugin registry entries.
2. During version downgrade, prune bundled plugin entries whose manifest path no longer exists.
3. Make openclaw doctor --fix able to repair stale plugin registry entries before full runtime config validation.
4. Improve the error message to include the source file that registered the missing manifest, e.g.:

Missing plugin manifest referenced by ~/.openclaw/plugins/installs.json:
pluginId=file-transfer
manifestPath=...

Notes

The systemd unit still had metadata from 2026.4.29, such as:

Description=OpenClaw Gateway (v2026.4.29)
OPENCLAW_SERVICE_VERSION=2026.4.29

But ExecStart pointed to the current global package path and openclaw --version reported 2026.4.27, so this did not appear to be the direct cause of the manifest error.

The direct cause was the stale file-transfer entry in ~/.openclaw/plugins/installs.json.