openclaw - 💡(How to fix) Fix npm plugin peer link drift can leave Discord tokens configured_unavailable [1 comments, 2 participants]

Summary

npm-installed OpenClaw plugins can lose or retain a stale local node_modules/openclaw peer dependency link. When that happens, plugin runtime/contract imports that depend on the host openclaw package can fail. In a live incident this caused the Discord plugin secret contract import to fail, leaving all configured Discord bot tokens as configured_unavailable even though the file-backed secrets existed and openclaw plugins doctor reported no issues.

Observed impact

On a local OpenClaw gateway, Telegram stayed connected, but Discord accounts mikhail, nadia, viktor, and vladislava were stopped/disconnected.

openclaw health --json --timeout 30000 showed the configured Discord accounts as:

configured: true
running: false
connected: false
tokenSource: config
tokenStatus: configured_unavailable
lastError: not configured

The token values were present in the configured file-backed secret provider. openclaw secrets audit --json did not show unresolved refs.

Root cause evidence

Importing the Discord plugin secret contract failed from the managed npm plugin tree:

Cannot find package 'openclaw' imported from /Users/mike/.openclaw/npm/node_modules/@openclaw/discord/dist/secret-config-contract-5S9U9pjx.js

The npm-installed Discord/Codex/ACPX plugin package trees were missing the plugin-local node_modules/openclaw peer link. Running openclaw plugins update discord, openclaw plugins update codex, and openclaw plugins update acpx recreated those peer links; after openclaw gateway restart, Discord tokens resolved and all Discord accounts connected.

Why this is a bug

The install/update path already knows how to create the host openclaw peer link for npm-installed plugins, but two gaps let this become an outage:

1. openclaw plugins doctor did not audit missing/stale openclaw peer links and incorrectly reported no plugin issues.
2. Gateway startup loaded plugins without first repairing missing/stale peer links, so one broken npm tree could leave runtime contract imports failing until an operator manually ran plugin updates.

Expected behavior

• openclaw plugins doctor should report npm-installed plugins whose declared peerDependencies.openclaw link is missing, unreadable, or points at the wrong host package root.
• Gateway startup should run a lightweight repair pass before loading runtime plugins so missing/stale node_modules/openclaw links are recreated automatically.
• If repair cannot resolve the issue, the gateway should emit a clear plugin diagnostic rather than surfacing downstream channel token status as only configured_unavailable / not configured.

Proposed fix implemented in fork

I implemented a source-level fix in a fork:

https://github.com/KovaForge/openclaw/commit/519dd4dac0

Patch summary:

• Adds reusable audit/repair helpers in src/plugins/plugin-peer-link.ts.
• Extends openclaw plugins doctor to report broken npm plugin openclaw peer links.
• Runs gateway startup peer-link repair before runtime plugin loading in src/gateway/server-startup-plugins.ts.
• Adds regression tests for missing and wrong-target peer links in src/plugins/plugin-peer-link.test.ts.

Verification

Focused checks passed locally:

pnpm exec vitest run src/plugins/plugin-peer-link.test.ts
pnpm exec oxlint src/plugins/plugin-peer-link.ts src/gateway/server-startup-plugins.ts src/cli/plugins-cli.ts src/plugins/plugin-peer-link.test.ts
pnpm tsgo:core

Operational verification after repair:

openclaw plugins doctor
openclaw health --json --timeout 30000
openclaw channels status --deep

Result: no plugin errors; Discord mikhail, nadia, viktor, and vladislava were running/connected with token status available.