openclaw - 💡(How to fix) Fix Bundled extensions in dist/ break maintainer workflow with bind-mounted source [1 comments, 2 participants]

Summary

Since the v2026.4.x series, OpenClaw ships extensions pre-bundled in dist/extensions/<plugin>/ inside the Docker image, and the plugin loader prefers these bundles over TypeScript sources at extensions/<plugin>/src/. This silently breaks the workflow used by external maintainers who bind-mount their fork's extensions/<plugin>/ directory into a running container to test PR changes against a real installation, without rebuilding the image.

Affected versions

• Working: v2026.3.x and earlier — dist/extensions/ did not exist in the image, the bind-mounted TS sources were loaded directly via jiti.
• Broken: v2026.4.x (verified on v2026.4.20-beta.x and v2026.4.24) — dist/extensions/<plugin>/*.js is loaded by the plugin discovery, the bind-mounted extensions/<plugin>/src/ is inert.

Reproduction

1. Run ghcr.io/openclaw/openclaw:2026.4.24.
2. Bind-mount <your-fork>/extensions/synology-chat:/app/extensions/synology-chat:ro.
3. Modify <your-fork>/extensions/synology-chat/src/webhook-handler.ts to add a distinctive log line (for example a params.log?.warn("[CHECK]") at the entry of authorizeSynologyWebhook).
4. Restart the gateway, send a webhook through, observe gateway logs.

Expected: the [CHECK] log appears in gateway logs.

Actual: the log does not appear; the corresponding code in /app/dist/channel-*.js (the bundled chunk) runs instead, with the version of the code that was packaged at image build time.

Why this matters

External maintainers and contributors typically iterate on plugin code by:

1. Editing extensions/<plugin>/src/*.ts in their fork checkout.
2. Bind-mounting that directory into the upstream container.
3. Restarting the container.
4. Exercising the plugin path in a real production-like setup before pushing the PR.

This loop used to work because the loader resolved extensions/<plugin>/ first. Now contributors who try this still see the old code running, which leads to hours of confused debugging ("my log doesn't appear", "my fix doesn't work") before realizing the bundle is masking the bind-mount.

The workaround is to run pnpm build:docker locally and additionally bind-mount <your-fork>/dist/extensions/<plugin> to /app/dist/extensions/<plugin>. This works but adds significant friction to PR validation.

Suggested directions

• Document the new requirement explicitly in the contributor docs (the dist/extensions/ precedence and the pnpm build:docker step).
• Or: in src/plugins/bundled-dir.ts, expose a clean opt-in (env var or config flag) for "prefer source over bundled, plugin by plugin" usable in production-like images.
• Or: when a TS source is found at extensions/<plugin>/ AND a bundle exists at dist/extensions/<plugin>/, log a one-time warning at startup so the ambiguity is visible.

Environment

• macOS arm64, Docker via OrbStack, image ghcr.io/openclaw/openclaw:2026.4.24.
• Loader-related code: src/plugins/sdk-alias.ts (isBundledPluginDistModulePath), src/plugins/bundled-dir.ts.

Happy to test patches.