@newbase-clawchat/openclaw-clawchat 2026.4.22 → 2026.4.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newbase-clawchat/openclaw-clawchat",
-  "version": "2026.4.22",
+  "version": "2026.4.23",
   "description": "OpenClaw ClawChat channel plugin",
   "files": [
     "index.ts",
@@ -12,8 +12,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck",
-    "release": "npm run prepublishOnly && npm publish",
-    "test-ui": "node ./tools/standalone-webchat-server.mjs"
+    "release": "npm run prepublishOnly && npm publish"
   },
   "dependencies": {
     "@newbase-clawchat/sdk": "^0.1.0",
@@ -46,11 +45,10 @@
       "docsPath": "/channels/openclaw-clawchat",
       "docsLabel": "openclaw-clawchat",
       "blurb":  "OpenClaw ClawChat channel plugin",
-      "order": 110
+      "order": 70
     },
     "install": {
       "npmSpec": "@newbase-clawchat/openclaw-clawchat",
-      "localPath": "extensions/openclaw-clawchat",
       "defaultChoice": "npm",
       "minHostVersion": ">=2026.3.23"
     }

package/src/channel.outbound.test.ts

@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const getClientMock = vi.hoisted(() => vi.fn());
 const getRuntimeMock = vi.hoisted(() => vi.fn());
+const waitForClientMock = vi.hoisted(() => vi.fn());
 const uploadOutboundMediaMock = vi.hoisted(() => vi.fn());
 const createApiClientMock = vi.hoisted(() => vi.fn());
 const sendTextMock = vi.hoisted(() => vi.fn());
@@ -10,6 +11,7 @@ const sendMediaMock = vi.hoisted(() => vi.fn());
 vi.mock("./runtime.ts", () => ({
   getOpenclawClawlingClient: getClientMock,
   getOpenclawClawlingRuntime: getRuntimeMock,
+  waitForOpenclawClawlingClient: waitForClientMock,
   startOpenclawClawlingGateway: vi.fn(),
 }));
 
@@ -31,12 +33,50 @@ describe("openclaw-clawchat channel outbound", () => {
     vi.resetModules();
     getClientMock.mockReset();
     getRuntimeMock.mockReset();
+    waitForClientMock.mockReset();
     uploadOutboundMediaMock.mockReset();
     createApiClientMock.mockReset();
     sendTextMock.mockReset();
     sendMediaMock.mockReset();
   });
 
+  it("sendText waits for client activation when no active client exists yet", async () => {
+    const client = { sendMessage: vi.fn() };
+    getClientMock.mockReturnValue(undefined);
+    waitForClientMock.mockResolvedValue(client);
+    sendTextMock.mockResolvedValue({ messageId: "m-2", acceptedAt: 456 });
+
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    const result = await openclawClawlingOutbound.sendText!({
+      cfg: {
+        channels: {
+          "openclaw-clawchat": {
+            enabled: true,
+            websocketUrl: "ws://t",
+            baseUrl: "https://api.example.com",
+            token: "tk",
+            userId: "agent-1",
+          },
+        },
+      } as never,
+      to: "cc:user-1",
+      text: "hello",
+    });
+
+    expect(waitForClientMock).toHaveBeenCalledWith("default");
+    expect(sendTextMock).toHaveBeenCalledWith({
+      client,
+      account: expect.objectContaining({ userId: "agent-1" }),
+      to: { chatId: "user-1", chatType: "direct" },
+      text: "hello",
+    });
+    expect(result).toEqual({
+      channel: "openclaw-clawchat",
+      to: "cc:user-1",
+      messageId: "m-2",
+    });
+  });
+
   it("sendMedia uploads mediaUrl and sends resulting fragments", async () => {
     const client = { sendMessage: vi.fn() };
     const runtime = { media: { loadWebMedia: vi.fn() } };
@@ -113,4 +153,51 @@ describe("openclaw-clawchat channel outbound", () => {
       }),
     ).rejects.toThrow(/requires mediaUrl/);
   });
+
+  it("sendMedia waits for client activation when no active client exists yet", async () => {
+    const client = { sendMessage: vi.fn() };
+    const runtime = { media: { loadWebMedia: vi.fn() } };
+    const apiClient = { uploadMedia: vi.fn() };
+    getClientMock.mockReturnValue(undefined);
+    waitForClientMock.mockResolvedValue(client);
+    getRuntimeMock.mockReturnValue(runtime);
+    createApiClientMock.mockReturnValue(apiClient);
+    uploadOutboundMediaMock.mockResolvedValue([
+      { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
+    ]);
+    sendMediaMock.mockResolvedValue({ messageId: "m-3", acceptedAt: 789 });
+
+    const { openclawClawlingOutbound } = await import("./outbound.ts");
+    const result = await openclawClawlingOutbound.sendMedia!({
+      cfg: {
+        channels: {
+          "openclaw-clawchat": {
+            enabled: true,
+            websocketUrl: "ws://t",
+            baseUrl: "https://api.example.com",
+            token: "tk",
+            userId: "agent-1",
+          },
+        },
+      } as never,
+      to: "cc:group:room-1",
+      text: "caption",
+      mediaUrl: "/tmp/photo.png",
+      mediaLocalRoots: ["/tmp"],
+    });
+
+    expect(waitForClientMock).toHaveBeenCalledWith("default");
+    expect(sendMediaMock).toHaveBeenCalledWith({
+      client,
+      account: expect.objectContaining({ userId: "agent-1", baseUrl: "https://api.example.com" }),
+      to: { chatId: "room-1", chatType: "group" },
+      text: "caption",
+      mediaFragments: [{ kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" }],
+    });
+    expect(result).toEqual({
+      channel: "openclaw-clawchat",
+      to: "cc:group:room-1",
+      messageId: "m-3",
+    });
+  });
 });

package/src/outbound.ts

@@ -9,7 +9,11 @@ import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { CHANNEL_ID, resolveOpenclawClawlingAccount, type ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { textToFragments } from "./message-mapper.ts";
 import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
-import { getOpenclawClawlingClient, getOpenclawClawlingRuntime } from "./runtime.ts";
+import {
+  getOpenclawClawlingClient,
+  getOpenclawClawlingRuntime,
+  waitForOpenclawClawlingClient,
+} from "./runtime.ts";
 
 export interface OutboundTarget {
   chatId: string;
@@ -198,10 +202,9 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
     channel: CHANNEL_ID,
     sendText: async ({ cfg, to, text }) => {
       const account = resolveOpenclawClawlingAccount(cfg);
-      const client = getOpenclawClawlingClient(account.accountId);
-      if (!client) {
-        throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
-      }
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
       const result = await sendOpenclawClawlingText({
         client,
         account,
@@ -215,10 +218,9 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
     },
     sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
       const account = resolveOpenclawClawlingAccount(cfg);
-      const client = getOpenclawClawlingClient(account.accountId);
-      if (!client) {
-        throw new Error(`openclaw-clawchat client not running for account ${account.accountId}`);
-      }
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
       if (!mediaUrl?.trim()) {
         throw new Error("openclaw-clawchat sendMedia requires mediaUrl");
       }

package/src/reply-dispatcher.test.ts

@@ -0,0 +1,252 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
+
+describe("openclaw-clawchat reply-dispatcher", () => {
+  it("emits message.failed in stream mode even if execution errors before any stream chunk", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+          onIdle?: () => Promise<void>;
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
+    const client = {
+      opts: {
+        transport: {
+          send: (data: string) => {
+            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
+            sent.push({ event: env.event, payload: env.payload });
+          },
+        },
+        traceIdFactory: () => "trace-1",
+      },
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "stream",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.event).toBe("message.failed");
+    expect(sent[0]!.payload.reason).toBe("Error: boom");
+    expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
+      ["chat-1", false, "direct"],
+    ]);
+  });
+
+  it("does not emit consolidated final after a streaming failure", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+          onIdle?: () => Promise<void>;
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
+    const client = {
+      opts: {
+        transport: {
+          send: (data: string) => {
+            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
+            sent.push({ event: env.event, payload: env.payload });
+          },
+        },
+        traceIdFactory: () => "trace-2",
+      },
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "stream",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 1, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await hooks?.deliver?.({ text: "partial reply" }, { kind: "block" });
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await hooks?.onIdle?.();
+
+    expect(sent.map((entry) => entry.event)).toEqual([
+      "message.created",
+      "message.add",
+      "message.failed",
+    ]);
+    expect(sent.find((entry) => entry.event === "message.reply")).toBeUndefined();
+    expect(sent.find((entry) => entry.event === "message.done")).toBeUndefined();
+  });
+
+  it("sends static error text when non-streaming reply execution fails", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const client = {
+      sendMessage: vi.fn().mockResolvedValue({
+        payload: { message_id: "server-m1", accepted_at: 1234 },
+      }),
+      replyMessage: vi.fn(),
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: { id: "chat-1", type: "direct" },
+        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
+      }),
+    );
+    expect(client.replyMessage).not.toHaveBeenCalled();
+  });
+
+  it("strips delivery retry wrapper text before sending non-streaming errors", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const client = {
+      sendMessage: vi.fn().mockResolvedValue({
+        payload: { message_id: "server-m1", accepted_at: 1234 },
+      }),
+      replyMessage: vi.fn(),
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(
+      new Error("Retry failed for delivery 123: Error: boom"),
+      { kind: "dispatch" },
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: { id: "chat-1", type: "direct" },
+        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
+      }),
+    );
+  });
+});

package/src/reply-dispatcher.ts

@@ -13,6 +13,7 @@ import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { textToFragments } from "./message-mapper.ts";
 import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
 import { sendOpenclawClawlingText, type OutboundReplyCtx } from "./outbound.ts";
+import { sendStreamingFailure } from "./streaming.ts";
 
 export interface ReplyDispatcherOptions {
   cfg: OpenClawConfig;
@@ -54,6 +55,15 @@ type StreamingReplyHooks = {
   onReasoningStream?: (payload: ReplyPayload) => Promise<void>;
 };
 
+function normalizeReplyErrorText(error: unknown): string {
+  const raw = String(error);
+  const retryWrapped = raw.match(/^Error: Retry failed for delivery [^:]+:\s*(.+)$/s);
+  if (retryWrapped?.[1]?.trim()) return retryWrapped[1].trim();
+  const retryWrappedBare = raw.match(/^Retry failed for delivery [^:]+:\s*(.+)$/s);
+  if (retryWrappedBare?.[1]?.trim()) return retryWrappedBare[1].trim();
+  return raw;
+}
+
 /**
  * Reply dispatcher for openclaw-clawchat.
  *
@@ -126,6 +136,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   const accumulatedMediaUrls: string[] = [];
   let finalEmitted = false;
   let streamingClosed = false;
+  let runFailed = false;
   let runDone = false;
   // `streamCreatedEmitted` is the authoritative guard: once a `message.created`
   // has been emitted for this dispatcher instance, never emit another — even
@@ -133,6 +144,9 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   // raced the lazy open path.
   let streamCreatedEmitted = false;
 
+  const mintStreamingMessageId = () =>
+    `${account.userId}-stream-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
   const openSessionIfNeeded = () => {
     if (!streamingEnabled || streamingSession || streamCreatedEmitted) return;
     streamCreatedEmitted = true;
@@ -143,7 +157,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     // which mints its own id. The inbound user message_id lives on
     // `replyTo.msgId`; keeping the two distinct avoids the agent's reply
     // frames shadowing the user turn they answer.
-    streamingMessageId = `${account.userId}-stream-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    streamingMessageId = mintStreamingMessageId();
     streamingSession = openBufferedStreamingSession({
       client,
       routing,
@@ -352,15 +366,35 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       }
     },
     onError: (error: unknown, info: { kind: string }) => {
+      const errorText = normalizeReplyErrorText(error);
       log?.error?.(
-        `[${account.accountId}] openclaw-clawchat ${info.kind} reply failed: ${String(error)}`,
+        `[${account.accountId}] openclaw-clawchat ${info.kind} reply failed: ${errorText}`,
       );
-      void closeStreamingSession("fail", String(error));
+      if (!streamingEnabled) {
+        void sendStatic(errorText);
+        return;
+      }
+      runFailed = true;
+      if (streamingSession && !streamingClosed) {
+        void closeStreamingSession("fail", errorText);
+        return;
+      }
+      if (streamingClosed) return;
+      streamingClosed = true;
+      if (!streamingMessageId) streamingMessageId = mintStreamingMessageId();
+      void sendStreamingFailure({
+        client,
+        routing,
+        messageId: streamingMessageId,
+        currentSequence: 0,
+        reason: errorText,
+      });
     },
     onIdle: async () => {
       if (runDone) return;
       runDone = true;
       if (!streamingEnabled) return;
+      if (runFailed) return;
       await closeStreamingSession("done");
       await emitFinalConsolidatedMessage();
     },

package/src/runtime.test.ts

@@ -349,6 +349,156 @@ describe("openclaw-clawchat runtime media ingest", () => {
   });
 });
 
+describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
+  it("marks dispatch idle when reply dispatch fails", async () => {
+    const markDispatchIdle = vi.fn();
+    const withReplyDispatcher = vi.fn(
+      async (opts: { run: () => Promise<unknown>; onSettled?: () => void | Promise<void> }) => {
+        try {
+          await opts.run();
+        } finally {
+          await opts.onSettled?.();
+        }
+      },
+    );
+    const dispatchReplyFromConfig = vi.fn().mockRejectedValue(new Error("dispatch boom"));
+    const logError = vi.fn();
+
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle,
+          })),
+          withReplyDispatcher,
+          dispatchReplyFromConfig,
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: vi.fn(), error: logError },
+      transport,
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "tc",
+        emitted_at: Date.now(),
+        payload: { nonce: "n" },
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: "th",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "tm",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+        payload: {
+          message_id: "m-fail",
+          message_mode: "normal",
+          message: {
+            body: {
+              fragments: [{ kind: "text", text: "hello" }],
+            },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+
+    await new Promise((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(markDispatchIdle).toHaveBeenCalledTimes(1);
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining("openclaw-clawchat message handler error:"),
+    );
+  });
+});
+
 describe("openclaw-clawchat runtime connect flow", () => {
   it("completes connect through MockTransport handshake", async () => {
     const { startOpenclawClawlingGateway } = await import("./runtime.ts");

package/src/runtime.ts

@@ -19,6 +19,7 @@ import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
 import { fetchInboundMedia } from "./media-runtime.ts";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 import { sendStreamingText } from "./streaming.ts";
+import { sendOpenclawClawlingText } from "./outbound.ts";
 
 type Log = { info?: (m: string) => void; error?: (m: string) => void };
 
@@ -33,6 +34,28 @@ export function getOpenclawClawlingClient(accountId: string): ClawlingChatClient
   return activeClients.get(accountId);
 }
 
+export async function waitForOpenclawClawlingClient(
+  accountId: string,
+  options: { timeoutMs?: number; pollMs?: number } = {},
+): Promise<ClawlingChatClient> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const pollMs = options.pollMs ?? 100;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const client = activeClients.get(accountId);
+    if (client && (client as { state?: string }).state === "connected") {
+      return client;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `openclaw-clawchat client did not activate within ${timeoutMs}ms for account ${accountId}`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
 export type ClawlingState =
   | "idle"
   | "connecting"
@@ -138,8 +161,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
   });
 
-  client.on("message", (env: Envelope) => {
-    dispatchOpenclawClawlingInbound({
+  client.on("message", async (env: Envelope) => {
+    try {
+      await dispatchOpenclawClawlingInbound({
       envelope: env as Envelope<DownlinkMessageSendPayload>,
       cfg,
       runtime,
@@ -238,14 +262,14 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         log?.info?.(
           `[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
         );
-        const dispatchResult = await rt.reply.withReplyDispatcher({
-          dispatcher,
-          onSettled: () => markDispatchIdle(),
-          run: () =>
-            rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
-        });
+        
         try {
-          
+          const dispatchResult = await rt.reply.withReplyDispatcher({
+            dispatcher,
+            onSettled: () => markDispatchIdle(),
+            run: () =>
+              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+          });
           const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
           const queuedFinal = Boolean(
             (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
@@ -264,14 +288,24 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           log?.error?.(
             `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
           );
-          throw err;
+          await sendOpenclawClawlingText({
+            client,
+            account: turn.account,
+            to: {
+              chatId: turn.peer.id,
+              chatType: turn.peer.kind === "group" ? "group" : "direct",
+            },
+            text: String(err),
+            ...(turn.replyCtx ? { replyCtx: turn.replyCtx } : {}),
+          });
         }
       },
-    }).catch((err) => {
+      })
+    } catch (err) {
       log?.error?.(
-        `[${accountId}] openclaw-clawchat inbound dispatch error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
+        `[${accountId}] openclaw-clawchat message handler error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
       );
-    });
+    }
   });
 
   // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`