Watcher: rapid multi-file edits trigger multiple full plugin reloads instead of one coalesced reload

Summary

Editing several watched files within a short window (e.g. openclaw.json plus one or two other watched files) triggers a separate full plugin reload for each save. There is currently no:

1. Debounce when multiple watched files change in a short window — every save is its own reload.
2. Scoped reload — small changes to non-config watched files (e.g. agent bootstrap markdown) still pay the cost of restarting all plugins/channels.
3. Visibility — the reload log line does not say which file triggered it, which makes diagnosing reload storms difficult.

Environment

• OpenClaw 2026.4.25 (also reproduces on 2026.4.26)
• macOS 26.4 arm64 / Node 24.13.1
• Single host

Reproduction

With the gateway running, save 4–5 watched files within ~30 seconds, e.g.:

1. vi ~/.openclaw/openclaw.json (toggle any flag, save)
2. Edit any other watched file (workspace bootstrap markdown, plugin dist/index.js, etc.), save
3. Re-save openclaw.json after another small change
4. Save another watched file
5. One more openclaw.json save

Each individual save produces its own full plugin reload sequence in gateway.log:

23:32:15  [plugins] [<plugin>] loaded …
23:32:15  [gateway] http server listening (… ; ~6s)
23:32:49  [plugins] [<plugin>] loaded …          (+34s, second save)
23:32:55  [plugins] [<plugin>] loaded …          (+6s,  third save)
23:33:01  [plugins] [<plugin>] loaded …          (+6s,  fourth save)
23:34:13  [plugins] [<plugin>] loaded …          (+72s, fifth save)

So 5 saves in ~2 minutes → 5 independent full reloads, each restarting every plugin and channel runtime.

Expected behavior

1. Debounce file-change events. A short configurable window (e.g. 2–5 s) where consecutive change events coalesce into a single reload, so saving five files in 30 s triggers one reload.

2. Scoped reload. When the changed file is a non-config watched file (e.g. an agent bootstrap markdown), refresh only the affected subsystem instead of restarting all plugins/channels.

3. Surface reload reason in the log line. Today the only signal is the generic plugin-loaded line — no indication of which file triggered the reload. A line like [gateway] config reload triggered by <file path> would make diagnosing reload storms much faster.

Why this matters

When multiple plugins or channel runtimes are wired up, every reload pays the full restart cost (re-init plugins, reconnect external services, re-establish sessions). Multi-file edit sessions — common when iterating on config + workspace files together — turn into 4–6× the necessary restart work, and downstream systems (rate-limited APIs, staggered reconnect queues) start failing in ways that look unrelated.

4.25 introduced stricter schema validation and 4.26 added degraded-mode tolerance for schema errors (very nice change), but the underlying watcher fan-out is unchanged: every watched-file save still triggers a full reload.

Suggested implementation surface (non-binding)

• Coalesce events from chokidar watchers in the gateway-side config loader (similar pattern to recent watcher hardening elsewhere in the codebase).
• For non-config watched files, route changes through a lighter-weight refresh path instead of the full plugin/channel reload path.
• Expose gateway.reload.debounceMs (default ~2500–5000) as a sibling to the existing gateway.reload.deferralTimeoutMs.
• Optional: a small [gateway] reload triggered by <file> info-level log so operators can correlate reload storms with file edits.

Workaround

For batches of edits, stop the gateway, perform all edits, then start the gateway so only one reload happens.

Happy to test any patch against this setup. Thanks for the work on 4.25/4.26.