openclaw - 💡(How to fix) Fix [Bug] Plugin loader rewraps require(ws) as namespace object instead of constructor — custom plugins silently break [2 comments, 3 participants]

Summary

Custom plugins that use require("ws") receive a namespace object (typeof "object") instead of the constructor function (typeof "function") when running inside the OpenClaw plugin loader. This causes new require("ws")(url) to throw WebSocket is not a constructor, silently breaking any plugin that uses the standard Node ws import pattern.

Symptom

Inside a custom plugin (loaded via extensions/), require("ws") returns a namespace object with .WebSocket, .Server, etc. as properties, rather than the ws constructor function that standalone Node returns for require("ws") with [email protected].

Plugins that do:

const WebSocket = require("ws");
// ...
const ws = new WebSocket(url);

Get: TypeError: WebSocket is not a constructor

Bundled upstream plugins (discord, feishu, browser, nostr) avoid this by using import * as ws from "ws" + ws.WebSocket as the constructor, which works with both shapes. But custom plugins following the standard require("ws") pattern from ws docs will break.

Root cause

The OpenClaw plugin loader (jiti-based transpile + sandbox) rewraps or transforms require() calls for bundled modules. The transformation for ws preserves the namespace object shape but doesn't expose the default export as a callable constructor — matching import * as ws from "ws" semantics rather than const ws = require("ws") CommonJS semantics.

In CommonJS, require("ws") returns the constructor directly ([email protected] module.exports = WebSocket). In ESM-style rewrap, it returns { default: WebSocket, WebSocket, Server, ... }.

Impact

• Any custom plugin using require("ws") and treating the result as a constructor will fail at runtime.
• The failure is silent in Promise executors — new WebSocket(url) throws inside new Promise(...), and if the surrounding code only has .catch() on the outer promise chain (not inside the executor), the promise never settles.
• This caused the depeches-flow custom plugin to silently fail all WebSocket RPC calls (wakes and surfaces) for an unknown duration, with zero error logging and zero delivery.

Workaround

Custom plugins can resolve the constructor at runtime:

const wsModule = require("ws");
const WebSocket = wsModule.WebSocket || wsModule.default || wsModule;

Or match the upstream pattern:

import * as ws from "ws";
// use ws.WebSocket as constructor

Suggested fix

Option A: Plugin loader should preserve CommonJS module.exports semantics for require(), making require("ws") return the constructor function as it would in plain Node.

Option B: Document that require() in the plugin sandbox returns ESM namespace objects, and custom plugins must use the wsModule.WebSocket || wsModule.default || wsModule pattern. Add a helper to plugin-sdk: resolveWsConstructor().

Option A is preferable — it eliminates the surprise factor and keeps custom plugin code matching standalone Node behavior.

Environment

• OpenClaw 2026.4.25
• macOS Darwin 24.3.0 arm64
• Custom plugin in ~/.openclaw/extensions/
• [email protected] (bundled with openclaw)

Related

• #74312 (auth-epoch session reset — discovery of this bug was a side-effect of debugging silent plugin failures)