@newbase-clawchat/openclaw-clawchat 2026.5.12-3 → 2026.5.12-5

package/README.md

@@ -1,10 +1,10 @@
 # @newbase-clawchat/openclaw-clawchat
 
-OpenClaw channel plugin that connects an agent to ClawChat over the ClawChat Protocol v2, using [`@newbase-clawchat/sdk`](https://www.npmjs.com/package/@newbase-clawchat/sdk) for the WebSocket transport plus a small REST surface for profile / social / media operations (`/v1/*` plus unversioned `/media/upload`).
+OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protocol v2 with a plugin-owned WebSocket client, plus a small REST surface for profile / social / media operations (`/v1/*` plus unversioned `/media/upload`).
 
 ## Features
 
-- WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
+- Plugin-owned WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
 - Invite-code onboarding — no raw credentials required
 - Inbound `message.send` / `message.reply` with reply context
 - Outbound text replies in `static` or `stream` mode, with a consolidated final `message.reply`
@@ -67,10 +67,14 @@ omitting it from the `channels add` CLI catalog. If `channels add` fails with
 `Unknown channel: openclaw-clawchat`, use `/clawchat-login A1B2C3` after a real
 Gateway restart.
 
-After a successful activation on a running Gateway with hot config reload,
-OpenClaw should reload the plugin registry and start the channel without a hard
-restart. Restart the Gateway only after installing/updating the plugin, when
-config reload is disabled, or when the channel probe does not become healthy:
+After a successful activation on a running Gateway with config reload, OpenClaw
+should load the full runtime plugin and start the channel automatically. If the
+Gateway only has the setup-only entry loaded, the credential write forces a
+Gateway reload/restart instead of a setup-only channel hot restart; after the full
+runtime is attached, later channel config changes can hot reload the channel.
+Restart the Gateway manually only after installing/updating the plugin when the
+automatic restart has not happened, when config reload is disabled, or when the
+channel probe does not become healthy:
 
 ```bash
 openclaw gateway restart
@@ -97,7 +101,8 @@ exists, and ensures tool policy covers the plugin. If `tools.allow` or
 id to `tools.alsoAllow` so policy-restricted agents can execute the tools.
 Before activation, account/media tools return a config error instead of
 disappearing; after activation/login, the channel is enabled and the same tools
-read the persisted token/userId after hot config reload or a Gateway restart.
+read the persisted token/userId after the runtime plugin reloads or the Gateway
+restarts.
 
 After activation/login, the channel section is enabled and has credentials:
 
@@ -145,7 +150,7 @@ Then open the printed URL (default `http://127.0.0.1:4318`) to exercise the plug
 src/
   channel.ts          plugin adapter (setup, auth.login, gateway, agentPrompt)
   runtime.ts          inbound dispatch + reply dispatcher
-  client.ts           chat-sdk WebSocket client wrapper
+  client.ts           ClawChat WebSocket client adapter and stream helpers
   api-client.ts       REST client for /v1/* + /media/upload
   inbound.ts          envelope → agent turn
   outbound.ts         agent reply → envelope

package/dist/index.js

@@ -7,7 +7,7 @@ import { registerOpenclawClawlingTools } from "./src/tools.js";
 export default defineChannelPluginEntry({
     id: "openclaw-clawchat",
     name: "Clawling Chat",
-    description: "Clawling Chat Protocol v2 channel plugin (chat-sdk)",
+    description: "Clawling Chat Protocol v2 channel plugin",
     plugin: openclawClawlingPlugin,
     configSchema: { schema: openclawClawlingConfigSchema },
     setRuntime: setOpenclawClawlingRuntime,

package/dist/src/channel.js

@@ -11,6 +11,9 @@ const CLAWCHAT_PLATFORM_PROMPT = "You are replying through ClawChat, a chat-firs
 export const openclawClawlingPlugin = createChatChannelPlugin({
     base: {
         ...openclawClawlingSetupPlugin,
+        reload: {
+            configPrefixes: [`channels.${CHANNEL_ID}`],
+        },
         directory: createEmptyChannelDirectoryAdapter(),
         auth: {
             login: async ({ cfg, accountId, runtime }) => {

package/dist/src/channel.setup.js

@@ -84,7 +84,7 @@ export const openclawClawlingSetupPlugin = {
         selectionLabel: "Clawling Chat",
         docsPath: "/channels/openclaw-clawchat",
         docsLabel: "openclaw-clawchat",
-        blurb: "Clawling Protocol v2 over WebSocket (chat-sdk).",
+        blurb: "ClawChat Protocol v2 over WebSocket.",
         order: 110,
     },
     capabilities: {
@@ -95,9 +95,6 @@ export const openclawClawlingSetupPlugin = {
         polls: false,
         blockStreaming: true,
     },
-    reload: {
-        configPrefixes: [`channels.${CHANNEL_ID}`],
-    },
     configSchema: {
         schema: openclawClawlingConfigSchema,
     },

package/dist/src/client.js

@@ -1,74 +1,17 @@
-import { createWSClient, } from "@newbase-clawchat/sdk";
-function createMsghubConnectTransport(account, transport, lifecycle) {
-    const maybeWrapped = transport;
-    if (maybeWrapped.__openclawInnerTransport)
-        return transport;
-    const wrapped = {
-        __openclawInnerTransport: transport,
-        get state() {
-            return transport.state;
-        },
-        connect(url, handlers) {
-            return transport.connect(url, handlers);
-        },
-        send(data) {
-            let parsed;
-            try {
-                parsed = JSON.parse(data);
-            }
-            catch {
-                transport.send(data);
-                return;
-            }
-            if (!parsed ||
-                typeof parsed !== "object" ||
-                parsed.event !== "connect") {
-                transport.send(data);
-                return;
-            }
-            const env = parsed;
-            const nonce = typeof env.payload?.nonce === "string" ? env.payload.nonce : "";
-            const payload = {
-                token: account.token,
-                nonce,
-                ...(account.userId ? { device_id: account.userId } : {}),
-                capabilities: {
-                    multi_device: true,
-                    device_replay: true,
-                },
-            };
-            const connectEnv = { ...env, payload };
-            transport.send(JSON.stringify(connectEnv));
-            lifecycle?.onConnectFrameSent?.(connectEnv);
-        },
-        close(code, reason) {
-            transport.close(code, reason);
-        },
-    };
-    return wrapped;
-}
-function installMsghubConnectTransport(account, client, lifecycle) {
-    const inner = client;
-    if (!inner.opts?.transport)
-        return;
-    inner.opts.transport = createMsghubConnectTransport(account, inner.opts.transport, lifecycle);
-}
+import { createClawChatClient } from "./ws-client.js";
 export function createOpenclawClawlingClient(account, overrides = {}) {
-    // Only forward a finite `maxRetries` to the SDK — the SDK's own default
-    // is already unbounded, so omitting the field keeps that behavior. This
-    // avoids forcing the SDK to special-case `Infinity`.
-    const maxRetries = account.reconnect.maxRetries;
-    const reconnect = {
-        enabled: true,
-        initialDelay: account.reconnect.initialDelay,
-        maxDelay: account.reconnect.maxDelay,
-        jitterRatio: account.reconnect.jitterRatio,
-        ...(Number.isFinite(maxRetries) ? { maxRetries } : {}),
-    };
-    const options = {
+    const client = createClawChatClient({
         url: account.websocketUrl,
         token: account.token,
-        reconnect,
+        deviceId: account.userId,
+        ...(overrides.transport ? { transport: overrides.transport } : {}),
+        reconnect: {
+            enabled: true,
+            initialDelay: account.reconnect.initialDelay,
+            maxDelay: account.reconnect.maxDelay,
+            jitterRatio: account.reconnect.jitterRatio,
+            maxRetries: account.reconnect.maxRetries,
+        },
         heartbeat: {
             enabled: true,
             interval: account.heartbeat.interval,
@@ -78,14 +21,16 @@ export function createOpenclawClawlingClient(account, overrides = {}) {
             timeout: account.ack.timeout,
             autoResendOnTimeout: account.ack.autoResendOnTimeout,
         },
-        // Buffer outbound sends during the tiny reconnect window so an inbound
-        // message isn't silently dropped while the socket is flapping.
-        queueWhileReconnecting: true,
-        ...(overrides.transport ? { transport: overrides.transport } : {}),
-        ...(overrides.logger ? { logger: overrides.logger } : {}),
-    };
-    const client = createWSClient(options);
-    installMsghubConnectTransport(account, client, overrides.wsLifecycle);
+    });
+    if (overrides.wsLifecycle?.onConnectFrameSent) {
+        const sendRawEnvelope = client.sendRawEnvelope.bind(client);
+        client.sendRawEnvelope = (env) => {
+            sendRawEnvelope(env);
+            if (env.event === "connect") {
+                overrides.wsLifecycle?.onConnectFrameSent?.(env);
+            }
+        };
+    }
     return client;
 }
 function normalizeRouting(params) {
@@ -97,31 +42,26 @@ function normalizeRouting(params) {
     throw new Error("openclaw-clawchat streaming emit requires routing");
 }
 /**
- * Emit a raw v2 envelope directly over the transport so we can carry top-level
- * `chat_id` routing without SDK-injected `to` metadata.
+ * Emit a raw v2 envelope through the local client so stream helpers carry
+ * top-level `chat_id` routing without legacy `to` metadata.
  */
 function emitEnvelope(client, event, payload, routing, options = {}) {
-    const inner = client;
-    if (!options.forceRawTransport && inner.emitRaw) {
-        inner.emitRaw(event, payload, { chat_id: routing.chatId });
+    if (!options.forceRawTransport) {
+        client.emitRaw(event, payload, { chat_id: routing.chatId });
         return;
     }
-    if (!inner.opts?.transport) {
-        if (!options.forceRawTransport && inner.emitRaw) {
-            inner.emitRaw(event, payload, { chat_id: routing.chatId });
-            return;
-        }
-        throw new Error("openclaw-clawchat streaming emit requires SDK raw transport");
+    if (typeof client.nextTraceId !== "function" || typeof client.sendRawEnvelope !== "function") {
+        throw new Error("openclaw-clawchat streaming emit requires local raw transport");
     }
     const env = {
         version: "2",
         event,
-        trace_id: inner.opts.traceIdFactory(),
+        trace_id: client.nextTraceId(),
         emitted_at: Date.now(),
         chat_id: routing.chatId,
         payload,
     };
-    inner.opts.transport.send(JSON.stringify(env));
+    client.sendRawEnvelope(env);
 }
 /**
  * Emit a minimal `message.created` envelope to open a streaming message.
@@ -189,10 +129,8 @@ export function emitStreamDone(client, params) {
  * the same `payload.message_id` as the preceding `message.created` /
  * `message.add` / `message.done` frames.
  *
- * The SDK's high-level `client.replyMessage()` disallows `payload.message_id`
- * on outbound replies (the server normally assigns one via ack); for the
- * streaming-finalize use case the backend expects the correlated id, so we
- * bypass the SDK validator and write directly to the transport.
+ * Final stream replies include the correlated `payload.message_id`, so they
+ * use the local raw-envelope API instead of any higher-level ackable send.
  */
 export function emitFinalStreamReply(client, params) {
     const routing = normalizeRouting(params);

package/dist/src/inbound.js

@@ -1,4 +1,4 @@
-import { EVENT, } from "@newbase-clawchat/sdk";
+import { EVENT, } from "./protocol-types.js";
 import { extractMediaFragments, fragmentsToText } from "./message-mapper.js";
 import { hasRenderableText, isInboundMessagePayload } from "./protocol.js";
 const DEDUP_MAX = 256;

package/dist/src/message-mapper.js

@@ -53,7 +53,7 @@ export function textToFragments(text) {
 /**
  * Extract media fragments from a body (image/file/audio/video). Skips
  * entries missing `url`. Preserves all optional metadata fields the
- * SDK passes through (mime/size/width/height/duration/name).
+ * protocol carries through (mime/size/width/height/duration/name).
  */
 export function extractMediaFragments(fragments) {
     const out = [];

package/dist/src/mock-transport.js

@@ -0,0 +1,31 @@
+export class MockTransport {
+    handlers;
+    currentState = "closed";
+    sent = [];
+    get state() {
+        return this.currentState;
+    }
+    async connect(_url, handlers) {
+        this.handlers = handlers;
+        this.currentState = "open";
+        handlers.onOpen();
+    }
+    send(data) {
+        if (this.currentState !== "open") {
+            throw new Error("transport is not open");
+        }
+        this.sent.push(data);
+    }
+    close(code = 1000, reason = "client close") {
+        if (this.currentState === "closed")
+            return;
+        this.currentState = "closed";
+        this.handlers?.onClose(code, reason);
+    }
+    emitInbound(data) {
+        this.handlers?.onMessage(data);
+    }
+    emitError(err) {
+        this.handlers?.onError(err);
+    }
+}

package/dist/src/outbound.js

@@ -9,12 +9,6 @@ import { createAlignedWsQueue } from "./ws-alignment.js";
 import { formatWsLog } from "./ws-log.js";
 const alignedOutboundQueues = new WeakMap();
 const alignedOutboundContexts = new WeakMap();
-function getRawClientInternals(client) {
-    const raw = client;
-    if (!raw.opts?.transport || !raw.opts.traceIdFactory || !raw.on)
-        return null;
-    return raw;
-}
 function getAlignedOutboundQueue(client, account, log) {
     const existing = alignedOutboundQueues.get(client);
     if (existing)
@@ -36,21 +30,14 @@ export function setAlignedOutboundLogContext(client, context) {
     alignedOutboundContexts.set(client, context);
 }
 export function flushAlignedOutboundQueue(client) {
-    const raw = getRawClientInternals(client);
-    if (!raw?.opts?.transport)
-        return;
     const queue = alignedOutboundQueues.get(client);
-    queue?.flush((wire) => raw.opts.transport.send(wire));
+    queue?.flush((wire) => client.sendWire(wire));
 }
 export function getAlignedOutboundQueueSize(client) {
     return alignedOutboundQueues.get(client)?.snapshot().length ?? 0;
 }
 async function sendAlignedAckableEnvelope(params) {
-    const raw = getRawClientInternals(params.client);
-    if (!raw?.opts?.transport || !raw.opts.traceIdFactory)
-        return null;
-    const transport = raw.opts.transport;
-    const traceId = raw.opts.traceIdFactory();
+    const traceId = params.client.nextTraceId();
     const env = {
         version: "2",
         event: params.eventName,
@@ -61,15 +48,16 @@ async function sendAlignedAckableEnvelope(params) {
     };
     const wire = JSON.stringify(env);
     const queue = getAlignedOutboundQueue(params.client, params.account, params.log);
+    const isReady = () => {
+        const state = params.client.state;
+        return params.client.transportState === "open" && (!state || state === "connected");
+    };
     return await new Promise((resolve, reject) => {
         let timer;
         const cleanup = () => {
             if (timer)
                 clearTimeout(timer);
-            if (raw.off)
-                raw.off("raw", onRaw);
-            else
-                raw.removeListener?.("raw", onRaw);
+            params.client.off("raw", onRaw);
         };
         const logAck = (event, action, fields) => {
             params.log?.info?.(formatWsLog({
@@ -78,7 +66,7 @@ async function sendAlignedAckableEnvelope(params) {
                 ...(alignedOutboundContexts.get(params.client)?.() ?? {
                     attempt: 1,
                     reconnectCount: 0,
-                    state: transport.state === "open" ? "ready" : "reconnecting",
+                    state: isReady() ? "ready" : "reconnecting",
                 }),
                 action,
                 fields: [
@@ -98,7 +86,7 @@ async function sendAlignedAckableEnvelope(params) {
             resolve(ack);
         };
         const startAckTimer = () => {
-            raw.on?.("raw", onRaw);
+            params.client.on("raw", onRaw);
             timer = setTimeout(() => {
                 cleanup();
                 logAck("ack_timeout", "reject_no_reconnect", [["timeout_ms", params.account.ack.timeout]]);
@@ -111,18 +99,22 @@ async function sendAlignedAckableEnvelope(params) {
             chatId: params.chatId,
             wire,
             onWrite: startAckTimer,
+            onDrop: () => {
+                cleanup();
+                reject(new Error(`send queue full; dropped ${params.eventName} before write for trace_id=${traceId}`));
+            },
         };
-        if (transport.state !== "open") {
+        if (!isReady()) {
             queue.enqueue(item);
             return;
         }
         try {
             queue.enqueue(item);
-            queue.flush((queuedWire) => transport.send(queuedWire));
+            queue.flush((queuedWire) => params.client.sendWire(queuedWire));
         }
-        catch (err) {
-            cleanup();
-            reject(err);
+        catch {
+            // The queue keeps the failed frame at the head for reconnect retry, so
+            // keep this promise pending until the frame is written+acked, dropped, or timed out.
         }
     });
 }
@@ -185,8 +177,8 @@ export async function sendOpenclawClawlingText(params) {
     }
     const mentions = params.mentions ?? [];
     const textFragments = text ? textToFragments(text) : [];
-    // Cast at the SDK boundary: each MediaItem object is structurally compatible
-    // with one of the SDK's narrow Fragment members (ImageFragment / FileFragment /
+    // Each MediaItem object is structurally compatible
+    // with one of the local narrow Fragment members (ImageFragment / FileFragment /
     // AudioFragment / VideoFragment) based on its runtime `kind`. The wide local
     // shape lets us build a single uniform array without a per-kind switch.
     const fragments = [...textFragments, ...richFragments, ...mediaFragments];
@@ -212,24 +204,13 @@ export async function sendOpenclawClawlingText(params) {
                 },
             },
         };
-        ack = (await sendAlignedAckableEnvelope({
+        ack = await sendAlignedAckableEnvelope({
             client: params.client,
             account: params.account,
             eventName: "message.reply",
             chatId: params.to.chatId,
             payload,
             ...(params.log ? { log: params.log } : {}),
-        })) ?? await params.client.replyMessage({
-            chat_id: params.to.chatId,
-            mode: "normal",
-            replyTo: {
-                msgId: params.replyCtx.replyToMessageId,
-                senderId: params.replyCtx.replyPreviewSenderId,
-                nickName: params.replyCtx.replyPreviewNickName,
-                fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
-            },
-            body: { fragments },
-            context: { mentions },
         });
     }
     else {
@@ -241,18 +222,13 @@ export async function sendOpenclawClawlingText(params) {
                 context: { mentions, reply: null },
             },
         };
-        ack = (await sendAlignedAckableEnvelope({
+        ack = await sendAlignedAckableEnvelope({
             client: params.client,
             account: params.account,
             eventName: "message.send",
             chatId: params.to.chatId,
             payload,
             ...(params.log ? { log: params.log } : {}),
-        })) ?? await params.client.sendMessage({
-            chat_id: params.to.chatId,
-            mode: "normal",
-            body: { fragments },
-            context: { mentions, reply: null },
         });
     }
     params.log?.info?.(`[${params.account.accountId}] openclaw-clawchat outbound mode=${mode} msg=${ack.payload.message_id} text_len=${text.length} media=${mediaFragments.length} trace=${ack.trace_id}`);

package/dist/src/protocol-types.js

@@ -0,0 +1,49 @@
+export const EVENT = {
+    CONNECT_CHALLENGE: "connect.challenge",
+    CONNECT: "connect",
+    HELLO_OK: "hello-ok",
+    HELLO_FAIL: "hello-fail",
+    MESSAGE_SEND: "message.send",
+    MESSAGE_ACK: "message.ack",
+    MESSAGE_REPLY: "message.reply",
+    MESSAGE_CREATED: "message.created",
+    MESSAGE_ADD: "message.add",
+    MESSAGE_DONE: "message.done",
+    MESSAGE_FAILED: "message.failed",
+    TYPING_UPDATE: "typing.update",
+    OFFLINE_BATCH: "offline.batch",
+    OFFLINE_ACK: "offline.ack",
+    OFFLINE_DONE: "offline.done",
+    PING: "ping",
+    PONG: "pong",
+};
+export class AuthError extends Error {
+    name = "AuthError";
+}
+export class TransportError extends Error {
+    name = "TransportError";
+}
+export class ProtocolError extends Error {
+    envelope;
+    name = "ProtocolError";
+    constructor(message, envelope) {
+        super(message);
+        this.envelope = envelope;
+    }
+}
+export class AckTimeoutError extends Error {
+    traceId;
+    timeoutMs;
+    name = "AckTimeoutError";
+    constructor(traceId, timeoutMs) {
+        super(`ack timeout after ${timeoutMs}ms for trace_id=${traceId}`);
+        this.traceId = traceId;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class StateError extends Error {
+    name = "StateError";
+}
+export function isBusinessDispatchEvent(event) {
+    return event === EVENT.MESSAGE_SEND || event === EVENT.MESSAGE_REPLY || event === EVENT.MESSAGE_DONE;
+}

package/dist/src/protocol-types.typecheck.js

@@ -0,0 +1 @@
+export {};

package/dist/src/protocol.js

@@ -1,8 +1,8 @@
 /**
  * Local narrow guards for inbound protocol envelopes.
  *
- * The SDK's `message` event hands us `Envelope<unknown>`. Before casting the
- * payload to `DownlinkMessageSendPayload` we run these cheap structural checks
+ * Raw client events hand us `Envelope<unknown>`. Before casting the
+ * payload to `MessagePayload` we run these cheap structural checks
  * so runtime errors surface as skipped messages, not crashes.
  */
 export function isInboundMessagePayload(payload) {

package/dist/src/reply-dispatcher.js

@@ -253,7 +253,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
         const bodyFragments = [
             ...(mergedText ? textToFragments(mergedText) : []),
             ...finalRichFragments,
-            // mediaFragments is the local wide shape; cast at SDK boundary as
+            // mediaFragments is the local wide shape; cast to the local protocol fragment type as
             // we do in outbound.ts.
             ...mergedMedia,
         ];

package/dist/src/runtime.js

@@ -1,4 +1,4 @@
-import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, } from "@newbase-clawchat/sdk";
+import { AckTimeoutError, AuthError, ProtocolError, StateError, TransportError, } from "./protocol-types.js";
 import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 import { createOpenclawClawlingClient } from "./client.js";
@@ -354,7 +354,7 @@ export async function startOpenclawClawlingGateway(params) {
             log?.info?.(`[${accountId}] openclaw-clawchat state error: ${classified.message}`);
         }
         else {
-            log?.error?.(`[${accountId}] openclaw-clawchat sdk error: ${classified.message}`);
+            log?.error?.(`[${accountId}] openclaw-clawchat client error: ${classified.message}`);
         }
     });
     client.on("message", async (env) => {
@@ -477,8 +477,8 @@ export async function startOpenclawClawlingGateway(params) {
     });
     // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
     // (auth). Transport failures (server unreachable, DNS error, etc.) do
-    // NOT reject this promise — the SDK catches them internally and drives
-    // its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+    // NOT reject this promise — the local client handles them internally and
+    // drives its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
     // capped at `maxDelay`, with jitter). So we never throw here on anything
     // other than auth failure; on auth we tear the account down cleanly and
     // return without throwing (which would make the gateway supervisor

package/dist/src/ws-alignment.js

@@ -34,6 +34,7 @@ export function createAlignedWsQueue(options) {
                         ["queue_size", queue.length],
                         ["queue_max", maxSize],
                     ], context().state);
+                    dropped.onDrop?.();
                 }
             }
             queue.push(item);