openclaw - 💡(How to fix) Fix [Bug]: 2026.4.27 plugin runtime-deps ENOENT race during hot channel reload leaves outbound permanently broken (regression of #55551) [4 comments, 3 participants]

Summary

On openclaw 2026.4.27 (macOS LaunchAgent gateway), any live edit to `openclaw.json` that triggers a channel hot-reload can fail plugin registration with `ENOENT` on a runtime-deps file that demonstrably exists on disk milliseconds later. When this hits the telegram plugin, it leaves the channel in a permanently cached `Outbound not configured for channel: telegram` state until manual gateway restart — making the bot appear unresponsive while the gateway itself is healthy.

This is functionally a regression of #55551 (closed 2026-04-25, fixed in v2026.3.28 via `resolveOutboundChannelPlugin` registry recovery): the outbound-resolution recovery path covers the missing-plugin case but does not cover the plugin-actively-failed-to-register case, where the cached failure state pre-empts the recovery fallback. Related to #71805 (ENOTEMPTY race on plugin-sdk in 2026.4.24, closed) — same problem area (parallel runtime-deps materialization), different file/error.

Environment

• OpenClaw: 2026.4.27 (cbc2ba0)
• Node: 25.5.0 (Homebrew)
• Host: macOS, LaunchAgent gateway under `gui/$UID/ai.openclaw.gateway`
• Install: `npm i -g openclaw` → `~/.npm-global/lib/node_modules/openclaw`
• Runtime-deps mirror: `~/.openclaw/plugin-runtime-deps/openclaw-2026.4.27-44803533892a/dist/`

Reproduction

1. Have an openclaw 2026.4.27 gateway running healthy with telegram channel configured.
2. Modify `~/.openclaw/openclaw.json` to add or change a telegram account (in our case: an agent added `channels.telegram.accounts.forge` with a SecretRef botToken).
3. Gateway logs: ``` [reload] config change requires channel reload (telegram) — deferring until N operation(s)... ```
4. When the deferred reload fires, the telegram plugin re-register may fail with ENOENT on a runtime-deps file: ``` [plugins] telegram failed during register from /…/openclaw/dist/extensions/telegram/index.js: Error: ENOENT: no such file or directory, open '/Users/page/.openclaw/plugin-runtime-deps/openclaw-2026.4.27-44803533892a/dist/docs-path-DVJW8JaL.js' [plugins] 1 plugin(s) failed to initialize (register: telegram). Run 'openclaw plugins list' for details. ```
5. The file exists on disk (verified with `ls -la` immediately after — same path, present). The race is in the loader's `fs.open()` returning ENOENT during the plugin-runtime-deps mirror materialization window.
6. From this point, all outbound on telegram fails permanently with the cached error: ``` [ws] ⇄ res ✗ agent errorCode=UNAVAILABLE errorMessage=Error: Outbound not configured for channel: telegram cached=true [warn] Subagent announce give up (retry-limit) … requester=agent:main:telegram:direct:<chatId> retries=3 endedAgo=98s Subagent completion direct announce failed for run …: Error: Outbound not configured for channel: telegram ```
7. The gateway's `resolveOutboundChannelPlugin` recovery path (added per #55551 in v2026.3.28) does NOT recover here — likely because the plugin is in a 'failed-register' state, not a 'missing' state.

Workaround

`launchctl kickstart -k gui/$UID/ai.openclaw.gateway` — clean restart with runtime-deps fully present from the start. Telegram plugin then registers successfully and the queued failed deliveries are auto-recovered via `delivery-recovery`. Takes ~10 seconds. Verified working.

Hypothesized fix areas

1. Runtime-deps materialization should be idempotent and complete-before-import. During channel hot-reload, the loader should wait for the runtime-deps mirror to be coherent before attempting plugin re-register. Or use a manifest-driven file existence pre-check before `require()`.
2. `resolveOutboundChannelPlugin` recovery should cover failed-register state, not just missing-plugin state. When a plugin's last register attempt failed, retry the register before returning the cached `Outbound not configured` error.
3. Cached registration failures should have a TTL (current behavior appears to cache forever within the gateway lifetime). A small TTL with bounded retry would let transient races self-heal.

Why this matters

For a personal-assistant deployment (Telegram is the primary user-facing channel), this is silent breakage — gateway is healthy, status reports green, but outbound is dead until someone notices and runs kickstart. We hit this twice tonight from different config-change triggers (a cron edit, an agent adding a new bot). It's likely common in any environment with active config evolution.

Cross-references

• #55551 (CLOSED 2026-04-25, v2026.3.28): fixed the `Outbound not configured for channel: telegram` symptom for the missing-plugin case. This bug is a regression of that — same symptom, different root cause path (failed-register vs missing).
• #71805 (CLOSED 2026-04-26): `ENOTEMPTY` race on plugin-sdk during parallel bootstrap in 2026.4.24. Same problem area (parallel runtime-deps materialization), different error code. The 2026.4.27 release notes mention plugin-runtime-deps caching/file-lock improvements ('reducing repeated startup chunk scans and avoiding FileHandle-GC recovery stalls') — those fixes addressed startup but not the hot-reload path.
• #55099 (OPEN): unrelated but in the telegram/network area — the 'sticky IPv4-only dispatcher' isn't actually sticky across requests. Mentioning only because the symptoms can compound during the same incident.