@newbase-clawchat/openclaw-clawchat 2026.5.4-1 → 2026.5.4-2

package/README.md

@@ -21,7 +21,8 @@ npm i @newbase-clawchat/openclaw-clawchat
 
 Requires `openclaw >= 2026.5.4` as a peer host.
 
-For the OpenClaw plugin install/update flow, see [`INSTALL.md`](./INSTALL.md).
+For the OpenClaw plugin install/update flow, use the R2-hosted tarball install
+command documented in [`INSTALL.md`](./INSTALL.md).
 
 Example LLM prompt:
 
@@ -176,6 +177,38 @@ npm run dev:openclaw-source
 This checkout is local-only. It is ignored by git and is not required to run the
 plugin tests or publish the package.
 
+## R2 package scripts
+
+Create and upload the OpenClaw plugin tarball to the R2 `openclaw/` prefix:
+
+```bash
+./package_openclaw_plugin.sh
+```
+
+The script runs `npm pack`, uploads the generated `.tgz` to the configured R2
+bucket, and prints the public URL. R2 credentials are read from `.env.r2`, which
+is ignored by git. Use `--no-upload` to build the tarball without uploading it.
+
+```bash
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_DEFAULT_REGION=auto
+R2_ENDPOINT=https://...
+R2_BUCKET=...
+```
+
+Install the R2-hosted tarball on a device or container with OpenClaw available:
+
+```bash
+./install_openclaw.sh
+```
+
+To install a specific uploaded tarball, pass its URL explicitly:
+
+```bash
+./install_openclaw.sh https://dddddddddddddtest.clawling.chat/openclaw/newbase-clawchat-openclaw-clawchat-2026.5.4-2.tgz
+```
+
 ## License
 
 See the repository root.

package/dist/src/channel.js

@@ -1,6 +1,6 @@
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
 import { createEmptyChannelDirectoryAdapter } from "openclaw/plugin-sdk/directory-runtime";
-import { resolveOpenclawClawlingAccount, } from "./config.js";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount, } from "./config.js";
 import { openclawClawlingOutbound } from "./outbound.js";
 import { getOpenclawClawlingRuntime, startOpenclawClawlingGateway } from "./runtime.js";
 import { openclawClawlingSetupPlugin } from "./channel.setup.js";
@@ -53,6 +53,7 @@ export const openclawClawlingPlugin = createChatChannelPlugin({
             ],
         },
         messaging: {
+            targetPrefixes: ["cc", "clawchat", CHANNEL_ID],
             normalizeTarget: (target) => target
                 .trim()
                 .replace(/^openclaw-clawchat:/i, "")

package/dist/src/client.js

@@ -44,12 +44,19 @@ function normalizeRouting(params) {
  * Emit a raw v2 envelope directly over the transport so we can carry top-level
  * `chat_id` routing without SDK-injected `to` metadata.
  */
-function emitEnvelope(client, event, payload, routing) {
+function emitEnvelope(client, event, payload, routing, options = {}) {
     const inner = client;
-    if (!inner.opts?.transport) {
-        inner.emitRaw?.(event, payload, { to: { id: routing.chatId, type: routing.chatType } });
+    if (!options.forceRawTransport && inner.emitRaw) {
+        inner.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");
+    }
     const env = {
         version: "2",
         event,
@@ -150,7 +157,7 @@ export function emitFinalStreamReply(client, params) {
                 },
             },
         },
-    }, routing);
+    }, routing, { forceRawTransport: true });
 }
 export function emitStreamFailed(client, params) {
     const now = Date.now();

package/dist/src/media-runtime.js

@@ -1,3 +1,4 @@
+import { buildOutboundMediaLoadOptions, } from "openclaw/plugin-sdk/media-runtime";
 export function inferMediaKindFromMime(mime) {
     if (!mime)
         return "file";
@@ -56,12 +57,12 @@ export async function uploadOutboundMedia(urls, ctx) {
     const out = [];
     for (const url of urls) {
         try {
-            const loaded = await ctx.runtime.media.loadWebMedia(url, {
+            const loaded = await ctx.runtime.media.loadWebMedia(url, buildOutboundMediaLoadOptions({
                 maxBytes,
-                ...(ctx.mediaLocalRoots && ctx.mediaLocalRoots.length > 0
-                    ? { localRoots: ctx.mediaLocalRoots }
-                    : {}),
-            });
+                ...(ctx.mediaAccess ? { mediaAccess: ctx.mediaAccess } : {}),
+                ...(ctx.mediaLocalRoots ? { mediaLocalRoots: ctx.mediaLocalRoots } : {}),
+                ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
+            }));
             const uploaded = await ctx.apiClient.uploadMedia({
                 buffer: loaded.buffer,
                 filename: loaded.fileName ?? "upload.bin",

package/dist/src/outbound.js

@@ -19,6 +19,8 @@ import { getOpenclawClawlingClient, getOpenclawClawlingRuntime, waitForOpenclawC
  *   - `clawchat:group:{chat_id}`      → group
  *   - `openclaw-clawchat:direct:{chat_id}` → direct
  *   - `openclaw-clawchat:group:{chat_id}`  → group
+ *   - `direct:{chat_id}`              → direct (host-normalized)
+ *   - `group:{chat_id}`               → group (host-normalized)
  *   - bare `{chat_id}`                → direct (backward compat)
  */
 export function parseOpenclawRecipient(to) {
@@ -30,6 +32,12 @@ export function parseOpenclawRecipient(to) {
         return { chatId: raw, chatType: "direct" };
     const scheme = raw.slice(0, firstColon).toLowerCase();
     const rest = raw.slice(firstColon + 1);
+    if (scheme === "direct" || scheme === "group") {
+        const chatId = rest.trim();
+        if (!chatId)
+            throw new Error(`openclaw-clawchat: missing chat_id in "${to}"`);
+        return { chatId, chatType: scheme };
+    }
     if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
         return { chatId: raw, chatType: "direct" };
     }
@@ -74,7 +82,7 @@ export async function sendOpenclawClawlingText(params) {
             mode: "normal",
             replyTo: {
                 msgId: params.replyCtx.replyToMessageId,
-                senderId: params.replyCtx.replyPreviewChatId ?? params.replyCtx.replyPreviewSenderId,
+                senderId: params.replyCtx.replyPreviewSenderId,
                 nickName: params.replyCtx.replyPreviewNickName,
                 fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
             },
@@ -144,7 +152,7 @@ export const openclawClawlingOutbound = {
                 messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
             };
         },
-        sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+        sendMedia: async ({ cfg, to, text, mediaUrl, mediaAccess, mediaLocalRoots, mediaReadFile }) => {
             const account = resolveOpenclawClawlingAccount(cfg);
             const client = getOpenclawClawlingClient(account.accountId) ??
                 (await waitForOpenclawClawlingClient(account.accountId));
@@ -160,7 +168,9 @@ export const openclawClawlingOutbound = {
             const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
                 apiClient,
                 runtime,
+                ...(mediaAccess ? { mediaAccess } : {}),
                 ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+                ...(mediaReadFile ? { mediaReadFile } : {}),
             });
             if (mediaFragments.length === 0) {
                 throw new Error(`openclaw-clawchat failed to upload media: ${mediaUrl}`);

package/dist/src/reply-dispatcher.js

@@ -1,4 +1,5 @@
 import { interactiveReplyToPresentation, renderMessagePresentationFallbackText, } from "openclaw/plugin-sdk/interactive-runtime";
+import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { openBufferedStreamingSession, mergeStreamingText, } from "./buffered-stream.js";
 import { emitFinalStreamReply } from "./client.js";
@@ -256,7 +257,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
             routing,
             replyTo: {
                 msgId: inboundMessageId ?? streamingMessageId,
-                previewId: inboundForFinalReply?.chatId ?? target.chatId,
+                previewId: inboundForFinalReply?.senderId ?? target.chatId,
                 nickName: inboundForFinalReply?.senderNickName ?? inboundForFinalReply?.senderId ?? target.chatId,
                 fragments: inboundForFinalReply?.bodyText
                     ? [{ kind: "text", text: inboundForFinalReply.bodyText }]
@@ -271,10 +272,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
         }
         if (text)
             streamText = mergeStreamingText(streamText, text);
-        const urls = [
-            ...(payload.mediaUrl ? [payload.mediaUrl] : []),
-            ...(payload.mediaUrls ?? []),
-        ].filter((u) => Boolean(u));
+        const urls = resolveOutboundMediaUrls(payload).filter(Boolean);
         for (const url of urls) {
             if (!accumulatedMediaUrls.includes(url))
                 accumulatedMediaUrls.push(url);
@@ -313,10 +311,7 @@ export function createOpenclawClawlingReplyDispatcher(options) {
         deliver: async (payload, info) => {
             const richFragment = buildRichInteractionFragment(payload);
             const text = richFragment && account.richInteractions ? "" : resolvePayloadText(payload);
-            const urls = [
-                ...(payload.mediaUrl ? [payload.mediaUrl] : []),
-                ...(payload.mediaUrls ?? []),
-            ].filter((u) => Boolean(u));
+            const urls = resolveOutboundMediaUrls(payload).filter(Boolean);
             log?.info?.(`[${account.accountId}] openclaw-clawchat deliver kind=${info?.kind ?? "unknown"} text_len=${text.length} media_urls=${urls.length} reasoning=${payload.isReasoning === true}`);
             if (payload.isReasoning) {
                 if (!account.forwardThinking)

package/dist/src/runtime.js

@@ -140,16 +140,16 @@ export async function startOpenclawClawlingGateway(params) {
                         timestamp: turn.timestamp,
                         ...rt.reply.resolveEnvelopeFormatOptions(cfg),
                     });
+                    const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
                     const ctxPayload = rt.reply.finalizeInboundContext({
                         Body: body,
                         BodyForAgent: turn.rawBody,
                         RawBody: turn.rawBody,
                         CommandBody: turn.rawBody,
-                        // Clawling v2 routes by chat_id. `senderId` is still preserved as
-                        // structured metadata, but the conversation target must be based on
-                        // `peer.id` so follow-up sends address the active chat, not merely
-                        // the human sender identity.
-                        From: `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`,
+                        // Clawling v2 routes by chat_id. `OriginatingTo` is what the
+                        // message tool uses as the implicit current-chat target, so keep it
+                        // on the conversation id rather than the agent account user id.
+                        From: conversationTarget,
                         To: `${CHANNEL_ID}:${account.userId}`,
                         SessionKey: route.sessionKey,
                         AccountId: route.accountId ?? accountId,
@@ -162,7 +162,7 @@ export async function startOpenclawClawlingGateway(params) {
                         MessageSidFull: turn.messageId,
                         Timestamp: turn.timestamp,
                         OriginatingChannel: CHANNEL_ID,
-                        OriginatingTo: `${CHANNEL_ID}:${account.userId}`,
+                        OriginatingTo: conversationTarget,
                     });
                     // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
                     const inboundPaths = turn.mediaItems.length > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newbase-clawchat/openclaw-clawchat",
-  "version": "2026.5.4-1",
+  "version": "2026.5.4-2",
   "description": "OpenClaw ClawChat channel plugin",
   "files": [
     "dist",

package/src/channel.outbound.test.ts

@@ -88,6 +88,8 @@ describe("openclaw-clawchat channel outbound", () => {
     uploadOutboundMediaMock.mockResolvedValue([
       { kind: "image", url: "https://cdn/uploaded.png", mime: "image/png" },
     ]);
+    const mediaReadFile = vi.fn(async () => Buffer.from("host-read"));
+    const mediaAccess = { localRoots: ["/tmp"], workspaceDir: "/workspace" };
 
     const { openclawClawlingOutbound } = await import("./outbound.ts");
     const result = await openclawClawlingOutbound.sendMedia!({
@@ -105,7 +107,9 @@ describe("openclaw-clawchat channel outbound", () => {
       to: "cc:group:room-1",
       text: "caption",
       mediaUrl: "/tmp/photo.png",
+      mediaAccess,
       mediaLocalRoots: ["/tmp"],
+      mediaReadFile,
     });
 
     expect(createApiClientMock).toHaveBeenCalledWith({
@@ -116,7 +120,9 @@ describe("openclaw-clawchat channel outbound", () => {
     expect(uploadOutboundMediaMock).toHaveBeenCalledWith(["/tmp/photo.png"], {
       apiClient,
       runtime,
+      mediaAccess,
       mediaLocalRoots: ["/tmp"],
+      mediaReadFile,
     });
     expect(client.sendMessage).toHaveBeenCalledWith(
       expect.objectContaining({

package/src/channel.test.ts

@@ -123,10 +123,32 @@ describe("openclaw-clawchat plugin", () => {
     expect(normalized).toBe("usr_01KPN6SQFQEGM9HR11CHRHPMMT");
   });
 
+  it("declares ClawChat target prefixes for OpenClaw channel selection", () => {
+    expect(openclawClawlingPlugin.messaging?.targetPrefixes).toEqual([
+      "cc",
+      "clawchat",
+      "openclaw-clawchat",
+    ]);
+  });
+
   it("parses openclaw-clawchat target prefix as a direct recipient", () => {
     expect(parseOpenclawRecipient("openclaw-clawchat:usr_01KPN6SQFQEGM9HR11CHRHPMMT")).toEqual({
       chatId: "usr_01KPN6SQFQEGM9HR11CHRHPMMT",
       chatType: "direct",
     });
   });
+
+  it("parses host-normalized group targets as group recipients", () => {
+    expect(parseOpenclawRecipient("group:cnv_01KR2NBGTKEQ0S0CAYCEQP3YPW")).toEqual({
+      chatId: "cnv_01KR2NBGTKEQ0S0CAYCEQP3YPW",
+      chatType: "group",
+    });
+  });
+
+  it("parses host-normalized direct targets as direct recipients", () => {
+    expect(parseOpenclawRecipient("direct:cnv_01KR2NBGTKEQ0S0CAYCEQP3YPW")).toEqual({
+      chatId: "cnv_01KR2NBGTKEQ0S0CAYCEQP3YPW",
+      chatType: "direct",
+    });
+  });
 });

package/src/channel.ts

@@ -67,6 +67,7 @@ export const openclawClawlingPlugin: ChannelPlugin<ResolvedOpenclawClawlingAccou
         ],
       },
       messaging: {
+        targetPrefixes: ["cc", "clawchat", CHANNEL_ID],
         normalizeTarget: (target) =>
           target
             .trim()

package/src/client.test.ts

@@ -1,12 +1,13 @@
-import { MockTransport } from "@newbase-clawchat/sdk";
+import { MockTransport, type ClawlingChatClient } from "@newbase-clawchat/sdk";
 import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/setup";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   createOpenclawClawlingClient,
   emitStreamCreated,
   emitStreamAdd,
   emitStreamDone,
   emitStreamFailed,
+  emitFinalStreamReply,
 } from "./client.ts";
 import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 
@@ -100,6 +101,66 @@ describe("openclaw-clawchat client", () => {
     client.close();
   });
 
+  it("uses SDK emitRaw with chat_id routing for stream lifecycle frames", () => {
+    const transportSend = vi.fn();
+    const emitRaw = vi.fn();
+    const client = {
+      opts: {
+        transport: { send: transportSend },
+        traceIdFactory: () => "trace-raw",
+      },
+      emitRaw,
+    } as unknown as ClawlingChatClient;
+
+    emitStreamCreated(client, {
+      messageId: "msg-1",
+      routing: { chatId: "chat-1", chatType: "group" },
+    });
+
+    expect(emitRaw).toHaveBeenCalledWith(
+      "message.created",
+      { message_id: "msg-1" },
+      { chat_id: "chat-1" },
+    );
+    expect(transportSend).not.toHaveBeenCalled();
+  });
+
+  it("falls back to SDK emitRaw with chat_id routing when raw transport is unavailable", () => {
+    const emitRaw = vi.fn();
+    const client = { emitRaw } as unknown as ClawlingChatClient;
+
+    emitStreamCreated(client, {
+      messageId: "msg-1",
+      routing: { chatId: "chat-1", chatType: "direct" },
+    });
+
+    expect(emitRaw).toHaveBeenCalledWith(
+      "message.created",
+      { message_id: "msg-1" },
+      { chat_id: "chat-1" },
+    );
+  });
+
+  it("requires raw transport for final stream replies that carry a client message_id", () => {
+    const emitRaw = vi.fn();
+    const client = { emitRaw } as unknown as ClawlingChatClient;
+
+    expect(() =>
+      emitFinalStreamReply(client, {
+        messageId: "agent-stream-1",
+        routing: { chatId: "chat-1", chatType: "direct" },
+        replyTo: {
+          msgId: "user-msg-1",
+          previewId: "user-1",
+          nickName: "User 1",
+          fragments: [{ kind: "text", text: "hello" }],
+        },
+        body: { fragments: [{ kind: "text", text: "reply" }] },
+      }),
+    ).toThrow(/raw transport/);
+    expect(emitRaw).not.toHaveBeenCalled();
+  });
+
   it("emitStreamAdd emits message.add with fragments: [{ text: full, delta: new }]", async () => {
     const transport = new MockTransport();
     const client = createOpenclawClawlingClient(baseAccount(), { transport });

package/src/client.ts

@@ -84,18 +84,26 @@ function emitEnvelope(
   event: string,
   payload: object,
   routing: EnvelopeRouting,
+  options: { forceRawTransport?: boolean } = {},
 ): void {
   const inner = client as unknown as {
     opts?: {
       transport: { send: (data: string) => void };
       traceIdFactory: () => string;
     };
-    emitRaw?: (event: string, payload: object, routing?: { to?: { id: string; type: ChatType } }) => void;
+    emitRaw?: (event: string, payload: object, routing?: { chat_id?: string; chat_type?: ChatType }) => void;
   };
-  if (!inner.opts?.transport) {
-    inner.emitRaw?.(event, payload, { to: { id: routing.chatId, type: routing.chatType } });
+  if (!options.forceRawTransport && inner.emitRaw) {
+    inner.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");
+  }
   const env = {
     version: "2" as const,
     event,
@@ -265,6 +273,7 @@ export function emitFinalStreamReply(
       },
     },
     routing,
+    { forceRawTransport: true },
   );
 }
 

package/src/manifest.test.ts

@@ -248,51 +248,41 @@ describe("openclaw-clawchat manifest", () => {
     expect(docs).toMatch(/Natural-language activation requests should call `clawchat_activate`/i);
   });
 
-  it("documents gateway restart as the required next step after plugin install or update", () => {
+  it("documents the numbered install restart step", () => {
     const install = fs.readFileSync(new URL("../INSTALL.md", import.meta.url), "utf8");
-    const restart = install.indexOf("## Restart the Gateway");
-    const activate = install.indexOf("## Activate");
+    const restart = install.indexOf("## 3. Restart");
+    const activate = install.indexOf("## 4. Activate");
     const installSection = install.slice(restart, activate);
 
-    expect(installSection).toMatch(/perform a\s+real OpenClaw Gateway restart/i);
-    expect(installSection).toMatch(/Do not rely on hot reload or channel reload/i);
     expect(installSection).toMatch(/openclaw gateway restart/);
-    expect(installSection).toMatch(/inside an OpenClaw chat\/agent turn/i);
-    expect(installSection).toMatch(/send a new message to continue/i);
+    expect(installSection).toMatch(/First restart completed/);
     expect(installSection).not.toMatch(/kill -TERM 1/);
     expect(installSection).not.toMatch(/docker restart <container>/);
-    expect(installSection).not.toMatch(/runtime imports the plugin/i);
-    expect(installSection).not.toMatch(/If the Gateway is already running/i);
   });
 
-  it("documents activation after restart through runtime tools before channels-add CLI", () => {
+  it("documents numbered CLI activation, second restart, and verification", () => {
     const install = fs.readFileSync(new URL("../INSTALL.md", import.meta.url), "utf8");
-    const activate = install.indexOf("## Activate");
-    const restartAgain = install.indexOf("## Restart Again");
-    const verify = install.indexOf("## Verify");
+    const activate = install.indexOf("## 4. Activate");
+    const restartAgain = install.indexOf("## 5. Restart Again");
+    const verify = install.indexOf("## 6. Verify");
     const activateSection = install.slice(activate, restartAgain);
 
-    expect(activateSection).toMatch(/After the Gateway has restarted and is reachable/i);
-    expect(activateSection).toMatch(/clawchat_activate/);
-    expect(activateSection).toMatch(/\/clawchat-login XXXXXX/);
     expect(activateSection).toMatch(/openclaw channels add --channel openclaw-clawchat --token "\$CLAWCHAT_INVITE_CODE"/);
-    expect(activateSection).toMatch(/Do not use `openclaw channels login --channel openclaw-clawchat` for first-time\s+activation/i);
-    expect(activateSection).not.toMatch(/OpenClaw 2026\.5\.5/i);
-    expect(activateSection).not.toMatch(/Unknown channel: openclaw-clawchat/i);
+    expect(activateSection).toMatch(/Activation completed/);
     expect(activateSection).not.toMatch(/openclaw channels status --probe/i);
-    expect(activateSection).not.toMatch(/verify the channel/i);
 
     const restartAgainSection = install.slice(
       restartAgain,
-      install.indexOf("## Verify"),
+      verify,
     );
-    expect(restartAgainSection).toMatch(/After activation succeeds/i);
-    expect(restartAgainSection).toMatch(/one more real Gateway restart/i);
     expect(restartAgainSection).toMatch(/openclaw gateway restart/i);
+    expect(restartAgainSection).toMatch(/Second restart completed/);
 
     const verifySection = install.slice(verify);
+    expect(verifySection).toMatch(/sleep 5/);
     expect(verifySection).toMatch(/openclaw channels status --probe/i);
+    expect(verifySection).toMatch(/Verification completed/);
     expect(verifySection).toMatch(/enabled, configured, running, and\s+connected/i);
-    expect(verifySection).toMatch(/startAccount invoked/i);
+    expect(verifySection).toMatch(/installation flow is complete/i);
   });
 });

package/src/media-runtime.test.ts

@@ -130,6 +130,32 @@ describe("uploadOutboundMedia", () => {
     ]);
   });
 
+  it("passes host media access options to loadWebMedia", async () => {
+    const { runtime, loadWebMedia } = buildRuntime();
+    const apiClient = buildApiClient();
+    const readFile = vi.fn(async () => Buffer.from("host-read"));
+
+    await uploadOutboundMedia(["relative/image.png"], {
+      apiClient,
+      runtime,
+      mediaAccess: {
+        localRoots: ["/workspace"],
+        readFile,
+        workspaceDir: "/workspace",
+      },
+    });
+
+    expect(loadWebMedia).toHaveBeenCalledWith(
+      "relative/image.png",
+      expect.objectContaining({
+        localRoots: ["/workspace"],
+        readFile,
+        hostReadCapability: true,
+        workspaceDir: "/workspace",
+      }),
+    );
+  });
+
   it("drops a single failed upload, returns the rest", async () => {
     const { runtime } = buildRuntime();
     const apiClient = buildApiClient();

package/src/media-runtime.ts

@@ -1,4 +1,9 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk/core";
+import {
+  buildOutboundMediaLoadOptions,
+  type OutboundMediaAccess,
+  type OutboundMediaReadFile,
+} from "openclaw/plugin-sdk/media-runtime";
 import type { OpenclawClawlingApiClient } from "./api-client.ts";
 
 /**
@@ -42,8 +47,12 @@ export interface UploadOutboundCtx {
   runtime: PluginRuntime;
   log?: LogSink;
   maxBytes?: number;
+  /** Host-authorized outbound media access from OpenClaw message delivery. */
+  mediaAccess?: OutboundMediaAccess;
   /** Allowed local roots for path-based uploads. Empty/undefined = use loadWebMedia defaults. */
-  mediaLocalRoots?: readonly string[];
+  mediaLocalRoots?: readonly string[] | "any";
+  /** Host-provided read bridge for sandbox/allowed local media paths. */
+  mediaReadFile?: OutboundMediaReadFile;
 }
 
 export function inferMediaKindFromMime(mime: string | undefined): MediaItem["kind"] {
@@ -114,12 +123,15 @@ export async function uploadOutboundMedia(
   const out: ClawlingMediaFragment[] = [];
   for (const url of urls) {
     try {
-      const loaded = await ctx.runtime.media.loadWebMedia(url, {
-        maxBytes,
-        ...(ctx.mediaLocalRoots && ctx.mediaLocalRoots.length > 0
-          ? { localRoots: ctx.mediaLocalRoots }
-          : {}),
-      });
+      const loaded = await ctx.runtime.media.loadWebMedia(
+        url,
+        buildOutboundMediaLoadOptions({
+          maxBytes,
+          ...(ctx.mediaAccess ? { mediaAccess: ctx.mediaAccess } : {}),
+          ...(ctx.mediaLocalRoots ? { mediaLocalRoots: ctx.mediaLocalRoots } : {}),
+          ...(ctx.mediaReadFile ? { mediaReadFile: ctx.mediaReadFile } : {}),
+        }),
+      );
       const uploaded = await ctx.apiClient.uploadMedia({
         buffer: loaded.buffer,
         filename: loaded.fileName ?? "upload.bin",

package/src/outbound.test.ts

@@ -92,7 +92,7 @@ describe("openclaw-clawchat outbound", () => {
       chat_id: "chat-1",
       replyTo: {
         msgId: "m-orig",
-        senderId: "chat-1",
+        senderId: "user-2",
         nickName: "Sender",
         fragments: [{ kind: "text", text: "original" }],
       },

package/src/outbound.ts

@@ -64,6 +64,8 @@ export interface SendResult {
  *   - `clawchat:group:{chat_id}`      → group
  *   - `openclaw-clawchat:direct:{chat_id}` → direct
  *   - `openclaw-clawchat:group:{chat_id}`  → group
+ *   - `direct:{chat_id}`              → direct (host-normalized)
+ *   - `group:{chat_id}`               → group (host-normalized)
  *   - bare `{chat_id}`                → direct (backward compat)
  */
 export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
@@ -75,6 +77,11 @@ export function parseOpenclawRecipient(to: string): { chatId: string; chatType:
 
   const scheme = raw.slice(0, firstColon).toLowerCase();
   const rest = raw.slice(firstColon + 1);
+  if (scheme === "direct" || scheme === "group") {
+    const chatId = rest.trim();
+    if (!chatId) throw new Error(`openclaw-clawchat: missing chat_id in "${to}"`);
+    return { chatId, chatType: scheme };
+  }
   if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
     return { chatId: raw, chatType: "direct" };
   }
@@ -127,7 +134,7 @@ export async function sendOpenclawClawlingText(params: SendParams): Promise<Send
       mode: "normal",
       replyTo: {
         msgId: params.replyCtx.replyToMessageId,
-        senderId: params.replyCtx.replyPreviewChatId ?? params.replyCtx.replyPreviewSenderId,
+        senderId: params.replyCtx.replyPreviewSenderId,
         nickName: params.replyCtx.replyPreviewNickName,
         fragments: [{ kind: "text", text: params.replyCtx.replyPreviewText }],
       },
@@ -217,7 +224,7 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
         messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
       };
     },
-    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaAccess, mediaLocalRoots, mediaReadFile }) => {
       const account = resolveOpenclawClawlingAccount(cfg);
       const client =
         getOpenclawClawlingClient(account.accountId) ??
@@ -234,7 +241,9 @@ export const openclawClawlingOutbound: ChannelOutboundAdapter = {
       const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
         apiClient,
         runtime,
+        ...(mediaAccess ? { mediaAccess } : {}),
         ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+        ...(mediaReadFile ? { mediaReadFile } : {}),
       });
       if (mediaFragments.length === 0) {
         throw new Error(`openclaw-clawchat failed to upload media: ${mediaUrl}`);

package/src/reply-dispatcher.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it, vi } from "vitest";
 import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
 
 describe("openclaw-clawchat reply-dispatcher", () => {
-  it("uses chat_id, not sender_id, as the consolidated streaming reply marker", async () => {
+  it("uses the inbound sender id in consolidated streaming reply previews", async () => {
     let hooks:
       | {
           deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
@@ -70,7 +70,7 @@ describe("openclaw-clawchat reply-dispatcher", () => {
         context: {
           reply: {
             reply_preview: {
-              id: "chat-1",
+              id: "user-1",
               nick_name: "User 1",
             },
           },
@@ -489,6 +489,104 @@ describe("openclaw-clawchat reply-dispatcher", () => {
     );
   });
 
+  it("prefers mediaUrls over legacy mediaUrl so one image is not sent twice", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: {
+            text?: string;
+            mediaUrl?: string;
+            mediaUrls?: string[];
+          }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+        }
+      | undefined;
+    const loadWebMedia = vi.fn(async (url: string) => ({
+      buffer: Buffer.from(`bytes:${url}`),
+      contentType: "image/png",
+      fileName: "image.png",
+    }));
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          code: 0,
+          msg: "ok",
+          data: { url: "https://cdn/uploaded.png", size: 12, mime: "image/png" },
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+    const client = {
+      sendMessage: vi.fn().mockResolvedValue({
+        payload: { message_id: "server-m1", accepted_at: 1234 },
+        trace_id: "trace-media",
+      }),
+      replyMessage: vi.fn(),
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    try {
+      createOpenclawClawlingReplyDispatcher({
+        cfg: {} as never,
+        runtime: {
+          media: { loadWebMedia },
+          channel: {
+            reply: {
+              resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+              createReplyDispatcherWithTyping: vi.fn((options) => {
+                hooks = options;
+                return { dispatcher: {}, replyOptions: {}, markDispatchIdle: vi.fn() };
+              }),
+            },
+          },
+        } as never,
+        account: {
+          accountId: "default",
+          baseUrl: "https://api.example.com",
+          token: "tk",
+          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() },
+      });
+
+      await hooks?.deliver?.(
+        {
+          text: "look",
+          mediaUrl: "https://cdn/legacy.png",
+          mediaUrls: ["https://cdn/image.png"],
+        },
+        { kind: "final" },
+      );
+
+      expect(loadWebMedia).toHaveBeenCalledTimes(1);
+      expect(loadWebMedia).toHaveBeenCalledWith("https://cdn/image.png", expect.any(Object));
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(client.sendMessage).toHaveBeenCalledWith(
+        expect.objectContaining({
+          chat_id: "chat-1",
+          body: {
+            fragments: [
+              { kind: "text", text: "look" },
+              {
+                kind: "image",
+                url: "https://cdn/uploaded.png",
+                mime: "image/png",
+                size: 12,
+                name: "image.png",
+              },
+            ],
+          },
+        }),
+      );
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
   it("includes rich interaction fragments in the consolidated streaming final reply", async () => {
     let hooks:
       | {

package/src/reply-dispatcher.ts

@@ -8,6 +8,7 @@ import {
 } from "openclaw/plugin-sdk/interactive-runtime";
 import type { PluginRuntime } from "openclaw/plugin-sdk/core";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import { resolveOutboundMediaUrls } from "openclaw/plugin-sdk/reply-payload";
 import type { ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
 import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import {
@@ -363,7 +364,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       routing,
       replyTo: {
         msgId: inboundMessageId ?? streamingMessageId,
-        previewId: inboundForFinalReply?.chatId ?? target.chatId,
+        previewId: inboundForFinalReply?.senderId ?? target.chatId,
         nickName:
           inboundForFinalReply?.senderNickName ?? inboundForFinalReply?.senderId ?? target.chatId,
         fragments: inboundForFinalReply?.bodyText
@@ -379,10 +380,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       finalRichFragments.push(richFragment);
     }
     if (text) streamText = mergeStreamingText(streamText, text);
-    const urls = [
-      ...(payload.mediaUrl ? [payload.mediaUrl] : []),
-      ...(payload.mediaUrls ?? []),
-    ].filter((u): u is string => Boolean(u));
+    const urls = resolveOutboundMediaUrls(payload).filter(Boolean);
     for (const url of urls) {
       if (!accumulatedMediaUrls.includes(url)) accumulatedMediaUrls.push(url);
     }
@@ -422,10 +420,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     deliver: async (payload: ReplyPayload, info?: { kind: "tool" | "block" | "final" }) => {
       const richFragment = buildRichInteractionFragment(payload);
       const text = richFragment && account.richInteractions ? "" : resolvePayloadText(payload);
-      const urls = [
-        ...(payload.mediaUrl ? [payload.mediaUrl] : []),
-        ...(payload.mediaUrls ?? []),
-      ].filter((u): u is string => Boolean(u));
+      const urls = resolveOutboundMediaUrls(payload).filter(Boolean);
       log?.info?.(
         `[${account.accountId}] openclaw-clawchat deliver kind=${info?.kind ?? "unknown"} text_len=${text.length} media_urls=${urls.length} reasoning=${payload.isReasoning === true}`,
       );

package/src/runtime.test.ts

@@ -205,6 +205,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
     expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
     expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
     expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:chat-1");
     expect(capturedCtx?.ConversationLabel).toBe("chat-1");
     expect(capturedCtx?.SenderId).toBe("user-1");
     expect(resolveAgentRoute).toHaveBeenCalledWith(
@@ -359,6 +360,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
     await startPromise;
 
     expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:group:grp-1");
     expect(capturedCtx?.ConversationLabel).toBe("group:grp-1");
     expect(capturedCtx?.SenderId).toBe("user-1");
     expect(capturedCtx?.ChatType).toBe("group");

package/src/runtime.ts

@@ -200,16 +200,16 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           timestamp: turn.timestamp,
           ...rt.reply.resolveEnvelopeFormatOptions(cfg),
         });
+        const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
         const ctxPayload = rt.reply.finalizeInboundContext({
           Body: body,
           BodyForAgent: turn.rawBody,
           RawBody: turn.rawBody,
           CommandBody: turn.rawBody,
-          // Clawling v2 routes by chat_id. `senderId` is still preserved as
-          // structured metadata, but the conversation target must be based on
-          // `peer.id` so follow-up sends address the active chat, not merely
-          // the human sender identity.
-          From: `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`,
+          // Clawling v2 routes by chat_id. `OriginatingTo` is what the
+          // message tool uses as the implicit current-chat target, so keep it
+          // on the conversation id rather than the agent account user id.
+          From: conversationTarget,
           To: `${CHANNEL_ID}:${account.userId}`,
           SessionKey: route.sessionKey,
           AccountId: route.accountId ?? accountId,
@@ -222,7 +222,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           MessageSidFull: turn.messageId,
           Timestamp: turn.timestamp,
           OriginatingChannel: CHANNEL_ID,
-          OriginatingTo: `${CHANNEL_ID}:${account.userId}`,
+          OriginatingTo: conversationTarget,
         });
         // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
         const inboundPaths =

package/src/scripts.test.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const root = new URL("../", import.meta.url);
+
+function readRootFile(name: string): string {
+  return fs.readFileSync(new URL(name, root), "utf8");
+}
+
+describe("OpenClaw packaging scripts", () => {
+  it("packages the npm tarball and uploads it to the R2 openclaw prefix", () => {
+    const script = readRootFile("package_openclaw_plugin.sh");
+
+    expect(script).toMatch(/npm pack --silent/);
+    expect(script).toContain('R2_ENV_FILE="${R2_ENV_FILE:-.env.r2}"');
+    expect(script).toContain('set -a; source "$R2_ENV_FILE"; set +a');
+    expect(script).toContain(': "${AWS_ACCESS_KEY_ID:?missing in $R2_ENV_FILE}"');
+    expect(script).toContain(': "${AWS_SECRET_ACCESS_KEY:?missing in $R2_ENV_FILE}"');
+    expect(script).toContain(': "${R2_ENDPOINT:?missing in $R2_ENV_FILE}"');
+    expect(script).toContain(': "${R2_BUCKET:?missing in $R2_ENV_FILE}"');
+    expect(script).not.toContain("f8eeaffb6f81ffd82b59c24d4ff797c9");
+    expect(script).not.toContain("587f8d4aa485a70f6e984a9efa7e609a86e4ef02d56a6682d9d7a9509913b8cb");
+    expect(script).toContain("OBJECT_KEY=\"openclaw/${TARGET_NAME}\"");
+    expect(script).toContain("https://dddddddddddddtest.clawling.chat/${OBJECT_KEY}");
+    expect(script).toMatch(/aws s3 cp[\s\S]*--content-type application\/gzip/);
+  });
+
+  it("keeps the local R2 env file out of git", () => {
+    const gitignore = readRootFile(".gitignore");
+
+    expect(gitignore).toMatch(/^\.env\.r2$/m);
+  });
+
+  it("downloads the R2 tarball and installs it through openclaw", () => {
+    const script = readRootFile("install_openclaw.sh");
+
+    expect(script).toContain("PUBLIC_BASE_URL=\"https://dddddddddddddtest.clawling.chat\"");
+    expect(script).toContain("CLAWCHAT_PLUGIN_URL=\"${1:-${PUBLIC_BASE_URL}/openclaw/${DEFAULT_TGZ}}\"");
+    expect(script).toContain("curl -fL \"$CLAWCHAT_PLUGIN_URL\" -o \"$CLAWCHAT_PLUGIN_TGZ\"");
+    expect(script).toContain("openclaw plugins install \"$CLAWCHAT_PLUGIN_TGZ\" --force");
+  });
+});